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

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> This is very early in the manual, where every word counts.  I am not
> very good at wording and do not have any better suggestions, but would
> it be possible to more efficiently convey this:
>
> 	Git reads its per-user configuration from ~/.gitignore.
>
> 	That file can also be manipulated with the "git config"
> 	command, which can be convenient in scripts or when using
> 	operating systems like Windows where it is not clear where
> 	the home directory is.
>
> 	For example, if your terminal supports it, you can tell Git
> 	to use color in the output for commands such as "git diff"
> 	with "git config --global color.ui auto".
>
> 	For more information and a list of possible settings, see
> 	git-config(1).

The way how the above introduces the "git config" command to people who
see git for the first time makes sense.  Unfortunately, --global and
per-user do not "click" together when given in isolation, and I think it
would help if it is explained this way, using a setting that can validly
be either per-user or project specific:

    Various configuration variables affect how git operates.  Some are
    specific to the user (e.g. if you prefer to see the output in colour),
    while some are specific to a repository (e.g. what other repositories
    it interacts with).  Git reads from ~/.gitconfig file to learn your
    personal settings and .git/config file of the repository you are
    working in to learn the repository settings.

    These are plain text files that you can view or edit in your text
    editor, but they also can be manipulated with the "git config"
    command, which is convenient in scripts or ...

    For example, if you want to use a particular e-mail address only while
    working in the current repository, you would set "user.email" variable
    to that e-mail address in the repository configuration file (i.e.
    .git/config) with this command:

	git config user.email your@email.address.xz

    If on the other hand you want to use the same address for any project
    you work with, you can instead set this in your personal configuration
    file (i.e.  ~/.gitconfig) with this command:

	git config --global user.email your@email.address.xz

    For more information ...

Since this is an end-user material, I deliberately omitted talking about
the --system (i.e. /etc/gitconfig) in the above.