repo2doc

repo2doc is a Rust command-line tool that converts repository files into LLM-friendly document snapshots.

What It Generates

• Deterministic output files (repo2doc_001.txt, repo2doc_002.txt, ...)
• First document includes repository metadata and an ASCII directory tree
• One section per source file (a source file is never split across outputs)
• Optional zip archive containing all generated output files

The scanner respects .gitignore, hard-excludes .git internals and .env* paths, skips binary files, and can optionally narrow output with include globs.

Install

Cargo (Local)

cargo install --path . --locked
repo2doc --help

npm (After Publishing)

This npm package builds the Rust binary during install, so Rust (cargo) must be available on the machine. The published lockfile is pinned to avoid edition2024-only transitive crates, so installs work on Cargo 1.83.0+.

npm install -g repo2doc
repo2doc --help

Build and Run

cargo build --release
cargo run --

CLI Usage

repo2doc [OPTIONS]

Key options:

• --repo <PATH>: repository root to scan (default: .)
  • when omitted (or .), repo2doc auto-detects the git top-level for the current working directory
  • if no git repo is detected, it uses the current working directory
• --out <PATH>: output directory (default: ./repo_docs)
• --max-words-per-file <WORDS>: word limit per output file (default: 500k = 500,000 words)
  • supports k and m suffixes (120k, 1m)
  • 0 means no limit (single output file)
• --format <txt|md>: output format (default: txt, markdown is optional backup)
• --include <GLOB>: only render files matching one or more globs
  • repeat the flag to combine patterns with OR semantics
  • patterns without / match basenames anywhere in the repo (pattern*.rs)
  • patterns with / match repo-relative paths (src/**/*.rs)
• --zip-out <ZIP_PATH>: optional zip destination
• --staged: only document files currently staged in git (writes staged.<ext>)
• --commit <COMMIT>: only document files touched by one or more commits (repeatable)
  • output file name uses the first commit value: <first-commit>.<ext>
• --diff: with --staged or --commit, render git patch output instead of full file contents
  • output file stem adds _diff in this mode (staged_diff.<ext>, <first-commit>_diff.<ext>)
  • git-scoped modes require --repo to point at a git work tree

Examples

# default behavior (txt output, 500k words per file)
repo2doc

# custom word limit
repo2doc --max-words-per-file 120k

# no limit (single file)
repo2doc --max-words-per-file 0

# markdown output
repo2doc --format md

# only include Rust files whose basenames start with "pattern"
repo2doc --include 'pattern*.rs'

# only include repo-relative paths under src/
repo2doc --include 'src/**/*.rs'

# zip output
repo2doc --zip-out ./repo_docs/output.zip

# only staged files, full file contents (default mode for scoped generation)
repo2doc --staged

# only staged changes as patch output
repo2doc --staged --diff

# files touched by one commit
repo2doc --commit 8e92f6d

# files touched by multiple commits (output named after the first commit)
repo2doc --commit 8e92f6d --commit 7a3fdcb

# commit-scoped patch output
repo2doc --commit 8e92f6d --diff

Quality Gates

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings -D missing_docs -D clippy::missing_errors_doc
cargo test