Re: Arguments for git update-index --refresh

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

Danny Lin <danny0838@gmail.com> writes:

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