Assuming the great day has come to think about this, one thing I'd love to do is to unify the name of the index/stage/cache in command-line parameters and the documentation.
The index/stage/cache should have one canonical name, and the documentation should support that consistently. My taste is to call it the "stage," but references to --index, --keep-index, --no-index, etc. are all over the code, as well as legacy references to "--cached".
* You can 'git rm --cached myfile' but you can't 'git rm --staged myfile' or 'git rm --index myfile'.
* You can 'git diff --no-index' or you can 'git diff --cached' with 'git diff --staged' as a synonym, deprioritized in the documentation ("--staged is a synonym of --cached"). But you can't 'git diff --index' or 'git diff --no-stage' or 'git diff --no-cache'.
* You can 'git stage' but 'git help stage' is only one line long, declaring that it's a synonym for 'git add'. 'add' appears in the 'git help' common commands, but not 'git stage'. There's no built-in 'git unstage', and certainly no appetite for 'git index' or 'git cache'.
* Not to mention all of the plumbing commands: checkout-index, diff-index, index-pack, merge-index, show-index, and update-index.
My understanding based on historical threads is that changes like this would be unwelcome, even just to add synonyms and standardize the documentation around "stage" as the term (leaving the plumbing commands alone), but if documentation+synonym patches are welcome here, I'd be very enthusiastic.
-Dan
> On Nov 29, 2018, at 3:05 PM, Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> wrote:
>
>
> On Thu, Nov 29 2018, Nguyễn Thái Ngọc Duy wrote:
>
>> v3 sees switch-branch go back to switch-branch (in v2 it was
>> checkout-branch). checkout-files is also renamed restore-files (v1 was
>> restore-paths). Hopefully we won't see another rename.
>>
>> I'll try to summarize the differences between the new commands and
>> 'git checkout' down here, but you're welcome to just head to 07/14 and
>> read the new man pages.
>>
>> 'git switch-branch'
>>
>> - does not "do nothing", you have to either switch branch, create a
>> new branch, or detach. "git switch-branch" with no arguments is
>> rejected.
>>
>> - implicit detaching is rejected. If you need to detach, you need to
>> give --detach. Or stick to 'git checkout'.
>>
>> - -b/-B is renamed to -c/-C with long option names
>>
>> - of course does not accept pathspec
>>
>> 'git restore-files'
>>
>> - takes a ref from --from argument, not as a free ref. As a result,
>> '--' is no longer needed. All non-option arguments are pathspec
>>
>> - pathspec is mandatory, you can't do "git restore-files" without any
>> pathspec.
>>
>> - I just remember -p which is allowed to take no pathspec :( I'll fix
>> it later.
>>
>> - Two more fancy features (the "git checkout --index" being the
>> default mode and the backup log for accidental overwrites) are of
>> course still missing. But they are coming.
>>
>> I did not go replace "detached HEAD" with "unnamed branch" (or "no
>> branch") everywhere because I think a unique term is still good to
>> refer to this concept. Or maybe "no branch" is good enough. I dunno.
>
> I finally tracked down
> https://redfin.engineering/two-commits-that-wrecked-the-user-experience-of-git-f0075b77eab1
> which I'd remembered reading and couldn't find again in these
> discussions. Re-reading it while one may not 100% agree with the
> author's opinion, it's an interesting rabbit hole.
>
> I also didn't know about EasyGit, or that Elijah Newren had written
> it. I haven't seen him chime in on this series, and would be interested
> to see what he thinks about it.
>
> Re the naming question in
> https://public-inbox.org/git/87o9abzv46.fsf@xxxxxxxxxxxxxxxxxxx/ &
> seeing that eg-switch exists, I wonder if just s/switch-branch/switch/
> makes more sense.
>
> Assuming greenfield development (which we definitely don't have), I
> don't like the "restore-files" name, but the alternative that makes
> sense is "checkout". Then this "--from" argument could become "git
> checkout-tree <treeish> -- <pathspec>", and we'd have:
>
> git switch <branchish>
> git checkout <pathspec>
> git checkout-tree <treeish> -- <pathspec>
>
> Or maybe that sucks, anyway what I was going to suggest is *if* others
> think that made sense as a "if we designed git today" endgame whether we
> could have an opt-in setting where you set e.g. core.uiVersion=3 (in
> anticipation of Git 3.0) and you'd get that behavior. There could be
> some other setting where core.uiVersion would use the old behavior (or
> with another setting, only warn) if we weren't connected to a terminal.
>
> I.e. I'm thinking of this as step #2 in a #3 step series. Where this is
> the fully backwards compatible UI improvement, but someone who'd
> e.g. use EasyGit or didn't have backwards compatibility concerns could
> enable step #3 and opt-in to a mode where we'd fixed a bunch of UI warts
> in a backwards-incompatible way.
>
> What would that mode look like? I'd to work on piling that on top of
> this :)
