[PATCH] Clarified documentation of --exclude-per-directory.

[PATCH] Clarified documentation of --exclude-per-directory.

[Shawn Pearce]

Tommi Virtanen noted on #git today that

  git ls-files --exclude-per-directory

doesn't appear to work as advertised by the documentation unless
--others is also used.  According to the current source code this
is the case as the --exclude-per-directory file isn't read unless
we are iterating over the working directory, which only happens
with --others.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
 Documentation/git-ls-files.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 8520b97..2a0b9f8 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -75,7 +75,8 @@ OPTIONS
 
 --exclude-per-directory=<file>::
 	read additional exclude patterns that apply only to the
-	directory and its subdirectories in <file>.
+	directory and its subdirectories in <file>.  This option
+	only takes effect if -o or --others is also used.
 
 --error-unmatch::
 	If any <file> does not appear in the index, treat this as an
@@ -167,7 +168,7 @@ time.  They are built and ordered in the
  * lines read from --exclude-from=<file>; patterns are ordered
    in the same order as they appear in the file.
 
- * When --exclude-per-directory=<name> is specified, upon
+ * When --exclude-per-directory=<name> and --others is specified, upon
    entering a directory that has such a file, its contents are
    appended at the end of the current "list of patterns".  They
    are popped off when leaving the directory.
-- 
1.4.2.1.g7a39b

Re: [PATCH] Clarified documentation of --exclude-per-directory.

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Tommi Virtanen noted on #git today that
>
>   git ls-files --exclude-per-directory
>
> doesn't appear to work as advertised by the documentation unless
> --others is also used.  According to the current source code this
> is the case as the --exclude-per-directory file isn't read unless
> we are iterating over the working directory, which only happens
> with --others.

I am puzzled by this problem description.

If we _were_ to read --exclude-per-directory file when we are
not doing --others, what better behaviour would we get out of
the command?

Re: [PATCH] Clarified documentation of --exclude-per-directory.

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Shawn Pearce <spearce@spearce.org> writes:
> 
> > Tommi Virtanen noted on #git today that
> >
> >   git ls-files --exclude-per-directory
> >
> > doesn't appear to work as advertised by the documentation unless
> > --others is also used.  According to the current source code this
> > is the case as the --exclude-per-directory file isn't read unless
> > we are iterating over the working directory, which only happens
> > with --others.
> 
> I am puzzled by this problem description.
> 
> If we _were_ to read --exclude-per-directory file when we are
> not doing --others, what better behaviour would we get out of
> the command?
 
From what I was able to gather on #git Tommi was trying to do:

	mkdir foo ; cd foo ; git init-db
	echo foo >foo
	echo foo >ignore
	git add foo ignore
	git commit -a -m create
	rm *
	git ls-files --exclude-per-directory=ignore \
		| git checkout-index

and not see "foo" come back into the working directory.  I don't
know what circumstances lead him to want to create an exclude file
pattern on a per-directory basis for use with checkout-index but
that seems to be what he was trying to do.


I don't really see a problem with applying --exclude-per-directory
all of time (like we apply --exclude=.git/info/exclude all of
time), its just not what the code does today.  I just personally
don't need that and don't have the time to fix ls-files to do so.
So I took the shorter approach and updated the documentation. :)

-- 
Shawn.