๐Ÿ“‚ Generate Repo File List

April 16, 2026 ยท View on GitHub

๐Ÿ“‚ Generate Repo File List

๐Ÿš€ Automatically create beautiful, organized file indexes for your GitHub repositories

GitHub release Tests Python License: Unlicense


Transform your repository structure into beautifully formatted HTML or Markdown file listings with custom colors, lazy loading, and automatic README updates.

๐ŸŽฏ Features โ€ข ๐Ÿš€ Quick Start โ€ข โš™๏ธ Configuration โ€ข ๐Ÿ“– Examples โ€ข ๐Ÿ”„ Versioning


โœจ Features

  • ๐ŸŽจ Colorful Output - Generate file lists with vibrant, customizable color schemes
  • ๐Ÿ“ฑ Responsive Design - Lazy loading optimized for mobile, tablet, and desktop viewports
  • ๐Ÿ”„ Auto README Updates - Seamlessly inject file lists into your README using markers
  • ๐ŸŽฏ Smart Categorization - Organize files by extension (Python, YAML, JavaScript, etc.)
  • ๐Ÿšซ Gitignore Integration - Respect .gitignore rules for clean file discovery
  • ๐Ÿ“Š Dual Format Support - Generate both HTML and Markdown outputs
  • โšก Performance Optimized - Chunk-based rendering for large repositories
  • ๐Ÿ”’ Secure - Hardened runner and comprehensive security best practices

๐Ÿš€ Quick Start

๐Ÿ“‹ Prerequisites

Add these markers to your README.md where you want the file list to appear:

<!-- FILE_LIST_START -->
<!-- FILE_LIST_END -->

๐ŸŽฌ Basic Workflow Setup

Create .github/workflows/file-list.yml in your repository:

name: ๐Ÿ“‚ Generate File List

on:
 push:
  branches: [main]
 workflow_dispatch:

permissions:
 contents: write

jobs:
 generate-file-list:
  runs-on: ubuntu-latest

  steps:
   - name: ๐Ÿ“ฅ Checkout repository
     uses: actions/checkout@v4

   - name: ๐Ÿ Set up Python
     uses: actions/setup-python@v5
     with:
      python-version: "3.x"

   - name: ๐Ÿ“‚ Generate File List
     uses: nick2bad4u/generate-repo-file-list@v1
     with:
      directory: "."
      output-format: "markdown"
      output-file: "file_list.md"
      respect-gitignore: "true"

   - name: ๐Ÿ’พ Commit Changes
     uses: stefanzweifel/git-auto-commit-action@v5
     with:
      commit_message: "๐Ÿ“‚ Update file list automatically"

๐Ÿ’ก Tip: Remove the cron schedule if you only want manual/push-triggered runs.


๐Ÿ“– Advanced Workflow Example

๐Ÿ”ง Click to see full-featured workflow with all options
name: Generate and Update README.MD File List

on:
 push:
  branches:
   - main
 pull_request:
  branches:
   - main
 workflow_dispatch: # Allows manual triggering

permissions:
 contents: write
 pull-requests: write

