gitauth 1.1.0

A CLI tool to rewrite Git commit authors and committers

GitAuth

A powerful, production-grade CLI tool to safely rewrite Git commit authors and committers across your repository history.

Features

• 🔄 Flexible Rewriting: Change specific authors or rewrite all commits
• 🔍 Author Detection: Identify all unique authors in your repository
• 🧪 Dry Run Mode: Preview changes before applying them
• 💾 Automatic Backups: Create repository backups before rewriting
• ⚡ Two Backends: Uses git filter-repo (preferred) with git filter-branch fallback
• 🛡️ Safety First: Validates repo state and provides clear warnings
• 📝 Preserves History: Keeps commit messages, timestamps, and commit order intact
• 🌍 Cross-Platform: Works on macOS, Linux, and Windows

Installation

From PyPI

pip install gitauth

From Source

git clone https://github.com/mubashardev/gitauth.git
cd gitauth
pip install -e .

Optional: Install git-filter-repo

For best performance, install git-filter-repo:

# macOS
brew install git-filter-repo

# Linux (Debian/Ubuntu)
sudo apt-get install git-filter-repo

# Or via pip
pip install git-filter-repo

If not installed, gitauth will automatically fall back to git filter-branch.

Usage

Check Repository Authors

List all unique authors in your repository:

gitauth check

Output:

Found 3 unique authors:
  John Doe <[e-mail]>
  Jane Smith <[e-mail]>
  Old Name <[e-mail]>

Dry Run (Preview Changes)

See which commits would be changed without modifying anything:

# Preview changes for a specific email
gitauth dry-run --old-email "[e-mail]"

# Preview changes for a specific name
gitauth dry-run --old-name "Old Name"

Rewrite Specific Author

Change commits from a specific author:

# By email
gitauth rewrite --old-email "[e-mail]" --new-name "New Name" --new-email "[e-mail]"

# By name
gitauth rewrite --old-name "Old Name" --new-name "New Name" --new-email "[e-mail]"

# Both (more specific)
gitauth rewrite --old-email "[e-mail]" --old-name "Old Name" --new-name "New Name" --new-email "[e-mail]"

Rewrite All Commits

Change all commits to a new author:

gitauth rewrite --all --new-name "New Name" --new-email "[e-mail]"

Create Backup

Manually create a backup of your repository:

gitauth backup

Creates: backup-YYYYMMDD-HHMMSS.tar.gz

Push Changes

After rewriting, push to remote (use with caution!):

# Interactive confirmation
gitauth push

# Force push without confirmation
gitauth push --force

Enable Verbose Logging

Add --verbose to any command for detailed output:

gitauth rewrite --old-email "[e-mail]" --new-name "New Name" --new-email "[e-mail]" --verbose

Branch-Specific Operations

Filter operations by specific branch:

# Check authors only on main branch
gitauth check --branch main

# Preview commits from specific branch
gitauth dry-run --old-email "[e-mail]" --branch develop

# Interactive selection for a specific branch
gitauth dry-run --choose-old --branch feature/new-feature

Note: The --branch option filters which commits are analyzed and displayed. When using the rewrite command, git-filter-repo and git-filter-branch rewrite history across all branches by default (this is standard Git behavior for history rewriting tools).

⚠️ Important Warnings

History Rewriting

Rewriting Git history is a destructive operation. Before using this tool:

1. ✅ Always create a backup (or work on a clone)
2. ✅ Coordinate with your team if working on a shared repository
3. ✅ Understand the implications of force-pushing
4. ✅ Test on a branch first before affecting main/master

Force Pushing

After rewriting history, you'll need to force push:

git push --force-with-lease origin main
# or use: gitauth push --force

Warning: This will rewrite history on the remote. All collaborators must re-clone or reset their local repositories.

Examples

Example 1: Fix Personal Email

You accidentally committed with your work email and want to change it to personal:

# 1. Check current authors
gitauth check

# 2. Preview changes
gitauth dry-run --old-email "[e-mail]"

# 3. Rewrite commits
gitauth rewrite --old-email "[e-mail]" --new-name "Your Name" --new-email "[e-mail]"

# 4. Push changes
gitauth push

Example 2: Unify Multiple Identities

You committed with different names/emails and want to unify them:

# Fix first identity
gitauth rewrite --old-email "[e-mail]" --new-name "Your Name" --new-email "[e-mail]"

# Fix second identity
gitauth rewrite --old-email "[e-mail]" --new-name "Your Name" --new-email "[e-mail]"

# Push once
gitauth push

Example 3: Transfer Repository Ownership

Change all commits to a new author (e.g., transferring project ownership):

# Preview all commits
gitauth dry-run --all

# Rewrite all
gitauth rewrite --all --new-name "New Owner" --new-email "[e-mail]"

# Push
gitauth push

How It Works

1. Detection: Scans repository using git log to find commits matching criteria
2. Validation: Checks if repository is clean and valid
3. Backup: Optionally creates a compressed backup
4. Rewriting: Uses git filter-repo (fast) or git filter-branch (fallback)
5. Preservation: Maintains commit timestamps, messages, and tree structure
6. Safety: Provides dry-run mode and interactive confirmations

Project Structure

gitauth/
├── gitauth/
│   ├── __init__.py
│   ├── cli.py              # Typer CLI interface
│   └── core/
│       ├── __init__.py
│       ├── git_utils.py    # Git operations and validation
│       ├── detect.py       # Author detection
│       ├── backup.py       # Backup functionality
│       └── rewrite.py      # Rewrite logic (filter-repo/filter-branch)
├── tests/
│   ├── __init__.py
│   ├── test_git_utils.py
│   ├── test_detect.py
│   ├── test_backup.py
│   └── test_rewrite.py
├── pyproject.toml
├── README.md
└── LICENSE

Development

Setup Development Environment

git clone https://github.com/yourusername/gitauth.git
cd gitauth
pip install -e ".[dev]"

Run Tests

pytest
pytest --cov=gitauth tests/

Format Code

black gitauth tests
ruff check gitauth tests

Build Package

python -m build

Publish to PyPI

python -m twine upload dist/*

Requirements

• Python 3.8+
• Git 2.0+
• git-filter-repo (optional, recommended)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Changelog

Version 1.0.0

• Initial release
• Support for git filter-repo and git filter-branch
• Dry run mode
• Automatic backups
• Author detection
• Cross-platform support

Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Read documentation

Acknowledgments

• Inspired by GitHub's author-rewrite script
• Powered by git-filter-repo
• Built with Typer

---

Made with ❤️ by Mubashar Dev