[RFC/PATCH 0/2] New 'stage' command

[RFC/PATCH 0/2] New 'stage' command

[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

[RFC/PATCH 1/2] git: remote stage

[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

[RFC/PATCH 2/2] Add new 'git stage' script

[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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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.

[RFC/PATCH 0/2] Re: New 'stage' command

[Nicolas Sebrecht]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Jay Soffian]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Markus Heidelberg]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Björn Steinbrink]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Markus Heidelberg]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Sverre Rabbelier]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Markus Heidelberg]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Johannes Schindelin]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[David Aguilar]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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?

Re: [RFC/PATCH 0/2] New 'stage' command

[David Aguilar]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Björn Steinbrink]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[David Kågedal]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[David Kågedal]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Björn Steinbrink]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Matthieu Moy]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Junio C Hamano]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Stefan Karpinski]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Octavio Alvarez]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Octavio Alvarez]

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.

Re: [RFC/PATCH 0/2] New 'stage' command

[Felipe Contreras]

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

Re: [RFC/PATCH 0/2] New 'stage' command

[Johannes Schindelin]

[-- 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

Re: [RFC/PATCH 0/2] New 'stage' command

[Octavio Alvarez]

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.