{"id":23462050,"url":"https://github.com/travisvn/gptree","last_synced_at":"2025-04-07T09:15:53.339Z","repository":{"id":268324941,"uuid":"903966317","full_name":"travisvn/gptree","owner":"travisvn","description":"A CLI tool to provide LLM context for coding projects by combining project files into a single text file (or clipboard text) with directory tree structure.","archived":false,"fork":false,"pushed_at":"2025-03-16T20:03:48.000Z","size":5046,"stargazers_count":51,"open_issues_count":2,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T08:07:58.465Z","etag":null,"topics":["ai","artificial-intelligence","brew","chatgpt","claude","cli","coding-assistant","command-line","copilot","cursor","developer-tools","devtools","gemini","gpt","homebrew","llm","openai","productivity","terminal","tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/travisvn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-16T01:49:48.000Z","updated_at":"2025-03-28T05:30:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"fdfd951c-d130-42b5-aa06-91da4923c1e2","html_url":"https://github.com/travisvn/gptree","commit_stats":null,"previous_names":["travisvn/gptree"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisvn%2Fgptree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisvn%2Fgptree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisvn%2Fgptree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisvn%2Fgptree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/travisvn","download_url":"https://codeload.github.com/travisvn/gptree/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622988,"owners_count":20968575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","brew","chatgpt","claude","cli","coding-assistant","command-line","copilot","cursor","developer-tools","devtools","gemini","gpt","homebrew","llm","openai","productivity","terminal","tool"],"created_at":"2024-12-24T08:15:36.456Z","updated_at":"2025-04-07T09:15:53.325Z","avatar_url":"https://github.com/travisvn.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# gptree 🌳\n\n**A CLI tool to provide LLM context for coding projects by combining project files into a single text file with a directory tree structure.**\n\n![GitHub stars](https://img.shields.io/github/stars/travisvn/gptree?style=social)\n![PyPI - Version](https://img.shields.io/pypi/v/gptree-cli)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/travisvn/gptree/.github%2Fworkflows%2Fbuild.yml)\n![GitHub Release](https://img.shields.io/github/v/release/travisvn/gptree)\n![GitHub last commit](https://img.shields.io/github/last-commit/travisvn/gptree?color=red)\n[![PyPI Downloads](https://static.pepy.tech/badge/gptree-cli)](https://pepy.tech/projects/gptree-cli)\n\n## What is gptree?\n\nWhen working with Large Language Models (LLMs) to continue or debug your coding projects, providing the right context is key. `gptree` simplifies this by:\n\n1. Generating a clear **directory tree structure** of your project.\n2. Combining the **contents of relevant files** into a single output text file.\n3. Allowing you to **select files interactively** to fine-tune which files are included.\n\nThe resulting file can easily be copied and pasted into LLM prompts to provide the model with the necessary context to assist you effectively.\n\n![GPTree Demo](./demo.gif)\n\n## Features\n\n- 🗂 **Tree Structure**: Includes a visual directory tree of your project.\n- ✅ **Smart File Selection**: Automatically excludes ignored files using `.gitignore` and common directories like `.git`, `__pycache__`, and `.vscode`.\n- 🎛 **Interactive Mode**: Select or deselect files interactively using arrow keys, with the ability to quit immediately by pressing `ESC`.\n- 🌍 **Global Config Support**: Define default settings in a `~/.gptreerc` file.\n- 🔧 **Directory-Specific Config**: Customize behavior for each project via a `.gptree_config` file.\n- 🎛 **CLI Overrides**: Fine-tune settings directly in the CLI for maximum control.\n- 📜 **Safe Mode**: Prevent overly large files from being combined by limiting file count and total size.\n- 📋 **Clipboard Support**: Automatically copy output to clipboard if desired.\n- 🛠 **Custom Configuration Management**: Define configurations that are auto-detected per project or globally.\n\n## Installation\n\n### Install via `pipx` 📦 (Recommended)\n\n```bash\npipx install gptree-cli\n```\n\n[How to setup pipx](https://pipx.pypa.io/)\n\n### Install via Homebrew 🍺\n\n```bash\nbrew tap travisvn/tap\nbrew install gptree\n```\n\nHomebrew will attempt to install `gptree` using `pip3` and will fall back to binary installation otherwise\n\n### Install via pip 🐍\n\nAlternatively, install `gptree` (`gptree-cli`) directly via [pip](https://pypi.org/project/gptree-cli/):\n\n```bash\npip install gptree-cli\n```\n\n\u003e [!NOTE]\n\u003e Performance is better when installing directly with Python (`pipx` or `pip`)\n\u003e\n\u003e The binary installation might take a second or two longer to start up (not a huge deal — just something to note)\n\n## Usage\n\nRun `gptree` in your project directory:\n\n```bash\ngptree\n```\n\nOr run it anywhere and define the relative path to your project\n\n### Options\n\n| Flag                             | Description                                                                                       |\n| -------------------------------- | ------------------------------------------------------------------------------------------------- |\n| `--interactive`, `-i`            | Enable interactive file selection                                                                 |\n| `--copy`, `-c`                   | Copy result directly to clipboard                                                                 |\n| `--include-file-types`           | Comma-separated list of file types to include (e.g., `.py,.js` or `py,js`). Use `*` for all types |\n| `--exclude-file-types`           | Comma-separated list of file types to exclude (e.g., `.log,.tmp` or `log,tmp`)                    |\n| `--output-file`                  | Specify the name of the output file                                                               |\n| `--output-file-locally`          | Save the output file in the current working directory                                             |\n| `--no-config`, `-nc`             | Disable creation or use of configuration files                                                    |\n| `--ignore-gitignore`             | Ignore `.gitignore` patterns                                                                      |\n| `--disable-safe-mode`, `-dsm`    | Disable safe mode checks for file count or size                                                   |\n| `--line-numbers`, `-n`           | Add line numbers to the output                                                                    |\n| `--previous`, `-p`               | Use the previously saved file selection                                                           |\n| `--save`, `-s`                   | Save the selected files to the configuration                                                      |\n| `--show-ignored-in-tree`         | Show all ignored files in the directory tree                                                      |\n| `--show-default-ignored-in-tree` | Show default ignored files in the tree while still respecting gitignore                           |\n| `--version`                      | Display the current version of GPTree                                                             |\n| `path`                           | (Optional) Root directory of your project. Defaults to `.`                                        |\n\n### Examples\n\nInteractive file selection with custom file types:\n\n```bash\ngptree --interactive --include-file-types '.py,.js'\n```\n\nSave current selection to config:\n\n```bash\ngptree --interactive --save\n```\n\nRe-use previously saved file selections and copy to clipboard:\n\n```bash\ngptree --previous --copy\n```\n\n## Configuration\n\n### Global Config (`~/.gptreerc`)\n\nDefine your global defaults in `~/.gptreerc` to avoid repetitive setup across projects. Example:\n\n```yaml\n# ~/.gptreerc\nversion: 2\nuseGitIgnore: true\nincludeFileTypes: .py,.js # Include only Python and JavaScript files\nexcludeFileTypes: .log,.tmp # Exclude log and temporary files\noutputFile: gptree_output.txt\noutputFileLocally: true\ncopyToClipboard: false\nsafeMode: true\nlineNumbers: false\nstoreFilesChosen: true\nshowIgnoredInTree: false\nshowDefaultIgnoredInTree: false\n```\n\nThis file is automatically created with default settings if it doesn't exist.\n\n### Directory Config (`.gptree_config`)\n\nCustomize settings for a specific project by adding a `.gptree_config` file to your project root. Example:\n\n```yaml\n# .gptree_config\nversion: 2\nuseGitIgnore: false\nincludeFileTypes: *  # Include all file types\nexcludeFileTypes: .test  # Exclude test files\noutputFile: gptree_output.txt\noutputFileLocally: false\ncopyToClipboard: true\nsafeMode: false\nlineNumbers: false\nstoreFilesChosen: false\nshowIgnoredInTree: false\nshowDefaultIgnoredInTree: true  # Show default ignored files while still respecting gitignore\n```\n\n### Configuration Precedence\n\nSettings are applied in the following order (highest to lowest precedence):\n\n1. **CLI Arguments**: Always override other settings.\n2. **Global Config**: User-defined defaults in `~/.gptreerc`.\n3. **Directory Config**: Project-specific settings in `.gptree_config`.\n4. **Programmed Defaults**: Built-in defaults used if no other settings are provided.\n\n## Safe Mode\n\nTo prevent overly large files from being combined, Safe Mode restricts:\n\n- The **total number of files** (default: 30).\n- The **combined file size** (default: ~25k tokens, ~100,000 bytes).\n\nOverride Safe Mode with `--disable-safe-mode`.\n\n## Interactive Mode\n\nIn interactive mode, use the following controls:\n\n| Key       | Action                               |\n| --------- | ------------------------------------ |\n| `↑/↓/j/k` | Navigate the file list               |\n| `SPACE`   | Toggle selection of the current file |\n| `a`       | Select or deselect all files         |\n| `ENTER`   | Confirm the selection and proceed    |\n| `ESC`     | Quit the process immediately         |\n\n## Contributing\n\nContributions are welcome! Please fork the repository and create a pull request for any improvements.\n\n## License\n\nThis project is licensed under GNU General Public License v3.0 (GPL-3.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravisvn%2Fgptree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravisvn%2Fgptree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravisvn%2Fgptree/lists"}