[PATCH v2 0/2] user-manual: new "getting started" section

[PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

This basically introduces the "getting started" section so users get familiar
with the configuration from the get-go, and also, most people prefer to teach
'git config --global' to setup the user name and email. Here are a few
examples:

git tutorial:
http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html

GNOME:
http://live.gnome.org/Git/Developers

SourceForge:
http://sourceforge.net/apps/trac/sourceforge/wiki/Git

github:
http://help.github.com/git-email-settings/

v2:

Reworded the getting started section based on comments from Michael J Gruber,
Jonathan Nieder and Junio C Hamano.

Felipe Contreras (2):
  user-manual: add global config section
  user-manual: simplify the user configuration

 Documentation/user-manual.txt |   37 ++++++++++++++++++++++++++++++++-----
 1 files changed, 32 insertions(+), 5 deletions(-)

[PATCH v2 1/2] user-manual: add global config section

[Felipe Contreras]

Comments from Michael J Gruber, Jonathan Nieder and Junio C Hamano.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/user-manual.txt |   29 +++++++++++++++++++++++++++++
 1 files changed, 29 insertions(+), 0 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 67ebffa..3fcbc36 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -40,6 +40,35 @@ without any explanation.
 Finally, see <<todo>> for ways that you can help make this manual more
 complete.
 
+[[getting-started]]
+Getting started
+=============
+
+Various configuration options affect how git operates. Some are specific to
+the user (e.g. if you prefer to see the output in colour), while some are
+specific to a repository (e.g. what other repositories it interacts with).
+
+For example, you can tell git to use color in the output of commands such as
+`git diff` by setting the `color.ui` option:
+------------------------------------------------
+$ git config --global color.ui auto
+------------------------------------------------
+
+Note that in this case the option is stored in the 'global' configuration. If
+you don't specify `--global`, then the option will be stored on the local
+(repository) configuration, which is probably not what you want.
+
+The options are stored in plain text files that you can view, or edit manually
+using the `--edit` option, and the format is very simple:
+------------------------------------------------
+$ git config --global --edit
+[color]
+        ui = auto
+------------------------------------------------
+
+This manual covers many configuration options (such as `color.ui`). For
+more details on the `git config` command, as well as all configuration
+options see linkgit:git-config[1].
 
 [[repositories-and-branches]]
 Repositories and Branches
-- 
1.6.5.1

[PATCH v2 2/2] user-manual: simplify the user configuration

[Felipe Contreras]

This is shorter, avoids the burder to think about the format of the
configuration file, and git config is already used in other places in
the manual.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/user-manual.txt |    8 +++-----
 1 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 3fcbc36..a0a75af 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1010,13 +1010,11 @@ Telling git your name
 ---------------------
 
 Before creating any commits, you should introduce yourself to git.  The
-easiest way to do so is to make sure the following lines appear in a
-file named .gitconfig in your home directory:
+easiest way is to use the linkgit:git-config[1] command:
 
 ------------------------------------------------
-[user]
-	name = Your Name Comes Here
-	email = you@yourdomain.example.com
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email you@yourdomain.example.com
 ------------------------------------------------
 
 (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
-- 
1.6.5.1

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Nanako Shiraishi]

Quoting Felipe Contreras <felipe.contreras@gmail.com> writes:

> ...
> Reworded the getting started section based on comments from Michael J Gruber,
> Jonathan Nieder and Junio C Hamano.

I'm surprised that you ignored comments from the original 
author of the document you are updating.

  Date: Tue, 13 Oct 2009 22:49:40 -0400
  Message-ID: <20091014024940.GB9700@fieldses.org>

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Quoting Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> ...
>> Reworded the getting started section based on comments from Michael J Gruber,
>> Jonathan Nieder and Junio C Hamano.
>
> I'm surprised that you ignored comments from the original
> author of the document you are updating.

I did not. His comment was that if we do this, it must be short, and
it is. If it's not, then it would be more productive to suggest ways
to trim it down.

>  Date: Tue, 13 Oct 2009 22:49:40 -0400
>  Message-ID: <20091014024940.GB9700@fieldses.org>

I've no way of figuring out what is that. Most people use a direct
link to a mail archive.

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Björn Steinbrink]

On 2009.10.24 17:08:06 +0300, Felipe Contreras wrote:
> On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> >  Date: Tue, 13 Oct 2009 22:49:40 -0400
> >  Message-ID: <20091014024940.GB9700@fieldses.org>
> 
> I've no way of figuring out what is that. Most people use a direct
> link to a mail archive.

Having the Message-ID is quite useful, so you can search your local mbox
to find the right message. You can also use gmane's Message-ID search:
http://mid.gmane.org/message_id_here

So: http://mid.gmane.org/20091014024940.GB9700@fieldses.org

Björn

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

2009/10/24 Björn Steinbrink <B.Steinbrink@gmx.de>:
> On 2009.10.24 17:08:06 +0300, Felipe Contreras wrote:
>> On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
>> >  Date: Tue, 13 Oct 2009 22:49:40 -0400
>> >  Message-ID: <20091014024940.GB9700@fieldses.org>
>>
>> I've no way of figuring out what is that. Most people use a direct
>> link to a mail archive.
>
> Having the Message-ID is quite useful, so you can search your local mbox
> to find the right message.

I don't have a local mbox, and I suspect I'm not the only one.

> You can also use gmane's Message-ID search:
> http://mid.gmane.org/message_id_here

That's a nice trick, but then using the following link would serve
exactly the same purpose, wouldn't it?

> So: http://mid.gmane.org/20091014024940.GB9700@fieldses.org

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> Reworded the getting started section based on comments from Michael J Gruber,
> Jonathan Nieder and Junio C Hamano.

Hmm, I thought JBF also had some input...

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> Reworded the getting started section based on comments from Michael J Gruber,
>> Jonathan Nieder and Junio C Hamano.
>
> Hmm, I thought JBF also had some input...

Ah, nevermind. Yes, he did have input, and I tend to agree with him, and
more importantly trust his judgement on the manual.

I think a "Getting started" section that only covers "git config" looks
way out of place in the beginning of this document.

Manuals by other people that teach "here is how you would do a hello-world
repository" would want to teach user.name before reaching that point, but
because the user-manual is written in such a way that it first introduces
concepts to understand what is going on without changing anything, we do
not have much need user.name until it gets to "Developing with git"
section.