jobs:
 build:
  runs-on: ubuntu-latest

  steps:
   - name: Checkout repository
     uses: actions/checkout@v4

   - name: List files in the repository
     run: |
      ls -al

   - name: Verify README.md exists
     run: |
      if [ ! -f README.md ]; then
        echo "README.md not found!"
        exit 1
      fi

   - name: Set up Python
     uses: actions/setup-python@v5
     with:
      python-version: "3.x"

   - name: Create src directory
     run: mkdir -p src

   - name: Download generate_file_list.py
     run: |
      curl -L -o src/generate_file_list.py https://github.com/Nick2bad4u/generate-repo-file-list/raw/refs/heads/main/src/generate_file_list.py
      chmod +x src/generate_file_list.py

   - name: Install dependencies (if any)
     run: |
      python -m pip install tqdm==4.66.4
      # Add any dependencies your script needs here
      # For example: pip install requests

   - name: Run Generate Repo File List Action
     uses: nick2bad4u/generate-repo-file-list@main
     with:
      log-level: "INFO"
      directory: "."
      repo-url: "https://github.com/${{ github.repository }}"
      fallback-repo-url: "https://github.com/${{ github.repository }}"
      output-format: "html"
      output-file: "file_list.html"
      color-source: "random"
      color-list: "#FF0000 #00FF00 #0000FF #FFFF00 #FF00FF #00FFFF"
      color-range-start: "#000000"
      color-range-end: "#FFFFFF"
      file-categories: ""
      overwrite-file-categories: "false"
      ignore-list: ""
      overwrite-ignore-list: "false"
      max-attempts: "1000000"
      exclude-blacks-threshold: "#222222"
      exclude-dark-colors: "false"
      exclude-bright-colors: "false"
      exclude-blacks: "false"
      ensure-readable-colors: "false"
      repo-root-header: "Repo Root"
      header-text: "## File List"
      intro-text: "# Here is a list of files included in this repository:"
      dark-color-luminance-threshold: "128"
      bright-color-luminance-threshold: "200"
      chunk-size: "40"
      viewport-mobile: "768"
      viewport-tablet: "1024"
      viewport-small-desktop: "1440"
      root-margin-large-desktop: "0px 0px 400px 0px"
      root-margin-small-desktop: "0px 0px 300px 0px"
      root-margin-tablet: "0px 0px 200px 0px"
      root-margin-mobile: "0px 0px 100px 0px"
      respect-gitignore: "true"
      default-branch: "${{ github.event.repository.default_branch }}"
      link-ref: "${{ github.sha }}"
      gtm-id: "GTM-T8J6HPLF"
      output-file-stdout: "false"

   - name: Update README.md
     uses: actions/github-script@v7
     with:
      script: |
       const fs = require('fs');
            const readmePath = './README.md';
            let fileListPath = './file_list.md';
            const fileListHTMLPath = './file_list.html';

            // Determine which file to use based on which is newer
            if (fs.existsSync(fileListPath) && fs.existsSync(fileListHTMLPath)) {
         const fileListStat = fs.statSync(fileListPath);
         const fileListHTMLStat = fs.statSync(fileListHTMLPath);

         if (fileListHTMLStat.mtime > fileListStat.mtime) {
           fileListPath = fileListHTMLPath;
           console.log('Using file_list.html because it is newer than file_list.md');
         } else {
           console.log('Using file_list.md because it is newer than file_list.html');
         }
            } else if (fs.existsSync(fileListHTMLPath)) {
         fileListPath = fileListHTMLPath;
         console.log('Using file_list.html because file_list.md does not exist');
            } else if (!fs.existsSync(fileListPath)) {
         console.warn('Neither file_list.md nor file_list.html exist.  Aborting README.md update.');
         return;
            }

       try {
         // Check if README.md exists, if not create it
         if (!fs.existsSync(readmePath)) {
         console.warn('README.md not found. Creating a new README.md file.');
         fs.writeFileSync(readmePath, '# Project Title\n\n<!-- FILE_LIST_START -->\n<!-- FILE_LIST_END -->\n');
         }

         // Read the contents of README.md
         let readmeContent = fs.readFileSync(readmePath, 'utf8');

         // Read the contents of file_list.md
         const fileListContent = fs.readFileSync(fileListPath, 'utf8');

         // Define start and end markers for the file list section
         const startMarker = '<!-- FILE_LIST_START -->';
         const endMarker = '<!-- FILE_LIST_END -->';

         // Find the start and end positions of the file list section
         const startPosition = readmeContent.indexOf(startMarker);
         const endPosition = readmeContent.indexOf(endMarker);

         // Check if the markers exist in the README.md file
         if (startPosition === -1 || endPosition === -1) {
           console.warn('Start or end markers not found in README.md.  The action will add the markers with the file list to the end of the file.');
           readmeContent += `\n${startMarker}\n${fileListContent}\n${endMarker}\n`;
         } else {
           // Replace the existing file list with the new content
           readmeContent = readmeContent.substring(0, startPosition + startMarker.length) +
             '\n' + fileListContent + '\n' +
             readmeContent.substring(endPosition);
         }

         // Write the updated content back to README.md
         fs.writeFileSync(readmePath, readmeContent);
         console.log('Successfully updated README.md');
       } catch (error) {
         console.error('Failed to update README.md:', error);
       }

   - name: Commit and push changes
     uses: stefanzweifel/git-auto-commit-action@v5
     with:
      commit_message: "Update file list in README.md automatically with GitHub Action"
      file_pattern: "README.md"
      commit_user_name: "{{ github.actor }}"
      commit_user_email: "{{ github.actor }}@users.noreply.github.com"
      commit_author: "{{ github.actor }} <{{ github.actor }}@users.noreply.github.com>"

