gitree 🌴

An upgrade from "ls" for developers. An open-source 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

💡 Getting Started

Open a terminal in any project and run:

# This should print the structure of the current working directory
gitree

# OR use this short alias
gt

Now try using --full for printing full directory structure:

gt --full

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

Try using --emoji for better visuals:

gt --full --emoji

# You can also use -f and -e together like this
gt -fe

🧠 This is where it gets useful

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

gt --code --copy --interactive

# OR alternaitvely, using short aliases
# -i for interactive, -c for copy, -f for full, -t for types
gt --code -ci

For zipping the whole project (use -g to respect gitignore):

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

# OR alternatively, using alias
gt -z project

# To respect gitignore rules when zipping, add -g flag
gt -gz project

# To zip only the code files use --code
gt -z project --code

For dumping 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 --export project --format tree

# OR using aliases
gt -x project --format tree

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

# OR using --fmt alias
gt -fx project --fmt json

🧩 How it works

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

⚙️ Common Arguments

General Options

Semantic Flags (Quick Actions)

Output & Export Options

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.