"Many people prefer to teach it this way" does not justify "everybody must
teach it this way" an iota, when teaching "config user.name" upfront will
fit the flow of how they teach but does not fit the flow of how this
manual teaches [*1*].

I'm inclined to to discard the first patch.

The point of the original text the second patch touches was to show how
simple the contents of the configuration file is and give the users that
there is nothing magic there.  While I do not like the second patch as-is,
because it destroys that nice property and treats the end users mindless
"cut-and-paste without thinking" sheeples, I think that it is rather vague
and unhelpful to the current target audience to say:

    ...  The easiest way to do so is to make sure the following lines
    appear in a file named .gitconfig in your home directory:

and the parts can use some improvement.  For example, "home directory"
does not hold true for people on platforms that lack the concept.  Keeping
the current "the following lines appear", rewording "in a file named
.gitconfig in your home directory" with "in your per-user configuration
file", keeping the display that shows how the config snippet should look
like, and using "config --global -e" might be a better approach.


[Footnote]

*1* Unless you are changing the flow of how this manual teaches at the
same time, that is.  And no, I am not suggesting that we should start from
"let's do a hello-world repository from scratch".  I think the current
"start from read-only and then learn how to grow history later" is one
valid way to teach.

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Sat, Oct 24, 2009 at 9:19 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>
>>> Reworded the getting started section based on comments from Michael J Gruber,
>>> Jonathan Nieder and Junio C Hamano.
>>
>> Hmm, I thought JBF also had some input...
>
> Ah, nevermind. Yes, he did have input, and I tend to agree with him, and
> more importantly trust his judgement on the manual.

JBF said this[1]:
If we have to do this, just keep it short....

And I am trying to keep it short.

> I think a "Getting started" section that only covers "git config" looks
> way out of place in the beginning of this document.

Now you are saying that the fact that it's short is a bad thing? That
goes against to what JBF said.

And let's not forget your previous comments

[2]: I think a "getting started" section near the beginning of the manual is a
good idea (and ll.40- is a very early part of the manual).

[3]: I actually wish this section appeared a lot earlier in the document, but
that is a separate issue.

> Manuals by other people that teach "here is how you would do a hello-world
> repository" would want to teach user.name before reaching that point, but
> because the user-manual is written in such a way that it first introduces
> concepts to understand what is going on without changing anything, we do
> not have much need user.name until it gets to "Developing with git"
> section.
>
> "Many people prefer to teach it this way" does not justify "everybody must
> teach it this way" an iota, when teaching "config user.name" upfront will
> fit the flow of how they teach but does not fit the flow of how this
> manual teaches [*1*].

Nobody argued that "everybody must teach it this way", the argument
was that most people find it easier, and considering the section is
about "developing with git" it is sensible to avoid burdening the
reader with concepts that don't pertain to the objective at hand,
which is getting them to configure their user.

And let's not forget that the current text is broken for Windows users.

> I'm inclined to to discard the first patch.

And you decided to mention that after many people including you, have
agreed that it's a good idea?

> The point of the original text the second patch touches was to show how
> simple the contents of the configuration file is and give the users that
> there is nothing magic there.  While I do not like the second patch as-is,
> because it destroys that nice property and treats the end users mindless
> "cut-and-paste without thinking" sheeples,

What's wrong with teaching one thing at a time? Configuring the user
is something so essential, I don't think it makes sense to make the
task difficult on purpose. Some people might avoid doing it precisely
because of that.

> I think that it is rather vague
> and unhelpful to the current target audience to say:
>
>    ...  The easiest way to do so is to make sure the following lines
>    appear in a file named .gitconfig in your home directory:
>
> and the parts can use some improvement.  For example, "home directory"
> does not hold true for people on platforms that lack the concept.  Keeping
> the current "the following lines appear", rewording "in a file named
> .gitconfig in your home directory" with "in your per-user configuration
> file", keeping the display that shows how the config snippet should look
> like, and using "config --global -e" might be a better approach.

If you read the results of the last git survey you'll see that the
area that needs most improvement is the documentation. Also I still
see many people doing commits without configuring the user name and
email properly and so I've tried very hard to improve the user manual
to make it easier for them to understand they must do that. In the
process I've added the --edit option to 'git config' and the new
"getting started" section, in order to address all the issues
mentioned in previous threads and gone through several iterations of
these patches already.

I'm starting to think that all the previous "constructive" feedback
was actually targeted to deter people from making any changes.

I'm CC'ing people that have been involved in previous threads.

> [Footnote]
>
> *1* Unless you are changing the flow of how this manual teaches at the
> same time, that is.  And no, I am not suggesting that we should start from
> "let's do a hello-world repository from scratch".  I think the current
> "start from read-only and then learn how to grow history later" is one
> valid way to teach.

I also don't think the flow should be changed, that's why I didn't put
the user configuration on the "getting started" section. It goes into
the "developing with git" section.

[1] http://article.gmane.org/gmane.comp.version-control.git/130236
[2] http://article.gmane.org/gmane.comp.version-control.git/115649
[3] http://article.gmane.org/gmane.comp.version-control.git/106667

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[J. Bruce Fields]

On Sat, Oct 24, 2009 at 11:16:51PM +0300, Felipe Contreras wrote:
> And let's not forget that the current text is broken for Windows users.

Just out of curiosity: do you have a list of what would need to be done
to make the manual work for windows users?

I haven't used any Windows/DOS commandline since, um, 1980-something, so
I'm a little clueless here.

--b.

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

>> I'm inclined to to discard the first patch.
>
> And you decided to mention that after many people including you, have
> agreed that it's a good idea?

This line of argument is wrong and counterproductive.  Of course, after
reading what others said and thinking about it more myself, I can change
my mind based on their opinions.  Otherwise there is no point in having
any mailing list discussion.

People propose changes, and two things can happen:

 (1) I and others may think it is not a good idea, clarifying argument may
     come from the original author and/or additional arguments defending
     the change may come from others.  People who thought it was not a
     good idea may change their mind, and the patch gets accepted.  git
     becomes better.

     If people cannot change their mind, it is useless to make supporting
     arguments to nudge them to reconsider.

 (2) I and others may think it is a good idea, a counterargument comes,
     and people who originally thought it was a good idea may change their
     mind, and the patch does not go in.  git is saved from becoming
     worse.

     If people cannot change their mind, it is useless to make counter-
     arguments to nudge them to reconsider.

Yes, I originally thought a "getting started" section may be a good idea.
There is no need to point it out to me.

But after I saw that the original author said "_if_ we have to do this,
keep it short", the comment made me question my previous assumption one
more time: is it really a good idea to add "getting started", and is it a
good idea to cover the config command in that section?

After re-reading the first thousand lines of the user manual, I realized
that the explanation was carefully laid out so that you do not have to be
taught "git config" in the beginning to be able to follow it.  Now, after
applying your latest patch, if we do not have to teach "config" there,
what else is left in the section? --- Nothing.

What conclusion do you expect me to reach after such a consideration,
other than "then let's not have it"?

> If you read the results of the last git survey you'll see that the
> area that needs most improvement is the documentation.

Yes, I did read it, but what about it?  You already know we both want to
have a good set of documentation.

Remember that "changing" and "improving" is different; some changes may
not necessarily be improvements.  "It needs improving, so let's change it"
is not an argument.  This isn't obviously limited to the documentation but
also applies to UI changes.

> Also I still
> see many people doing commits without configuring the user name and
> email properly and so I've tried very hard to improve the user manual
> to make it easier for them to understand they must do that.

The "unconfigured user.name is wrong" is the least of the problems for
people who start commiting without understanding the basic principles.
People may ask "how do I publish my changes", "how do I discard the
commit" and "how do I modify the commit two days ago", and teaching them
things like "reset HEAD^" and "rebase -i", without making them aware of
the implications will do disservice to them in the long run.  That kind of
self-teaching is already done by people (and for doing so sometimes they
hurt themselves) by diving into man pages of individual commands before
understanding the distributedness and its implications, and my hope has
always been to keep the user-manual a document that teaches things in one
coherent and hopefully the most useful order.

The early part of the manual (the first thousand lines) does not talk
about making commits but lays out the groundwork for a good reason.  And
in order to follow the current structure of the manual, you do not need to
be taught "config" as the first thing.

It is a totally different story if we are going to rewrite the manual in
such a way that we start from "hello world".  I am not necessarily saying
it is a bad way to teach [*1*].

But the current "starting from a sightseer, while learning the basic
concepts like reachability and stuff, and then learn to build on top of
others' work" structure would also be a valid way to teach, and in that
presentation order, I do not think teaching "config" sits well at the
beginning.


[Footnote]

*1* Indeed, the book I did recently does just that, starting from a solo
user who develops on his own from scratch, and then uses another
repository as a back up repository, and then works on two different
machines with a repository each, still working solo no the same project.
After that working with other users collaboratively comes. If you teach in
that order, you have to cover config before you cover commit, which pretty
much means config is mentioned at the very beginning.

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Sun, Oct 25, 2009 at 6:08 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>>> I'm inclined to to discard the first patch.
>>
>> And you decided to mention that after many people including you, have
>> agreed that it's a good idea?
>
> This line of argument is wrong and counterproductive.  Of course, after
> reading what others said and thinking about it more myself, I can change
> my mind based on their opinions.  Otherwise there is no point in having
> any mailing list discussion.
>
> People propose changes, and two things can happen:
>
>  (1) I and others may think it is not a good idea, clarifying argument may
>     come from the original author and/or additional arguments defending
>     the change may come from others.  People who thought it was not a
>     good idea may change their mind, and the patch gets accepted.  git
>     becomes better.
>
>     If people cannot change their mind, it is useless to make supporting
>     arguments to nudge them to reconsider.
>
>  (2) I and others may think it is a good idea, a counterargument comes,
>     and people who originally thought it was a good idea may change their
>     mind, and the patch does not go in.  git is saved from becoming
>     worse.
>
>     If people cannot change their mind, it is useless to make counter-
>     arguments to nudge them to reconsider.

Yes, people can change their mind, but if they do so, they must tell
it as it is, and you didn't:
  I think a "Getting started" section that only covers "git config" looks
  way out of place in the beginning of this document.

If you would have said it properly "I've changed my mind" there's an
obvious question that arises: Why? What made you change your mind. You
didn't say that either.

> Yes, I originally thought a "getting started" section may be a good idea.
> There is no need to point it out to me.

One never knows =/

> But after I saw that the original author said "_if_ we have to do this,
> keep it short", the comment made me question my previous assumption one
> more time: is it really a good idea to add "getting started", and is it a
> good idea to cover the config command in that section?
>
> After re-reading the first thousand lines of the user manual, I realized
> that the explanation was carefully laid out so that you do not have to be
> taught "git config" in the beginning to be able to follow it.  Now, after
> applying your latest patch, if we do not have to teach "config" there,
> what else is left in the section? --- Nothing.
>
> What conclusion do you expect me to reach after such a consideration,
> other than "then let's not have it"?

Aha! That's the explanation I was looking for, and what I think you
should have said in the first place. Now we can do some productive
discussion.

I disagree. I think it's awfully useful to have color.ui = auto
configured before reading the multitude of 'git branch', 'git show',
and 'git diff' commands that are presented on first two sections. So
useful, in fact, that I think it should be enabled by default.

Supposing that color.ui is 'auto' by default, then yeah, I don't see
the point of such a "git config" section so early in the document, but
it must be explained somewhere.

>> If you read the results of the last git survey you'll see that the
>> area that needs most improvement is the documentation.
>
> Yes, I did read it, but what about it?  You already know we both want to
> have a good set of documentation.
>
> Remember that "changing" and "improving" is different; some changes may
> not necessarily be improvements.  "It needs improving, so let's change it"
> is not an argument.  This isn't obviously limited to the documentation but
> also applies to UI changes.

No, but "improving" needs "changing", and the discussion I see is
biased towards "not changing".

>> Also I still
>> see many people doing commits without configuring the user name and
>> email properly and so I've tried very hard to improve the user manual
>> to make it easier for them to understand they must do that.
>
> The "unconfigured user.name is wrong" is the least of the problems for
> people who start commiting without understanding the basic principles.
> People may ask "how do I publish my changes", "how do I discard the
> commit" and "how do I modify the commit two days ago", and teaching them
> things like "reset HEAD^" and "rebase -i", without making them aware of
> the implications will do disservice to them in the long run.  That kind of
> self-teaching is already done by people (and for doing so sometimes they
> hurt themselves) by diving into man pages of individual commands before
> understanding the distributedness and its implications, and my hope has
> always been to keep the user-manual a document that teaches things in one
> coherent and hopefully the most useful order.

