Metadata-Version: 2.3
Name: repocat
Version: 0.3.0
Summary: Deterministic repository capture for prompt-friendly output
Keywords: llm,prompt,context,repository,cli,ai
Author: omasoud
Author-email: omasoud <osama.masoud@gmail.com>
License: MIT License
         
         Copyright (c) 2026 omasoud
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
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.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Dist: pathspec>=1.1.1
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.25.1
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/omasoud/repocat
Project-URL: Source, https://github.com/omasoud/repocat
Project-URL: Bug Tracker, https://github.com/omasoud/repocat/issues
Description-Content-Type: text/markdown

# repocat

`repocat` captures the current repository into prompt-friendly text. It walks the
current working directory, selects UTF-8 files with deterministic ignore rules,
and renders Claude XML-style output by default.

`repocat` is inspired by
[`files-to-prompt`](https://github.com/simonw/files-to-prompt), but it is not a
fork. It works toward the same broad goal of turning project files into useful
LLM prompt context with a different CLI UX, including ordered include/exclude
rules, explicit interactive-stdout handling, and CXML output by default.

## Install

Install as a standalone tool (recommended):

```bash
uv tool install repocat
# or
pipx install repocat
```

Or install into your current environment:

```bash
uv add repocat
# or
pip install repocat
```

To develop locally:

```bash
uv sync
uv run repocat --list-files
```

## Usage

By default, `repocat` writes prompt output to stdout when stdout is redirected
or piped:

```bash
repocat > prompt.xml
repocat | pbcopy
```

When stdout is an interactive terminal, bare `repocat` prints guidance instead
of dumping file contents. To print directly to the terminal anyway:

```bash
repocat --stdout
```

For the full command reference, rule-order details, examples, and project link:

```bash
repocat -h
```

Render Markdown fenced code blocks instead:

```bash
repocat --markdown > prompt.md
```

Write output to a UTF-8 file. The output file is excluded from capture:

```bash
repocat --output prompt.xml
```

List the files that would be captured without rendering contents:

```bash
repocat --list-files
```

The list ends with a summary line such as `Total files: 12`.

Check why specific files would or would not be captured:

```bash
repocat check README.md src/main.py
```

Disable `.gitignore` handling:

```bash
repocat --ignore-gitignore
```

Use repocat-specific include and exclude rules:

```bash
repocat --include "tmp/keep.txt"
repocat --exclude "secrets.env"
repocat --include "*" --exclude "secrets.env"
repocat --exclude "*" --include "tests/**" --gitignore-filter --list-files
```

`--include`, `--exclude`, and `--gitignore-filter` are repeatable and
order-sensitive. Later repocat rules override earlier repocat rules.

## Rule Precedence

By default, repocat respects `.gitignore`, but `.repocatignore` and command-line
rules are evaluated in a higher-precedence repocat layer.

Most repocat rules decide directly:

- `--exclude PATTERN` excludes matching files.
- `--include PATTERN` force-includes matching files, even if `.gitignore` would
  otherwise ignore them.

`--gitignore-filter` is the exception: it applies `.gitignore` as an
exclusion-only filter at that point in the ordered CLI rule sequence. It can
remove ignored files from a previous include, but it never includes files by
itself.

If the ordered repocat layer makes no decision for a file, normal `.gitignore`
handling is applied. If `.gitignore` also makes no decision, the file is
included.

Precedence:

1. Hard exclusions always win.
2. Root `.repocatignore` and ordered CLI rules decide next.
3. `.gitignore` decides only when repocat has no matching rule.
4. Files are included by default.

When `--ignore-gitignore` is set, `--gitignore-filter` has no effect because no
`.gitignore` files are loaded.

Hard exclusions are:

- Any `.git/` directory and all descendants.
- The `--output` file when it is inside the invocation root.

Nested `.repocatignore` files are ignored. Nested `.gitignore` files are honored
by default and scoped to their own directories.

## Text, Symlinks, and Warnings

All configuration files, captured files, and output files use UTF-8. Selected
files that cannot be read as UTF-8, or cannot be read due to an I/O error, are
skipped with warnings on stderr. Warnings are never mixed into stdout prompt
output.

Directory symlinks are not followed. File symlinks are captured only when their
targets resolve to regular files inside the invocation root; the rendered source
path remains the symlink path. Broken file symlinks and external symlink targets
are skipped with stderr warnings.
