git update-index: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git update-index is the plumbing that edits the staging area directly, including the assume-unchanged and skip-worktree bits.

update-index is low-level. Its assume-unchanged/skip-worktree flags are powerful but a common source of "my change vanished" bugs.

What it does

git update-index registers file contents and flags in the index. It can mark files assume-unchanged (a performance hint) or skip-worktree (tell Git to ignore local edits to a tracked file).

Common usage

Terminal

git update-index --assume-unchanged config.local
git update-index --no-assume-unchanged config.local
git update-index --skip-worktree settings.json
git update-index --refresh
git ls-files -v | grep '^[hsS]'   # list flagged files

Options

Flag	What it does
--assume-unchanged	Skip change detection (perf hint, not durable)
--skip-worktree	Ignore local changes to a tracked file
--no-assume-unchanged / --no-skip-worktree	Clear the bits
--refresh	Refresh stat info in the index
--chmod=+x	Set the executable bit on a file

Common errors in CI

Edits to a file marked assume-unchanged or skip-worktree silently do not get committed - and these bits are local-only, so they cause "works on my machine" drift. Audit with git ls-files -v (lowercase letters indicate the flags) and clear with --no-skip-worktree.

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

Frequently asked questions

git update-index: Usage, Options & Common CI Errors?