I don't think the user manual is achieving that purpose. I don't know
if it's the user manual's fault, or git's UI. Both areas need a lot of
improvement (as the git user survey suggests), and I've tried to
improve both with a lot resistance in both. So I'm not very hopeful
anymore.

> The early part of the manual (the first thousand lines) does not talk
> about making commits but lays out the groundwork for a good reason.  And
> in order to follow the current structure of the manual, you do not need to
> be taught "config" as the first thing.
>
> It is a totally different story if we are going to rewrite the manual in
> such a way that we start from "hello world".  I am not necessarily saying
> it is a bad way to teach [*1*].
>
> But the current "starting from a sightseer, while learning the basic
> concepts like reachability and stuff, and then learn to build on top of
> others' work" structure would also be a valid way to teach, and in that
> presentation order, I do not think teaching "config" sits well at the
> beginning.

IMO the vast majority of git users will use it to just fetch a
repository, and browse through it, and that's because most people are
not developers. Even developers most probably will start that way, and
only start committing after a while.

However, I haven't met any proficient git user that got to that point
by reading the user manual, so I think it must be completely
re-thought. Judging from the luck I've had pushing even the simplest
changes I don't think it will improve much more, unfortunately.

Cheers.

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Jonathan Nieder]

Hi Felipe,

Felipe Contreras wrote:

> I disagree. I think it's awfully useful to have color.ui = auto
> configured before reading the multitude of 'git branch', 'git show',
> and 'git diff' commands that are presented on first two sections. So
> useful, in fact, that I think it should be enabled by default.

This is why I think you had a good idea here.  When a program doesn’t
behave as I would like, it can be very comforting to know where its
dotfile is and be able to edit it (I’m not sure how I learn this for
most programs).  And it is much easier to parse git output without
reading it all when color is turned on, so that is a setting I imagine
could be useful to people.

On the other hand, it is far more pleasant to use a program that
doesn’t need configuration at all.  And as I mentioned before, it is
best to avoid wasted time at the beginning of the manual.

> Supposing that color.ui is 'auto' by default,

Should it be?  I think it would not be too hard to detect a color
terminal by checking $TERM.  Are many people bothered by color?  Do we
need some way to make it more obvious how to turn color _off_?

> No, but "improving" needs "changing", and the discussion I see is
> biased towards "not changing".
[...]
> I don't think the user manual is achieving that purpose. I don't know
> if it's the user manual's fault, or git's UI. Both areas need a lot of
> improvement (as the git user survey suggests), and I've tried to
> improve both with a lot resistance in both. So I'm not very hopeful
> anymore.

I hope you have not misunderstood.  I cannot speak for everyone else
here, but I know I am happier when (1) fixes match problems to be
solved in a documented way and (2) fixes do not unnecessarily break
unrelated habits.  One way to bring this about is to justify each
change by explaining what real problem it will solve and how it avoids
collateral damage.  Without that justification, a change is indeed
dangerous and might be worth resisting until it gets clarified.  But
this is not meant to prevent fixes from occuring at all.

Could you list some UI patches that were overlooked or not properly
addressed?  Maybe people just forgot about them or were waiting for an
updated version, or maybe the problems some solve weren’t articulated
clearly yet.  I would be glad to help out in any way I can.

> However, I haven't met any proficient git user that got to that point
> by reading the user manual, so I think it must be completely
> re-thought.

I have met one.  (Well, he read the git tutorial and learned by using
git, too.)  I think the user manual’s pretty well written, though it
certainly has its gaps and rough spots.

> Judging from the luck I've had pushing even the simplest
> changes I don't think it will improve much more, unfortunately.

Even the simplest changes can be hard.  But I hope they do not amount
to nothing.  I hope at the very least the git-config manual page will
improve...

Thank you for working on this.  I hope you succeed in improving git’s
usability, one way or another.

Regards,
Jonathan

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Felipe Contreras wrote:
>> Supposing that color.ui is 'auto' by default,
>
> Should it be?  I think it would not be too hard to detect a color
> terminal by checking $TERM.  Are many people bothered by color?  Do we
> need some way to make it more obvious how to turn color _off_?

I think it should be.

>> No, but "improving" needs "changing", and the discussion I see is
>> biased towards "not changing".
> [...]
>> I don't think the user manual is achieving that purpose. I don't know
>> if it's the user manual's fault, or git's UI. Both areas need a lot of
>> improvement (as the git user survey suggests), and I've tried to
>> improve both with a lot resistance in both. So I'm not very hopeful
>> anymore.
>
> I hope you have not misunderstood.  I cannot speak for everyone else
> here, but I know I am happier when (1) fixes match problems to be
> solved in a documented way and (2) fixes do not unnecessarily break
> unrelated habits.  One way to bring this about is to justify each
> change by explaining what real problem it will solve and how it avoids
> collateral damage.  Without that justification, a change is indeed
> dangerous and might be worth resisting until it gets clarified.  But
> this is not meant to prevent fixes from occuring at all.

Well. I've sent many patches, and gone through several iterations.
After fixing all outstanding issues, addressing all the comments, and
getting several "I like this" votes, Junio suddenly decides he doesn't
like the initial changes at all and doesn't provide any way forward.

I don't see how that's an environment that fosters changes.

> Could you list some UI patches that were overlooked or not properly
> addressed?  Maybe people just forgot about them or were waiting for an
> updated version, or maybe the problems some solve weren’t articulated
> clearly yet.  I would be glad to help out in any way I can.

For example there have been many attempts to bring the 'git stage' to
foreground of the UI; right now it's kind of hidden and many people
don't even realize it's there. Even simplistic attempts as
standardizing --index, --cache and so on into --stage have failed
miserably.

Again, there doesn't seem to be a path forward. Perhaps the git's
stage will remain an obscure feature of git forever. (all the input
from git user's survey points out that people are not really using it)

>> Judging from the luck I've had pushing even the simplest
>> changes I don't think it will improve much more, unfortunately.
>
> Even the simplest changes can be hard.  But I hope they do not amount
> to nothing.  I hope at the very least the git-config manual page will
> improve...

What I mean is: if the simplest changes are *impossible*, then there's
barely any hope of progress.

Cheers.

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Michael J Gruber]

Felipe Contreras venit, vidit, dixit 12.11.2009 00:15:
> On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
>> Felipe Contreras wrote:
>>> Supposing that color.ui is 'auto' by default,
>>
>> Should it be?  I think it would not be too hard to detect a color
>> terminal by checking $TERM.  Are many people bothered by color?  Do we
>> need some way to make it more obvious how to turn color _off_?
> 
> I think it should be.

