threads / patch / 17287

patch, 2 partsuser-manual: Simplify the user configuration.

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

## tl;dr

25 messages between Jan 21, 2009 and Jan 25, 2009. Diffs are folded; open one to read it.

replies: 24people: 8as markdown or json

Felipe Contreras· Jan 21, 2009, 18:09 UTC · lore

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(-)
Show changes to Documentation/user-manual.txt +3 −5
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
Felipe Contreras· Jan 21, 2009, 18:09 UTC · re: Felipe Contreras · lore

[PATCH 2/2] Fix typo.

"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(-)
Show changes to sha1_file.c +1 −1
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
Markus Heidelberg· Jan 21, 2009, 18:55 UTC · re: Felipe Contreras · lore

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

Felipe Contreras, 21.01.2009:
Show 15 quoted lines
> +++ 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
Felipe Contreras· Jan 21, 2009, 19:04 UTC · re: Markus Heidelberg · lore

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

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(-)
Show changes to Documentation/user-manual.txt +3 −5
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
Jeff King· Jan 21, 2009, 19:18 UTC · re: Felipe Contreras · lore

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

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
Felipe Contreras· Jan 21, 2009, 19:39 UTC · re: Jeff King · lore

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

On Wed, Jan 21, 2009 at 9:18 PM, Jeff King <peff@peff.net> wrote:
Show 15 quoted lines
> 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
Jeff King· Jan 21, 2009, 19:51 UTC · re: Felipe Contreras · lore

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

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
Junio C Hamano· Jan 21, 2009, 20:54 UTC · re: Felipe Contreras · lore

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

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.

Wincent Colaiuta· Jan 21, 2009, 21:13 UTC · re: Junio C Hamano · lore

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

El 21/1/2009, a las 21:54, Junio C Hamano escribió:
Show 16 quoted lines
> 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:
Show 15 quoted lines
> 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:
Show 14 quoted lines
> 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

Felipe Contreras· Jan 21, 2009, 21:19 UTC · re: Junio C Hamano · lore

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

On Wed, Jan 21, 2009 at 10:54 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 16 quoted lines
> 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
Hannu Koivisto· Jan 22, 2009, 16:17 UTC · re: Felipe Contreras · lore

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

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
Felipe Contreras· Jan 22, 2009, 16:57 UTC · re: Hannu Koivisto · lore

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

On Thu, Jan 22, 2009 at 6:17 PM, Hannu Koivisto <azure@iki.fi> wrote:
Show 6 quoted lines
> 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
Junio C Hamano· Jan 22, 2009, 17:14 UTC · re: Felipe Contreras · lore

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

Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 10 quoted lines
> 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.

Johannes Schindelin· Jan 22, 2009, 17:28 UTC · re: Junio C Hamano · lore

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

Hi,
On Thu, 22 Jan 2009, Junio C Hamano wrote:
Show 17 quoted lines
> 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

Hannu Koivisto· Jan 22, 2009, 18:59 UTC · re: Felipe Contreras · lore

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

Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 10 quoted lines
> 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
Felipe Contreras· Jan 24, 2009, 08:21 UTC · re: Hannu Koivisto · lore

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

On Thu, Jan 22, 2009 at 8:59 PM, Hannu Koivisto <azure@iki.fi> wrote:
Show 39 quoted lines
> 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
Johannes Schindelin· Jan 24, 2009, 13:42 UTC · re: Felipe Contreras · lore

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

Hi,
On Sat, 24 Jan 2009, Felipe Contreras wrote:
Show 43 quoted lines
> 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

Felipe Contreras· Jan 24, 2009, 14:04 UTC · re: Johannes Schindelin · lore

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

On Sat, Jan 24, 2009 at 3:42 PM, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

Show 62 quoted lines
> 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
Junio C Hamano· Jan 25, 2009, 20:34 UTC · re: Felipe Contreras · lore

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

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.

Felipe Contreras· Jan 25, 2009, 21:12 UTC · re: Junio C Hamano · lore

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

On Sun, Jan 25, 2009 at 10:34 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 17 quoted lines
> 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
Jeff King· Jan 25, 2009, 21:44 UTC · re: Felipe Contreras · lore

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

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
Wincent Colaiuta· Jan 25, 2009, 22:55 UTC · re: Jeff King · lore

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

El 25/1/2009, a las 22:44, Jeff King escribió:
Show 17 quoted lines
> 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

Jeff King· Jan 25, 2009, 23:20 UTC · re: Wincent Colaiuta · lore

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

On Sun, Jan 25, 2009 at 11:55:24PM +0100, Wincent Colaiuta wrote:
Show 9 quoted lines
>> 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
Kyle Moffett· Jan 25, 2009, 07:32 UTC · re: Hannu Koivisto · lore

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

On Thu, Jan 22, 2009 at 1:59 PM, Hannu Koivisto <azure@iki.fi> wrote:
Show 9 quoted lines
> 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

Johannes Schindelin· Jan 25, 2009, 12:06 UTC · re: Kyle Moffett · lore

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

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

← back to recent threads