{"thread":{"id":"11161","subject":"[PATCH] Let git-help prefer man-pages installed with this version of git","startedAt":"2007-12-06T18:33:01Z","lastAt":"2007-12-07T19:29:15Z","messageCount":10,"participants":["Sergei Organov","Johannes Schindelin","Junio C Hamano","Andreas Ericsson","David Brown"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"62178","messageId":"87hciv7jkt.fsf@osv.gnss.ru","threadId":"11161","inReplyTo":null,"subject":"[PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-12-06T18:33:01Z","receivedAt":"2007-12-06T18:33:01Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"Prepend $(prefix)/share/man to the MANPATH environment variable\nbefore invoking 'man' from help.c:show_man_page().\n\nSigned-off-by: Sergei Organov \n---\n Makefile | 5 ++++-\n help.c | 21 +++++++++++++++++++++\n 2 files changed, 25 insertions(+), 1 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex 999391e..3030d31 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -154,6 +154,7 @@ STRIP ?= strip\n \n prefix = $(HOME)\n bindir = $(prefix)/bin\n+mandir = $(prefix)/share/man\n gitexecdir = $(bindir)\n sharedir = $(prefix)/share\n template_dir = $(sharedir)/git-core/templates\n@@ -744,6 +745,7 @@ ETC_GITCONFIG_SQ = $(subst ','\\'',$(ETC_GITCONFIG))\n \n DESTDIR_SQ = $(subst ','\\'',$(DESTDIR))\n bindir_SQ = $(subst ','\\'',$(bindir))\n+mandir_SQ = $(subst ','\\'',$(mandir))\n gitexecdir_SQ = $(subst ','\\'',$(gitexecdir))\n template_dir_SQ = $(subst ','\\'',$(template_dir))\n prefix_SQ = $(subst ','\\'',$(prefix))\n@@ -790,7 +792,8 @@ git$X: git.o $(BUILTIN_OBJS) $(GITLIBS)\n \t$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ git.o \\\n \t\t$(BUILTIN_OBJS) $(ALL_LDFLAGS) $(LIBS)\n \n-help.o: common-cmds.h\n+help.o: help.c common-cmds.h GIT-CFLAGS\n+\t$(QUIET_CC)$(CC) -o $*.o -c $(ALL_CFLAGS) '-DGIT_MAN_PATH=\"$(mandir_SQ)\"' $<\n \n git-merge-subtree$X: git-merge-recursive$X\n \t$(QUIET_BUILT_IN)$(RM) $@ && ln git-merge-recursive$X $@\ndiff --git a/help.c b/help.c\nindex 37a9c25..9f843c9 100644\n--- a/help.c\n+++ b/help.c\n@@ -8,6 +8,8 @@\n #include \"exec_cmd.h\"\n #include \"common-cmds.h\"\n \n+static const char *builtin_man_path = GIT_MAN_PATH;\n+\n /* most GUI terminals set COLUMNS (although some don't export it) */\n static int term_columns(void)\n {\n@@ -239,6 +241,24 @@ void list_common_cmds_help(void)\n \t}\n }\n \n+static void setup_man_path(void)\n+{\n+\tconst char *old_path = getenv(\"MANPATH\");\n+\tstruct strbuf new_path;\n+\n+\tstrbuf_init(&new_path, 0);\n+\n+\tstrbuf_addstr(&new_path, builtin_man_path);\n+\tif (old_path) {\n+\t\tstrbuf_addch(&new_path, ':');\n+\t\tstrbuf_addstr(&new_path, old_path);\n+\t}\n+\n+\tsetenv(\"MANPATH\", new_path.buf, 1);\n+\n+\tstrbuf_release(&new_path);\n+}\n+\n static void show_man_page(const char *git_cmd)\n {\n \tconst char *page;\n@@ -254,6 +274,7 @@ static void show_man_page(const char *git_cmd)\n \t\tpage = p;\n \t}\n \n+\tsetup_man_path();\n \texeclp(\"man\", \"man\", page, NULL);\n }\n \n-- \n1.5.3.4\n"},{"id":"62193","messageId":"Pine.LNX.4.64.0712062107520.21625@wbgn129.biozentrum.uni-wuerzburg.de","threadId":"11161","inReplyTo":"87hciv7jkt.fsf@osv.gnss.ru","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-12-06T20:09:05Z","receivedAt":"2007-12-06T20:09:05Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Thu, 6 Dec 2007, Sergei Organov wrote:\n\n> Prepend $(prefix)/share/man to the MANPATH environment variable before \n> invoking 'man' from help.c:show_man_page().\n\nThis commit message is severely lacking. Why would you _ever_ prefer the \ninstalled man pages before invoking \"man\", which should find them anyway?\n\nCiao,\nDscho\n"},{"id":"62268","messageId":"87d4ti7qu1.fsf@osv.gnss.ru","threadId":"11161","inReplyTo":"Pine.LNX.4.64.0712062107520.21625@wbgn129.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-12-07T10:16:06Z","receivedAt":"2007-12-07T10:16:06Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"Johannes Schindelin writes:\n\n> Hi,\n>\n> On Thu, 6 Dec 2007, Sergei Organov wrote:\n>\n>> Prepend $(prefix)/share/man to the MANPATH environment variable before \n>> invoking 'man' from help.c:show_man_page().\n>\n> This commit message is severely lacking. Why would you _ever_ prefer the \n> installed man pages before invoking \"man\", which should find them\n> anyway?\n\nObviously because you want manual pages corresponding to the version of\ngit you are invoking, not any random version of man-pages man may find\nby default.\n\n-- \nSergei.\n"},{"id":"62270","messageId":"7vodd23i1v.fsf@gitster.siamese.dyndns.org","threadId":"11161","inReplyTo":"87d4ti7qu1.fsf@osv.gnss.ru","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-07T10:39:24Z","receivedAt":"2007-12-07T10:39:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergei Organov writes:\n\n> Johannes Schindelin writes:\n>\n>> On Thu, 6 Dec 2007, Sergei Organov wrote:\n>>\n>>> Prepend $(prefix)/share/man to the MANPATH environment variable before \n>>> invoking 'man' from help.c:show_man_page().\n>>\n>> This commit message is severely lacking. Why would you _ever_ prefer the \n>> installed man pages before invoking \"man\", which should find them\n>> anyway?\n>\n> Obviously because you want manual pages corresponding to the version of\n> git you are invoking, not any random version of man-pages man may find\n> by default.\n\nWhile I almost agree with the rest of your sentence, you have to realize\nthat it is obviously not obvious if somebody asked you to clarify.\n\nHow about this:\n\n Prepend $(prefix)/share/man to the MANPATH environment variable\n before invoking 'man' from help.c:show_man_page(). There may be\n other git documentation in the user's MANPATH but the user is asking\n a specific instance of git about its own documentation, so we'd\n better show the documentation for _that_ instance of git.\n\nHaving written that, it is very tempting to further clarify the above:\n\n Usually, if a user has his own version of git and regularly uses it\n by having the non-system executable directory (e.g. $HOME/bin/git)\n early in his $PATH, its corresponding documentation would also be in\n a non-system documentation directory (e.g. $HOME/man) early in his\n $MANPATH, and this change is a no-op. The only case this change\n matters is where the user installs his own git outside of his $PATH\n and $MANPATH, and explicitly runs his git executable\n (e.g. \"$HOME/junk/git-1.5.4/bin/git diff\").\n\nWhen you clarify it this way, the change does not look as useful\nanymore, does it? How typical would that use be, to run your git\nexecutable by always naming it by path without relying on $PATH\nenvironment variable?\n"},{"id":"62275","messageId":"871w9y7mei.fsf@osv.gnss.ru","threadId":"11161","inReplyTo":"7vodd23i1v.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-12-07T11:51:49Z","receivedAt":"2007-12-07T11:51:49Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"Junio C Hamano writes:\n\n> Sergei Organov writes:\n>\n>> Johannes Schindelin writes:\n>>\n>>> On Thu, 6 Dec 2007, Sergei Organov wrote:\n>>>\n>>>> Prepend $(prefix)/share/man to the MANPATH environment variable before \n>>>> invoking 'man' from help.c:show_man_page().\n>>>\n>>> This commit message is severely lacking. Why would you _ever_ prefer the \n>>> installed man pages before invoking \"man\", which should find them\n>>> anyway?\n>>\n>> Obviously because you want manual pages corresponding to the version of\n>> git you are invoking, not any random version of man-pages man may find\n>> by default.\n>\n> While I almost agree with the rest of your sentence, you have to realize\n> that it is obviously not obvious if somebody asked you to clarify.\n\nProbably.\n\n>\n> How about this:\n>\n> Prepend $(prefix)/share/man to the MANPATH environment variable\n> before invoking 'man' from help.c:show_man_page(). There may be\n> other git documentation in the user's MANPATH but the user is asking\n> a specific instance of git about its own documentation, so we'd\n> better show the documentation for _that_ instance of git.\n\nThis sounds nice to me. Do you want me to re-submit the patch with\nmodified commit message?\n\n>\n> Having written that, it is very tempting to further clarify the above:\n>\n> Usually, if a user has his own version of git and regularly uses it\n> by having the non-system executable directory (e.g. $HOME/bin/git)\n> early in his $PATH, its corresponding documentation would also be in\n> a non-system documentation directory (e.g. $HOME/man) early in his\n> $MANPATH, and this change is a no-op. The only case this change\n> matters is where the user installs his own git outside of his $PATH\n> and $MANPATH, and explicitly runs his git executable\n> (e.g. \"$HOME/junk/git-1.5.4/bin/git diff\").\n\nFirst, I don't think you need to clarify like this. It is just\nimplementation detail of git-help that it uses 'man', and thus\nimplicitly relies on MANPATH. The essential thing has been already\nstated above: git-help should show correct documentation.\n\nSecond, the change is still useful even if user did put custom path to\n'git' into its PATH, but didn't even thought of customizing\nMANPATH. Besides, a user could be entirely unaware of 'man' the utility.\n\n\n> When you clarify it this way, the change does not look as useful\n> anymore, does it?\n\nYes, it still does, I think. I doubt it's that obvious that 'git help'\nuses MANPATH at all. Besides, it's not 'git man', isn't it? To further\nemphasize my point, we don't require user to tweak MANPATH in order to\nget corresponding 'git --help' output, isn't it? Also, please look here:\n\n$ ~/git/bin/git help -a | head -n 3 | tail -n 1\navailable git commands in '/home/osv/git/bin'\n$ git help -a | head -n 3 | tail -n 1\ngit commands available in '/usr/bin'\n$\n\nAnd the last, basing on the same arguments, it's not that useful that\n'git xxx' invokes correct 'git-xxx' command by prepending installation\npath to the PATH, isn't it?\n\nOverall, I just want 'git help' to behave consistently.\n\n> How typical would that use be, to run your git executable by always\n> naming it by path without relying on $PATH environment variable?\n\nTo tell the truth, I'd prefer to just use -M option of man and don't\nrely on MANPATH at all, so that 'git help' will issue error if there is\nno documentation installed for this particular version of git.\n\n[BTW, git-help lacks his own man page, so I can't actually argue on a\nground of some documentation of git-help.]\n\n-- \nSergei.\n"},{"id":"62280","messageId":"47593EB2.3020309@op5.se","threadId":"11161","inReplyTo":"871w9y7mei.fsf@osv.gnss.ru","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2007-12-07T12:38:10Z","receivedAt":"2007-12-07T12:38:10Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Sergei Organov wrote:\n> Junio C Hamano writes:\n> \n >> Having written that, it is very tempting to further clarify the above:\n>>\n>> Usually, if a user has his own version of git and regularly uses it\n>> by having the non-system executable directory (e.g. $HOME/bin/git)\n>> early in his $PATH, its corresponding documentation would also be in\n>> a non-system documentation directory (e.g. $HOME/man) early in his\n>> $MANPATH, and this change is a no-op. The only case this change\n>> matters is where the user installs his own git outside of his $PATH\n>> and $MANPATH, and explicitly runs his git executable\n>> (e.g. \"$HOME/junk/git-1.5.4/bin/git diff\").\n> \n> First, I don't think you need to clarify like this. It is just\n> implementation detail of git-help that it uses 'man', and thus\n> implicitly relies on MANPATH. The essential thing has been already\n> stated above: git-help should show correct documentation.\n> \n> Second, the change is still useful even if user did put custom path to\n> 'git' into its PATH, but didn't even thought of customizing\n> MANPATH. Besides, a user could be entirely unaware of 'man' the utility.\n> \n\nThe number of users in the entire world that are completely unaware of\nthe 'man' utility but still manages to build git and install it in a\nnon-default path can probably be counted on one hand of a 65 year old\nsaw-mill worker.\n\nI'm not sure if we're doing them a greater service by DWIMing this or\nby telling them about the 'man' utility.\n\n> \n>> How typical would that use be, to run your git executable by always\n>> naming it by path without relying on $PATH environment variable?\n> \n> To tell the truth, I'd prefer to just use -M option of man and don't\n> rely on MANPATH at all, so that 'git help' will issue error if there is\n> no documentation installed for this particular version of git.\n> \n\nDoes \"man -M\" work everywhere, or is your patch opening a can of worms\nto get probably-not-needed functionality?\n\nOtoh, you submitted a patch, so there are probably a few people out\nthere that care about this. I'm not one of them, so I'll shut up now\nthat my lunch is over ;-)\n\n-- \nAndreas Ericsson andreas.ericsson@op5.se\nOP5 AB www.op5.se\nTel: +46 8-230225 Fax: +46 8-230231\n"},{"id":"62283","messageId":"87prxi6567.fsf@osv.gnss.ru","threadId":"11161","inReplyTo":"47593EB2.3020309@op5.se","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-12-07T12:49:20Z","receivedAt":"2007-12-07T12:49:20Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"Andreas Ericsson writes:\n> Sergei Organov wrote:\n[...]\n>> To tell the truth, I'd prefer to just use -M option of man and don't\n>> rely on MANPATH at all, so that 'git help' will issue error if there is\n>> no documentation installed for this particular version of git.\n>>\n>\n> Does \"man -M\" work everywhere, or is your patch opening a can of worms\n> to get probably-not-needed functionality?\n\nThis patch doesn't use \"man -M\", it tweaks MANPATH instead. Partly because\nthe rest of 'git' tweaks 'PATH' to get correct executable to be run, and\nnot run it using explicit absolute path, so tweaking MANPATH is\nconsistent with the rest of git.\n\n-- \nSergei.\n"},{"id":"62295","messageId":"20071207161919.GA25490@old.davidb.org","threadId":"11161","inReplyTo":"7vodd23i1v.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"David Brown","fromEmail":"git@davidb.org","sentAt":"2007-12-07T16:19:19Z","receivedAt":"2007-12-07T16:19:19Z","isPatch":true,"sender":{"key":"git@davidb.org","avatar":"https://gravatar.com/avatar/94c86a2938470a74c2eac5e2b69afc0871f79a660295c02219597aba8cb101c1?d=mp&s=160"},"body":"On Fri, Dec 07, 2007 at 02:39:24AM -0800, Junio C Hamano wrote:\n\n> Usually, if a user has his own version of git and regularly uses it\n> by having the non-system executable directory (e.g. $HOME/bin/git)\n> early in his $PATH, its corresponding documentation would also be in\n> a non-system documentation directory (e.g. $HOME/man) early in his\n> $MANPATH, and this change is a no-op. The only case this change\n> matters is where the user installs his own git outside of his $PATH\n> and $MANPATH, and explicitly runs his git executable\n> (e.g. \"$HOME/junk/git-1.5.4/bin/git diff\").\n>\n>When you clarify it this way, the change does not look as useful\n>anymore, does it? How typical would that use be, to run your git\n>executable by always naming it by path without relying on $PATH\n>environment variable?\n\nOr, git gets installed out of path in its own tree, and then the 'git'\nexecutable itself is symlinked somewhere into the path. I know this\nhappens, because this is what IT ended up doing.\n\nIt's also fairly easy to add a new executable path, and forget to add a new\nmanpath directory.\n\nDave\n"},{"id":"62296","messageId":"20071207162204.GB25490@old.davidb.org","threadId":"11161","inReplyTo":"20071207161919.GA25490@old.davidb.org","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"David Brown","fromEmail":"git@davidb.org","sentAt":"2007-12-07T16:22:04Z","receivedAt":"2007-12-07T16:22:04Z","isPatch":true,"sender":{"key":"git@davidb.org","avatar":"https://gravatar.com/avatar/94c86a2938470a74c2eac5e2b69afc0871f79a660295c02219597aba8cb101c1?d=mp&s=160"},"body":"On Fri, Dec 07, 2007 at 08:19:19AM -0800, David Brown wrote:\n\n> Or, git gets installed out of path in its own tree, and then the 'git'\n> executable itself is symlinked somewhere into the path. I know this\n> happens, because this is what IT ended up doing.\n\n This is what IT ended up doing, where I work.\n\nI haven't run into the problem this patch fixes because the strange\nout-of-path git is the only version of git available on the systems.\n\nDave\n"},{"id":"62307","messageId":"7vbq921eyc.fsf@gitster.siamese.dyndns.org","threadId":"11161","inReplyTo":"871w9y7mei.fsf@osv.gnss.ru","subject":"Re: [PATCH] Let git-help prefer man-pages installed with this version of git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-07T19:29:15Z","receivedAt":"2007-12-07T19:29:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergei Organov writes:\n\n> First, I don't think you need to clarify like this. It is just\n> implementation detail of git-help that it uses 'man', and thus\n> implicitly relies on MANPATH. The essential thing has been already\n> stated above: git-help should show correct documentation.\n\nOk, this is a good argument for the patch. With Christian's\nenhancements, we will handle -i(nfo) and -w(eb) and we will tell the\n\"info\" and \"html\" browsers where the documentation we installed for the\nrunning instance of git is, so we should do so consistently for\n\"manpage\" browser (aka \"man\"). You are right.\n"}]}