Metadata-Version: 2.4
Name: filemerger-cli
Version: 0.4.1
Summary: Developer CLI tool to consolidate project files into a single, AI-ready output.
Author: CodeFleetX
License: MIT
Project-URL: Homepage, https://gitlab.com/binaryfleet/filemerger
Project-URL: Repository, https://gitlab.com/binaryfleet/filemerger
Project-URL: Issues, https://gitlab.com/binaryfleet/filemerger/issues
Keywords: filemerger,file-merger,cli,developer-tools,ai,llm,code,codebase,code-review,ai-context,project-context,developer-productivity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pathspec>=0.11
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# FileMerger

**A developer-focused CLI for consolidating project files into a single, AI-ready context document.**

Maintained by [DjangoPlay](https://djangoplay.org)

`filemerger-cli` is a developer-focused command-line tool that consolidates project
files into a single, **AI-ready** output. It is designed to provide LLMs with an
accurate, low-noise, structurally-aware view of a codebase or a selected portion
of one.

It is useful for providing complete project context to AI tools such as ChatGPT,
Gemini, Grok, Claude, and other LLM-based development workflows.

## Features

* Consolidate files and directories into a single output
* Target files and directories by name across multiple source roots
* Respect nested `.gitignore` rules
* Support optional `.filemergerignore` rules
* Include or exclude files using glob patterns
* Automatically redact common secrets by default
* Skip binary files safely
* Control maximum file size and per-file line limits
* Enforce approximate AI context-token budgets
* Deterministic file ordering
* Multiple AI-friendly output formats
* Stream output directly to standard output
* Dry-run support
* Optional symlink traversal
* Runtime configuration through `.filemerger.toml`
* CLI overrides with predictable configuration precedence
* Statistics for files, lines, bytes, tokens, skipped files, and redactions

## Requirements

* Python 3.11 or later
* `pathspec` 0.11 or later

## Installation

```bash
pip install filemerger-cli
```

After installation, the `filemerger` command is available globally:

```bash
filemerger --help
```

## Basic Usage

Merge a directory:

```bash
filemerger src/
```

Merge explicit files and directories:

```bash
filemerger src/ utils/helpers.py
```

Generate Markdown output:

```bash
filemerger src/ --format markdown
```

Print output directly to standard output:

```bash
filemerger src/ --format markdown --stdout
```

Preview files without generating output:

```bash
filemerger . --dry-run
```

Generate statistics:

```bash
filemerger src/ --stats
```

## Targeting Files and Directories

FileMerger supports name-based targeting across one or more source roots.

```bash
filemerger \
  --source users apidocs/views help/forms \
  --target views/ models.py \
  --skip migrations/ __pycache__/
```

Target matching supports three forms:

| Entry            | Meaning                                             |
| ---------------- | --------------------------------------------------- |
| `views/`         | Directory name matched anywhere under a source root |
| `views/login.py` | Exact relative path from a source root              |
| `models.py`      | Filename matched anywhere under a source root       |

If `--target` is omitted, every eligible file under the specified `--source`
roots becomes a candidate.

Targeting and skipping can be combined in the same command.

## Filtering

FileMerger applies filtering consistently to every candidate file.

### Extensions

Only supported file extensions are processed by default.

Additional extensions can be enabled with:

```bash
filemerger . --allow-ext .yaml,.yml,.toml
```

Specific files can be force-included regardless of extension:

```bash
filemerger . --include Dockerfile "*.env.example"
```

### Include and Exclude Patterns

Use glob patterns to explicitly include or exclude files:

```bash
filemerger . \
  --include Dockerfile "*.env.example" \
  --exclude "*.min.js" "*.map"
```

### Ignored Files

FileMerger respects `.gitignore` rules on a per-directory basis, matching
Git-style nested ignore behavior.

An optional `.filemergerignore` file is also supported using the same syntax.

### Excluded Directories and Files

Common directories such as the following are excluded by default:

```text
.git/
__pycache__/
node_modules/
migrations/
tests/
```

Individual exclusions can be restored:

```bash
filemerger . --allow-dir migrations,tests
```

or:

```bash
filemerger . --allow-file .DS_Store
```

### Binary Files

Binary files are detected using a null-byte heuristic and skipped automatically.

Skipped files are reported when statistics or verbose output is enabled.

### File Size Limits

The default maximum file size is 2 MB.

Override it when required:

```bash
filemerger . --max-size 25
```

## Secret Redaction

Secret redaction is enabled by default.

Before content is written to an output file or streamed to standard output,
FileMerger scans for common secret patterns, including:

* AWS access keys
* Generic API keys
* Bearer tokens
* Private key blocks
* Slack tokens
* GitHub tokens

Detected values are replaced with:

```text
[REDACTED:SECRET]
```

Disable redaction only when raw content is explicitly required:

```bash
filemerger . --no-redact-secrets
```

Redaction counts are included in statistics.

## Context Budgeting

FileMerger can estimate the resulting output size in tokens using a
character-based heuristic.

```bash
filemerger . --stats --max-tokens 100000
```

If the merged output would exceed the configured token budget,
FileMerger reports the condition and exits non-zero.

This is useful when preparing code context for an LLM with a fixed context
window or when enforcing limits in CI and automation workflows.

## Per-File Truncation

A single large source file can be limited with:

```bash
filemerger . --max-lines-per-file 400
```

When truncation occurs, FileMerger adds a marker such as:

```text
[truncated after 400 lines]
```

This prevents a large generated or source file from dominating the resulting
AI context.

## Output Formats

FileMerger supports several output formats.

| Format      | Option              | Purpose                            |
| ----------- | ------------------- | ---------------------------------- |
| Default     | `--format default`  | Human review and audits            |
| LLM         | `--llm`             | Structured plain-text AI ingestion |
| Compact LLM | `--llm-compact`     | Compact AI-oriented output         |
| AI Markers  | `--ai-markers`      | Explicit AI file-boundary markers  |
| Markdown    | `--format markdown` | Recommended for AI chat tools      |
| JSON        | `--format json`     | Programmatic consumption           |

### Markdown

Markdown output uses fenced code blocks with language-aware syntax highlighting:

```bash
filemerger src/ --format markdown
```

This is the recommended format when pasting project context into AI chat
tools.

### LLM

Use the LLM-oriented format with:

```bash
filemerger src/ --llm
```

A compact variant is available:

```bash
filemerger src/ --llm-compact
```

### AI Markers

The AI marker format provides explicit file boundaries:

```bash
filemerger src/ --ai-markers
```

Example structure:

```text
<<<FILE 1: path/to/file.py>>>
<content>
<<<END FILE>>>
```

This is useful for deterministic multi-file AI ingestion.

### JSON

JSON output is intended for programmatic processing:

```bash
filemerger src/ --format json
```

The structured representation includes information such as file path,
language, content, skipped status, and redaction information.

## Directory Tree

FileMerger prepends a tree-style project structure to output by default.

This gives an AI model an overview of the project's shape before it receives
the file contents.

Disable the tree when required:

```bash
filemerger src/ --no-tree
```

## Output Destination

By default, output is written to:

```text
filemerger-output.txt
```

Specify another output name:

```bash
filemerger src/ --output merged
```

or:

```bash
filemerger src/ -o merged
```

To stream output instead of creating a file:

```bash
filemerger src/ --stdout --format markdown
```

For example, output can be piped directly into another command:

```bash
filemerger src/ --format markdown --stdout | pbcopy
```

## Statistics

Statistics can be enabled with:

```bash
filemerger src/ --stats
```

Reported information includes:

* Files processed
* Total lines
* Total bytes
* Estimated tokens
* Skipped binary files
* Skipped non-UTF-8 files
* Skipped unreadable files
* Redacted-secret count

Verbose output is also available:

```bash
filemerger src/ --verbose
```

## Ordering

File processing is deterministic by default and sorted by path.

Alternative ordering modes are available:

```bash
filemerger src/ --sort path
filemerger src/ --sort name
filemerger src/ --sort size
filemerger src/ --sort mtime
```

The supported ordering modes are:

```text
path
name
size
mtime
```

## Configuration

FileMerger optionally supports a `.filemerger.toml` configuration file.

Example:

```toml
[filters]
max_file_size_mb = 1
exclude_dirs = ["tests"]

[output]
separator_length = 60
```

The configuration file is discovered by searching upward from the current
directory toward the filesystem root, similar to Git configuration discovery.

## Configuration Precedence

Configuration is resolved in the following order:

```text
CLI arguments
    ↓
.filemerger.toml
    ↓
Built-in defaults
```

Therefore, CLI arguments always take precedence.

For example:

```bash
filemerger . \
  --allow-dir migrations,tests \
  --allow-ext .yaml \
  --allow-file .DS_Store \
  --max-size 5 \
  --separator 40
```

These values override corresponding values from `.filemerger.toml`.

## Symlinks

Symlinks are not followed by default.

Enable symlink traversal explicitly:

```bash
filemerger . --follow-symlinks
```

Symlink traversal is opt-in to avoid unexpected traversal and potential
directory-loop problems.

## Design Goals

FileMerger is designed around a few core principles:

* **Deterministic output** — identical inputs produce predictable ordering.
* **AI-first formatting** — Markdown, JSON, LLM, and AI-marker formats are
  first-class output modes.
* **Safe by default** — secrets are redacted, binaries are skipped, and
  symlinks are not followed unless explicitly enabled.
* **Minimal configuration** — useful behavior works without a configuration
  file.
* **Predictable filtering** — extension, ignore, include, exclude, and target
  rules are applied consistently.
* **Zero project mutation** — FileMerger reads project content and generates
  output without modifying the source project.

## Links

* **Homepage:** https://gitlab.com/binaryfleet/filemerger
* **Repository:** https://gitlab.com/binaryfleet/filemerger
* **Issues:** https://gitlab.com/binaryfleet/filemerger/issues
* **Documentation:** https://docs.djangoplay.org/view#projects/filemerger/

## License

`filemerger-cli` is released under the MIT License.
