# git merge-base: Usage, Options & Common CI Errors

> git merge-base finds the common ancestor of two commits, the basis for diffing a PR. Reference for --fork-point, --is-ancestor, and shallow-clone errors.

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

git merge-base returns the best common ancestor of two commits - the point your branch diverged.

merge-base is how CI computes "changed in this PR": diff against the merge base of the branch and its target.

## What it does

git merge-base finds the commit where two branches diverged (their best common ancestor), which is the correct base for computing a pull request’s effective diff.

## Common usage

```Terminal
git merge-base main feature
git diff $(git merge-base main HEAD) HEAD   # PR changes only
git merge-base --is-ancestor A B && echo "A is ancestor of B"
git merge-base --fork-point main feature
```

## Options

| Flag | What it does |
| --- | --- |
| --is-ancestor | Exit 0 if first commit is an ancestor of second |
| --fork-point | Use reflog to find where a branch forked |
| --all | Print all merge bases (for criss-cross merges) |
| --octopus | Best common ancestor of many commits |

## Common errors in CI

fatal: Not a valid commit name or an empty result usually means the base branch is missing on the runner - a shallow or single-branch clone. Fetch the target branch (git fetch origin main) or set fetch-depth: 0 so the common ancestor is reachable.

## 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 merge-base: Usage, Options & Common CI Errors?

merge-base is how CI computes "changed in this PR": diff against the merge base of the branch and its target.

### What it does?

git merge-base finds the commit where two branches diverged (their best common ancestor), which is the correct base for computing a pull request’s effective diff.

### Common errors in CI?

fatal: Not a valid commit name or an empty result usually means the base branch is missing on the runner - a shallow or single-branch clone. Fetch the target branch (git fetch origin main) or set fetch-depth: 0 so the common ancestor is reachable.

---

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