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

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.

Related guides

git add: Usage, Options & Common CI Errorsgit add stages changes for the next commit. Reference for -A, -p, --update, and the pathspec and ignored-file… git ls-files: Usage, Options & Common CI Errorsgit ls-files lists files Git knows about in the index. Reference for --others, --modified, --exclude-standard… git rm: Usage, Options & Common CI Errorsgit rm removes files from the working tree and the index. Reference for --cached, -r, -f, and the "has staged… git status: Usage, Options & Common CI Errorsgit status shows staged, unstaged, and untracked changes plus branch state. Reference for -s, --porcelain, -b…