git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: Command-line interface thoughts

From
Jakub Narebski <jnareb@gmail.com>
Date
Jun 4, 2011, 21:49 UTC
Message-ID
<m339jps1wt.fsf@localhost.localdomain>
In-Reply-To
<BANLkTinTWG7YXGKZzmH0rqtt+Ob7X+2yMQ@mail.gmail.com>
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.

See also gitcli(7) manpage for description of --index and --cached options (and other git command line conventions).

> 2. Adopt a (semi-)formal notation for describing what commands do.
Whom it would help?  Not an ordinary user.
> 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>".

> 4. Deemphasize the "branch" command for creating branches.
Or add "git branch --checkout <newbranch>".
> 
> A "normal" (long) email follows.  At the end are examples of commands
> in a not-quite-so-formal notation.
Show 7 quoted lines
> ------------
> 
> I was the primary designer of the PAR2 open file format and write a
> lot of big software (application-layer multicast, etc.).  I've been
> using Git for 2 months.  I love it and I greatly admire the plumbing.
> However, the default "porcelain" has at times been more confusing than
> enlightening.
BTW. have you read gitcli(7) manpage?
Show 24 quoted lines
> I had some ideas about the porcelain and decided they were worth
> sending to the mailing list.  I ran the ideas by the two Git gurus who
> answer my questions and they agreed with them.  I wish I had the time
> to implement them but I did PAR2 when I had time off and I'm working
> now.  I apologize if any of these are repeats or have already been
> discussed to death.
> 
> 
> My recommendations are:
> 
> 1. Pick aliases for the next commit and the working tree that act like
> commits on the command-line.
> 
> By "next commit", I mean "the commit that would be generated if the
> "commit" command was run right now".  "Next commit" is not the same as
> the index.  The index is a _file_ that serves multiple purposes.
> (Think of it's state during a conflicted merge.)  But the index does
> usually hold the files that change between HEAD and the next commit.
> 
> 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.
The problem is first, that you make INDEX / STAGE / NEXT and 
WORK / WTREE *look* like commits (like pseudo symbolic refs), while
they do not *behave* like commits.
 
"git show HEAD" looks differently from "git show NEXT" or "git show WTREE".
Neither the index now working tree have a parent, or author, or commit
message.  The index (staging area) can have stages, though you sidestep
this issue by handwaving it away.  Working area has notion of tracked,
untracked ignored and untracked not ignored (other) files.   Etc., etc.

BTW. both index and worktree have their own "aliases", namely ':0:' for index (stage 0), and ':' or ':/' for top tree.

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*.

Show 6 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.

Show 5 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.
 
> 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"?

Show 5 quoted lines
> 
> Currently, to understand what commands do, I use "A Visual Git
> Reference", which has been extremely valuable to me. Kuddos to Mark
> Lodato for it.
> http://marklodato.github.com/visual-git-guide/index-en.html

Unfortunately manpages cannot really include images. Well, there is some kind of obscure graph description language for manpages ('dot' or something like that), supposedly, IIRC...

> 
> [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.
Show 7 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
Show 15 quoted lines
> 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"!)
> 
> When these file-based operations are removed from "checkout" and
> "reset", the purposes of those commands becomes clearer: "checkout"
> changes HEAD to a new branch and "reset" moves the current branch
> pointer to a different commit.  These operations may share code with
> the operations "checkout -- <file>" and "reset -- <file>", but they
> serve different purposes from the user's perspective and the user
> should have different names to refer to them.
> 
> As for naming these new commands, the "yet-another-porcelain" renames
> "reset -- <file>" to "unadd", which I like very much.

Well, that goes counter to reducing number of commands, but I quite like this name. Though "unadd <revision> -- <file>" looks a bit strange...

> 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.
Show 5 quoted lines
> 
> 4. Deemphasize the "branch" command for creating branches.
> 
> I assumed that the command "branch" was used for creating branches.
> After all, that's how it is done in the "gittutorial(7)" man page.

It _is_ used to create branches. But perhaps we should update gittutorial(7) (and check users manual)...

> However, after reviewing all the major commands, I find that it is the
> _last_ way I want to create a branch. It creates a new branch, but it
> doesn't switch HEAD to the new branch!

"checkout -b" is just shortcut for "branch" + "checkout". Very convenient one, that is...

Show 5 quoted lines
> 
> The commands that should be emphasized are "checkout -b <name>",
> "commit -b <name>", and "stash branch".  These make sense in normal
> git usage. The "branch" command has its uses but it is not usually the
> way you want to create a branch.
[...]
Show 10 quoted lines
> ----
> 
> These are just some commands written in a not-quite-formal notation.
> This notation doesn't handle a detached head, adding directories, the
> state after a conflicted "stash pop", etc.  Still, as it is, I think
> it's very informative to users for getting the gist of what command
> does.
> 
> "add foo.txt"
>    NEXT:foo.txt = WTREE:foo.txt

What about "add --intent-to-add foo.txt"? What about "add <directory>"? What about resolving merge conflicts?

Show 7 quoted lines
> "rm foo.txt"
>    delete(NEXT:foo.txt)
>    delete(WTREE:foo.txt)
> "rm --cached foo.txt"
>    delete(NEXT:foo.txt)
> "/bin/rm foo.txt"
>    delete(WTREE:foo.txt)

O.K. Note however that "git rm foo.txt" on conflicted entry would clean up conflict.

Show 5 quoted lines
> "mv foo.txt bar.txt"
>    WTREE:bar.txt = WTREE:foo.txt
>    NEXT.bar.txt = WTREE:foo.txt
>    delete(WTREE:foo.txt)
>    delete(NEXT:foo.txt)
O.K., but what is important are atomicity and safety checks.
> "checkout -- foo.txt"
>    WTREE:foo.txt = NEXT:foo.txt
> "reset -- foo.txt"
>    NEXT:foo.txt = HEAD:foo.txt
Those are not the only modes.
> "commit"
>    HEAD = new(HEAD + (NEXT-HEAD))
>    NEXT = HEAD
   HEAD + (NEXT-HEAD) == NEXT
"git commit" doesn't apply patches.
> "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!
> 
> "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.

End there is "checkout -f" and "checkout -m".
>    WTREE = FOO
>    NEXT = FOO
>    HEAD ::= FOO // changes the alias of HEAD to refer to FOO
And this is supposed to be easier to understand?
Show 9 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^^)
???
[...]
Show 5 quoted lines
> "cherry-pick FOO" (prequires WTREE==NEXT==HEAD)
>    HEAD = new(HEAD + (FOO - FOO^))
>    NEXT = HEAD
>    WTREE = HEAD
> "rebase FOO" is basically a iterated application of "cherry-pick"
Ordinary rebase isn't.
-- 
Jakub Narebski
Poland
ShadeHawk on #git
Previous: Michael NahasNext: Michael Nahas
Message 2 of 98 in “Command-line interface thoughts”
  1. Michael NahasJun 4, 2011
  2. Jakub NarebskiJun 4, 2011
  3. Michael NahasJun 5, 2011
  4. Jakub NarebskiJun 5, 2011
  5. Scott ChaconJun 5, 2011
  6. Jakub NarebskiJun 5, 2011
  7. Junio C HamanoJun 6, 2011
  8. Michael J GruberJun 6, 2011
  9. Michael NahasJun 6, 2011
  10. Jakub NarebskiJun 6, 2011
  11. Michael J GruberJun 6, 2011
  12. Jakub NarebskiJun 8, 2011
  13. Junio C HamanoJun 6, 2011
  14. Drew NorthupJun 6, 2011
  15. Junio C HamanoJun 6, 2011
  16. Michael J GruberJun 6, 2011
  17. Junio C HamanoJun 6, 2011
  18. Scott ChaconJun 6, 2011
  19. Junio C HamanoJun 6, 2011
  20. Michael J GruberJun 7, 2011
  21. Jonathan NiederJun 7, 2011
  22. Holger HellmuthJun 7, 2011
  23. Jonathan NiederJun 7, 2011
  24. Jakub NarebskiJun 7, 2011
  25. Holger HellmuthJun 8, 2011
  26. Jakub NarebskiJun 8, 2011
  27. Holger HellmuthJun 9, 2011
  28. Jakub NarebskiJun 10, 2011
  29. Holger HellmuthJun 10, 2011
  30. Jakub NarebskiJun 10, 2011
  31. Holger HellmuthJun 10, 2011
  32. git diff --added (Re: Command-line interface thoughts)Jonathan Nieder, Jun 13, 2011
  33. Miles BaderJun 13, 2011
  34. Miles BaderJun 13, 2011
  35. Jonathan NiederJun 13, 2011
  36. Junio C HamanoJun 13, 2011
  37. Junio C HamanoJun 13, 2011
  38. Holger HellmuthJun 13, 2011
  39. Michael NahasJun 13, 2011
  40. Jakub NarebskiJun 13, 2011
  41. Holger HellmuthJun 13, 2011
  42. Michael HaggertyJun 14, 2011
  43. Jakub NarebskiJun 14, 2011
  44. René ScharfeJun 7, 2011
  45. Jakub NarebskiJun 7, 2011
  46. Jakub NarebskiJun 8, 2011
  47. Michael NahasJun 8, 2011
  48. Jakub NarebskiJun 8, 2011
  49. Michael NahasJun 8, 2011
  50. Jeff KingJun 8, 2011
  51. Michael NahasJun 8, 2011
  52. Jeff KingJun 9, 2011
  53. Michael NahasJun 9, 2011
  54. Jakub NarebskiJun 10, 2011
  55. Jakub NarebskiJun 9, 2011
  56. Michael NahasJun 9, 2011
  57. Jakub NarebskiJun 9, 2011
  58. Jakub NarebskiJun 9, 2011
  59. Michael HaggertyJun 9, 2011
  60. Andreas EricssonJun 9, 2011
  61. Thomas RastJun 9, 2011
  62. Jeff KingJun 9, 2011
  63. Jay SoffianJun 9, 2011
  64. Jeff KingJun 9, 2011
  65. Junio C HamanoJun 9, 2011
  66. Jay SoffianJun 9, 2011
  67. Junio C HamanoJun 9, 2011
  68. Michael HaggertyJun 9, 2011
  69. Junio C HamanoJun 9, 2011
  70. Michael HaggertyJun 9, 2011
  71. Jeff KingJun 9, 2011
  72. Michael HaggertyJun 9, 2011
  73. Jakub NarebskiJun 9, 2011
  74. Michael HaggertyJun 9, 2011
  75. Jakub NarebskiJun 10, 2011
  76. Michael NahasJun 10, 2011
  77. Jakub NarebskiJun 10, 2011
  78. Jeff KingJun 9, 2011
  79. Michael NahasJun 9, 2011
  80. Jeff KingJun 9, 2011
  81. Jakub NarebskiJun 9, 2011
  82. Michael NahasJun 10, 2011
  83. Jeff KingJun 10, 2011
  84. Junio C HamanoJun 10, 2011
  85. Junio C HamanoJun 10, 2011
  86. Jakub NarebskiJun 10, 2011
  87. Michael HaggertyJun 12, 2011
  88. Junio C HamanoJun 12, 2011
  89. Michael NahasJun 12, 2011
  90. Junio C HamanoJun 12, 2011
  91. Michael NahasJun 13, 2011
  92. Jeff KingJun 13, 2011
  93. Jeff KingJun 9, 2011
  94. Paul EbermannJun 5, 2011
  95. Paul EbermannJun 5, 2011
  96. Michael NahasJun 7, 2011
  97. Junio C HamanoJun 7, 2011
  98. Michael NahasJun 7, 2011

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.