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

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

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.

On Friday 11 May 2007, J. Bruce Fields wrote:

On Thu, May 10, 2007 at 11:53:31PM +0200, Johan Herland wrote:

quoted

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, [off-list ref]
www.herland.net

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:

quoted

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

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.

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

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:

quoted

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.

quoted

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 [off-list ref]