git-update-index Tutorial

The short version

git-update-index is used to update index entries and attributes directly.

When it is a good fit

• when you need to update index entries and attributes directly
• when you want this step to be repeatable instead of ad hoc
• when you need a clearer mental model of what Git is recording or updating

Basic example

git update-index --assume-unchanged path/to/file

What to watch most closely

Plumbing commands are closer to Git internals, so check whether a safer high-level command already solves the problem.

A safer working habit

Treat it as a read-only inspection tool first, then move to write-oriented usage only when necessary.

Useful angles for understanding it

• Inspect lower-level objects and refs
• Write scripts or debug advanced issues
• Verify internal repository state

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git update-index solves the problem of "directly modifying index entries and attributes". It is a low-level write command that allows direct manipulation of file entries in the index, setting flags like assume-unchanged and skip-worktree, or manually adding/removing index entries.

Typical use cases

• Mark a file as "assume unchanged" by running git update-index --assume-unchanged path/to/file to tell Git to ignore local modifications to that file (useful for local config files).
• Manually build the index in a low-level script by using git update-index --add --cacheinfo to directly add entries to the index.
• Set the skip-worktree flag with git update-index --skip-worktree to prevent Git from overwriting local files during checkout.

Diagram view

Index operation

File pathEntry attributes (assume-unchanged / skip-worktree)cacheinfo data

→git update-index

Results

Updated indexAttribute flag changesAdded/removed index entries

update-index writes directly to the index — it is a write operation, not a read-only query. Understand the current index state before operating.

Special cases and boundaries

• git update-index is a write operation that directly modifies index content. After execution, the index state changes, which can affect subsequent commit and checkout behavior.
• --assume-unchanged merely tells Git "assume this file has not changed" — if the file is actually modified, Git may not detect it, leading to potential issues.
• --skip-worktree differs from --assume-unchanged: the former means "I don't want Git to touch this file", suitable for local config files; the latter means "this file is large, I don't want to check if it changed".
• When manually adding entries with --cacheinfo, you must correctly specify the mode, blob hash, and path — incorrect data can corrupt the index.
• Before manipulating the index, it is recommended to first run git ls-files --stage to see the current index state and confirm the existing attributes of the target entry.