Re: [PATCH] Documentation: clarify .gitattributes search

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

Jason Merrill <jason@redhat.com> writes:

> From 04b504dc0c174d697cc1b75829fe2f7473f193ce Mon Sep 17 00:00:00 2001
> From: Jason Merrill <jason@redhat.com>
> Date: Sun, 5 Apr 2009 21:54:37 -0400
> Subject: [PATCH] Documentation: clarify .gitattributes search

You do not want these four lines in the body of the message.

>  When deciding what attributes are assigned to a path, git
>  consults `$GIT_DIR/info/attributes` file (which has the highest
>  precedence), `.gitattributes` file in the same directory as the
> -path in question, and its parent directories (the further the
> -directory that contains `.gitattributes` is from the path in
> -question, the lower its precedence).
> +path in question, and its parent directories within the git repository
> +(the further the directory that contains `.gitattributes` is from the
> +path in question, the lower its precedence).

I initially:

 (1) thought this was in "it goes without saying" category (but I am at
     fault here---losing git virginity long time ago);

 (2) also wondered why you were confused to think if your home directory
     (for that matter, any higher directory, like /.gitattributes at the
     filesystem root level) that is clearly outside of the project could
     possibly affect what happens inside a project; and

 (3) was puzzled why you do not have any patch to description of ignore
     files (perhaps you do not even a similar confusion on them).

The last point was interesting, because the documentation of gitignore
uses this language:

 * Patterns read from a `.gitignore` file in the same directory
   as the path, or in any parent directory, with patterns in the
   higher level files (up to the root) being overridden by those in
   lower level files down to the directory containing the file.
   These patterns match relative to the location of the
   `.gitignore` file.

So "up to the root" might help.  It might not.

A few questions.

 (1) To a long-time git person, "up to the root" is obviously talking
     about the toplevel of the work tree, not "root of the filesystem",
     but is it clear to _you_ (or do you think it would be clear to
     somebody else without much previous exposure to git)?

 (2) If not, I think we should come up with a good wording and use that in
     both.  How does the "toplevel of the work tree" sound for that
     purpose?

I would want to avoid the word "directories within the git repository",
because people would misinterpret that to mean directories like .git/refs
and .git/objects/info, which is clearly not what you meant here.