From e703d7118c68bb5b1f850dae4060609a88500b18 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 23 Mar 2014 15:58:12 -0700 Subject: parse-options: multi-word argh should use dash to separate words "When you need to use space, use dash" is a strange way to say that you must not use a space. Because it is more common for the command line descriptions to use dashed-multi-words, you do not even want to use spaces in these places. Rephrase the documentation to avoid this strangeness. Fix a few existing multi-word argument help strings, i.e. - GPG key-ids given to -S/--gpg-sign are "key-id"; - Refs used for storing notes are "notes-ref"; and - Expiry timestamps given to --expire are "expiry-date". and update the corresponding documentation pages. Signed-off-by: Junio C Hamano diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index f1e6b2f..1c03c79 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] - [-S[]] ... + [-S[]] ... 'git cherry-pick' --continue 'git cherry-pick' --quit 'git cherry-pick' --abort @@ -101,8 +101,8 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. --S[]:: ---gpg-sign[=]:: +-S[]:: +--gpg-sign[=]:: GPG-sign commits. --ff:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 7c42e9c..d58758f 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -13,7 +13,7 @@ SYNOPSIS [-F | -m ] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=] [--date=] [--cleanup=] [--[no-]status] - [-i | -o] [-S[]] [--] [...] + [-i | -o] [-S[]] [--] [...] DESCRIPTION ----------- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 4395459..a3c1fa3 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] - [-s ] [-X ] [-S[]] + [-s ] [-X ] [-S[]] [--[no-]rerere-autoupdate] [-m ] [...] 'git merge' HEAD ... 'git merge' --abort diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 84bb0fe..310f0a5 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -14,7 +14,7 @@ SYNOPSIS 'git notes' append [-F | -m | (-c | -C) ] [] 'git notes' edit [] 'git notes' show [] -'git notes' merge [-v | -q] [-s ] +'git notes' merge [-v | -q] [-s ] 'git notes' merge --commit [-v | -q] 'git notes' merge --abort [-v | -q] 'git notes' remove [--ignore-missing] [--stdin] [...] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index e05e6b3..c452f33 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -290,14 +290,14 @@ The lines after the separator describe the options. Each line of options has this format: ------------ -*? SP+ help LF +*? SP+ help LF ------------ -``:: +``:: its format is the short option character, then the long option name separated by a comma. Both parts are not required, though at least one is necessary. `h,help`, `dry-run` and `f` are all three correct - ``. + ``. ``:: `` are of `*`, `=`, `?` or `!`. @@ -313,11 +313,11 @@ Each line of options has this format: * Use `!` to not make the corresponding negated long option available. -``:: - ``, if specified, is used as a name of the argument in the - help output, for options that take arguments. `` is - terminated by the first whitespace. When you need to use space in the - argument hint use dash instead. +``:: + ``, if specified, is used as a name of the argument in the + help output, for options that take arguments. `` is + terminated by the first whitespace. It is customary to use a + dash to separate words in a multi-word argument hint. The remainder of the line, after stripping the spaces, is used as the help associated to the option. diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 9eb83f0..cceb5f2 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -8,7 +8,7 @@ git-revert - Revert some existing commits SYNOPSIS -------- [verse] -'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[]] ... +'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[]] ... 'git revert' --continue 'git revert' --quit 'git revert' --abort @@ -80,8 +80,8 @@ more details. This is useful when reverting more than one commits' effect to your index in a row. --S[]:: ---gpg-sign[=]:: +-S[]:: +--gpg-sign[=]:: GPG-sign commits. -s:: diff --git a/builtin/checkout.c b/builtin/checkout.c index ada51fa..a0e72d2 100644 --- a/builtin/checkout.c +++ b/builtin/checkout.c @@ -1095,7 +1095,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix) OPT_BOOL(0, "detach", &opts.force_detach, N_("detach the HEAD at named commit")), OPT_SET_INT('t', "track", &opts.track, N_("set upstream info for new branch"), BRANCH_TRACK_EXPLICIT), - OPT_STRING(0, "orphan", &opts.new_orphan_branch, N_("new branch"), N_("new unparented branch")), + OPT_STRING(0, "orphan", &opts.new_orphan_branch, N_("new-branch"), N_("new unparented branch")), OPT_SET_INT('2', "ours", &opts.writeout_stage, N_("checkout our version for unmerged files"), 2), OPT_SET_INT('3', "theirs", &opts.writeout_stage, N_("checkout their version for unmerged files"), diff --git a/builtin/commit.c b/builtin/commit.c index 3783bca..96bf762 100644 --- a/builtin/commit.c +++ b/builtin/commit.c @@ -1472,7 +1472,7 @@ int cmd_commit(int argc, const char **argv, const char *prefix) OPT_BOOL('e', "edit", &edit_flag, N_("force edit of commit")), OPT_STRING(0, "cleanup", &cleanup_arg, N_("default"), N_("how to strip spaces and #comments from message")), OPT_BOOL(0, "status", &include_status, N_("include status in commit message template")), - { OPTION_STRING, 'S', "gpg-sign", &sign_commit, N_("key id"), + { OPTION_STRING, 'S', "gpg-sign", &sign_commit, N_("key-id"), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, /* end commit message options */ diff --git a/builtin/merge.c b/builtin/merge.c index f0cf120..2a144e1 100644 --- a/builtin/merge.c +++ b/builtin/merge.c @@ -220,7 +220,7 @@ static struct option builtin_merge_options[] = { OPT_BOOL(0, "abort", &abort_current_merge, N_("abort the current in-progress merge")), OPT_SET_INT(0, "progress", &show_progress, N_("force progress reporting"), 1), - { OPTION_STRING, 'S', "gpg-sign", &sign_commit, N_("key id"), + { OPTION_STRING, 'S', "gpg-sign", &sign_commit, N_("key-id"), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, OPT_BOOL(0, "overwrite-ignore", &overwrite_ignore, N_("update ignored files (default)")), OPT_END() diff --git a/builtin/notes.c b/builtin/notes.c index bb89930..39c8573 100644 --- a/builtin/notes.c +++ b/builtin/notes.c @@ -939,7 +939,7 @@ int cmd_notes(int argc, const char **argv, const char *prefix) int result; const char *override_notes_ref = NULL; struct option options[] = { - OPT_STRING(0, "ref", &override_notes_ref, N_("notes_ref"), + OPT_STRING(0, "ref", &override_notes_ref, N_("notes-ref"), N_("use notes from ")), OPT_END() }; diff --git a/builtin/revert.c b/builtin/revert.c index 065d88d..f9ed5bd 100644 --- a/builtin/revert.c +++ b/builtin/revert.c @@ -89,7 +89,7 @@ static void parse_args(int argc, const char **argv, struct replay_opts *opts) OPT_STRING(0, "strategy", &opts->strategy, N_("strategy"), N_("merge strategy")), OPT_CALLBACK('X', "strategy-option", &opts, N_("option"), N_("option for merge strategy"), option_parse_x), - { OPTION_STRING, 'S', "gpg-sign", &opts->gpg_sign, N_("key id"), + { OPTION_STRING, 'S', "gpg-sign", &opts->gpg_sign, N_("key-id"), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, OPT_END(), OPT_END(), diff --git a/builtin/tag.c b/builtin/tag.c index 40356e3..6c7c6bd 100644 --- a/builtin/tag.c +++ b/builtin/tag.c @@ -513,7 +513,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix) OPT_BOOL('s', "sign", &opt.sign, N_("annotated and GPG-signed tag")), OPT_STRING(0, "cleanup", &cleanup_arg, N_("mode"), N_("how to strip spaces and #comments from message")), - OPT_STRING('u', "local-user", &keyid, N_("key id"), + OPT_STRING('u', "local-user", &keyid, N_("key-id"), N_("use another key to sign the tag")), OPT__FORCE(&force, N_("replace the tag if exists")), OPT_COLUMN(0, "column", &colopts, N_("show tag list in columns")), diff --git a/parse-options.h b/parse-options.h index d670cb9..8fa02dc 100644 --- a/parse-options.h +++ b/parse-options.h @@ -143,7 +143,7 @@ struct option { { OPTION_CALLBACK, (s), (l), (v), N_("time"),(h), 0, \ parse_opt_approxidate_cb } #define OPT_EXPIRY_DATE(s, l, v, h) \ - { OPTION_CALLBACK, (s), (l), (v), N_("expiry date"),(h), 0, \ + { OPTION_CALLBACK, (s), (l), (v), N_("expiry-date"),(h), 0, \ parse_opt_expiry_date_cb } #define OPT_CALLBACK(s, l, v, a, h, f) \ { OPTION_CALLBACK, (s), (l), (v), (a), (h), 0, (f) } -- cgit v0.10.2-6-g49f6 From ec160ae12b0ae938ed5076b9f604e88976fc429c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 23 Mar 2014 16:57:28 -0700 Subject: update-index: teach --cacheinfo a new syntax "mode,sha1,path" The "--cacheinfo" option is unusual in that it takes three option parameters. An option with an optional parameter is bad enough. An option with multiple parameters is simply insane. Introduce a new syntax that takes these three things concatenated together with a comma, which makes the command line syntax more uniform across subcommands, while retaining the traditional syntax for backward compatiblity. If we were designing the "update-index" subcommand from scratch today, it may probably have made sense to make this option (and possibly others) a command mode option that does not take any option parameter (hence no need for arg-help). But we do not live in such an ideal world, and as far as I can tell, the command still supports (and must support) mixed command modes in a single invocation, e.g. $ git update-index path1 --add path2 \ --cacheinfo 100644 $(git hash-object --stdin -w diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index e0a8702..d6de4a0 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git update-index' [--add] [--remove | --force-remove] [--replace] [--refresh] [-q] [--unmerged] [--ignore-missing] - [(--cacheinfo )...] + [(--cacheinfo ,,)...] [--chmod=(+|-)x] [--[no-]assume-unchanged] [--[no-]skip-worktree] @@ -68,8 +68,12 @@ OPTIONS --ignore-missing:: Ignores missing files during a --refresh +--cacheinfo ,,:: --cacheinfo :: - Directly insert the specified info into the index. + Directly insert the specified info into the index. For + backward compatibility, you can also give these three + arguments as three separate parameters, but new users are + encouraged to use a single-parameter form. --index-info:: Read index information from stdin. diff --git a/builtin/update-index.c b/builtin/update-index.c index d12ad95..ba54e19 100644 --- a/builtin/update-index.c +++ b/builtin/update-index.c @@ -629,14 +629,42 @@ static int resolve_undo_clear_callback(const struct option *opt, return 0; } +static int parse_new_style_cacheinfo(const char *arg, + unsigned int *mode, + unsigned char sha1[], + const char **path) +{ + unsigned long ul; + char *endp; + + errno = 0; + ul = strtoul(arg, &endp, 8); + if (errno || endp == arg || *endp != ',' || (unsigned int) ul != ul) + return -1; /* not a new-style cacheinfo */ + *mode = ul; + endp++; + if (get_sha1_hex(endp, sha1) || endp[40] != ',') + return -1; + *path = endp + 41; + return 0; +} + static int cacheinfo_callback(struct parse_opt_ctx_t *ctx, const struct option *opt, int unset) { unsigned char sha1[20]; unsigned int mode; + const char *path; + if (!parse_new_style_cacheinfo(ctx->argv[1], &mode, sha1, &path)) { + if (add_cacheinfo(mode, sha1, path, 0)) + die("git update-index: --cacheinfo cannot add %s", path); + ctx->argv++; + ctx->argc--; + return 0; + } if (ctx->argc <= 3) - return error("option 'cacheinfo' expects three arguments"); + return error("option 'cacheinfo' expects ,,"); if (strtoul_ui(*++ctx->argv, 8, &mode) || get_sha1_hex(*++ctx->argv, sha1) || add_cacheinfo(mode, sha1, *++ctx->argv, 0)) @@ -740,9 +768,9 @@ int cmd_update_index(int argc, const char **argv, const char *prefix) PARSE_OPT_NOARG | PARSE_OPT_NONEG, really_refresh_callback}, {OPTION_LOWLEVEL_CALLBACK, 0, "cacheinfo", NULL, - N_(" "), + N_(",,"), N_("add the specified entry to the index"), - PARSE_OPT_NOARG | /* disallow --cacheinfo= form */ + PARSE_OPT_NOARG | /* disallow --cacheinfo= form */ PARSE_OPT_NONEG | PARSE_OPT_LITERAL_ARGHELP, (parse_opt_cb *) cacheinfo_callback}, {OPTION_CALLBACK, 0, "chmod", &set_executable_bit, N_("(+/-)x"), diff --git a/t/t2107-update-index-basic.sh b/t/t2107-update-index-basic.sh index a6405d3..fe2fb17 100755 --- a/t/t2107-update-index-basic.sh +++ b/t/t2107-update-index-basic.sh @@ -48,4 +48,17 @@ test_expect_success '--cacheinfo does not accept gitlink null sha1' ' test_cmp expect actual ' +test_expect_success '--cacheinfo mode,sha1,path (new syntax)' ' + echo content >file && + git hash-object -w --stdin expect && + + git update-index --add --cacheinfo 100644 "$(cat expect)" file && + git rev-parse :file >actual && + test_cmp expect actual && + + git update-index --add --cacheinfo "100644,$(cat expect),elif" && + git rev-parse :elif >actual && + test_cmp expect actual +' + test_done -- cgit v0.10.2-6-g49f6 From b6c2a0d45d4165dfd326bd7a28e66d9cedb8ae84 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 23 Mar 2014 16:04:36 -0700 Subject: parse-options: make sure argh string does not have SP or _ We encourage to spell an argument hint that consists of multiple words as a single-token separated with dashes. In order to help catching violations added by new callers of parse-options, make sure argh does not contain SP or _ when the code validates the option definitions. Signed-off-by: Junio C Hamano diff --git a/parse-options.c b/parse-options.c index a5fa0b8..c81d3a0 100644 --- a/parse-options.c +++ b/parse-options.c @@ -375,6 +375,9 @@ static void parse_options_check(const struct option *opts) default: ; /* ok. (usually accepts an argument) */ } + if (opts->argh && + strcspn(opts->argh, " _") != strlen(opts->argh)) + err |= optbug(opts, "multi-word argh should use dash to separate words"); } if (err) exit(128); -- cgit v0.10.2-6-g49f6