# git branch: Usage, Options & Common CI Errors

> git branch lists, creates, renames, and deletes branches. Reference for -d, -D, -m, --set-upstream-to, and the not-fully-merged delete error in CI.

Source: https://latchkey.dev/learn/command-reference/git-branch  
Updated: 2026-06-25

git branch manages your branches: list them, make them, rename them, delete them.

Use git branch for branch bookkeeping; use switch/checkout to actually move onto a branch.

## What it does

git branch with no arguments lists local branches. With a name it creates a branch; with flags it deletes, renames, or lists branches by various filters.

## Common usage

```Terminal
git branch                    # list local branches
git branch -a                 # include remote-tracking branches
git branch feature            # create (does not switch)
git branch -d feature         # delete if merged
git branch -m old new         # rename
```

## Options

| Flag | What it does |
| --- | --- |
| -d / --delete | Delete a merged branch |
| -D | Force-delete an unmerged branch |
| -m / --move | Rename a branch |
| -a / --all | List local and remote-tracking branches |
| --set-upstream-to=<ref> | Set the tracked upstream |

## 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' - git -d protects unmerged work. Use -D to force. Listing only shows what was cloned, so -a may miss branches if the clone was single-branch.

## 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git branch: Usage, Options & Common CI Errors?

Use git branch for branch bookkeeping; use switch/checkout to actually move onto a branch.

### What it does?

git branch with no arguments lists local branches. With a name it creates a branch; with flags it deletes, renames, or lists branches by various filters.

### 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' - git -d protects unmerged work. Use -D to force. Listing only shows what was cloned, so -a may miss branches if the clone was single-branch.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt