How To Change a Branch Name in Git (Safely and Step by Step)

Renaming a Git branch is one of those tasks that sounds simple, but can feel risky—especially if other people or services already use that branch name. The good news: Git gives you clear commands to change a branch name both locally and on a remote like GitHub, GitLab, or Bitbucket.

This guide walks through how Git branch names work, how to rename them, and what to watch out for depending on your setup.

What does it mean to change a branch name in Git?

A Git branch is just a movable label pointing to a sequence of commits. When you “rename a branch” you’re not changing the history; you’re only changing the label that points to that history.

So:

• Your commits stay the same
• Your files and code don’t change
• Only the branch reference (name) changes

Typical reasons you might rename a branch:

• Replace master with main
• Fix a typo (e.g., feautre/login → feature/login)
• Make names clearer (button-fix → bugfix/header-button)
• Follow team naming conventions

Renaming matters more when the branch is shared (pushed to a remote, used by others, referenced in CI/CD pipelines) than when it’s just local.

Basics: Check your current branch before renaming

Git renaming behaves differently depending on whether you’re renaming:

• The branch you are currently on
• A different local branch
• A remote branch (like origin/main)

To see your current branch:

git status 

You’ll see something like:

On branch feature/login 

Or use:

git branch 

The current branch is marked with an asterisk:

* feature/login main bugfix/header 

This matters because:

• You can rename the branch you’re on with one command
• You can also rename another local branch, but the command is slightly different
• Renaming a remote branch is not a single “rename” command; it’s more like “create new name + remove old name”

How to rename a local Git branch

Rename the branch you’re currently on

1. Make sure you’re on the branch to rename:

   git status 

2. Run:

   git branch -m new-branch-name 

Example: rename master to main while on master:

git branch -m main 

Git updates the branch name locally. Your working directory and commit history remain exactly the same.

Rename a different local branch

If you’re on main and want to rename feature/login to feature/auth-login:

git branch -m feature/login feature/auth-login 

Pattern:

git branch -m old-name new-name 

This changes only the local branch reference. If the old branch name was already pushed to a remote, the remote still has the old name until you manage that separately.

How to rename a remote branch (e.g., on GitHub or GitLab)

There is no single “rename remote branch” command built into Git. Instead, you:

1. Rename your local branch
2. Push the new name to the remote
3. Remove the old name from the remote
4. Update default branch settings and other users’ setups as needed

Assume:

• Remote is called origin
• Old name: master
• New name: main

1. Rename the local branch

If you’re on master:

git branch -m main 

If you’re on some other branch:

git branch -m master main 

2. Push the renamed branch and set upstream

git push origin -u main 

The -u sets origin/main as the tracking branch for your local main.

3. Delete the old branch name from the remote

git push origin --delete master 

Now the remote repository only has main.

4. Update the default branch (in hosting UI)

On platforms like GitHub, GitLab, or Bitbucket:

• Go to repository settings
• Find Default branch
• Change it from master to main (or from whatever old name to new name)

This step is important because:

• New pull requests often default to targeting the default branch
• Some tools and integrations rely on that setting

5. Let others know they must update their local clones

Anyone who previously pulled the old branch will need to:

git fetch origin git branch -m master main # Rename locally git branch -u origin/main main # Set upstream git remote set-head origin -a # Update origin/HEAD 

They may have small variations depending on their local setup, but the basic idea is:

• Rename their local branch
• Point it to the new remote branch
• Update what Git considers the “default” remote branch

Local branch rename vs remote branch rename: key differences

Common naming scenarios and what to watch out for

1. Renaming master to main

Very common in newer projects. Extra things to consider:

• CI/CD pipelines may reference master explicitly
• Deployment scripts may pull from master
• External tools (hooks, bots) may assume master

Anywhere master is written down (config files, workflows, documentation) may need an update.

2. Renaming a feature branch used in a pull request

If you rename a branch that already has an open pull request:

• Some platforms automatically track the new name
• Others may close or “break” the PR link

