FileMerger

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

Maintained by DjangoPlay

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

pip install filemerger-cli

After installation, the filemerger command is available globally:

filemerger --help

Basic Usage

Merge a directory:

filemerger src/

Merge explicit files and directories:

filemerger src/ utils/helpers.py

Generate Markdown output:

filemerger src/ --format markdown

Print output directly to standard output:

filemerger src/ --format markdown --stdout

Preview files without generating output:

filemerger . --dry-run

Generate statistics:

filemerger src/ --stats

Targeting Files and Directories

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

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:

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

Specific files can be force-included regardless of extension:

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

Include and Exclude Patterns

Use glob patterns to explicitly include or exclude files:

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:

.git/
__pycache__/
node_modules/
migrations/
tests/

Individual exclusions can be restored:

filemerger . --allow-dir migrations,tests

or:

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:

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:

[REDACTED:SECRET]

Disable redaction only when raw content is explicitly required:

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.

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:

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

When truncation occurs, FileMerger adds a marker such as:

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

filemerger src/ --format markdown

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

LLM

Use the LLM-oriented format with:

filemerger src/ --llm

A compact variant is available:

filemerger src/ --llm-compact

AI Markers

The AI marker format provides explicit file boundaries:

filemerger src/ --ai-markers

Example structure:

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

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:

filemerger src/ --no-tree

Output Destination

By default, output is written to:

filemerger-output.txt

Specify another output name:

filemerger src/ --output merged

or:

filemerger src/ -o merged

To stream output instead of creating a file:

filemerger src/ --stdout --format markdown

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

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

Statistics

Statistics can be enabled with:

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:

filemerger src/ --verbose

Ordering

File processing is deterministic by default and sorted by path.

Alternative ordering modes are available:

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

The supported ordering modes are:

path
name
size
mtime

Configuration

FileMerger optionally supports a .filemerger.toml configuration file.

Example:

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

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

Therefore, CLI arguments always take precedence.

For example:

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:

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.