git-rewrite 0.5.0__py3-none-any.whl

git_rewrite/cli.py

@@ -0,0 +1,415 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   cli.py
+#   ──────
+#
+#   Main CLI for git-rewrite with subcommand dispatch.
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Jan 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Imports
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+import sys
+import traceback
+from pathlib import Path
+from .argbuilder import ArgsParser
+from .argbuilder import Namespace
+from .version import VERSION_STR
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Descriptions
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+SCAN_DESCRIPTION = """\
+Scan a git repository for sensitive words without modifying anything.
+
+This command streams through all commits and blobs using git fast-export,
+searching for occurrences of words defined in your config file.
+Use this to audit a repository before sanitising it.
+
+The config file should be JSON with a "words" array:
+  {"words": ["secretword", "internalname"]}
+
+Example:
+  git-rewrite scan -r ./my-repo -c dirty-words.json
+  git-rewrite scan -r ./my-repo -c dirty-words.json -v  # verbose
+"""
+
+SANITISE_DESCRIPTION = """\
+Rewrite git history to remove or replace sensitive words.
+
+Creates a NEW repository with sanitised history. The original is never modified.
+Uses git fast-export/fast-import for efficient streaming.
+
+Features:
+  - Replace words in file contents, commit messages, author/committer names
+  - Map specific words to specific replacements (or use default "REDACTED")
+  - Map author names to specific email addresses
+  - Exclude specific files from the output (e.g., lock files)
+  - Remap submodule commit references if you've sanitised submodules too
+
+Config file (JSON):
+  - words: list of words to find/replace
+  - word_mapping: dict mapping words to replacements
+  - email_mapping: dict mapping author names to emails
+  - exclude_files: list of files to exclude
+
+Example:
+  git-rewrite sanitise -r ./dirty-repo -o ./clean-repo -c config.json
+  git-rewrite sanitise --sample-config  # print example config
+"""
+
+FLATTEN_DESCRIPTION = """\
+Flatten submodules by inlining their contents into the main repository.
+
+Creates a NEW repository where submodule references (gitlinks) are replaced
+with the actual file contents from those submodules at each commit.
+Useful for merging submodule history into a monorepo.
+
+The command will:
+  1. Scan history to find all submodule paths and URLs
+  2. Clone or use existing checkouts of submodule repositories
+  3. Stream history, replacing gitlinks with actual file trees
+  4. Write a commit mapping file (old SHA -> new SHA)
+
+Use --scan-only to just list submodules without flattening.
+
+Example:
+  git-rewrite flatten -r ./repo-with-submodules -o ./flat-repo
+  git-rewrite flatten -r ./repo --scan-only  # list submodules
+"""
+
+REMAP_DESCRIPTION = """\
+Remap submodule commit references using a mapping file.
+
+When you sanitise or rewrite a submodule repository, its commit SHAs change.
+If you have a parent repository that references those submodules, the gitlink
+references become invalid. This command updates those references.
+
+The mapping file format is: old_sha new_sha (one per line)
+This is the output from a previous sanitise operation.
+
+Optionally rewrite submodule URLs in .gitmodules with --url-rewrite.
+
+Example:
+  git-rewrite remap -r ./parent -o ./remapped -m mapping.txt
+  git-rewrite remap -r ./repo -o ./out -m map.txt \\
+      --url-rewrite ../old-submodule.git ../new-submodule.git
+"""
+
+COMPOSE_DESCRIPTION = """\
+Compose multiple commit mapping files into one.
+
+When chaining operations (e.g., flatten -> sanitise), each produces a mapping
+file. This command composes them: given A->B and B->C mappings, produces A->C.
+
+Mapping files are processed in order, following the chain of transformations.
+The format is: old_sha new_sha (one per line).
+
+Example:
+  git-rewrite compose -m flatten.txt -m sanitise.txt -o combined.txt
+  git-rewrite compose -m a.txt -m b.txt -m c.txt -o final.txt
+"""
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Argument Parsing
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def create_parser() -> ArgsParser:
+    """Create the main argument parser with subcommands."""
+    parser = ArgsParser(
+        prog="git-rewrite",
+        description=(
+            "Git history rewriting tools for sanitising, flattening, and remapping."
+        ),
+        version=f"git-rewrite {VERSION_STR}",
+    )
+
+    # =========== Common Options ===========
+
+    common = parser.create_common_collection()
+    common.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show verbose output",
+    )
+
+    # =========== Scan Command ===========
+
+    scan_cmd = parser.add_command(
+        "scan",
+        help="Scan repository for sensitive words (read-only)",
+        description=SCAN_DESCRIPTION,
+    )
+    scan_cmd.add_argument(
+        "-r",
+        "--repo",
+        type=Path,
+        required=True,
+        help="Path to the git repository",
+    )
+    scan_cmd.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        required=True,
+        help="Path to JSON config file",
+    )
+
+    # =========== Sanitise Command ===========
+
+    sanitise_cmd = parser.add_command(
+        "sanitise",
+        help="Rewrite history to remove sensitive words",
+        description=SANITISE_DESCRIPTION,
+    )
+    sanitise_cmd.add_argument(
+        "--sample-config",
+        action="store_true",
+        help="Print sample config and exit",
+    )
+    sanitise_cmd.add_argument(
+        "-r",
+        "--repo",
+        type=Path,
+        help="Path to source repository",
+    )
+    sanitise_cmd.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Path for output repository",
+    )
+    sanitise_cmd.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        help="Path to JSON config file",
+    )
+    sanitise_cmd.add_argument(
+        "--delete",
+        action="store_true",
+        help="Delete output directory if exists",
+    )
+    sanitise_cmd.add_argument(
+        "-d",
+        "--default",
+        default="REDACTED",
+        help="Default replacement word (default: REDACTED)",
+    )
+    sanitise_cmd.add_argument(
+        "-m",
+        "--commit-map",
+        type=Path,
+        help="Path to write commit mapping file",
+    )
+    sanitise_cmd.add_argument(
+        "-s",
+        "--submodule-map",
+        type=Path,
+        help="Path to submodule commit mapping file",
+    )
+    sanitise_cmd.add_argument(
+        "--copy-remotes",
+        action="store_true",
+        help="Copy git remotes from source to output repository",
+    )
+
+    # =========== Flatten Command ===========
+
+    flatten_cmd = parser.add_command(
+        "flatten",
+        help="Flatten submodules into main repository",
+        description=FLATTEN_DESCRIPTION,
+    )
+    flatten_cmd.add_argument(
+        "-r",
+        "--repo",
+        type=Path,
+        required=True,
+        help="Path to source repository",
+    )
+    flatten_cmd.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Path for output repository",
+    )
+    flatten_cmd.add_argument(
+        "-m",
+        "--commit-map",
+        type=Path,
+        help="Path to write commit mapping file",
+    )
+    flatten_cmd.add_argument(
+        "--delete",
+        action="store_true",
+        help="Delete output directory if exists",
+    )
+    flatten_cmd.add_argument(
+        "--scan-only",
+        action="store_true",
+        help="Only scan and list submodules",
+    )
+    flatten_cmd.add_argument(
+        "--copy-remotes",
+        action="store_true",
+        help="Copy git remotes from source to output repository",
+    )
+
+    # =========== Remap Command ===========
+
+    remap_cmd = parser.add_command(
+        "remap",
+        help="Remap submodule commit references",
+        description=REMAP_DESCRIPTION,
+    )
+    remap_cmd.add_argument(
+        "-r",
+        "--repo",
+        type=Path,
+        required=True,
+        help="Path to source repository",
+    )
+    remap_cmd.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        required=True,
+        help="Path for output repository",
+    )
+    remap_cmd.add_argument(
+        "-m",
+        "--commit-map",
+        type=Path,
+        required=True,
+        help="Path to commit mapping file (old_sha new_sha per line)",
+    )
+    remap_cmd.add_argument(
+        "--submodule-path",
+        type=str,
+        help="Specific submodule path to remap (for gitlink filtering)",
+    )
+    remap_cmd.add_argument(
+        "--url-rewrite",
+        nargs=2,
+        action="append",
+        metavar=("OLD_URL", "NEW_URL"),
+        help="Rewrite URL in .gitmodules (can be specified multiple times)",
+    )
+    remap_cmd.add_argument(
+        "--delete",
+        action="store_true",
+        help="Delete output directory if exists",
+    )
+    remap_cmd.add_argument(
+        "--copy-remotes",
+        action="store_true",
+        help="Copy git remotes from source to output repository",
+    )
+
+    # =========== Compose Command ===========
+
+    compose_cmd = parser.add_command(
+        "compose",
+        help="Compose multiple commit mapping files",
+        description=COMPOSE_DESCRIPTION,
+    )
+    compose_cmd.add_argument(
+        "-m",
+        "--mapping",
+        type=Path,
+        action="append",
+        dest="mappings",
+        required=True,
+        help="Mapping file to include (can be specified multiple times, in order)",
+    )
+    compose_cmd.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        required=True,
+        help="Path for output mapping file",
+    )
+
+    return parser
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Main Entry Point
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def main(argv: list[str] | None = None) -> int:
+    """
+    Main entry point for git-rewrite CLI.
+
+    Parameters:
+        argv: Command line arguments (without program name). If None, uses sys.argv[1:].
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    try:
+        return _main_inner(argv)
+    except KeyboardInterrupt:
+        print()
+        print("---- Manually Terminated ----")
+        print()
+        return 1
+    except SystemExit:
+        raise
+    except BaseException as e:
+        t = "-----------------------------------------------------------------------------\n"
+        t += "UNHANDLED EXCEPTION OCCURRED!!\n"
+        t += "\n"
+        t += traceback.format_exc()
+        t += "\n"
+        t += f"EXCEPTION: {type(e)} {e}\n"
+        t += "-----------------------------------------------------------------------------\n"
+        t += "\n"
+        print(t, file=sys.stderr)
+        return 1
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def _main_inner(argv: list[str]) -> int:
+    """Inner main function that does the actual work."""
+    from . import compose
+    from . import flatten
+    from . import remap
+    from . import sanitise
+    from . import scan
+
+    parser = create_parser()
+    args: Namespace = parser.parse(argv)
+
+    if not args.command:
+        return 0  # Help was shown by ArgsParser
+
+    commands = {
+        "scan": scan.run,
+        "sanitise": sanitise.run,
+        "flatten": flatten.run,
+        "remap": remap.run,
+        "compose": compose.run,
+    }
+
+    return commands[args.command](args)

git_rewrite/common/__init__.py

@@ -0,0 +1,103 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   common/__init__.py
+#   ───────────────────
+#
+#   Common utilities for git-rewrite.
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Jan 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+from .config import BLOB_MODE
+from .config import EXEC_MODE
+from .config import GITLINK_MODE
+from .config import TREE_MODE
+from .config import CommitInfo
+from .config import SubmoduleInfo
+from .config import TreeEntry
+from .repo import clone_repo
+from .repo import commit_tree
+from .repo import copy_remotes
+from .repo import get_all_branches
+from .repo import get_all_commits
+from .repo import get_all_tags
+from .repo import get_branch_commit
+from .repo import get_commit_info
+from .repo import get_gitmodules_at_commit
+from .repo import get_remotes
+from .repo import get_tag_commit
+from .repo import get_tree_sha
+from .repo import git
+from .repo import git_bytes
+from .repo import hash_object
+from .repo import init_repo
+from .repo import ls_tree
+from .repo import mktree
+from .repo import object_exists
+from .repo import parse_gitmodules
+from .repo import read_blob
+from .repo import update_ref
+from .stream import COMMIT_PATTERN
+from .stream import D_PATTERN
+from .stream import FROM_PATTERN
+from .stream import M_PATTERN
+from .stream import MARK_PATTERN
+from .stream import MERGE_PATTERN
+from .stream import checkout_default_branch
+from .stream import create_stream_writer
+from .stream import finalise_stream
+from .stream import start_fast_export
+from .stream import start_fast_import
+
+__all__ = [
+    # config
+    "GITLINK_MODE",
+    "TREE_MODE",
+    "BLOB_MODE",
+    "EXEC_MODE",
+    "SubmoduleInfo",
+    "CommitInfo",
+    "TreeEntry",
+    # repo
+    "git",
+    "git_bytes",
+    "init_repo",
+    "clone_repo",
+    "get_all_branches",
+    "get_all_tags",
+    "get_tag_commit",
+    "get_all_commits",
+    "get_commit_info",
+    "get_branch_commit",
+    "ls_tree",
+    "read_blob",
+    "get_tree_sha",
+    "mktree",
+    "hash_object",
+    "commit_tree",
+    "update_ref",
+    "get_gitmodules_at_commit",
+    "parse_gitmodules",
+    "object_exists",
+    "get_remotes",
+    "copy_remotes",
+    # stream
+    "MARK_PATTERN",
+    "COMMIT_PATTERN",
+    "FROM_PATTERN",
+    "MERGE_PATTERN",
+    "M_PATTERN",
+    "D_PATTERN",
+    "start_fast_export",
+    "start_fast_import",
+    "create_stream_writer",
+    "finalise_stream",
+    "checkout_default_branch",
+]

git_rewrite/common/config.py

@@ -0,0 +1,65 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   config.py
+#   ─────────
+#
+#   Shared configuration types and constants for git-rewrite.
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Jan 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Imports
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+from typing import TypedDict
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Constants
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+GITLINK_MODE = "160000"
+TREE_MODE = "040000"
+BLOB_MODE = "100644"
+EXEC_MODE = "100755"
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Types
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+class SubmoduleInfo(TypedDict):
+    """Information about a submodule from .gitmodules."""
+
+    path: str
+    url: str
+
+
+class CommitInfo(TypedDict):
+    """Information about a git commit."""
+
+    tree: str
+    parents: list[str]
+    author_name: str
+    author_email: str
+    author_date: str
+    committer_name: str
+    committer_email: str
+    committer_date: str
+    message: str
+
+
+class TreeEntry(TypedDict):
+    """A single entry in a git tree."""
+
+    mode: str
+    type: str
+    sha: str
+    name: str