Re: [PATCH] Documentation/git-update-index.txt: add an example of use
Matěj Cepl <mcepl@cepl.eu> writes:
> I met this command in the wild and I spent a lot of time to
> understand what it is good for.
> ---
Show 20 quoted lines
> Documentation/git-update-index.txt | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
> index 7128aed540..da11cbc418 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -399,6 +399,15 @@ M foo.c
> <8> you can tell about the change after the fact.
> <9> now it checks with lstat(2) and finds it has been changed.
>
> +To speed up other Git commands that rely on the index, such as git status
> +or git commit, user can refresh the index and avoid having to re-check
> +the status of every file in the working directory. This command
> +doesn't modify any committed data in your repository.
> ++
> +----------------
> +$ git update-index -q --refresh || true
> +----------------
> +
Two comments.
* The example before the new one is for a rather esoteric corner
case of running Git on an inefficient filesystem. Perhaps this
new one more commonly happens, in which case, it probably sits
better earlier in the list of examples.
* Because most (if not all) Porcelain commands like "git commit" or
"git status" automatically refreshes the index, it is of dubious
value to manually refresh, like your example does, before running
them. You pay the price either way, and the only difference may
be the time (and brain cycle) you spend to manually issue the
"update-index --refresh" command.
The benefit of refreshing the index manually beforehand mostly comes when you are running two or more plumbing commands that do not refresh the index by themselves. We used to implement an equivlent of today's "git status" using "git diff-files" and "git diff-cache" (yes, we literally ran these two commands in a row to show their results in the output, one for "changes to be committed" and the other for "changes left in the working tree"), and before running these two, the scripted implementation of "git status" ran "git update-index --refresh".
Thanks.
Matěj Cepl