[PATCH] doc/gitattributes: mention non-recursive behavior
On Tue, Mar 20, 2018 at 12:04:11AM -0400, Jeff King wrote: > > I guess my takeaway is that it would be _good_ if the gitattributes > > documentation contained the caveat about not matching directories > > recursively, but _great_ if gitattributes and gitignore (and whatever > > else there is) were consistent. > > I agree it would be nice if they were consistent (and pathspecs, too). > But unfortunately at this point there's a maze of backwards > compatibility to deal with. So let's not forget to do the easy half there. Here's a patch. -- >8 -- Subject: [PATCH] doc/gitattributes: mention non-recursive behavior The gitattributes documentation claims that the pattern rules are largely the same as for gitignore. However, the rules for recursion are different. In an ideal world, we would make them the same (if for nothing else than consistency and simplicity), but that would create backwards compatibility issues. For some discussion, see this thread: https://public-inbox.org/git/slrnkldd3g.1l4@majutsushi.net/ But let's at least document the differences instead of actively misleading the user by claiming that they're the same. Signed-off-by: Jeff King --- Documentation/gitattributes.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index d52b254a22..1094fe2b5b 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -56,9 +56,16 @@ Unspecified:: When more than one pattern matches the path, a later line overrides an earlier line. This overriding is done per -attribute. The rules how the pattern matches paths are the -same as in `.gitignore` files; see linkgit:gitignore[5]. -Unlike `.gitignore`, negative patterns are forbidden. +attribute. + +The rules by which the pattern matches paths are the same as in +`.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: + + - negative patterns are forbidden + + - patterns that match a directory do not recursively match paths +inside that directory (so using the trailing-slash `path/` syntax is +pointless in an attributes file; use `path/**` instead) When deciding what attributes are assigned to a path, Git consults `$GIT_DIR/info/attributes` file (which has the highest -- 2.17.0.rc0.402.ged0b3fd1ee
Re: [PATCH] doc/gitattributes: mention non-recursive behavior
That's perfect, thank you so much! On Tue, Mar 20, 2018 at 12:14 AM, Jeff King wrote: > On Tue, Mar 20, 2018 at 12:04:11AM -0400, Jeff King wrote: > >> > I guess my takeaway is that it would be _good_ if the gitattributes >> > documentation contained the caveat about not matching directories >> > recursively, but _great_ if gitattributes and gitignore (and whatever >> > else there is) were consistent. >> >> I agree it would be nice if they were consistent (and pathspecs, too). >> But unfortunately at this point there's a maze of backwards >> compatibility to deal with. > > So let's not forget to do the easy half there. Here's a patch. > > -- >8 -- > Subject: [PATCH] doc/gitattributes: mention non-recursive behavior > > The gitattributes documentation claims that the pattern > rules are largely the same as for gitignore. However, the > rules for recursion are different. > > In an ideal world, we would make them the same (if for > nothing else than consistency and simplicity), but that > would create backwards compatibility issues. For some > discussion, see this thread: > > https://public-inbox.org/git/slrnkldd3g.1l4@majutsushi.net/ > > But let's at least document the differences instead of > actively misleading the user by claiming that they're the > same. > > Signed-off-by: Jeff King > --- > Documentation/gitattributes.txt | 13 ++--- > 1 file changed, 10 insertions(+), 3 deletions(-) > > diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt > index d52b254a22..1094fe2b5b 100644 > --- a/Documentation/gitattributes.txt > +++ b/Documentation/gitattributes.txt > @@ -56,9 +56,16 @@ Unspecified:: > > When more than one pattern matches the path, a later line > overrides an earlier line. This overriding is done per > -attribute. The rules how the pattern matches paths are the > -same as in `.gitignore` files; see linkgit:gitignore[5]. > -Unlike `.gitignore`, negative patterns are forbidden. > +attribute. > + > +The rules by which the pattern matches paths are the same as in > +`.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: > + > + - negative patterns are forbidden > + > + - patterns that match a directory do not recursively match paths > +inside that directory (so using the trailing-slash `path/` syntax is > +pointless in an attributes file; use `path/**` instead) > > When deciding what attributes are assigned to a path, Git > consults `$GIT_DIR/info/attributes` file (which has the highest > -- > 2.17.0.rc0.402.ged0b3fd1ee >
Re: [PATCH] doc/gitattributes: mention non-recursive behavior
On Tue, Mar 20, 2018 at 5:14 AM, Jeff King wrote: > On Tue, Mar 20, 2018 at 12:04:11AM -0400, Jeff King wrote: > >> > I guess my takeaway is that it would be _good_ if the gitattributes >> > documentation contained the caveat about not matching directories >> > recursively, but _great_ if gitattributes and gitignore (and whatever >> > else there is) were consistent. >> >> I agree it would be nice if they were consistent (and pathspecs, too). >> But unfortunately at this point there's a maze of backwards >> compatibility to deal with. > > So let's not forget to do the easy half there. Here's a patch. > > -- >8 -- > Subject: [PATCH] doc/gitattributes: mention non-recursive behavior > > The gitattributes documentation claims that the pattern > rules are largely the same as for gitignore. However, the > rules for recursion are different. > > In an ideal world, we would make them the same (if for > nothing else than consistency and simplicity), but that > would create backwards compatibility issues. For some > discussion, see this thread: > > https://public-inbox.org/git/slrnkldd3g.1l4@majutsushi.net/ > > But let's at least document the differences instead of > actively misleading the user by claiming that they're the > same. > > Signed-off-by: Jeff King > --- > Documentation/gitattributes.txt | 13 ++--- > 1 file changed, 10 insertions(+), 3 deletions(-) > > diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt > index d52b254a22..1094fe2b5b 100644 > --- a/Documentation/gitattributes.txt > +++ b/Documentation/gitattributes.txt > @@ -56,9 +56,16 @@ Unspecified:: > > When more than one pattern matches the path, a later line > overrides an earlier line. This overriding is done per > -attribute. The rules how the pattern matches paths are the > -same as in `.gitignore` files; see linkgit:gitignore[5]. > -Unlike `.gitignore`, negative patterns are forbidden. > +attribute. > + > +The rules by which the pattern matches paths are the same as in > +`.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: > + > + - negative patterns are forbidden After 8b1bd02415 (Make !pattern in .gitattributes non-fatal - 2013-03-01) maybe we could use the verb "ignored" too instead of "forbidden" > + > + - patterns that match a directory do not recursively match paths > +inside that directory (so using the trailing-slash `path/` syntax is Technically gitignore does not match paths inside either. It simply ignores the whole dir and not traverse in (which is more of an optimization than anything). That is coincidentally perceived as recursively ignoring. Anyway yes it's good to spell out the differences here for gitattributes. > +pointless in an attributes file; use `path/**` instead) We probably could do this internally too (converting "path/" to "path/**") but we need to deal with corner cases (e.g. "path" without the trailing slash, but is a directory). So yes, suggesting the user to do it instead may be easier. > > When deciding what attributes are assigned to a path, Git > consults `$GIT_DIR/info/attributes` file (which has the highest > -- > 2.17.0.rc0.402.ged0b3fd1ee > -- Duy
Re: [PATCH] doc/gitattributes: mention non-recursive behavior
On Tue, Mar 20, 2018 at 05:41:52PM +0100, Duy Nguyen wrote: > > +The rules by which the pattern matches paths are the same as in > > +`.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: > > + > > + - negative patterns are forbidden > > After 8b1bd02415 (Make !pattern in .gitattributes non-fatal - > 2013-03-01) maybe we could use the verb "ignored" too instead of > "forbidden" Makes sense. The original is already in 'next', so do you want to send an incremental patch? > > +pointless in an attributes file; use `path/**` instead) > > We probably could do this internally too (converting "path/" to > "path/**") but we need to deal with corner cases (e.g. "path" without > the trailing slash, but is a directory). So yes, suggesting the user > to do it instead may be easier. Yeah, I almost suggested that, but I worried about those corner cases. It seems like documenting the current behavior is the right first step in any case. One other maybe-difference I came across coincidentally today: you have to quote the pattern in .gitattributes if it contains spaces, but not in .gitignore. But that's more an artifact of the rest of the file syntax than the pattern syntax (.gitignore has no other fields to confuse it with). -Peff
Re: [PATCH] doc/gitattributes: mention non-recursive behavior
On Wed, Mar 21, 2018 at 7:50 AM, Jeff King wrote: > On Tue, Mar 20, 2018 at 05:41:52PM +0100, Duy Nguyen wrote: > >> > +The rules by which the pattern matches paths are the same as in >> > +`.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: >> > + >> > + - negative patterns are forbidden >> >> After 8b1bd02415 (Make !pattern in .gitattributes non-fatal - >> 2013-03-01) maybe we could use the verb "ignored" too instead of >> "forbidden" > > Makes sense. The original is already in 'next', so do you want to send > an incremental patch? It's up to you. After all it's you who's doing all the work :) >> > +pointless in an attributes file; use `path/**` instead) >> >> We probably could do this internally too (converting "path/" to >> "path/**") but we need to deal with corner cases (e.g. "path" without >> the trailing slash, but is a directory). So yes, suggesting the user >> to do it instead may be easier. > > Yeah, I almost suggested that, but I worried about those corner cases. > It seems like documenting the current behavior is the right first step > in any case. Agreed. > One other maybe-difference I came across coincidentally today: you have > to quote the pattern in .gitattributes if it contains spaces, but not in > .gitignore. But that's more an artifact of the rest of the file syntax > than the pattern syntax (.gitignore has no other fields to confuse it > with). Yeah I forgot about that (and I was the one who started it). The document was updated in 860a74d9d9 (attr: support quoting pathname patterns in C style - 2017-01-27) though. -- Duy
Re: [PATCH] doc/gitattributes: mention non-recursive behavior
On Wed, Mar 21, 2018 at 05:16:16PM +0100, Duy Nguyen wrote: > >> After 8b1bd02415 (Make !pattern in .gitattributes non-fatal - > >> 2013-03-01) maybe we could use the verb "ignored" too instead of > >> "forbidden" > > > > Makes sense. The original is already in 'next', so do you want to send > > an incremental patch? > > It's up to you. After all it's you who's doing all the work :) I was trying to trick you into doing it. ;) As I tried to write up the commit message, though, I had second thoughts. It's true that they are ignored in the current code. But I do not think they are something we want to encourage, and certainly we do not want to promise that the "ignored" behavior will last forever. So I think it is actually best to declare them forbidden, and we just happen to treat it as a non-fatal error in the current code. > > One other maybe-difference I came across coincidentally today: you have > > to quote the pattern in .gitattributes if it contains spaces, but not in > > .gitignore. But that's more an artifact of the rest of the file syntax > > than the pattern syntax (.gitignore has no other fields to confuse it > > with). > > Yeah I forgot about that (and I was the one who started it). The > document was updated in 860a74d9d9 (attr: support quoting pathname > patterns in C style - 2017-01-27) though. OK. I was considering adding a special note to the list of differences, but I think the existing text is probably fine. -Peff