[PATCH] docs: .gitignore in parents is current repo only

[PATCH] docs: .gitignore in parents is current repo only

[Andrew Berry]

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.

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

Re: [PATCH] docs: .gitignore in parents is current repo only

[Junio C Hamano]

Andrew Berry <andrew@furrypaws.ca> writes:

> The current documentation reads as if .gitignore files will be parsed in
> every parent directory, and not until they reach a repository boundary.

Hmph.  While it is not adding an incorrect information to the
documentation per-se, I am not sure if this is necessary to begin
with.  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.

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

Re: [PATCH] docs: .gitignore in parents is current repo only

[Bagas Sanjaya]

On 03/07/21 05.20, Andrew Berry wrote:
>    * 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

So for example I have `something/foo` in ../.gitignore, but .gitignore 
(in current directory `something`) has `foo`. Is .gitignore from current 
directory or ../.gitignore takes effect?

Also s/toplevel/top level/

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] docs: .gitignore in parents is current repo only

[Andrew Berry]

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"?

On 2 Jul 2021, at 20:21, Bagas Sanjaya wrote:

> So for example I have `something/foo` in ../.gitignore, but .gitignore 
> (in current directory `something`) has `foo`. Is .gitignore from 
> current directory or ../.gitignore takes effect?

In this case, both rules resolve to the same path, so I don't think it 
matters? But in practice I'd expect it to be `something/.gitignore`, 
since you can negate the pattern from the parent ignore file.

> Also s/toplevel/top level/

That showed up in the diff due to word wrapping. If no other changes are 
accepted, I'll file a followup after to get this fixed on it's own.

Re: [PATCH] docs: .gitignore in parents is current repo only

[Junio C Hamano]

"Andrew Berry" <andrew@furrypaws.ca> writes:

> 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"?

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

Re: [PATCH] docs: .gitignore in parents is current repo only

[Andrew Berry]

On 5 Jul 2021, at 15:59, Junio C Hamano wrote:

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

Yes, that's good. My only suggestion would mirror the earlier one, to 
split toplevel to "top-level" or "top level".

Re: [PATCH] docs: .gitignore in parents is current repo only

[Junio C Hamano]

"Andrew Berry" <andrew@furrypaws.ca> writes:

> split toplevel to "top-level" or "top level".

Ah, that's even better.

[PATCH] docs: .gitignore parsing is to the top of the repo

[Andrew Berry]

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

[PATCH] docs: .gitignore parsing is to the top of the repo

[Andrew Berry]

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

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

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Junio C Hamano]

Andrew Berry <andrew@furrypaws.ca> writes:

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

Sent a wrong/stale patch?

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Junio C Hamano]

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.

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Junio C Hamano]

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.

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Andrew Berry]

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.

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Junio C Hamano]

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

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Andrew Berry]

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

Re: [PATCH] docs: .gitignore parsing is to the top of the repo

[Junio C Hamano]

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