# git pull: Usage, Options & Common CI Errors

> git pull fetches from a remote and integrates the changes. Reference for --rebase, --ff-only, and the merge-conflict and divergent-branches errors.

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

git pull is git fetch followed by an integration step (merge or rebase).

Pull updates your branch with remote changes. In CI you almost always want --rebase or --ff-only for predictable results.

## What it does

git pull runs git fetch to get new commits, then merges (default) or rebases them onto your current branch.

## Common usage

```Terminal
git pull
git pull --rebase origin main
git pull --ff-only             # fail instead of creating a merge
```

## Options

| Flag | What it does |
| --- | --- |
| --rebase | Rebase local commits instead of merging |
| --ff-only | Only fast-forward; error if a merge is required |
| --no-rebase | Force a merge integration |
| --autostash | Stash/unstash dirty changes around the pull |

## Common errors in CI

fatal: Need to specify how to reconcile divergent branches - newer Git refuses to guess. Pick one: git config pull.rebase true (or pull.ff only). "Your local changes would be overwritten by merge" means a dirty tree; commit, stash, or use --autostash 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.

```.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 pull: Usage, Options & Common CI Errors?

Pull updates your branch with remote changes. In CI you almost always want --rebase or --ff-only for predictable results.

### What it does?

git pull runs git fetch to get new commits, then merges (default) or rebases them onto your current branch.

### Common errors in CI?

fatal: Need to specify how to reconcile divergent branches - newer Git refuses to guess. Pick one: git config pull.rebase true (or pull.ff only). "Your local changes would be overwritten by merge" means a dirty tree; commit, stash, or use --autostash first.

---

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