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

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