How to Rename Git Branches Locally and Remotely
Git, a distributed version control system, enables developers to manage code changes, track revisions, and collaborate effectively. A fundamental Git feature is branching, which allows the creation of isolated environments for tasks like new features or bug fixes without affecting the main project. As the project evolves, renaming branches becomes a practical way to reflect updated objectives or improve naming consistency. For example, switching a branch from bugfix/login to fix/login-auth can boost clarity and structure.
This guide outlines how to rename a Git branch both locally and on a remote repository, including how to do so without switching branches using git checkout.
Quick Reference for Renaming a Branch
For those already comfortable with Git, here are the essential commands:
# Change the name of the current branch
$ git branch -m <new_branch_name>
# Rename a specific local branch
$ git branch -m <old_branch_name> <new_branch_name>
# Push new branch and remove the old from the remote
$ git push origin :<old_branch_name> <new_branch_name>
# Link the renamed branch to its remote counterpart
$ git push --set-upstream origin <new_branch_name>
How to Rename a Local Git Branch
Local branches exist solely on your machine and are not visible on remote repositories. Renaming them helps maintain order and adhere to updated project naming standards.
Local Rename Command Syntax
The typical structure for renaming a branch locally is:
git branch [OPTIONS] [BRANCH NAMES]
Explanation:
- git branch: Handles branch-related actions
- -m: Renames a branch safely, prevents conflicts if the new name exists
- -M: Forces rename even if the new branch name is already taken
- [BRANCH NAMES]: Existing and target names for the rename operation
Local Rename Example
Here’s a step-by-step process to rename a local branch:
Start by listing all local branches in your Git project directory.
$ git branch
Expected output:
- feature-auth
- feature-2fa
- * main (currently active)
Switch to the branch you want to rename:
$ git checkout feature-auth
Rename the branch using -m:
$ git branch -m feature-login
This will change feature-auth to feature-login. The -m flag prevents overwriting if feature-login already exists.
Check to confirm the rename:
$ git branch
You should see:
- * feature-login
- feature-2fa
- main
How to Rename a Remote Git Branch
Remote branches are hosted repositories like those on GitHub. Git doesn’t support direct renaming on remotes—you must rename locally, push the updated branch, and delete the old one from the remote server.
Remote Rename Command Syntax
git push [REMOTE] :[OLD BRANCH NAME] [NEW BRANCH NAME]
Command breakdown:
- git push: Uploads changes to the remote
- [REMOTE]: Usually
origin - :[OLD BRANCH NAME]: Deletes the old branch from remote
- [NEW BRANCH NAME]: Pushes the newly renamed branch
Remote Rename Example
First, view your local branches:
$ git branch
Output might be:
- * feature-login
- feature-2fa
- main
Switch to the branch you plan to rename:
$ git checkout feature-2fa
Rename it locally:
$ git branch -m feature-mfa
Push the renamed branch and delete the old one remotely:
$ git push origin :feature-2fa feature-mfa
This pushes feature-mfa and removes feature-2fa from the remote repository.
Link the local branch to the remote counterpart:
$ git push -u origin feature-mfa
The -u option sets upstream tracking for future push and pull operations.
Confirm the branch has been renamed remotely:
$ git branch -r
The deleted branch (feature-2fa) should no longer appear. The new one (feature-mfa) will be listed.
How to Rename a Git Branch Without Switching
You can rename a local Git branch without checking it out using git branch -m. This approach is helpful when the target branch isn’t currently active.
Command Syntax Without Checkout
git branch -m [OLD BRANCH NAME] [NEW BRANCH NAME]
Explanation:
- git branch: Manages branch functions
- -m: Performs the rename
- [OLD BRANCH NAME]: Current name of the branch
- [NEW BRANCH NAME]: New name for the branch
Example: Renaming a Git Branch Without Checking It Out
Use the following procedure to rename a Git branch without switching to it:
First, display all available local branches:
$ git branch
Rename the desired branch using the syntax below:
$ git branch -m old-branch-name new-branch-name
Upload the renamed branch and remove the previous one from the remote:
$ git push origin :old-branch-name new-branch-name
Link the new branch to its remote counterpart:
$ git push -u origin new-branch-name
To confirm the rename on the remote, list all remote branches:
$ git branch -r
The previous branch name should be absent from the list, while the new name should now appear.
Conclusion
You’ve now learned how to rename Git branches both on your local system and in remote repositories using reliable and safe commands. Whether adjusting your current branch name or modifying another without switching, you’ve applied accurate syntax to carry out renames effectively. For remote branches, you pushed updates, removed deprecated names, and established tracking references to maintain synchronization. These practices improve clarity, uphold naming standards, and support a more organized Git workflow. For further guidance on working with branches, consult the official Git documentation.
