A handful of help-related patches

Whilst looking at git-rebase, I noticed I have a few local git --help related patches from a couple of years ago that I use on my own systems.

I'm not sure whether they're just personal quirks, but I thought I should post them to the list in case they're of wider interest or might be relevant upstream.

The first two patches allow the HTML path used by git-help --web to be set in .gitconfig, and allow it to be a URL prefix, so you can do

[help]
format = html
htmlpath = http://git-scm.com/docs

git wibble --help will then open http://git-scm.com/docs/git-wibble.html
instead of /share/doc/git/html/git-wibble.html in your browser.

The third patch adds a help format called 'usage' making git wibble --help equivalent to git wibble -h, i.e. printing short command-line usage information. (Generally that's what I want and I end up rather surprised when I get an unwanted man page because my fingers are trained to type the more universal --help rather than -h.)

This 'usage' help format is also good for making --help do something useful other than produce an error message on our cut-down servers without man pages, web browsers and so on.

Best wishes,

Chris.

If set in git-config, help.htmlpath overrides system_path(GIT_HTML_PATH) which was compiled in. This allows users to repoint system-wide git at their own copy of the documentation without recompiling.

---
 builtin/help.c |   11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

index 8f9cd60..b467db2 100644
@@ -34,6 +34,8 @@ enum help_format {
 	HELP_FORMAT_WEB
 };
 
+static char *html_path = NULL;
+
 static int show_all = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;

@@ -265,6 +267,12 @@ static int git_help_config(const char *var, const char *value, void *cb)
 		help_format = parse_help_format(value);
 		return 0;
 	}
