Re: Command-line interface thoughts
- From
Jakub Narebski <jnareb@gmail.com>
- Date
- Jun 5, 2011, 11:10 UTC
- Message-ID
- <201106051311.00951.jnareb@gmail.com>
- In-Reply-To
- <BANLkTinidLbQ_FcVEiGSK91uXYWaKk7MKA@mail.gmail.com>
On Sun, 5 Jun 2011, Michael Nahas wrote:
Show 15 quoted lines
> 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.
>> See also gitcli(7) manpage for description of --index and --cached >> options (and other git command line conventions). > > Thanks for the pointer. I've now read it.
[...]
Show 5 quoted lines
>> BTW. have you read gitcli(7) manpage? > > I have now. I'd swear I've read close to 30 manpages but never > heard-of/noticed that one until you mentioned it. Thanks for the > pointer; it's good to have --index and --cached clarified.
Hmmm... gitcli(7) is linked only from git(1) and git-rev-parse(1) manpages. Perhaps link to it should be added to user-manual at least, to make it easier to find?
Show 8 quoted lines
>>> 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.
There is also kind of "meta" problem: people who do not understand English well instead of not understanding textual description of git behavior would now not understand explanation of said formal notation.
Cargill's quandary: "any design problem can be solved by adding an additional level of indirection, except for too many levels of indirection."
;-)
Show 9 quoted lines
>>> 3. Move the operations "checkout -- <file>" and "reset -- <file>" to >>> their own command names >> >> Proposed "git unadd <pathspec>..." doesn't cover all features of >> "git reset <rev> -- <path>" nor "git checkout [<rev>] -- <path>". > > I'm confused. How can it not cover all the features? I'm just > suggesting renaming the command. From "git reset -- <path>" to "git > unadd [--] <path>".
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>".)
Show 6 quoted lines
>>> 4. Deemphasize the "branch" command for creating branches. >> >> Or add "git branch --checkout <newbranch>". > > Would that operation be the different from the existing "git checkout > -b <new branch>", or just another way to write it?
No, it would be just another way to do it.
>>> My recommendations are: >>> >>> 1. Pick aliases for the next commit and the working tree that act like >>> commits on the command-line.
[...]
Show 8 quoted lines
>>> 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.
I'm sorry, I should have written it more clearly.
Show 9 quoted lines
>> 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.
Show 20 quoted lines
>>> 2. Adopt a notation for describing what commands do. >>> >>> I am sure in developer discussions there are descriptions of the >>> "commit" command as something like: >>> HEAD = new(HEAD + (NEXT-HEAD)) >>> NEXT = HEAD >> >> Basic algebra fail >> >> HEAD + (NEXT-HEAD) == NEXT >> >> Besides "git commit" creates commit from state of index, no diffing or >> patching is involved. > > I would claim that the "state of index" is an approximation of > (NEXT-HEAD). Also, the new Tree and Blob objects that get written > during the commit are another approximation of (NEXT-HEAD). Neither > of these is exactly a patch applied to HEAD, but that's the intent I > was going for with my algebraic identity. (It's not a fail; it's an > unoptimization!)
It's still fail. Git is at its repository model _snapshot_ based, not _changeset_ (delta) based. "git commit" takes _exact_ state of index, and does not care about HEAD version. Nb. your case does not cover creating root commit (including but not limited to initial commit).
If you want to describe what "git commit" does it would be:
commit = new Commit
commit^{tree} = :0: # or NEXT
commit^ = HEAD^{commit} # i.e. HEAD, but be more explicit
HEAD@ = commit # or @{0}, i.e. branch pointed by HEAD
# or HEAD itself if it is detached (no branch)
The above does not cover commit message, author and committer info,
and in some cases 'encoding' header (for commit message).Show 7 quoted lines
>>> Where "-" creates a patch between versions and + applies a patch. Git >>> already has some operators like "^", which refers to the parent of a >>> commit. Those are useful for defining things like "commit --amend": >>> HEAD = new(HEAD^ + (NEXT-HEAD^)) >>> NEXT = HEAD >> >> Which is again not true.
Again, snapshot, not delta.
Show 19 quoted lines
> [Addressed below, where the "what if HEAD is a merge commit with > multiple predecessors" is mentioned.] > >>> Having this notation and using it in the man pages will make the exact >>> nature of the operation clear. (Right now, it takes a lot of reading >>> to figure out what happens to NEXT with the various command-line >>> options of "reset".) >> >> It's not that difficult: only "git reset --soft [<rev>]" doesn't >> affect index. >> >> 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. [...]
Show 7 quoted lines
>>> [I've included git commands in a not-formal-enough notation at the end >>> of this email.] >> >> NEVERTHELESS some kind of semi-formal notation might be useful. > > I'm glad you agree. Do you think my not-formal-enough notation is a > good start or do you want to propose another notation to start from?
Well, I am not sure if it is good enough idea to waste time on it... Hmmm... maybe revctrl.org guys would be interested? Just a thought.
Show 17 quoted lines
>>> 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"!)
[...]
Show 14 quoted lines
>>> 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...
[cut]
Show 10 quoted lines
>>> "commit --amend" >>> HEAD = new(HEAD^ + (NEXT-HEAD^)) >>> NEXT = HEAD >> >> HEAD^ + (NEXT-HEAD^) == NEXT >> >> "git commit --amend" works correctly even if HEAD is a merge commit! > > Another good issue. A formal notation will need to specify how to > deal with cases of a commit with more than one predecessor.
Perhaps, in extension notation proposed for describing what "git commit" does perhaps
commit^@ = HEAD^@
or just
commit = copy(HEAD^{commit})
commit^{tree} = :0:
Note however that "git commit" has more modes. Not including exotic
ones there is "git commit -a", "git commit [--only] <file>", and
rarely used "git commit --include <file>".Show 9 quoted lines
>>> "checkout FOO" (prequires WTREE==NEXT==HEAD) >> >> No such requirement. It's all about which files differ between HEAD >> and FOO. If you start working on some file, and decide that you >> should have made the change on different branch, "git checkout FOO" >> allow to move to FOO branch... assuming that changed file has the same >> contents in HEAD and in FOO. > > Okay. I will have to think about how a formal notation can denote that...
I think that table with HEAD version, worktree version, switched to branch version, and result for plain checkout, -f/--force and -m/--merge would be a better solution than formal notation.
Show 11 quoted lines
>>> WTREE = FOO >>> NEXT = FOO >>> HEAD ::= FOO // changes the alias of HEAD to refer to FOO >> >> And this is supposed to be easier to understand? > > "checkout" is a very simple command to describe in English, so the > mathematical description will be more convoluted. I don't (yet) > understand some of the variants of "git reset" even though they are > written in English. I'm hoping a formal notation will make them > easier to understand.
Hmmm...
Show 14 quoted lines
>>> "stash save" >>> STASH = new(new(HEAD+(NEXT-HEAD))+WTREE-NEXT) >>> NEXT = HEAD >>> WTREE = HEAD >>> push(STASH) >>> "stash pop" >>> STASH = pop() >>> WTREE = HEAD + (STASH-STASH^^) >>> NEXT = HEAD + (STASH^-STASH^^) >> >> ??? > > "stash save" makes two new consecutive commits: one equal to NEXT and > another equal to WTREE.
No, "stash save" doesn't make two _consecutive_ commits. It makes a commit which has state of worktree as one parent, and state of index as other parent (i.e. a merge commit).
> (This is "STASH" above, with my unoptimizations.) > I don't know where the SHA of the final commit gets > stored, so I just created push() and pop() commands.
It is stored in 'refs/stash' and its reflog.
> Rereading the man page, the commit containing WTREE has two parents. > This notation doesn't have a way to denote that.
Right.
-- Jakub Narebski Poland