Re: [RFC/PATCH 7/8] user-manual: add global config section

["J. Bruce Fields" <bfields@fieldses.org>]

On Wed, Mar 25, 2009 at 12:17:12AM +0200, Felipe Contreras wrote:
> On Tue, Mar 24, 2009 at 11:52 PM, J. Bruce Fields <bfields@fieldses.org> wrote:
> > On Sun, Mar 22, 2009 at 08:05:20PM +0200, Felipe Contreras wrote:
> >> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> >> ---
> >>  Documentation/user-manual.txt |   34 ++++++++++++++++++++++++++++++++++
> >>  1 files changed, 34 insertions(+), 0 deletions(-)
> >>
> >> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> >> index 3278aa7..b7678aa 100644
> >> --- a/Documentation/user-manual.txt
> >> +++ b/Documentation/user-manual.txt
> >> @@ -40,6 +40,40 @@ without any explanation.
> >>  Finally, see <<todo>> for ways that you can help make this manual more
> >>  complete.
> >>
> >> +[[getting-started]]
> >> +Getting started
> >> +=============
> >> +
> >> +You can skip this section safely, however, configuring git at an early stage
> >> +would probably make your overall experience with it more pleasant. Also many
> >> +parts on this manual would be easier to grasp.
> >
> > I'd skip this first paragraph.
> 
> Ok. I was regretting it even as I was writing it :p
> 
> >> +
> >> +Git's configuration is distributed on different locations: 'system', 'global', and
> >> +'repository'. Variables are stored in the form of 'foo.bar', and the precedence
> >> +order is 'repository' > 'global' > 'system'.
> >
> > "distributed on" isn't right ("among" instead of "on" might work).  It's
> > not obvious to me what ">" means in terms of precedence.  And I'm not
> > sure the comment about the form conveys any useful information.  Also, I
> > think the systemwide configuration is less important, and could be left
> > to the man page.
> 
> Ok. That would make it easier.
> 
> How about:
> Git's configuration is distributed among different locations--on this
> manual we are only going to deal with 'global' and 'repository', where
> 'repository' variables take precedence over 'global' ones.

Sounds OK, but "on this" should be "in this", or even simpler just:
"this manual will only deal with...".  And then 'global' and
'repository' aren't really nouns on their own (what are they
modifying?).  So maybe: "deal with 'global' and 'repository' variables"?

> 
> >> +
> >> +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' (for the user) configuration.
> >> +
> >> +You can take a look and manually modify the configuration with the `--edit`
> >
> > "take a look and" isn't really necessary; either eliminate it or replace
> > it by "view and" or just "also".
> 
> I like "View and".

OK.  Thanks!--b.