# Git "Your local changes would be overwritten" in CI

> Fix Git "error: Your local changes to the following files would be overwritten by checkout/merge" in CI - a dirty workspace on a reused runner blocking a checkout or pull.

Source: https://latchkey.dev/learn/git/git-local-changes-overwritten  
Updated: 2026-06-25

Git stopped a checkout, pull, or merge because the working tree has uncommitted changes that the operation would clobber. On a reused or self-hosted runner this means the previous job left modified or generated files behind.

## Diagnose it: depth, refs, or credentials?

CI checkouts are shallow and detached by default, which breaks anything that needs history or a branch name. Before treating it as a credential problem, confirm what the runner actually fetched.

```.github/workflows/ci.yml
- run: |
    git rev-parse --is-shallow-repository
    git rev-parse --abbrev-ref HEAD      # prints HEAD when detached
    git log --oneline -3
    git remote -v
    git for-each-ref --format="%(refname)" | head
```

> `actions/checkout` fetches depth 1 and leaves you on a detached HEAD. Anything diffing against a base ref, reading the branch name, or running `git describe` needs `fetch-depth: 0` and usually an explicit ref.

## The checkout options that fix most of this

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # full history: diffs, tags, git describe
    submodules: recursive # submodules are NOT fetched by default
    persist-credentials: false  # if a later step pushes with its own token
```

## FAQ

### What causes Git "Your local changes would be overwritten" in CI?

There are 2 common causes: a dirty workspace from a previous job and tracked files modified by a build step. A reused runner kept build artifacts or generated files (a regenerated lockfile, compiled output) as uncommitted changes, so the next checkout would overwrite them and Git refuses.

### How do I fix Git "Your local changes would be overwritten" in CI?

There are 2 fixes depending on which cause you have: reset the workspace before checkout and force a clean checkout in the workflow. Work through them in order, since the first is the most common.

### What does Git "Your local changes would be overwritten" in CI actually mean?

A checkout/pull step fails with error: Your local changes to the following files would be overwritten by checkout and Please commit your changes or stash them before you switch branches.

### How do I stop Git "Your local changes would be overwritten" in CI happening again?

Use ephemeral runners, or hard-reset + clean at job start on persistent ones. The prevention section lists 3 changes that keep it from recurring.

---

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