[PATCH 1/2] user-manual: Simplify the user configuration.

[PATCH 1/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 19f571a..3a9704c 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -981,13 +981,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 user.name "Your Name Comes Here"
+$ git config user.email you@yourdomain.example.com
 ------------------------------------------------
 
 (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
-- 
1.6.1

[PATCH 2/2] Fix typo.

[Felipe Contreras]

"its pointless" is wrong, should be "it is pointless" so "it's
pointless".

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 sha1_file.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/sha1_file.c b/sha1_file.c
index f08493f..69fef9f 100644
--- a/sha1_file.c
+++ b/sha1_file.c
@@ -800,7 +800,7 @@ unsigned char* use_pack(struct packed_git *p,
 	if (p->pack_fd == -1 && open_packed_git(p))
 		die("packfile %s cannot be accessed", p->pack_name);
 
-	/* Since packfiles end in a hash of their content and its
+	/* Since packfiles end in a hash of their content and it's
 	 * pointless to ask for an offset into the middle of that
 	 * hash, and the in_window function above wouldn't match
 	 * don't allow an offset too close to the end of the file.
-- 
1.6.1

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Markus Heidelberg]

Felipe Contreras, 21.01.2009:
> +++ b/Documentation/user-manual.txt
> @@ -981,13 +981,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 user.name "Your Name Comes Here"
> +$ git config user.email you@yourdomain.example.com

--global

Markus

[PATCH] 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 19f571a..c8a1b7b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -981,13 +981,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.1

Re: [PATCH] user-manual: Simplify the user configuration.

[Jeff King]

On Wed, Jan 21, 2009 at 09:04:10PM +0200, Felipe Contreras wrote:

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

I seem to recall this coming up several times before, and there being a
sentiment that it was _good_ to introduce the user to concept of a
config file. It lets them know that it exists, approximately what the
syntax looks like, and demystifies what is going on when you type "git
config" (i.e., it intentionally shows that there is more than way to do
it).

I don't have a personal preference, but you may want to grep the
list archives for other discussion.

-Peff

Re: [PATCH] user-manual: Simplify the user configuration.

[Felipe Contreras]

On Wed, Jan 21, 2009 at 9:18 PM, Jeff King <peff@peff.net> wrote:
> On Wed, Jan 21, 2009 at 09:04:10PM +0200, Felipe Contreras wrote:
>
>> 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.
>
> I seem to recall this coming up several times before, and there being a
> sentiment that it was _good_ to introduce the user to concept of a
> config file. It lets them know that it exists, approximately what the
> syntax looks like, and demystifies what is going on when you type "git
> config" (i.e., it intentionally shows that there is more than way to do
> it).
>
> I don't have a personal preference, but you may want to grep the
> list archives for other discussion.

That's over complicating the user with what should probably be one of
the first things to do. Besides, do Windows users know which is their
home directory?

Maybe a comment like previous git config commands:
If you examine the file .gitconfig in your home directory, you will see this:

------------------------------------------------
...
[user]
       name = Your Name Comes Here
       email = you@yourdomain.example.com
...
------------------------------------------------

-- 
Felipe Contreras

Re: [PATCH] user-manual: Simplify the user configuration.

[Jeff King]

On Wed, Jan 21, 2009 at 09:39:27PM +0200, Felipe Contreras wrote:

> That's over complicating the user with what should probably be one of
> the first things to do. Besides, do Windows users know which is their
> home directory?

Like I said, I don't care one way or the other, personally. But you
should at least address points brought up in the previous iterations:

  http://thread.gmane.org/gmane.comp.version-control.git/37921/focus=38007

  http://thread.gmane.org/gmane.comp.version-control.git/46903

-Peff

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Junio C Hamano]

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

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

I am moderately against changing this part to use "git config".

We traditionally introduced how to set configuration variables first by
editing it in an editor, and this was quite deliberate, in order to show
how the configuration file looks like, to demonstrate that there is no
deep magic in the file format, and to explain that it is perfectly Ok to
edit it without using "git config" command.

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

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Wincent Colaiuta]

El 21/1/2009, a las 21:54, Junio C Hamano escribió:

> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> 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.
>
> I am moderately against changing this part to use "git config".
>
> We traditionally introduced how to set configuration variables first  
> by
> editing it in an editor, and this was quite deliberate, in order to  
> show
> how the configuration file looks like, to demonstrate that there is no
> deep magic in the file format, and to explain that it is perfectly  
> Ok to
> edit it without using "git config" command.

If that's the goal, why not do both?:

1. Show people how to use "git config" like this patch does (seeing as  
it's easier and less error prone)

2. Tell people that they can inspect and even edit the config file by  
hand if they want

The actual order of 1 and 2 depends on where you want to place more  
emphasis:

Something like either:

> 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:
>
> [user]
> 	name = Your Name Comes Here
> 	email = you@yourdomain.example.com
>
> As a convenience you can use linkgit:git-config[1] to modify  
> your .gitconfig
> instead of editing it by hand:
>
> $ git config --global user.name "Your Name Comes Here"
> $ git config --global user.email you@yourdomain.example.com


Or:


> Before creating any commits, you should introduce yourself to git.   
> The
> easiest way is to use the linkgit:git-config[1] command:
>
> $ git config --global user.name "Your Name Comes Here"
> $ git config --global user.email you@yourdomain.example.com
>
> Your settings are written to a file named .gitconfig in your home
> directory which you can inspect or even edit by hand. Settings look  
> like this:
>
> [user]
> 	name = Your Name Comes Here
> 	email = you@yourdomain.example.com


Cheers,
Wincent

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Felipe Contreras]

On Wed, Jan 21, 2009 at 10:54 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> 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.
>
> I am moderately against changing this part to use "git config".
>
> We traditionally introduced how to set configuration variables first by
> editing it in an editor, and this was quite deliberate, in order to show
> how the configuration file looks like, to demonstrate that there is no
> deep magic in the file format, and to explain that it is perfectly Ok to
> edit it without using "git config" command.
>
> I actually wish this section appeared a lot earlier in the document, but
> that is a separate issue.

I agree that it's good that people get familiar with the config
format, and that it should appear earlier in the document, perhaps as
a separate section. However, for new users that just want to get
started any extra burden weighs in the misconception that git is not
user friendly.

I read the comments in both threads Jeff pointed out and I have
comments regarding the argument that it's easy to edit a text file.

It's easy to *change* a text file, not so much to write something by
hand. Although the user would probably just copy-paste the text from
the online manual (changing spaces by a tag in the process) there's a
possibility that the manual is printed.

This brings back my previous question: where is the home directory in
a Windows system?

An idea would be to add an --edit option to git config, so the users
don't need to care about the location of the text file and just do
"git config --global --edit" which would bring the editor. Although
I'm not sure how that would work on Windows since the editor is
probably not properly configured at that point.

Now, *nobody* has replied back the comments of providing both the git
config command and .gitconfig snip. It was mentioned in both threads
and ignored.

Anyone against that?

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Hannu Koivisto]

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

> This brings back my previous question: where is the home directory in
> a Windows system?

It's where %HOMEDRIVE%%HOMEPATH% points to.

-- 
Hannu

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Felipe Contreras]

On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> This brings back my previous question: where is the home directory in
>> a Windows system?
>
> It's where %HOMEDRIVE%%HOMEPATH% points to.

I thought it was something like that. Do we want something like that
in the manual, or should we assume Windows users know that?

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Junio C Hamano]

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

> On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>
>>> This brings back my previous question: where is the home directory in
>>> a Windows system?
>>
>> It's where %HOMEDRIVE%%HOMEPATH% points to.
>
> I thought it was something like that. Do we want something like that
> in the manual, or should we assume Windows users know that?

Funny; while I was test driving Msysgit (I wrote the report in my blog
pages some time ago), I got curious about this exact issue.  I thought the
choice of $HOME at that path was quite natural even for me who does not
usually use Windows.

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Johannes Schindelin]

Hi,

On Thu, 22 Jan 2009, Junio C Hamano wrote:

> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
> >> Felipe Contreras <felipe.contreras@gmail.com> writes:
> >>
> >>> This brings back my previous question: where is the home directory in
> >>> a Windows system?
> >>
> >> It's where %HOMEDRIVE%%HOMEPATH% points to.
> >
> > I thought it was something like that. Do we want something like that
> > in the manual, or should we assume Windows users know that?
> 
> Funny; while I was test driving Msysgit (I wrote the report in my blog
> pages some time ago), I got curious about this exact issue.  I thought the
> choice of $HOME at that path was quite natural even for me who does not
> usually use Windows.

That's what they said when they convinced me that /home/<user>/ was not a 
natural place on Windows.

Ciao,
Dscho

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Hannu Koivisto]

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

> On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>
>>> This brings back my previous question: where is the home directory in
>>> a Windows system?
>>
>> It's where %HOMEDRIVE%%HOMEPATH% points to.
>
> I thought it was something like that. Do we want something like that
> in the manual, or should we assume Windows users know that?

I should have added that Unix programs (i.e. Cygwin programs and
even some native ports) probably use %HOME% which may be different
from %HOMEDRIVE%%HOMEPATH%.  I recall that if you haven't
explicitly set up HOME in Windows environment, Cygwin sets it up
magically from passwd or falls back to %HOMEDRIVE%%HOMEPATH%.  I
have no idea if msysgit respects %HOME% if it is set or always uses
%HOMEDRIVE%%HOMEPATH% or something completely different (user
profile, most likely).

It certainly may be that "home directory" is a foreign concept to
some Windows users.  Some might know it as a user profile or a
personal folder (just guessing, I'm pretty isolated from less
experienced Windows users), even though user profile is a separate
concept from "home directory" (note that there is %USERPROFILE%
which by default is the same as %HOMEDRIVE%%HOMEPATH% at least in
XP).

In any case, what Cygwin git does should be expected by Cygwin
users.  If msysgit wanted to be a really native Windows application
and store the configuration where Microsoft thinks it should be
stored, it probably shouldn't store the config under "home
directory" to begin with (I'm guessing that's what it does) but
under %USERPROFILE\Application Data\Git (...FILE\Local
Settings\... in case non-roaming storage is wanted).  And in that
case the manual might be misleading for msysgit users.  See
e.g. <http://msdn.microsoft.com/en-us/library/ms995853.aspx>.

-- 
Hannu

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Felipe Contreras]

On Thu, Jan 22, 2009 at 8:59 PM, Hannu Koivisto <azure@iki.fi> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> This brings back my previous question: where is the home directory in
>>>> a Windows system?
>>>
>>> It's where %HOMEDRIVE%%HOMEPATH% points to.
>>
>> I thought it was something like that. Do we want something like that
>> in the manual, or should we assume Windows users know that?
>
> I should have added that Unix programs (i.e. Cygwin programs and
> even some native ports) probably use %HOME% which may be different
> from %HOMEDRIVE%%HOMEPATH%.  I recall that if you haven't
> explicitly set up HOME in Windows environment, Cygwin sets it up
> magically from passwd or falls back to %HOMEDRIVE%%HOMEPATH%.  I
> have no idea if msysgit respects %HOME% if it is set or always uses
> %HOMEDRIVE%%HOMEPATH% or something completely different (user
> profile, most likely).
>
> It certainly may be that "home directory" is a foreign concept to
> some Windows users.  Some might know it as a user profile or a
> personal folder (just guessing, I'm pretty isolated from less
> experienced Windows users), even though user profile is a separate
> concept from "home directory" (note that there is %USERPROFILE%
> which by default is the same as %HOMEDRIVE%%HOMEPATH% at least in
> XP).
>
> In any case, what Cygwin git does should be expected by Cygwin
> users.  If msysgit wanted to be a really native Windows application
> and store the configuration where Microsoft thinks it should be
> stored, it probably shouldn't store the config under "home
> directory" to begin with (I'm guessing that's what it does) but
> under %USERPROFILE\Application Data\Git (...FILE\Local
> Settings\... in case non-roaming storage is wanted).  And in that
> case the manual might be misleading for msysgit users.  See
> e.g. <http://msdn.microsoft.com/en-us/library/ms995853.aspx>.

Isn't that enough argument to stop assuming the user knows where is
the "home directory"?

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Johannes Schindelin]

Hi,

On Sat, 24 Jan 2009, Felipe Contreras wrote:

> On Thu, Jan 22, 2009 at 8:59 PM, Hannu Koivisto <azure@iki.fi> wrote:
> > Felipe Contreras <felipe.contreras@gmail.com> writes:
> >
> >> On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
> >>> Felipe Contreras <felipe.contreras@gmail.com> writes:
> >>>
> >>>> This brings back my previous question: where is the home directory in
> >>>> a Windows system?
> >>>
> >>> It's where %HOMEDRIVE%%HOMEPATH% points to.
> >>
> >> I thought it was something like that. Do we want something like that
> >> in the manual, or should we assume Windows users know that?
> >
> > I should have added that Unix programs (i.e. Cygwin programs and
> > even some native ports) probably use %HOME% which may be different
> > from %HOMEDRIVE%%HOMEPATH%.  I recall that if you haven't
> > explicitly set up HOME in Windows environment, Cygwin sets it up
> > magically from passwd or falls back to %HOMEDRIVE%%HOMEPATH%.  I
> > have no idea if msysgit respects %HOME% if it is set or always uses
> > %HOMEDRIVE%%HOMEPATH% or something completely different (user
> > profile, most likely).
> >
> > It certainly may be that "home directory" is a foreign concept to
> > some Windows users.  Some might know it as a user profile or a
> > personal folder (just guessing, I'm pretty isolated from less
> > experienced Windows users), even though user profile is a separate
> > concept from "home directory" (note that there is %USERPROFILE%
> > which by default is the same as %HOMEDRIVE%%HOMEPATH% at least in
> > XP).
> >
> > In any case, what Cygwin git does should be expected by Cygwin
> > users.  If msysgit wanted to be a really native Windows application
> > and store the configuration where Microsoft thinks it should be
> > stored, it probably shouldn't store the config under "home
> > directory" to begin with (I'm guessing that's what it does) but
> > under %USERPROFILE\Application Data\Git (...FILE\Local
> > Settings\... in case non-roaming storage is wanted).  And in that
> > case the manual might be misleading for msysgit users.  See
> > e.g. <http://msdn.microsoft.com/en-us/library/ms995853.aspx>.
> 
> Isn't that enough argument to stop assuming the user knows where is
> the "home directory"?

Why does it appear as if we always have to bend over for Windows?  That is 
really frustrating.

In any case, the only thing the user would need to know the location of 
$HOME for is for .gitconfig.  And for Windows users I suggest using the 
dialog in git gui (for the variables that are editable there), which 
should cover most of what the user needs.  For everything else, they 
should use "git config".

Because if you really start with explaining where the home can be on 
Windows, you would also have to cover why "%USERPROFILE%" does not work in 
Git bash.  And before you know what is happening, you have a big ass 
Windows chapter in the user manual that revolves around anything except 
Git.

Ciao,
Dscho

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Felipe Contreras]

On Sat, Jan 24, 2009 at 3:42 PM, Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:
> Hi,
>
> On Sat, 24 Jan 2009, Felipe Contreras wrote:
>
>> On Thu, Jan 22, 2009 at 8:59 PM, Hannu Koivisto <azure@iki.fi> wrote:
>> > Felipe Contreras <felipe.contreras@gmail.com> writes:
>> >
>> >> On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
>> >>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>> >>>
>> >>>> This brings back my previous question: where is the home directory in
>> >>>> a Windows system?
>> >>>
>> >>> It's where %HOMEDRIVE%%HOMEPATH% points to.
>> >>
>> >> I thought it was something like that. Do we want something like that
>> >> in the manual, or should we assume Windows users know that?
>> >
>> > I should have added that Unix programs (i.e. Cygwin programs and
>> > even some native ports) probably use %HOME% which may be different
>> > from %HOMEDRIVE%%HOMEPATH%.  I recall that if you haven't
>> > explicitly set up HOME in Windows environment, Cygwin sets it up
>> > magically from passwd or falls back to %HOMEDRIVE%%HOMEPATH%.  I
>> > have no idea if msysgit respects %HOME% if it is set or always uses
>> > %HOMEDRIVE%%HOMEPATH% or something completely different (user
>> > profile, most likely).
>> >
>> > It certainly may be that "home directory" is a foreign concept to
>> > some Windows users.  Some might know it as a user profile or a
>> > personal folder (just guessing, I'm pretty isolated from less
>> > experienced Windows users), even though user profile is a separate
>> > concept from "home directory" (note that there is %USERPROFILE%
>> > which by default is the same as %HOMEDRIVE%%HOMEPATH% at least in
>> > XP).
>> >
>> > In any case, what Cygwin git does should be expected by Cygwin
>> > users.  If msysgit wanted to be a really native Windows application
>> > and store the configuration where Microsoft thinks it should be
>> > stored, it probably shouldn't store the config under "home
>> > directory" to begin with (I'm guessing that's what it does) but
>> > under %USERPROFILE\Application Data\Git (...FILE\Local
>> > Settings\... in case non-roaming storage is wanted).  And in that
>> > case the manual might be misleading for msysgit users.  See
>> > e.g. <http://msdn.microsoft.com/en-us/library/ms995853.aspx>.
>>
>> Isn't that enough argument to stop assuming the user knows where is
>> the "home directory"?
>
> Why does it appear as if we always have to bend over for Windows?  That is
> really frustrating.
>
> In any case, the only thing the user would need to know the location of
> $HOME for is for .gitconfig.  And for Windows users I suggest using the
> dialog in git gui (for the variables that are editable there), which
> should cover most of what the user needs.  For everything else, they
> should use "git config".
>
> Because if you really start with explaining where the home can be on
> Windows, you would also have to cover why "%USERPROFILE%" does not work in
> Git bash.  And before you know what is happening, you have a big ass
> Windows chapter in the user manual that revolves around anything except
> Git.

Huh? That was exactly my point.

It's much easier for everyone to just use git config --global than
explain how create and edit the .gitconfig file. If this is explained
it shouldn't be in the "Telling git your name" section.

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Junio C Hamano]

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

> It's much easier for everyone to just use git config --global than
> explain how create and edit the .gitconfig file. If this is explained
> it shouldn't be in the "Telling git your name" section.

I think it is Ok to have, and it probably is helpful to have, a document
that accompanies the generic manual, "Platform supplement", to explain
things like "On this platform, what is referred to as $HOME in the generic
manual is implemented as %HOMEDRIVE%%HOMEPATH%", to cover peculiarities of
each platform.

But I think it is going backwards to butcher the description in the main
manual in order to make the platform supplement shorter.  Even Windows is
not a good enough reason to break the logical ordering of how things
should be best taught to the readers of the manual, which is not specific
to a platform.

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Felipe Contreras]

On Sun, Jan 25, 2009 at 10:34 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> It's much easier for everyone to just use git config --global than
>> explain how create and edit the .gitconfig file. If this is explained
>> it shouldn't be in the "Telling git your name" section.
>
> I think it is Ok to have, and it probably is helpful to have, a document
> that accompanies the generic manual, "Platform supplement", to explain
> things like "On this platform, what is referred to as $HOME in the generic
> manual is implemented as %HOMEDRIVE%%HOMEPATH%", to cover peculiarities of
> each platform.
>
> But I think it is going backwards to butcher the description in the main
> manual in order to make the platform supplement shorter.  Even Windows is
> not a good enough reason to break the logical ordering of how things
> should be best taught to the readers of the manual, which is not specific
> to a platform.

That's why I think there should be a whole section regarding git
configuration before "Telling git your name".

However, my last proposal was to have both the git config --global
*and* the $HOME/.gitconfig description. Is there any argument against
that?

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Jeff King]

On Sun, Jan 25, 2009 at 11:12:57PM +0200, Felipe Contreras wrote:

> However, my last proposal was to have both the git config --global
> *and* the $HOME/.gitconfig description. Is there any argument against
> that?

This is like the fifth time you have asked, and for some reason, nobody
seems to have said yes or no. So I will go ahead and say: yes, I think
that is a fine idea.

I think there should also be some explanatory text that indicates they
are totally interchangeable for the rest of the document. Something
like: "When we show configuration in the rest of this document, we will
use format X [I think probably "git config $VAR $VALUE"]. But you can
use whichever method you are most comfortable with."

-Peff

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Wincent Colaiuta]

El 25/1/2009, a las 22:44, Jeff King escribió:

> On Sun, Jan 25, 2009 at 11:12:57PM +0200, Felipe Contreras wrote:
>
>> However, my last proposal was to have both the git config --global
>> *and* the $HOME/.gitconfig description. Is there any argument against
>> that?
>
> This is like the fifth time you have asked, and for some reason,  
> nobody
> seems to have said yes or no. So I will go ahead and say: yes, I think
> that is a fine idea.
>
> I think there should also be some explanatory text that indicates they
> are totally interchangeable for the rest of the document. Something
> like: "When we show configuration in the rest of this document, we  
> will
> use format X [I think probably "git config $VAR $VALUE"]. But you can
> use whichever method you are most comfortable with."

I already suggested something similar about 4 days ago:

http://article.gmane.org/gmane.comp.version-control.git/106673/

Cheers,
Wincent

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Jeff King]

On Sun, Jan 25, 2009 at 11:55:24PM +0100, Wincent Colaiuta wrote:

>> I think there should also be some explanatory text that indicates they
>> are totally interchangeable for the rest of the document. Something
>> like: "When we show configuration in the rest of this document, we will
>> use format X [I think probably "git config $VAR $VALUE"]. But you can
>> use whichever method you are most comfortable with."
>
> I already suggested something similar about 4 days ago:
>
> http://article.gmane.org/gmane.comp.version-control.git/106673/

Oh, I think I must have mixed up reading your post and thinking it was
from Felipe. Sorry.

At any rate, I think what you wrote there is sensible.

-Peff

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Kyle Moffett]

On Thu, Jan 22, 2009 at 1:59 PM, Hannu Koivisto <azure@iki.fi> wrote:
> In any case, what Cygwin git does should be expected by Cygwin
> users.  If msysgit wanted to be a really native Windows application
> and store the configuration where Microsoft thinks it should be
> stored, it probably shouldn't store the config under "home
> directory" to begin with (I'm guessing that's what it does) but
> under %USERPROFILE\Application Data\Git (...FILE\Local
> Settings\... in case non-roaming storage is wanted).  And in that
> case the manual might be misleading for msysgit users.  See
> e.g. <http://msdn.microsoft.com/en-us/library/ms995853.aspx>.

Actually, if msysgit really wanted to be a "native" windows program,
it would use the good-old brain-damaged method of storing
everything-and-the-kitchen-sink in the registry, including the
locations and reflogs for every repository you have ever examined.
Admittedly the collection of 150+ dotfiles in my Linux homedir looks
relatively similar to parts of the windows registry at times...

Cheers,
Kyle Moffett

Re: [PATCH 1/2] user-manual: Simplify the user configuration.

[Johannes Schindelin]

Hi,

On Sun, 25 Jan 2009, Kyle Moffett wrote:

> Actually, if msysgit really wanted to be a "native" windows program,

... it would

- not use MSys, but MSVC++,

- have a backing by a startup company,

- not use any of Git's source code at all, but reimplement everything in 
  closed source,

- come with a shrink wrapped box and a huge manual,

- do a lot of BS advertisement,

- offer overprized courses for management, in fancy locations,

- would cost around 50 dollars for a single license,

- would cost around 1500 dollars for a site-wide license with free 
  upgrades for 3 years and 2 free training courses,

- be dog slow, eating resources like mad, and

- crash frequently.

Other questions?

Ciao,
Dscho