Back then (before my involvement with git) the result of the discussion
was something like: "Since some of us are way more opposed to the use of
colors than others are in favor..." This does not sound overly democratic.

Feel free to bring this issue on for a change in Git 1.7.0. It would be
good to research any possible incompatibilities this would imply (other
than the looks of the output),

>>> No, but "improving" needs "changing", and the discussion I see is
>>> biased towards "not changing".
>> [...]
>>> I don't think the user manual is achieving that purpose. I don't know
>>> if it's the user manual's fault, or git's UI. Both areas need a lot of
>>> improvement (as the git user survey suggests), and I've tried to
>>> improve both with a lot resistance in both. So I'm not very hopeful
>>> anymore.
>>
>> I hope you have not misunderstood.  I cannot speak for everyone else
>> here, but I know I am happier when (1) fixes match problems to be
>> solved in a documented way and (2) fixes do not unnecessarily break
>> unrelated habits.  One way to bring this about is to justify each
>> change by explaining what real problem it will solve and how it avoids
>> collateral damage.  Without that justification, a change is indeed
>> dangerous and might be worth resisting until it gets clarified.  But
>> this is not meant to prevent fixes from occuring at all.
> 
> Well. I've sent many patches, and gone through several iterations.
> After fixing all outstanding issues, addressing all the comments, and
> getting several "I like this" votes, Junio suddenly decides he doesn't
> like the initial changes at all and doesn't provide any way forward.
> 
> I don't see how that's an environment that fosters changes.

The process can be frustrating at times. Many patches go through many
rounds. I've had occasions where I got frustrated and gave up, as well
as those where I learned a lot and the actual result was much better
than it would have been without thorough discussions. It's this process
which tries to ensure that the project is moving forward most of the
time, rather than sporadically back and forth; moving forward maybe a
bit slower, but still at an impressive overall rate.

Regarding this specific patch series: I took part in the initial
discussion, and got frustrated by the original poster's seemingly
unwillingness to accept advice, so I left. I'm not drawing any general
conclusions, and please don't take this as an ad hominem argument.
Sometimes it's simply a matter of mismatching participants.

It's just my impression that many people retreat from a discussion
because they feel it's getting unproductive (from their particular point
of view), maybe hoping the thread will die out sooner or later. Once it
looks as if something they object to could be included they come back
with counter arguments. This makes the discussion seemingly go back and
forth, but is a natural sociological effect.

>> Could you list some UI patches that were overlooked or not properly
>> addressed?  Maybe people just forgot about them or were waiting for an
>> updated version, or maybe the problems some solve weren’t articulated
>> clearly yet.  I would be glad to help out in any way I can.
> 
> For example there have been many attempts to bring the 'git stage' to
> foreground of the UI; right now it's kind of hidden and many people
> don't even realize it's there. Even simplistic attempts as
> standardizing --index, --cache and so on into --stage have failed
> miserably.
> 
> Again, there doesn't seem to be a path forward. Perhaps the git's
> stage will remain an obscure feature of git forever. (all the input
> from git user's survey points out that people are not really using it)

I didn't read that out of the survey. On the other hand, the last survey
pretty impressively showed where it had been publicized most
prominently. One should keep that in mind when interpreting the results.

If you care to go back to that discussion you see that there is good
reason for having both --cached and --index. They are different. "git
help cli" explains this nicely.

"To stage" has been introduced to describe what "git add" does to people
who hard wire "add" to the meaning it has in other VCSes. In fact, this
would be unnecessary if the concept of Git as a *content* tracker could
be transmitted more successfully. Git cares about content only, so what
could "git add" possibly mean?

"git stage" is a failed follow up ui experiment.

In this regard, I think the problem is that there are really two kinds
of people in terms of learning style:

- Some prefer recipes, similarities with previously known recipes. "How
do I...?" And then try do understand "How does (G)it...?" from that.

- Some want to understand concepts first: "How does (G)it...?" And then
figure out how to use (G)it to do what they want.

I'd guess most developers and a large fraction of the "technical crowd"
belong in the second camp.

I still think we should both

- try and teach concepts early, emphasize that Git is different
(content, index, branch - that's it)
- make Git behave in "expected ways", making it easy for the (willing)
beginner) without compromising its usefulness as a power tool.

I better stop before I digress even more from the original topic :)

Michael

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Thu, Nov 12, 2009 at 1:29 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Feel free to bring this issue on for a change in Git 1.7.0. It would be
> good to research any possible incompatibilities this would imply (other
> than the looks of the output),

Isn't that what we are doing just now?

> The process can be frustrating at times. Many patches go through many
> rounds. I've had occasions where I got frustrated and gave up, as well
> as those where I learned a lot and the actual result was much better
> than it would have been without thorough discussions. It's this process
> which tries to ensure that the project is moving forward most of the
> time, rather than sporadically back and forth; moving forward maybe a
> bit slower, but still at an impressive overall rate.

Except in this case there is no path forward. If there is, I would
like to hear it.

> Regarding this specific patch series: I took part in the initial
> discussion, and got frustrated by the original poster's seemingly
> unwillingness to accept advice, so I left. I'm not drawing any general
> conclusions, and please don't take this as an ad hominem argument.
> Sometimes it's simply a matter of mismatching participants.

What are you talking about? All your comments were addressed in
subsequent patches, as the commit message of the patch in this thread
points out.

Moreover, in the paragraph before you argued that these thorough
discussions are actually a good thing. Or are patch committers not
allowed to discuss?

> I didn't read that out of the survey. On the other hand, the last survey
> pretty impressively showed where it had been publicized most
> prominently. One should keep that in mind when interpreting the results.

So? What are the surveys supposed to be for, if not to use the results?

> If you care to go back to that discussion you see that there is good
> reason for having both --cached and --index. They are different. "git
> help cli" explains this nicely.

"good" is a very subjective term; I don't think "they are different"
is a good reason. By that logic --only-index and
--index-and-working-dir serve the same purpose, just like --gogo and
--dance.

But there's no point in discussing this until people accept there is a
problem, and there seems to be unwillingness to accept that very few
people use the stage properly.

> "To stage" has been introduced to describe what "git add" does to people
> who hard wire "add" to the meaning it has in other VCSes. In fact, this
> would be unnecessary if the concept of Git as a *content* tracker could
> be transmitted more successfully. Git cares about content only, so what
> could "git add" possibly mean?

