Merge branch 'jn/help-everywhere'

* jn/help-everywhere: (23 commits)
  diff --no-index: make the usage string less scary
  merge-{recursive,subtree}: use usagef() to print usage
  Introduce usagef() that takes a printf-style format
  Let 'git <command> -h' show usage without a git dir
  Show usage string for 'git http-push -h'
  Let 'git http-fetch -h' show usage outside any git repository
  Show usage string for 'git stripspace -h'
  Show usage string for 'git unpack-file -h'
  Show usage string for 'git show-index -h'
  Show usage string for 'git rev-parse -h'
  Show usage string for 'git merge-one-file -h'
  Show usage string for 'git mailsplit -h'
  Show usage string for 'git imap-send -h'
  Show usage string for 'git get-tar-commit-id -h'
  Show usage string for 'git fast-import -h'
  Show usage string for 'git check-ref-format -h'
  http-fetch: add missing initialization of argv0_path
  Show usage string for 'git show-ref -h'
  Show usage string for 'git merge-ours -h'
  Show usage string for 'git commit-tree -h'
  ...

Conflicts:
	imap-send.c

Documentation/git-show-ref.txt

@@ -8,7 +8,7 @@ git-show-ref - List references in a local repository
 SYNOPSIS
 --------
 [verse]
-'git show-ref' [-q|--quiet] [--verify] [-h|--head] [-d|--dereference]
+'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]
 	     [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]
 	     [--heads] [--] <pattern>...
 'git show-ref' --exclude-existing[=<pattern>] < ref-list
@@ -30,7 +30,6 @@ the `.git` directory.
 OPTIONS
 -------
 
--h::
 --head::
 
 	Show the HEAD reference.

Makefile

@@ -602,7 +602,6 @@ BUILTIN_OBJS += builtin-diff-index.o
 BUILTIN_OBJS += builtin-diff-tree.o
 BUILTIN_OBJS += builtin-diff.o
 BUILTIN_OBJS += builtin-fast-export.o
-BUILTIN_OBJS += builtin-fetch--tool.o
 BUILTIN_OBJS += builtin-fetch-pack.o
 BUILTIN_OBJS += builtin-fetch.o
 BUILTIN_OBJS += builtin-fmt-merge-msg.o

builtin-check-ref-format.c

@@ -35,6 +35,9 @@ static void collapse_slashes(char *dst, const char *src)
 
 int cmd_check_ref_format(int argc, const char **argv, const char *prefix)
 {
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage(builtin_check_ref_format_usage);
+
 	if (argc == 3 && !strcmp(argv[1], "--branch")) {
 		struct strbuf sb = STRBUF_INIT;
 

builtin-commit-tree.c

@@ -105,7 +105,7 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)
 
 	git_config(git_default_config, NULL);
 
-	if (argc < 2)
+	if (argc < 2 || !strcmp(argv[1], "-h"))
 		usage(commit_tree_usage);
 	if (get_sha1(argv[1], tree_sha1))
 		die("Not a valid object name %s", argv[1]);

builtin-grep.c

@@ -788,6 +788,13 @@ int cmd_grep(int argc, const char **argv, const char *prefix)
 		OPT_END()
 	};
 
+	/*
+	 * 'git grep -h', unlike 'git grep -h <pattern>', is a request
+	 * to show usage information and exit.
+	 */
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage_with_options(grep_usage, options);
+
 	memset(&opt, 0, sizeof(opt));
 	opt.prefix = prefix;
 	opt.prefix_length = (prefix && *prefix) ? strlen(prefix) : 0;

builtin-log.c

@@ -50,6 +50,12 @@ static void cmd_log_init(int argc, const char **argv, const char *prefix,
 	if (default_date_mode)
 		rev->date_mode = parse_date_format(default_date_mode);
 
+	/*
+	 * Check for -h before setup_revisions(), or "git log -h" will
+	 * fail when run without a git directory.
+	 */
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage(builtin_log_usage);
 	argc = setup_revisions(argc, argv, rev, "HEAD");
 
 	if (rev->diffopt.pickaxe || rev->diffopt.filter)
@@ -1242,6 +1248,9 @@ int cmd_cherry(int argc, const char **argv, const char *prefix)
 		argv++;
 	}
 
