Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Staging and Committing

git update-index --assume-unchanged and --skip-worktree

Reference for git update-index --assume-unchanged and --skip-worktree: what each flag does, how to list and undo them, and why neither replaces .gitignore.

git update-index can set two per-file flags in the index that make Git stop looking at a tracked file's working-tree changes. --assume-unchanged is a performance promise ("this file does not change, do not stat it"). --skip-worktree is a stronger statement ("pretend the working copy matches the index, whatever is on disk"). Both leave the file tracked and committed; they only hide local edits from git status, git diff and git add -A.

People use them to keep a local tweak to a tracked config file out of their commits. Neither flag is a good tool for that job, but knowing exactly how they behave avoids confusion.

Terminal
git update-index --skip-worktree config.local.php
git update-index --no-skip-worktree config.local.php
git ls-files -v | grep '^S'

Try it

Bash Hide a local edit with skip-worktree

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 assume-unchanged versus skip-worktree

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 [--[no-]assume-unchanged] [--[no-]skip-worktree] [--] <file>...
git ls-files -v          # lowercase letter = assume-unchanged, S = skip-worktree
Name Description
--assume-unchanged Mark the paths so Git no longer checks them for changes.
--no-assume-unchanged Clear the flag; Git compares the file again.
--skip-worktree Mark the paths as "ignore my working copy". Used by sparse checkout.
--no-skip-worktree Clear the flag.
git ls-files -v Show a status letter per file: H normal, h assume-unchanged, S skip-worktree, s both.

Returns: nothing on success. Errors: an unknown path stops with error: <file>: cannot add to the index - missing --add option?.

Usage notes

  • They are not ignore rules. .gitignore applies to untracked files. These flags apply to files that are already tracked, and they exist only in your own index, so teammates are unaffected.
  • assume-unchanged is a speed hint. Git trusts you not to modify the file, so a change may simply be missed. It is meant for huge trees on slow file systems.
  • skip-worktree is the right flag for local edits. Git keeps the flag across most index operations, and git add, commit -a and reset --hard leave the file alone.
  • Upstream changes still collide. If a pull changes the flagged file, Git refuses with "Your local changes to the following files would be overwritten". Clear the flag, stash or restore the file, pull, then reapply your edit.
  • Flags are easy to forget. A file that "will not update" is often flagged; check with git ls-files -v | grep -E '^[a-zS]'.
  • Sparse checkout sets skip-worktree automatically on files outside the cone.
  • Better alternatives: commit a template (config.example) and ignore the real file, or use git stash for short-lived edits, or an include of a local configuration file.