repo-to-md

A command-line tool to generate a single Markdown file that concatenates the structure and content of a specified directory. Useful for providing context to Large Language Models (LLMs) or creating simple project documentation.

Features

• Recursively scans a directory.
• Outputs a tree-like structure of the directory (using relative paths).
• Includes the content of text files, formatted with line numbers.
• Automatically detects and skips likely binary files.
• Allows ignoring specific directories, files, and extensions via command-line options.
• Provides sensible default ignores for common development artifacts (e.g., .git, node_modules, .pyc).
• Output can be directed to stdout (default), a file (-o), or the system clipboard (-c).
• Uses typer for a user-friendly command-line interface.

How to Use

1. Install Dependencies:

   uv sync

2. Make Executable (Optional):

   chmod +x repo_to_md.py

3. Run: (Examples assume it's executable, otherwise use python repo_to_md.py ...)

   • Basic Usage (Output to stdout, current directory):

     ./repo_to_md.py .

     or

     uvx repo_to_md.py .

   • Specify Directory:

     ./repo_to_md.py /path/to/your/project

     or

     uvx repo_to_md.py /path/to/your/project

   • Output to File:

     ./repo_to_md.py . --output project_docs.md
     # or short form:
     ./repo_to_md.py . -o project_docs.md

     or

     uvx repo_to_md.py . -o project_docs.md

   • Output to Clipboard:

     ./repo_to_md.py . --clipboard
     # or short form:
     ./repo_to_md.py . -c

     or

     uvx repo_to_md.py . -c

   • Ignore Specific Directories: (Uses default ignores + adds logs and temp)

     ./repo_to_md.py . --ignore-dir logs --ignore-dir temp

     or

     uvx repo_to_md.py . --ignore-dir logs --ignore-dir temp

   • Ignore Specific Files: (Uses default ignores + adds .env and config.json)

     ./repo_to_md.py . --ignore-file .env --ignore-file config.json

     or

     uvx repo_to_md.py . --ignore-file .env --ignore-file config.json

   • Ignore Specific Extensions: (Uses default ignores + adds .log and .tmp)

     ./repo_to_md.py . --ignore-ext log --ignore-ext .tmp # Handles leading dot or not

     or

     uvx repo_to_md.py . --ignore-ext log --ignore-ext .tmp # Handles leading dot or not

   • Combining Ignores:

     ./repo_to_md.py . -o out.md --ignore-dir build --ignore-file secrets.txt --ignore-ext bak

     or

     uvx repo_to_md.py . -o out.md --ignore-dir build --ignore-file secrets.txt --ignore-ext bak

   • Get Help:

     ./repo_to_md.py --help

     or

     uvx repo_to_md.py --help

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines.