filemerger-cli 0.3.0__py3-none-any.whl

filemerger/__init__.py

@@ -0,0 +1,4 @@
+__all__ = [
+    "collect_files",
+    "merge_files",
+]

filemerger/cli.py

@@ -0,0 +1,83 @@
+import argparse
+import sys
+import os
+
+from .core import collect_files, merge_files
+from .utils import normalize_output_filename
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Consolidate project files into a single text output"
+    )
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        help="Files or directories to include"
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="Output file name (always saved as .txt)"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show files that would be included without writing output"
+    )
+    parser.add_argument(
+        "--stats",
+        action="store_true",
+        help="Print merge statistics"
+    )
+    parser.add_argument(
+        "--llm",
+        action="store_true",
+        help="Optimize output for LLM context ingestion"
+    )
+    parser.add_argument(
+        "--llm-compact",
+        action="store_true",
+        help="More compact LLM output with fewer blank lines"
+    )
+
+    args = parser.parse_args()
+
+    if args.llm_compact:
+        args.llm = True
+
+    output_file = normalize_output_filename(args.output)
+    output_file = os.path.join(os.getcwd(), output_file)
+
+    files = collect_files(args.paths, output_file=output_file)
+
+    if not files:
+        print("No valid files found.")
+        sys.exit(2)
+
+    if args.dry_run:
+        print("Files to be included:")
+        for f in files:
+            print(f" - {f}")
+
+        if args.stats:
+            print("\nStats:")
+            print(f"  Files: {len(files)}")
+        sys.exit(0)
+
+    stats = merge_files(
+        files,
+        output_file,
+        llm_mode=args.llm,
+        llm_compact=args.llm_compact,
+    )
+
+    print(f"✔ Merged {stats.files} files into {output_file}")
+
+    if args.stats:
+        print("\nStats:")
+        print(f"  Files: {stats.files}")
+        print(f"  Lines: {stats.lines}")
+        print(f"  Bytes: {stats.bytes}")
+        print(f"  Skipped files: {stats.skipped_files}")
+
+if __name__ == "__main__":
+    main()

filemerger/config.py

@@ -0,0 +1,28 @@
+ALLOWED_EXTENSIONS = {
+    ".py", ".js", ".json", ".html", ".css", ".txt", ".md"
+}
+
+EXCLUDED_FILES = {
+    ".DS_Store",
+}
+
+EXCLUDED_DIRECTORIES = {
+    "__pycache__",
+    ".git",
+    ".idea",
+    ".vscode",
+    "node_modules",
+    "migrations",
+    "tests",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "env",
+    ".env",
+    ".venv",
+}
+
+DEFAULT_SEPARATOR_LENGTH = 90
+MAX_FILE_SIZE_MB = 2
+
+DEFAULT_OUTPUT_FILE = "filemerger-output.txt"

filemerger/core.py

@@ -0,0 +1,69 @@
+import os
+from typing import List, Set
+from .filters import is_allowed_file
+from .gitignore import load_gitignore
+from .user_config import load_user_config
+from .config import EXCLUDED_DIRECTORIES, MAX_FILE_SIZE_MB
+from .format_default import DefaultFormatter
+from .format_llm import LLMFormatter
+from .stats import MergeStats
+
+def collect_files(
+    paths: List[str],
+    *,
+    output_file: str | None = None,
+) -> List[str]:
+    collected: Set[str] = set()
+    root = os.getcwd()
+
+    gitignore_spec = load_gitignore(root)
+    user_config = load_user_config()
+
+    max_mb = user_config.get("filters", {}).get("max_file_size_mb", MAX_FILE_SIZE_MB)
+    excluded_dirs = set(EXCLUDED_DIRECTORIES)
+    excluded_dirs.update(
+        user_config.get("filters", {}).get("exclude_dirs", [])
+    )
+
+    max_file_size_bytes = int(max_mb * 1024 * 1024)
+
+    for path in paths:
+        if os.path.isfile(path) and is_allowed_file(
+            path,
+            output_file=output_file,
+            gitignore_spec=gitignore_spec,
+            root=root,
+            max_file_size_bytes=max_file_size_bytes,
+            excluded_dirs=excluded_dirs,
+        ):
+            collected.add(os.path.abspath(path))
+
+        elif os.path.isdir(path):
+            for current_root, _, files in os.walk(path):
+                for name in sorted(files):
+                    full_path = os.path.join(current_root, name)
+                    if is_allowed_file(
+                        full_path,
+                        output_file=output_file,
+                        gitignore_spec=gitignore_spec,
+                        root=root,
+                        max_file_size_bytes=max_file_size_bytes,
+                        excluded_dirs=excluded_dirs,
+                    ):
+                        collected.add(os.path.abspath(full_path))
+
+    return sorted(collected)
+
+def merge_files(
+    files: List[str],
+    output_file: str,
+    *,
+    llm_mode: bool = False,
+    llm_compact: bool = False,
+) -> MergeStats:
+    if llm_mode or llm_compact:
+        formatter = LLMFormatter(compact=llm_compact)
+    else:
+        formatter = DefaultFormatter()
+
+    return formatter.write(files, output_file)

filemerger/filters.py

@@ -0,0 +1,37 @@
+import os
+from .gitignore import is_ignored
+
+def is_allowed_file(
+    path: str,
+    *,
+    output_file: str | None = None,
+    gitignore_spec=None,
+    root: str | None = None,
+    max_file_size_bytes: int,
+    excluded_dirs: set[str],
+) -> bool:
+    if not os.path.isfile(path):
+        return False
+
+    if output_file and os.path.abspath(path) == os.path.abspath(output_file):
+        return False
+
+    if gitignore_spec and root and is_ignored(path, root=root, spec=gitignore_spec):
+        return False
+
+    if os.path.splitext(path)[1].lower() not in {
+        ".py", ".js", ".json", ".html", ".css", ".txt", ".md"
+    }:
+        return False
+
+    parts = path.split(os.sep)
+    if any(part in excluded_dirs for part in parts):
+        return False
+
+    try:
+        if os.path.getsize(path) > max_file_size_bytes:
+            return False
+    except OSError:
+        return False
+
+    return True

filemerger/format_default.py

@@ -0,0 +1,53 @@
+from typing import List
+from .stats import MergeStats
+from .user_config import load_user_config
+from .config import DEFAULT_SEPARATOR_LENGTH
+
+class DefaultFormatter:
+    def write(self, files: List[str], output_file: str) -> MergeStats:
+        user_config = load_user_config()
+        sep_len = user_config.get("output", {}).get(
+            "separator_length", DEFAULT_SEPARATOR_LENGTH
+        )
+        separator = "-" * int(sep_len)
+
+        stats = MergeStats(files=len(files))
+
+        with open(output_file, "w", encoding="utf-8") as out:
+            header = "FILES INCLUDED\n" + separator + "\n"
+            out.write(header)
+            stats.lines += header.count("\n")
+            stats.bytes += len(header.encode("utf-8"))
+
+            for f in files:
+                line = f"{f}\n"
+                out.write(line)
+                stats.lines += 1
+                stats.bytes += len(line.encode("utf-8"))
+
+            out.write("\n")
+            stats.lines += 1
+            stats.bytes += 1
+
+            for file_path in files:
+                block_header = (
+                    f"{separator}\nFILE: {file_path}\n{separator}\n"
+                )
+                out.write(block_header)
+                stats.lines += block_header.count("\n")
+                stats.bytes += len(block_header.encode("utf-8"))
+
+                try:
+                    with open(file_path, "r", encoding="utf-8") as f:
+                        content = f.read().rstrip() + "\n"
+                        out.write(content)
+                        stats.lines += content.count("\n")
+                        stats.bytes += len(content.encode("utf-8"))
+                except UnicodeDecodeError:
+                    skipped = "[Skipped: binary or non-UTF8 file]\n"
+                    out.write(skipped)
+                    stats.lines += 1
+                    stats.bytes += len(skipped.encode("utf-8"))
+                    stats.skipped_files += 1
+
+        return stats

filemerger/format_llm.py

@@ -0,0 +1,36 @@
+from typing import List
+from .stats import MergeStats
+
+class LLMFormatter:
+    def __init__(self, *, compact: bool = False):
+        self.compact = compact
+
+    def write(self, files: List[str], output_file: str) -> MergeStats:
+        stats = MergeStats(files=len(files))
+
+        with open(output_file, "w", encoding="utf-8") as out:
+            for idx, file_path in enumerate(files, start=1):
+                header = f"[{idx}] {file_path}\n"
+                out.write(header)
+                stats.lines += 1
+                stats.bytes += len(header.encode("utf-8"))
+
+                try:
+                    with open(file_path, "r", encoding="utf-8") as f:
+                        content = f.read().rstrip() + ("\n" if self.compact else "\n\n")
+                        out.write(content)
+                        stats.lines += content.count("\n")
+                        stats.bytes += len(content.encode("utf-8"))
+                except UnicodeDecodeError:
+                    skipped = "[Skipped: binary or non-UTF8 file]\n"
+                    out.write(skipped)
+                    stats.lines += 1
+                    stats.bytes += len(skipped.encode("utf-8"))
+                    stats.skipped_files += 1
+
+                if not self.compact:
+                    out.write("\n")
+                    stats.lines += 1
+                    stats.bytes += 1
+
+        return stats

filemerger/formatter.py

@@ -0,0 +1,6 @@
+from typing import List
+from .stats import MergeStats
+
+class BaseFormatter:
+    def write(self, files: List[str], output_file: str) -> MergeStats:
+        raise NotImplementedError

filemerger/gitignore.py

@@ -0,0 +1,29 @@
+import os
+import pathspec
+from typing import Optional
+
+def load_gitignore(root: str) -> Optional[pathspec.PathSpec]:
+    """
+    Load .gitignore from the given root directory.
+    Returns None if no .gitignore exists.
+    """
+    gitignore_path = os.path.join(root, ".gitignore")
+    if not os.path.isfile(gitignore_path):
+        return None
+
+    with open(gitignore_path, "r", encoding="utf-8") as f:
+        lines = f.read().splitlines()
+
+    return pathspec.PathSpec.from_lines("gitwildmatch", lines)
+
+def is_ignored(
+    path: str,
+    *,
+    root: str,
+    spec: Optional[pathspec.PathSpec],
+) -> bool:
+    if not spec:
+        return False
+
+    rel_path = os.path.relpath(path, root)
+    return spec.match_file(rel_path)

filemerger/stats.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+@dataclass
+class MergeStats:
+    files: int = 0
+    lines: int = 0
+    bytes: int = 0
+    skipped_files: int = 0

filemerger/user_config.py

@@ -0,0 +1,15 @@
+import os
+import tomllib
+from typing import Dict, Any
+
+def load_user_config() -> Dict[str, Any]:
+    """
+    Load .filemerger.toml from the current working directory.
+    Returns empty dict if not found.
+    """
+    config_path = os.path.join(os.getcwd(), ".filemerger.toml")
+    if not os.path.isfile(config_path):
+        return {}
+
+    with open(config_path, "rb") as f:
+        return tomllib.load(f)

filemerger/utils.py

@@ -0,0 +1,20 @@
+import os
+from .config import DEFAULT_OUTPUT_FILE
+
+def normalize_output_filename(output: str | None) -> str:
+    """
+    Normalize output filename:
+    - Default to DEFAULT_OUTPUT_FILE
+    - Force .txt extension
+    - Strip directory components (always write to CWD)
+    """
+    if not output:
+        return DEFAULT_OUTPUT_FILE
+
+    base = os.path.basename(output)
+    name, ext = os.path.splitext(base)
+
+    if ext.lower() != ".txt":
+        return f"{name}.txt"
+
+    return base

filemerger_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: filemerger-cli
+Version: 0.3.0
+Summary: Developer CLI tool to consolidate project files into a single output
+Author: BinaryFleet
+License: MIT
+Project-URL: Homepage, https://github.com/binaryfleet/filemerger
+Project-URL: Repository, https://github.com/binaryfleet/filemerger
+Project-URL: Issues, https://github.com/binaryfleet/filemerger/issues
+Keywords: cli,developer-tools,file-merger,llm,code-review
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec>=0.11
+Dynamic: license-file
+
+# FileMerger
+
+**FileMerger** is a developer-focused CLI tool that consolidates project files into a
+single plain-text output.
+
+It is designed to help developers:
+- Share complete code context with AI tools (ChatGPT, Gemini, Grok, Claude, etc.)
+- Review large codebases
+- Create audit or snapshot files
+- Prepare structured input for analysis
+
+---
+
+## Installation
+
+```bash
+pip install filemerger
+```
+
+---
+
+## Basic Usage
+
+Merge a directory:
+
+```bash
+filemerger src/
+```
+
+Specify output file:
+
+```bash
+filemerger src/ --output context.txt
+```
+
+Dry run (no file written):
+
+```bash
+filemerger . --dry-run
+```
+
+---
+
+## Output Modes
+
+FileMerger supports multiple output modes depending on **who (or what)** will consume the output.
+
+### 1. Default Mode (Human-Readable)
+
+```bash
+filemerger src/
+```
+
+**Use this when:**
+
+* You want to read the output yourself
+* You are reviewing or auditing code
+* You want clear visual separation
+
+**Characteristics:**
+
+* File lists and headers
+* Visual separators
+* Structured, readable layout
+
+---
+
+### 2. LLM Mode (`--llm`)
+
+```bash
+filemerger src/ --llm
+```
+
+**Use this when:**
+
+* The output will be pasted into an AI system
+* You want deterministic file references
+* You want to reduce semantic noise
+
+**Characteristics:**
+
+* Files are numbered (`[1]`, `[2]`, …)
+* No decorative separators
+* Simple, predictable structure
+
+Example:
+
+```
+[1] path/to/file.py
+<content>
+
+[2] another/file.js
+<content>
+```
+
+---
+
+### 3. LLM Compact Mode (`--llm-compact`)
+
+```bash
+filemerger src/ --llm-compact
+```
+
+**Use this when:**
+
+* Token limits are tight
+* The project is very large
+* Maximum efficiency matters
+
+**Characteristics:**
+
+* Same structure as `--llm`
+* Fewer blank lines
+* Minimal formatting overhead
+
+---
+
+## Statistics
+
+Use `--stats` to print merge statistics:
+
+```bash
+filemerger src/ --stats
+```
+
+Reported values:
+
+* Number of files
+* Total lines
+* Total bytes
+* Skipped files (binary / non-UTF8)
+
+---
+
+## Configuration (Optional)
+
+FileMerger supports an optional `.filemerger.toml` file in the project root.
+
+Example:
+
+```toml
+[filters]
+max_file_size_mb = 1
+exclude_dirs = ["tests"]
+
+[output]
+separator_length = 60
+```
+
+If the file is not present, default behavior is used.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+See the [LICENSE](LICENSE) file for details.

filemerger_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+filemerger/__init__.py,sha256=cK_fu67VOvaz2x8vA8GjvSSl3nzPkcO0mYiNAKEN9yM,54
+filemerger/cli.py,sha256=w99HGLjAfhswfi898Vj5GKxSWqVn-H1krh_ttdUf5Go,2070
+filemerger/config.py,sha256=FdvW-aqSIlup13s19vwVlNRlhboHyKqHULZu-rSPYO8,454
+filemerger/core.py,sha256=9IWp4DInHcEGgwOVkzvoxLXulf1eXUkeyef_N7-ge70,2175
+filemerger/filters.py,sha256=8udBqIpz4Ac6n7vRf1gfH67ubXiwl7t5HS-YdchrzWI,905
+filemerger/format_default.py,sha256=O2nXiXxBNHMnLNcJEcQRFJlE-N3FGT-_cQln-3OxMr4,1964
+filemerger/format_llm.py,sha256=il1J1rzuoIni_sY3i81WnswdNkgs4QnsV5O8zh4tCkk,1391
+filemerger/formatter.py,sha256=3NL2jlabzhxUttzDYaAnL-sfQ8XCxcHcv7wuzHfcmkA,181
+filemerger/gitignore.py,sha256=P4j2c5yUmPkd5qHl9Nmj1c-TXvtgoz-j1EmDWY1H0tU,728
+filemerger/stats.py,sha256=Ot1MEDX9atkGImDIXFzPyriNe1-K42nzhYuHkEH51_Q,148
+filemerger/user_config.py,sha256=7YsojU_ArtuV6_zWMHsfgr3nu8fmMXH90fb9cbniuSI,405
+filemerger/utils.py,sha256=_mYbT2rQj9xVlQC2hgaU8p-opgx6wgS-Hz-v8pjYpDA,482
+filemerger_cli-0.3.0.dist-info/licenses/LICENSE,sha256=9SW1OrVckeEZJ2FZERYeZNW-KQlkuEfo2pDXWLnaSnI,1117
+filemerger_cli-0.3.0.dist-info/METADATA,sha256=qSAxZ3mAsVodVLxAHrZGo2UCjJ-nPieEj9d4dFhMsJs,2889
+filemerger_cli-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+filemerger_cli-0.3.0.dist-info/entry_points.txt,sha256=ZhK_MfyMXjYvYg27m09NMZMJL5hN_nzXa9HLYMRAybg,51
+filemerger_cli-0.3.0.dist-info/top_level.txt,sha256=nSw1KMXvWRdNjRMV0OaH8s78L6V-MeyKhY5SUgnKbk8,11
+filemerger_cli-0.3.0.dist-info/RECORD,,

filemerger_cli-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

filemerger_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+filemerger = filemerger.cli:main

filemerger_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+This project is licensed under the MIT License.
+
+MIT License
+
+Copyright (c) 2026 binaryfleet
+
+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.

filemerger_cli-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+filemerger