Re: [PATCH/RFC v3 00/14] Introduce new commands switch-branch and restore-files

From: Thomas Gummerer <t.gummerer@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>,
	avarab@gmail.com, git@vger.kernel.org, sbeller@google.com,
	sxenos@google.com
Subject: Re: [PATCH/RFC v3 00/14] Introduce new commands switch-branch and restore-files
Date: Sun, 2 Dec 2018 18:58:38 +0000	[thread overview]
Message-ID: <20181202185838.GN4883@hank.intra.tgummerer.com> (raw)
In-Reply-To: <xmqqefb3mhrs.fsf@gitster-ct.c.googlers.com>

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.