[PATCH] Add cross-references between docs for for-each-ref and show-ref

[PATCH] Add cross-references between docs for for-each-ref and show-ref

[Michael Haggerty]

Add cross-references between the manpages for git-for-each-ref(1) and
git-show-ref(1).

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
There is a lot of overlap between the functionality of these two
commands.  It might be handy to give the user some hints about when to
use one command vs. the other, but honestly I don't have a gut feeling
for this myself.  Maybe long-term the commands should converge into
one?

 Documentation/git-for-each-ref.txt | 4 ++++
 Documentation/git-show-ref.txt     | 1 +
 2 files changed, 5 insertions(+)

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 94f5c46..d639abe 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -227,6 +227,10 @@ Documentation
 -------------
 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
+SEE ALSO
+--------
+linkgit:git-show-ref[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index b0a309b..ffd1b03 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -175,6 +175,7 @@ FILES
 
 SEE ALSO
 --------
+linkgit:git-for-each-ref[1],
 linkgit:git-ls-remote[1],
 linkgit:git-update-ref[1],
 linkgit:gitrepository-layout[5]
-- 
1.8.5.2

Re: [PATCH] Add cross-references between docs for for-each-ref and show-ref

[Junio C Hamano]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> Add cross-references between the manpages for git-for-each-ref(1) and
> git-show-ref(1).
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
> There is a lot of overlap between the functionality of these two
> commands.

Two differences I most often use (i.e. take advantage of) are:

 - The former is about showing 0 or more matching refs, and not
   matching anything is a perfectly normal condition, i.e.

   $ git for-each-ref refs/heads/no-such

   exits with status 0.  The latter can be used with --verify to
   check if one ref exists, on the other hand.

 - The former takes the match-from-left-to-right pattern (similar to
   the usual pathspec match), while the latter matches from the
   tail.

   $ git for-each-ref refs/heads/*  ;# only one-level names
   $ git for-each-ref refs/heads/** ;# catches both master and mh/path-max
   $ git show-ref master ;# refs/heads/master, refs/remotes/origin/master,...