A Rust-based command-line utility to provide project context by scanning directories and optionally including relevant dependency files, with support for filtering and custom output.
cargo install contree-cli
contree --helpcontree is designed to help developers quickly gather and inspect project files and dependencies, particularly useful for debugging or understanding project structure. It respects .gitignore and custom .contreeignore files, supports grep-style filtering, and can include dependency files referenced in error outputs (for Rust projects).
- Directory Scanning: Recursively scans a specified directory (or current working directory by default) for files.
- File Filtering: Supports grep-style pattern matching to filter files by content.
- Explicit File Inclusion: Allows specifying files to include regardless of filters or directory scope.
- Dependency Analysis: For Rust projects, extracts and includes dependency files referenced in error messages or related to specific types/macros.
- Custom Output: Outputs results to stdout or a specified file.
- Pipeline Support: Accepts piped input (e.g., from test output) and integrates it with the context generation.
-
Ensure you have
ubiinstalled (brew install ubion Mac) -
ubi --project harmony-labs/contree-cli --exe contree --in /usr/local/bin/(
ubi --project harmony-labs/contree-cli --tag v0.1.4 --exe contree --in /usr/local/bin/for specific version)
Prerequisites
- Clone the repository or copy the project files to your local machine.
- Navigate to the project directory:
cd /path/to/contree-cli - Build the project:
make build
- Install the binary:
This installs
make install
contreeto your Cargo bin directory (typically~/.cargo/bin).
Alternatively, build and run directly without installation:
make runRun contree in the current directory:
contree-d, --dir <PATH>: Specify the directory to scan (defaults to.).-g, --grep <PATTERN>: Filter files by content matching a pattern (plain text or/regex/for regex).-i, --include <FILES>: Comma-separated list of files to include (e.g.,file1.rs,file2.rs).-D, --include-deps: Include dependency files referenced in errors (Rust projects only).-o, --output <FILE>: Write output to a file instead of stdout.
-
Scan the current directory and filter files containing "transaction":
contree --grep transaction
Or with regex:
contree --grep "/(D|d)atabase/" -
Include specific files and output to a file:
contree --include src/main.rs,lib.rs --output context.md
-
Pipe test output and include dependencies:
cargo test | contree --include-deps
-
Use Makefile targets:
make run-grep GREP=transaction make run-include INCLUDE=src/main.rs
src/main.rs: Main application logic.Cargo.toml: Rust package manifest with dependencies.Makefile: Build and run shortcuts..contreeignore: Custom ignore file (e.g., excludesCargo.lock)..gitignore: Standard Git ignore file (e.g., excludestarget/).
anyhow: Error handling.regex: Parsing and filtering with regular expressions.walkdir&ignore: Directory traversal with ignore file support.clap: Command-line argument parsing.atty: Detects if input/output is a terminal.
make buildmake cleanmake release- The tool assumes a Rust project when
--include-depsis used and looks forCargo.tomlto confirm. - Dependency file inclusion relies on
cargo treeand the local Cargo registry (typically~/.cargo/registry). - Binary files are skipped during grep filtering and marked as
[binary file]in output.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
This project adheres to the Contributor Covenant. By participating, you are expected to uphold this code.
If you discover a security vulnerability, please see SECURITY.md for how to report it.
See CHANGELOG.md for release history.
This project is licensed under the terms of the MIT License.
@mateodelnorte