Re: [PATCH 1/2] user-manual: add global config section

[Felipe Contreras <felipe.contreras@gmail.com>]

On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:
>> So that users get to know how to configure git from the get-to with good
>> practical example (color.ui = auto) that most people would probably like
>> anyway.
>>
>> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
>> ---
>>  Documentation/user-manual.txt |   27 +++++++++++++++++++++++++++
>>  1 files changed, 27 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index 67ebffa..ff2563a 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -40,6 +40,33 @@ without any explanation.
>>  Finally, see <<todo>> for ways that you can help make this manual more
>>  complete.
>>
>> +[[getting-started]]
>> +Getting started
>> +=============
>> +
>> +Git's configuration is distributed among different locations--this manual will
>> +only to deal with 'global' (for the user) and 'repository' variables, where
>> +'repository' variables take precedence over 'global' ones.
>
> Well, you do talk about "system" below, and that's about it. Also, the
> configuration is not really distributed among different locations. Most
> newbies interested in a *D*VCS will misunderstand this (as git having
> distributed configuration).
>
> Alternative:
>
> Git's default configuration can be changed on a system wide, global (per
> user) and local (per repository) level, in the order of increasing
> precedence.

When I read that it's not clear if the local level discards the global
level completely or it's aggregated. If we specify that it's only the
variables that take precedence it might be clearer:

Git's configuration is composed of variables that are stored in
multiple locations: 'system' (all users), 'global' (for the user), and
'repository' -- in decreasing order of precedence.

>> +
>> +You would probably want to start setting up something useful:
>> +------------------------------------------------
>> +$ git config --global color.ui auto
>> +------------------------------------------------
>> +
>> +This will make prettier the output of certain commands such as `git diff`, but
>> +that's not important; what is important here is that `color.ui` has been
>> +stored in the 'global' configuration.
>
> This will make certain commands such as `git diff` use colors in the
> output. What is important here is that the value `auto` for the option
> `color.ui` has been stored in the 'global' configuration. Use `--system`
> for the system wide configuration; specifying neither `--system` nor
> `--global` makes `git config` access the local configuration.

I think we should only mention (once) the system wide configuration,
but not cover it. That's for system administrators, not users.

>> +
>> +View and manually modify the configuration by opening `~/.gitconfig`:
>
> View and manually modify the global configuration by opening
> `~/.gitconfig` in your editor or using `git config --global --edit`:

I have separate patches for 'git config --edit', but Junio suggested
to hold them back because --edit is a relatively new option.

>> +------------------------------------------------
>> +[color]
>> +        ui = auto
>> +------------------------------------------------
>> +
>> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).
>
> I don't even think we should talk about locations here, "git config -e"
> should be the first user's way to do it.

I disagree. Most useful configurations (color.ui, user.email) should
be global. The complete newbie might think: cool, now I have my git
properly configured (with 'git config -e'), and then when cloning a
new repo (s)he would think: ok, git just forgot what I told him. When
that happens (s)he would have to re-learn and re-configure git.

When users think about configuration, it's usually a 'global'
configuration, so that's what we should teach from the beginning and
make sure they understand the difference between 'global' and
'repository' configurations.

>> +
>> +More git configurations will be covered in the rest of the manual, if you want
>> +to learn more look at linkgit:git-config[1] for details.
>
> "Configurations" is ambiguous, it can be easily (mis)understood as
> "types of configuration" (global, local etc.). Also, the above doesn't
> really cover even one option. How about:
>
> This manual covers many configuration options (such as `color.ui.`). For
> more details on the `git config` command as well as all configuration
> options see linkgit:git-config[1].

Looks better, except s/configuration options/configuration variables/

Cheers.

-- 
Felipe Contreras