threads / patch / 30711

patchDocumentation: have ls-files and ls-tree "see also" each other

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

## tl;dr

4 messages between Jun 5, 2012 and Jun 5, 2012. Diffs are folded; open one to read it.

replies: 3people: 2as markdown or json

Matthew Ogilvie· Jun 5, 2012, 05:10 UTC · lore
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.

(This is a resend. I sent this patch a couple of weeks ago, but it apparently slipped through the cracks.)

 Documentation/git-ls-files.txt |    2 +-
 Documentation/git-ls-tree.txt  |    4 ++++
 2 files changed, 5 insertions(+), 1 deletions(-)
Show changes to 2 files +5 −1

Documentation/git-ls-files.txt, Documentation/git-ls-tree.txt

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 4b28292..8ce3c3b 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -207,7 +207,7 @@ pattern file appears in.
 
 SEE ALSO
 --------
-linkgit:git-read-tree[1], linkgit:gitignore[5]
+linkgit:git-ls-tree[1], linkgit:git-read-tree[1], linkgit:gitignore[5]
 
 GIT
 ---
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 16e87fd..1cd52cc 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -95,6 +95,10 @@ Object size identified by <object> is given in bytes, and right-justified
 with minimum width of 7 characters.  Object size is given only for blobs
 (file) entries; for other entries `-` character is used in place of size.
 
+SEE ALSO
+--------
+linkgit:git-ls-files[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
Junio C Hamano· Jun 5, 2012, 05:43 UTC · re: Matthew Ogilvie · lore

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

Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:
Show 6 quoted lines
> 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?

Matthew Ogilvie· Jun 5, 2012, 06:29 UTC · re: Junio C Hamano · lore

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

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.

Junio C Hamano· Jun 5, 2012, 15:03 UTC · re: Matthew Ogilvie · lore

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

Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:
Show 14 quoted lines
> On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:
>> ...
>> 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?

Two questions that sound similar, somewhat related to each other, but fundamentally different are [*1*]:

 - Does it help knowing B to make good use of A?
 - Do you need to know what is in the documentation for B in order
   to understand what is in the documentation for A?

If the answer to either one is yes, it may be a good idea to have "See also B" in the documentation for A.

The ls-files and ls-tree pair does not pass either of the above two tests. They both give list of paths (but so do "diff --name-only" and other things), but the similarity between them stops there, and more importantly, similarity does not play any role in the above two tests.

If we had a third test:
 - Does it help knowing B to avoid wasting time attempting to use A
   for a task for which A is not a suitable tool?

then ls-files and ls-tree pair would qualify. I however am not convinced it is particularly a good test.

[Footnote]

*1* Note that the latter is a sign that A is described in terms of B (i.e. "We assume you understand B; otherwise stop now, go there and learn B, and come back. Now we will describe A"); it is preferrable to avoid it if we can do so without duplication of the information at the source level.

← back to recent threads