Git "Your local changes would be overwritten" in CI

By Kaveh Alemi·Latchkey

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.

What this error means

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. It surfaces on persistent runners that reuse the workspace, not on ephemeral ones.

error: Your local changes to the following files would be overwritten by checkout:
	package-lock.json
Please commit your changes or stash them before you switch branches.
Aborting

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.

- 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

Common causes

A dirty workspace from a previous job

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.

Tracked files modified by a build step

A step edited a tracked file in place (formatting, codegen) before a later checkout/pull, leaving the tree dirty.

How to fix it

Reset the workspace before checkout

Discard uncommitted changes and untracked files so the checkout has a clean tree to land in.

git reset --hard
git clean -ffdx
git checkout main

Force a clean checkout in the workflow

On GitHub Actions, actions/checkout cleans the workspace by default; ensure it is not disabled.

- uses: actions/checkout@v4
  with:
    clean: true   # default; resets the workspace each run

The checkout options that fix most of this

- 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

How to prevent it

• Use ephemeral runners, or hard-reset + clean at job start on persistent ones.
• Avoid committing generated files that build steps rewrite.
• Keep actions/checkout clean step enabled (the default).

Frequently asked questions

Related guides

References

• Git reference manual
• GitHub Actions documentation