Re: [PATCH] Documentation/git-update-index.txt: add an example of use

[Junio C Hamano <gitster@pobox.com>]

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.
> ---

Missing sign-off.

>  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.