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

[PATCH v3 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 v3 2/3] Allow help.htmlpath to be a URL prefix

[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..92f2349 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 (!strstr(html_path, "://")) {
+		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

[PATCH v3 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 92f2349..0df5bbf 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

Re: [PATCH v3 2/3] Allow help.htmlpath to be a URL prefix

[Junio C Hamano]

Chris Webb <chris@arachsys.com> writes:

> 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..92f2349 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 (!strstr(html_path, "://")) {
> +		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);

Sounds sensible and looks reasonable.  Thanks.

I do not think [PATCH 3/3] is a positive change at all, though.

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

[Junio C Hamano]

Chris Webb <chris@arachsys.com> writes:

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

I'll queue after updating this to

	static const char *html_path;

as the return value of const char *system_path(GIT_HTML_PATH) is
assigned to it.

Re: [PATCH v3 2/3] Allow help.htmlpath to be a URL prefix

[Chris Webb]

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

> Sounds sensible and looks reasonable.  Thanks.

Great! Glad they were of interest.

> I do not think [PATCH 3/3] is a positive change at all, though.

Yes, I think my aversion for being thrown into the full manual with
git foo --help is quite unusual, so this one's probably better left
as one of my idiosyncratic local patches.

The reason I thought there was a chance this could be of wider interest is
that, on a machine without man pages,

  $ git show --help
  warning: failed to exec 'man': No such file or directory
  fatal: no man viewer handled the request

is a bit unfriendly when git actually has enough internal help to be able to
offer

  $ git show -h    
  usage: git log [<options>] [<since>..<until>] [[--] <path>...]
     or: git show [options] <object>...

...but only if you know that -h exists and is not a synonym for --help.

Cheers,

Chris.