How to Delete a Branch in Git (Local & Remote)

by

Introduction

Working with branches is a fundamental part of Git-based workflows. However, when a feature or bugfix is complete, it’s good practice to delete the branch to keep your repository clean and manageable. In this post, we’ll walk you through how to delete both local and remote Git branches — plus how to handle common errors.

🔹 How to Delete a Local Branch in Git

To delete a local branch (i.e., one on your own machine), use the following command:

git branch -d branch-name

This safely deletes the branch only if it has been merged.

To force delete the branch (even if it hasn’t been merged), use:

git branch -D branch-name

Example:

git branch -d feature/login
git branch -D feature/old-experiment

✅ Make sure you’re not currently on the branch you’re trying to delete.

🔹 How to Delete a Remote Branch in Git

To delete a branch from a remote repository like GitHub, GitLab, or Bitbucket, use:

git push origin --delete branch-name

Example:

git push origin --delete feature/login

This command tells Git to remove the feature/login branch from the remote origin.

🔸 Common Error: Branch is Used by a Worktree

Sometimes you may encounter an error like this:

error: cannot delete branch 'uat' used by worktree at '/Users/devuser/projects/test-worktree'

This means the branch is currently in use by a worktree, a Git feature that allows multiple working directories.

✅ Fix: Remove or Detach the Worktree

  1. Navigate to the worktree:
cd /Users/devuser/projects/test-worktree
  1. Switch to another branch:
git switch main
  1. Then return to your main repo and delete the branch:
git branch -d uat

Alternatively, remove the worktree completely (if no longer needed):

git worktree remove /Users/devuser/projects/test-worktree --force
git branch -d uat

⚠️ --force will delete the worktree even if it has uncommitted changes. Use it with caution.

✅ Final Thoughts

Deleting unnecessary branches is an easy yet powerful way to improve your Git workflow. Whether you’re working solo or in a team, keeping your branches tidy helps avoid confusion and simplifies collaboration.