โš™๏ธ Configuration


โš™๏ธ Configuration

๐ŸŽ›๏ธ Input Parameters

๐Ÿ”ง Essential Inputs
ParameterDescriptionDefaultOptions
directoryRoot directory to scan.Any valid path
output-formatFile formatmarkdownmarkdown, html
output-fileOutput filenamefile_list.mdAny filename
repo-urlRepository URLAuto-detectedGitHub URL
respect-gitignoreHonor .gitignorefalsetrue, false
๐ŸŽจ Color & Styling Inputs
ParameterDescriptionDefault
color-sourceColor generation methodrandom
color-listCustom color palette#FF0000 #00FF00 #0000FF
color-range-startMin color for random#000000
color-range-endMax color for random#FFFFFF
exclude-dark-colorsSkip dark colorsfalse
exclude-bright-colorsSkip bright colorsfalse
ensure-readable-colorsMaintain contrast ratiofalse
๐Ÿ“ฑ Responsive & Performance Inputs
ParameterDescriptionDefault
chunk-sizeLines per lazy-load chunk40
viewport-mobileMobile breakpoint (px)768
viewport-tabletTablet breakpoint (px)1024
viewport-small-desktopDesktop breakpoint (px)1440
root-margin-mobileMobile intersection margin0px 0px 100px 0px
root-margin-tabletTablet intersection margin0px 0px 200px 0px
๐Ÿ“‚ File Organization Inputs
ParameterDescriptionDefault
file-categoriesCustom ext/name pairs
overwrite-file-categoriesReplace default categoriesfalse
ignore-listAdditional ignore patterns
overwrite-ignore-listReplace default ignoresfalse
repo-root-headerRoot folder headerRepo Root
header-textMain file list header## File List
intro-textIntro paragraph# Here is a list...
๐Ÿ”— Version Control Inputs
ParameterDescriptionDefault
link-refGit ref for file linksCurrent branch
default-branchFallback branchmain
gtm-idGoogle Tag Manager container in HTML outputGTM-T8J6HPLF
output-file-stdoutPrint to stdoutfalse
log-levelLogging verbosityINFO

๐Ÿ“– Examples

๐ŸŽจ HTML Output with Custom Colors

- uses: nick2bad4u/generate-repo-file-list@v1
  with:
   output-format: "html"
   output-file: "file_list.html"
   color-source: "list"
   color-list: "#FF6B6B #4ECDC4 #45B7D1 #FFA07A #98D8C8"
   chunk-size: "50"

๐Ÿ“ Markdown with Gitignore Respect

- uses: nick2bad4u/generate-repo-file-list@v1
  with:
   output-format: "markdown"
   respect-gitignore: "true"
   ignore-list: "build dist .venv"

๐Ÿท๏ธ Custom File Categories

- uses: nick2bad4u/generate-repo-file-list@v1
  with:
   file-categories: ".tsx TypeScript .vue Vue .rs Rust"
   overwrite-file-categories: "false"

๐Ÿงช Running Tests

# Install dependencies
pip install -r requirements.txt

# Run test suite
pytest
# Linux/macOS
pip install -r requirements.txt && pytest

๐Ÿ”„ Versioning and Releases

This action uses automated semantic versioning ๐Ÿค–. Every push to main triggers intelligent version detection:

๐Ÿ“ˆ Version Bump Rules

Commit PatternBump TypeExample
BREAKING CHANGE or !:๐Ÿ”ด Majorv1.0.0 โ†’ v2.0.0
feat: or feature:๐ŸŸก Minorv1.0.0 โ†’ v1.1.0
All others๐ŸŸข Patchv1.0.0 โ†’ v1.0.1

