[PATCH] Documentation: clarify .gitattributes search

[PATCH] Documentation: clarify .gitattributes search

[Jason Merrill]

[-- Attachment #1: Type: text/plain, Size: 1 bytes --]



[-- Attachment #2: 0001-Documentation-clarify-.gitattributes-search.patch --]
[-- Type: text/x-patch, Size: 1432 bytes --]

>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


Signed-off-by: Jason Merrill <jason@redhat.com>
---
As discussed on IRC today; I was wondering if my home directory qualified
as a parent directory, but apparently not.

 Documentation/gitattributes.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 55668e3..0338385 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 within the git repository
+(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
-- 
1.6.2.2

Re: [PATCH] Documentation: clarify .gitattributes search

[Junio C Hamano]

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.

[PATCH v2] Documentation: clarify .gitattributes search

[Jason Merrill]

[-- Attachment #1: Type: text/plain, Size: 1543 bytes --]

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.



[-- Attachment #2: 0001-Documentation-clarify-.gitattributes-search.patch --]
[-- Type: text/x-patch, Size: 2139 bytes --]

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

Re: [PATCH v2] Documentation: clarify .gitattributes search

[Jeff King]

On Mon, Apr 06, 2009 at 11:03:36AM -0400, Jason Merrill wrote:

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

I don't think per-user attribute patterns are an unreasonable thing to
want, but I think traversing above the git worktree root is not a good
way to implement it. Specifically:

  1. It's inefficient. If your repo is only two directories deep, we now
     might look at 2 gitattributes files. But if you put your repo in
     /some/long/path/in/your/filesystem, we now have to check _each_ of
     those, even though they are very unlikely to contain gitattributes
     files.

  2. It doesn't cover the per-user case very well. Repositories in your
     home directory and repositories in (for example) /tmp would need
     two separate gitattributes files.

Specifically checking $HOME/.gitattributes does make some sense to me
(though perhaps it is worth giving it a different basename in case your
home directory actually is a git repository).

The argument against it would be that it is up to the repo to define the
_types_ of its files, and for the user to define what to do with those
types. But if you have many repos, I could certainly see it being
convenient to globally say "for lack of better information, assume *.foo
files are type foo".

And there is already some precedent, as you note, in core.excludesfile.

-Peff