git branch -d / -D: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git branch -d safely deletes a merged branch; -D forces deletion regardless of merge state.

Branch cleanup is routine after merges. The -d/-D distinction is a safety gate: -d refuses to drop unmerged work, while -D overrides that check.

What it does

git branch -d deletes a local branch only if it is fully merged into its upstream or HEAD. git branch -D (a synonym for --delete --force) deletes it unconditionally, discarding any commits unique to it.

Common usage

git branch -d feature           # only if merged
git branch -D feature           # force, even if unmerged
git branch -d -r origin/old     # delete a remote-tracking ref locally
git branch --merged main | grep -v '\*' | xargs -r git branch -d

Options

Common errors in CI

error: The branch 'X' is not fully merged. If you are sure you want to delete it, run 'git branch -D X' - -d protects unmerged commits; use -D to override. error: Cannot delete branch 'X' checked out at '<path>' means it is the current branch or used by a worktree; switch away first.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation