| Message ID | 20210811045727.2381-7-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | stage: officially start moving to "staging area" | expand |
On 11/08/21 11.57, Felipe Contreras wrote: > @@ -12,6 +12,7 @@ SYNOPSIS > 'git stage' [options] [--] [<paths>...] > 'git stage' (-a | --add) [options] [--] [<paths>...] > 'git stage' (-r | --remove) [options] [--] [<paths>...] > +'git stage' (-d | --diff) [options] [--] [<paths>...] > > > DESCRIPTION > @@ -32,11 +33,15 @@ OPTIONS > --remove:: > Remove changes from the staging area. See linkgit:git-reset[1]. > > +-d:: > +--diff:: > + View the changes staged for the next commit. See linkgit:git-diff[1]. > Is it synonym to `git diff --staged`?
Bagas Sanjaya wrote: > On 11/08/21 11.57, Felipe Contreras wrote: > > @@ -12,6 +12,7 @@ SYNOPSIS > > 'git stage' [options] [--] [<paths>...] > > 'git stage' (-a | --add) [options] [--] [<paths>...] > > 'git stage' (-r | --remove) [options] [--] [<paths>...] > > +'git stage' (-d | --diff) [options] [--] [<paths>...] > > > > > > DESCRIPTION > > @@ -32,11 +33,15 @@ OPTIONS > > --remove:: > > Remove changes from the staging area. See linkgit:git-reset[1]. > > > > +-d:: > > +--diff:: > > + View the changes staged for the next commit. See linkgit:git-diff[1]. > > > > Is it synonym to `git diff --staged`? Yes, it's the same thing. Although from discussions in 2013 people found it odd that the option is --staged when specifying something that affects the future. It should probably be `git diff --stage`.
Bagas Sanjaya <bagasdotme@gmail.com> writes: > On 11/08/21 11.57, Felipe Contreras wrote: >> @@ -12,6 +12,7 @@ SYNOPSIS >> 'git stage' [options] [--] [<paths>...] >> 'git stage' (-a | --add) [options] [--] [<paths>...] >> 'git stage' (-r | --remove) [options] [--] [<paths>...] >> +'git stage' (-d | --diff) [options] [--] [<paths>...] >> >> DESCRIPTION >> @@ -32,11 +33,15 @@ OPTIONS >> --remove:: >> Remove changes from the staging area. See linkgit:git-reset[1]. >> +-d:: >> +--diff:: >> + View the changes staged for the next commit. See linkgit:git-diff[1]. >> > > Is it synonym to `git diff --staged`? Looks like it. A more notable aspect of the above list is not the similarity but difference from the rest of Git. The above organizes various operations on the staging area in a single command as its operating modes, so you'd use "git stage --diff" for comparing with the staging area but use something else ("git commit --diff HEAD"???). It is a good example that illustrates that the proposed organization may not help learning or using the system for operations that also apply to other things like commit and working tree (in other words, "git stage --grep" may not be such a good idea for the same reason as "git stage --diff"). But if it were limited to operations that apply only to the index (e.g. "git add" and "git rm"), it may be an improvement (I think we added "git stage" synonym exactly for that reason, already). Having said that, if we added "git stage --remove", there may be complaints that say "the stage command does too many things", just like those that caused "checkout" to be split into "restore" (check out contents for selected paths in order to work on the current branch) and "switch" (check out a branch in order to start working on it). I dunno.
Junio C Hamano wrote: > A more notable aspect of the above list is not the similarity but > difference from the rest of Git. The above organizes various > operations on the staging area in a single command as its operating > modes, so you'd use "git stage --diff" for comparing with the > staging area but use something else ("git commit --diff HEAD"???). It is not different from the rest of git: * git branch --delete * git tag --delete * git remote remove * git stash drop * git worktree remove * git submodule add * git config --edit * git notes remove * git bundle create * git bisect start Plus it's not unusual for commands and options to be redundant, especially when they attempt to simplify or improve the user interface, starting with `git checkout` / `git switch`. > It is a good example that illustrates that the proposed organization > may not help learning or using the system for operations that also > apply to other things like commit and working tree (in other words, > "git stage --grep" may not be such a good idea for the same reason > as "git stage --diff"). But if it were limited to operations that > apply only to the index (e.g. "git add" and "git rm"), it may be an > improvement (I think we added "git stage" synonym exactly for that > reason, already). > > Having said that, if we added "git stage --remove", there may be > complaints that say "the stage command does too many things", Or there might not. > just like those that caused "checkout" to be split into "restore" > (check out contents for selected paths in order to work on the current > branch) and "switch" (check out a branch in order to start working on > it). I dunno. I don't see many people complaining that `git branch` does "too many things", neither `git stash` or any of the commands listed above. Moreover, you are not addressing the most interesting thing my proposal enables: git stage --edit
On Wed, Aug 11, 2021 at 09:00:18AM -0700, Junio C Hamano wrote: > A more notable aspect of the above list is not the similarity but > difference from the rest of Git. The above organizes various > operations on the staging area in a single command as its operating > modes, so you'd use "git stage --diff" for comparing with the > staging area but use something else ("git commit --diff HEAD"???). > > It is a good example that illustrates that the proposed organization > may not help learning or using the system for operations that also > apply to other things like commit and working tree (in other words, > "git stage --grep" may not be such a good idea for the same reason > as "git stage --diff"). But if it were limited to operations that > apply only to the index (e.g. "git add" and "git rm"), it may be an > improvement (I think we added "git stage" synonym exactly for that > reason, already). One thing I find off-putting about "git stage --diff" is that to me, "stage" reads as a verb. So it is like "git add --diff", which seems out-of-place; there are two verbs in a row. I do not mind the term "staging area", but using "the stage" as a noun is simply confusing to me in this context. -Peff
Jeff King wrote: > On Wed, Aug 11, 2021 at 09:00:18AM -0700, Junio C Hamano wrote: > > > A more notable aspect of the above list is not the similarity but > > difference from the rest of Git. The above organizes various > > operations on the staging area in a single command as its operating > > modes, so you'd use "git stage --diff" for comparing with the > > staging area but use something else ("git commit --diff HEAD"???). > > > > It is a good example that illustrates that the proposed organization > > may not help learning or using the system for operations that also > > apply to other things like commit and working tree (in other words, > > "git stage --grep" may not be such a good idea for the same reason > > as "git stage --diff"). But if it were limited to operations that > > apply only to the index (e.g. "git add" and "git rm"), it may be an > > improvement (I think we added "git stage" synonym exactly for that > > reason, already). > > One thing I find off-putting about "git stage --diff" is that to me, > "stage" reads as a verb. So it is like "git add --diff", which seems > out-of-place; there are two verbs in a row. > > I do not mind the term "staging area", but using "the stage" as a noun > is simply confusing to me in this context. OK, but "stage" can be a noun. Here is one of the definitions: : a center of attention or scene of action This definition doesn't imply what the action is about, but "commit stage" should be perfectly aligned with that definition. Here's another one: : one of two or more sections of a rocket that have their own fuel and engine These rocket stages need to be prepared before the launch, just like changes before a commit. A commit can be thought of as a single-stage rocket, and just like parts can be added and removed from this single-stage before launch, so can changes before a commit. I understand why this might not seem natural to native English speakers, but it's perfectly aligned with the etymology of the word "stage" (to stay). I'm not saying it should be thought of this way, merely that it *can*. Either way, I also thought about adding yet another command `git staging-area` and diff instead of an option be a subcommand: `git staging-area diff`, but to be frank I don't think anybody would end up using this command, especially without default aliases (like `git sa`). So I opted against it. Even though `git stage --diff` is not ideal, it's the least bad option in my option.
Jeff King venit, vidit, dixit 2021-08-11 21:06:47: > On Wed, Aug 11, 2021 at 09:00:18AM -0700, Junio C Hamano wrote: > > > A more notable aspect of the above list is not the similarity but > > difference from the rest of Git. The above organizes various > > operations on the staging area in a single command as its operating > > modes, so you'd use "git stage --diff" for comparing with the > > staging area but use something else ("git commit --diff HEAD"???). > > > > It is a good example that illustrates that the proposed organization > > may not help learning or using the system for operations that also > > apply to other things like commit and working tree (in other words, > > "git stage --grep" may not be such a good idea for the same reason > > as "git stage --diff"). But if it were limited to operations that > > apply only to the index (e.g. "git add" and "git rm"), it may be an > > improvement (I think we added "git stage" synonym exactly for that > > reason, already). > > One thing I find off-putting about "git stage --diff" is that to me, > "stage" reads as a verb. So it is like "git add --diff", which seems > out-of-place; there are two verbs in a row. > > I do not mind the term "staging area", but using "the stage" as a noun > is simply confusing to me in this context. I think this exemplifies what I meant by discussing things in order. The concept "staging area" works in teaching and explaining things. But that does not imply that a "stage command" is the best way to convey that concept in the UI. Formost, "staging area" is a conceptual item much like a "commit", a "rev", a "reference", a "working tree" etc. When it comes to the UI, I don't think we have any concept or guide to decide what are verbs and nouns, what ends up as a command and what as an option or argument. In particular: Do we say "git verb object" or "git object verb"? Consequently, the status quo provides conflicting examples to follow. Take "git branch" and "git tag": Both use the term as a noun when they list the refs (but in singular form) and as a verb when they create them. The difference between "list" and "create" is indicated only by the absence or presence of an argument. We are used to that, and it's convenient, but it's certainly not good UI. For other subcommands, they use options like "-m" etc. "git remote", "git submodule" use arguments to indicate subcommands. At least, they stay within their "realm" ("git branch" acting on branch refs etc.). The staging area/index is necessarily something that you not only "list" or act on, but also compare to other items, or create other items from (a commit). A very "non-verby" conceptual item, instead an "object" (in linguistic terms). Therefore, "git stage" as an alias to "git add" does not serve the purpose of establishing "staging area" very well, and "git stage --diff" shows exactly the problem with turning an "object-like item" into a "verb-like command". In fact: "It adds the current state of pathspec to the staging area" is a perfect answer to the question: "What does git add pathspec do?" I mean, so much of git is about operating on or comparing between three different types of "sources": the working tree, the index, a treeish. A lot of confusion comes from the fact that we hide this behind different commands to act on them and different ways to specify these conceptual items: - You specify a treeish as an argument to a command. - You specify the index as an option (--cached, --staged) or by choosing the right command. - You specify the working tree as an option (--worktree) or by choosing the right command (checkout vs. reset) or number of options (diff). Newer commands like "restore" try to help but fail badly when e.g. "restore --staged" means you overwrite what is staged with something from a treeish. I still think it's very worthwhile to fantasize about a git which has only verb-like commands (such as diff, add, checkout, checkin) and a consistent way of specifying the objects to act upon (possibly amended by "git pluralnoun" being synonymous to "git ls noun" or similar convenience shortcuts). Michael
On Wed, Aug 11, 2021 at 03:18:45PM -0500, Felipe Contreras wrote: > > One thing I find off-putting about "git stage --diff" is that to me, > > "stage" reads as a verb. So it is like "git add --diff", which seems > > out-of-place; there are two verbs in a row. > > > > I do not mind the term "staging area", but using "the stage" as a noun > > is simply confusing to me in this context. > > OK, but "stage" can be a noun. > > Here is one of the definitions: > > : a center of attention or scene of action > > This definition doesn't imply what the action is about, but > "commit stage" should be perfectly aligned with that definition. > > Here's another one: > > : one of two or more sections of a rocket that have their own fuel and engine Sure, I know the various meanings of "stage" in English. But I do not find it a synonym for "staging area" at all. Now my opinion may not matter, but: - I thought the goal of using a different name was to find something that made intuitive sense to English speakers. I do not find "the stage" any better than "the index" (in fact, I find it worse). - Part of your argument seems to be "many people expressed an opinion that the term 'staging area' was a good idea". My name was among them. But in the very email from which you quoted me, I am arguing that "staging area" makes sense to me, but "the stage" does not. -Peff
On Wed, Aug 11, 2021 at 10:19:06PM +0200, Michael J Gruber wrote: > > > It is a good example that illustrates that the proposed organization > > > may not help learning or using the system for operations that also > > > apply to other things like commit and working tree (in other words, > > > "git stage --grep" may not be such a good idea for the same reason > > > as "git stage --diff"). But if it were limited to operations that > > > apply only to the index (e.g. "git add" and "git rm"), it may be an > > > improvement (I think we added "git stage" synonym exactly for that > > > reason, already). > > > > One thing I find off-putting about "git stage --diff" is that to me, > > "stage" reads as a verb. So it is like "git add --diff", which seems > > out-of-place; there are two verbs in a row. > > > > I do not mind the term "staging area", but using "the stage" as a noun > > is simply confusing to me in this context. > > I think this exemplifies what I meant by discussing things in order. The > concept "staging area" works in teaching and explaining things. But > that does not imply that a "stage command" is the best way to convey > that concept in the UI. Yeah, I agree very much that saying "the term staging area makes sense" does not imply that the "stage command" is a good idea. > I mean, so much of git is about operating on or comparing between three > different types of "sources": the working tree, the index, a treeish. A > lot of confusion comes from the fact that we hide this behind different > commands to act on them and different ways to specify these conceptual > items: > - You specify a treeish as an argument to a command. > - You specify the index as an option (--cached, --staged) or by choosing > the right command. > - You specify the working tree as an option (--worktree) or by choosing > the right command (checkout vs. reset) or number of options (diff). > > Newer commands like "restore" try to help but fail badly when e.g. "restore > --staged" means you overwrite what is staged with something from a > treeish. Agreed. At one point[1] I half-proposed a "git put" command that would move changes between those three places (and giving a concrete name for the index and working tree so they could be specified as sources or destinations). I do still like it as a conceptual model, but IIRC it gets hairy in some of the details (e.g., "checkout -p HEAD" is still using the index as an intermediary). > I still think it's very worthwhile to fantasize about a git which has > only verb-like commands (such as diff, add, checkout, checkin) and a > consistent way of specifying the objects to act upon (possibly amended > by "git pluralnoun" being synonymous to "git ls noun" or similar > convenience shortcuts). I don't really disagree with anything in your post, but I do think a pure-verb world would be tricky in some ways. Or at least verbose. We have "git branch --delete". But "git delete" seems a little too open-ended. The concept of that verb is meaningful only in the context or a particular noun. We could call it "git delete-branch", but that doesn't really seem to make the world a better place. :) -Peff
Jeff King venit, vidit, dixit 2021-08-11 22:40:53: > I don't really disagree with anything in your post, but I do think a > pure-verb world would be tricky in some ways. Or at least verbose. We > have "git branch --delete". But "git delete" seems a little too > open-ended. The concept of that verb is meaningful only in the context > or a particular noun. We could call it "git delete-branch", but that > doesn't really seem to make the world a better place. :) In fact I think it does, because it keeps the verb-object order and avoids "verbs as options": git rm-branch git rm-tag git rm-remote git ls-branch git ls-tag git ls-remote (yeah, I know... maybe use ls-pluralform instead for all) ... Maybe: git branches aliased to "git ls-branch" etc. as convenience. For sake of convenience, if we have "ls-pluralform" (aliased to "pluralform") we could even alias "create-singularform" to "singularform". I mean, I want use this git thing myself ;) Michael
Michael J Gruber <git@grubix.eu> writes: > I still think it's very worthwhile to fantasize about a git which has > only verb-like commands (such as diff, add, checkout, checkin) and a > consistent way of specifying the objects to act upon (possibly amended > by "git pluralnoun" being synonymous to "git ls noun" or similar > convenience shortcuts). It is nice to fantasize that the world were without confusing mixture of variety of things. I am not sure if a single "git create" command that can be used to create a new commit (aka "git commit"), a new tag (aka "git tag"), or a new worktree (aka "git worktree add"), or a single "git remove" command that can be used to remove a branch (aka "git branch -d"), a tracked file (aka "git rm"), would create a more easy to learn and explain UI. At some point, I suspect that we would run out verbs more quickily than we can organize commands and concepts in a way that is easy to understand and explain by using them.
On Wed, Aug 11, 2021 at 04:40:54PM -0400, Jeff King wrote: > Agreed. At one point[1] I half-proposed a "git put" command that would > move changes between those three places (and giving a concrete name for > the index and working tree so they could be specified as sources or > destinations). I forgot my footnote. It's: https://lore.kernel.org/git/20110607200659.GA6177@sigill.intra.peff.net/ Not that I really think it's worth anybody's time to dig too far into it. -Peff
Jeff King wrote: > On Wed, Aug 11, 2021 at 03:18:45PM -0500, Felipe Contreras wrote: > > > > One thing I find off-putting about "git stage --diff" is that to me, > > > "stage" reads as a verb. So it is like "git add --diff", which seems > > > out-of-place; there are two verbs in a row. > > > > > > I do not mind the term "staging area", but using "the stage" as a noun > > > is simply confusing to me in this context. > > > > OK, but "stage" can be a noun. > > > > Here is one of the definitions: > > > > : a center of attention or scene of action > > > > This definition doesn't imply what the action is about, but > > "commit stage" should be perfectly aligned with that definition. > > > > Here's another one: > > > > : one of two or more sections of a rocket that have their own fuel and engine > > Sure, I know the various meanings of "stage" in English. But I do not find it a > synonym for "staging area" at all. Nowhere did I argue that they are synonyms. I said "stage" can be a noun. Just like "staging area" is also a noun. They do not mean the same thing. > Now my opinion may not matter, but: > > - I thought the goal of using a different name was to find something > that made intuitive sense to English speakers. I do not find "the > stage" any better than "the index" (in fact, I find it worse). We already found something more intuitive to English speakers: "staging area". > - Part of your argument seems to be "many people expressed an opinion > that the term 'staging area' was a good idea". My name was among > them. But in the very email from which you quoted me, I am arguing > that "staging area" makes sense to me, but "the stage" does not. I am perfectly aware of that. Everyone agrees "staging area" is the way to go. How that gets translated to the user interface is a *different* matter: * git diff --staged * git diff --stage * git diff --staging-area * git staging-area --diff * git stage --diff My main concern is not precisely how this term gets transcribed to the UI, it is that it actually gets done. If it's easier to start by updating the documentation to start using "staging area" since that requires less discussion about term mapping, then I'll gladly attempt that first.
Michael J Gruber wrote: > Therefore, "git stage" as an alias to "git add" does not serve the purpose > of establishing "staging area" very well, and "git stage --diff" shows > exactly the problem with turning an "object-like item" into a "verb-like > command". But "stage" can be a noun in English too. Just like "branch" can be both a verb and a noun. > I still think it's very worthwhile to fantasize about a git which has > only verb-like commands (such as diff, add, checkout, checkin) and a > consistent way of specifying the objects to act upon (possibly amended > by "git pluralnoun" being synonymous to "git ls noun" or similar > convenience shortcuts). There was a sub-thread in which we fantasized a consistent UI [1], and taking Mercurial as inspiration the way to fix some of the warts would be: git branch # verb git branches new # noun verb git branches delete # noun verb Now, it's pretty unlikely that the inconsistencies with `git branch` will ever be fixed, but we can take that as guidance for the staging area: git stage # verb git unstage # verb git staging-area add # noun verb git staging-area remove # noun verb git staging-area diff # noun verb This I think would be the most consistent way of implementing this, my only problem is that 'staging-area' is too long. Of course users could easily write aliases, but git should be easy to use by default. If git implemented default aliases as I suggested [2], then I would have no problem with 'staging-area', because the user could simply do: git sa diff But that's a very big *if*. Cheers. [1] https://lore.kernel.org/git/f0770358-be4c-a747-0851-b2fd73c1978e@mfriebe.de/ [2] http://lore.kernel.org/git/20210702100506.1422429-1-felipe.contreras@gmail.com
diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt index e2f83783b2..460a8d6228 100644 --- a/Documentation/git-stage.txt +++ b/Documentation/git-stage.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git stage' [options] [--] [<paths>...] 'git stage' (-a | --add) [options] [--] [<paths>...] 'git stage' (-r | --remove) [options] [--] [<paths>...] +'git stage' (-d | --diff) [options] [--] [<paths>...] DESCRIPTION @@ -32,11 +33,15 @@ OPTIONS --remove:: Remove changes from the staging area. See linkgit:git-reset[1]. +-d:: +--diff:: + View the changes staged for the next commit. See linkgit:git-diff[1]. SEE ALSO -------- linkgit:git-add[1] linkgit:git-reset[1] +linkgit:git-diff[1] GIT --- diff --git a/builtin/stage.c b/builtin/stage.c index 2d50b3c393..c57bb2d683 100644 --- a/builtin/stage.c +++ b/builtin/stage.c @@ -10,6 +10,7 @@ static const char *const stage_usage[] = { N_("git stage [options] [--] <paths>..."), N_("git stage --add [options] [--] <paths>..."), N_("git stage --remove [options] [--] <paths>..."), + N_("git stage --diff [options] [<commit>] [--] <paths>..."), NULL }; @@ -41,11 +42,12 @@ static int rerun(int argc, const char **argv, ...) int cmd_stage(int argc, const char **argv, const char *prefix) { - int add = 0, remove = 0; + int add = 0, remove = 0, diff = 0; struct option options[] = { OPT_BOOL_F('a', "add", &add, N_("add changes"), PARSE_OPT_NONEG), OPT_BOOL_F('r', "remove", &remove, N_("remove changes"), PARSE_OPT_NONEG), + OPT_BOOL_F('d', "diff", &diff, N_("show changes"), PARSE_OPT_NONEG), OPT_END() }; @@ -54,6 +56,8 @@ int cmd_stage(int argc, const char **argv, const char *prefix) if (remove) return rerun(argc, argv, "reset", NULL); + if (diff) + return rerun(argc, argv, "diff", "--staged", NULL); return rerun(argc, argv, "add", NULL); } diff --git a/t/t3710-stage.sh b/t/t3710-stage.sh index 834eee66d5..aab979c20c 100755 --- a/t/t3710-stage.sh +++ b/t/t3710-stage.sh @@ -35,4 +35,11 @@ test_expect_success 'unstage' ' ! in_stage bar ' +test_expect_success 'diff' ' + echo foo > foo && + git stage --add foo && + git stage --diff > out && + test_file_not_empty out +' + test_done
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/git-stage.txt | 5 +++++ builtin/stage.c | 6 +++++- t/t3710-stage.sh | 7 +++++++ 3 files changed, 17 insertions(+), 1 deletion(-)