Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git update-index command

Reference for git update-index: add, remove and modify index entries directly, use --cacheinfo and --index-info, set mode bits and the assume-unchanged and skip-worktree flags.

git update-index is the low-level command that edits the index (the staging area). git add is a friendly wrapper around it. With update-index you can register a file that exists in the working tree, insert an entry for a blob that has no file at all (--cacheinfo), remove entries, change the executable bit, refresh cached stat data, and set per-entry flags such as --assume-unchanged and --skip-worktree.

Unlike git add, it does not search for files itself: it acts only on the paths you name or send on standard input, and it refuses to add a new file unless you say --add. It is mostly used in scripts and in explanations of how the index works.

Terminal
git update-index --add file.txt
git update-index --add --cacheinfo 100644,<blob-id>,path/name.txt

Try it

Bash Put a blob in the index without a file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Modes and flags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git update-index [--add] [--remove | --force-remove] [--replace]
                 [--refresh | --really-refresh] [-q] [--unmerged] [--ignore-missing]
                 [--cacheinfo <mode>,<object>,<path>] | [--cacheinfo <mode> <object> <path>]
                 [--chmod=(+|-)x] [--info-only]
                 [--assume-unchanged | --no-assume-unchanged]
                 [--skip-worktree | --no-skip-worktree]
                 [--really-refresh] [--index-info] [--index-version <n>]
                 [--split-index | --no-split-index] [--untracked-cache | --no-untracked-cache]
                 [--fsmonitor | --no-fsmonitor] [-z] [--stdin] [--verbose] [--] [<file>...]
Option Description
--add Allow adding files that are not yet in the index. Without it, unknown paths are an error.
--remove Remove an entry whose file no longer exists in the working tree.
--force-remove Remove the entry even if the file still exists (the file stays).
--replace If a path conflicts with an entry (a file where a directory is, or the reverse), replace it.
--refresh Re-check stat data of all entries and update the cache; entries whose content changed are reported as needing update.
--really-refresh Like --refresh, but also ignores assume-unchanged flags.
--cacheinfo <mode>,<object>,<path> Insert an entry for an object that is already in the database. Mode is e.g. 100644, 100755, 120000 or 160000.
--index-info Read lines <mode> SP <object> TAB <path> (and the form with stage number) from standard input. A mode of 0 removes the path.
--chmod=+x / --chmod=-x Set or clear the executable bit of the index entry.
--info-only Compute the object ID but do not write the object.
--assume-unchanged Mark entries so Git does not check the working tree file for changes.
--skip-worktree Mark entries as "pretend the file is unchanged and may be absent"; used by sparse checkout.
--unmerged If a path is unmerged, do not stop with an error.
--index-version <n> Convert the index file to version 2, 3 or 4.
--split-index, --untracked-cache, --fsmonitor Enable the matching index extension.
--stdin / -z Read paths from standard input (NUL-separated with -z).
-q Quiet: do not complain about files that need updating.

Returns: exit status 0 on success; non-zero when a path could not be processed, for example error: x: cannot add to the index - missing --add option?.

Usage notes

  • git add is different in two ways. It finds files itself (directories, ignore rules, pathspecs) and it also refreshes the index; update-index takes exactly the paths you give it.
  • --cacheinfo needs an existing object. Write the blob first with git hash-object -w; otherwise later commands fail with "invalid object".
  • --assume-unchanged is a promise, not an ignore rule. It is a performance hint meant for files you will not edit. If the file does change upstream, operations such as checkout, merge or stash may fail or silently overwrite. For local-only changes to tracked config files, prefer --skip-worktree, which Git respects more strictly. For files nobody should track, use .gitignore and remove them from the index. See git update-index skip.
  • See flags with git ls-files -v: lowercase letters mark assume-unchanged entries; S marks skip-worktree.
  • Unmerged entries. During a conflict the index holds stages 1, 2 and 3. --index-info can write them; git update-index --add --cacheinfo writes stage 0 and resolves the path.
  • Concurrent access. The command takes .git/index.lock; if another Git process is running you get a "File exists" error.
  • Index version. --index-version 4 shrinks the index by prefix-compressing paths. Old tools may not read it.