patchDocumentation: clarify .gitattributes search

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

Jason Merrill <jason@redhat.com> writes:

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

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.

Junio C Hamano wrote:

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

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

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

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

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