+	if (argc > 1 && !strcmp(argv[1], "-h"))
+		usage(cherry_usage);
+
 	switch (argc) {
 	case 4:
 		limit = argv[3];

builtin-mailsplit.c

@@ -231,6 +231,8 @@ int cmd_mailsplit(int argc, const char **argv, const char *prefix)
 			continue;
 		} else if ( arg[1] == 'f' ) {
 			nr = strtol(arg+2, NULL, 10);
+		} else if ( arg[1] == 'h' ) {
+			usage(git_mailsplit_usage);
 		} else if ( arg[1] == 'b' && !arg[2] ) {
 			allow_bare = 1;
 		} else if (!strcmp(arg, "--keep-cr")) {

builtin-merge-ours.c

@@ -10,6 +10,9 @@
 #include "git-compat-util.h"
 #include "builtin.h"
 
+static const char builtin_merge_ours_usage[] =
+	"git merge-ours <base>... -- HEAD <remote>...";
+
 static const char *diff_index_args[] = {
 	"diff-index", "--quiet", "--cached", "HEAD", "--", NULL
 };
@@ -17,6 +20,9 @@ static const char *diff_index_args[] = {
 
 int cmd_merge_ours(int argc, const char **argv, const char *prefix)
 {
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage(builtin_merge_ours_usage);
+
 	/*
 	 * We need to exit with 2 if the index does not match our HEAD tree,
 	 * because the current index is what we will be committing as the

builtin-merge-recursive.c

@@ -33,7 +33,7 @@ int cmd_merge_recursive(int argc, const char **argv, const char *prefix)
 	}
 
 	if (argc < 4)
-		die("Usage: %s <base>... -- <head> <remote> ...", argv[0]);
+		usagef("%s <base>... -- <head> <remote> ...", argv[0]);
 
 	for (i = 1; i < argc; ++i) {
 		if (!strcmp(argv[i], "--"))

builtin-mv.c

@@ -64,15 +64,15 @@ int cmd_mv(int argc, const char **argv, const char *prefix)
 
 	git_config(git_default_config, NULL);
 
-	newfd = hold_locked_index(&lock_file, 1);
-	if (read_cache() < 0)
-		die("index file corrupt");
-
 	argc = parse_options(argc, argv, prefix, builtin_mv_options,
 			     builtin_mv_usage, 0);
 	if (--argc < 1)
 		usage_with_options(builtin_mv_usage, builtin_mv_options);
 
+	newfd = hold_locked_index(&lock_file, 1);
+	if (read_cache() < 0)
+		die("index file corrupt");
+
 	source = copy_pathspec(prefix, argv, argc, 0);
 	modes = xcalloc(argc, sizeof(enum update_mode));
 	dest_path = copy_pathspec(prefix, argv + argc, 1, 0);

builtin-read-tree.c

@@ -108,11 +108,11 @@ int cmd_read_tree(int argc, const char **argv, const char *unused_prefix)
 
 	git_config(git_default_config, NULL);
 
-	newfd = hold_locked_index(&lock_file, 1);
-
 	argc = parse_options(argc, argv, unused_prefix, read_tree_options,
 			     read_tree_usage, 0);
 
+	newfd = hold_locked_index(&lock_file, 1);
+
 	prefix_set = opts.prefix ? 1 : 0;
 	if (1 < opts.merge + opts.reset + prefix_set)
 		die("Which one? -m, --reset, or --prefix?");

builtin-reflog.c

@@ -698,6 +698,9 @@ static const char reflog_usage[] =
 
 int cmd_reflog(int argc, const char **argv, const char *prefix)
 {
+	if (argc > 1 && !strcmp(argv[1], "-h"))
+		usage(reflog_usage);
+
 	/* With no command, we default to showing it. */
 	if (argc < 2 || *argv[1] == '-')
 		return cmd_log_reflog(argc, argv, prefix);

builtin-rerere.c

@@ -106,6 +106,9 @@ int cmd_rerere(int argc, const char **argv, const char *prefix)
 	if (argc < 2)
 		return rerere();
 
+	if (!strcmp(argv[1], "-h"))
+		usage(git_rerere_usage);
+
 	fd = setup_rerere(&merge_rr);
 	if (fd < 0)
 		return 0;

builtin-rev-parse.c

@@ -432,6 +432,13 @@ static void die_no_single_rev(int quiet)
 		die("Needed a single revision");
 }
 
+static const char builtin_rev_parse_usage[] =
+"git rev-parse --parseopt [options] -- [<args>...]\n"
+"   or: git rev-parse --sq-quote [<arg>...]\n"
+"   or: git rev-parse [options] [<arg>...]\n"
+"\n"
+"Run \"git rev-parse --parseopt -h\" for more information on the first usage.";
+
 int cmd_rev_parse(int argc, const char **argv, const char *prefix)
 {
 	int i, as_is = 0, verify = 0, quiet = 0, revs_count = 0, type = 0;
@@ -444,6 +451,9 @@ int cmd_rev_parse(int argc, const char **argv, const char *prefix)
 	if (argc > 1 && !strcmp("--sq-quote", argv[1]))
 		return cmd_sq_quote(argc - 2, argv + 2);
 
+	if (argc > 1 && !strcmp("-h", argv[1]))
+		usage(builtin_rev_parse_usage);
+
 	prefix = setup_git_directory();
 	git_config(git_default_config, NULL);
 	for (i = 1; i < argc; i++) {

builtin-show-ref.c

@@ -7,7 +7,7 @@
 #include "parse-options.h"
 
 static const char * const show_ref_usage[] = {
-	"git show-ref [-q|--quiet] [--verify] [-h|--head] [-d|--dereference] [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [pattern*] ",
+	"git show-ref [-q|--quiet] [--verify] [--head] [-d|--dereference] [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [pattern*] ",
 	"git show-ref --exclude-existing[=pattern] < ref-list",
 	NULL
 };
@@ -183,7 +183,10 @@ static const struct option show_ref_options[] = {
 	OPT_BOOLEAN(0, "heads", &heads_only, "only show heads (can be combined with tags)"),
 	OPT_BOOLEAN(0, "verify", &verify, "stricter reference checking, "
 		    "requires exact ref path"),
-	OPT_BOOLEAN('h', "head", &show_head, "show the HEAD reference"),
+	{ OPTION_BOOLEAN, 'h', NULL, &show_head, NULL,
+	  "show the HEAD reference",
+	  PARSE_OPT_NOARG | PARSE_OPT_HIDDEN },
+	OPT_BOOLEAN(0, "head", &show_head, "show the HEAD reference"),
 	OPT_BOOLEAN('d', "dereference", &deref_tags,
 		    "dereference tags into object IDs"),
 	{ OPTION_CALLBACK, 's', "hash", &abbrev, "n",
@@ -201,6 +204,9 @@ static const struct option show_ref_options[] = {
 
 int cmd_show_ref(int argc, const char **argv, const char *prefix)
 {
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage_with_options(show_ref_usage, show_ref_options);
+
 	argc = parse_options(argc, argv, prefix, show_ref_options,
 			     show_ref_usage, PARSE_OPT_NO_INTERNAL_HELP);
 

builtin-stripspace.c

@@ -73,9 +73,11 @@ int cmd_stripspace(int argc, const char **argv, const char *prefix)
 	struct strbuf buf = STRBUF_INIT;
 	int strip_comments = 0;
 
-	if (argc > 1 && (!strcmp(argv[1], "-s") ||
+	if (argc == 2 && (!strcmp(argv[1], "-s") ||
 				!strcmp(argv[1], "--strip-comments")))
 		strip_comments = 1;
+	else if (argc > 1)
+		usage("git stripspace [-s | --strip-comments] < <stream>");
 
 	if (strbuf_read(&buf, 0, 1024) < 0)
 		die_errno("could not read the input");

builtin-tar-tree.c

@@ -11,6 +11,9 @@ static const char tar_tree_usage[] =
 "git tar-tree [--remote=<repo>] <tree-ish> [basedir]\n"
 "*** Note that this command is now deprecated; use \"git archive\" instead.";
 
+static const char builtin_get_tar_commit_id_usage[] =
+"git get-tar-commit-id < <tarfile>";
+
 int cmd_tar_tree(int argc, const char **argv, const char *prefix)
 {
 	/*
@@ -81,6 +84,9 @@ int cmd_get_tar_commit_id(int argc, const char **argv, const char *prefix)
 	char *content = buffer + RECORDSIZE;
 	ssize_t n;
 
+	if (argc != 1)
+		usage(builtin_get_tar_commit_id_usage);
+
 	n = read_in_full(0, buffer, HEADERSIZE);
 	if (n < HEADERSIZE)
 		die("git get-tar-commit-id: read error");

builtin.h

@@ -48,7 +48,6 @@ extern int cmd_diff_tree(int argc, const char **argv, const char *prefix);
 extern int cmd_fast_export(int argc, const char **argv, const char *prefix);
 extern int cmd_fetch(int argc, const char **argv, const char *prefix);
 extern int cmd_fetch_pack(int argc, const char **argv, const char *prefix);
-extern int cmd_fetch__tool(int argc, const char **argv, const char *prefix);
 extern int cmd_fmt_merge_msg(int argc, const char **argv, const char *prefix);
 extern int cmd_for_each_ref(int argc, const char **argv, const char *prefix);
 extern int cmd_format_patch(int argc, const char **argv, const char *prefix);

diff-no-index.c

@@ -201,8 +201,8 @@ void diff_no_index(struct rev_info *revs,
 			return;
 	}
 	if (argc != i + 2)
-		die("git diff %s takes two paths",
+		usagef("git diff %s <path> <path>",
-		    no_index ? "--no-index" : "[--no-index]");
+		       no_index ? "--no-index" : "[--no-index]");
 
 	diff_setup(&revs->diffopt);
 	for (i = 1; i < argc - 2; ) {

fast-import.c

@@ -2405,6 +2405,9 @@ int main(int argc, const char **argv)
 
 	git_extract_argv0_path(argv[0]);
 
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage(fast_import_usage);
+
 	setup_git_directory();
 	git_config(git_pack_config, NULL);
 	if (!pack_compression_seen && core_compression_seen)

git-compat-util.h

@@ -189,6 +189,7 @@ extern char *gitbasename(char *);
 
 /* General helper functions */
 extern NORETURN void usage(const char *err);
+extern NORETURN void usagef(const char *err, ...) __attribute__((format (printf, 1, 2)));
 extern NORETURN void die(const char *err, ...) __attribute__((format (printf, 1, 2)));
 extern NORETURN void die_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));
 extern int error(const char *err, ...) __attribute__((format (printf, 1, 2)));

git-merge-one-file.sh

@@ -16,6 +16,18 @@
 # been handled already by git read-tree, but that one doesn't
 # do any merges that might change the tree layout.
 
+USAGE='<orig blob> <our blob> <their blob> <path>'
+USAGE="$USAGE <orig mode> <our mode> <their mode>"
+LONG_USAGE="Usage: git merge-one-file $USAGE
+
+Blob ids and modes should be empty for missing files."
+
+if ! test "$#" -eq 7
+then
+	echo "$LONG_USAGE"
+	exit 1
+fi
+
 case "${1:-.}${2:-.}${3:-.}" in
 #
 # Deleted in both or deleted in one and unchanged in the other

git.c

@@ -229,21 +229,24 @@ struct cmd_struct {
 
 static int run_builtin(struct cmd_struct *p, int argc, const char **argv)
 {
-	int status;
+	int status, help;
 	struct stat st;
 	const char *prefix;
 
 	prefix = NULL;
-	if (p->option & RUN_SETUP)
+	help = argc == 2 && !strcmp(argv[1], "-h");
-		prefix = setup_git_directory();
+	if (!help) {
+		if (p->option & RUN_SETUP)
+			prefix = setup_git_directory();
 
-	if (use_pager == -1 && p->option & RUN_SETUP)
+		if (use_pager == -1 && p->option & RUN_SETUP)
-		use_pager = check_pager_config(p->cmd);
+			use_pager = check_pager_config(p->cmd);
-	if (use_pager == -1 && p->option & USE_PAGER)
+		if (use_pager == -1 && p->option & USE_PAGER)
-		use_pager = 1;
+			use_pager = 1;
+	}
 	commit_pager_choice();
 
-	if (p->option & NEED_WORK_TREE)
+	if (!help && p->option & NEED_WORK_TREE)
 		setup_work_tree();
 
 	trace_argv_printf(argv, "trace: built-in: git");
@@ -304,7 +307,6 @@ static void handle_internal_command(int argc, const char **argv)
 		{ "fast-export", cmd_fast_export, RUN_SETUP },
 		{ "fetch", cmd_fetch, RUN_SETUP },
 		{ "fetch-pack", cmd_fetch_pack, RUN_SETUP },
-		{ "fetch--tool", cmd_fetch__tool, RUN_SETUP },
 		{ "fmt-merge-msg", cmd_fmt_merge_msg, RUN_SETUP },
 		{ "for-each-ref", cmd_for_each_ref, RUN_SETUP },
 		{ "format-patch", cmd_format_patch, RUN_SETUP },

http-fetch.c

@@ -1,6 +1,10 @@
 #include "cache.h"
+#include "exec_cmd.h"
 #include "walker.h"
 
+static const char http_fetch_usage[] = "git http-fetch "
+"[-c] [-t] [-a] [-v] [--recover] [-w ref] [--stdin] commit-id url";
+
 int main(int argc, const char **argv)
 {
 	const char *prefix;
@@ -19,9 +23,7 @@ int main(int argc, const char **argv)
 	int get_verbosely = 0;
 	int get_recover = 0;
 
-	prefix = setup_git_directory();
+	git_extract_argv0_path(argv[0]);
-
-	git_config(git_default_config, NULL);
 
 	while (arg < argc && argv[arg][0] == '-') {
 		if (argv[arg][1] == 't') {
@@ -37,6 +39,8 @@ int main(int argc, const char **argv)
 		} else if (argv[arg][1] == 'w') {
 			write_ref = &argv[arg + 1];
 			arg++;
+		} else if (argv[arg][1] == 'h') {
+			usage(http_fetch_usage);
 		} else if (!strcmp(argv[arg], "--recover")) {
 			get_recover = 1;
 		} else if (!strcmp(argv[arg], "--stdin")) {
@@ -44,10 +48,8 @@ int main(int argc, const char **argv)
 		}
 		arg++;
 	}
-	if (argc < arg + 2 - commits_on_stdin) {
+	if (argc != arg + 2 - commits_on_stdin)
-		usage("git http-fetch [-c] [-t] [-a] [-v] [--recover] [-w ref] [--stdin] commit-id url");
+		usage(http_fetch_usage);
-		return 1;
-	}
 	if (commits_on_stdin) {
 		commits = walker_targets_stdin(&commit_id, &write_ref);
 	} else {
@@ -55,6 +57,11 @@ int main(int argc, const char **argv)
 		commits = 1;
 	}
 	url = argv[arg];
+
+	prefix = setup_git_directory();
+
+	git_config(git_default_config, NULL);
+
 	if (url && url[strlen(url)-1] != '/') {
 		rewritten_url = xmalloc(strlen(url)+2);
 		strcpy(rewritten_url, url);

http-push.c

@@ -1792,8 +1792,6 @@ int main(int argc, char **argv)
 
 	git_extract_argv0_path(argv[0]);
 
-	setup_git_directory();
-
 	repo = xcalloc(sizeof(*repo), 1);
 
 	argv++;
@@ -1827,6 +1825,8 @@ int main(int argc, char **argv)
 				force_delete = 1;
 				continue;
 			}
+			if (!strcmp(arg, "-h"))
+				usage(http_push_usage);
 		}
 		if (!repo->url) {
 			char *path = strstr(arg, "//");
@@ -1854,6 +1854,8 @@ int main(int argc, char **argv)
 	if (delete_branch && nr_refspec != 1)
 		die("You must specify only one branch name when deleting a remote branch");
 
+	setup_git_directory();
+
 	memset(remote_dir_exists, -1, 256);
 
 	/*

imap-send.c

@@ -94,6 +94,8 @@ struct msg_data {
 	unsigned int crlf:1;
 };
 
+static const char imap_send_usage[] = "git imap-send < <mbox>";
+
 #undef DRV_OK
 #define DRV_OK          0
 #define DRV_MSG_BAD     -1
@@ -1370,6 +1372,9 @@ int main(int argc, char **argv)
 
 	git_extract_argv0_path(argv[0]);
 
+	if (argc != 1)
+		usage(imap_send_usage);
+
 	setup_git_directory_gently(&nongit_ok);
 	git_config(git_imap_config, NULL);
 

index-pack.c

@@ -882,6 +882,9 @@ int main(int argc, char **argv)
 
 	git_extract_argv0_path(argv[0]);
 
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage(index_pack_usage);
+
 	/*
 	 * We wish to read the repository's config file if any, and
 	 * for that it is necessary to call setup_git_directory_gently().

pack-redundant.c

@@ -603,6 +603,9 @@ int main(int argc, char **argv)
 
 	git_extract_argv0_path(argv[0]);
 
+	if (argc == 2 && !strcmp(argv[1], "-h"))
+		usage(pack_redundant_usage);
+
 	setup_git_directory();
 
 	for (i = 1; i < argc; i++) {

show-index.c

@@ -1,6 +1,9 @@
 #include "cache.h"
 #include "pack.h"
 
+static const char show_index_usage[] =
+"git show-index < <packed archive index>";
+
 int main(int argc, char **argv)
 {
 	int i;
@@ -8,6 +11,8 @@ int main(int argc, char **argv)
 	unsigned int version;
 	static unsigned int top_index[256];
 
+	if (argc != 1)
+		usage(show_index_usage);
 	if (fread(top_index, 2 * 4, 1, stdin) != 1)
 		die("unable to read header");
 	if (top_index[0] == htonl(PACK_IDX_SIGNATURE)) {

unpack-file.c

@@ -28,7 +28,7 @@ int main(int argc, char **argv)
 
 	git_extract_argv0_path(argv[0]);
 
-	if (argc != 2)
+	if (argc != 2 || !strcmp(argv[1], "-h"))
 		usage("git unpack-file <sha1>");
 	if (get_sha1(argv[1], sha1))
 		die("Not a valid object name %s", argv[1]);

usage.c

@@ -12,9 +12,9 @@ static void report(const char *prefix, const char *err, va_list params)
 	fprintf(stderr, "%s%s\n", prefix, msg);
 }
 
-static NORETURN void usage_builtin(const char *err)
+static NORETURN void usage_builtin(const char *err, va_list params)
 {
-	fprintf(stderr, "usage: %s\n", err);
+	report("usage: ", err, params);
 	exit(129);
 }
 
@@ -36,7 +36,7 @@ static void warn_builtin(const char *warn, va_list params)
 
 /* If we are in a dlopen()ed .so write to a global variable would segfault
  * (ugh), so keep things static. */
-static NORETURN_PTR void (*usage_routine)(const char *err) = usage_builtin;
+static NORETURN_PTR void (*usage_routine)(const char *err, va_list params) = usage_builtin;
 static NORETURN_PTR void (*die_routine)(const char *err, va_list params) = die_builtin;
 static void (*error_routine)(const char *err, va_list params) = error_builtin;
 static void (*warn_routine)(const char *err, va_list params) = warn_builtin;
@@ -46,9 +46,18 @@ void set_die_routine(NORETURN_PTR void (*routine)(const char *err, va_list param
 	die_routine = routine;
 }
 
+void usagef(const char *err, ...)
+{
+	va_list params;
+
+	va_start(params, err);
+	usage_routine(err, params);
+	va_end(params);
+}
+
 void usage(const char *err)
 {
-	usage_routine(err);
+	usagef("%s", err);
 }
 
 void die(const char *err, ...)