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

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Oct 12, 2009, 12:25 UTC
Message-ID: <4AD32024.6020005@drmicha.warpmail.net>
In-Reply-To: <1255293786-17293-2-git-send-email-felipe.contreras@gmail.com>

Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:

Show 24 quoted lines

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

Show 9 quoted lines

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

Show 6 quoted lines

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