Victor's room

Overview & Root Cause Summary: The error error: The branch '<branch_name>' is not fully merged. If you are sure you want to delete it, run 'git branch -D <branch_name>' occurs when attempting to delete a local branch using the safe deletion flag (git branch -d). Git blocks the deletion because it calculates branch ancestry using exact cryptographic commit SHAs. In modern workflows using GitHub or GitLab, Pull Requests merged via “Squash and merge” or “Rebase and merge” create new commit objects with different hashes on the target branch (main), causing Git’s local history graph to treat the original feature branch commits as unmerged.

Understanding the Root Causes

• Squash and Merge Operations: Merging a pull request via GitHub or GitLab’s “Squash and merge” combines all feature commits into a single new commit with a new SHA hash. Because the original commit hashes are not in the ancestry tree of main, local Git perceives them as unmerged.
• Rebase Merges: Replaying commits onto the target branch rewrites their parent pointers and hashes, breaking SHA-based branch containment checks.
• Truly Unmerged Local Work: The branch contains experimental or aborted commits that were never pushed or merged into the upstream branch.
• Safe Deletion Safeguard: Git’s lowercase -d flag strictly requires that the target branch is a direct ancestor of HEAD or your upstream tracking branch to prevent accidental data loss.

Step 1: Quick Fix (Verify Changes and Force Delete with -D)

If you have already confirmed that your pull request was successfully squashed and merged into main, use the force deletion flag to remove the local branch.

# 1. Switch to your default branch and pull latest changes:
git switch main
git pull origin main

# 2. Verify that your feature branch changes exist on main (returns empty if fully integrated):
git diff main...<branch_name>

# 3. Force delete the local branch safely:
git branch -D <branch_name>

# Note: git branch -D is an alias for git branch --delete --force

Step 2: Auditing Unmerged Commits Before Deletion

Before deleting a branch when you are unsure if its code was preserved, audit the differences between the branch and your base branch.

# 1. View commits on your branch that do not exist on main:
git log main..<branch_name> --oneline

# 2. Use git cherry to detect if commit patches were applied upstream (shows '-' if applied):
git cherry -v main <branch_name>

# 3. If there is unmerged code you still want to preserve, merge or rebase it first:
git merge <branch_name>

Step 3: Pruning and Bulk Cleaning Stale Local Branches

Clean up stale remote-tracking references and safely prune local branches whose upstream PRs have already closed.

# 1. Prune deleted remote tracking branches:
git fetch --all --prune

# 2. List all local branches that are traditionally merged into main:
git branch --merged main

# 3. Safely delete traditionally merged branches in bulk (excluding main):
git branch --merged main | grep -v "^\*" | grep -v "main" | xargs -n 1 git branch -d

Verification & Testing Steps

Confirm that the local branch has been cleanly removed from your repository’s branch index.

# 1. Verify the deleted branch is no longer listed locally:
git branch --list <branch_name>

# 2. Verify current repository status:
git status

# 3. Inspect full branch tree (local and remote):
git branch -a

Summary Comparison Table