Git Identity Management and History Rewriting: Complete Guide

Table of Contents#

Overview#

Managing Git identities and rewriting history are powerful but potentially dangerous operations. This guide covers everything from basic identity configuration to advanced history rewriting techniques, with a focus on safety and best practices.

Understanding Git Identity#

How Git Identity Works#

1
graph TD
2
    A[Git Identity] --> B[Global Config]
3
    A --> C[Local Config]
4
    A --> D[Environment Variables]
5

6
    B --> E[~/.gitconfig]
7
    C --> F[.git/config]
8
    D --> G[GIT_AUTHOR_NAME<br/>GIT_AUTHOR_EMAIL]
9

10
    H[Commit] --> I[Author Info]
11
    H --> J[Committer Info]
12

13
    E --> I
14
    F --> I
15
    G --> I
16

17
    style A fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
18
    style H fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Identity Components#

Git tracks two identities for each commit:

Author: The person who originally wrote the code
Committer: The person who created the commit

Setting Up Git Identity#

Basic Configuration#

1
# Set global identity
2
git config --global user.name "Your Name"
3
git config --global user.email "your.email@example.com"
4

5
# Set repository-specific identity
6
git config user.name "Work Name"
7
git config user.email "work.email@company.com"
8

9
# Verify current configuration
10
git config --list
11
git config user.name
12
git config user.email

Multiple Identity Management#

Create a structured approach for managing multiple identities:

1
# Personal projects
2
git config --global user.personal.name "Personal Name"
3
git config --global user.personal.email "personal@email.com"
4

5
# Work projects
6
git config --global user.work.name "Work Name"
7
git config --global user.work.email "work@company.com"
8

9
# Alias for switching identities
10
git config --global alias.identity-personal '!git config user.name "$(git config user.personal.name)" && git config user.email "$(git config user.personal.email)"'
11
git config --global alias.identity-work '!git config user.name "$(git config user.work.name)" && git config user.email "$(git config user.work.email)"'

Directory-Based Configuration#

Use conditional includes for automatic identity switching:

1
[includeIf "gitdir:~/personal/"]
2
    path = ~/.gitconfig-personal
3

4
[includeIf "gitdir:~/work/"]
5
    path = ~/.gitconfig-work
6

7
# ~/.gitconfig-personal
8
[user]
9
    name = Personal Name
10
    email = personal@email.com
11

12
# ~/.gitconfig-work
13
[user]
14
    name = Work Name
15
    email = work@company.com

Rewriting Git History#

⚠️ Important Warning#

1
graph TD
2
    A[History Rewriting] --> B{Shared Repository?}
3
    B -->|Yes| C[⚠️ DANGER ZONE ⚠️]
4
    B -->|No| D[Proceed with Caution]
5

6
    C --> E[Coordinate with Team]
7
    C --> F[Backup First]
8
    C --> G[Force Push Required]
9

10
    D --> H[Local Changes Only]
11
    D --> I[Safe to Proceed]
12

13
    style C fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
14
    style E fill:#ffd43b,stroke:#fab005,stroke-width:2px
15
    style F fill:#ffd43b,stroke:#fab005,stroke-width:2px

Method 1: Using git filter-branch#

Change author information for all commits:

1
#!/bin/bash
2
# BACKUP YOUR REPOSITORY FIRST!
3
git clone --bare https://github.com/user/repo.git repo-backup
4

5
# Rewrite history
6
git filter-branch --env-filter '
7
OLD_EMAIL="old.email@example.com"
8
CORRECT_NAME="Correct Name"
9
CORRECT_EMAIL="correct.email@example.com"
10

11
if [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ]
12
then
13
    export GIT_COMMITTER_NAME="$CORRECT_NAME"
14
    export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"
15
fi
16
if [ "$GIT_AUTHOR_EMAIL" = "$OLD_EMAIL" ]
17
then
18
    export GIT_AUTHOR_NAME="$CORRECT_NAME"
19
    export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"
20
fi
21
' --tag-name-filter cat -- --branches --tags

Method 2: Using git filter-repo (Recommended)#

First, install git-filter-repo:

1
# Install via pip
2
pip install git-filter-repo
3

4
# Or download directly
5
wget https://raw.githubusercontent.com/newren/git-filter-repo/main/git-filter-repo
6
chmod +x git-filter-repo
7
sudo mv git-filter-repo /usr/local/bin/

Create a mailmap file:

1
Correct Name <correct.email@example.com> <old.email@example.com>
2
Correct Name <correct.email@example.com> Old Name <old.email@example.com>

Apply the mailmap:

1
git filter-repo --mailmap .mailmap

Method 3: Interactive Rebase (Recent Commits)#

For recent commits only:

1
# Rewrite last 5 commits
2
git rebase -i HEAD~5
3

4
# In the editor, change 'pick' to 'edit' for commits to modify
5
# For each commit:
6
git commit --amend --author="New Name <new.email@example.com>"
7
git rebase --continue

Changing All Commits to Single Author#

Complete Identity Rewrite#

1
#!/bin/bash
2
# Change ALL commits to a single author
3
git filter-branch --env-filter '
4
export GIT_COMMITTER_NAME="New Author Name"
5
export GIT_COMMITTER_EMAIL="new.author@example.com"
6
export GIT_AUTHOR_NAME="New Author Name"
7
export GIT_AUTHOR_EMAIL="new.author@example.com"
8
' --tag-name-filter cat -- --branches --tags
9

10
# Force push to remote
11
git push --force --tags origin 'refs/heads/*'

Using git filter-repo#

