A handful of help-related patches

A handful of help-related patches

[Chris Webb]

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.

[PATCH 1/3] Add config variable to set HTML path for git-help --web

[Chris Webb]

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.

Signed-off-by: Chris Webb <chris@arachsys.com>
---
 builtin/help.c |   11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/builtin/help.c b/builtin/help.c
index 8f9cd60..b467db2 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -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

[PATCH 2/3] Allow help.htmlpath to be an http: URL

[Chris Webb]

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.

Signed-off-by: Chris Webb <chris@arachsys.com>
---
 builtin/help.c |    8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/builtin/help.c b/builtin/help.c
index b467db2..60b3251 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -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

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Jeff King]

On Wed, Jun 27, 2012 at 09:55:13PM +0100, Chris Webb wrote:

> 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.

Nice.

>  	/* 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);
> +	}

I'd rather not tie this directly to http. Is there any reason not to
allow https, for example? Can we maybe just look for strstr("://")
instead? That's the same magic we use to differentiate URLs from paths
when looking for repositories.

-Peff

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Chris Webb]

Jeff King <peff@peff.net> writes:

> >  	/* 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);
> > +	}
> 
> I'd rather not tie this directly to http. Is there any reason not to
> allow https, for example? Can we maybe just look for strstr("://")
> instead? That's the same magic we use to differentiate URLs from paths
> when looking for repositories.

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.

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, Jun 27, 2012 at 09:55:13PM +0100, Chris Webb wrote:
>
>> 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.
>
> Nice.
>
>>  	/* 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);
>> +	}
>
> I'd rather not tie this directly to http. Is there any reason not to
> allow https, for example? Can we maybe just look for strstr("://")
> instead? That's the same magic we use to differentiate URLs from paths
> when looking for repositories.

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.

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Chris Webb]

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

> 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.

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Jeff King]

On Wed, Jun 27, 2012 at 02:32:49PM -0700, Junio C Hamano wrote:

> >>  	/* 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);
> >> +	}
> >
> > I'd rather not tie this directly to http. Is there any reason not to
> > allow https, for example? Can we maybe just look for strstr("://")
> > instead? That's the same magic we use to differentiate URLs from paths
> > when looking for repositories.
> 
> 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?"

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

> 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?"

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.

> 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.

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

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Chris Webb]

Jeff King <peff@peff.net> writes:

> 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.

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.

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Jeff King]

On Wed, Jun 27, 2012 at 11:19:39PM +0100, Chris Webb wrote:

> Jeff King <peff@peff.net> writes:
> 
> > 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.
> 
> 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 ://?

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

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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.

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

> 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.

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

Thanks.

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Chris Webb]

Jeff King <peff@peff.net> writes:

> On Wed, Jun 27, 2012 at 11:19:39PM +0100, Chris Webb wrote:
> 
> > 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 ://?
> 
> That just seems needlessly complex. Why not just check for "://" and be
> done?
[...]
> 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.

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

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

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.

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Jeff King]

On Thu, Jun 28, 2012 at 07:56:23AM +0100, Chris Webb wrote:

> > This, and "://", both sound sensible.
> 
> 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!

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

-Peff

Re: [PATCH 2/3] Allow help.htmlpath to be an http: URL

[Chris Webb]

Jeff King <peff@peff.net> writes:

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

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

Best wishes,

Chris.

[PATCH 3/3] Add a help format 'usage' to provide brief command usage

[Chris Webb]

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.

Signed-off-by: Chris Webb <chris@arachsys.com>
---
 builtin/help.c |   16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/builtin/help.c b/builtin/help.c
index 60b3251..d4c3f5d 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -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