Re: Command-line interface thoughts

> On Sun, 5 Jun 2011, Michael Nahas wrote:
>> On Sat, Jun 4, 2011 at 5:49 PM, Jakub Narebski <jnareb@gmail.com> wrote:
>>> Michael Nahas <mike.nahas@gmail.com> writes:
>>>
>>>> Quick list of recommendations:
>>>>
>>>> 1. Pick aliases for the next commit and the working tree that act like
>>>>    commits on the command-line.
>>>
>>> No go.  This was asked for many times, and each time shot down.
>>> Those "aliases" / pseudo-refs looks like commits but do not behave
>>> exactly like commits.  This would increase connfusion.
>>
>> I'm glad it was discussed.  I think users would know that those
>> commits were special (they are writeable after all), but I'm sure more
>> informed people than I made the same arguments.
>
> Perhaps we should add conclusion / summary of this discussion either
> somewhere on git wiki (http://git.wiki.kernel.org), or e.g. on gitcli(7)
> manpage, so that it won't get reiterated again and again.  It is sort
> of frequently asked question^W request.

>
>>>> 2. Adopt a (semi-)formal notation for describing what commands do.
>>>
>>> Whom it would help?  Not an ordinary user.
>>
>> I think it would help experts in discussing exactly what happens.  For
>> ordinary users that are hitting an intricate case (or don't know
>> English very well), it would be good if there was something that would
>> tell them mathematically what occurs.
>
> Well, semi-formal notation could help, but I am not sure if it would
> really be easier to understand than textual description.

> What about (well, more rarely used) "git reset <commit> -- <path>"?
> But I quite like "git unadd" alias, even if "git unadd <commit> <path>"
> looks strange; we have precedent in the form of "git stage" command
> (alias).
>

>> (And renaming "git checkout -- <path>" to some
>> yet-to-be-named other command.)
>
> I think this one could be left as is, at least until a really good name
> for said replacement appears ("git revert" means something else, and
> "git revert-file" is a bit long, and can be confused with currently
> not existing but proposed and discussed "git revert <revision> <pathspec>".)

>>>> My recommendations are:
>>>>
>>>> 1. Pick aliases for the next commit and the working tree that act like
>>>> commits on the command-line.
> [...]
>>>> For the alias for the next commit and working tree, I suggest "NEXT"
>>>> and "WTREE".  Creating these aliases will make the interface more
>>>> regular. It will remove oddities like "diff --cached FOO" and replace
>>>> them with "diff NEXT FOO" and mean that "diff" and "diff FOO" can be
>>>> explained as "diff WTREE NEXT" and "diff WTREE FOO".
>>>
>>> This idea ws proposed multiple time on git mailing list, and every
>>> time it was rejected.
> [...]
>> That this idea has been brought up multiple times says that it does
>> have some merit.  But apparently not enough merit.
>
> No, this only means that people *think* it has merit.  And perhaps
> that they are poisoned by Subversion's pseudo-refs ;-P

>
>>> BTW. both index and worktree have their own "aliases", namely ':0:'
>>> for index (stage 0), and ':' or ':/' for top tree.
>>
>> Really?  Where can these aliases be used?
>
> Well, actually they _currently_ cannot be used in many places.
>
> You can view version of file as it is in the index with
>
>  $ git show :0:path/to/file
>
> You can add file from a top of project directory (given new enough git;
> I think it isn't in any released git version yet) with
>
>  $ git add :/path/to/file
>
> independently on subdirectory you are in (i.e. --full-tree).
>
>
> But the main point was meant to be that even if there was some merit
> to the pseudo-tree-ish aliases, ':0:' or '::' or ':0' would be better
> that NEXT / STAGE / INDEX that looks like symbolic refs and therefore
> commits but ain't, and ':/' would be better that WORK / WTREE.

>>> Second, it doesn't solve issue of needing --cached and/or --index
>>> swiches completely.  Those pseudo-almost-refs hide them for "git diff",
>>> "git grep", "git ls-files", perhaps "git submodule" where we *read*
>>> from index, but not for "git apply", "git rm" or "git stash" where
>>> those swicthes affect *writing*.
>>
>> I agree with you that it would not get rid of all switches.  I never
>> expected it to.  My major aim was to simplify things like the "diff"
>> command, which I have trouble remembering the different variations of.

> You miss the point of this.  The issue is that you have to learn about
> '--cached' and '--index' *anyway* (because pseudo-almost-refs do not
> solve everything), and for consistency and backward compatibility we
> need to support '--cached' for "git diff" etc., so you proposal brings
> nothing but new thing to learn (and not only syntax, but quirks as well).
>
> So you only add to required knowledgebase, not reduce it.

>>> Hrmmm... how this notation would explain differences between
>>> "git reset --hard", "git reset --keep" and "git reset --merge"?
>>
>> I don't understand what "git reset --keep" and "git reset --merge" do.
>> I've read the manpage but am still confused.  One of my reasons for
>> suggesting a notation is so that there is a clear mathematical
>> representation of what the commands do.  Once I understand them, I can
>> make an attempt at a notation that can explain them.
>
> What I meant here is that above notation wouldn't help explaining the
> differences between --hard, --keep and --merge.  Perhaps a table could
> help there.
>
> But IMVHO is more important for documentation to tell *when* one would
> use one or another, not how they work.

>>>> 3. Move the operations "checkout -- <file>" and "reset -- <file>" to
>>>> their own command names
>>>>
>>>> This is my biggest and most important suggestion.
>>>>
>>>> "checkout -- foo.txt" copies foo.txt from NEXT to WTREE. Similarly,
>>>> "reset -- foo.txt" will copy foo.txt from HEAD to NEXT.
>>>
>>>  "checkout HEAD -- foo.txt" copies foo.txt from HEAD to NEXT and WTREE
>>>
>>>  "checkout HEAD^ -- foo.txt" copies foo.txt from HEAD^ to NEXT and WTREE
>>>  "reset HEAD^ -- foo.txt" copies foo.txt from HEAD^ to NEXT
>>>
>>>> These are operations to designate/undesignate files in the next commit
>>>> and should be grouped with others like them: "add", "rm" and "mv". (In
>>>> fact, the man page for "reset -- <file>" even says that it is the
>>>> opposite of "add"!)
> [...]
>
>>>> For the other, my best suggestion is "head-to-next", but I'm sure
>>>> someone can do better.
>>>
>>> I'd rather remember that "git checkout" is about checking out
>>> something to a working area.
>>
>> Now that I've separated these two usages of "checkout" in my brain,
>> "git checkout <branch>" is all about changing to a different branch.
>> That files in the working tree change is just incidental to moving to
>> the new branch.
>>
>> The manpage paragraph for "git checkout -- <file>" has in bold that
>> this usage "does not switch branches".  So, for me, it's a completely
>> different usage and should be a different command.
>
> For me it is about "checking out" two different entities: a branch
> (or related case of non-branch ref, e.g. "git checkout v1.7.3", or
> "git checkout HEAD~2"), or a pathspec (file or directory).  Checking
> out branch means making it current branch, checking out file means
> making this version of a file current.
>
>> I wish I had a reasonable name to suggest for the new command.
>
> Good name is a required prerequisite here, unfortunately...