usage: git add [options] [--] <filepattern>...

I don't see any mention of this "blob" mythical creature. In the vast
majority of the minds of git users, 'git add' adds files to the
repository, just like any other VCS.

Proof of that is that only 23% of the people use "git add -i / -p" and
15% "git add -u / -A" often.

> "git stage" is a failed follow up ui experiment.

I agree with that. But assuming because one UI experiment failed, all
other "stage" proposals are doomed.

> In this regard, I think the problem is that there are really two kinds
> of people in terms of learning style:
>
> - Some prefer recipes, similarities with previously known recipes. "How
> do I...?" And then try do understand "How does (G)it...?" from that.
>
> - Some want to understand concepts first: "How does (G)it...?" And then
> figure out how to use (G)it to do what they want.
>
> I'd guess most developers and a large fraction of the "technical crowd"
> belong in the second camp.

I actually belong to the two groups. When I started to use git I
learned it through recipes and grew fond of it, but didn't really know
what was really happening even thought I used it for years. It wasn't
until a colleague recommended me to read "Git from the bottom up",
then I really started to understand git and realized I didn't know
squat. Sure, I heard concepts such as "feature branches", "rebase" and
"stage interactive", and I had in my to-do list to learn them, but
that was it.

I'm pretty sure the vast majority of users are in the darkness just as I was.

> I still think we should both

What?

> - try and teach concepts early, emphasize that Git is different
> (content, index, branch - that's it)

Well, that's the first failure right there. If your objective is to
confuse people, then sure, call it "index", otherwise choose a name
that corresponds with it's purpose: stage.

> - make Git behave in "expected ways", making it easy for the (willing)
> beginner) without compromising its usefulness as a power tool.

Sure, but if the UI was more friendly people would learn to use the
advanced features through it's use. Currently there are no ropes to do
that. You have to read a book or something.

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Nanako Shiraishi]

Quoting Michael J Gruber <git@drmicha.warpmail.net>

> Regarding this specific patch series: I took part in the initial
> discussion, and got frustrated by the original poster's seemingly
> unwillingness to accept advice, so I left. I'm not drawing any general
> conclusions, and please don't take this as an ad hominem argument.
> Sometimes it's simply a matter of mismatching participants.

I didn't get myself involved in the follow-up discussion exactly 
for the same reason.

> If you care to go back to that discussion you see that there is good
> reason for having both --cached and --index. They are different. "git
> help cli" explains this nicely.

The need to support both options in the same command (eg. apply) means 
that anybody who says "I don't like 'index' nor 'cache'; why don't we 
change them all to 'stage'" doesn't understand the issue.

But that doesn't mean "apply --cached" vs "apply --index" is the best 
way to let the users specify which operation is requested. I don't 
think Felipe seriously wants to change them to --gogo vs --dance, but 
if he made a more constructive proposal, instead of making such a 
comment whose intended effect is only to annoy people, we may see 
an improved UI at the end.  Proposing "--index-only" vs "--index-too" 
or even "--stage-only" vs "--stage-too" would have helped him appear 
to be more serious and constructive and I think your expression 
"mismatching participants" was a great way to say this.

There was a similar discussion about "diff --cached". The command 
compares two things and the current syntax relies on counting the 
number of treeish on the command line to specify what these two things 
are, and sometimes people are confused which way the comparison occurs.

 * If you have two treeish, it compares the two treeish. Specifically, 
   it shows the change to make one treeish into the other treeish.

 * If you have one treeish, it compares the treeish with working tree 
   or the index (it shows the change to make the treeish into working 
   tree or the index). You need --cached to choose the "index", and
   this can safely be aliased to --staged.

 * If you have zero treeish, it compares the index with working tree 
   (it shows the change to make the index into working tree).

But it is also possible to have an alternate syntax to explicitly say
what you are comparing with what. Perhaps these may make it unnecessary
to remember which way the comparison occurs:

 git diff --tree-vs-staged HEAD
	same as "git diff --cached HEAD"
 git diff --staged-vs-tree HEAD
	same as "git diff -R --cached HEAD"

 git diff --staged-vs-working
	same as "git diff"
 git diff --working-vs-staged
	same as "git diff -R"

 git diff --tree-vs-working HEAD
	same as "git diff HEAD"
 git diff --working-vs-tree HEAD
	same as "git diff -R HEAD"

If people like this as a concept we can introduce shorter way to spell 
them, eg. "git diff --ts HEAD", etc.

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Quoting Michael J Gruber <git@drmicha.warpmail.net>
>> If you care to go back to that discussion you see that there is good
>> reason for having both --cached and --index. They are different. "git
>> help cli" explains this nicely.
>
> The need to support both options in the same command (eg. apply) means
> that anybody who says "I don't like 'index' nor 'cache'; why don't we
> change them all to 'stage'" doesn't understand the issue.
>
> But that doesn't mean "apply --cached" vs "apply --index" is the best
> way to let the users specify which operation is requested. I don't
> think Felipe seriously wants to change them to --gogo vs --dance, but
> if he made a more constructive proposal, instead of making such a
> comment whose intended effect is only to annoy people, we may see
> an improved UI at the end.  Proposing "--index-only" vs "--index-too"
> or even "--stage-only" vs "--stage-too" would have helped him appear
> to be more serious and constructive and I think your expression
> "mismatching participants" was a great way to say this.

Right, your explanation is more clear: the fact that we need both
doesn't mean we cannot use the term "stage". As to "constructive
proposal" I deliberately tried to avoid them in case somebody tried to
disregard it as bike-shedding, and move on. What I'm trying to do is
bring up the issue that the stage is not user friendly.

> There was a similar discussion about "diff --cached". The command
> compares two things and the current syntax relies on counting the
> number of treeish on the command line to specify what these two things
> are, and sometimes people are confused which way the comparison occurs.
>
>  * If you have two treeish, it compares the two treeish. Specifically,
>   it shows the change to make one treeish into the other treeish.
>
>  * If you have one treeish, it compares the treeish with working tree
>   or the index (it shows the change to make the treeish into working
>   tree or the index). You need --cached to choose the "index", and
>   this can safely be aliased to --staged.
>
>  * If you have zero treeish, it compares the index with working tree
>   (it shows the change to make the index into working tree).
>
> But it is also possible to have an alternate syntax to explicitly say
> what you are comparing with what. Perhaps these may make it unnecessary
> to remember which way the comparison occurs:
>
>  git diff --tree-vs-staged HEAD
>        same as "git diff --cached HEAD"
>  git diff --staged-vs-tree HEAD
>        same as "git diff -R --cached HEAD"
>
>  git diff --staged-vs-working
>        same as "git diff"
>  git diff --working-vs-staged
>        same as "git diff -R"
>
>  git diff --tree-vs-working HEAD
>        same as "git diff HEAD"
>  git diff --working-vs-tree HEAD
>        same as "git diff -R HEAD"

