Metadata-Version: 2.4
Name: gitree
Version: 0.2.1
Summary: Gitree: git-aware project tree printing and zipping for docs and LLMs
Author: Shahzaib Ahmad
License: MIT
Project-URL: Homepage, https://github.com/ShahzaibAhmad05/gitree
Project-URL: Repository, https://github.com/ShahzaibAhmad05/gitree
Project-URL: Issues, https://github.com/ShahzaibAhmad05/gitree/issues
Project-URL: Changelog, https://github.com/ShahzaibAhmad05/gitree/releases
Keywords: tree,directory-tree,git,gitignore,cli,docs,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pathspec>=0.11
Requires-Dist: pyperclip>=1.5
Requires-Dist: questionary>=1.10.0
Dynamic: license-file

# Gitree

**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.**

## ✨ Features

| 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 |

## 🔥 The problems it solves:

* 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 `.gitignore` for prompting LLMs.**

## 📦 Installation

Run this command in your terminal:

```
# Install using pip
pip install gitree       
```

### 💡 Usage

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.

## 🧭 Interactive Mode

Gitree supports an **interactive mode** that allows you to select files and directories step-by-step instead of relying only on CLI flags.

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

### Enable Interactive Mode

Use the `-i` or `--interactive` flag:

    gitree --interactive
    # or
    gitree -i

### How It Works

When interactive mode is enabled, Gitree will:

1. Scan the project directory (respecting `.gitignore`)
2. Present an interactive file and folder selection menu
3. Allow you to choose what to include or exclude
4. Generate output based on your selections

### Interactive Controls

During interactive selection, the following keys are supported:

- **↑ / ↓** — navigate items  
- **Space** — select / deselect item  
- **Enter** — confirm selection  
- **Esc / Ctrl+C** — exit interactive mode  

### Example

    gitree -i --emoji --out context.txt

This will:
- launch interactive selection
- display output using emojis
- save the result to `context.txt`


### Updating Gitree:

To update the tool, type:

```
pip install -U gitree
```

Pip will automatically replace the older version with the latest release.


## 🧪 Continuous Integration (CI)

Gitree uses Continuous Integration (CI) to ensure code quality and prevent regressions on every change.

### What CI Does
- Runs automated checks on every pull request
- Verifies that all CLI arguments work as expected
- Ensures the tool behaves consistently across updates

### Current Test Coverage

| Test Type | Description |
|----------|-------------|
| CLI Argument Tests | Validates all supported CLI flags and options |
| Workflow Checks | Ensures PRs follow required checks before merging |

> ℹ️ CI tests are continuously expanding as new features are added.


## ⚙️ CLI Arguments

In addition to the directory path, the following options are available:

| Argument            | Description |
|---------------------|-------------|
| `--version`, `-v`   | Displays the installed version. |
| `--max-depth`           | Limits recursion depth. Example: `--depth 1` shows only top-level files and folders. |
| `--hidden-items`    | Includes hidden files and directories. Does not override `.gitignore`. |
| `--exclude`         | Patterns of files to exclude. Example: `--exclude *.pyc __pycache__`. |
| `--exclude-depth`   | Limits depth for `--exclude` patterns. Example: `--exclude-depth 2` applies exclude rules only to first 2 levels. |
| `--gitignore-depth` | Controls how deeply `.gitignore` files are discovered. Example: `--gitignore-depth 0` uses only the root `.gitignore`. |
| `--no-gitignore`    | Ignores all `.gitignore` rules when set. |
| `--max-items`       | Limits items shown per directory. Extra items are summarized as `... and x more items`. Default: `20`. |
| `--no-limit`        | Removes the per-directory item limit. |
| `--no-files`        | Hide files from the tree (only show directories). |
| `--emoji`, `-e`     | Show emojis in tree output. |
| `--summary`         | Print a summary of the number of files and folders at each level. |
| `--zip [name]`, `-z` | Zips the project while respecting `.gitignore`. Example: `--zip a` creates `a.zip`. |
| `--json [file]`     | Export tree as JSON to specified file. Example: `--json tree.json`. |
| `--txt [file]`      | Export tree as text to specified file. Example: `--txt tree.txt`. |
| `--md [file]`       | Export tree as Markdown to specified file. Example: `--md tree.md`. |
| `--output [file]`, `-o` | Save tree structure to file. Example: `--output tree.txt` or `--output tree.md` for markdown format. |
| `--copy`, `-c`      | Copy tree output to clipboard. |
| `--include`         | Patterns of files to include (used in interactive mode). Example: `--include *.py *.js`. |
| `--include-file-type` | Include files of a specific type. Example: `--include-file-type json` or `--include-file-type .py`. Case-insensitive. |
| `--include-file-types` | Include files of multiple types. Example: `--include-file-types png jpg json`. Case-insensitive. |
| `--json [file]`     | Export tree as JSON to specified file. **By default, includes file contents** (up to 1MB per file). |
| `--txt [file]`      | Export tree as text to specified file. **By default, includes file contents** (up to 1MB per file). |
| `--md [file]`       | Export tree as Markdown to specified file. **By default, includes file contents** with syntax highlighting (up to 1MB per file). |
| `--no-contents`     | Don't include file contents when exporting to JSON, TXT, or MD formats. Only the tree structure will be included. |
| `--interactive`, `-i` | Interactive mode: select files to include using a terminal-based UI. |
| `--include`         | Patterns of files to include. Example: `--include *.py *.js`. |
| `--init-config`     | Create a default `config.json` file in the current directory. |
| `--config-user`     | Open `config.json` in the default editor. |
| `--no-config`       | Ignore `config.json` and use hardcoded defaults. |


## 📝 File Contents in Exports

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:

```bash
gitree --json output.json --no-contents
```


## 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
```

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
```


## Contributions

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.
