git update-index

The hammer beneath git add.

🎯 What & why

git update-index is the low-level hammer that mutates .git/index directly. Every porcelain that stages, unstages, or twiddles a file's bookkeeping bit ultimately calls into the same machinery this command exposes.

🧠 Mental model

The index is a sorted table of (mode, sha, stage, path). update-index lets you insert, remove, refresh stat info, or set per-entry flags (assume-unchanged, skip-worktree) one row at a time, with no automatic worktree scanning.

🛠️ Synopsis

git update-index [--add] [--remove] [--refresh] [--chmod=(+|-)x]
                 [--assume-unchanged | --no-assume-unchanged]
                 [--skip-worktree   | --no-skip-worktree]
                 [--cacheinfo <mode>,<sha>,<path>]
                 [--info-only] [--stdin [-z]] [--] [<path>...]

🎚️ Switches & options

Flag	What it does
`--add`	Allow inserting paths the index does not already know about.
`--remove`	⚠️ Allow dropping index entries; combined with --add it mirrors `git add -A`.
`--refresh`	Re-stat tracked files and update cached stat info; does not change content.
`--cacheinfo <mode>,<sha>,<path>`	Insert an entry pointing at an existing object without reading the worktree.
`--chmod=(+\|-)x`	Flip the executable bit on the index entry only.
`--assume-unchanged / --no-assume-unchanged`	Set or clear the bit that tells Git to skip stat checks (a performance hint, not a guarantee).
`--skip-worktree / --no-skip-worktree`	Set or clear the bit that hides a path from checkout/diff; the foundation of sparse-checkout.
`--stdin [-z]`	Read paths from stdin (NUL-delimited with -z) for batch updates.
`--info-only`	Add an entry by SHA without requiring the object to exist locally (used by partial clones).

💡 Use cases

Stage a precomputed blob by SHA without ever writing it to the worktree.
Toggle the executable bit on a tracked file without touching its content.
Drive sparse-checkout by setting --skip-worktree on paths you want hidden.
Refresh stat cache after a tool (rsync, build system) rewrote files with identical content.

🧪 Examples

Stage a blob by SHA at a path

git update-index --add --cacheinfo 100644,$(git hash-object -w build.txt),build.txt

Make a script executable in the index only

git update-index --chmod=+x scripts/run.sh

Hide a tracked file via skip-worktree

git update-index --skip-worktree config/local.env

Refresh stat info for the whole index

git update-index --refresh

🎓 Recommendations

Reach for --skip-worktree (not --assume-unchanged) when you want a tracked file to be locally invisible; it is the supported, sparse-checkout-aware bit.
When scripting, prefer --stdin -z so paths with newlines or spaces survive intact.
After --cacheinfo, run git write-tree to confirm the index is internally consistent.

🪤 Common pitfalls

--assume-unchanged is a hint Git can override during merges and refresh; never use it as a permanent ignore mechanism.
Using --remove on a path that still exists in the worktree drops the index entry but leaves the file behind, easy to lose track of.
--cacheinfo with a SHA Git does not have produces an unreadable index unless you also use --info-only on purpose.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.