I like David Kågedal's suggestion more:
http://kerneltrap.org/mailarchive/git/2008/10/29/3857134

Cheers.

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Nanako Shiraishi]

Quoting Felipe Contreras <felipe.contreras@gmail.com>

> On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
>> ... I don't
>> think Felipe seriously wants to change them to --gogo vs --dance, but
>> if he made a more constructive proposal, instead of making such a
>> comment whose intended effect is only to annoy people, we may see
>> an improved UI at the end.  Proposing "--index-only" vs "--index-too"
>> or even "--stage-only" vs "--stage-too" would have helped him appear
>> to be more serious and constructive and I think your expression
>> "mismatching participants" was a great way to say this.
>
> Right, your explanation is more clear:

You have a funny way of saying "I'm sorry, I wasn't constructive, 
and my attitude repelled many participants from the discussion".

> the fact that we need both
> doesn't mean we cannot use the term "stage". As to "constructive
> proposal" I deliberately tried to avoid them in case somebody tried to
> disregard it as bike-shedding, and move on.

If the only constructive proposal you could make is to replace 
words used in two operations without clarifying concepts any 
better to newbies, then what you are doing is bike-shedding. 
I don't think trying to hide that by not making any proposal 
changes that.

> What I'm trying to do is
> bring up the issue that the stage is not user friendly.

I thought you were the one who wanted to use "stage" everywhere?

For what it's worth, "stage" isn't very user friendly to me; 
maybe it is because I'm not a native English speaker. I'm not 
saying that when I hear "index" or "cached" I'll understand 
what they mean even if I didn't have any prior knowledge of 
git, but I am saying "stage" isn't any better than these two 
words in that respect. Of course the user needs to understand 
what it is and how it is used, no matter what word you use.

I think a proposal to replace the word "index" with "stage" 
will sound nothing but bike-shedding to anybody, especially 
after getting familiar with "index" and seeing it taught on 
many web pages and books.

> I like David Kågedal's suggestion more:
> http://kerneltrap.org/mailarchive/git/2008/10/29/3857134

For people who like a usable threaded interface to read 
the message in context here is its URL.

http://thread.gmane.org/gmane.comp.version-control.git/99332/focus=99401

Yes, I had David's proposal in mind when I wrote my response. 
Even though the fundamental idea is the same, I used --X-vs-Y 
option to avoid the problems David's proposal has in a slightly 
nicer way.

David's proposal introduced two magic tokens STAGE and WORKTREE.

  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)

This looks nice on surface, but I think the apparent niceness 
is shallow. If of course has a small problem of introducing an 
obvious backward incompatibility. You can't use a branch whose 
name is STAGE anymore, but a deeper problem is that these two 
magic tokens pretend to be refs. But they do so only to the diff 
command. I don't see how you can make them sanely be usable to 
other commands like "git log v1.0.0..WORKTREE".

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[J. Bruce Fields]

On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote:
> David's proposal introduced two magic tokens STAGE and WORKTREE.
> 
>   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)
> 
> This looks nice on surface, but I think the apparent niceness 
> is shallow. If of course has a small problem of introducing an 
> obvious backward incompatibility. You can't use a branch whose 
> name is STAGE anymore, but a deeper problem is that these two 
> magic tokens pretend to be refs. But they do so only to the diff 
> command. I don't see how you can make them sanely be usable to 
> other commands like "git log v1.0.0..WORKTREE".

Doesn't appear that refs have to point to commits; e.g., on the linux
project:

	git log v2.6.11-tree..v2.6.32-rc7
	error: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a
	commit
	fatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7


You might be able to add some extra syntax to prevent conflicts with
branch names.  Uh, :STAGE, :WORKTREE ??  But I think that conflicts with
something else.  And the "magic tokens" get a little uglier and harder
to remember.  Bah.

--b.

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Matthieu Moy]

Nanako Shiraishi <nanako3@lavabit.com> writes:

> I don't see how you can make them sanely be usable to 
> other commands like "git log v1.0.0..WORKTREE".

See what gitk is showing you when you have uncommited changes. You
have some kind of "pseudo-commits" on top of your history for the
index and the worktree. "git log v1.0.0..WORKTREE" could very well be
a text-mode version of what's already in gitk.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote:
>> David's proposal introduced two magic tokens STAGE and WORKTREE.
>> 
>>   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)
>> 
>> This looks nice on surface, but I think the apparent niceness 
>> is shallow. If of course has a small problem of introducing an 
>> obvious backward incompatibility. You can't use a branch whose 
>> name is STAGE anymore, but a deeper problem is that these two 
>> magic tokens pretend to be refs. But they do so only to the diff 
>> command. I don't see how you can make them sanely be usable to 
>> other commands like "git log v1.0.0..WORKTREE".
>
> Doesn't appear that refs have to point to commits; e.g., on the linux
> project:
>
> 	git log v2.6.11-tree..v2.6.32-rc7
> 	error: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a
> 	commit
> 	fatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7

True.  A ref can even point to a blob.

I think "diff" always takes two (pseudo-)tree-ish in David's world, and
you should be able to use these magic topens anywhere that expects a
tree-ish.  For example:

    $ git checkout STAGE Makefile

would be a way to say "please check out the version of Makefile in the
staging area".  And

    $ git archive WORKTREE
    $ git archive STAGE

would be a version of tar that is index-aware.

But we do not have to support commit-ish operations, such as "git log".

It is a different story if these pseudo-refs that denote tree-ish are
useful outside the context of "diff".  I do not think of many commands
that take arbitrary tree-ish other than the ones I mentioned above.  Even
though they take arbitrary tree-ish, people almost always use commit-ish
with them.

Which points to another issue with the approach.

The original intention of these magic tokens are to make things easier,
but they actually may make things _harder_ to teach, because you have to
explain why "git log WORKTREE" does not work but "git archive WORKTREE"
does.  Admittedly, you already have to explain your example to people
saying "it does not work because v2.6.11 is a tree and a tree by itself
does not have a point in history", but the thing is, v2.6.11-tree and
v2.6.11 are oddballs, and you do not have to give that explanation very
often, simply because the users are not exposed to a raw tree.

