Git Rename Branch: The Local Move, the Remote Move, and the Part That Breaks CI

Renaming a local git branch is one command: git branch -m new-name. Renaming a branch that already exists on the remote is four commands, because git has no rename operation for remote refs at all — it pushes the new name, deletes the old one, and re-points your local tracking.

That asymmetry is the whole reason this trips people up. The local rename feels instant and complete, so the natural assumption is that pushing will carry it over. It does not. You end up with two branches on the remote, an open pull request pointing at the dead one, and a CI pipeline that still watches a name nobody uses.

Table of contents

• Renaming a local branch you have not pushed
• Renaming a branch that is already on the remote
• What happens to everyone else’s clone
• The things a rename quietly breaks
• Renaming the default branch
• What to do instead, sometimes
• How this fits the rest of the stack
• FAQ

Renaming a local branch you have not pushed

If the branch only exists on your machine, this is genuinely a one-liner. From the branch itself:

git branch -m corrected-name

From anywhere else, name both the old and the new:

git branch -m typo-name corrected-name

The -m flag is for move, which is what a rename actually is — git is renaming a file in .git/refs/heads. Use -M (capital) to force the rename when a branch with the target name already exists. That overwrites the existing branch, so check first with git branch —list corrected-name rather than reaching for -M out of habit.

Nothing else changes. Your commits, your working tree, your stash, and your reflog are all untouched. A branch in git is a pointer to a commit, and renaming it moves the label, not the history.

Renaming a branch that is already on the remote

This is the sequence that actually matters. There are four steps and skipping any one of them leaves something broken.

1. Rename it locally: git branch -m old-name new-name
2. Push the new name and set upstream: git push origin -u new-name
3. Delete the old remote branch: git push origin --delete old-name
4. Clean up stale remote-tracking refs on every other clone: git fetch --prune

Step 2 and step 3 are separate pushes because there is no atomic rename in the git wire protocol. For the window between them, both names exist on the remote pointing at the same commit. That is harmless for a few seconds and genuinely awkward if you stop halfway and go to lunch.

The -u in step 2 is the part people drop. Without it your local branch still tracks origin/old-name, which you are about to delete, and the next git pull fails with a message about no upstream. Set it in the same command and the problem never appears.

What happens to everyone else’s clone

Nothing, until they fetch. And when they do fetch, git does not tell them a branch was renamed — it tells them one branch appeared and another vanished. Those look identical to a branch being deleted and an unrelated one being created.

Anyone who had the old branch checked out ends up on a local branch tracking a remote ref that no longer exists. Their fix:

git branch -m old-name new-name
git fetch origin
git branch -u origin/new-name new-name
git remote set-head origin -a

That last line updates what origin/HEAD points at, which only matters if you renamed the default branch. It is cheap to run and confusing to debug when it is missing, so include it.

If the team is more than about three people, send the four lines in a message rather than expecting everyone to derive them. This is the one part of a branch rename that reliably costs somebody an afternoon.

The things a rename quietly breaks

The commands are easy. The blast radius is where the cost is, and it is almost entirely in the systems that reference branch names as strings.

• Open pull requests. Most hosts retarget a PR when the base branch is renamed, but a PR whose head branch is deleted is closed, not moved. Merge or retarget open PRs before you delete the old remote branch.
• Branch protection rules. These match on name or pattern. A rule on release does not follow a rename to releases. Your new branch is unprotected and nobody gets an error about it.
• CI triggers. A pipeline with branches: [staging] in its config silently stops running. Nothing fails — it just never starts, which is a much worse failure mode than a red build.
• Deploy hooks. Anything that builds on push to a named branch has the same problem, including the auto-deploy wiring on most hosting platforms.
• Hardcoded links. Documentation, dashboards, and READMEs that link to a branch by URL will 404.

The pattern across all five: a branch rename is a config change disguised as a git command. Grep your CI config, your deploy settings, and your docs for the old name before you run step 3.

Renaming the default branch

This is the same four steps plus one, and the extra step is not optional: most hosts will not let you delete a branch that is currently the repository default. Change the default in the repository settings first, then delete.

The order that works:

1. Push the new branch name to the remote.
2. Change the repository’s default branch in settings to the new name.
3. Move branch protection rules and rulesets across to the new name.
4. Retarget any open pull requests that used the old branch as their base.
5. Delete the old remote branch.

Doing settings before deletion is what keeps this boring. Deleting first gives you a repository with no default branch, which several tools handle badly.

One kindness worth doing for a public repository: before deleting, push a single commit to the old branch whose only change is a README line saying where the branch moved to. Anyone who lands on the old name from a stale bookmark gets an answer instead of a 404.

What to do instead, sometimes

Not every rename needs to happen. If the only problem is that a branch name is ugly and the branch will merge this week, the cheapest fix is to merge it and let the name disappear with it.

The renames genuinely worth the disruption are the ones where the name is wrong rather than untidy: a branch called hotfix-login that is actually a three-week refactor, or a long-lived branch whose name encodes a sprint number that no longer means anything. Those confuse people on every future glance.

For short-lived feature branches, the honest answer is that a bad name for four days costs less than the coordination of a rename.

How this fits the rest of the stack

Branch names leak into more systems than anyone expects, and the leak shows up as a deploy that quietly stops running rather than as an error. That is the same class of problem as the rest of your deployment config: it is fine until one string changes, and then it is invisible. A platform that shows you the deploy log, the branch it built from, and the commit it built — in one place — turns a silent no-op into something you can see. If you are sizing up what a project costs to run before you commit to the setup, the RunxBuild hosting calculator puts the service, the database, the storage, and the bandwidth on one page as separate line items.

Useful related references:

• Deployment Server: The Thing That Decides Whether Your App Reaches Production or Lives in a Branch
• How to Rename a File in Linux: mv, rename, and git mv
• MySQL Rename Column: The SQL Is Easy, the Deployment Is the Work
• Services on RunxBuild

FAQ

Does renaming a git branch lose commits?

No. A branch is a pointer to a commit, and renaming it moves the label without touching history. Your commits, working tree, and stash are all unaffected. Even if you rename badly you can recover the old pointer from git reflog.

What is the difference between git branch -m and -M?

Lowercase -m refuses to overwrite an existing branch with the target name. Uppercase -M forces the rename and overwrites it. Use -m by default; -M can discard a branch you did not realise existed.

Why does git pull fail after I rename a branch?

Your local branch still tracks the old remote-tracking ref, which no longer exists. Fix it with git branch -u origin/new-name new-name, or avoid it by passing -u when you first push the new name.

Can I rename a remote branch directly?

No. The git protocol has no remote rename operation. You push the new name and delete the old one, which is two separate operations against the remote.

Will renaming a branch break my CI pipeline?

It can, silently. Pipelines that filter on branch name simply stop triggering rather than failing. Check your CI config, deploy hooks, and branch protection rules for the old name before deleting the old remote branch.