[PATCH] git show documentation: no longer refer to git-diff-tree options

The only git-diff-tree option that makes sense with git-show is '-s',
but (from a user's point of view) it has sightly different meaning,
since you don't have a --stdin option when using git-show.

This patch removes the reference to git-diff-tree options and adds
documentation for '-s', in the context of git-show.

Signed-off-by: Miklos Vajna <redacted>
---

On Sun, Apr 27, 2008 at 04:29:55PM +0900, nanako3@bluebottle.com wrote:

I do not know if the updated patch is correct either.

Did you try "git show" with the options you have in the new
"tree-options" file, for example "git show --root HEAD", and checked
to make sure they make sense?

The initial problem I tried to solve with this patch is to avoid the
situation, when you try to figure out what 'git show --foo' does and you
can't find that option in man git-show, which is a usability problem, I
think.

I think "git show -s" makes sense as it is easier to type than "git
log -1" but I do not think any other options you listed makes sense
with "git show".

I just checked each option one by one and right, I haven't found any
other option that could be useful for git-show either. Given that the
wording of -s for git-show is quite different, I think it would be
easier to just document -s in git-show as well. Like this?

Thanks.

 Documentation/git-show.txt |    9 +++------
 1 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index dccf0e2..299b611 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt

@@ -25,12 +25,6 @@ with \--name-only).
 
 For plain blobs, it shows the plain contents.
 
-The command takes options applicable to the linkgit:git-diff-tree[1] command to
-control how the changes the commit introduces are shown.
-
-This manual page describes only the most frequently used options.
-
-
 OPTIONS
 -------
 <object>::

@@ -38,6 +32,9 @@ OPTIONS
 	For a more complete list of ways to spell object names, see
 	"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
 
+-s::
+	Don't show a textural diff for commits.
+
 include::pretty-options.txt[]
 
 

-- 
1.5.5.1.91.g499fc.dirty

Miklos Vajna [off-list ref] writes:

I just checked each option one by one and right, I haven't found any
other option that could be useful for git-show either. Given that the
wording of -s for git-show is quite different, I think it would be
easier to just document -s in git-show as well. Like this?

Hmm, yes but not exactly.

You lost --stat, --name-only and friends that were implied by mentioning
"diff-tree".

I agree your _motivation_ behind your original patch is good.  Saying "see
also that page if you want to do very exotic and rarely useful operation"
is one thing, but saying "described are most often used ones" and not
describing enough is bad.

Perhaps we would want to include diff-options.txt.  There may be some
options that are no-op or always-on in the context of "git show" in the
file, but we already have an infrastracture to turn parts of the inclusion
on and off depending on which manual page includes it.

The only git-diff-tree option that makes sense with git-show is '-s',
but (from a user's point of view) it has sightly different meaning,
since you don't have a --stdin option when using git-show.

This patch removes the reference to git-diff-tree options and adds
documentation for '-s', in the context of git-show.

It also includes git-diff options, but excludes the ones which are not
relevant for this command.

Signed-off-by: Miklos Vajna <redacted>
---

On Sun, Apr 27, 2008 at 10:33:26AM -0700, Junio C Hamano [off-list ref] wrote:

Hmm, yes but not exactly.

You lost --stat, --name-only and friends that were implied by
mentioning
"diff-tree".

I agree your _motivation_ behind your original patch is good.  Saying
"see
also that page if you want to do very exotic and rarely useful
operation"
is one thing, but saying "described are most often used ones" and not
describing enough is bad.

Perhaps we would want to include diff-options.txt.  There may be some
options that are no-op or always-on in the context of "git show" in
the
file, but we already have an infrastracture to turn parts of the
inclusion
on and off depending on which manual page includes it.

This patch implements this, I hope.

(Sorry for the delay, BTW.)

 Documentation/diff-options.txt |   10 ++++++++++
 Documentation/git-show.txt     |   14 ++++++++------
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 13234fa..af7846d 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt

@@ -17,6 +17,7 @@ ifdef::git-format-patch[]
 	Generate patches without diffstat.
 endif::git-format-patch[]
 
+ifndef::git-show[]
 ifndef::git-format-patch[]
 -p::
 	Generate patch (see section on generating patches).

@@ -25,6 +26,7 @@ endif::git-format-patch[]
 
 -u::
 	Synonym for "-p".
+endif::git-show[]
 
 -U<n>::
 	Shorthand for "--unified=<n>".

@@ -37,8 +39,10 @@ endif::git-format-patch[]
 	Generate the raw format.
 	{git-diff-core? This is the default.}
 
+ifndef::git-show[]
 --patch-with-raw::
 	Synonym for "-p --raw".
+endif::git-show[]
 
 --stat[=width[,name-width]]::
 	Generate a diffstat.  You can override the default

@@ -70,6 +74,7 @@ endif::git-format-patch[]
 	Output a condensed summary of extended header information
 	such as creations, renames and mode changes.
 
+ifndef::git-show[]
 --patch-with-stat::
 	Synonym for "-p --stat".
 	{git-format-patch? This is the default.}

@@ -78,6 +83,7 @@ endif::git-format-patch[]
 	NUL-line termination on output.  This affects the --raw
 	output field terminator.  Also output from commands such
 	as "git-log" will be delimited with NUL between commits.
+endif::git-show[]
 
 --name-only::
 	Show only names of changed files.

@@ -159,6 +165,7 @@ endif::git-format-patch[]
 	the number of rename/copy targets exceeds the specified
 	number.
 
+ifndef::git-show[]
 -S<string>::
 	Look for differences that contain the change in <string>.
 

@@ -170,6 +177,7 @@ endif::git-format-patch[]
 --pickaxe-regex::
 	Make the <string> not a plain string but an extended POSIX
 	regex to match.
+endif::git-show[]
 
 -O<orderfile>::
 	Output the patch in the order specified in the

@@ -212,6 +220,7 @@ endif::git-format-patch[]
 -w::
 	Shorthand for "--ignore-all-space".
 
+ifndef::git-show[]
 --exit-code::
 	Make the program exit with codes similar to diff(1).
 	That is, it exits with 1 if there were differences and

@@ -219,6 +228,7 @@ endif::git-format-patch[]
 
 --quiet::
 	Disable all output of the program. Implies --exit-code.
+endif::git-show[]
 
 --ext-diff::
 	Allow an external diff helper to be executed. If you set an

diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index dccf0e2..6b5c3fb 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt

@@ -25,12 +25,6 @@ with \--name-only).
 
 For plain blobs, it shows the plain contents.
 
-The command takes options applicable to the linkgit:git-diff-tree[1] command to
-control how the changes the commit introduces are shown.
-
-This manual page describes only the most frequently used options.
-
-
 OPTIONS
 -------
 <object>::

@@ -38,6 +32,14 @@ OPTIONS
 	For a more complete list of ways to spell object names, see
 	"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
 
+-s, --quiet::
+	Don't show a textural diff for commits.
+
+
+:git-show: 1
+include::diff-options.txt[]
+
+
 include::pretty-options.txt[]
 
 

-- 
1.5.5.1