gptree 🌳

A CLI tool to provide LLM context for coding projects by combining project files into a single text file with a directory tree structure.

What is gptree?

When working with Large Language Models (LLMs) to continue or debug your coding projects, providing the right context is key. gptree simplifies this by:

1. Generating a clear directory tree structure of your project.
2. Combining the contents of relevant files into a single output text file.
3. Allowing you to select files interactively to fine-tune which files are included.
4. Supporting both simple file type filtering and advanced glob patterns for maximum flexibility.

The resulting file can easily be copied and pasted into LLM prompts to provide the model with the necessary context to assist you effectively.

Features

• 🗂 Tree Structure: Includes a visual directory tree of your project.
• ✅ Smart File Selection: Automatically excludes ignored files using .gitignore and common directories like .git, __pycache__, and .vscode.
• 📁 Simple File Types: Easy filtering by file extensions (e.g., .py,.js) for quick setup.
• 🎯 Advanced Patterns: Optional glob patterns for complex filtering (e.g., src/**/*.py, !**/tests/**).
• 🎛 Interactive Mode: Select or deselect files interactively using arrow keys, with the ability to quit immediately by pressing ESC.
• 🌍 Global Config Support: Define default settings in a ~/.gptreerc file.
• 🔧 Directory-Specific Config: Customize behavior for each project via a .gptree_config file.
• 🎛 CLI Overrides: Fine-tune settings directly in the CLI for maximum control.
• 📜 Safe Mode: Prevent overly large files from being combined by limiting file count and total size.
• 📋 Clipboard Support: Automatically copy output to clipboard if desired.
• 🛠 Custom Configuration Management: Define configurations that are auto-detected per project or globally.

🆕 GPTree GUI - Now Available! 🎉

Experience gptree with a beautiful and efficient graphical interface!

• Lightweight & Fast: Built with Rust for optimal performance.
• Cross-Platform: Available on macOS, Windows, and Linux
• Learn More & Download: Visit gptree.dev
• Open Source: Check out the code on GitHub

Installation

Install via pipx 📦 (Recommended)

pipx install gptree-cli

How to setup pipx

Install via Homebrew 🍺

brew tap travisvn/tap
brew install gptree

Homebrew will attempt to install gptree using pip3 and will fall back to binary installation otherwise

Install via pip 🐍

Alternatively, install gptree (gptree-cli) directly via pip:

pip install gptree-cli

[!NOTE] Performance is better when installing directly with Python (pipx or pip)

The binary installation might take a second or two longer to start up (not a huge deal — just something to note)

Usage

Run gptree in your project directory:

gptree

Or run it anywhere and define the relative path to your project

Options

| Flag | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------- | | --interactive, -i | Enable interactive file selection | | --copy, -c | Copy result directly to clipboard | | --include-file-types | Comma-separated list of file types to include (e.g., .py,.js or py,js). Use * for all types | | --exclude-file-types | Comma-separated list of file types to exclude (e.g., .log,.tmp or log,tmp) | | --include-patterns | Advanced: Glob patterns to include (e.g., src/**/*.py,**/*.js). Overrides include-file-types | | --exclude-patterns | Advanced: Glob patterns to exclude (e.g., **/tests/**,**/*.log). Combined with exclude-file-types | | --output-file | Specify the name of the output file | | --output-file-locally | Save the output file in the current working directory | | --no-config, -nc | Disable creation or use of configuration files | | --ignore-gitignore | Ignore .gitignore patterns | | --disable-safe-mode, -dsm | Disable safe mode checks for file count or size | | --line-numbers, -n | Add line numbers to the output | | --previous, -p | Use the previously saved file selection | | --save, -s | Save the selected files to the configuration | | --show-ignored-in-tree | Show all ignored files in the directory tree | | --show-default-ignored-in-tree | Show default ignored files in the tree while still respecting gitignore | | --version | Display the current version of GPTree | | path | (Optional) Root directory of your project. Defaults to . |

Examples

Simple File Type Filtering (Recommended for Most Users)

Include only Python and JavaScript files:

gptree --include-file-types .py,.js

Exclude log and temporary files:

gptree --exclude-file-types .log,.tmp,.cache

Include specific types while excluding others:

gptree --include-file-types .py,.js,.ts --exclude-file-types .test.py,.spec.js

<details> <summary>

Advanced Pattern Filtering (For Power Users)

</summary>

Include Python files from src directory but exclude test files:

gptree --include-patterns "src/**/*.py" --exclude-patterns "**/test_*.py"

Complex filtering for a web project:

gptree --include-patterns "src/**/*.{js,ts,jsx,tsx},styles/**/*.{css,scss}" --exclude-patterns "**/tests/**,**/*.test.*,**/*.spec.*"

Include all files except those in specific directories:

gptree --exclude-patterns "node_modules/**,venv/**,.git/**"

Hybrid Approach (Best of Both Worlds)

Use file types as primary filter with additional pattern exclusions:

gptree --include-file-types .py,.js --exclude-patterns "**/tests/**,**/node_modules/**"

Note: When both file types and patterns are specified for includes, patterns take precedence. For excludes, both file types and patterns are combined.

Interactive Mode and Configuration

Interactive file selection with pre-filtered files:

gptree --interactive --include-file-types .py,.js

Save current selection to config:

gptree --interactive --save

Re-use previously saved file selections and copy to clipboard:

gptree --previous --copy

File Filtering: Simple vs Advanced

GPTree offers two approaches for file filtering to accommodate different user needs:

🎯 Simple File Types (Recommended)

Use when: You want to include/exclude files by extension quickly and easily.

# Quick and easy - include Python and JavaScript files
gptree --include-file-types .py,.js

# Exclude common unwanted files
gptree --exclude-file-types .log,.tmp,.pyc

Config Example:

includeFileTypes: .py,.js,.ts
excludeFileTypes: .log,.tmp

🚀 Advanced Glob Patterns

Use when: You need precise control over directory structure and complex filtering.

# Advanced - include specific directory patterns
gptree --include-patterns "src/**/*.py,tests/**/*.py" --exclude-patterns "**/conftest.py"

Config Example:

includePatterns: src/**/*.py,**/*.js
excludePatterns: **/tests/**,**/*.log

🔄 Hybrid Usage

You can combine both approaches! File types provide the base filter, while patterns add advanced rules:

# Use file types as base, patterns for advanced exclusions
gptree --include-file-types .py,.js --exclude-patterns "**/node_modules/**,**/tests/**"

Pattern Syntax Reference

| Pattern | Description | | -------------- | ----------------------------------------------------- | | *.py | Files ending in .py in current directory | | **/*.py | All .py files recursively | | src/**/*.js | All .js files in src directory tree | | **/tests/** | All files in any tests directory | | **/*.{js,ts} |