1
# Create a script to replace all authors
2
cat > replace-authors.py << 'EOF'
3
#!/usr/bin/env python3
4
def replace_author(commit):
5
    commit.author_name = b"New Author Name"
6
    commit.author_email = b"new.author@example.com"
7
    commit.committer_name = b"New Author Name"
8
    commit.committer_email = b"new.author@example.com"
9
EOF
10

11
# Run the filter
12
git filter-repo --commit-callback "$(cat replace-authors.py)"

Safety Measures#

Before Rewriting History#

1
graph LR
2
    A[Pre-Rewrite Checklist] --> B[Backup Repository]
3
    A --> C[Notify Team Members]
4
    A --> D[Document Changes]
5
    A --> E[Test on Clone First]
6

7
    B --> F[git clone --mirror]
8
    C --> G[Email/Slack/Meeting]
9
    D --> H[README/Wiki Update]
10
    E --> I[Verify Results]
11

12
    style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
13
    style B fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Backup Script#

1
#!/bin/bash
2
REPO_NAME=$(basename `git rev-parse --show-toplevel`)
3
BACKUP_DIR="$HOME/git-backups"
4
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
5

6
echo "Creating backup of $REPO_NAME..."
7

8
# Create backup directory
9
mkdir -p "$BACKUP_DIR"
10

11
# Clone with all refs
12
git clone --mirror . "$BACKUP_DIR/${REPO_NAME}_${TIMESTAMP}.git"
13

14
# Create a bundle for extra safety
15
git bundle create "$BACKUP_DIR/${REPO_NAME}_${TIMESTAMP}.bundle" --all
16

17
echo "Backup created at: $BACKUP_DIR"
18
echo "Mirror: ${REPO_NAME}_${TIMESTAMP}.git"
19
echo "Bundle: ${REPO_NAME}_${TIMESTAMP}.bundle"

Advanced Techniques#

Selective History Rewriting#

1
# Only change commits in specific date range
2
git filter-branch --env-filter '
3
if [ $GIT_COMMIT_DATE > "2023-01-01" ] && [ $GIT_COMMIT_DATE < "2023-12-31" ]; then
4
    export GIT_AUTHOR_NAME="New Name"
5
    export GIT_AUTHOR_EMAIL="new@email.com"
6
fi
7
' -- --all

Preserving Specific Information#

1
# Keep timestamps while changing author
2
git filter-branch --env-filter '
3
export GIT_AUTHOR_NAME="New Name"
4
export GIT_AUTHOR_EMAIL="new@email.com"
5
export GIT_COMMITTER_NAME="New Name"
6
export GIT_COMMITTER_EMAIL="new@email.com"
7
# Preserve original timestamps
8
export GIT_AUTHOR_DATE="$GIT_AUTHOR_DATE"
9
export GIT_COMMITTER_DATE="$GIT_COMMITTER_DATE"
10
' -- --all

Post-Rewrite Procedures#

Cleaning Up#

1
# Remove original refs created by filter-branch
2
git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d
3

4
# Garbage collection
5
git reflog expire --expire=now --all
6
git gc --prune=now --aggressive

Updating Remote Repository#

1
# Force push all branches
2
git push --force --all
3

4
# Force push all tags
5
git push --force --tags
6

7
# Notify team members
8
echo "Repository history has been rewritten. All team members must:"
9
echo "1. Backup their local changes"
10
echo "2. Delete their local repository"
11
echo "3. Clone fresh from remote"

Team Coordination#

Communication Template#

1
## Git History Rewrite Notice
2

3
**When**: [Date and Time]
4
**Repository**: [Repository Name]
5
**Reason**: [Explanation]
6

7
### Required Actions:
8

9
1. Push any pending commits before [deadline]
10
2. After rewrite, delete local repository
11
3. Clone fresh copy: `git clone [repo-url]`
12
4. Reapply any local changes
13

14
### Changes Made:
15

16
- [List of changes]
17

18
Contact [your-name] with questions.

Recovery Procedures#

If Something Goes Wrong#

1
# Restore from bundle
2
git clone /path/to/backup.bundle restored-repo
3

4
# Restore from mirror
5
git clone /path/to/backup.git restored-repo
6

7
# Push to overwrite remote (after verification)
8
cd restored-repo
9
git push --force --all origin
10
git push --force --tags origin

Best Practices#

Identity Management#

Use SSH keys with different emails for different services
Configure conditional includes for automatic identity switching
Verify identity before commits with git config user.email
Use signed commits for additional verification

History Rewriting#

Always backup before rewriting history
Test on a clone before applying to main repository
Coordinate with team for shared repositories
Document the process for future reference
Use git filter-repo instead of filter-branch when possible

Common Pitfalls#

Things to Avoid#

1
graph TD
2
    A[Common Mistakes] --> B[No Backup]
3
    A --> C[Wrong Email Format]
4
    A --> D[Partial Rewrite]
5
    A --> E[No Team Notice]
6

7
    B --> F[Data Loss Risk]
8
    C --> G[Invalid Commits]
9
    D --> H[Inconsistent History]
10
    E --> I[Conflicts & Confusion]
11

12
    style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
13
    style F fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
14
    style I fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px

Conclusion#

Git identity management and history rewriting are powerful features that require careful handling. Key takeaways:

Plan before acting: Always have a clear goal and backup strategy
Test thoroughly: Use clones to verify results before applying to main repository
Communicate clearly: Ensure all team members are aware of changes
Use modern tools: Prefer git-filter-repo over filter-branch
Document everything: Keep records of what was changed and why

Remember: with great power comes great responsibility. Use these techniques wisely and always prioritize data safety over convenience.