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.