* [RFC/PATCH 0/2] New 'stage' command @ 2009-04-05 13:48 Felipe Contreras 2009-04-05 13:48 ` [RFC/PATCH 1/2] git: remote stage Felipe Contreras ` (2 more replies) 0 siblings, 3 replies; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 13:48 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Felipe Contreras Hi, The 'stage' is probably the most novel-yet-missunderstood feature of git, and somehow the user interface is not exploiting it properly, even to the point where it doesn't even have a consistent name (stage, index, cache, etc) This patch series is one approach that has been working reasonably well for me, which is to replace the 'git stage' command to map different actions that can be executed with it. For example 'git stage diff' is more natural (at least to me) than 'git diff --cached', same goes for 'git stage rm foo.c' vs 'git rm --cached foo.c'. This is the list of actions I've mapped: * add: git stage = git stage add (git add) * rm: (git rm --cached) * diff: (git rm --cached) * import: stage all files; modified, deleted, new * ls: (git ls-files --stage) Felipe Contreras (2): git: remote stage Add new 'git stage' script Documentation/git-stage.txt | 19 ------------------- Makefile | 2 +- git-stage.sh | 28 ++++++++++++++++++++++++++++ git.c | 1 - 4 files changed, 29 insertions(+), 21 deletions(-) delete mode 100644 Documentation/git-stage.txt create mode 100644 git-stage.sh ^ permalink raw reply [flat|nested] 38+ messages in thread
* [RFC/PATCH 1/2] git: remote stage 2009-04-05 13:48 [RFC/PATCH 0/2] New 'stage' command Felipe Contreras @ 2009-04-05 13:48 ` Felipe Contreras 2009-04-05 13:48 ` [RFC/PATCH 2/2] Add new 'git stage' script Felipe Contreras 2009-04-05 19:02 ` [RFC/PATCH 0/2] New 'stage' command Junio C Hamano 2009-04-05 21:58 ` [RFC/PATCH 0/2] " Markus Heidelberg 2 siblings, 1 reply; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 13:48 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Felipe Contreras Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/git-stage.txt | 19 ------------------- Makefile | 1 - git.c | 1 - 3 files changed, 0 insertions(+), 21 deletions(-) delete mode 100644 Documentation/git-stage.txt diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt deleted file mode 100644 index 7f251a5..0000000 --- a/Documentation/git-stage.txt +++ /dev/null @@ -1,19 +0,0 @@ -git-stage(1) -============== - -NAME ----- -git-stage - Add file contents to the staging area - - -SYNOPSIS --------- -[verse] -'git stage' args... - - -DESCRIPTION ------------ - -This is a synonym for linkgit:git-add[1]. Please refer to the -documentation of that command. diff --git a/Makefile b/Makefile index 7867eac..0c3de6b 100644 --- a/Makefile +++ b/Makefile @@ -345,7 +345,6 @@ BUILT_INS += git-merge-subtree$X BUILT_INS += git-peek-remote$X BUILT_INS += git-repo-config$X BUILT_INS += git-show$X -BUILT_INS += git-stage$X BUILT_INS += git-status$X BUILT_INS += git-whatchanged$X diff --git a/git.c b/git.c index c2b181e..ebc3ccb 100644 --- a/git.c +++ b/git.c @@ -267,7 +267,6 @@ static void handle_internal_command(int argc, const char **argv) const char *cmd = argv[0]; static struct cmd_struct commands[] = { { "add", cmd_add, RUN_SETUP | NEED_WORK_TREE }, - { "stage", cmd_add, RUN_SETUP | NEED_WORK_TREE }, { "annotate", cmd_annotate, RUN_SETUP }, { "apply", cmd_apply }, { "archive", cmd_archive }, -- 1.6.2.2.406.g45db3f ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [RFC/PATCH 2/2] Add new 'git stage' script 2009-04-05 13:48 ` [RFC/PATCH 1/2] git: remote stage Felipe Contreras @ 2009-04-05 13:48 ` Felipe Contreras 0 siblings, 0 replies; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 13:48 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Felipe Contreras Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Makefile | 1 + git-stage.sh | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 0 deletions(-) create mode 100644 git-stage.sh diff --git a/Makefile b/Makefile index 0c3de6b..a1837fc 100644 --- a/Makefile +++ b/Makefile @@ -291,6 +291,7 @@ SCRIPT_SH += git-rebase.sh SCRIPT_SH += git-repack.sh SCRIPT_SH += git-request-pull.sh SCRIPT_SH += git-sh-setup.sh +SCRIPT_SH += git-stage.sh SCRIPT_SH += git-stash.sh SCRIPT_SH += git-submodule.sh SCRIPT_SH += git-web--browse.sh diff --git a/git-stage.sh b/git-stage.sh new file mode 100644 index 0000000..a5b3ad8 --- /dev/null +++ b/git-stage.sh @@ -0,0 +1,28 @@ +#!/bin/sh + +case "$1" in +add) + shift + git add $@ + ;; +rm) + shift + git rm --cached $@ + ;; +diff) + shift + git diff --cached $@ + ;; +import) + shift + git ls-files --modified --others --exclude-standard -z | \ + git update-index --add --remove -z --stdin + ;; +ls) + shift + git ls-files --stage $@ + ;; +*) + git add $@ + ;; +esac -- 1.6.2.2.406.g45db3f ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 13:48 [RFC/PATCH 0/2] New 'stage' command Felipe Contreras 2009-04-05 13:48 ` [RFC/PATCH 1/2] git: remote stage Felipe Contreras @ 2009-04-05 19:02 ` Junio C Hamano 2009-04-05 19:28 ` Felipe Contreras 2009-04-05 21:58 ` [RFC/PATCH 0/2] " Markus Heidelberg 2 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2009-04-05 19:02 UTC (permalink / raw) To: Felipe Contreras; +Cc: git Felipe Contreras <felipe.contreras@gmail.com> writes: > This is the list of actions I've mapped: > > * add: git stage = git stage add (git add) > * rm: (git rm --cached) > * diff: (git rm --cached) > * import: stage all files; modified, deleted, new > * ls: (git ls-files --stage) I do not think these are good ideas at all, as it just spreads more confusion, not less. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 19:02 ` [RFC/PATCH 0/2] New 'stage' command Junio C Hamano @ 2009-04-05 19:28 ` Felipe Contreras 2009-04-05 19:33 ` Junio C Hamano 2009-04-05 19:34 ` [RFC/PATCH 0/2] " Nicolas Sebrecht 0 siblings, 2 replies; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 19:28 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano <gitster@pobox.com> wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >> This is the list of actions I've mapped: >> >> * add: git stage = git stage add (git add) >> * rm: (git rm --cached) >> * diff: (git rm --cached) >> * import: stage all files; modified, deleted, new >> * ls: (git ls-files --stage) > > I do not think these are good ideas at all, as it just spreads more > confusion, not less. Do you agree that there's already a lot of confusion? (stage, cache, index, etc.) And do you agree that many git newbies don't use the stage? Actually most of them don't even know what it is, and just do "git commit -a". If so, how do you think these issues should be handled? -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 19:28 ` Felipe Contreras @ 2009-04-05 19:33 ` Junio C Hamano 2009-04-05 19:59 ` Junio C Hamano 2009-04-05 19:34 ` [RFC/PATCH 0/2] " Nicolas Sebrecht 1 sibling, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2009-04-05 19:33 UTC (permalink / raw) To: Felipe Contreras; +Cc: git Felipe Contreras <felipe.contreras@gmail.com> writes: > On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano <gitster@pobox.com> wrote: >> Felipe Contreras <felipe.contreras@gmail.com> writes: >> >>> This is the list of actions I've mapped: >>> >>> * add: git stage = git stage add (git add) >>> * rm: (git rm --cached) >>> * diff: (git rm --cached) >>> * import: stage all files; modified, deleted, new >>> * ls: (git ls-files --stage) >> >> I do not think these are good ideas at all, as it just spreads more >> confusion, not less. > > Do you agree that there's already a lot of confusion? (stage, cache, > index, etc.) > > And do you agree that many git newbies don't use the stage? Actually > most of them don't even know what it is, and just do "git commit -a". > > If so, how do you think these issues should be handled? Perhaps not spreading "stage" even wider? That is the newest confusing term that caused the most harm. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 19:33 ` Junio C Hamano @ 2009-04-05 19:59 ` Junio C Hamano 2009-04-05 20:41 ` Felipe Contreras 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2009-04-05 19:59 UTC (permalink / raw) To: Felipe Contreras; +Cc: git Junio C Hamano <gitster@pobox.com> writes: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >> On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano <gitster@pobox.com> wrote: >>> Felipe Contreras <felipe.contreras@gmail.com> writes: >>> >>>> This is the list of actions I've mapped: >>>> >>>> * add: git stage = git stage add (git add) >>>> * rm: (git rm --cached) >>>> * diff: (git rm --cached) >>>> * import: stage all files; modified, deleted, new >>>> * ls: (git ls-files --stage) >>> >>> I do not think these are good ideas at all, as it just spreads more >>> confusion, not less. >> >> Do you agree that there's already a lot of confusion? (stage, cache, >> index, etc.) >> >> And do you agree that many git newbies don't use the stage? Actually >> most of them don't even know what it is, and just do "git commit -a". >> >> If so, how do you think these issues should be handled? > > Perhaps not spreading "stage" even wider? That is the newest confusing > term that caused the most harm. This probably needs clarification for new people who do not know the history. Before Linus published the very original git, he was designing a system that can work with the tarball+patches workflow, and dircache (which was the name of the .git directory) was a mechanism to give various snapshots a faster access by using the git object machinery by "caching" the result of applying sequence of patches to certain point of history. The file inside the .dircache that records the object names that correspond to the state in the work tree state was .dircache/index. We've been living with the cache/index, and many user visible actions have been called in sentences like "adding contents to the cache" or "comparing with the index" that used cache/index more or less interchangeably. Later we started to standardizing on the term "index" primarily because that is the entity on the filesystem the end user is aware of (as opposed to "cache" that still live throughout the code). Some operations however needed to have two modes of operation, one being working on both work tree files and the index and another being working only on the index. Most of the time, the former was the default (and the only mode implemented) and the latter mode needed an explicit option to ask for. --cached is used when you ask them to ignore work tree (i.e. "git apply --cached", "git diff --cached"). Unfortunately apply has a third variant that works only on the work tree and because it is meant as a replacement of GNU patch that works outside a git repository, that mode is the default, and you need to ask with "git apply --index" to affect both the index and the work tree. If we were already well into "standardize on index, not telling the end-users about cache" journey back then, and --cached should have been called --index-only, but unfortunately the history was the other way around. Later, some outside people started "git training industry" without talking with the git development community and started using a new term "to stage" as a verb to describe "add to the index". Addition of "git diff --staged" was supposed to lesson the confusion resulted from this mess, but as we can see from your patch it had a reverse effect. I do not think "to stage" as the name of the _concept_ is a bad thing per-se. But the name of the concept and the command verb (and option name) does not have to agree with each other. cf. http://gitster.livejournal.com/19427.html In retrospect, I think it might have been less problematic if we firmly rejected "stage" as an option name, but instead renamed the --cached option to --index-only and made the former a synonym to the latter to really standardize on "index". I think it still is Ok to use the word "to stage" to colloquially call the act of "adding to index", but if we did not add that to the UI but kept it strictly at the concept level, it would have made the UI less confusing, not more. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 19:59 ` Junio C Hamano @ 2009-04-05 20:41 ` Felipe Contreras 2009-04-05 20:55 ` Jay Soffian 0 siblings, 1 reply; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 20:41 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Sun, Apr 5, 2009 at 10:59 PM, Junio C Hamano <gitster@pobox.com> wrote: > Junio C Hamano <gitster@pobox.com> writes: > >> Felipe Contreras <felipe.contreras@gmail.com> writes: >> >>> On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano <gitster@pobox.com> wrote: >>>> Felipe Contreras <felipe.contreras@gmail.com> writes: >>>> >>>>> This is the list of actions I've mapped: >>>>> >>>>> * add: git stage = git stage add (git add) >>>>> * rm: (git rm --cached) >>>>> * diff: (git rm --cached) >>>>> * import: stage all files; modified, deleted, new >>>>> * ls: (git ls-files --stage) >>>> >>>> I do not think these are good ideas at all, as it just spreads more >>>> confusion, not less. >>> >>> Do you agree that there's already a lot of confusion? (stage, cache, >>> index, etc.) >>> >>> And do you agree that many git newbies don't use the stage? Actually >>> most of them don't even know what it is, and just do "git commit -a". >>> >>> If so, how do you think these issues should be handled? >> >> Perhaps not spreading "stage" even wider? That is the newest confusing >> term that caused the most harm. > > This probably needs clarification for new people who do not know the > history. Thanks for the clarification. <snip/> Consider this: == cache == This word is barely used in the English language, perhaps only used in computing nowadays. The 'cache' is often referred to a place for temporary storage, the purpose being rapid access. It is usually transparent to the user. Git uses the term in a completely different manner and the --cached option is used in important command such as rm and diff. However, people rarely use the term "git cache", probably because it immediately evokes multiple caches for better performances. == index == It is unclear to me what the word means in English language, but it is generally used as a list of things, the purpose being for easy retrieval. Again, git is using the term in a different manner, however it is the most widely used term to identify the concept "the git index", probably due to the fact that the word "index" evokes a single entity. But for some reason it's not used in any important commands as '--index' or '--indexed'. == stage == The word "stage" is used widely in the English language, and it immediately evokes a theatrical stage. Generally, it means a different (upper) level. In git it is barely used, mostly on the "documentation industry" probably because it's easier to understand for most people (even non-native-English speakers). Ideally the term should evoke the concept of a *single* area that has no other purpose to differentiate from the contents of the working directory. Also, the action to add and remove content from this area should sound natural. That rules out "cache" since "uncache" makes no sense. Something similar happens with "unindex", although it doesn't sound completely bad. On the other hand "stage" and "unstage" sound perfectly fine. > I do not think "to stage" as the name of the _concept_ is a bad thing > per-se. But the name of the concept and the command verb (and option > name) does not have to agree with each other. > > cf. http://gitster.livejournal.com/19427.html > > In retrospect, I think it might have been less problematic if we firmly > rejected "stage" as an option name, but instead renamed the --cached > option to --index-only and made the former a synonym to the latter to > really standardize on "index". I think it still is Ok to use the word "to > stage" to colloquially call the act of "adding to index", but if we did > not add that to the UI but kept it strictly at the concept level, it would > have made the UI less confusing, not more. Why is it so natural to co-relate "stage" to "adding to the index"? Would such a relation make sense outside of the git world? No. It is natural to you because you already know what is the "git index"... it is a *staging* area for commit preparation, logically it's natural to co-relate this area with the action "to stage". Please note it is not an _indexing_ area, nor a _caching_ area. I agree that the internal (plumbing) term does not need to match the conceptual term (used in documentation, tutorials, etc.), but the higher level (porcelain) term *must* match in order for new comers to grasp it quickly and avoid confusion. I understand there are historic reasons for the names "cache" and "index" and those should be thought before considering any change. But also consider that I'm not proposing any big change... the term "stage" is already being used, and there's already a "git stage" command. I'm only proposing to add a few more options :) I would be very pleased if you could at least try the patch for a few days, and try "git stage diff" (or "git s diff" with an alias). I've become very fond of "git s" "git s diff" and "git s -p -u". Cheers. -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 20:41 ` Felipe Contreras @ 2009-04-05 20:55 ` Jay Soffian 2009-04-05 22:06 ` Felipe Contreras 0 siblings, 1 reply; 38+ messages in thread From: Jay Soffian @ 2009-04-05 20:55 UTC (permalink / raw) To: Felipe Contreras; +Cc: Junio C Hamano, git On Sun, Apr 5, 2009 at 4:41 PM, Felipe Contreras <felipe.contreras@gmail.com> wrote: > == stage == > > The word "stage" is used widely in the English language, and it > immediately evokes a theatrical stage. Generally, it means a different > (upper) level. > > In git it is barely used, mostly on the "documentation industry" > probably because it's easier to understand for most people (even > non-native-English speakers). Would an index by any other name smell as sweet? http://www.merriam-webster.com/dictionary/staging%20area :-) j. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 20:55 ` Jay Soffian @ 2009-04-05 22:06 ` Felipe Contreras 0 siblings, 0 replies; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 22:06 UTC (permalink / raw) To: Jay Soffian; +Cc: Junio C Hamano, git On Sun, Apr 5, 2009 at 11:55 PM, Jay Soffian <jaysoffian@gmail.com> wrote: > On Sun, Apr 5, 2009 at 4:41 PM, Felipe Contreras > <felipe.contreras@gmail.com> wrote: >> == stage == >> >> The word "stage" is used widely in the English language, and it >> immediately evokes a theatrical stage. Generally, it means a different >> (upper) level. >> >> In git it is barely used, mostly on the "documentation industry" >> probably because it's easier to understand for most people (even >> non-native-English speakers). > > Would an index by any other name smell as sweet? Yeap, almost. Do you have in mind any other word that would fit? -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* [RFC/PATCH 0/2] Re: New 'stage' command 2009-04-05 19:28 ` Felipe Contreras 2009-04-05 19:33 ` Junio C Hamano @ 2009-04-05 19:34 ` Nicolas Sebrecht 1 sibling, 0 replies; 38+ messages in thread From: Nicolas Sebrecht @ 2009-04-05 19:34 UTC (permalink / raw) To: Felipe Contreras; +Cc: Junio C Hamano, git On Sun, Apr 05, 2009 at 10:28:24PM +0300, Felipe Contreras wrote: > > I do not think these are good ideas at all, as it just spreads more > > confusion, not less. Agreed. > Do you agree that there's already a lot of confusion? (stage, cache, > index, etc.) > > And do you agree that many git newbies don't use the stage? Actually > most of them don't even know what it is, and just do "git commit -a". > > If so, how do you think these issues should be handled? Read the documentation? Read tutorials? -- Nicolas Sebrecht ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 13:48 [RFC/PATCH 0/2] New 'stage' command Felipe Contreras 2009-04-05 13:48 ` [RFC/PATCH 1/2] git: remote stage Felipe Contreras 2009-04-05 19:02 ` [RFC/PATCH 0/2] New 'stage' command Junio C Hamano @ 2009-04-05 21:58 ` Markus Heidelberg 2009-04-05 22:35 ` Felipe Contreras 2 siblings, 1 reply; 38+ messages in thread From: Markus Heidelberg @ 2009-04-05 21:58 UTC (permalink / raw) To: Felipe Contreras; +Cc: git, Junio C Hamano Felipe Contreras, 05.04.2009: > For example 'git stage diff' is more natural (at least to me) than 'git diff > --cached', same goes for 'git stage rm foo.c' vs 'git rm --cached foo.c'. Not for me. If I want to GET a diff, I want to use a command "diff", so "git diff" is more obvious. The next step is to say WHAT exactly to diff. Therefor options to the "diff" command are more logically to me from a hierarchic POV. And here I don't think options like "--cached" or "sha1..sha2", despite having different style, make any difference. Markus ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 21:58 ` [RFC/PATCH 0/2] " Markus Heidelberg @ 2009-04-05 22:35 ` Felipe Contreras 2009-04-05 23:06 ` Björn Steinbrink 2009-04-05 23:17 ` Markus Heidelberg 0 siblings, 2 replies; 38+ messages in thread From: Felipe Contreras @ 2009-04-05 22:35 UTC (permalink / raw) To: markus.heidelberg; +Cc: git, Junio C Hamano On Mon, Apr 6, 2009 at 12:58 AM, Markus Heidelberg <markus.heidelberg@web.de> wrote: > Felipe Contreras, 05.04.2009: >> For example 'git stage diff' is more natural (at least to me) than 'git diff >> --cached', same goes for 'git stage rm foo.c' vs 'git rm --cached foo.c'. > > Not for me. If I want to GET a diff, I want to use a command "diff", so > "git diff" is more obvious. > The next step is to say WHAT exactly to diff. Therefor options to the > "diff" command are more logically to me from a hierarchic POV. And here > I don't think options like "--cached" or "sha1..sha2", despite having > different style, make any difference. Well, it's a matter of preference, and you would not loose the option to do it the way you like. But actually, "git diff --cached" is a different action; you can't do "git diff --cached HEAD^.." for example. Consider "git rm foo.c" vs "git rm --cached foo.c"... both commands are removing a file, the only difference is that one is removing from the staging area while the other is removing it from the working directory. Now think about "git branch -d bar", following the "first I specify the action, and then the object" thinking, would it make sense to have "git rm --branch bar"? Probably not; if you want to do stuff with branches, you use "git branch", similarly, if you want to do stuff with the staging area, why not use "git stage"? -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 22:35 ` Felipe Contreras @ 2009-04-05 23:06 ` Björn Steinbrink 2009-04-05 23:23 ` Markus Heidelberg 2009-04-05 23:17 ` Markus Heidelberg 1 sibling, 1 reply; 38+ messages in thread From: Björn Steinbrink @ 2009-04-05 23:06 UTC (permalink / raw) To: Felipe Contreras; +Cc: markus.heidelberg, git, Junio C Hamano On 2009.04.06 01:35:24 +0300, Felipe Contreras wrote: > On Mon, Apr 6, 2009 at 12:58 AM, Markus Heidelberg > <markus.heidelberg@web.de> wrote: > > Felipe Contreras, 05.04.2009: > >> For example 'git stage diff' is more natural (at least to me) than 'git diff > >> --cached', same goes for 'git stage rm foo.c' vs 'git rm --cached foo.c'. > > > > Not for me. If I want to GET a diff, I want to use a command "diff", so > > "git diff" is more obvious. > > The next step is to say WHAT exactly to diff. Therefor options to the > > "diff" command are more logically to me from a hierarchic POV. And here > > I don't think options like "--cached" or "sha1..sha2", despite having > > different style, make any difference. > > Well, it's a matter of preference, and you would not loose the option > to do it the way you like. But actually, "git diff --cached" is a > different action; you can't do "git diff --cached HEAD^.." for > example. Sure you can. It diffs the index against HEAD^ > Consider "git rm foo.c" vs "git rm --cached foo.c"... both commands > are removing a file, the only difference is that one is removing from > the staging area while the other is removing it from the working > directory. The working tree _and_ the index. To delete it only from the working tree you need "rm", not "git rm". > Now think about "git branch -d bar", following the "first I > specify the action, and then the object" thinking, would it make sense > to have "git rm --branch bar"? Probably not; if you want to do stuff > with branches, you use "git branch", similarly, if you want to do > stuff with the staging area, why not use "git stage"? If you're going that way, you'll also need "clone create", "working-tree grep", "repo/remote fetch/pull/push", etc. "git branch", "git tag", "git remote" and maybe "git status" are the "outsiders", in that the commands (in some forms) end up as "git <object> <action>" form. The rest is "git <action> <object>". So "git stage <action>" would extend the minority, and not lead to unification. Björn ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 23:06 ` Björn Steinbrink @ 2009-04-05 23:23 ` Markus Heidelberg 2009-04-06 9:48 ` Björn Steinbrink 0 siblings, 1 reply; 38+ messages in thread From: Markus Heidelberg @ 2009-04-05 23:23 UTC (permalink / raw) To: Björn Steinbrink; +Cc: Felipe Contreras, git, Junio C Hamano Björn Steinbrink, 06.04.2009: > On 2009.04.06 01:35:24 +0300, Felipe Contreras wrote: > > Well, it's a matter of preference, and you would not loose the option > > to do it the way you like. But actually, "git diff --cached" is a > > different action; you can't do "git diff --cached HEAD^.." for > > example. > > Sure you can. It diffs the index against HEAD^ No, note the ".." Markus ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 23:23 ` Markus Heidelberg @ 2009-04-06 9:48 ` Björn Steinbrink 0 siblings, 0 replies; 38+ messages in thread From: Björn Steinbrink @ 2009-04-06 9:48 UTC (permalink / raw) To: Markus Heidelberg; +Cc: Felipe Contreras, git, Junio C Hamano On 2009.04.06 01:23:58 +0200, Markus Heidelberg wrote: > Björn Steinbrink, 06.04.2009: > > On 2009.04.06 01:35:24 +0300, Felipe Contreras wrote: > > > Well, it's a matter of preference, and you would not loose the option > > > to do it the way you like. But actually, "git diff --cached" is a > > > different action; you can't do "git diff --cached HEAD^.." for > > > example. > > > > Sure you can. It diffs the index against HEAD^ > > No, note the ".." Oh, d'oh... Sorry, and thanks! Björn ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 22:35 ` Felipe Contreras 2009-04-05 23:06 ` Björn Steinbrink @ 2009-04-05 23:17 ` Markus Heidelberg 2009-04-05 23:22 ` Sverre Rabbelier 1 sibling, 1 reply; 38+ messages in thread From: Markus Heidelberg @ 2009-04-05 23:17 UTC (permalink / raw) To: Felipe Contreras; +Cc: git, Junio C Hamano Felipe Contreras, 06.04.2009: > On Mon, Apr 6, 2009 at 12:58 AM, Markus Heidelberg > <markus.heidelberg@web.de> wrote: > > Felipe Contreras, 05.04.2009: > >> For example 'git stage diff' is more natural (at least to me) than 'git diff > >> --cached', same goes for 'git stage rm foo.c' vs 'git rm --cached foo.c'. > > > > Not for me. If I want to GET a diff, I want to use a command "diff", so > > "git diff" is more obvious. > > The next step is to say WHAT exactly to diff. Therefor options to the > > "diff" command are more logically to me from a hierarchic POV. And here > > I don't think options like "--cached" or "sha1..sha2", despite having > > different style, make any difference. > > Well, it's a matter of preference, and you would not loose the option > to do it the way you like. I know, but that's not the topic. > But actually, "git diff --cached" is a > different action; you can't do "git diff --cached HEAD^.." for > example. And I neither could I do "git stage diff HEAD^.." > Consider "git rm foo.c" vs "git rm --cached foo.c"... both commands > are removing a file, the only difference is that one is removing from > the staging area while the other is removing it from the working > directory. Now think about "git branch -d bar", following the "first I > specify the action, and then the object" thinking, would it make sense > to have "git rm --branch bar"? Probably not; Right, the argumentation with first the action doesn't fly any more. I guess it has to be considered what makes sense to have as command. "rm" (not git-rm) is such a well-known tool for deleting files so it probably doesn't make sense to have a command git-rm-files instead. > if you want to do stuff > with branches, you use "git branch", similarly, if you want to do > stuff with the staging area, why not use "git stage"? So git-diff for working with diffs, git-branch for working with branches and git-rm/git-add for working on file level makes sense for me. Whether the a command can work with both the working tree and the index doesn't seem to make a difference for me. Markus ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 23:17 ` Markus Heidelberg @ 2009-04-05 23:22 ` Sverre Rabbelier 2009-04-05 23:45 ` Johannes Schindelin 2009-04-06 3:24 ` David Aguilar 0 siblings, 2 replies; 38+ messages in thread From: Sverre Rabbelier @ 2009-04-05 23:22 UTC (permalink / raw) To: markus.heidelberg; +Cc: Felipe Contreras, git, Junio C Hamano Heya, On Mon, Apr 6, 2009 at 01:17, Markus Heidelberg <markus.heidelberg@web.de> wrote: > Felipe Contreras, 06.04.2009: >> But actually, "git diff --cached" is a >> different action; you can't do "git diff --cached HEAD^.." for >> example. > > And I neither could I do "git stage diff HEAD^.." I rest my case ;). That's the whole point Felipe is trying to make here. $ git diff --cached $ git diff HEAD^.. That's two different modes of operation with the only difference being a switch ('--cached'), which changes what is, and what is not valid after that. Whereas with $ git stage diff There is no confusion that 'HEAD^..' is not a valid argument, as there is no command in 'git stage diff' to which it _is_ a valid argument. -- Cheers, Sverre Rabbelier ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 23:22 ` Sverre Rabbelier @ 2009-04-05 23:45 ` Johannes Schindelin 2009-04-06 9:37 ` Felipe Contreras 2009-04-06 3:24 ` David Aguilar 1 sibling, 1 reply; 38+ messages in thread From: Johannes Schindelin @ 2009-04-05 23:45 UTC (permalink / raw) To: Sverre Rabbelier; +Cc: markus.heidelberg, Felipe Contreras, git, Junio C Hamano Hi, On Mon, 6 Apr 2009, Sverre Rabbelier wrote: > On Mon, Apr 6, 2009 at 01:17, Markus Heidelberg > <markus.heidelberg@web.de> wrote: > > Felipe Contreras, 06.04.2009: > >> But actually, "git diff --cached" is a different action; you can't do > >> "git diff --cached HEAD^.." for example. > > > > And I neither could I do "git stage diff HEAD^.." > > I rest my case ;). That's the whole point Felipe is trying to make here. > $ git diff --cached > $ git diff HEAD^.. > > [...] Could you post at some stage what the current state of this discussion is, so that people who do not have time to read all those mails, let alone fire off 10+ mails per hour, can comment about their view of things? So far, it seems that the view of only a handful is represented in that thread. Thanks, Dscho ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 23:45 ` Johannes Schindelin @ 2009-04-06 9:37 ` Felipe Contreras 0 siblings, 0 replies; 38+ messages in thread From: Felipe Contreras @ 2009-04-06 9:37 UTC (permalink / raw) To: Johannes Schindelin Cc: Sverre Rabbelier, markus.heidelberg, git, Junio C Hamano On Mon, Apr 6, 2009 at 2:45 AM, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote: > Hi, > > On Mon, 6 Apr 2009, Sverre Rabbelier wrote: > >> On Mon, Apr 6, 2009 at 01:17, Markus Heidelberg >> <markus.heidelberg@web.de> wrote: >> > Felipe Contreras, 06.04.2009: >> >> But actually, "git diff --cached" is a different action; you can't do >> >> "git diff --cached HEAD^.." for example. >> > >> > And I neither could I do "git stage diff HEAD^.." >> >> I rest my case ;). That's the whole point Felipe is trying to make here. >> $ git diff --cached >> $ git diff HEAD^.. >> >> [...] > > Could you post at some stage what the current state of this discussion is, > so that people who do not have time to read all those mails, let alone > fire off 10+ mails per hour, can comment about their view of things? > > So far, it seems that the view of only a handful is represented in that > thread. So far it seems nobody likes the idea. Junio has explained why things are the way they are, but he hasn't answered my arguments, including the fact that this doesn't change anything, it merely adds options to an already existing command. This is the mail that hasn't been answered yet: http://article.gmane.org/gmane.comp.version-control.git/115705 -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-05 23:22 ` Sverre Rabbelier 2009-04-05 23:45 ` Johannes Schindelin @ 2009-04-06 3:24 ` David Aguilar 2009-04-06 5:17 ` Junio C Hamano 1 sibling, 1 reply; 38+ messages in thread From: David Aguilar @ 2009-04-06 3:24 UTC (permalink / raw) To: Sverre Rabbelier; +Cc: markus.heidelberg, Felipe Contreras, git, Junio C Hamano On 0, Sverre Rabbelier <srabbelier@gmail.com> wrote: > Heya, > > On Mon, Apr 6, 2009 at 01:17, Markus Heidelberg > <markus.heidelberg@web.de> wrote: > > Felipe Contreras, 06.04.2009: > >> But actually, "git diff --cached" is a > >> different action; you can't do "git diff --cached HEAD^.." for > >> example. > > > > And I neither could I do "git stage diff HEAD^.." > > I rest my case ;). That's the whole point Felipe is trying to make here. > $ git diff --cached > $ git diff HEAD^.. > > That's two different modes of operation with the only difference being > a switch ('--cached'), which changes what is, and what is not valid > after that. > > Whereas with > $ git stage diff > > There is no confusion that 'HEAD^..' is not a valid argument, as there > is no command in 'git stage diff' to which it _is_ a valid argument. Hello Here's an interesting email from a while back: http://kerneltrap.org/mailarchive/git/2008/10/29/3857134 The above mentions the following suggestion: git diff STAGE WORKTREE (like "git diff" today) git diff HEAD WORKTREE (like "git diff HEAD" today) git diff WORKTREE HEAD (like "git diff -R HEAD" today) git diff HEAD STAGE (like "git diff --cached" today) git diff commit STAGE (like "git diff --cached commit" today) >From a consistency and usability perspective, the above example seems very appealing because: a) it does not introduce any new commands, and b) it is consistent with the way git-diff's command-line interface works today. All we'd have to do is teach git-diff to special-case 'STAGE' and 'WORKTREE'. Now, whether we'd want to do that is a completely different discussion, but I figured I'd throw the old thread out there. -- David ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 3:24 ` David Aguilar @ 2009-04-06 5:17 ` Junio C Hamano 2009-04-06 5:53 ` David Aguilar 2009-04-06 13:20 ` David Kågedal 0 siblings, 2 replies; 38+ messages in thread From: Junio C Hamano @ 2009-04-06 5:17 UTC (permalink / raw) To: David Aguilar; +Cc: Sverre Rabbelier, markus.heidelberg, Felipe Contreras, git David Aguilar <davvid@gmail.com> writes: > On 0, Sverre Rabbelier <srabbelier@gmail.com> wrote: >> Heya, >> >> On Mon, Apr 6, 2009 at 01:17, Markus Heidelberg >> <markus.heidelberg@web.de> wrote: >> > Felipe Contreras, 06.04.2009: >> >> But actually, "git diff --cached" is a >> >> different action; you can't do "git diff --cached HEAD^.." for >> >> example. >> > >> > And I neither could I do "git stage diff HEAD^.." >> >> I rest my case ;). That's the whole point Felipe is trying to make here. >> $ git diff --cached >> $ git diff HEAD^.. >> >> That's two different modes of operation with the only difference being >> a switch ('--cached'), which changes what is, and what is not valid >> after that. >> >> Whereas with >> $ git stage diff >> >> There is no confusion that 'HEAD^..' is not a valid argument, as there >> is no command in 'git stage diff' to which it _is_ a valid argument. > > Hello > > Here's an interesting email from a while back: > > http://kerneltrap.org/mailarchive/git/2008/10/29/3857134 > > The above mentions the following suggestion: > > git diff STAGE WORKTREE (like "git diff" today) > git diff HEAD WORKTREE (like "git diff HEAD" today) > git diff WORKTREE HEAD (like "git diff -R HEAD" today) > git diff HEAD STAGE (like "git diff --cached" today) > git diff commit STAGE (like "git diff --cached commit" today) > > > From a consistency and usability perspective, the above > example seems very appealing because: > > a) it does not introduce any new commands, and > > b) it is consistent with the way git-diff's command-line > interface works today. > > All we'd have to do is teach git-diff to special-case > 'STAGE' and 'WORKTREE'. Now, whether we'd want to do > that is a completely different discussion, but I figured I'd > throw the old thread out there. How would you express operations the current --index option does in such a scheme? Yet another WORKTREEANDTHEINDEX token? ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 5:17 ` Junio C Hamano @ 2009-04-06 5:53 ` David Aguilar 2009-04-06 6:18 ` Junio C Hamano 2009-04-06 13:20 ` David Kågedal 1 sibling, 1 reply; 38+ messages in thread From: David Aguilar @ 2009-04-06 5:53 UTC (permalink / raw) To: Junio C Hamano; +Cc: Sverre Rabbelier, markus.heidelberg, Felipe Contreras, git On 0, Junio C Hamano <gitster@pobox.com> wrote: > David Aguilar <davvid@gmail.com> writes: > > > On 0, Sverre Rabbelier <srabbelier@gmail.com> wrote: > >> Heya, > >> > >> On Mon, Apr 6, 2009 at 01:17, Markus Heidelberg > >> <markus.heidelberg@web.de> wrote: > >> > Felipe Contreras, 06.04.2009: > >> >> But actually, "git diff --cached" is a > >> >> different action; you can't do "git diff --cached HEAD^.." for > >> >> example. > >> > > >> > And I neither could I do "git stage diff HEAD^.." > >> > >> I rest my case ;). That's the whole point Felipe is trying to make here. > >> $ git diff --cached > >> $ git diff HEAD^.. > >> > >> That's two different modes of operation with the only difference being > >> a switch ('--cached'), which changes what is, and what is not valid > >> after that. > >> > >> Whereas with > >> $ git stage diff > >> > >> There is no confusion that 'HEAD^..' is not a valid argument, as there > >> is no command in 'git stage diff' to which it _is_ a valid argument. > > > > Here's an interesting email from a while back: > > > > http://kerneltrap.org/mailarchive/git/2008/10/29/3857134 > > > > The above mentions the following suggestion: > > > > git diff STAGE WORKTREE (like "git diff" today) > > git diff HEAD WORKTREE (like "git diff HEAD" today) > > git diff WORKTREE HEAD (like "git diff -R HEAD" today) > > git diff HEAD STAGE (like "git diff --cached" today) > > git diff commit STAGE (like "git diff --cached commit" today) > > > > From a consistency and usability perspective, the above > > example seems very appealing because: > > ... > > All we'd have to do is teach git-diff to special-case > > 'STAGE' and 'WORKTREE'. Now, whether we'd want to do > > that is a completely different discussion, but I figured I'd > > throw the old thread out there. > > How would you express operations the current --index option does in such a > scheme? Yet another WORKTREEANDTHEINDEX token? Is it a trick question? git-diff doesn't have an --index option, only --staged. Ah, I know the answer: http://kerneltrap.org/mailarchive/git/2008/11/12/4072144 http://kerneltrap.org/mailarchive/git/2008/11/12/4067114 http://kerneltrap.org/mailarchive/git/2008/11/2/3896104 I did say it *seemed* appealing, not that it actually was ;) Alrighty.. my only purpose was to bring up the old thread since I think many ideas were fleshed out back when 'git diff --staged' was introduced. How useful it is in the context of this discussion about a new 'stage' command is questionable, so I'll shut up now =) -- David ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 5:53 ` David Aguilar @ 2009-04-06 6:18 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2009-04-06 6:18 UTC (permalink / raw) To: David Aguilar; +Cc: Sverre Rabbelier, markus.heidelberg, Felipe Contreras, git David Aguilar <davvid@gmail.com> writes: > Ah, I know the answer: > > http://kerneltrap.org/mailarchive/git/2008/11/12/4072144 > http://kerneltrap.org/mailarchive/git/2008/11/12/4067114 > http://kerneltrap.org/mailarchive/git/2008/11/2/3896104 > > I did say it *seemed* appealing, not that it actually was ;) Heh, I forgot all about that. What is sad about it is that I back then predicted that we will regret "diff --staged". http://kerneltrap.org/mailarchive/git/2008/11/11/4056664 ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 5:17 ` Junio C Hamano 2009-04-06 5:53 ` David Aguilar @ 2009-04-06 13:20 ` David Kågedal 2009-04-06 13:42 ` David Kågedal 2009-04-06 18:30 ` Junio C Hamano 1 sibling, 2 replies; 38+ messages in thread From: David Kågedal @ 2009-04-06 13:20 UTC (permalink / raw) To: git Cc: David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras, git Junio C Hamano <gitster@pobox.com> writes: > David Aguilar <davvid@gmail.com> writes: > >> Hello >> >> Here's an interesting email from a while back: Thanks, I would have brought it back up myself if you hadn't. >> http://kerneltrap.org/mailarchive/git/2008/10/29/3857134 >> >> The above mentions the following suggestion: >> >> git diff STAGE WORKTREE (like "git diff" today) >> git diff HEAD WORKTREE (like "git diff HEAD" today) >> git diff WORKTREE HEAD (like "git diff -R HEAD" today) >> git diff HEAD STAGE (like "git diff --cached" today) >> git diff commit STAGE (like "git diff --cached commit" today) >> >> >> From a consistency and usability perspective, the above >> example seems very appealing because: >> >> a) it does not introduce any new commands, and >> >> b) it is consistent with the way git-diff's command-line >> interface works today. >> >> All we'd have to do is teach git-diff to special-case >> 'STAGE' and 'WORKTREE'. Now, whether we'd want to do >> that is a completely different discussion, but I figured I'd >> throw the old thread out there. > > How would you express operations the current --index option does in such a > scheme? Yet another WORKTREEANDTHEINDEX token? What do you mean? This was a suggestion for how git diff should work. I fail to see how you would need a WORKTREEANDTHEINDEX there. I think this is a basic usability issue for a high-level porcelain command such as diff. Having the command syntax "git diff <something> <somethingelse>" makes sure you never wonder what you are diffing. "git diff --cached" makes me wonder what the index is diffed against every time I see it. We wouldn't have to use the "STAGE" or "WORKTREE" names, of course. It doesn't have to look like refspecs even. The last example already has a syntax that matches the suggestion: git diff --cached <commit> So, extrapolating this to "git diff --worktree --cached" would mean what "git diff -R" means today etc. The obvious objection is that "git diff --cached <foo>" would mean the inverse of "git diff <foo> --cached", but maybe that isn't so unexpected by the user after all? -- David Kågedal ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 13:20 ` David Kågedal @ 2009-04-06 13:42 ` David Kågedal 2009-04-06 18:30 ` Junio C Hamano 1 sibling, 0 replies; 38+ messages in thread From: David Kågedal @ 2009-04-06 13:42 UTC (permalink / raw) To: git Cc: David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras, Junio C Hamano David Kågedal <davidk@lysator.liu.se> writes: > We wouldn't have to use the "STAGE" or "WORKTREE" names, of course. It > doesn't have to look like refspecs even. The last example already has > a syntax that matches the suggestion: > > git diff --cached <commit> > > So, extrapolating this to "git diff --worktree --cached" would mean > what "git diff -R" means today etc. BTW, I don't really care much about whether it's spelled "cached" "index" "staged" or "dumbledore". I just want some regularity in the diff command. I'll happily let someone else figure out the taxonomy. -- David Kågedal ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 13:20 ` David Kågedal 2009-04-06 13:42 ` David Kågedal @ 2009-04-06 18:30 ` Junio C Hamano 2009-04-06 19:13 ` Felipe Contreras ` (4 more replies) 1 sibling, 5 replies; 38+ messages in thread From: Junio C Hamano @ 2009-04-06 18:30 UTC (permalink / raw) To: David Kågedal Cc: git, David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras David Kågedal <davidk@lysator.liu.se> writes: > What do you mean? This was a suggestion for how git diff should > work. I fail to see how you would need a WORKTREEANDTHEINDEX there. You are talking only about "git diff". I am talking about the whole git suite, because you have to worry about how such a proposal would affect other parts of the UI. For example, what, if anything, should be done to "git grep --cached" and "git apply --index"? Leave them unchanged and only change "git diff"? > I think this is a basic usability issue for a high-level porcelain > command such as diff. I do not think there is any usability issue. Why do you think saying STAGE in all capital makes it easier to _use_ instead of saying --cached (or --index-only)? In either way, you need to understand the underlying concept, such as: - there are three distinct kinds of states: a committed state, the state in the index (aka "what you have staged so far to the index"), and the state in your work tree. - many commands understand that you want to operate on and/or inspect states in one or more of these states. They default to what is often used (e.g. "git diff" compares the index and the work tree, "git grep" looks in the work tree, "git apply" patches the work tree [*1*]), but you can tell them to use different entities via options and arguments. How does it help understanding any of the above to introduce STAGE? The only difference I see is that you change "via options and arguments" to "via arguments of different kinds, either a real commit object name or some fake token that stands for the index or the work tree state". Spelled out more explicitly, the current "options and arguments" works this way: - when you want to work with a committed state (or more in general, with a tree-ish), you give the name of the commit; - when you want to work with the index, you say --cached; - when you want to work with both the index and the work tree at the same time, you say --index. - for all commands, working with work tree is the default, so there is no --work-tree option (we could add one, if you really want). and the STAGE would work something like this: - when you want to work with a committed state (or more in general, with a tree-ish), you give the name of the commit; - when you want to work with the index, you say STAGE; not that you cannot have a ref called STAGE and if you have a file in the work tree whose name is STAGE you need to say "git command ... -- STAGE" to name the file, or "git command ... STAGE --" to clarify that you do not mean the file but you mean to use the fake toekn STAGE. - when you want to work with both the index and the work tree at the same time, you say STAGEANDWORKTREE (the same disambiguation caveat applies). - for all commands, working with work tree is the default, but you can still say WORKTREE (the same disambiguation caveat applies). If anything, I think these capitalized fake tokens spread more confusion. Sure, "git diff HEAD STAGED" and "git diff HEAD WORKTREE" may make the command lines look as if what these fake tokens represent are "sort of" commits, but that is only true while you are using a command that has modes to work on the index and/or on the work tree. These fake tokens do not work everywhere, and it is not an implementation limit. Fundamentally they cannot work everywhere. Think. What does "git log STAGE" mean? Can you explain why it does not make any sense? The user needs to be aware that the index is NOT a commit to understand why such a command line doesn't make sense _anyway_. I think it is counterproductive for the learning curve of new people to make these different concepts look as if they belong to the same family by using STAGE (that look too similar to HEAD). You seem to think it would make it easier for them to learn if these different concepts are not presented as different. But they are different, and if new people start with a false impression that these are "sort of" commits, they need to unlearn that at some point, and that "some point" is not "advanced use". Even bog standard "git log" exposes why hiding the conceptual differences between these three states does not work. Teach that different things are different, and express that in the UI. That would avoid the confusion down the line. [Footnote] *1* "git apply" was originally done to replace use of "GNU patch" in Linus's workflow because "patch" was deliberately too lenient, and as such, it does not look at the index by default. In a git repository, as long as a patch does not contain creation of new files, this is a good default, too. You can "git apply incoming.patch && git diff -U20" to see what the patch does in wider context, for example. If "git apply --index" were the default, the same can be done with "git diff -U20 HEAD" and it won't risk forgetting new files. But it is a huge backward incompatible change that won't happen without deep thought. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 18:30 ` Junio C Hamano @ 2009-04-06 19:13 ` Felipe Contreras 2009-04-06 19:25 ` Björn Steinbrink 2009-04-06 20:49 ` Matthieu Moy ` (3 subsequent siblings) 4 siblings, 1 reply; 38+ messages in thread From: Felipe Contreras @ 2009-04-06 19:13 UTC (permalink / raw) To: Junio C Hamano Cc: David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg On Mon, Apr 6, 2009 at 9:30 PM, Junio C Hamano <gitster@pobox.com> wrote: > David Kågedal <davidk@lysator.liu.se> writes: > >> What do you mean? This was a suggestion for how git diff should >> work. I fail to see how you would need a WORKTREEANDTHEINDEX there. > > You are talking only about "git diff". I am talking about the whole git > suite, because you have to worry about how such a proposal would affect > other parts of the UI. How do currently do you something like this: git diff HEAD^..STAGE You can't. This is not an issue for any other git commands, that's why --stage, --cache, --index make sense for _other_ commands, not 'git diff'. -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 19:13 ` Felipe Contreras @ 2009-04-06 19:25 ` Björn Steinbrink 2009-04-07 10:01 ` Felipe Contreras 0 siblings, 1 reply; 38+ messages in thread From: Björn Steinbrink @ 2009-04-06 19:25 UTC (permalink / raw) To: Felipe Contreras Cc: Junio C Hamano, David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg On 2009.04.06 22:13:26 +0300, Felipe Contreras wrote: > On Mon, Apr 6, 2009 at 9:30 PM, Junio C Hamano <gitster@pobox.com> wrote: > > David Kågedal <davidk@lysator.liu.se> writes: > > > >> What do you mean? This was a suggestion for how git diff should > >> work. I fail to see how you would need a WORKTREEANDTHEINDEX there. > > > > You are talking only about "git diff". I am talking about the whole git > > suite, because you have to worry about how such a proposal would affect > > other parts of the UI. > > How do currently do you something like this: > git diff HEAD^..STAGE git diff --cached HEAD^ The "hard" (and pretty weird) one would be "git diff STAGE..HEAD^", which is: git diff -R --cached HEAD^ Björn ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 19:25 ` Björn Steinbrink @ 2009-04-07 10:01 ` Felipe Contreras 2009-04-07 12:45 ` Johannes Schindelin 0 siblings, 1 reply; 38+ messages in thread From: Felipe Contreras @ 2009-04-07 10:01 UTC (permalink / raw) To: Björn Steinbrink Cc: Junio C Hamano, David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg On Mon, Apr 6, 2009 at 10:25 PM, Björn Steinbrink <B.Steinbrink@gmx.de> wrote: > On 2009.04.06 22:13:26 +0300, Felipe Contreras wrote: >> On Mon, Apr 6, 2009 at 9:30 PM, Junio C Hamano <gitster@pobox.com> wrote: >> > David Kågedal <davidk@lysator.liu.se> writes: >> > >> >> What do you mean? This was a suggestion for how git diff should >> >> work. I fail to see how you would need a WORKTREEANDTHEINDEX there. >> > >> > You are talking only about "git diff". I am talking about the whole git >> > suite, because you have to worry about how such a proposal would affect >> > other parts of the UI. >> >> How do currently do you something like this: >> git diff HEAD^..STAGE > > git diff --cached HEAD^ > > The "hard" (and pretty weird) one would be "git diff STAGE..HEAD^", > which is: > > git diff -R --cached HEAD^ Sorry, that's what I meant. So it's possible, but completely unintuitive, and different from other use cases. -- Felipe Contreras ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-07 10:01 ` Felipe Contreras @ 2009-04-07 12:45 ` Johannes Schindelin 0 siblings, 0 replies; 38+ messages in thread From: Johannes Schindelin @ 2009-04-07 12:45 UTC (permalink / raw) To: Felipe Contreras Cc: Björn Steinbrink, Junio C Hamano, David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg [-- Attachment #1: Type: TEXT/PLAIN, Size: 1398 bytes --] Hi, On Tue, 7 Apr 2009, Felipe Contreras wrote: > On Mon, Apr 6, 2009 at 10:25 PM, Björn Steinbrink <B.Steinbrink@gmx.de> wrote: > > On 2009.04.06 22:13:26 +0300, Felipe Contreras wrote: > >> On Mon, Apr 6, 2009 at 9:30 PM, Junio C Hamano <gitster@pobox.com> wrote: > >> > David Kågedal <davidk@lysator.liu.se> writes: > >> > > >> >> What do you mean? This was a suggestion for how git diff should > >> >> work. I fail to see how you would need a WORKTREEANDTHEINDEX there. > >> > > >> > You are talking only about "git diff". I am talking about the whole git > >> > suite, because you have to worry about how such a proposal would affect > >> > other parts of the UI. > >> > >> How do currently do you something like this: > >> git diff HEAD^..STAGE > > > > git diff --cached HEAD^ > > > > The "hard" (and pretty weird) one would be "git diff STAGE..HEAD^", > > which is: > > > > git diff -R --cached HEAD^ > > Sorry, that's what I meant. > > So it's possible, but completely unintuitive, and different from other > use cases. At least it is consistent. You are always able to say "-R" if you want to have the reverse diff, this is commonly known from GNU diff and other diff implementations. Also, "git diff --cached" is _only_ a shortcut for "git diff --cached HEAD". This is yet another proof that you should not teach the shortcuts first, it _harms_ understanding. Ciao, Dscho ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 18:30 ` Junio C Hamano 2009-04-06 19:13 ` Felipe Contreras @ 2009-04-06 20:49 ` Matthieu Moy 2009-04-07 0:55 ` Junio C Hamano [not found] ` <87skkligzb.fsf@krank.kagedal.org> ` (2 subsequent siblings) 4 siblings, 1 reply; 38+ messages in thread From: Matthieu Moy @ 2009-04-06 20:49 UTC (permalink / raw) To: Junio C Hamano Cc: David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras Junio C Hamano <gitster@pobox.com> writes: > - there are three distinct kinds of states: a committed state, the state > in the index (aka "what you have staged so far to the index"), and the > state in your work tree. > > - many commands understand that you want to operate on and/or inspect > states in one or more of these states. They default to what is often > used (e.g. "git diff" compares the index and the work tree, "git grep" > looks in the work tree, "git apply" patches the work tree [*1*]), but > you can tell them to use different entities via options and arguments. > > How does it help understanding any of the above to introduce STAGE? For the first, if there are three kinds of states, I would find it natural to have three kinds of ways to talk about these states. Sure, it doesn't change the second, since it makes things more explicit, it doesn't make them more concise. > - when you want to work with the index, you say --cached; But that doesn't apply to "git diff". Both "git diff" and "git diff --cached" work with the index. "git diff" works with the index and work tree, while "git diff --cached" work with the index and HEAD. > - when you want to work with both the index and the work tree at the > same time, you say --index. ... which is everything but intuitive. The option name doesn't tell the user what the command is doing. First thing is that with Git, the user has to learn 3 words for one concept (index, cache, staging area). And then, he has to learn that although people use "index" and "cache" as synomyms, --index and --cached have different meanings. And that one can also have a --cache, and that it's possible to have a --stage too, but with different meaning. I can understand the historical reasons, but I think finding a way to get rid of this historical terminology mess should be encourraged. > - for all commands, working with work tree is the default, so there is > no --work-tree option (we could add one, if you really want). Except "git checkout", which takes the index by default, and a commit if specified. It makes sense since checking-out from the working tree doesn't make sense, but it is a special case, and learning the general rules you give doesn't tell the user what "git checkout" does. Except "git ls-files", too. And I may have missed some. See, you complain about special cases with the proposal, but the current UI _has_ tons of special cases like this. > and the STAGE would work something like this: > > - when you want to work with a committed state (or more in general, > with a tree-ish), you give the name of the commit; It's not just "I want to work with". It's also about the role of the things you want to work with. "git diff WORKTREE STAGE" would mean "diff from the worktree to the staging area", while "git diff STAGE WORKTREE" would mean the other way around. > Think. What does "git log STAGE" mean? Can you explain why it does not > make any sense? It could make sense. Actually, gitk does show the work-tree and the index in a way similar to commits. Fundamentally, I don't see a difference between "git log" and "gitk" except that gitk is graphical. Sure, STAGE and WORKTREE cannot have a commit message, and hardly have an author, but I could very well imagine "git log --stat WORKTREE" showing roughly what "git diff --stat; git diff --stat --cached; git log --stat HEAD" does today. I don't know how usefull this would be, but I wouldn't say it doesn't make sense either. -- Matthieu ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 20:49 ` Matthieu Moy @ 2009-04-07 0:55 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2009-04-07 0:55 UTC (permalink / raw) To: Matthieu Moy Cc: David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras Matthieu Moy <Matthieu.Moy@imag.fr> writes: > But that doesn't apply to "git diff". Both "git diff" and "git diff > --cached" work with the index. It is so often used against HEAD that it is the default for --cached mode. If it confuses your students, do not teach them "git diff --cached" without teaching "git diff --cached HEAD" first. > ... which is everything but intuitive. The option name doesn't tell > the user what the command is doing. Surely, I already said that --cached vs --index are not the best words, didn't I? But the point was that introducing STAGE and other "ref-looking tokens" not only does not help the situation at all, but makes it worse. > I can understand the historical reasons, but I think finding a way to > get rid of this historical terminology mess should be encourraged. No, you should aim higher, if you are trying to change things. Find a way to convey the concepts better, and come up with a way (i.e. set of options---as I already explained why ref looking tokens is inferiour than explicit options) that does not break the backward compatibility, and help new people learn. I am not interested in the "ref-looking tokens" because they fail the latter test. >> - for all commands, working with work tree is the default, so there is >> no --work-tree option (we could add one, if you really want). > > Except "git checkout", which takes the index by default, and > a commit if specified. It makes sense since checking-out from the > working tree doesn't make sense,... You say "except X" but you need to qualify "but that default makes sense for X". I'd say that is true for all X---so you are saying the default is sensible, which is good. > Except "git ls-files", too.... It is a plumbing that only works with the index. What's your problem? > See, you complain about special cases with the proposal, but the > current UI _has_ tons of special cases like this. The two example you quoted above are neither tons nor special cases. And I am not saying that "ref-looking tokens are bad because there are special cases" anyway. ^ permalink raw reply [flat|nested] 38+ messages in thread
[parent not found: <87skkligzb.fsf@krank.kagedal.org>]
* Re: [RFC/PATCH 0/2] New 'stage' command [not found] ` <87skkligzb.fsf@krank.kagedal.org> @ 2009-04-07 1:02 ` Junio C Hamano 2009-04-07 8:39 ` Octavio Alvarez 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2009-04-07 1:02 UTC (permalink / raw) To: David Kågedal Cc: Felipe Contreras, markus heidelberg, Sverre Rabbelier, David Aguilar, git David Kågedal <davidk@lysator.liu.se> writes: >> - when you want to work with both the index and the work tree at the >> same time, you say STAGEANDWORKTREE (the same disambiguation caveat >> applies). > > No, where did this come from? "git apply STAGEANDWORKTREE this.patch". I do not want "for diff you can use these metavariables to name two things compared, but you can do so only for diff". >> Think. What does "git log STAGE" mean? Can you explain why it does not >> make any sense? > > As I already explained, you read way to much into my message. I think the fundamental difference between us is that you are too attached to the notion of "for diff you can use these metavariables to name two things compared". That by itself looks very nice if you only look at the diff command line, but I do not want "but you can do so only for diff, so you have to unlearn the metavariables and do thing in different ways for other commands" part. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-07 1:02 ` Junio C Hamano @ 2009-04-07 8:39 ` Octavio Alvarez [not found] ` <878wmcj1fs.fsf@krank.kagedal.org> 0 siblings, 1 reply; 38+ messages in thread From: Octavio Alvarez @ 2009-04-07 8:39 UTC (permalink / raw) To: Junio C Hamano, David Kågedal Cc: Felipe Contreras, markus heidelberg, Sverre Rabbelier, David Aguilar, git On Mon, 06 Apr 2009 18:02:10 -0700, Junio C Hamano <gitster@pobox.com> wrote: > David Kågedal <davidk@lysator.liu.se> writes: > >>> - when you want to work with both the index and the work tree at the >>> same time, you say STAGEANDWORKTREE (the same disambiguation >>> caveat >>> applies). >> >> No, where did this come from? > > "git apply STAGEANDWORKTREE this.patch". I do not want "for diff you can > use these metavariables to name two things compared, but you can do so > only for diff". That example is broken. git apply doesn't even take an arbitrary treeish. >>> Think. What does "git log STAGE" mean? Can you explain why it does >>> not >>> make any sense? gitk actually does this. Even more, gitk shows them in this order: STAGE^ would be HEAD. WORKTREE^ would be STAGE. Makes sense. (Not that I think git log should do the same.) The difference between git diff and git reset is that git diff should take a range of trees, not a range of commits as parameters. OTOH, git reset doesn't know or care about trees, it needs commits. git checkout WORKTREE:file makes sense, even though it is useless, but that's why it git checout STAGE:file makes sense: it should accept any tree instead of a commit. git apply doesn't even take commits. It *could* take trees if it automagically created a branch on the commit, though. Either that, or git-apply shouldn't exist at all. It's similar with git reset. You wouldn't use STAGE or WORKTREE here because a commit is actually necessary, but according option names like: --stage --worktree --both --none are better than --hard, --soft and --mixed. So, if the man page for git-reset says "commit-id" and the man page for git diff says "tree-id..tree-id", I don't see any kind of confusion. git checkout could too. git reset and git log are to say "commit-id", but support clearer options. WORKTREE, STAGE are trees as commits are also trees, but not all trees are commits. ^ permalink raw reply [flat|nested] 38+ messages in thread
[parent not found: <878wmcj1fs.fsf@krank.kagedal.org>]
* Re: [RFC/PATCH 0/2] New 'stage' command [not found] ` <878wmcj1fs.fsf@krank.kagedal.org> @ 2009-04-07 15:01 ` Octavio Alvarez 0 siblings, 0 replies; 38+ messages in thread From: Octavio Alvarez @ 2009-04-07 15:01 UTC (permalink / raw) To: David Kågedal, Junio C. Hamano Cc: git, David Aguilar, Sverre Rabbelier, markus heidelberg, Felipe Contreras On Tue, 07 Apr 2009 01:46:47 -0700, David Kågedal <davidk@lysator.liu.se> wrote: > "Octavio Alvarez" <alvarezp@alvarezp.ods.org> writes: > >> The difference between git diff and git reset is that git diff should >> take >> a range of trees, not a range of commits as parameters. OTOH, git reset >> doesn't know or care about trees, it needs commits. > > No, git diff doesn't take a range. It takes two trees (including the > work "tree" and the index "tree"). The A..B syntax is nonsense for git > diff, but I believe it supported for historical reasons. > Thanks. I correct by s/range of// but the case persists. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 18:30 ` Junio C Hamano ` (2 preceding siblings ...) [not found] ` <87skkligzb.fsf@krank.kagedal.org> @ 2009-04-07 1:36 ` Stefan Karpinski 2009-04-07 7:38 ` Octavio Alvarez 4 siblings, 0 replies; 38+ messages in thread From: Stefan Karpinski @ 2009-04-07 1:36 UTC (permalink / raw) To: Junio C Hamano Cc: David Kågedal, git, David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras On Mon, Apr 6, 2009 at 11:30 AM, Junio C Hamano <gitster@pobox.com> wrote: > David Kågedal <davidk@lysator.liu.se> writes: > >> What do you mean? This was a suggestion for how git diff should >> work. I fail to see how you would need a WORKTREEANDTHEINDEX there. > > You are talking only about "git diff". I am talking about the whole git > suite, because you have to worry about how such a proposal would affect > other parts of the UI. > > For example, what, if anything, should be done to "git grep --cached" and > "git apply --index"? Leave them unchanged and only change "git diff"? > >> I think this is a basic usability issue for a high-level porcelain >> command such as diff. > > I do not think there is any usability issue. Why do you think saying > STAGE in all capital makes it easier to _use_ instead of saying --cached > (or --index-only)? In either way, you need to understand the underlying > concept, such as: There is most definitely a usability issue here. I use git every day and I *cannot* for the life of me remember all the inconsistent stage-related oddball commands. I have a number of aliases for them (similar to what Felipe is proposing) which are the only way I can remember them. Whenever I find myself using a git repo without those aliases, I have to fire up the man pages. Trying to explain all of this to coworkers that use git—honestly, I don't even try to go there. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [RFC/PATCH 0/2] New 'stage' command 2009-04-06 18:30 ` Junio C Hamano ` (3 preceding siblings ...) 2009-04-07 1:36 ` Stefan Karpinski @ 2009-04-07 7:38 ` Octavio Alvarez 4 siblings, 0 replies; 38+ messages in thread From: Octavio Alvarez @ 2009-04-07 7:38 UTC (permalink / raw) To: Junio C Hamano, David Kågedal Cc: git, David Aguilar, Sverre Rabbelier, markus.heidelberg, Felipe Contreras On Mon, 06 Apr 2009 11:30:54 -0700, Junio C Hamano <gitster@pobox.com> wrote: > - when you want to work with the index, you say --cached; > > - when you want to work with both the index and the work tree at the > same time, you say --index. This is where I also think the options are messed up. If I want to work with the "index", shouldn't I use... uhh... "--index"? If I want to work with both, shouldn't I use something like "--both"? "And if --index works with the workcopy and index, will --cache use both, the workcopy and the cache?" To a new user like me, these options don't look like they refer to different actions, but to different existing things. Those options say that there is an index, and there is a cache. (Now I learned all of this through reading the docs which is not hard, but reading this from the man pages is not intuitive at all.) ^ permalink raw reply [flat|nested] 38+ messages in thread
end of thread, other threads:[~2009-04-07 15:03 UTC | newest] Thread overview: 38+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2009-04-05 13:48 [RFC/PATCH 0/2] New 'stage' command Felipe Contreras 2009-04-05 13:48 ` [RFC/PATCH 1/2] git: remote stage Felipe Contreras 2009-04-05 13:48 ` [RFC/PATCH 2/2] Add new 'git stage' script Felipe Contreras 2009-04-05 19:02 ` [RFC/PATCH 0/2] New 'stage' command Junio C Hamano 2009-04-05 19:28 ` Felipe Contreras 2009-04-05 19:33 ` Junio C Hamano 2009-04-05 19:59 ` Junio C Hamano 2009-04-05 20:41 ` Felipe Contreras 2009-04-05 20:55 ` Jay Soffian 2009-04-05 22:06 ` Felipe Contreras 2009-04-05 19:34 ` [RFC/PATCH 0/2] " Nicolas Sebrecht 2009-04-05 21:58 ` [RFC/PATCH 0/2] " Markus Heidelberg 2009-04-05 22:35 ` Felipe Contreras 2009-04-05 23:06 ` Björn Steinbrink 2009-04-05 23:23 ` Markus Heidelberg 2009-04-06 9:48 ` Björn Steinbrink 2009-04-05 23:17 ` Markus Heidelberg 2009-04-05 23:22 ` Sverre Rabbelier 2009-04-05 23:45 ` Johannes Schindelin 2009-04-06 9:37 ` Felipe Contreras 2009-04-06 3:24 ` David Aguilar 2009-04-06 5:17 ` Junio C Hamano 2009-04-06 5:53 ` David Aguilar 2009-04-06 6:18 ` Junio C Hamano 2009-04-06 13:20 ` David Kågedal 2009-04-06 13:42 ` David Kågedal 2009-04-06 18:30 ` Junio C Hamano 2009-04-06 19:13 ` Felipe Contreras 2009-04-06 19:25 ` Björn Steinbrink 2009-04-07 10:01 ` Felipe Contreras 2009-04-07 12:45 ` Johannes Schindelin 2009-04-06 20:49 ` Matthieu Moy 2009-04-07 0:55 ` Junio C Hamano [not found] ` <87skkligzb.fsf@krank.kagedal.org> 2009-04-07 1:02 ` Junio C Hamano 2009-04-07 8:39 ` Octavio Alvarez [not found] ` <878wmcj1fs.fsf@krank.kagedal.org> 2009-04-07 15:01 ` Octavio Alvarez 2009-04-07 1:36 ` Stefan Karpinski 2009-04-07 7:38 ` Octavio Alvarez
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).