gitree 0.5.0

gitree: git-aware project tree printing and zipping for docs and LLMs

gitree 🌴

A replacement of "ls" for developers. An open-source python tool to analyze folder structures and to provide code context to LLMs. Published on PyPi

[!NOTE] Instead of the full-name "gitree", you may use "gt" to call this tool

---

📦 Installation

Install using pip (python package manager):

# Install the latest version using pip
pip install gitree

# Alternatively, use pipx
pipx install gitree

# to update gitree
pip install -U gitree

---

💡 Usage

To literally get started, I would recommend doing this:

Open a terminal in any project and run:

# paths should default to the current working directory
# This will scan gitignores by default
gitree

# OR use this short alias
gt

Now try this for better visuals:

gt --emoji

# OR -e as alias for --emoji
gt -e

For printing the full structure of any directory or project:

gt --full -e

# OR -f as alias for --full (and then -e can just be used together with it)
gt -fe

For copying all C++ code in your project, with interactive selection:

gt --full --copy --interactive --only-types cpp

# OR alternaitvely, using alias
# -i for interactive, -c for copy and -f for full
gt -fci --only-types cpp

For zipping the whole project, respecting gitignore:

# creates project.zip in the same directory
gt --full --zip project

# OR alternatively, using alias
gt -fz project

For copying the whole project into a single file:

# Creates project.txt in the directory from where gt is run
# Default format for export is tree
gt --full --export project --format tree

# OR alternatively use alias
gt -fx project --format tree

# OR use other formats
gt -fx project --format json
gt -fx project --format md

---

🧩 How it works

    ╭────────────────────────────╮
    │           Start            │
    ╰────────────────────────────╯
                  │
                  ▼
    ╭────────────────────────────╮
    │      Argument Parsing      │
    ╰────────────────────────────╯
                  │
                  ▼
    ╭────────────────────────────╮
    │  Files/Folders Selection   │
    ╰────────────────────────────╯
                  │
                  ▼
    ╭────────────────────────────╮
    │   Interactive Selection    │
    │      (only if used)        │
    ╰────────────────────────────╯
            │
            ├─────────────────────────┐
            │                         │
            ▼                         ▼
    ╭─────────────────╮    ╭─────────────────────╮
    │ Zipping Service │    │   Drawing Service   │
    ╰─────────────────╯    ╰─────────────────────╯
            │                  │
            │                  ├────────────────────┐
            │                  │                    │
            │                  ▼                    ▼
            │         ╭─────────────────╮  ╭──────────────────╮
            │         │  Copy Service   │  │  Export Service  │
            │         ╰─────────────────╯  ╰──────────────────╯
            │                  │                    │
            │                  └──────────┬─────────┘
            │                             │
            └─────────────────────────────┘
                           │
                           ▼
               ╭────────────────────────╮
               │    Output & Finish     │
               ╰────────────────────────╯

---

✨ Overall Features

Feature	Description
Tree Visualization	Generate a structure for any directory for visualizing and understanding the codebase
Smart File Selection	Control what's selected by the tool with custom ignore patterns, depth limits, and item caps
Interactive Selection	Gain full control of the output by reviewing what's selected by the file selection service
Copy Your Codebase	Instantly copy the whole codebase file contents to your clipboard to paste into LLMs
Multiple Export Formats	Export your codebase contents to files using tree, json and markdown formats
Zipping the Whole Project	Create project archives that automatically respect .gitignore rules
Large/Binary Files Handling	Automatically detects binary and large files and marks or skips them during export

---

⚙️ Common Arguments

General Options

Argument	Description
-h, --help	Show the help message with all available options and exit.
-v, --version	Display the version number of the tool.
--verbose	Enable logger output to the console. Helpful for debugging.
--config-user	Create a default config.json file in the current directory and open it in the default editor.
--no-config	Ignore both user-level and global-level config.json and use default and CLI values for configuration.

Semantic Flags (Quick Actions)

Argument	Description
-f, --full	Shortcut for --max-depth 5 - show full directory tree up to 5 levels deep.
-e, --emoji	Show emojis in the output for better visual clarity.
-i, --interactive	Use interactive mode for manual file selection after automatic filtering.
-c, --copy	Copy file contents and project structure to clipboard (great for LLM prompts).
--only-types	Include only specific code extensions (e.g., --only-types py cpp tsx).

Output & Export Options

Argument	Description
-z, --zip	Create a zip archive of the given directory respecting gitignore rules.
--export	Save project structure along with its contents to a file with the format specified using --format.
--format	Format output only. Options: tree, json, md. Default: tree.

Full CLI Arguments List (Click to expand)

Listing Options

Argument	Description
--max-items	Limit items to be selected per directory.
--max-entries	Limit entries (files/dirs) to be selected for the overall output.
--max-depth	Maximum depth to traverse when selecting files.
--gitignore-depth	Limit depth to look for during .gitignore processing.
-a, --hidden-items, --all	Show hidden files and directories.
--exclude [pattern ...]	Patterns of files to specifically exclude.
--exclude-depth	Limit depth for exclude patterns.
--include [pattern ...]	Patterns of files to specifically include.
--include-file-types	Include files of certain types.
--files-first	Print files before directories.
--no-color	Disable colored output.
--no-contents	Don't include file contents in export/copy.
--no-contents-for [path ...]	Exclude contents for specific files for export/copy.
--max-file-size	Maximum file size in MB to include in exports (default: 1.0).
--override-files	Override existing files.

Listing Override Options

Argument	Description
--no-max-entries	Disable --max-entries limit.
--no-max-items	Disable --max-items limit.
--no-gitignore	Do not use .gitignore rules.
--no-files	Hide files (show only directories).

---

Installation (for Contributors)

Clone the repository:

git clone 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):

gt

For running unit tests after making changes:

python -m tests

---

Contributions

[!TIP] This is YOUR tool. Issues and pull requests are always welcome.

Gitree is kept intentionally small and readable, so contributions that preserve simplicity and follow Contributing Guidelines are especially appreciated.