gitree 0.4.4

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

gitree 🌴

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

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

---

📦 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

You will see an output similar to this:

📂 gitree
├─ 📁 gitree
├─ 📁 tests
├─ 📄 CODE_OF_CONDUCT.md
├─ 📄 CONTRIBUTING.md
├─ 📄 LICENSE
├─ 📄 pyproject.toml
├─ 📄 README.md
├─ 📄 requirements.txt
└─ 📄 SECURITY.md

For printing the full structure of any directory or project:

gt --full

# OR -f as alias for --full
gt -f

Some useful commands you can use with this tool (for LLM prompting):

# Copy all C++ code in your project, 
# with interactive selection for those files
gt **/*.cpp --copy -i

# For React-based frontend projects
gt --exclude **/*.json

# Zip the whole project files (respecting gitignore)
# creates project.zip in the same directory
gitree --zip project

# Export the file contents of your project, in different formats
gitree --export project --format tree
gitree --export project --format json
gitree --export 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

---

⚙️ CLI Arguments

The following optional arguments are available for use:

General Options

Argument	Description
--version, -v	Display the version number of the tool.
--config-user	Create a default config.json file in the current directory and open that file in the default editor.
--no-config	Ignore both user-level and global-level config.json and use default and CLI values for configuration.
--verbose	Enable logger output to the console. Enabling this prints a log after the full workflow run. Helpful for debugging.

Output & Export Options

Argument	Description
--zip, -z	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.

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.
--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.
--copy, -c	Copy file contents and project structure to clipboard. Similar to --export but copies to the clipboard instead.
--emoji, -e	Show emojis in the output.
--interactive, -i	Use interactive mode for further file selection.
--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):

gitree

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.