On 11/30, Junio C Hamano wrote:
>
> I am unsure about the wisdom of calling it "--index", though.
>
> The "--index" option is "the command can work only on the index, or
> only on the working tree files, or on both the index and the working
> tree files, and this option tells it to work in the 'both the index
> and the working tree files' mode", but when "restore-files" touches
> paths, it always modifies both the index and the working tree, so
> the "--index" option does not capture the differences well in this
> context [*1*]. As I saw this was described as "not using the usual
> 'overlay' semantics [*2*]", perhaps --overlay/--no-overlay option
> that defaults to --no-overlay is easier to explain.
Agreed, I think --{no-,}overlay is a much better name for the option,
I'll use that for my patch series (I hope to send that soon after 2.20
is released).
I must admit that I was not aware that the mode is called overlay
mode, before you explained it to me, so I wouldn't expect most users
to know either. But as it's easy to explain that probably doesn't
matter much.
> side note 1. I think the original mention of "--index" came in
> the context of contrasting "git reset" with "git checkout".
> "git reset (--hard|--mixed) -- <pathspec>" (that does not move
> HEAD), which does not but perhaps should exist, is very much
> like "git checkout -- <pathspec>", and if "reset" were written
> after the "--index/--cached" convention was established, "reset
> --hard" would have called "reset --index" while "reset --mixed"
> would have been "reset --cached" (i.e. only work on the index
> and not on the working tree). And "reset --index <directory>"
> would have worked by removing paths in <directory> that are not
> in the HEAD and updating paths in <directory> that are in the
> HEAD, i.e. identical to the non overlay behaviour proposed for
> the "git checkout" command. So calling the non overlay mode
> "--index" makes sense in the context of discussing "git reset",
> and not in the context of "git checkout".
>
> side note 2. "git checkout <tree-ish> <pathspec>" grabs entries
> from the <tree-ish> that patch <pathspec> and adds them to the
> index and checks them out to the working tree. If the original
> index has entries that match <pathspec> but do not appear in
> <tree-ish>, they are left in the result. That is "overlaying
> what was taken from the <tree-ish> on top of what is in the
> index".
>
> Having said all that, I will not be looking at the series until 2.20
> final. And I hope more people do the same to concentrate on helping
> us prevent the last minute glitch slipping in the final release.
>
> Thanks.
