In Git, there are two easy commands you can use to delete a branch both locally and remotely.
To delete a Git branch locally, run the following command:
git branch -d your-local-branch
The delete a Git branch remotely, run the following command:
git push origin --delete your-remote-branch
Remember that Git doesn’t let you delete a branch you’re currently working on. Thus, you need to make sure to checkout the branch you are about to delete. You run do e.g. git checkout main before deleting the target branch.
This comprehensive guide teaches you how to properly delete local and remote branches with real examples. You will also learn about a common error related to deleting branches and what to do when facing one.
How to Delete a Git Branch Locally
To successfully delete a local branch in Git, make sure you won’t need it. In other words, there should be no important changes or the branch should have been merged with the main branch already.
Before deletion, check out from the branch you are about to get rid of. This is because Git won’t let you delete the branches you’re working on.
To delete a Git branch locally:
- Checkout from the branch you want to delete with the git checkout command.
- Use the git branch -d command to remove the branch.
git branch -d your-local-branch
Example
I have a project with branches main and add-example-file. The latter branch is redundant and I want to get rid of it.
To get rid of the add-example-file branch, I’m going to check that the current branch I’m working on is not add-example-file using the git branch command:
$ git branch * add-example-file main
As you can tell, the current branch I’m working on is add-example-file, so I need to check out from it.
$ git checkout main
With this command, I’m no longer in the add-example-file branch. This means I can now delete it locally:
$ git branch -d add-example-file Deleted branch add-example-file (was b8e3511).
The command line tool tells that the deletion was successful. Thus, there’s no longer a branch named add-example-file.
Sometimes this command might fail because your branch is not reachable from its upstream or HEAD. Next, let’s have a quick look at why this might happen and what you should do.
Error: The branch is not fully merged.
If you try to delete a local branch and see an error like “error: the branch [branch-name] is not fully merged”, it’s usually nothing to worry about. It means the branch you’re about to delete is not reachable from its upstream or HEAD.
For instance, you can see this error when you try to remove a local branch when the remote branch has been deleted during a pull request before you’ve pulled in the changes.
To get past this error, you can replace the -d with -D in the branch removal command:
git branch -D your-local-branch
But if you suspect there are unmerged commits, don’t be afraid to investigate further. For example, you can use the following command to check the commits that haven’t been merged:
git log your-source-branch --not your-target-branch
How to Delete a Git Branch Remotely
There are two ways you can delete a Git branch from the remote:
- Use GitHub’s UI to delete a remote branch (handy when merging a PR).
- Use the GitHub CLI to push a deleted branch to the remote.
Once you have merged a pull request in GitHub, it shows this view where it offers to delete the merged branch. Just click the “Delete branch” button and the branch will be deleted from the remote.
Alternatively, you can remove any remote branch using the command line with the following command:
git push origin --delete your-remote-branch
This basically pushes a deleted branch to the remote origin.
Example
I have an example project with two branches: main and add-python-file.
But because I just merged the add-python-file branch with the main branch, I don’t need it anymore. Thus, I can push a deleted branch to the origin with the command you just learned:
git push origin --delete add-python-file
After running this command there’s only the main branch left in the project.
Rename Instead of Delete?
Last but not least, you don’t need to delete and recreate a local branch to change its name.
There’s a separate command, git branch -m, you can use to change the name of your branch in Git:
git branch -m old-name new-name
In case you’re wondering, the -m is short for –move which means moving the old branch to a new location.
Thanks for reading. Happy coding!