But WORKTREE and STAGE tokens are _meant_ to be exposed to them much more
prominently.  That's the whole point of the "git diff STAGE WORKTREE"
proposal.

People would become aware that they are very different from ordinary
commits, and then eventually they will realize that they are not even
trees [*1*].  

At that point, I suspect that these magic tokens become larger UI warts
themselves; they behave differently from everything else that is spelled
in all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD).

As to --tree-vs-index counterproposal (was it a counterproposal?), except
for that I think they are too long to type in practice and need to be
shortened to be useful, I do not have a fundamental objection against it.


[Footnote]

*1* For example, I would not expect that we will make "git show WORKTREE"
to build a tree on the fly by running "git add -A && git write-tree" with
a temporary index and then running "git show" on the resulting tree
object, because there would be a better response than that if a user asks
"please show my worktree".

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Tue, Nov 17, 2009 at 8:25 PM, Junio C Hamano <gitster@pobox.com> wrote:
> But we do not have to support commit-ish operations, such as "git log".

Right, and actuallly don't have to support WORKTREE/STAGE on all the
commands that work with the stage. For example I think 'git apply'
behaves completely different than 'git diff', since you cannot apply a
patch on top of a commit, therefore it doesn't make sense to stage
stuff as pseudo-refs; it makes sense to keep the --foo options
(although I would prefer something like --stage and --stage-only).

> It is a different story if these pseudo-refs that denote tree-ish are
> useful outside the context of "diff".  I do not think of many commands
> that take arbitrary tree-ish other than the ones I mentioned above.  Even
> though they take arbitrary tree-ish, people almost always use commit-ish
> with them.
>
> Which points to another issue with the approach.
>
> The original intention of these magic tokens are to make things easier,
> but they actually may make things _harder_ to teach, because you have to
> explain why "git log WORKTREE" does not work but "git archive WORKTREE"
> does.  Admittedly, you already have to explain your example to people
> saying "it does not work because v2.6.11 is a tree and a tree by itself
> does not have a point in history", but the thing is, v2.6.11-tree and
> v2.6.11 are oddballs, and you do not have to give that explanation very
> often, simply because the users are not exposed to a raw tree.
>
> But WORKTREE and STAGE tokens are _meant_ to be exposed to them much more
> prominently.  That's the whole point of the "git diff STAGE WORKTREE"
> proposal.
>
> People would become aware that they are very different from ordinary
> commits, and then eventually they will realize that they are not even
> trees [*1*].
>
> At that point, I suspect that these magic tokens become larger UI warts
> themselves; they behave differently from everything else that is spelled
> in all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD).

That could be easily fixed by making explicit in the syntax that these
are not typical refs: i.e. @stage and @work.

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> That could be easily fixed by making explicit in the syntax that these
> are not typical refs: i.e. @stage and @work.

The message I get from that suggestion is that the most sensible approach,
if we are going to add something from this discussion to "git diff", is to
do what you did _not_ quote from my message, which is:

    As to --tree-vs-index counterproposal (was it a counterproposal?),
    except for that I think they are too long to type in practice and need
    to be shortened to be useful, I do not have a fundamental objection
    against it.

IOW, this is about options, and should not be done as syntax sugar that
does a half-baked job of pretending to be refs.

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Wed, Nov 18, 2009 at 12:19 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> That could be easily fixed by making explicit in the syntax that these
>> are not typical refs: i.e. @stage and @work.
>
> The message I get from that suggestion is that the most sensible approach,
> if we are going to add something from this discussion to "git diff", is to
> do what you did _not_ quote from my message, which is:
>
>    As to --tree-vs-index counterproposal (was it a counterproposal?),
>    except for that I think they are too long to type in practice and need
>    to be shortened to be useful, I do not have a fundamental objection
>    against it.
>
> IOW, this is about options, and should not be done as syntax sugar that
> does a half-baked job of pretending to be refs.

Sorry, I thought your only objection to STAGE and WORKTREE was that
they were not clearly differentiated, and my proposal gets rid of that
issue. Now I fail to see what's the problem since you didn't explain
what's wrong with adding syntactic sugar.

If the goal of the change is to make things more user-friendly, then
I'd say "git diff HEAD @stage" is better than "git diff
--tree-vs-staged HEAD".

-- 
Felipe Contreras

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> If the goal of the change is to make things more user-friendly, then
> I'd say "git diff HEAD @stage" is better than "git diff
> --tree-vs-staged HEAD".

Exactly.  That is where we disagree.  The funny "@stage" does not convey
the fact that it is affecting how "git diff" operates, like any other
option like "-R" does in "git diff -R" command line does.  Now the user
needs to know git commands take -option like other normal tools do, but in
addition they need to remember that an oddball "diff" subcommand takes
"@funny" in addition to the usual "-option".

How would that be an improvement?

Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras]

On Wed, Nov 18, 2009 at 1:13 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Exactly.  That is where we disagree.  The funny "@stage" does not convey
> the fact that it is affecting how "git diff" operates, like any other
> option like "-R" does in "git diff -R" command line does.  Now the user
> needs to know git commands take -option like other normal tools do, but in
> addition they need to remember that an oddball "diff" subcommand takes
> "@funny" in addition to the usual "-option".

Right now there are 4 modes of operations, the user would need to
remember all of them... instead, the @stage pointer would reduce the
modes to 1, so the user would have to look on the man-page only once,
quickly.

Also, to me it feels more natural to do "git diff b a" rather than
"git diff -R a b", therefore "git diff @stage HEAD" beats "git diff -R
--cached HEAD".

Moreover, I wonder if these modes are really properly implemented. For
example, what's with these funky commands:
git diff HEAD master next <- shouldn't only 2 be allowed?
git diff HEAD..master HEAD..next

Anyway, you are making the assumption that users actually use, and
understand the different modes of operation, but I'm claiming most of
them don't, and one of the reasons could be that they are not
intuitive.

> How would that be an improvement?

It might make people actually start using the stage, which again, it
seems apparent to me they don't. This can be easily interpreted from
reading the git user survey (only 23% of the people use "git add -i /
-p", and 15% "git add -u / -A" often), but if you don't believe so, we
can wait for the next one and ask the question explicitly.

-- 
Felipe Contreras