# repo-to-md
<p>
<a href="https://pypi.org/project/repo-to-md/"><img src="https://img.shields.io/pypi/v/repo-to-md.svg" alt="PyPI version" /></a>
<a href="https://pypi.org/project/repo-to-md/"><img src="https://img.shields.io/pypi/pyversions/repo-to-md.svg" alt="Python versions" /></a>
</p>
Turn any repointo a single **Markdown** file with directory tree and file contents.
```shell
# 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:
<pre>
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
```
</pre>
## 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`](https://github.com/astral-sh/uv) tool, a
single command is enough:
To run `repo-to-md` one time, without installing it, use `uvx`:
```bash
# Run one time using uvx
uvx repo-to-md github/repo > repo.md
```
Or install it globally:
```bash
# 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.
```bash
# 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.
```bash
repo-to-md octocat/Hello-World > hello-world.md
```
Local repo but only files inside the `src/` folder.
```bash
repo-to-md ~/Projects/myapp -i src/ > myapp_src.md
```
Print contents of just the `pyproject.toml` file alone:
```bash
repo-to-md . -i pyproject.toml
```
Current directory with patterns (source parameter is optional):
```bash
# 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 ⌘<kbd>V</kbd>)*
* **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.
```shell
Bash(repo-to-md github/repo > repo.md)
```
Alternatively, you can just output the entire repo into current context:
```shell
Bash(repo-to-md github/repo)
```
You can even invoke it without `Bash` and Claude will understand you.
```shell
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:
```bash
# 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:
```markdown
# 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](https://spdx.org/licenses/Apache-2.0.html).
Raw data
{
"_id": null,
"home_page": null,
"name": "repo-to-md",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "vduseev <vagiz@duseev.com>",
"keywords": "ai, claude, context, fetch, git, llm, markdown, read, repo, repository, text",
"author": null,
"author_email": "vduseev <vagiz@duseev.com>",
"download_url": "https://files.pythonhosted.org/packages/30/4a/834cf03c1958f5c8851efeb71fa4c91aa39a9c0ac5cc6c26de8317c61418/repo_to_md-0.1.1.tar.gz",
"platform": null,
"description": "# repo-to-md\n\n<p>\n <a href=\"https://pypi.org/project/repo-to-md/\"><img src=\"https://img.shields.io/pypi/v/repo-to-md.svg\" alt=\"PyPI version\" /></a>\n <a href=\"https://pypi.org/project/repo-to-md/\"><img src=\"https://img.shields.io/pypi/pyversions/repo-to-md.svg\" alt=\"Python versions\" /></a>\n</p>\n\nTurn any repointo a single **Markdown** file with directory tree and file contents.\n\n```shell\n# Print entire repo from GitHub into stdout as a Markdown file\n$ repo-to-md octocat/Hello-World\n\n# Print current directory as Markdown (source parameter is optional)\n$ repo-to-md\n```\n\nResult:\n\n<pre>\nProject and branch: octocat/Hello-World\n\nDirectory structure:\n.\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 src\n\u2502 \u2514\u2500\u2500 main.py\n\u251c\u2500\u2500 tests\n\u2502 \u2514\u2500\u2500 test_main.py\n\u2514\u2500\u2500 .gitignore\n\n```python # src/main.py\nprint(\"Hello, world!\")\n```\n\n```python # tests/test_main.py\nassert main.hello() == \"Hello, world!\"\n```\n\n```python # .gitignore\n*.pyc\n```\n</pre>\n\n## Features\n\n* Remote or local:\n * Short GitHub repo: `owner/repo`\n * Full GitHub URL: `https://github.com/owner/repo`\n * SSH URL: `git@github.com:owner/repo.git`\n * Local path: `/local/path/repo`\n* Specify files:\n * Include (`-i`) any number of paths or globs like `src/`, `tests/*`, `README.md`.\n * Exclude with (`-e`).\n * Patterns with `./` prefix are automatically normalized (e.g., `./src/` becomes `src/`).\n* Choose branch:\n * Default: `main`\n * Specify with `--branch` or `-b`.\n* Skips binary blobs, media, archives, and dozens of lock files automatically.\n* Excludes `.git` and understands `.gitignore` automatically.\n\n## Installation\n\nThe project is distributed on PyPI, so any modern Python installer will work. \nIf you already use the excellent [`uv`](https://github.com/astral-sh/uv) tool, a\nsingle command is enough:\n\nTo run `repo-to-md` one time, without installing it, use `uvx`:\n\n```bash\n# Run one time using uvx\nuvx repo-to-md github/repo > repo.md\n```\n\nOr install it globally:\n\n```bash\n# Install\nuv tool install repo-to-md\n# Run it\nrepo-to-md github/repo > repo.md\n```\n\nOf course, you can also use `pip` if you prefer.\n\n```bash\n# Install\npip install repo-to-md\n# Run it\nrepo-to-md github/repo > repo.md\n```\n\n### Supported platforms\n\n* macOS, Linux, Windows\n* Python \u2265 3.10 (see badge above)\n\n## Usage\n\nEntire GitHub repo into a single `hello-world.md` file.\n\n```bash\nrepo-to-md octocat/Hello-World > hello-world.md\n```\n\nLocal repo but only files inside the `src/` folder.\n\n```bash\nrepo-to-md ~/Projects/myapp -i src/ > myapp_src.md\n```\n\nPrint contents of just the `pyproject.toml` file alone:\n\n```bash\nrepo-to-md . -i pyproject.toml\n```\n\nCurrent directory with patterns (source parameter is optional):\n\n```bash\n# These are equivalent\nrepo-to-md -i src/ -e \"*.lock\"\nrepo-to-md . -i src/ -e \"*.lock\"\nrepo-to-md . -i ./src/ -e \"*.lock\" # ./ prefix is automatically stripped\n```\n\nThe first positional argument is either a GitHub repo or a local path (defaults to current directory). \nSelectively include or exclude files/directories with `-i/--include` and `-e/--exclude`.\n\n## Copy to clipboard\n\n* **macOS**: `repo-to-md . | pbcopy` *(paste with \u2318<kbd>V</kbd>)*\n* **Linux / X11**: `repo-to-md . | xclip -selection clipboard`\n* **Windows / PowerShell**: `repo-to-md . | clip`\n\nReplace `.` with any path or GitHub repo, and feel free to include `src/` or similar after it.\n\n## With Claude Code\n\nBest way to use it inside Claude Code is to ask it to dump the repo into\na Markdown file and then work with that file.\n\n```shell\nBash(repo-to-md github/repo > repo.md)\n```\n\nAlternatively, you can just output the entire repo into current context:\n\n```shell\nBash(repo-to-md github/repo)\n```\n\nYou can even invoke it without `Bash` and Claude will understand you.\n\n```shell\nrepo-to-md github/repo\n```\n\n### Custom Claude Code Slash Command\n\nFor 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:\n\n```bash\n# Copy the slash command file\ncp fetch-repo.md ~/.claude/commands/\n\n# Or for project-specific commands\ncp fetch-repo.md .claude/commands/\n```\n\nThen use it in Claude Code:\n\n```\n/fetch-repo owner/repo\n/fetch-repo owner/repo --branch develop\n/fetch-repo owner/repo --include \"src/\" --exclude \"*.lock\"\n/fetch-repo /path/to/local/repo --output analysis.md\n```\n\nThis command provides a streamlined way to fetch and analyze repository contents with proper context and follow-up suggestions.\n\n### CLAUDE.md Instructions\n\nTo 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:\n\n```markdown\n# Repository Analysis Instructions\n\nWhen 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`.\n\n## Usage Examples:\n- \"How does facebook/react implement hooks?\" \u2192 Use: `repo-to-md facebook/react --include \"packages/react/src/ReactHooks*\"`\n- \"Show me how tailwindcss handles configuration\" \u2192 Use: `repo-to-md tailwindlabs/tailwindcss --include \"src/config*\"`\n- \"Analyze the testing setup in this repo\" \u2192 Use: `repo-to-md owner/repo --include \"test*\" --include \"*.test.*\"`\n\n## Output Options:\n1. **For reference/analysis**: Output directly to context using `repo-to-md owner/repo [options]`\n2. **For extensive analysis**: Save to file using `repo-to-md owner/repo [options] --output analysis.md`\n\nUse the most specific include/exclude patterns possible to focus on relevant code sections and avoid overwhelming the context with unnecessary files.\n```\n\nThis 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.\n\n## Contributing & License\n\nIssues and pull requests are welcome. Licensed under the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html).\n",
"bugtrack_url": null,
"license": null,
"summary": "Fetch git and GitHub repos as markdown for LLM and AI Agents context",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/vduseev/repo-to-md",
"Issues": "https://github.com/vduseev/repo-to-md/issues",
"Repository": "https://github.com/vduseev/repo-to-md"
},
"split_keywords": [
"ai",
" claude",
" context",
" fetch",
" git",
" llm",
" markdown",
" read",
" repo",
" repository",
" text"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0f808dd961daaae5993aa92ff66c16e92e306a5f301a873fe70be7b52e35911b",
"md5": "b57824585e50668804ba9259c8b57cba",
"sha256": "0a632e51e108456f2d8fbe3049bf565d6de7feda3af79b3935a51ba455712818"
},
"downloads": -1,
"filename": "repo_to_md-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b57824585e50668804ba9259c8b57cba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13670,
"upload_time": "2025-07-23T09:15:09",
"upload_time_iso_8601": "2025-07-23T09:15:09.557330Z",
"url": "https://files.pythonhosted.org/packages/0f/80/8dd961daaae5993aa92ff66c16e92e306a5f301a873fe70be7b52e35911b/repo_to_md-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "304a834cf03c1958f5c8851efeb71fa4c91aa39a9c0ac5cc6c26de8317c61418",
"md5": "396310ce01467bba58b3800a6ca52a4e",
"sha256": "3a03a7f6efa995a3a0f60c28a41eae0ffec5d56efa2ca177b7ddc4ab3d4547f0"
},
"downloads": -1,
"filename": "repo_to_md-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "396310ce01467bba58b3800a6ca52a4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14423,
"upload_time": "2025-07-23T09:15:10",
"upload_time_iso_8601": "2025-07-23T09:15:10.638839Z",
"url": "https://files.pythonhosted.org/packages/30/4a/834cf03c1958f5c8851efeb71fa4c91aa39a9c0ac5cc6c26de8317c61418/repo_to_md-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 09:15:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vduseev",
"github_project": "repo-to-md",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "repo-to-md"
}
JSON
