[PATCH v2] Documentation: clarify .gitattributes search

From: Jason Merrill <jason@redhat.com>
Date: Apr 6, 2009, 15:03 UTC
Message-ID: <49DA19C8.5010308@redhat.com>
In-Reply-To: <7viqlicp1y.fsf@gitster.siamese.dyndns.org>

Junio C Hamano wrote:

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

Because it would be useful if it did; specifically, it would be convenient to be able to say that ChangeLog files use git-merge-changelog wherever they appear, and not have to repeat that in all my projects. I didn't really expect it, but thought that maybe it was designed to work that way.

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

I hadn't really thought about them, but looking at the documentation now I see that ignore files have the core.excludesfile config variable to provide global ignores; there doesn't seem to be anything analogous for attributes.

>  (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)?

It seems clear enough, as it would be pointless to say it if it meant the root of the filesystem.

>  (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?

Sure, I'll use that.

Use the term "toplevel of the work tree" in gitattributes.txt and gitignore.txt to define the limits of the search for those files.

Signed-off-by: Jason Merrill <jason@redhat.com>
---
 Documentation/gitattributes.txt |    6 +++---
 Documentation/gitignore.txt     |    4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 55668e3..b762bba 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -60,9 +60,9 @@ same as in `.gitignore` files; see linkgit:gitignore[5].
 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 up to the toplevel of the
+work tree (the further the directory that contains `.gitattributes`
+is from the path in question, the lower its precedence).
 
 If you wish to affect only a single repository (i.e., to assign
 attributes to files that are particular to one user's workflow), then
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 59321a2..7df3cef 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -31,8 +31,8 @@ precedence, the last matching pattern decides the outcome):
 
  * 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.
+   higher level files (up to the toplevel of the work tree) 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.  A project normally includes such
    `.gitignore` files in its repository, containing patterns for

-- 
1.6.2.2