git delete branch is a simple process, but it requires understanding the difference between deleting a local branch and a remote branch. When a branch is deleted, all the code changes and commits associated with that branch are also deleted, which means it cannot be recovered unless you have a backup.
To delete a local branch in Git, you need to use the "git branch -d" command followed by the branch name. This command deletes the branch from your local repository, but it does not affect the remote repository. If you want to delete a remote branch, you can use the "git push" command along with the "--delete" option.
In this article, we will explore how to delete a branch in Git, including both local and remote branches. We will also cover some best practices for managing branches in Git to help you keep your code repository organized and efficient.
There can be a couple of scenarios wherein you would wish to delete branch. Following are some of the possible scenarios:
- git delete local branch
- git delete remote branch
- git delete branch local and remote
- Perform git merge and git delete branch
We will cover all these scenarios individually with the best recommendation to do this the right way.
How to check if branch is local or remote
To check if a Git branch is local or remote, you can use the following command:
Syntax:
git branch -a
This command will list all branches, both local and remote, in your Git repository. Local branches are prefixed with an asterisk "*", while remote branches are prefixed with the name of the remote repository, such as "origin/".
For example, if you run the command "git branch -a" in your Git repository and see the following output:
feature-branch * main remotes/origin/HEAD -> origin/main remotes/origin/feature-branch remotes/origin/main
You can see that "feature-branch" and "main" are local branches, while "remotes/origin/feature-branch" and "remotes/origin/main" are remote branches.
In addition, the output also shows that the remote repository "origin" is being tracked and the "HEAD" pointer is pointing to the "main" branch of the "origin" repository.
Git delete local branch
To delete a local Git branch, use -d or --delete as shown in the following command:
Syntax:
git branch -d branch_name git branch --delete branch_name
Example:
git branch -d feature-branch
This command will delete the "feature-branch" from your local repository. However, if there are any unmerged changes on the branch, Git will not allow you to delete it. In that case, you can use the -D option instead of -d to force delete the branch.
Scenario-1: Fix error: Cannot delete branch 'XXX' checked out at 'YYY'
First step, make sure you are not part of the branch which you wish to delete or else you will get this error:
deepak@ubuntu:~/git_examples$ git switch issue-6291 Switched to branch 'issue-6291' deepak@ubuntu:~/git_examples$ git branch --delete issue-6291 error: Cannot delete branch 'issue-6291' checked out at '/home/deepak/git_examples'
As you can see, I switched to issue-6291 branch and then trying to delete the same branch leads to an ERROR.
So to delete the branch, you must checkout as a different branch first.
deepak@ubuntu:~/git_examples$ git switch main
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 2 commits.
(use "git push" to publish your local commits)
Check your current branch:
deepak@ubuntu:~/git_examples$ git branch
issue-5632
issue-6291
issue-9538
* main
my-feature-branch
Now try to delete your branch:
deepak@ubuntu:~/git_examples$ git branch --delete issue-6291
Deleted branch issue-6291 (was e126b0b).
Scenario-2: Fix error: The branch 'XXX' is not fully merged.
Let us try to delete another of our local branch:
deepak@ubuntu:~/git_examples$ git branch --delete issue-5632
error: The branch 'issue-5632' is not fully merged.
If you are sure you want to delete it, run 'git branch -D issue-5632'. This error is caused because we have some un-merged changes in branch issue-5632 due to which the branch delete has failed.
In such case either you can delete the branch forcefully or merge the changes and then perform the delete operation.
Solution-1: Perform merge and git delete branch
I will push these changes to a new branch issue-5632 on the remote gitlab server.
deepak@ubuntu:~/git_examples$ git push origin issue-5632
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (4/4), 319 bytes | 159.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for issue-5632, visit:
remote: https://gitlab.com/golinuxcloud/git_examples/-/merge_requests/new?merge_request%5Bsource_branch%5D=issue-5632
remote:
To gitlab.com:golinuxcloud/git_examples.git
* [new branch] issue-5632 -> issue-5632
This will create a merge request with main branch and will also create a new branch on the remote server.
To merge this into main branch, switch to main branch:
deepak@ubuntu:~/git_examples$ git switch main
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 2 commits.
(use "git push" to publish your local commits)
Check your current branch
deepak@ubuntu:~/git_examples$ git branch
issue-5632
issue-9538
* main
my-feature-branch
Merge issue-5632 branch into main
deepak@ubuntu:~/git_examples$ git merge issue-5632
Updating e126b0b..cf00196
Fast-forward
test-5632/patch-1 | 0
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 test-5632/patch-1
Verify the git log to confirm the merge:
deepak@ubuntu:~/git_examples$ git log --oneline cf00196 (HEAD -> main, origin/issue-5632, issue-5632) Added patch-1 e126b0b (origin/my-feature-branch, my-feature-branch, issue-9538) Adding new group 5e04f57 Created new script to add groups 1b6369c (origin/main, origin/HEAD) Added create_users.sh script 6297a37 Updated script2.sh in main branch ...
Now you can go ahead and delete the local branch:
deepak@ubuntu:~/git_examples$ git branch --delete issue-5632
Deleted branch issue-5632 (was cf00196).
NOTE:
Solution-2: Forcefully delete git local branch
If you do not wish to merge your changes, then you can forcefully delete the branch locally using --delete --force or -D:
So you can use:
git branch --delete --force <branch_to_be_deleted>
OR
git branch -D <branch_to_be_deleted>
Scenari0-3: git delete all local branches
To delete all local branches in a Git repository, except for the currently checked out branch, you can use the following command:
git branch | grep -v "master" | xargs git branch -D
This command will list all the branches in your local Git repository (excluding the "master" branch), and then use the "xargs" command to pass the branch names as arguments to the "git branch -D" command, which deletes the branches. Replace "master" with your branch which you want to exclude from deletion.
Explanation:
- The "
git branch" command lists all the branches in your local Git repository. - The "
grep -v" command filters out the "master" branch from the list of branches. - The "
xargs" command passes the branch names as arguments to the "git branch -D" command. - The "
git branch -D" command deletes the branches.
Note that this command will permanently delete all local branches that are not the currently checked out branch. Therefore, make sure to create a backup or save any important branches before executing this command.
Scenario-4: git delete branch locally and repull
To delete a Git branch locally and then pull the latest changes from the remote repository, you can use the following steps:
Switch to the branch you want to delete:
git checkout branch_name
Delete the local branch:
git branch -D branch_name
Pull the latest changes from the remote repository:
git pull
Explanation:
- The "
git checkout" command switches to the branch you want to delete. - The "
git branch -D" command deletes the branch locally. - The "
git pull" command pulls the latest changes from the remote repository.
Note that if there are changes in the local branch that have not been pushed to the remote repository, those changes will be lost after deleting the branch locally. Therefore, make sure to push any important changes before deleting the branch.
git branch delete remote
To delete a branch from the remote, use any of the following syntax:
git push origin --delete <branch> # Git version 1.7.0 or newer git push origin -d <branch> # Shorter version (Git 1.7.0 or newer) git push origin :<branch> # Git versions older than 1.7.0
Scenario-1: When branch is available only on the remote (not locally)
Since, issue-5632 branch is available only on the remote server as we have already deleted it on the local repo. To delete this branch also from the remote we will use:
deepak@ubuntu:~/git_examples$ git push origin --delete issue-5632
To gitlab.com:golinuxcloud/git_examples.git
- [deleted] issue-5632
This command will delete the branch and all of its commit history from the remote repository.
Explanation:
- The "
git push" command pushes changes from your local repository to the remote repository. - The "
--delete" option tells Git to delete the specified branch on the remote repository. - "
origin" is the name of the remote repository.
Note that this command will permanently delete the branch and its entire commit history, which means that you won't be able to recover the branch or its changes. Therefore, use this command with caution and make sure that you don't need the branch or its history before executing it.
Verify the list of branch on the remote to make sure your branch was deleted successfully:
deepak@ubuntu:~/git_examples$ git branch --remotes
origin/HEAD -> origin/main
origin/main
origin/my-feature-branch
If you want to delete the branch locally as well, you can use the following command in addition to the one above:
git branch -D branch_name
This command will delete the branch and its commit history from your local repository.
Note that this command will also permanently delete the branch and its entire commit history locally, which means that you won't be able to recover the branch or its changes. Therefore, use this command with caution and make sure that you don't need the branch or its history before executing it.
Scenario-2: When there are un-merged changes locally
I have pushed issue-9538 to the remote gitlab server, so now this branch is also available on the remote:
deepak@ubuntu:~/git_examples$ git branch --remotes
origin/HEAD -> origin/main
origin/issue-9538
origin/main
origin/my-feature-branch
I will commit some changes into this branch, but will not merge it with main branch:
deepak@ubuntu:~/git_examples$ git branch * issue-9538 main my-feature-branch deepak@ubuntu:~/git_examples$ git add bugs/patch-9538 deepak@ubuntu:~/git_examples$ git commit -m "added patch for #9538" -a [issue-9538 d850184] added patch for #9538 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 bugs/patch-9538
Let's try to delete this branch on the remote repo server:
deepak@ubuntu:~/git_examples$ git push origin --delete issue-9538
To gitlab.com:golinuxcloud/git_examples.git
- [deleted] issue-9538
So, even though I was in issue-9538 branch and there were un-merged changes, but still the remote branch was successfully deleted. So these factors do not matter if we wish to delete remote branch.
With this step, the remote branch has been deleted but the local branch is still there along with the un-merged changes:
deepak@ubuntu:~/git_examples$ git branch
* issue-9538
main
my-feature-branch
So we must delete this branch locally as explained in section one of this article.
git delete branch local and remote
We have covered this topic separately, now lets understand the flow which should be followed when trying to delete a branch from both local and remote git server.
In my case my-feature-branch is available on both local and remote git server:
deepak@ubuntu:~/git_examples$ git branch
* issue-9538
main
my-feature-branch
Step-1: Switch to alternate branch
Make sure you are on a different branch and not in the one you plan to delete. To switch your branch you can use:
git checkout <different_branch>
OR
git switch <different_branch>
Since we are already on a different branch, we will ignore this step.
Step-2: Delete branch on the remote
Next we will delete the branch on the remote server first:
deepak@ubuntu:~/git_examples$ git push origin --delete my-feature-branch
To gitlab.com:golinuxcloud/git_examples.git
- [deleted] my-feature-branch
As you can verify, now my-feature-branch is deleted from remote but is still available locally:
deepak@ubuntu:~/git_examples$ git branch --all * issue-9538 main my-feature-branch remotes/origin/HEAD -> origin/main remotes/origin/main
Step-3: Delete branch locally
Now we can delete our branch locally. Since the remote branch is already deleted, we can safely use --delete --force or -D to perform a force delete of the git branch:
deepak@ubuntu:~/git_examples$ git branch --delete --force my-feature-branch
Deleted branch my-feature-branch (was e126b0b).
Verify the list of branch:
deepak@ubuntu:~/git_examples$ git branch --all * issue-9538 main remotes/origin/HEAD -> origin/main remotes/origin/main
Step-4: Pruning the obsolete local remote-tracking branch
Note that deleting X remote branch from the command line using a git push will also remove the local remote-tracking branch origin/X, so it is necessary to prune the obsolete remote-tracking branch with git fetch --prune or git fetch -p.
deepak@ubuntu:~/git_examples$ git switch main
Switched to branch 'main'
Perform a fetch on other machines after deleting remote branch, to remove obsolete tracking branches.
deepak@ubuntu:~/git_examples$ git fetch --all --prune
Fetching origin
Summary
In this article we discussed in depth about different commands using which you can delete git branch both locally and remotely. You can safely remove a branch with git branch -d yourbranch. If it contains unmerged changes (ie, you would lose commits by deleting the branch), git will tell you and won't delete it.
To delete a remote branch, use git push origin :mybranch, assuming your remote name is origin and the remote branch you want do delete is named mybranch. You can read more at git branch
