patchdocs: .gitignore in parents is current repo only

>   * 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
> +   as the path, or in any parent directory in the same repository, 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
>     files generated as part of the project build.

>    * 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
> +   as the path, or in any parent directory in the same repository, 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

> On 2 Jul 2021, at 20:06, Junio C Hamano wrote:
>
>> I would have thought that "up to the toplevel of the work
>> tree" would be sufficiently clear where the upward traversal of the
>> directories ends, i.e. at the repository boundary.
>
> Seems reasonable. What if we move that note to come after "any parent
> directory"?

> "Andrew Berry" <andrew@furrypaws.ca> writes:
>
> Meaning something like the following?
>
> I do agree that it makes it a lot clearer.
>
>  Documentation/gitignore.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git c/Documentation/gitignore.txt w/Documentation/gitignore.txt
> index 53e7d5c914..58c2e41bbe 100644
> --- c/Documentation/gitignore.txt
> +++ w/Documentation/gitignore.txt
> @@ -27,8 +27,8 @@ 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
> +   as the path, or in any parent directory (up to the toplevel 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

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

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

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

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

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

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

> 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 | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index 53e7d5c914..534cda5747 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -27,10 +27,10 @@ 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
> +   as the path, or in any parent directory in the same repository, 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
>     files generated as part of the project build.