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

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

[Matěj Cepl]

I met this command in the wild and I spent a lot of time to
understand what it is good for.
---
 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
+----------------
+
 
 SKIP-WORKTREE BIT
 -----------------
-- 
2.47.1

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

[Junio C Hamano]

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.

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

[Matěj Cepl]

[-- Attachment #1.1.1: Type: text/plain, Size: 1162 bytes --]

On Mon Dec 2, 2024 at 4:01 AM CET, Junio C Hamano wrote:
> Missing sign-off.

Whoopsie! I am sorry, but given that I am probably withdrawing my
submission anyway, it is not relevant, I guess.

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

I’ve got the idea from https://groups.google.com/g/git-mentoring/c/mJnuzbUqyAQ/m/02Pr9uhmAAAJ ,
so I thought it something one does.

Best,

Matěj

-- 
http://matej.ceplovi.cz/blog/, @mcepl@floss.social
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
All men's miseries derive from not being able to sit in a quiet
room alone.
  -- Blaise Pascal


[-- Attachment #1.2: E09FEF25D96484AC.asc --]
[-- Type: application/pgp-keys, Size: 3102 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
wwCdEnRlCGlvnO78R0FgKXlt3RyzGuE=
=sxoW
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 216 bytes --]