From: Matthew Ogilvie Date: Tue, 05 Jun 2012 06:29:35 GMT Subject: Re: [PATCH] Documentation: have ls-files and ls-tree "see also" each other 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: > Matthew Ogilvie writes: > > > Signed-off-by: Matthew Ogilvie > > --- > > > > 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.