Arguments for git update-index --refresh

Danny Lin· Apr 15, 2022, 10:21 UTC · lore

According to the manual of git-update-index (https://git-scm.com/docs/git-update-index), --ignore-submodules must be passed before --refresh to take effect. However, a real test shows that -q and --ignore-missing also don't take effect when passed after --refresh. I wonder if --refresh must be passed after all other arguments, and the documentation may need a revision. I also wonder what is the reason that --refresh must be passed after, and can't we make it more flexible?

Junio C Hamano· Apr 15, 2022, 16:48 UTC · re: Danny Lin · lore

Re: Arguments for git update-index --refresh

Danny Lin <danny0838@gmail.com> writes:

Show 8 quoted lines

> According to the manual of git-update-index
> (https://git-scm.com/docs/git-update-index), --ignore-submodules must
> be passed before --refresh to take effect. However, a real test shows
> that -q and --ignore-missing also don't take effect when passed after
> --refresh. I wonder if --refresh must be passed after all other
> arguments, and the documentation may need a revision. I also wonder
> what is the reason that --refresh must be passed after, and can't we
> make it more flexible?

For backward compatibility reasons, it is unlikely we can change it, so it is a moot point to ask why. But anyway.

The "update-index" plumbing subcommand predates the philosophy behind our modern option parsing infrastructure; it was designed to process each option as it parse it from left to right. We do not advertise this in the documentation or help text, but we do even a strange things like this:

    git update-index fileA --add fileB

where "we allow a new path to be added to the index" option ONLY applies to fileB (in other words, if fileA is not yet added to the index, the command would barf, but fileB is allowed to be a "new" file). --remove is also the same way.

With the understanding of "each option is processed as it is parsed from left to right", you should be able to "explain" [*1*] the behaviour you observed, better than relying on the description in the document, e.g. "only respected when passed before" [*2*], which is not technically wrong but does not tell you the real reason.

[Footnote]

*1* You should be able to explain, but you do not have to agree with
    it.  Within the context of the modern Git command set, I do not
    agree with it, but unfortunately it is too late to change it, as
    scripts people wrote over time do agree with and depend on the
    behaviour X-<.

*2* Update to remove these haphazard mention of the ordering and to
    place more stress on the "processed as it is read" nature of the
    options in the documentation may help users.