git-rewrite

Git history rewriting tools - sanitise, flatten submodules, and remap references.

Installation

uv sync

Usage

Scan for Sensitive Words

Scan a repository for dirty words without making any changes:

uv run git-rewrite scan -r /path/to/repo -c config.json

Options:

• -r, --repo - Path to the git repository
• -c, --config - Path to JSON config file
• -v, --verbose - Show verbose output

Sanitise Repository

Rewrite history to remove sensitive words:

uv run git-rewrite sanitise -r /path/to/repo -o /path/to/output -c config.json

Options:

• -r, --repo - Path to source repository
• -o, --output - Path for output repository
• -c, --config - Path to JSON config file
• -d, --default - Default replacement word (default: placeholder)
• -m, --commit-map - Path to write commit mapping file
• -s, --submodule-map - Path to submodule commit mapping file
• --delete - Delete output directory if exists
• --sample-config - Print sample config and exit
• -v, --verbose - Show verbose output

Sample Configuration

{
    "words": ["secretword", "internalname", "sensitiveid"],
    "word_mapping": {
        "secretword": "publicword",
        "internalname": "externalname"
    },
    "email_mapping": {
        "john smith": "jsmith@example.com",
        "jane doe": "jdoe@example.com"
    },
    "exclude_files": [
        "package-lock.json",
        "yarn.lock"
    ]
}

Flatten Submodules

Flatten submodules into the main repository:

# Scan for submodules only
uv run git-rewrite flatten -r /path/to/repo --scan-only

# Flatten submodules
uv run git-rewrite flatten -r /path/to/repo -o /path/to/output

Options:

• -r, --repo - Path to source repository
• -o, --output - Path for output repository
• -m, --commit-map - Path to write commit mapping file
• --scan-only - Only scan and list submodules
• --delete - Delete output directory if exists
• -v, --verbose - Show verbose output

Remap Submodule References

Update submodule commit references in a repository:

uv run git-rewrite remap -r /path/to/repo -o /path/to/output -m mapping.txt

Options:

• -r, --repo - Path to source repository
• -o, --output - Path for output repository
• -m, --commit-map - Path to commit mapping file
• --submodule-path - Specific submodule path to remap
• --url-rewrite OLD NEW - Rewrite URL in .gitmodules (can repeat)
• --delete - Delete output directory if exists
• -v, --verbose - Show verbose output

Workflow Example

A typical workflow for cleaning up and flattening a repository:

# 1. Scan for sensitive words
uv run git-rewrite scan -r ./myrepo -c dirty-words.json

# 2. Sanitise the repository
uv run git-rewrite sanitise -r ./myrepo -o ./myrepo-clean -c dirty-words.json \
    -m commit-map.txt

# 3. Flatten submodules in the cleaned repo
uv run git-rewrite flatten -r ./myrepo-clean -o ./myrepo-flat -m submodule-map.txt

# 4. Update consumer repositories to use new submodule commits
uv run git-rewrite remap -r ./consumer-repo -o ./consumer-updated \
    -m submodule-map.txt --submodule-path libs/mylib

Development

# Set up development environment
make dev

# Run linting and type checking
make check

# Auto-format code
make format

# Build wheel and docs
make build

Publishing

Publishing requires cal-publish-python configuration. See the cal-publish-python documentation for setup.

# Build first
make build

# Publish wheel to PyPI and docs to GitLab Pages
make publish

Requirements

• Python 3.12+
• Git

Licence

MIT