How to Rename a Git Branch: Local & Remote Guide for Developers

Renaming a Git branch seems like a harmless cosmetic tweak until your GitHub Actions pipeline crashes because it cannot find the old reference. A simple name change breaks automated deployments immediately if you do not update the remote tracking branch correctly.

What Actually Happens When You Rename a Git Branch?

Git does not modify your code or commit history during a rename operation. A branch is simply a lightweight movable pointer resting on a specific commit hash. When you execute the rename command, Git takes that pointer and attaches a new text label to it. Your commit hashes and file structures remain identical.

The Difference Between -m and -M Flags (Case Sensitivity)

Changing feature-login to Feature-Login triggers a fatal error on Windows and macOS machines. These operating systems use case-insensitive file systems by default. Git thinks the branch name already exists and blocks the standard move command.

Use the uppercase -M flag to force the rename. This instructs Git to overwrite the existing case-insensitive match locally. Linux environments do not face this exact issue, but using the force flag guarantees the rename works smoothly across all operating systems.

How to Rename a Local Git Branch

Renaming the Current Branch

Switch to the branch you want to modify before running the command. The -m flag stands for move, reflecting exactly what Git does under the hood with your commit pointer.

git branch -m new-branch-name

Renaming a Different Local Branch

You do not need to check out a branch to change its name. Specify both names directly from your current working directory:

git branch -m old-branch-name new-branch-name

This saves time when cleaning up multiple local branches without switching context.

How to Rename a Remote Git Branch

Local renames do not automatically sync with your remote repository. You must manually remove the old reference from the server and push the new one.

Step 1: Delete the Old Remote Branch

git push origin --delete old-branch-name

This clears the obsolete name from the server and prevents teammates from accidentally pulling an outdated reference during their next fetch operation.

Step 2: Push the New Branch and Reset Upstream

git push origin -u new-branch-name

The -u flag sets the new upstream tracking connection. Future pull and push commands work seamlessly without requiring explicit remote names. Confirm everything is linked correctly:

git branch -vv

If the old upstream still appears, reset it manually:

git branch --set-upstream-to=origin/new-branch-name

Before You Rename: A Quick Checklist

Renaming a branch mid-project without a few quick checks creates more work than the rename itself saves. Before running any command, verify:

• Open pull requests? On GitHub, renaming via the UI updates PR targets automatically. On GitLab and Bitbucket, open merge requests will lose their target branch and need manual updates.
• Default branch? Renaming main or master requires platform admin access and additional steps (covered below).
• Active teammates on this branch? Let them know before pushing the delete command. Their local copies will still reference the old remote name until they run git fetch --prune.
• CI/CD hardcoded references? Run git grep "old-branch-name" -- "*.yml" before anything else.

Renaming Default Branches (main or master)

Modifying your primary repository branch requires extra steps beyond standard terminal commands. You must update the default branch setting within your hosting platform settings before pushing any local changes. Ensure you have admin permissions before attempting this, as standard contributors cannot modify the default branch setting.

Platform-Specific Renames (GitHub, GitLab, Bitbucket UI)

GitHub offers a built-in rename tool directly on the web interface. Changing the name via the GitHub UI automatically updates all open Pull Requests targeting that specific branch. GitLab and Bitbucket behave slightly differently and often require manual UI updates to re-target merge requests after a rename. Always verify open pull requests after altering branch names.

CI/CD Pipeline Impact: What to Check After a Rename

Hardcoded branch names in your configuration files will break your deployment pipelines instantly. CI/CD runners look for exact string matches to trigger builds.

Search your .github/workflows or .gitlab-ci.yml files for the old branch name:

git grep "old-branch-name" -- "*.yml"

Update any on: push: branches: triggers to reflect the new name. Failing to do this leaves your newly pushed commits without automated testing or deployment. If you use environment variables in Node.js or build scripts, check those configuration files as well.

How to Update Your Team's Local Repositories

If teammates have already pulled the old branch, they need to update their local setup after you rename it.

# Step 1: Fetch the updated remote branch list
git fetch --prune
# Step 2: Rename the local branch to match
git branch -m old-branch-name new-branch-name
# Step 3: Reset tracking to the new remote branch
git branch --set-upstream-to=origin/new-branch-name
# Step 4: Remove the old local branch if it still exists
git branch -d old-branch-name

Step 4 removes the local branch that still has the old name — without it, teammates end up with both the old and new names in git branch output, which causes confusion. The --prune flag in git fetch removes stale remote-tracking references, so the deleted old branch no longer appears in their branch list.

How to Undo a Branch Rename (Using git reflog)

Accidental renames are easily reversible. Git records every pointer movement in your local repository history.

git reflog

Find the hash from before the rename, check it out, and recreate your original branch name. This safety net means a typo in the branch name never becomes a permanent problem.

If you also need to restore the old remote branch name, push the original name back to origin and delete the new one using the same steps from the remote rename section above.