On GitHub, renaming a branch typically keeps the PR attached, but any local clones using the old name must rename locally to keep pushing.

3. Renaming a branch used by automation

If the branch is used by:

• CI jobs (.yml pipeline files)
• Cron-based automations
• Webhooks or deploy scripts (git checkout old-branch-name)

Those scripts won’t automatically follow the rename. They will keep trying to use the old name until updated.

What can go wrong, and how to avoid it

“Branch not found” errors

After deleting the old branch on the remote, commands like:

git push origin old-name 

Will fail. Fix is usually:

git branch -m old-name new-name git push origin -u new-name 

Divergent or duplicate branches

If someone:

• Doesn’t rename locally
• Creates a new branch with the old name
• Pushes it to the remote

You can end up with a fresh old-name branch that’s unrelated to the original history. This may be fine, or very confusing, depending on your workflow.

Stale references in config and documentation

Even after you rename:

• Old branch names may be hard-coded in config files
• READMEs and docs might still reference old names
• Build scripts might still check out the old branch

These don’t automatically update; they must be changed manually.

How your specific setup changes the “right” way to rename

Renaming a branch is technically the same set of Git commands, but the impact depends heavily on your context.

Here are some variables that shape what you should do.

1. Solo project vs shared team repo

• Solo repo, only local:

  • Simple: just git branch -m old new
  • No remote or other users to worry about

• Team repo, shared remote:

  • You need to coordinate with others
  • People may have unmerged work on the old branch
  • Open pull requests may rely on the old name

2. CI/CD and automation tools

• If your repo is wired into CI systems, release pipelines, or auto-deploy scripts:
  • Pipelines may have branch-specific triggers
  • Deployment config might explicitly name the branch
  • Changing the branch name without updating these can break builds or deploys

3. Hosting provider and branch protection rules

Different platforms handle renames slightly differently:

• GitHub, GitLab, Bitbucket UI may support “rename default branch” and keep redirects, but protected branch rules may need manual updates.
• Branch protection (e.g., “Require PRs into main”) may be tied to exact branch names.

4. Local environment and Git client

How you interact with Git affects how you experience the rename:

• Command-line Git: You run the raw commands shown here
• GUI Git clients or IDEs (VS Code, IntelliJ, etc.):
  • Often offer a “rename branch” action
  • Under the hood, they still run the same Git commands
  • But some clients handle remote clean-up or tracking flags differently

5. Your comfort level with Git history and recovery

If you’re less experienced:

• You might prefer renaming only local branches at first
• You may want a backup (e.g., tag or additional branch) before deleting old remote names

If you’re more comfortable:

• You might do more aggressive clean-up
• You may script branch renames across multiple repos or remotes

Different user profiles, different rename strategies

To see how much the approach can vary, imagine these scenarios:

• Beginner with a personal project:

  • Has a single branch and no remote
  • Can safely run git branch -m better-name and be done

• Small team on GitHub with basic CI:

  • Has main and multiple long-lived feature branches
  • Needs to think about open pull requests, minimal downtime, and updating a couple of workflow files

• Larger organization with heavy automation:

  • Uses complex CI/CD, deployment environments, and protected branches
  • Might treat a branch rename almost like a mini-migration: planned downtime, scripts to update configs, and coordinated changes across many services

The underlying Git commands are similar, but the risk, coordination, and cleanup work are very different.

Where your own situation becomes the deciding factor

The mechanics of changing a Git branch name are straightforward:

• Local rename: git branch -m old-name new-name
• Push new name: git push origin -u new-name
• Remove old remote name: git push origin --delete old-name
• Update default branch and tools where needed

What really determines how you apply this is:

• Whether you’re working alone or in a team
• Which hosting platform you use and how it handles branch defaults and protections
• How many tools (CI, deploy scripts, bots) depend on the old name
• How comfortable you are with Git cleanup and troubleshooting if something doesn’t behave as expected

Once you understand the core commands, the remaining step is to map them onto your own repository, collaborators, and tooling to decide how carefully—and how widely—you need to roll out a branch rename.