+	if (!strcmp(var, "help.htmlpath")) {
+		if (!value)
+			return config_error_nonbool(var);
+		html_path = xstrdup(value);
+		return 0;
+	}
 	if (!strcmp(var, "man.viewer")) {
 		if (!value)
 			return config_error_nonbool(var);

@@ -387,7 +395,8 @@ static void show_info_page(const char *git_cmd)
 static void get_html_page_path(struct strbuf *page_path, const char *page)
 {
 	struct stat st;
-	const char *html_path = system_path(GIT_HTML_PATH);
+	if (!html_path)
+		html_path = system_path(GIT_HTML_PATH);
 
 	/* Check that we have a git documentation directory. */
 	if (stat(mkpath("%s/git.html", html_path), &st)

1.7.10

Setting this to a URL prefix instead of a path to a local directory allows git-help --web to work even when HTML docs aren't locally installed, by pointing the browser at a copy accessible on the web. For example,

[help]
format = html
htmlpath = http://git-scm.com/docs

will use the publicly available documentation on the git homepage.

---
 builtin/help.c |    8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

index b467db2..60b3251 100644
@@ -399,9 +399,11 @@ static void get_html_page_path(struct strbuf *page_path, const char *page)
 		html_path = system_path(GIT_HTML_PATH);
 
 	/* Check that we have a git documentation directory. */
-	if (stat(mkpath("%s/git.html", html_path), &st)
-	    || !S_ISREG(st.st_mode))
-		die(_("'%s': not a documentation directory."), html_path);
+	if (prefixcmp(html_path, "http:")) {
+		if (stat(mkpath("%s/git.html", html_path), &st)
+				|| !S_ISREG(st.st_mode))
+			die("'%s': not a documentation directory.", html_path);
+	}
 
 	strbuf_init(page_path, 0);
 	strbuf_addf(page_path, "%s/%s.html", html_path, page);

1.7.10

Nice.

Thanks, that's a much better heuristic! I'll use !strstr(html_path, "://") in a re-roll. You're quite right, this ought to also allow https://, ftp://, etc.

Best wishes,

Chris.

One part of me says "any non-standard html-path should be sent to the browser". Another part of me says "what if network is unavailable? Wouldn't it be nice to fall back to use the local copy?"

And a small voice in me responds to the latter with "If you have a local copy anyway, why would you want to go to the network even if you could?"

Which leads me to conclude that it is the right thing to do if html_path came from the configuration, not from the compiled-in default, to always ask browser to do its thing, and let it fail if it has to fail---it is not Git's problem anymore at that point.

It also is the simplest.

Yes, indeed! Okay, I'll re-roll it that way and go for the super-simple approach.

Cheers,

Chris.

Fallback might be nice, but I really don't want to get into interpreting what URLs mean or whether the network is up.

One reason is that the network version may contain more information (for example, the git-scm.com versions give you links to related articles, and also tell you in which versions the documentation changed).

Speaking of versions, this patch is not sufficient to actually point the browser to the correct version at a site like git-scm.com. We could add some kind of strbuf_expand magic like "http://git-scm.com/%c/%v" or something like that (where %c is the command and %v is the git version). But that is probably over-engineering.

I don't know that configured vs compiled-in is the right distinction there, though. If I'm building a minimal git for a stripped-down machine and I don't want to include the HTML pages locally, I might want to set the html path to a URL at build-time. That saves each user from having to configure it.

-Peff

How about only testing for a git documentation directory if both help.htmlpath isn't set (so we're using the compiled-in version) and the compiled-in version doesn't contain ://?

Best wishes,

Chris.

That just seems needlessly complex. Why not just check for "://" and be done?

Let's take a step back for a moment. Why is that check even there? You can always just hand the path (or URL, or whatever) to the browser command and hope it can make sense of it. If it can't, it will give you an error.

I think the check is purely about being slightly nicer when there are no HTML docs at all (e.g., because you didn't bother building them, or your binary distribution didn't include them). If your browser is graphical, we'll spawn it with a bogus URL, and the error message will be in some window elsewhere on your desktop. Git will happily exit without a further message. By adding in that check, we can detect that situation and produce an error message immediately.

So one solution would be to simply remove the check entirely. It was a slight nicety in some situations, but expanding the definition of the HTML path to include full URLs means we can no longer accurately determine what exists and what does not. So we can just stop trying and let the browser handle it completely.

Another option would be to introduce a new "net" type of help format which accepts a URL instead of a path. That would leave the existing code-path untouched. But it does seem needlessly complex, as it would do more or less the same thing as the "html" format.

-Peff

This, and "://", both sound sensible.

Yeah, that does not sound like a good reason to have such a complex scheme.

Thanks.

[...]

I have no real preference between any of the suggestions so far: they'd all be completely fine with me. Peff's :// test for a URL is much better than my
http: prefix, so should replace the latter if we need a test at all, but apart from that I don't mind at all.

Okay, I'll re-send now the :// version I did in response to Peff's first email purely on the basis that it doesn't change the behaviour at all for existing users who don't set htmlpath at all, plus it's already sat in my reflog!

However, if you'd both prefer a version in which I just take the check out altogether, let me know and I'll spin that instead.

Cheers,

Chris.

I think the "://" one is my preference. I just looked over your v3 series, and the patches look good to me.

-Peff

Thanks, and thanks for suggesting the much nicer :// heuristic.

Best wishes,

Chris.

Configuring the new help.format = usage makes git foo --help exactly equivalent to git foo -h, displaying brief command-line usage info instead of full documentation in the form of a man/html page.

This is useful on stripped-down servers where man pages and viewer aren't present, or if your fingers are trained to type COMMAND --help instead of COMMAND -h to get usage info and the man page behaviour is disturbing.

---
 builtin/help.c |   16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

index 60b3251..d4c3f5d 100644
@@ -31,7 +31,8 @@ enum help_format {
 	HELP_FORMAT_NONE,
 	HELP_FORMAT_MAN,
 	HELP_FORMAT_INFO,
-	HELP_FORMAT_WEB
+	HELP_FORMAT_WEB,
+	HELP_FORMAT_USAGE
 };
 
 static char *html_path = NULL;

@@ -46,11 +47,12 @@ static struct option builtin_help_options[] = {
 			HELP_FORMAT_WEB),
 	OPT_SET_INT('i', "info", &help_format, "show info page",
 			HELP_FORMAT_INFO),
+	OPT_SET_INT('u', "usage", &help_format, "show usage", HELP_FORMAT_USAGE),
 	OPT_END(),
 };
 
 static const char * const builtin_help_usage[] = {
-	"git help [--all] [--man|--web|--info] [command]",
+	"git help [--all] [--man|--web|--info|--usage] [command]",
 	NULL
 };
 

@@ -62,6 +64,8 @@ static enum help_format parse_help_format(const char *format)
 		return HELP_FORMAT_INFO;
 	if (!strcmp(format, "web") || !strcmp(format, "html"))
 		return HELP_FORMAT_WEB;
+	if (!strcmp(format, "usage"))
+		return HELP_FORMAT_USAGE;
 	die(_("unrecognized help format '%s'"), format);
 }
 

@@ -431,6 +435,11 @@ static void show_html_page(const char *git_cmd)
 	open_html(page_path.buf);
 }
 
+static void show_usage(const char *git_cmd)
+{
+	execl_git_cmd(git_cmd, "-h", NULL);
+}
+
 int cmd_help(int argc, const char **argv, const char *prefix)
 {
 	int nongit;

@@ -482,6 +491,9 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 	case HELP_FORMAT_WEB:
 		show_html_page(argv[0]);
 		break;
+	case HELP_FORMAT_USAGE:
+		show_usage(argv[0]);
+		break;
 	}
 
 	return 0;

1.7.10