[PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Johan Herland]

[-- Attachment #1: Type: text/plain, Size: 1016 bytes --]

Use git-config for setting global user.name and user.email rather than
telling the user to edit ~/.gitconfig directly. This brings 
user-manual.txt in line with tutorial.txt.

Signed-off-by: Johan Herland <johan@herland.net>
---
 Documentation/user-manual.txt |    7 ++-----
 1 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt 
b/Documentation/user-manual.txt
index 13db969..23e2f45 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -158,11 +158,8 @@ Making changes
 Make sure git knows who to blame:
 
 ------------------------------------------------
-$ cat >>~/.gitconfig <<\EOF
-[user]
-	name = Your Name Comes Here
-	email = you@yourdomain.example.com
-EOF
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email you@yourdomain.example.com
 ------------------------------------------------
 
 Select file contents to include in the next commit, then make the
-- 
1.5.0.7


[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[J. Bruce Fields]

On Thu, May 10, 2007 at 11:53:31PM +0200, Johan Herland wrote:
> Use git-config for setting global user.name and user.email rather than
> telling the user to edit ~/.gitconfig directly. This brings 
> user-manual.txt in line with tutorial.txt.

The inconsistency is intentional.  We want users to know about
git-config, because it's helpful when writing scripts, and because it
has a useful manpage.  But we also want them to know about the
config-file syntax, since most of us find reading and editing a file
more intuitive than running git-config.  So we use a mixture of both.

--b.

> Signed-off-by: Johan Herland <johan@herland.net>
> ---
>  Documentation/user-manual.txt |    7 ++-----
>  1 files changed, 2 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/user-manual.txt 
> b/Documentation/user-manual.txt
> index 13db969..23e2f45 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -158,11 +158,8 @@ Making changes
>  Make sure git knows who to blame:
>  
>  ------------------------------------------------
> -$ cat >>~/.gitconfig <<\EOF
> -[user]
> -	name = Your Name Comes Here
> -	email = you@yourdomain.example.com
> -EOF
> +$ git config --global user.name "Your Name Comes Here"
> +$ git config --global user.email you@yourdomain.example.com
>  ------------------------------------------------
>  
>  Select file contents to include in the next commit, then make the
> -- 
> 1.5.0.7
> 

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Junio C Hamano]

I think this was rejected before, and the reason was that the
point of this section is to make users aware that what novices
might think is internal is actually represented in a very simple
to understand and simple to change format, and reassure people
that making small mistakes can be fixed with an editor.

And I think that reasoning still stands.

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Johan Herland]

[-- Attachment #1: Type: text/plain, Size: 1131 bytes --]

On Friday 11 May 2007, J. Bruce Fields wrote:
> On Thu, May 10, 2007 at 11:53:31PM +0200, Johan Herland wrote:
> > Use git-config for setting global user.name and user.email rather than
> > telling the user to edit ~/.gitconfig directly. This brings
> > user-manual.txt in line with tutorial.txt.
>
> The inconsistency is intentional.  We want users to know about
> git-config, because it's helpful when writing scripts, and because it
> has a useful manpage.  But we also want them to know about the
> config-file syntax, since most of us find reading and editing a file
> more intuitive than running git-config.  So we use a mixture of both.

I see your point, but when I look at the user manual, the only place I can 
actually find git-config used is in [[remote-branch-configuration]]. 
Besides, we also present the config-file syntax for user.{name,email} in 
[[telling-git-your-name]], so it's not like I'm remove every reference to 
the layout of .gitconfig.

Maybe we can present both versions in [[making-changes]]?


Have fun!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Petr Baudis]

On Fri, May 11, 2007 at 12:02:53AM CEST, J. Bruce Fields wrote:
> On Thu, May 10, 2007 at 11:53:31PM +0200, Johan Herland wrote:
> > Use git-config for setting global user.name and user.email rather than
> > telling the user to edit ~/.gitconfig directly. This brings 
> > user-manual.txt in line with tutorial.txt.
> 
> The inconsistency is intentional.  We want users to know about
> git-config, because it's helpful when writing scripts, and because it
> has a useful manpage.  But we also want them to know about the
> config-file syntax, since most of us find reading and editing a file
> more intuitive than running git-config.  So we use a mixture of both.

However, in that case I think this is not the good point to show
~/.gitconfig. Your goal at that point should be to get the user able to
commit as simply as possible, and having to manually edit some config
file is unnecessary hassle when you can just use these two simple
commands; also, we use the same commands in tutorials, crash courses
etc. So I really think that consistency is better here. The more viable
strategy is to mention that git-config really just plays with simple
text files at some... later point. :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Ever try. Ever fail. No matter. // Try again. Fail again. Fail better.
		-- Samuel Beckett

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[J. Bruce Fields]

