patchuser-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 <johan@herland.net>
---
 Documentation/user-manual.txt |    7 ++-----
 1 files changed, 2 insertions(+), 5 deletions(-)

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

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:

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

On Fri, May 11, 2007 at 12:02:53AM CEST, J. Bruce Fields 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, 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. :-)

On Fri, May 11, 2007 at 01:00:45AM +0200, Petr Baudis wrote:

Sure.

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.

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.

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

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.

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

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:

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.

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.

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.