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

[Michael J Gruber <git@drmicha.warpmail.net>]

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.

> +
> +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.

> +
> +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`:

> +------------------------------------------------
> +[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.

> +
> +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].

>  [[repositories-and-branches]]
>  Repositories and Branches

Cheers,
Michael