Re: [PATCH] Documentation: have ls-files and ls-tree "see also" each other

From: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
Date: Jun 5, 2012, 06:29 UTC
Message-ID: <20120605062935.GA4683@comcast.net>
In-Reply-To: <7vehpuqpob.fsf@alter.siamese.dyndns.org>

On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:

Show 20 quoted lines

> Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:
> 
> > Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>
> > ---
> >
> > I could have used these references when I was looking at git-ls-files
> > documentation and trying to figure out how to make it list files
> > from a specific commit like git-ls-tree.
> 
> I do not like this kind of patches in general.  Where will it end?
> 
> "I wanted to know how to list objects recorded in a commit, and I
> could have used a reference to git-ls-tree from git-commit, so here
> is a patch to make them refer to each other"?
> 
> That kind of overfiew is what the tutorial (for concepts like the
> index, tree objects, commit objects, etc.) and the list of commands
> in git(1).  Is there compelling reason other than "I didn't bother
> to look, and it is likely other people wouldn't" to apply patches
> like this?

Not really.  Certainly this is a low priority change.

But why do many of the man pages have "SEE ALSO" sections? Should we just get rid of such sections? Does anyone have any guidelines/rules for what makes sense to be in a "SEE ALSO" section?

My personal impression is that git-ls-files (which lists files in the working directory or index) and git-ls-tree (which lists files in a commit or tree object) are so similar that they could almost be merged into a single command. Linking them together in the documentation seemed obvious, but maybe that's just me.