Git Version Tested: Git 2.30+ to 2.45+ (Windows, macOS, Linux). Works seamlessly with GitHub, GitLab, and Bitbucket.
Rename the current branch with git branch -m new-name. Then publish it with git push -u origin new-name and, after collaborators have switched, remove the old remote name with git push origin --delete old-name.
The 3-Step Solution (AEO / TL;DR)
| Step | Operation | Command |
|---|---|---|
| 1. Rename Local | Switch to branch and rename | git branch -m <old-name> <new-name> |
| 2. Push & Upstream | Push new branch name and bind tracking | git push -u origin <new-name> |
| 3. Delete Old Remote | Clean up deprecated remote branch | git push origin --delete <old-name> |
[!TIP] Collaborator Warning Git has no single atomic command that renames a remote branch on GitHub or GitLab. A remote rename is a new branch push followed by the deletion of the old branch. If you or teammates need to revert mistakes or manage active branches, see our guides on how to undo recent Git commits and Git branch management.
git branch -m old-name new-name
git push -u origin new-name
git push origin --delete old-nameGit has no single command that renames a remote branch. A remote rename is a new branch push followed by deletion of the old remote branch. Delay that deletion if other developers, open pull requests, deployment rules, or CI jobs still use the old name.
Step 1: Renaming a Local Git Branch
Renaming a local branch is straightforward and typically the first step in the process.
Renaming the Current Branch
If you are currently checked out on the branch you wish to rename, use the following command:
git branch -m <new-branch-name>For example, if you are on the feature/login branch and want to rename it to feature/authentication:
git branch -m feature/authenticationRenaming a Different Branch
If you are currently on a different branch (e.g., main or develop), you can rename the target branch using the following syntax:
git branch -m <old-branch-name> <new-branch-name>Example:
git branch -m old-feature-name new-feature-nameStep 2: Synchronizing with the Remote Repository
Renaming a local branch does not automatically update the remote repository. This is the most crucial part of the process, especially for DevOps engineers managing CI/CD pipelines and collaborative environments.
To update the remote repository, publish the new branch, set its upstream, and then delete the old remote name when it is safe. Publishing first avoids a period in which neither remote branch exists.
2.1: Push the New Local Branch and Set Its Upstream
Now, push your newly renamed local branch to the remote repository.
git push -u origin <new-branch-name>Alternatively, you can use the following command if you prefer the git branch --set-upstream-to syntax:
git branch --set-upstream-to=origin/<new-branch-name> <new-branch-name>2.2: Delete the Old Remote Branch
After verifying the new branch and updating repository settings, delete the old remote branch:
git push origin --delete <old-branch-name>This deletes the branch on origin. It is different from git branch -d -r origin/old-name, which only removes a remote-tracking reference from your local repository.
A Complete Workflow Summary
For a clear and concise workflow, here is the complete sequence of commands:
-
Rename the local branch:
git branch -m <new-branch-name> -
Push and set upstream tracking for the new branch:
git push -u origin <new-branch-name> -
Delete the old remote branch after verification:
git push origin --delete <old-branch-name>
How Collaborators Update After the Rename
Each collaborator can prune the old remote-tracking name and connect a local branch to the renamed remote branch:
git fetch origin --prune
git branch -m old-name new-name
git branch --set-upstream-to=origin/new-name new-nameIf the collaborator does not need an existing local branch, they can instead run git switch --track origin/new-name.
DevOps Considerations and Best Practices
As a DevOps expert, renaming branches has implications for your automated workflows and CI/CD pipelines.
- Update CI/CD Pipelines: If your pipelines or build configurations reference the old branch name, you must update them to use the new name. Failure to do so will break your automated deployments and tests.
- Communicate with the Team: Inform your team members about the branch rename. They will need to perform a
git fetchand potentially agit pullto update their local repositories and track the new branch. - Clean Up Stale References: After renaming, ensure that any open pull requests or merge requests related to the old branch are updated or closed and reopened against the new branch.
- Git Hooks and Automation: If you use Git hooks, verify that they are compatible with the branch rename and continue to function as expected.
Conclusion
Renaming a Git branch is a routine operation in software development. By following these steps, you can ensure a smooth transition from the old branch name to the new one, both locally and on your remote repository. A clean and consistent Git history is essential for efficient collaboration and reliable DevOps practices. Mastering these commands will contribute significantly to maintaining a well-organized and professional codebase.
