tree2md

A command-line tool that scans directories and outputs their structure in Markdown format. Can optionally include file contents as code blocks with syntax highlighting.

Features

• Generate Markdown-formatted directory trees
• Include file contents as syntax-highlighted code blocks
• Filter files by extension
• Find files using wildcard patterns (glob)
• Respect .gitignore patterns
• Truncate large files by bytes or lines
• Support for hidden files and directories
• Read file paths from stdin for precise control
• Flat output format for discrete file collections
• Security boundary enforcement with --restrict-root
• Fast and efficient, written in Rust

Installation

From crates.io

cargo install tree2md

From source

git clone https://github.com/zawakin/tree2md.git
cd tree2md
cargo build --release
# Binary will be at ./target/release/tree2md

Pre-built binaries

Download pre-built binaries from the releases page.

Available for:

• Linux (x86_64)
• macOS (Apple Silicon)
• Windows (x86_64)

Usage

Common Use Cases

# Copy project structure to clipboard for documentation (macOS)
tree2md src -c | pbcopy

# Copy project structure to clipboard (Linux)
tree2md src -c | xclip -selection clipboard

# Copy project structure to clipboard (Windows)
tree2md src -c | clip

# Generate README documentation
tree2md src -c > PROJECT_STRUCTURE.md

# Quick overview without file contents
tree2md src | pbcopy

All Options

# Basic usage - output tree structure of current directory
tree2md

# Scan specific directory
tree2md /path/to/directory

# Include file contents as code blocks
tree2md -c

# Filter by extensions
tree2md -e .rs,.toml

# Find files matching wildcard patterns
tree2md -f "*.rs"                    # All .rs files
tree2md -f "src/**/*.rs"             # All .rs files under src/
tree2md -f "*.toml" -f "*.md"        # Multiple patterns

# Include hidden files
tree2md -a

# Respect .gitignore
tree2md --respect-gitignore

# Truncate file contents
tree2md -c --max-lines 50
tree2md -c --truncate 1000

# Combine options
tree2md -f "src/**/*.rs" -c --max-lines 100

Stdin Mode

Read file paths from stdin for precise control over which files to include:

# Document only Git-tracked TypeScript files
git ls-files "*.ts" | tree2md --stdin -c

# Document recently changed files
git diff --name-only HEAD~1 | tree2md --stdin

# Use with find for null-delimited paths (handles spaces/special chars)
find src -type f -name "*.rs" -print0 | tree2md --stdin0

# Expand directories found in stdin
printf '%s\n' src tests | tree2md --stdin --expand-dirs

# Keep input order (useful for prioritized documentation)
echo -e "README.md\nsrc/main.rs\nCargo.toml" | tree2md --stdin --keep-order

# Restrict paths to project directory (security)
rg -l "TODO" | tree2md --stdin --restrict-root "$(pwd)"

# Merge stdin with directory scan
rg --files --type rust | tree2md --stdin --stdin-mode merge src

# Use flat format for discrete file collections
fzf -m | tree2md --stdin --flat -c

Options

Basic Options

• -c, --contents - Include file contents as code blocks
• -t, --truncate <N> - Truncate file content to the first N bytes
• --max-lines <N> - Limit file content to the first N lines
• -e, --include-ext <EXTS> - Comma-separated list of extensions to include (e.g., .go,.py)
• -f, --find <PATTERNS> - Find files matching wildcard patterns (can be used multiple times)
• -a, --all - Include hidden files and directories
• --respect-gitignore - Respect .gitignore files
• -h, --help - Print help information
• -V, --version - Print version information

Stdin Mode Options

• --stdin - Read file paths from stdin (newline-delimited)
• --stdin0 - Read file paths from stdin (null-delimited, for paths with spaces)
• --stdin-mode <authoritative|merge> - How to handle stdin input (default: authoritative)
  • authoritative: Use only files from stdin
  • merge: Combine stdin files with directory scan
• --keep-order - Preserve the input order from stdin (default: sort alphabetically)
• --base <DIR> - Base directory for resolving relative paths from stdin (default: current directory)
• --restrict-root <DIR> - Ensure all paths are within this directory (security feature)
• --expand-dirs - Expand directories found in stdin to their contents
• --flat - Use flat output format instead of tree structure

Example Output

## File Structure
- my_project/
  - src/
    - main.rs
    - lib.rs
  - Cargo.toml
  - README.md

### src/main.rs
```rust
// src/main.rs
fn main() {
    println!("Hello, world!");
}
```

### src/lib.rs
```rust
// src/lib.rs
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
```

Supported Languages

The tool automatically detects and applies syntax highlighting for:

• Rust (.rs)
• Go (.go)
• Python (.py)
• JavaScript (.js)
• TypeScript (.ts, .tsx)
• HTML (.html)
• CSS (.css, .scss, .sass)
• SQL (.sql)
• Shell scripts (.sh)
• TOML (.toml)
• YAML (.yaml, .yml)
• JSON (.json)
• Markdown (.md)

Building from Source

Requirements:

• Rust 1.70 or later
• Cargo

# Clone the repository
git clone https://github.com/zawakin/tree2md.git
cd tree2md

# Build release version
cargo build --release

# Run tests
cargo test

# Install locally
cargo install --path .

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.