| Message ID | 20210706205712.75270-1-andrew@furrypaws.ca (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: .gitignore parsing is to the top of the repo | expand |
Andrew Berry <andrew@furrypaws.ca> writes: > * 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 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 > + as the path, or in any parent directory (up to the top-level of the work > + tree), with patterns in the higher level files 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 > files generated as part of the project build. Line rewrapping makes it hard to see what actually got changed, but does this only move "(up to the top-level of the work tree)" around without anything else, as discussed? If you do "toplevel" -> "top-level" while at it, perhaps we would want to correct "work tree" -> "working tree". Looking better. Thanks.
Junio C Hamano <gitster@pobox.com> writes: > Andrew Berry <andrew@furrypaws.ca> writes: > >> * 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 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 >> + as the path, or in any parent directory (up to the top-level of the work >> + tree), with patterns in the higher level files 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 >> files generated as part of the project build. > > Line rewrapping makes it hard to see what actually got changed, but > does this only move "(up to the top-level of the work tree)" around > without anything else, as discussed? > > If you do "toplevel" -> "top-level" while at it, perhaps we would > want to correct "work tree" -> "working tree". > > Looking better. Another tangent. The discovery process used for the .gitattributes files is identical to what is done to the .gitignore files; we may want to make sure that the explanation we give in our documentation won't cause the same confusion you are trying to avoid with this change. Such a fix does not have to be (and probably should not be) a part of this change, though. Thanks.
On 6 Jul 2021, at 20:18, Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: >> >> Line rewrapping makes it hard to see what actually got changed, To check, that's asked for, correct? Or is it better to do one commit with the word changes, another to clean up the wrapping? >> but >> does this only move "(up to the top-level of the work tree)" around >> without anything else, as discussed? >> >> If you do "toplevel" -> "top-level" while at it, perhaps we would >> want to correct "work tree" -> "working tree". >> >> Looking better. Yes, I realized I sent the wrong file when reviewing the sent email, hence the followup. Aside, it's not clear to me how to send patch emails that _also_ have not-to-be-committed notes like "oops, ignore the last". First time contributor problems! > Another tangent. The discovery process used for the .gitattributes > files is identical to what is done to the .gitignore files; we may > want to make sure that the explanation we give in our documentation > won't cause the same confusion you are trying to avoid with this > change. Such a fix does not have to be (and probably should not be) > a part of this change, though. I'm out of the office for the next week, but otherwise I'm glad to take that on when I'm back if no one else picks it up.
"Andrew Berry" <andrew@furrypaws.ca> writes: >>> Line rewrapping makes it hard to see what actually got changed, > > To check, that's asked for, correct? Or is it better to do one commit > with the word changes, another to clean up the wrapping? We do not encourage one-word-per-line or other silliness, but as long as the source is readable enough, there is no need for line re-wrapping, and I suspect that principle would apply. >> Another tangent. The discovery process used for the .gitattributes >> files is identical to what is done to the .gitignore files; we may >> want to make sure that the explanation we give in our documentation >> won't cause the same confusion you are trying to avoid with this >> change. Such a fix does not have to be (and probably should not be) >> a part of this change, though. > > I'm out of the office for the next week, but otherwise I'm glad to > take that on when I'm back if no one else picks it up. Here is how we describe the .gitattributes side: 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 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). Finally global and system-wide files are considered (they have the lowest precedence). I think we are already good on this side. Thanks.
On 6 Jul 2021, at 17:57, Junio C Hamano wrote: > If you do "toplevel" -> "top-level" while at it, perhaps we would > want to correct "work tree" -> "working tree". Rather than think of this as a one-off fix, I thought to look to see how many instances of each are currently used. toplevel: 246 top-level: 119 work tree: 538 working tree: 2610 Since many of these instances are in translated strings, and that the text is understandable with any of the variants, I don't think it's worth changing. "Our standard is no standard" etc. That leaves bringing the note about the work tree earlier in the sentence. Here's a hopefully easier to read word-diff. Look good? diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 53e7d5c914..b4c8b9c0de 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -27,12 +27,11 @@ precedence, the last matching pattern decides the outcome): them. * 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-]{+directory+} (up to the toplevel of the work [-tree)-]{+tree), with patterns in the higher level files+} 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 files generated as part of the project build. * Patterns read from `$GIT_DIR/info/exclude`.
"Andrew Berry" <andrew@furrypaws.ca> writes: > On 6 Jul 2021, at 17:57, Junio C Hamano wrote: > >> If you do "toplevel" -> "top-level" while at it, perhaps we would >> want to correct "work tree" -> "working tree". > > Rather than think of this as a one-off fix, I thought to look to see > how many instances of each are currently used. > > toplevel: 246 > top-level: 119 > work tree: 538 > working tree: 2610 > > Since many of these instances are in translated strings, and that the > text is understandable with any of the variants, I don't think it's > worth changing. "Our standard is no standard" etc. So using "working tree" and "toplevel" might be adjusting to majority, but I agree that there are so numerous that tweaking only one "toplevel" (or another "work tree") should not distract the main point of this patch. Thanks for stepping back and thinking it carefully. I wish everybody did more of that ;-) > That leaves bringing the note about the work tree earlier in the > sentence. Here's a hopefully easier to read word-diff. Look good? Sure, but the thing is that the version of the patch (with the change from toplevel to top-level) has already been in 'next' for more than a week. Thanks. > diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt > index 53e7d5c914..b4c8b9c0de 100644 > --- a/Documentation/gitignore.txt > +++ b/Documentation/gitignore.txt > @@ -27,12 +27,11 @@ precedence, the last matching pattern decides the > outcome): > them. > > * 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-]{+directory+} (up to the toplevel of the work > [-tree)-]{+tree), with patterns in the higher level files+} 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 > files generated as part of the project build. > > * Patterns read from `$GIT_DIR/info/exclude`.
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 53e7d5c914..af8f231cc1 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -27,12 +27,11 @@ precedence, the last matching pattern decides the outcome): them. * 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 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 + as the path, or in any parent directory (up to the top-level of the work + tree), with patterns in the higher level files 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 files generated as part of the project build. * Patterns read from `$GIT_DIR/info/exclude`.
The current documentation reads as if .gitignore files will be parsed in every parent directory, and not until they reach a repository boundary. This clarifies the current behaviour. As well, this corrects 'toplevel' to 'top-level', matching usage for 'top-level domain'. Signed-off-by: Andrew Berry <andrew@furrypaws.ca> --- Documentation/gitignore.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-)