A git-aware CLI tool to provide LLM context for coding projects by combining project files into a single file with a number of different formats to choose from.
| Feature | Description |
|---|---|
| 📊 Project Tree Visualization | Generate clean directory trees with customizable depth and formatting |
| 🗜️ Smart Zipping | Create project archives that automatically respect .gitignore rules |
| 🎯 Flexible Filtering | Control what's shown with custom ignore patterns, depth limits, and item caps |
| 🔍 Gitignore Integration | Use .gitignore files at any depth level, or disable entirely when needed |
| 📋 Multiple Output Formats | Export to files, copy to clipboard, or display with emoji icons |
| 📁 Directory-Only View | Show just the folder structure without files for high-level overviews |
| 📈 Project Summary | Display file and folder counts at each directory level with summary mode |
- sharing project structure in issues or pull requests
- generating directory trees for documentation
- pasting project layouts into LLMs
- converting entire codebases to a single json file using
.gitignorefor prompting LLMs.
Install using pip (python package manager):
# Install the latest version using pip
pip install gitree
# Get the stable version instead (older, lacks features)
pip install gitree==0.1.3
To use this tool, refer to this format:
gitree [path] [other CLI args/flags]
Open a terminal in any project and run:
# path should default to .
gitree
Example output:
Gitree
├─ gitree/
│ ├─ constants/
│ │ ├─ __init__.py
│ │ └─ constant.py
│ ├─ services/
│ │ ├─ __init__.py
│ │ ├─ draw_tree.py
│ │ ├─ list_enteries.py
│ │ ├─ parser.py
│ │ └─ zip_project.py
│ ├─ utilities/
│ │ ├─ __init__.py
│ │ ├─ gitignore.py
│ │ └─ utils.py
│ ├─ __init__.py
│ └─ main.py
├─ CODE_OF_CONDUCT.md
├─ CONTRIBUTING.md
├─ LICENSE
├─ pyproject.toml
├─ README.md
├─ requirements.txt
└─ SECURITY.md
Using emojis as file/directory icons:
gitree --emoji
Example output:
Gitree
├─ 📂 gitree/
│ ├─ 📂 constants/
│ │ ├─ 📄 __init__.py
│ │ └─ 📄 constant.py
│ ├─ 📂 services/
│ │ ├─ 📄 __init__.py
│ │ ├─ 📄 draw_tree.py
│ │ ├─ 📄 list_enteries.py
│ │ ├─ 📄 parser.py
│ │ └─ 📄 zip_project.py
│ ├─ 📂 utilities/
│ │ ├─ 📄 __init__.py
│ │ ├─ 📄 gitignore.py
│ │ └─ 📄 utils.py
│ ├─ 📄 __init__.py
│ └─ 📄 main.py
├─ 📄 CODE_OF_CONDUCT.md
├─ 📄 CONTRIBUTING.md
├─ 📄 LICENSE
├─ 📄 pyproject.toml
├─ 📄 README.md
├─ 📄 requirements.txt
└─ 📄 SECURITY.md
For zipping a directory:
gitree --zip out
creates out.zip in the same directory.
Gitree supports an interactive mode that allows you to select files and directories step-by-step instead of relying only on CLI flags.
Tip
This is useful when:
- you want fine-grained control over included files
- you prefer a guided terminal-based selection flow
- you want to explore a project before exporting its structure
Use the -i or --interactive flag:
gitree --interactive
# or
gitree -i
When interactive mode is enabled, Gitree will:
- Scan the project directory (respecting
.gitignore) - Present an interactive file and folder selection menu
- Allow you to choose what to include or exclude
- Generate output based on your selections
During interactive selection, the following keys are supported:
- ↑ / ↓ — navigate items
- Space — select / deselect item
- Enter — confirm selection
- Esc / Ctrl+C — exit interactive mode
gitree -i --emoji --out context.txt
This will:
- launch interactive selection
- display output using emojis
- save the result to
context.txt
To update the tool, type:
pip install -U gitree
Pip will automatically replace the older version with the latest release.
Gitree uses Continuous Integration (CI) to ensure code quality and prevent regressions on every change.
- Runs automated checks on every pull request
- Verifies that all CLI arguments work as expected
- Ensures the tool behaves consistently across updates
| Test Type | Description |
|---|---|
| CLI Argument Tests | Validates all supported CLI flags and options |
| Workflow Checks | Ensures PRs follow required checks before merging |
Note
CI tests are continuously expanding as new features are added.
The CI configuration is defined in .github/workflows/
Each workflow file specifies:
- Trigger conditions (i.e. pull request)
- The Python version(s) used
- The commands executed during the pipeline
If any step fails, the pipeline will fail and the pull request cannot be merged until the issue is resolved.
In addition to the directory path, the following options are available:
| Argument | Description |
|---|---|
--version, -v |
Displays the installed version. |
--interactive, -i |
Interactive selection UI. |
--init-config |
Create a default config.json in the current directory. |
--config-user |
Open config.json in the default editor. |
--no-config |
Ignore config.json and use hardcoded defaults. |
| Argument | Description |
|---|---|
--max-depth |
Limit recursion depth (e.g., --max-depth 1). |
--hidden-items |
Include hidden files and directories (does not override .gitignore). |
--exclude [pattern] |
Exclude patterns (e.g., --exclude *.pyc __pycache__). |
--exclude-depth [n] |
Limit depth for exclude patterns (e.g., --exclude-depth 2). |
--gitignore-depth [n] |
Control discovery depth for .gitignore (e.g., --gitignore-depth 0). |
--no-gitignore |
Ignore all .gitignore rules. |
--max-items |
Limit items per directory (default: 20). |
--no-limit |
Remove per-directory item limit. |
--max-lines |
Limit lines (default: 40). |
--no-limit |
Remove per-directory item limit. |
--no-max-lines |
Disable total lines limit. |
--no-files |
Show only directories (hide files). |
--emoji, -e |
Use emojis in output. |
--summary |
Print file/folder counts per level. |
--include [pattern] |
Include patterns (often used with interactive mode). |
--include-file-type |
Include a specific file type (e.g., .py, json). |
--include-file-types |
Include multiple file types (e.g., png jpg json). |
| Argument | Description |
|---|---|
--max-depth |
Limit recursion depth (e.g., --max-depth 1). |
--hidden-items |
Include hidden files and directories (does not override .gitignore). |
--exclude [pattern] |
Exclude patterns (e.g., --exclude *.pyc __pycache__). |
--exclude-depth [n] |
Limit depth for exclude patterns (e.g., --exclude-depth 2). |
--gitignore-depth [n] |
Control discovery depth for .gitignore (e.g., --gitignore-depth 0). |
--no-gitignore |
Ignore all .gitignore rules. |
--max-items |
Limit items per directory (default: 20). |
--no-limit |
Remove per-directory item limit. |
--no-files |
Show only directories (hide files). |
When using --json, --txt, or --md flags, file contents are included by default. This feature:
- ✅ Includes text file contents (up to 1MB per file)
- ✅ Detects and marks binary files as
[binary file] - ✅ Handles large files by marking them as
[file too large: X.XXmb] - ✅ Uses syntax highlighting in Markdown format based on file extension
- ✅ Works with all filtering options (
--exclude,--include,.gitignore, etc.)
To export only the tree structure without file contents, use the --no-contents flag:
gitree --json output.json --no-contents
Clone the repository:
git clone [https://github.com/ShahzaibAhmad05/Gitree](https://github.com/ShahzaibAhmad05/Gitree)
Move into the project directory:
cd Gitree
Setup a Virtual Environment (to avoid package conflicts):
python -m venv .venv
Activate the virtual environment:
.venv/Scripts/Activate # on windows
.venv/bin/activate # on linux/macOS
Warning
If you get an execution policy error on windows, run this:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Install dependencies in the virtual environment:
pip install -r requirements.txt
The tool is now available as a Python CLI in your virtual environment.
For running the tool, type (venv should be activated):
gitree
For running tests after making any changes:
python -m unittest discover tests
Tip
This is YOUR tool. Issues and pull requests are welcome.
Gitree is kept intentionally small and readable, so contributions that preserve simplicity are especially appreciated.