Improve gitignore documentation wrt excluded directories
cover Improve gitignore documentation wrt excluded directories
Also here:
https://github.com/kblees/git/commits/kb/gitignore-doc
These two patches were the result of a discussion mid-october [1] that I almost forgot about...now including an example as suggested by Jeff.
[1] http://thread.gmane.org/gmane.comp.version-control.git/235753/focus=235856
Karsten Blees (2):
gitignore.txt: fix documentation of "**" patterns gitignore.txt: clarify recursive nature of excluded directories
Documentation/gitignore.txt | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-)
Signature · 1 line
1.8.4.msysgit.0.12.g88f5ed0
PATCH 1/2 gitignore.txt: fix documentation of "**" patterns
"**" means bold in ASCIIDOC, so we need to escape it.
--- Documentation/gitignore.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/gitignore.txt +3 -3
@@ -113,12 +113,12 @@ full pathname may have special meaning: - A leading "`**`" followed by a slash means match in all directories. For example, "`**/foo`" matches file or directory - "`foo`" anywhere, the same as pattern "`foo`". "**/foo/bar" + "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`" matches file or directory "`bar`" anywhere that is directly under directory "`foo`". - - A trailing "/**" matches everything inside. For example, - "abc/**" matches all files inside directory "abc", relative + - A trailing "`/**`" matches everything inside. For example, + "`abc/**`" matches all files inside directory "`abc`", relative to the location of the `.gitignore` file, with infinite depth. - A slash followed by two consecutive asterisks then a slash
Signature · 1 line
1.8.4.msysgit.0.12.g88f5ed0
Re: [PATCH 1/2] gitignore.txt: fix documentation of "**" patterns
Quoted 15 lines · Karsten Blees
"**" means bold in ASCIIDOC, so we need to escape it.
Signed-off-by Karsten Blees <[email protected]>--- Documentation/gitignore.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Documentation/gitignore.txt +0
-0@@ -113,12 +113,12 @@ full pathname may have special meaning: - A leading "`**`" followed by a slash means match in all directories. For example, "`**/foo`" matches file or directory
Documentation/gitignore.txt full pathname may have special meaning: · line 122
Quoted 10 lines
Documentation/gitignore.txt +3
-3- "`foo`" anywhere, the same as pattern "`foo`". "**/foo/bar" + "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`" matches file or directory "`bar`" anywhere that is directly under directory "`foo`". - - A trailing "/**" matches everything inside. For example, - "abc/**" matches all files inside directory "abc", relative + - A trailing "`/**`" matches everything inside. For example, + "`abc/**`" matches all files inside directory "`abc`", relative to the location of the `.gitignore` file, with infinite depth.
All, including the quoting of abc that does not have anything to do with the double-asterisk, look good; thanks.
Quoted 2 lines
Documentation/gitignore.txt +0
-0- A slash followed by two consecutive asterisks then a slash
PATCH 2/2 gitignore.txt: clarify recursive nature of excluded directories
In reply to Karsten BleesAdditionally, precedence of negated patterns is exactly as outlined in the DESCRIPTION section, we don't need to repeat this.
--- Documentation/gitignore.txt | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)
Documentation/gitignore.txt +16 -2
@@ -79,8 +79,9 @@ PATTERN FORMAT - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become - included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded (i.e. excluding a directory + will recursively and irrevocably exclude the entire content). Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`".
@@ -182,6 +183,19 @@ Another example: The second .gitignore prevents Git from ignoring `arch/foo/kernel/vmlinux.lds.S`. +Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): + +-------------------------------------------------------------- + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +-------------------------------------------------------------- + SEE ALSO -------- linkgit:git-rm[1],
Signature · 1 line
1.8.4.msysgit.0.12.g88f5ed0
Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories
Quoted 2 lines · Karsten Blees
Additionally, precedence of negated patterns is exactly as outlined in the DESCRIPTION section, we don't need to repeat this.
Very good, thanks.
Even though I have a suspicion that somebody else may be able to come up with a better phrase that does not sound unnecessarily strongly than "recursively and irrevocably", that somebody else is not me, so I'll queue this as-is for now.
Quoted 42 lines
Signed-off-by Karsten Blees <[email protected]>--- Documentation/gitignore.txt | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)Documentation/gitignore.txt +16
-2@@ -79,8 +79,9 @@ PATTERN FORMAT - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become - included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded (i.e. excluding a directory + will recursively and irrevocably exclude the entire content). Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`".@@ -182,6 +183,19 @@ Another example: The second .gitignore prevents Git from ignoring `arch/foo/kernel/vmlinux.lds.S`. +Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): + +-------------------------------------------------------------- + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +-------------------------------------------------------------- + SEE ALSO -------- linkgit:git-rm[1],
Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories
Quoted 11 lines · Junio C Hamano
Quoted 2 lines · Karsten Blees
Additionally, precedence of negated patterns is exactly as outlined in the DESCRIPTION section, we don't need to repeat this.
Very good, thanks.
Even though I have a suspicion that somebody else may be able to come up with a better phrase that does not sound unnecessarily strongly than "recursively and irrevocably", that somebody else is not me, so I'll queue this as-is for now.
Just in case somebody thinks about rephrasing, to me, these two words sound heavier than the information they actually convey, and that is why I said "unnecessarily strong".
The key thing in the behaviour when a directory is excluded is that it tells us to stop going into that directory, and there is no way to override it with another .gitignore file somewhere inside, because we are told not to even bother looking for it. "Recursively and irrevocably" may be an accurate description of the end result, but that sounds more like a rule without a "because"; to a reader (me), it lacks the "aha, of course" that comes from understanding why.
Quoted 41 lines
Quoted 41 lines
Signed-off-by Karsten Blees <[email protected]>--- Documentation/gitignore.txt | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)Documentation/gitignore.txt +16
-2@@ -79,8 +79,9 @@ PATTERN FORMAT - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become - included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded (i.e. excluding a directory + will recursively and irrevocably exclude the entire content). Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`".@@ -182,6 +183,19 @@ Another example: The second .gitignore prevents Git from ignoring `arch/foo/kernel/vmlinux.lds.S`. +Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): + +-------------------------------------------------------------- + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +-------------------------------------------------------------- + SEE ALSO -------- linkgit:git-rm[1],
Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories
Quoted 9 lines · Junio C Hamano
Quoted 7 lines · Junio C Hamano
Quoted 2 lines · Karsten Blees
Additionally, precedence of negated patterns is exactly as outlined in the DESCRIPTION section, we don't need to repeat this.
Very good, thanks.
Quoted 8 lines
Quoted 4 lines
Even though I have a suspicion that somebody else may be able to come up with a better phrase that does not sound unnecessarily strongly than "recursively and irrevocably", that somebody else is not me, so I'll queue this as-is for now.
Just in case somebody thinks about rephrasing, to me, these two words sound heavier than the information they actually convey, and that is why I said "unnecessarily strong".
I agree that it seems unnecessarily strong. The word "irrevocable" to me implies that it cannot ever be changed. But of course it is only irrevocable for the particular run; you can always edit the .gitignore file. :)
Quoted 8 lines
The key thing in the behaviour when a directory is excluded is that it tells us to stop going into that directory, and there is no way to override it with another .gitignore file somewhere inside, because we are told not to even bother looking for it. "Recursively and irrevocably" may be an accurate description of the end result, but that sounds more like a rule without a "because"; to a reader (me), it lacks the "aha, of course" that comes from understanding why.
I think it is more than just "we do not descend and so do not read the .gitignore file". I thought the previous discussion on this topic showed that you cannot do:
$ cat .gitignore foo !foo/bar
to see foo/bar.
Quoted 9 lines
Quoted 9 lines
Documentation/gitignore.txt PATTERN FORMAT · line 86
Quoted 9 lines
- An optional prefix "
!" which negates the pattern; any matching file excluded by a previous pattern will becomeDocumentation/gitignore.txt +3
-2- included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded (i.e. excluding a directory + will recursively and irrevocably exclude the entire content). Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`".
How about:
It is not possible to re-include a file if a parent directory of that file is excluded. Once git considers a directory excluded, it does not descend into the directory to consider its contents further.
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/gitignore.txt +4
-0+Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): +
Quoted 8 lines
Quoted 8 lines
Documentation/gitignore.txt Another example: · line 197
Quoted 8 lines
+--------------------------------------------------------------
Documentation/gitignore.txt +7
-0+ $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +--------------------------------------------------------------
That looks good to me. The simplest example would be handling a top-level directory (i.e., ignore all except /foo). That is a subset of what's happening above, and I think showing the general case is good. I'd worry slightly that a non-astute reader might not figure out how to simplify down to the top-level case, and we should have two examples. I may just be overly pessimistic, though.
-Peff
Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories
Am 07.11.2013 20:55, schrieb Jeff King:
Quoted 38 lines · Junio C Hamano
Quoted 10 lines
Quoted 7 lines · Junio C Hamano
Quoted 2 lines · Karsten Blees
Additionally, precedence of negated patterns is exactly as outlined in the DESCRIPTION section, we don't need to repeat this.
Very good, thanks.
Quoted 8 lines
Quoted 4 lines
Even though I have a suspicion that somebody else may be able to come up with a better phrase that does not sound unnecessarily strongly than "recursively and irrevocably", that somebody else is not me, so I'll queue this as-is for now.
Just in case somebody thinks about rephrasing, to me, these two words sound heavier than the information they actually convey, and that is why I said "unnecessarily strong".
I agree that it seems unnecessarily strong. The word "irrevocable" to me implies that it cannot ever be changed. But of course it is only irrevocable for the particular run; you can always edit the .gitignore file. :)
Quoted 8 lines
The key thing in the behaviour when a directory is excluded is that it tells us to stop going into that directory, and there is no way to override it with another .gitignore file somewhere inside, because we are told not to even bother looking for it. "Recursively and irrevocably" may be an accurate description of the end result, but that sounds more like a rule without a "because"; to a reader (me), it lacks the "aha, of course" that comes from understanding why.
I think it is more than just "we do not descend and so do not read the .gitignore file". I thought the previous discussion on this topic showed that you cannot do:
Quoted 6 lines
$ cat .gitignore foo !foo/barto see foo/bar.
Yes, the pattern could be in .git/info/exclude and it still wouldn't work.
Quoted 10 lines
Quoted 9 lines
Quoted 9 lines
Documentation/gitignore.txt PATTERN FORMAT · line 86
Quoted 9 lines
- An optional prefix "
!" which negates the pattern; any matching file excluded by a previous pattern will becomeDocumentation/gitignore.txt +3
-2- included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded (i.e. excluding a directory + will recursively and irrevocably exclude the entire content). Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`".
Quoted 6 lines
How about:
It is not possible to re-include a file if a parent directory of that file is excluded. Once git considers a directory excluded, it does not descend into the directory to consider its contents further.
Hmm...an unsuspecting reader might still assume that it works in top-level .gitignore, given the precendence rules above...
How about this:
It is not possible to re-include a file if a parent directory of that file is excluded. Git doesn't list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they are defined.
Quoted 22 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/gitignore.txt +4
-0+Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): +Quoted 8 lines
Quoted 8 lines
Documentation/gitignore.txt Another example: · line 197
Quoted 8 lines
+--------------------------------------------------------------
Documentation/gitignore.txt +7
-0+ $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +--------------------------------------------------------------That looks good to me. The simplest example would be handling a top-level directory (i.e., ignore all except
/foo). That is a subset of what's happening above, and I think showing the general case is good. I'd worry slightly that a non-astute reader might not figure out how to simplify down to the top-level case, and we should have two examples. I may just be overly pessimistic, though.-Peff
Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories
Quoted 10 lines · Karsten Blees
Quoted 6 lines
How about:
It is not possible to re-include a file if a parent directory of that file is excluded. Once git considers a directory excluded, it does not descend into the directory to consider its contents further.
Hmm...an unsuspecting reader might still assume that it works in top-level .gitignore, given the precendence rules above...
Quoted 6 lines
How about this:
It is not possible to re-include a file if a parent directory of that file is excluded. Git doesn't list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they are defined.
Yeah, I like that.
-Peff
PATCH 2/2 gitignore.txt: clarify recursive nature of excluded directories
Additionally, precedence of negated patterns is exactly as outlined in the DESCRIPTION section, we don't need to repeat this.
---
I also force-pushed to git://github.com/kblees/git.git kb/gitignore-doc.
Documentation/gitignore.txt | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-)
Documentation/gitignore.txt +17 -2
@@ -79,8 +79,10 @@ PATTERN FORMAT - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become - included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded. Git doesn't list excluded + directories for performance reasons, so any patterns on contained + files have no effect, no matter where they are defined. Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`".
@@ -182,6 +184,19 @@ Another example: The second .gitignore prevents Git from ignoring `arch/foo/kernel/vmlinux.lds.S`. +Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): + +-------------------------------------------------------------- + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +-------------------------------------------------------------- + SEE ALSO -------- linkgit:git-rm[1],
Signature · 1 line
1.8.4.msysgit.1
Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories
Thanks; will queue.