How to Migrate from Master to Main Branch

This guide walks you through safely migrating an existing Git repository from the master branch to main branch, covering both local repositories and server repositories.

Why Migrate?

Modern Standard: main is now the default branch name for new repositories
Consistency: Align with current industry practices and GitHub/GitLab defaults

Before You Start

⚠️ IMPORTANT: This process affects all users of the repository. Coordinate with your team!

Prerequisites Checklist

[ ] Notify all team members about the migration
[ ] Ensure all team members have pushed their latest changes
[ ] Have backup of the repository (just in case)
[ ] Administrator access to the Git server
[ ] Update any CI/CD scripts that reference master

Step-by-Step Migration Process

Step 1: Prepare the Local Repository

Switch to master and get latest changes:

git checkout master
git pull origin master

Check repository status:

git status                    # Should be clean
git log --oneline -5         # Verify recent commits
git branch -a                # See all branches

Step 2: Rename Local Branch

Rename master to main:
```
git branch -m master main
```

Verify the rename:

git branch                   # Should show 'main' with asterisk
git log --oneline -3         # Verify history is intact

Step 3: Update Server Repository

Option A: If You Have Server Access

On the Git server (e.g., git@devel):

# Navigate to the bare repository
cd /path/to/repos/build-cert.git

# Change the default branch pointer
git symbolic-ref HEAD refs/heads/main

# Verify the change
git symbolic-ref HEAD        # Should show 'refs/heads/main'

Option B: Using Git Commands from Client

Push the new main branch:
```
git push -u origin main
```

On the server, change default branch:

# SSH to server
ssh git@devel
cd build-cert.git
git symbolic-ref HEAD refs/heads/main

Step 4: Update Remote Tracking

Set main as upstream:
```
git push -u origin main
```

Verify remote tracking:

git branch -vv               # Should show main tracking origin/main

Step 5: Clean Up Old Master Branch

⚠️ Wait until all team members have migrated before deleting master!

Delete remote master branch:
```
git push origin --delete master
```
Clean up remote tracking references:
```
git remote prune origin
```

Verify cleanup:

git branch -a               # Should not show origin/master
git ls-remote --heads origin # Should only show main

Team Member Migration

Once the server migration is complete, each team member needs to update their local repository:

For Team Members

Fetch latest changes:
```
git fetch origin
```

Switch to new main branch:

git checkout main           # Switch to new main
# OR if main doesn't exist locally:
git checkout -b main origin/main

Delete old local master:

git branch -d master        # Delete local master branch

Clean up tracking references:

git remote prune origin     # Remove stale remote references

Verify the migration:

git branch -a               # Should show main, not master
git status                  # Should show "On branch main"

Real Example: Your build-cert Repository

Based on your current setup, here’s the specific migration for your repository:

Current State Analysis

From your git config --list output, I can see:

Local branch: master
Remote tracking: branch.master.remote=origin and branch.master.merge=refs/heads/master
Server: git@devel:build-cert.git still uses master

Your Migration Steps

Prepare your local repository:

cd /home/billf/devel/build-cert
git checkout master
git pull origin master      # Get latest changes

Rename your local branch:
```
git branch -m master main
```
Push new main branch:
```
git push -u origin main
```

Update server default branch:

# SSH to your server
ssh git@devel
cd build-cert.git
git symbolic-ref HEAD refs/heads/main
exit

Delete old master branch:

git push origin --delete master
git remote prune origin

Verify migration:

git branch -vv              # Should show: * main [origin/main]
git config --list | grep branch  # Should show main, not master

Updating References in Files

After migration, update any files that reference the old branch:

Common Files to Check

Documentation files:
- README.md
- HOW-TO-VERSION.md (update examples)
- Any deployment scripts

Your HOW-TO-VERSION.md needs updates:

# Change references from:
git push origin master
git checkout master

# To:
git push origin main
git checkout main

CI/CD configurations:
- Check any automated scripts
- Update deployment triggers

Troubleshooting

Problem: “fatal: A branch named ‘main’ already exists”

# Check what's in main
git log main --oneline -5

# If main is outdated, delete it first
git branch -D main

# Then retry the rename
git branch -m master main

Problem: Team Member Gets “branch ‘master’ not found”

# Team member should fetch and switch to main
git fetch origin
git checkout -b main origin/main
git branch -d master  # Delete old local master

Problem: Server Won’t Let You Delete Master

# Some servers protect default branches
# First change default branch, then delete:
ssh git@devel
cd build-cert.git
git symbolic-ref HEAD refs/heads/main
git branch -d master  # Now you can delete it

Problem: References Still Point to Master

# Clean up all references
git remote prune origin
git fetch origin

# Check what references exist
git ls-remote origin
git branch -a

Post-Migration Checklist

[ ] Local repository uses main branch
[ ] Server default branch is main
[ ] Old master branch deleted from server
[ ] All team members have migrated
[ ] Documentation updated to reference main
[ ] CI/CD scripts updated
[ ] Any external integrations updated

Rollback Plan (Just in Case)

If something goes wrong, you can rollback:

Recreate master branch:

git checkout -b master main
git push -u origin master

Update server default:

ssh git@devel
cd build-cert.git
git symbolic-ref HEAD refs/heads/master

Delete main branch:

git push origin --delete main
git branch -d main

Benefits After Migration

✅ Consistency: New repositories automatically use main
✅ Modern Standard: Aligned with industry practices
✅ Team Clarity: Everyone uses the same branch naming
✅ Future-Proof: Ready for modern Git workflows

Remember: Take your time with this migration and coordinate with your team. The benefits are worth the careful planning!