repo-to-md

Turn any repointo a single Markdown file with directory tree and file contents.

# Print entire repo from GitHub into stdout as a Markdown file
$ repo-to-md octocat/Hello-World

# Print current directory as Markdown (source parameter is optional)
$ repo-to-md

Result:

Project and branch: octocat/Hello-World

Directory structure:
.
├── README.md
├── src
│   └── main.py
├── tests
│   └── test_main.py
└── .gitignore

```python  # src/main.py
print("Hello, world!")
```

```python  # tests/test_main.py
assert main.hello() == "Hello, world!"
```

```python  # .gitignore
*.pyc
```

Features

• Remote or local:
  • Short GitHub repo: owner/repo
  • Full GitHub URL: https://github.com/owner/repo
  • SSH URL: git@github.com:owner/repo.git
  • Local path: /local/path/repo
• Specify files:
  • Include (-i) any number of paths or globs like src/, tests/*, README.md.
  • Exclude with (-e).
  • Patterns with ./ prefix are automatically normalized (e.g., ./src/ becomes src/).
• Choose branch:
  • Default: main
  • Specify with --branch or -b.
• Skips binary blobs, media, archives, and dozens of lock files automatically.
• Excludes .git and understands .gitignore automatically.

Installation

The project is distributed on PyPI, so any modern Python installer will work.
If you already use the excellent uv tool, a single command is enough:

To run repo-to-md one time, without installing it, use uvx:

# Run one time using uvx
uvx repo-to-md github/repo > repo.md

Or install it globally:

# Install
uv tool install repo-to-md
# Run it
repo-to-md github/repo > repo.md

Of course, you can also use pip if you prefer.

# Install
pip install repo-to-md
# Run it
repo-to-md github/repo > repo.md

Supported platforms

• macOS, Linux, Windows
• Python ≥ 3.10 (see badge above)

Usage

Entire GitHub repo into a single hello-world.md file.

repo-to-md octocat/Hello-World > hello-world.md

Local repo but only files inside the src/ folder.

repo-to-md ~/Projects/myapp -i src/ > myapp_src.md

Print contents of just the pyproject.toml file alone:

repo-to-md . -i pyproject.toml

Current directory with patterns (source parameter is optional):

# These are equivalent
repo-to-md -i src/ -e "*.lock"
repo-to-md . -i src/ -e "*.lock"
repo-to-md . -i ./src/ -e "*.lock"  # ./ prefix is automatically stripped

The first positional argument is either a GitHub repo or a local path (defaults to current directory).
Selectively include or exclude files/directories with -i/--include and -e/--exclude.

Copy to clipboard

• macOS: repo-to-md . | pbcopy (paste with ⌘V)
• Linux / X11: repo-to-md . | xclip -selection clipboard
• Windows / PowerShell: repo-to-md . | clip

Replace . with any path or GitHub repo, and feel free to include src/ or similar after it.

With Claude Code

Best way to use it inside Claude Code is to ask it to dump the repo into a Markdown file and then work with that file.

Bash(repo-to-md github/repo > repo.md)

Alternatively, you can just output the entire repo into current context:

Bash(repo-to-md github/repo)

You can even invoke it without Bash and Claude will understand you.

repo-to-md github/repo

Custom Claude Code Slash Command

For even better integration, you can add a custom slash command to your Claude Code setup. Copy the fetch-repo.md file from this repository to your .claude/commands/ directory:

# Copy the slash command file
cp fetch-repo.md ~/.claude/commands/

# Or for project-specific commands
cp fetch-repo.md .claude/commands/

Then use it in Claude Code:

/fetch-repo owner/repo
/fetch-repo owner/repo --branch develop
/fetch-repo owner/repo --include "src/" --exclude "*.lock"
/fetch-repo /path/to/local/repo --output analysis.md

This command provides a streamlined way to fetch and analyze repository contents with proper context and follow-up suggestions.

CLAUDE.md Instructions

To make Claude Code automatically use repo-to-md for repository analysis instead of built-in tools, add this instruction to your project's CLAUDE.md file:

# Repository Analysis Instructions

When I ask you to analyze, examine, or understand how a specific repository implements a feature or pattern, use the `repo-to-md` command instead of web search or file system tools like `ls` and `grep`.

## Usage Examples:
- "How does facebook/react implement hooks?" → Use: `repo-to-md facebook/react --include "packages/react/src/ReactHooks*"`
- "Show me how tailwindcss handles configuration" → Use: `repo-to-md tailwindlabs/tailwindcss --include "src/config*"`
- "Analyze the testing setup in this repo" → Use: `repo-to-md owner/repo --include "test*" --include "*.test.*"`

## Output Options:
1. **For reference/analysis**: Output directly to context using `repo-to-md owner/repo [options]`
2. **For extensive analysis**: Save to file using `repo-to-md owner/repo [options] --output analysis.md`

Use the most specific include/exclude patterns possible to focus on relevant code sections and avoid overwhelming the context with unnecessary files.

This instruction helps Claude Code understand when and how to use repo-to-md for repository analysis tasks, making it more efficient than generic web searches or file system exploration.

Contributing & License

Issues and pull requests are welcome. Licensed under the Apache-2.0.