From: Petr Baudis <pasky@suse.cz>
Date: Mon, 21 Jul 2008 21:04:52 GMT
Subject: Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Message-ID: <20080721210452.GP10151@machine.or.cz>
In-Reply-To: <7v1w1nvf7q.fsf@gitster.siamese.dyndns.org>

On Mon, Jul 21, 2008 at 01:00:57AM -0700, Junio C Hamano wrote:
> Petr Baudis <pasky@suse.cz> writes:
> 
> > +Note that within a subdirectory of the working copy, 'git ls-tree'
> > +will automatically prepend the subdirectory prefix to the specified
> > +paths and assume just the prefix was specified in case no paths were
> > +given --- no matter what the tree object is!
> 
> Don't be negative upfront.  Explain why this is a good thing first.
> 
> 	... were given.  This is useful when you are deep in a
> 	subdirectory and want to inspect the list of files in an arbitrary
> 	commit.  E.g.
> 
> 		$ cd some/deep/path
> 		$ git ls-tree --name-only -r HEAD~20
> 
> 	will list the files in some/deep/path (i.e. where you are) 20
> 	commits ago, just like running "/bin/ls" there will give you the
> 	list of files you have right now.

Frankly, I think this is overdoing it. I'm all for being positive, but
it is obvious why this is good thing when you inspect a root tree and
there's no need to be too wordy about it - it should be enough to
acknowledge this later by the "as expected" as I note below.

The documentation should be detailed and complete, but not too chatty,
or it gets too hard to read again.

> > +Thus, within a subdirectory, 'git ls-tree' behaves as expected
> > +only when run on a root tree object (e.g. with a 'HEAD' tree-ish,
> > +but not anymore when passed 'HEAD:Documentation' instead).
> > +
> > +
> >  OPTIONS
> >  -------
> >  <tree-ish>::

-- 
				Petr "Pasky" Baudis
As in certain cults it is possible to kill a process if you know
its true name.  -- Ken Thompson and Dennis M. Ritchie