How to Delete a Git Branch Locally and Remotely
After finishing work on a feature or bug fix, you'll often need to clean up by deleting branches that are no longer needed. Git branches can exist both locally on your machine and remotely on servers like GitHub, GitLab, or Bitbucket, and each requires different commands to delete safely.
In this guide, you'll learn how to delete Git branches in both locations, along with safety checks to prevent accidental data loss.
Prerequisites
You'll need Git installed on your system and access to a Git repository with multiple branches. Basic familiarity with Git branching concepts will help you understand when it's safe to delete branches.
Checking Your Current Branches
Before deleting any branches, it's important to see what branches exist and which one you're currently on. You can't delete the branch you're currently working on.
To see all local branches:
git branch
The output shows all your local branches with an asterisk next to your current branch:
feature/user-authentication
* main
hotfix/security-patch
To see both local and remote branches:
git branch -a
This shows a more complete picture including remote tracking branches:
feature/user-authentication
* main
hotfix/security-patch
remotes/origin/feature/user-authentication
remotes/origin/main
remotes/origin/hotfix/security-patch
Deleting Local Branches
Git provides two options for deleting local branches: a safe delete and a force delete.
Safe Delete with -d Flag
The safe delete option checks if the branch has been merged before allowing deletion:
git branch -d feature/user-authentication
If the branch contains unmerged changes, Git will prevent the deletion and show an error message:
error: The branch 'feature/user-authentication' is not fully merged.
If you are sure you want to delete it, run 'git branch -D feature/user-authentication'.
This safety check prevents you from accidentally losing work that hasn't been incorporated into other branches.
Force Delete with -D Flag
When you're certain you want to delete a branch regardless of its merge status:
git branch -D feature/user-authentication
Use this carefully, as it will delete the branch even if it contains unique commits that haven't been merged elsewhere. Always double-check that you don't need the work in that branch.
Deleting Multiple Local Branches
You can delete several branches at once by listing them:
git branch -d feature/login feature/signup hotfix/minor-bug
This is useful when cleaning up after a release when multiple feature branches are no longer needed.
Deleting Remote Branches
Remote branches require a different approach since they exist on the server rather than your local machine.
Using git push with --delete
The most straightforward way to delete a remote branch:
git push origin --delete feature/user-authentication
This command tells the remote repository (origin) to delete the specified branch. You'll see confirmation output:
To github.com:username/repository.git
- [deleted] feature/user-authentication
Using the Colon Syntax
An alternative syntax that pushes "nothing" to the remote branch, effectively deleting it:
git push origin :feature/user-authentication
This older syntax means "push nothing to the feature/user-authentication branch on origin," which deletes the remote branch. The --delete
flag is more explicit and easier to understand.
Cleaning Up Remote Tracking References
After deleting a remote branch, your local Git might still have references to it. Clean these up with:
git remote prune origin
This removes local references to remote branches that no longer exist on the server. You can also use:
git fetch --prune
This fetches updates from the remote and automatically prunes deleted branch references.
Deleting Both Local and Remote Branches
When you want to completely remove a branch from everywhere, combine the commands:
# Delete the local branch
git branch -d feature/user-authentication
# Delete the remote branch
git push origin --delete feature/user-authentication
# Clean up remote references
git remote prune origin
You can create a simple script or alias to do this in one step:
# Add this to your ~/.gitconfig or ~/.zshrc
alias git-delete-branch='f() { git branch -d $1 && git push origin --delete $1 && git remote prune origin; }; f'
Then use it like:
git-delete-branch feature/user-authentication
Safety Checks Before Deleting
Before deleting any branch, especially important ones, perform these safety checks:
Check if the branch has been merged into your main branch:
git branch --merged main
This shows branches that have been fully merged into main and are generally safe to delete.
See which branches haven't been merged:
git branch --no-merged main
Be extra careful with these branches as they contain work that might be lost.
Check recent commits on the branch:
git log --oneline feature/user-authentication -10
This shows the last 10 commits on the branch so you can verify what work would be lost.
Handling Different Scenarios
Branch Still Checked Out Elsewhere
If you're working in a repository with multiple worktrees or if someone else has the branch checked out, you might get an error when trying to delete. Switch to a different branch first:
git checkout main
git branch -d feature/user-authentication
Protected Branches
Some repositories have branch protection rules that prevent deletion of important branches like main
or develop
. You'll get an error if you try to delete these:
git push origin --delete main
# Error: refusing to delete the current branch: refs/heads/main
This is a safety feature to prevent accidental deletion of critical branches.
Recovering Accidentally Deleted Branches
If you accidentally delete a local branch, you can often recover it using the reflog:
# Find the commit hash of the deleted branch
git reflog
# Create a new branch from that commit
git branch feature/user-authentication 9fceb02
For remote branches, recovery is only possible if someone else has a copy of the branch or if the remote repository has backup procedures in place.
Best Practices for Branch Cleanup
Regularly clean up merged branches to keep your repository organized. Many teams do this as part of their release process or sprint cleanup.
Use descriptive branch names that include the feature or issue number, making it easier to identify which branches can be safely deleted:
git branch -d feature/JIRA-123-user-login
git branch -d hotfix/issue-456-security-fix
Consider setting up automated branch cleanup in your CI/CD pipeline to delete merged feature branches automatically after a certain period.
Always communicate with your team before deleting shared branches, even if they appear to be merged. Someone might be using that branch as a base for other work.
Verifying Successful Deletion
After deleting branches, verify they're gone:
# Check local branches
git branch
# Check remote branches
git branch -r
# Verify specific branch is gone
git show-branch feature/user-authentication
# Should show: fatal: bad sha1 reference
You now have the knowledge to safely manage branch cleanup in your Git repositories. Remember that deletion is permanent for remote branches, so always double-check before removing branches that might contain important work.
Found an issue?