Why rename a branch and not panic

Renaming a branch is mostly administrative surgery on pointers. The commits stay where they are and history is intact. The real risk is confusion and broken automation when some poor bot or coworker still thinks the old name is sacred. This guide walks you through the safe sequence so you do not leave ghosts in the repo.

Quick checklist before you start

• Confirm you have a clean working tree with no uncommitted changes
• Decide the final branch name and any CI or PR references to update
• Plan to push the new branch before deleting the old remote branch

Step 1 verify your branch and working tree

Run these commands to avoid surprises

git status
git branch -v

If git status shows dirty changes stash or commit them first. A clean tree makes renames boring and safe.

Step 2 rename locally

If you are currently on the branch use the shorter form

git branch -m new-name

If you are on a different branch or want to be explicit use the long form

git branch -m old-name new-name

This only changes the local pointer. Commit history does not move. Nobody needs therapy.

Step 3 push the renamed branch and set tracking

Push the new branch to the remote. You can set upstream in one command so future push and pull are normal

git push -u origin new-name

If you prefer two steps run git push origin new-name first and then git push -u origin new-name to set tracking. If the push fails check permissions and remote branch protection rules.

Step 4 remove the old branch from the remote

Once the new branch is safely on the remote delete the old pointer so the branch list is not full of fossils

git push origin --delete old-name

You can also remove the old branch from the hosting web UI if you prefer clicking instead of typing. Either way remove the stale reference so other people do not keep opening PRs against a dead name.

Step 5 tell your team and update automation

Let collaborators fetch and prune so local lists match the server

git fetch --prune
# or to be thorough
git fetch --all --prune

Advise anyone who had the old branch checked out to either rename their local branch or check out the new one. For example

git checkout new-name
# or to rename a local copy
git branch -m old-name new-name

Update CI configuration, open pull requests and any scripts that referenced the old branch name. If a PR was open update its source branch on the hosting site if needed.

Verification tips

• Use git branch -vv to confirm the new branch tracks origin new-name
• Run git remote show origin to see remote branches and tracking info
• Check your CI and PR pages to confirm builds and references are healthy

Common pitfalls and how to avoid them

• Do not delete the remote branch before pushing the new one unless you enjoy drama
• Branch protection rules can block creating a new branch. Check settings if a push fails
• Remind reviewers that the PR source branch name changed so they do not approve the wrong thing

Quick cheat sheet

# verify
git status
git branch -v

# rename locally when on the branch
git branch -m new-name

# rename from another branch
git branch -m old-name new-name

# push and set upstream
git push -u origin new-name

# delete old remote branch
git push origin --delete old-name

# have everyone clean up
git fetch --prune

Rename operations are boring when done in the right order and painful when done in a hurry. Follow this sequence, announce the change, and your repo will stay tidy and slightly less haunted.