patchLet git-help prefer man-pages installed with this version of git

Prepend $(prefix)/share/man to the MANPATH environment variable before invoking 'man' from help.c:show_man_page().

Signed-off-by: Sergei Organov <osv@javad.com>
---
 Makefile |    5 ++++-
 help.c   |   21 +++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletions(-)

Hi,

On Thu, 6 Dec 2007, Sergei Organov wrote:

This commit message is severely lacking. Why would you _ever_ prefer the installed man pages before invoking "man", which should find them anyway?

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Obviously because you want manual pages corresponding to the version of git you are invoking, not any random version of man-pages man may find by default.

Sergei Organov <osv@javad.com> writes:

While I almost agree with the rest of your sentence, you have to realize that it is obviously not obvious if somebody asked you to clarify.

How about this:

    Prepend $(prefix)/share/man to the MANPATH environment variable
    before invoking 'man' from help.c:show_man_page().  There may be
    other git documentation in the user's MANPATH but the user is asking
    a specific instance of git about its own documentation, so we'd
    better show the documentation for _that_ instance of git.

Having written that, it is very tempting to further clarify the above:

    Usually, if a user has his own version of git and regularly uses it
    by having the non-system executable directory (e.g. $HOME/bin/git)
    early in his $PATH, its corresponding documentation would also be in
    a non-system documentation directory (e.g. $HOME/man) early in his
    $MANPATH, and this change is a no-op.  The only case this change
    matters is where the user installs his own git outside of his $PATH
    and $MANPATH, and explicitly runs his git executable
    (e.g. "$HOME/junk/git-1.5.4/bin/git diff").

When you clarify it this way, the change does not look as useful anymore, does it? How typical would that use be, to run your git executable by always naming it by path without relying on $PATH environment variable?

Junio C Hamano <gitster@pobox.com> writes:

Probably.

This sounds nice to me. Do you want me to re-submit the patch with modified commit message?

First, I don't think you need to clarify like this. It is just implementation detail of git-help that it uses 'man', and thus implicitly relies on MANPATH. The essential thing has been already stated above: git-help should show correct documentation.

Second, the change is still useful even if user did put custom path to 'git' into its PATH, but didn't even thought of customizing MANPATH. Besides, a user could be entirely unaware of 'man' the utility.

Yes, it still does, I think. I doubt it's that obvious that 'git help' uses MANPATH at all. Besides, it's not 'git man', isn't it? To further emphasize my point, we don't require user to tweak MANPATH in order to get corresponding 'git --help' output, isn't it? Also, please look here:

$ ~/git/bin/git help -a | head -n 3 | tail -n 1 available git commands in '/home/osv/git/bin' $ git help -a | head -n 3 | tail -n 1 git commands available in '/usr/bin' $

And the last, basing on the same arguments, it's not that useful that 'git xxx' invokes correct 'git-xxx' command by prepending installation path to the PATH, isn't it?

Overall, I just want 'git help' to behave consistently.

To tell the truth, I'd prefer to just use -M option of man and don't rely on MANPATH at all, so that 'git help' will issue error if there is no documentation installed for this particular version of git.

[BTW, git-help lacks his own man page, so I can't actually argue on a ground of some documentation of git-help.]

Sergei Organov wrote:

 >> Having written that, it is very tempting to further clarify the above:

The number of users in the entire world that are completely unaware of the 'man' utility but still manages to build git and install it in a non-default path can probably be counted on one hand of a 65 year old saw-mill worker.

I'm not sure if we're doing them a greater service by DWIMing this or by telling them about the 'man' utility.

Does "man -M" work everywhere, or is your patch opening a can of worms to get probably-not-needed functionality?

Otoh, you submitted a patch, so there are probably a few people out there that care about this. I'm not one of them, so I'll shut up now that my lunch is over ;-)

Andreas Ericsson <ae@op5.se> writes:

[...]

This patch doesn't use "man -M", it tweaks MANPATH instead. Partly because the rest of 'git' tweaks 'PATH' to get correct executable to be run, and not run it using explicit absolute path, so tweaking MANPATH is consistent with the rest of git.

Sergei Organov <osv@javad.com> writes:

Ok, this is a good argument for the patch. With Christian's enhancements, we will handle -i(nfo) and -w(eb) and we will tell the "info" and "html" browsers where the documentation we installed for the running instance of git is, so we should do so consistently for "manpage" browser (aka "man"). You are right.

On Fri, Dec 07, 2007 at 02:39:24AM -0800, Junio C Hamano wrote:

Or, git gets installed out of path in its own tree, and then the 'git' executable itself is symlinked somewhere into the path. I know this happens, because this is what IT ended up doing.

It's also fairly easy to add a new executable path, and forget to add a new manpath directory.

Dave

On Fri, Dec 07, 2007 at 08:19:19AM -0800, David Brown wrote:

   This is what IT ended up doing, where I work.

I haven't run into the problem this patch fixes because the strange out-of-path git is the only version of git available on the systems.

Dave