Option 1: Auto-update with latest compatible version (recommended)

- uses: nick2bad4u/generate-repo-file-list@v1

Option 2: Pin to specific version for maximum stability

- uses: nick2bad4u/generate-repo-file-list@v1.2.3

๐Ÿ’ฌ Commit Message Examples

# ๐ŸŸข Patch: v1.0.0 โ†’ v1.0.1
git commit -m "fix: correct Windows path handling"

# ๐ŸŸก Minor: v1.0.0 โ†’ v1.1.0
git commit -m "feat: add lazy loading for large repos"

# ๐Ÿ”ด Major: v1.0.0 โ†’ v2.0.0
git commit -m "feat!: restructure input parameters

BREAKING CHANGE: renamed 'file-list' to 'output-file'"

๐Ÿ“š Learn More: See VERSIONING.md for complete release documentation.


๐Ÿ“Š Output Examples

๐ŸŽญ Markdown Format Preview

## File List

### Repo Root

- [.gitignore](https://github.com/user/repo/blob/main/.gitignore)
- [README.md](https://github.com/user/repo/blob/main/README.md)
- [requirements.txt](https://github.com/user/repo/blob/main/requirements.txt)

### Python

- [src/app.py](https://github.com/user/repo/blob/main/src/app.py)
- [tests/test_app.py](https://github.com/user/repo/blob/main/tests/test_app.py)

๐ŸŒˆ HTML Format Preview

The HTML output includes:

  • โœจ Vibrant color-coded file links
  • ๐Ÿ“ฑ Responsive lazy loading
  • ๐ŸŽฏ Organized categorization
  • โšก Performance-optimized rendering

๐ŸŒ Live Demo: Visit our GitHub Pages to see HTML output in action!


๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. ๐Ÿด Fork the repository
  2. ๐ŸŒฟ Create your feature branch (git checkout -b feature/AmazingFeature)
  3. โœ… Commit your changes (git commit -m 'feat: add some amazing feature')
  4. ๐Ÿ“ค Push to the branch (git push origin feature/AmazingFeature)
  5. ๐ŸŽ‰ Open a Pull Request

๐Ÿ“„ License

This is free and unencumbered software released into the public domain under The Unlicense.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

For more information, see https://unlicense.org.


๐Ÿ™ Acknowledgments

  • Built with โค๏ธ using Python and GitHub Actions
  • Inspired by the need for better repository documentation
  • Thanks to all contributors and users!

โญ If you find this useful, please star the repository!

Made with ๐Ÿ’™ by Nick2bad4u

Report Bug โ€ข Request Feature โ€ข View Releases


File List

Here is a list of files included in this repository:

Repo Root

JavaScript

YAML

src

tests


๐Ÿ“‹ Example Output

Markdown Format

The Markdown output generates clean, standard Markdown links organized by category:

## File List

# Here is a list of files included in this repository:

### Repo Root

- [.gitignore](https://github.com/your-org/your-repo/blob/main/.gitignore)
- [README.md](https://github.com/your-org/your-repo/blob/main/README.md)
- [package.json](https://github.com/your-org/your-repo/blob/main/package.json)

### JavaScript

- [index.js](https://github.com/your-org/your-repo/blob/main/index.js)
- [utils.js](https://github.com/your-org/your-repo/blob/main/utils.js)

### Python

- [src/main.py](https://github.com/your-org/your-repo/blob/main/src/main.py)
- [tests/test_main.py](https://github.com/your-org/your-repo/blob/main/tests/test_main.py)

HTML Format

The HTML output includes vibrant colors, lazy loading for performance, and responsive design:

<h1>## File List</h1>
<p># Here is a list of files included in this repository:</p>

<div
 class="lazyload-placeholder"
 data-content="file-list-1"
 style="min-height: 400px;"
></div>

<script>
 // Lazy loading script with viewport-aware configuration
 // Chunks load progressively as user scrolls
 // Colors randomly generated for visual distinction
</script>

Live HTML Preview: View the actual generated HTML with colors and lazy loading at GitHub Pages

Note: GitHub's Markdown renderer doesn't display inline HTML styles. For the full colorful experience, view the HTML file directly or through GitHub Pages.