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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 1, 2009, 22:51 UTC
Message-ID: <94a0d4530905011551r635a4ebfrba86707419e13cc4@mail.gmail.com>
In-Reply-To: <7v3abowk6v.fsf@gitster.siamese.dyndns.org>

On Sat, May 2, 2009 at 1:08 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 12 quoted lines

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

Show 13 quoted lines

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

Show 26 quoted lines

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