https://github.com/flyingfathead/catgit
Python tool to dump out a git project & its structure in a `cat`-esque way (to i.e. a LLM)
https://github.com/flyingfathead/catgit
automation cat cli code-management developer-tools git git-tools open-source productivity-tools python python3 version-control
Last synced: about 2 months ago
JSON representation
Python tool to dump out a git project & its structure in a `cat`-esque way (to i.e. a LLM)
- Host: GitHub
- URL: https://github.com/flyingfathead/catgit
- Owner: FlyingFathead
- Created: 2024-04-25T16:25:14.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-13T07:45:09.000Z (over 1 year ago)
- Last Synced: 2025-10-11T07:56:13.836Z (6 months ago)
- Topics: automation, cat, cli, code-management, developer-tools, git, git-tools, open-source, productivity-tools, python, python3, version-control
- Language: Python
- Homepage: https://github.com/FlyingFathead/catgit
- Size: 68.4 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# catgit
**_`catgit` is a Python-based cli tool to dump out an entire directory structure or a git project in a `cat`-esque way or to pass it along into a text editor into a single output or text file_**
## About `catgit`
This tool is designed to streamline the process of reviewing project contents, making it a neat little utility for developers who manage large or complex Git repositories and/or use LLM-based AI assistants to sort through their codebases.
`catgit` is intended to display the contents of a git project (or any directory tree for that matter) in a consolidated, readable format directly in your terminal or through a specified text editor. It provides a quick overview of the project's structure, including ignored files based on your `.gitignore` settings, and can output all readable files sequentially.
`catgit` supports direct dumps of an entire project's contents straight into your favorite text editor, i.e. to be passed along to a LLM assistant or such with the `--editor` flag. It can also be used to get the structural view of regular directories and their file contents, even if they're not Git repositories.
`catgit` has its own `.catgitignore` ignore lists and `.catgitinclude` include lists, both work the same way as `.gitignore` does. You can use `.catgitignore` to ignore files that you don't want to be included in your project directory tree dump, or `.catgitinclude` (with the `--includedonly` command line flag) to only include the files listed in the include file.
## Features
- **`.catgitignore`** and **`.catgitinclude`**:
- `.catgitignore`: read and respect files to skip over additional files or directories specific to `catgit` outputs. Works the same way as `.gitignore` does.
- `.catgitinclude`: when `--includedonly` command line flag is in use, only the files listed in the include file will be included in the printout.
- **Project Overview**: Outputs the complete directory and file structure of your Git project.
- **Gitignore Respect**: Respects `.gitignore` files to skip over ignored files or directories.
- **Flexible Output**: Supports output directly to the terminal or opens in a specified text editor like nano or gedit.
- **Configurable**: Options to toggle the inclusion of the tree view in the output, and choose between terminal output and editor output through configuration.
## Installation
You can install `catgit` directly from the source code:
1. Clone the repository:
```bash
git clone https://github.com/FlyingFathead/catgit.git
```
2. Navigate to the cloned directory:
```bash
cd catgit
```
3. Install the package:
```bash
pip install .
```
### Using without install
Alternatively, if you only want to try out `catgit`, navigate to the `catgit/` subdirectory and run it with:
```bash
python catgit.py /path/to/your/project/
```
## Configuration
For quick setup after installation, just use:
```bash
catgit --setup
```
`catgit` uses a configuration file (`config.ini`) which allows the user to set preferences such as:
- `output_method`: Choose between `terminal` and `editor` to display the project output.
- `editor_command`: Specify which editor to use when opening the output (e.g., `vim`, `nano`, `gedit`).
- `ignore_gitignored`: Toggle whether to ignore files as specified in `.gitignore`.
- `include_tree_view_in_file`: Decide whether to include the directory tree structure in the concatenated file output.
- `treat_non_git_as_error`: Decide whether to quit if the directory structure is not recognized as a Git repository.
- `.catgitinclude` and `.catgitignore` files to ignore files or only list included (works akin to `.gitignore`)
Please see the `config.ini` for more configuration options.
## Usage
To use `catgit`, navigate to the root directory of the project and run:
```bash
catgit /path/to/your/project/
```
You can also pass the output directly to your editor with the flag `--editor` (since v`0.10.4`):
```bash
catgit /path/to/your/project/ --editor
```
Or, `cd` to your project directory and simply run:
```bash
catgit . --editor
```
You will be prompted for an editor if a default isn't found. You can use i.e. `vim`, `nano` etc on Linux, `notepad` on Windows, etc.
## Help
After having been installed, help for using `catgit` is available by typing:
```bash
catgit --help
```
## Changes
- `0.11.4` - support added for configurable extra delimiters (i.e. markdown triple-backticks; enabled by default)
- see `config.ini` for more
- added autoconfig to default editor when i.e. listing `catgit . --editor` and no suitable editor is set.
- fixed `.gitignore` and `.catgitignore` rules and how they apply.
- `0.11.3` - fixes to ignore/include file reading and traversal rules
- `0.11.2` - added the `.catgitinclude` feature
- this allows to only print out selected files from the project, as listed in the include file
- the logic is similar to `.gitignore` (or `.catgitignore`), except it's files to _include_, not to _exclude_
- can be utilized with `--includeonly` cmdline flag
- `0.11.1` - subprocess optimization (speeds up `catgit` on larger projects)
- `0.11.0` - added `.catgitignore` functionality to ignore files
- works the same way as `.gitignore`, is useful for selective project outputs
- also added `debug_mode` (true/false) flag into `config.ini` for verbose mode
- `0.10.8` - output clarification to minimize LLM confusion and `--version`
- `0.10.7` - added `ThreadPoolExecutor` for faster performance; file sizes; line counting
- `0.10.6` - added the `treat_non_git_as_error` (true/false) config option
- `0.10.5` - git checks made robust and verbose
- `0.10.4` - added `--editor` flag for sending straight to text editor, checks for editor and asks the user if not found
- `0.10.3` - improved error catching, absolute paths
- `0.10.2` - switched to using `tempfile` for better cross-platform compatibility
- `0.10.1` - added the `--setup` flag for quick setup in cli
- `0.10` - initial public release w/ installer
## Credits
`catgit` was developed by [FlyingFathead](https://github.com/FlyingFathead) with digital ghost code contributions from ChaosWhisperer.
## License
`catgit` is open-source software licensed under the MIT license.