Junio C Hamano [off-list ref] writes:
Karsten Blees [off-list ref] writes:
quoted
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
Signed-off-by: Karsten Blees <redacted>
---
Documentation/gitignore.txt | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index f971960..5ecc48e 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -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],
On Thu, Nov 07, 2013 at 11:37:38AM -0800, Junio C Hamano wrote:
Junio C Hamano [off-list ref] writes:
quoted
Karsten Blees [off-list ref] writes:
quoted
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".
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. :)
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
quoted
- 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`".
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
quoted
+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
+--------------------------------------------------------------
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
Am 07.11.2013 20:55, schrieb Jeff King:
On Thu, Nov 07, 2013 at 11:37:38AM -0800, Junio C Hamano wrote:
quoted
Junio C Hamano [off-list ref] writes:
quoted
Karsten Blees [off-list ref] writes:
quoted
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".
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
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.
Yes, the pattern could be in .git/info/exclude and it still wouldn't work.
quoted
quoted
quoted
- 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`".
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
quoted
quoted
+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
+--------------------------------------------------------------
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
On Thu, Nov 07, 2013 at 09:27:16PM +0100, Karsten Blees wrote:
quoted
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.
Yeah, I like that.
-Peff
Additionally, precedence of negated patterns is exactly as outlined in
the DESCRIPTION section, we don't need to repeat this.
Signed-off-by: Karsten Blees <redacted>
---
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(-)
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index f971960..205e80e 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -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],
--
1.8.4.msysgit.1