Re: [PATCH 6/7] user-manual: add global config section

On Sat, May 2, 2009 at 1:08 AM, Junio C Hamano [off-list ref] wrote:

Felipe Contreras [off-list ref] writes:

quoted

quoted

For that "introductory" purpose, however, I'd suggest showing how they
appear in the actual .git/config file first in the editor and then show a
way to use the "git config" command as an alternative.

I disagree. Opening ~/.gitconfig will just open an empty file for the
new users, afterwards they'll just scratch their heads wondering, now
what?

Why on earth would anybody start introducing ~/.gitconfig before talking
about .git/config?

In most people's minds 'configuring git' means a global configuration.
The first configuration most people do is to configure their e-mail,
doing it for only one repository is not useful at all.

A good sequence would be:

       To start working on a tarball extract (or your uncontrolled
       project) with git, first do:

       $ git init

       Whoa.  That was fast.  Did it do anything?  Yes, it created a
       subdirectory .git that is going to store your history and other
       control information.  Right now you do not have any history (nor
       the current state for that matter) recorded in it, but it already
       has some control information.  One of the more important one is
       the per-repository configuration file.  Take a look:

Most people don't start with 'git init' they start with 'git clone'

       $ git config --edit

       It would show something like:

       [core]
               ...

       ... explain a bit on how simple the configuration syntax is ...

       While you have it open, it would be a good idea to add this to
       introduce yourself to git:

       [user]
               email = clueful@git.us.er
               name = My Self

       If you work in multiple projects under the same identity, you
       do not have to add user.email and user.name to each and every
       repository this way.  Instead, you can do that to your per-user
       configuration file, like:

       $ git config --global --edit

       but if you work in different projects using different mail address
       (e.g. work vs hobby projects), you would want to have this
       information per-repository.

All that is already explained in detail, if people want a short-cut
this fits better:

Before making any commits, configure your user:
$ git config --global user.name "Simisani Takobana"
$ git config --global user.email simisani@gmail.com

This is what most guides use:

gnome:
http://live.gnome.org/Git/Developers

sourceforge:
http://apps.sourceforge.net/trac/sourceforge/wiki/Git

github:
http://github.com/guides/tell-git-your-user-name-and-email-address/6

sourcemage:
http://www.sourcemage.org/Git_Guide

archlinux:
http://wiki.archlinux.org/index.php/Super_Quick_Git_Guide

amarok:
http://amarok.kde.org/wiki/Development/Git

I could continue.

The reason why they use 'git config --global' is because introductions
must be quick so that the user can do something useful as fast as
possible. Many people are not patient enough and even when the guide
is simple and fast people still send patches with wrongly configured
email addresses.

This is a more usual (and pleasant) introduction to git:

$ git config --global user.name "Foo Bar"
$ git config --global user.email foo.bar@gmail.com
$ git clone git://git.gnome.org/foo

make changes

$ git commit -a
$ git format-patch origin/master

There, the user has achieved something useful. Hopefully at that point
the user will say:

Hey, that was easy, I wonder why people complain about git not being
user-friendly. Let's read a bit more about what I just did.

-- 
Felipe Contreras