On Fri, May 11, 2007 at 01:00:45AM +0200, Petr Baudis wrote:
> However, in that case I think this is not the good point to show
> ~/.gitconfig. Your goal at that point should be to get the user able
> to commit as simply as possible,

Sure.

> and having to manually edit some config file is unnecessary hassle
> when you can just use these two simple commands;

I don't get it; why are the two commands "simple", and editing a file a
"hassle"?  In terms of, say, time required, or number of keystrokes, I
suspect the two are about the same.  And it seems to me that:

	- As users of a tool designed mainly to track changes to text
	  files, git users are likely to be pretty proficient at editing
	  text files.
	- People also need to be able to view the configuration and
	  change it.  If they make a typo on the first try, they may
	  need to do this sooner rather than later.  With a config file,
	  this is trivial.  With git-config, you have to learn at least
	  one new thing (how to query values).
	- The config file is easier to read than the git-config output.
	- You're going to have to edit some text anyway to plug your
	  name in, so we can't make this a pure cut-n-paste from the
	  docs.

> also, we use the same commands in tutorials, crash courses etc. So I
> really think that consistency is better here. The more viable strategy
> is to mention that git-config really just plays with simple text files
> at some...  later point. :-)

So while I'm not convinced of the value of consistency here, if we have
to have consistency, I'd rather standardize on config-file-editing.

--b.

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Junio C Hamano]

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

> So while I'm not convinced of the value of consistency here, if we have
> to have consistency, I'd rather standardize on config-file-editing.

I obviously agree with everything you said.

I do not think "consistency" should weigh too much in the
teaching and learning process, which is what a manual is about.
It is beneficial to make the readers aware, early in the
process, that there typically are more than one ways to do
things, one suitable for scripting and the other for interactive
use.  In the introductory part of the user-manual, I think it is
a very good idea to give a bit of glimpse of what is going on
under the hood, and config file is probably the easiest thing to
give that warm feeling of something they can understand is going
on to the readers.

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Nicolas Pitre]

On Thu, 10 May 2007, J. Bruce Fields wrote:

> So while I'm not convinced of the value of consistency here, if we have
> to have consistency, I'd rather standardize on config-file-editing.

Why not simply providing both?

	You can modify your config with the following commands:

	...

	Alternatively, you might edit your ~/.gitconfig directly as 
	well with the following content:

	...

Wouldn't that be clearer?  This way there is no confusion since it is 
clear up front that both methods are equivalent, and the user can choose 
between them.

For one, I prefer the git-config method even if I do edit source files 
all day long.  It just seems faster to me.


Nicolas

Re: [PATCH] user-manual: Use "git config --global" instead of editing ~/.gitconfig

[Jan Hudec]

[-- Attachment #1: Type: text/plain, Size: 2194 bytes --]

On Thu, May 10, 2007 at 23:46:53 -0400, J. Bruce Fields wrote:
> On Fri, May 11, 2007 at 01:00:45AM +0200, Petr Baudis wrote:
> > However, in that case I think this is not the good point to show
> > ~/.gitconfig. Your goal at that point should be to get the user able
> > to commit as simply as possible,
> 
> Sure.

I would vote for telling users both ways to do it on that spot.
Something along the lines:

    git-config --global user.email ...
    git-config --global user.name ...

    Alternatively, you can edit ~/.gitconfig and add the following:
    {{{
    [user]
    email = ...
    name = ...
    }}}

I don't like the current description with cat or echo or what it is though.
It requires more thinking than necessary and especially as the mingw port
progresses there will be more Windows users to whom this will be totaly
confusing.

> > and having to manually edit some config file is unnecessary hassle
> > when you can just use these two simple commands;
> 
> I don't get it; why are the two commands "simple", and editing a file a
> "hassle"?  In terms of, say, time required, or number of keystrokes, I
> suspect the two are about the same.  And it seems to me that:
> 
> 	- As users of a tool designed mainly to track changes to text
> 	  files, git users are likely to be pretty proficient at editing
> 	  text files.
> 	- People also need to be able to view the configuration and
> 	  change it.  If they make a typo on the first try, they may
> 	  need to do this sooner rather than later.  With a config file,
> 	  this is trivial.  With git-config, you have to learn at least
> 	  one new thing (how to query values).
> 	- The config file is easier to read than the git-config output.
> 	- You're going to have to edit some text anyway to plug your
> 	  name in, so we can't make this a pure cut-n-paste from the
> 	  docs.

Well, I would not say editing the difference is that big, but I do think it's
easier to call two commands. Maybe it's psychological "I have to write
something to get it working", even though it's actually less keystrokes than
calling the commands.

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]