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
- Short GitHub repo:
- Specify files:
- Include (
-i) any number of paths or globs likesrc/,tests/*,README.md. - Exclude with (
-e). - Patterns with
./prefix are automatically normalized (e.g.,./src/becomessrc/).
- Include (
- Choose branch:
- Default:
main - Specify with
--branchor-b.
- Default:
- Skips binary blobs, media, archives, and dozens of lock files automatically.
- Excludes
.gitand understands.gitignoreautomatically.
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.
Metadata
Release files for repo-to-md 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| repo_to_md-0.1.1.tar.gz | 14.4 kB | Without provenance | Details for repo_to_md-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| repo_to_md-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for repo_to_md-0.1.1-py3-none-any.whl |
Total release size: 28.1 kB
Release files / repo_to_md-0.1.1.tar.gz
| Download URL | repo_to_md-0.1.1.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a03a7f6efa995a3a0f60c28a41eae0ffec5d56efa2ca177b7ddc4ab3d4547f0
|
|
BLAKE2b-256 checksum How to use checksums |
304a834cf03c1958f5c8851efeb71fa4c91aa39a9c0ac5cc6c26de8317c61418
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.16
|
Release files / repo_to_md-0.1.1-py3-none-any.whl
| Download URL | repo_to_md-0.1.1-py3-none-any.whl |
|---|---|
| Size | 13.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a632e51e108456f2d8fbe3049bf565d6de7feda3af79b3935a51ba455712818
|
|
BLAKE2b-256 checksum How to use checksums |
0f808dd961daaae5993aa92ff66c16e92e306a5f301a873fe70be7b52e35911b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.16
|
Security for repo-to-md 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.