Re: Errors in man git

From: Jan Krüger <jk@jk.gs>
Date: Sep 8, 2010, 21:31 UTC
Message-ID: <20100908233140.7d5df3ee@jk.gs>
In-Reply-To: <BLU0-SMTP666507C6D3E37A50B92431BB720@phx.gbl>

Hi,

"Daniel U. Thibault" <d.u.thibault@sympatico.ca> wrote:

> There are no indications in the "man git" pages as to how to
> report errors, so I'm following the instructions I googled at 
> http://www.kernel.org/doc/man-pages/reporting_bugs.html (adding 
> git@vger.kernel.org to the mailing list as it seems appropriate).

Since the manpages are written by the git project only, I think it's more appropriate to address the git mailing list only. [pruning other recipients]

Show 6 quoted lines

> [...] Hence "git COMMAND" should work once the appropriate value
> is substituted for COMMAND.  The COMMANDs are later documented (GIT 
> COMMANDS) as long lists of "porcelain" and "plumbing" COMMANDs.  
> However, *none* of the COMMANDs given actually work.  For instance,
> one (porcelain) COMMAND is "git-gui" but typing "git git-gui" in a
> command shell results in the message:

That's because of the way other manpages have to be referenced. Let me include a snippet from the manpage to clarify:

| HIGH-LEVEL COMMANDS (PORCELAIN)
|       We separate the porcelain commands into the main commands and
|       some ancillary user utilities.
|
|   Main porcelain commands
|       git-add(1)
|           Add file contents to the index.

Here, "git-add(1)" is written in one word because otherwise it's not a valid reference to another manpage. The only alternative is that we rename the manpage to "add"... but people probably won't like git polluting the manpage namespace that way, and "add" by itself isn't a valid command anyway.

If you look at "man git-add", you'll see that the synopsis given there shows the right way to invoke the command:

| NAME
|       git-add - Add file contents to the index
| 
| SYNOPSIS
|       git add [-n] [-v] [--force | -f] [--interactive | -i]
|                [--patch | -p] [--edit | -e] [--all | [--update | -u]]
|                [--intent-to-add | -N] [--refresh] [--ignore-errors]
|                [--ignore-missing] [--] [<filepattern>...]

I agree that it is potentially confusing, but the manpage references are clearly recognisable as such.

Personally I don't consider it necessary to change this, since it's clearly not horribly complicated to figure out the meaning, but here's a patch for the sake of completeness.

----8<----

Subject: [PATCH] Documentation/git.txt: explain that manpages for subcommands exist

On the off chance that it is not apparent that the manpages for individual git commands explain how to use git commands (e.g. if someone manages to conclude that "git git-add" is the way to use git-add(1)), add a small explanation about that.

Signed-off-by: Jan Krüger <jk@jk.gs>
---
 Documentation/git.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 93e3b07..fbceb12 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -316,7 +316,8 @@ GIT COMMANDS
 ------------
 
 We divide git into high level ("porcelain") commands and low level
-("plumbing") commands.
+("plumbing") commands. Please refer to the individual manpages listed
+in the sections below for details on how to invoke each command.
 
 High-level commands (porcelain)
 -------------------------------

-- 
1.7.2.3.392.g02377