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

[Matthew Ogilvie <mmogilvi_git@miniinfo.net>]

On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:
> 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.