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

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.
--user-config	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).
--code	Include only code extensions

Output & Export Options

Argument	Description
-z, --zip	Create a zip archive of the given directory (respects gitignore if -g is used).
-x, --export	Save project structure along with its contents to a file with the format specified using --format.
--format, --fmt	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.
-s, --size	Show file sizes in the output.

Listing Override Options

Argument	Description
--no-max-entries	Disable --max-entries limit.
--no-max-items	Disable --max-items limit.
-g, --gitignore	Enable .gitignore rules (respects .gitignore files).
--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.