What does `git checkout-index -u` or `--index` do? -

the git checkout-index command copies files index working tree.

the documentation includes cryptic remark -u or --index command-line parameter:

-u
--index
update stat information checked out entries in index file.

what "stat information?" what's difference between updating , not updating it?

i find in simple experiments, git checkout-index writes files working tree, you'd expect; can't see difference between using -u/--index , not using it.

git-checkout-index copies data from index to working tree. git-update-index copies metadata from working tree to index.

these low-level commands need told do.
option exists @ a wonder of user interface design useful option ensure git's index reflects consistent view of working tree after operation has been performed.

specifically, updates (at least) metadata doesn't contribute git repository rather used determine if files unchanged. see how human-readable dump of .git/index? , what git index contain exactly?.

added in 415e96c.

by way of example, i'll follow along t/t2002-checkout-cache-u.sh, runs command first without , -u (again, that's "the equivalent of git update-index --refresh on checked out entry").

1) preparation:

echo frotz >path0 && git update-index --add path0 && t=$(git write-tree) 

2) without -u, git checkout-index smudges stat information.

rm -f path0 && git read-tree $t && git checkout-index -f -a && git diff-files --exit-code 

output of diff-files:

:100644 100644 8e4020bb5a8d8c873b25de15933e75cc0fc275df 0000000000000000000000000000000000000000 m  path0 --> 1 

see what's in index:

$ git ls-files --debug path0   ctime: 0:0   mtime: 0:0   dev: 0    ino: 0   uid: 0    gid: 0   size: 0   flags: 0 

3) -u, git checkout-index picks stat information new files.

rm -f path0 && git read-tree $t && git checkout-index -u -f -a && git diff-files --exit-code 

(returns 0)

now stat(2) there:

$ git ls-files --debug path0   ctime: 1491479474:0   mtime: 1491479474:0   dev: 16777220 ino: 50556411   uid: 501  gid: 20   size: 6   flags: 0 

apart stat information being recorded, there's 1 other interesting bit in output. why git-diff-files there differences between working tree , index?

the manual says field in output is

sha1 "dst"; 0{40} if creation, unmerged or "look @ work tree".

<sha1> shown 0’s if file new on filesystem , out of sync index.

so test case illustrating 1 way git uses metadata information: when comparing files in working tree , index. if stat information looks stale (or zeroes), file might have changed. since git-read-tree writes index, , not working tree, invalidates stat information. , if stat information valid, git-diff-files can confidently give blob id entry.