Skip to content

Commit 9c9b4f2

Browse files
alexhenriegitster
alexhenrie
authored and
gitster
committed
standardize usage info string format
This patch puts the usage info strings that were not already in docopt- like format into docopt-like format, which will be a litle easier for end users and a lot easier for translators. Changes include: - Placing angle brackets around fill-in-the-blank parameters - Putting dashes in multiword parameter names - Adding spaces to [-f|--foobar] to make [-f | --foobar] - Replacing <foobar>* with [<foobar>...] Signed-off-by: Alex Henrie <[email protected]> Reviewed-by: Matthieu Moy <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent addfb21 commit 9c9b4f2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+109
-105
lines changed

‎Documentation/CodingGuidelines

+6-2
Original file line numberDiff line numberDiff line change
@@ -441,6 +441,10 @@ Writing Documentation:
441441
--sort=<key>
442442
--abbrev[=<n>]
443443

444+
If a placeholder has multiple words, they are separated by dashes:
445+
<new-branch-name>
446+
--template=<template-directory>
447+
444448
Possibility of multiple occurrences is indicated by three dots:
445449
<file>...
446450
(One or more of <file>.)
@@ -457,12 +461,12 @@ Writing Documentation:
457461
(Zero or more of <patch>. Note that the dots are inside, not
458462
outside the brackets.)
459463

460-
Multiple alternatives are indicated with vertical bar:
464+
Multiple alternatives are indicated with vertical bars:
461465
[-q | --quiet]
462466
[--utf8 | --no-utf8]
463467

464468
Parentheses are used for grouping:
465-
[(<rev>|<range>)...]
469+
[(<rev> | <range>)...]
466470
(Any number of either <rev> or <range>. Parens are needed to make
467471
it clear that "..." pertains to both <rev> and <range>.)
468472

‎advice.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ void detach_advice(const char *new_name)
105105
"state without impacting any branches by performing another checkout.\n\n"
106106
"If you want to create a new branch to retain commits you create, you may\n"
107107
"do so (now or later) by using -b with the checkout command again. Example:\n\n"
108-
" git checkout -b new_branch_name\n\n";
108+
" git checkout -b <new-branch-name>\n\n";
109109

110110
fprintf(stderr, fmt, new_name);
111111
}

‎archive.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88
#include "dir.h"
99

1010
static char const * const archive_usage[] = {
11-
N_("git archive [options] <tree-ish> [<path>...]"),
11+
N_("git archive [<options>] <tree-ish> [<path>...]"),
1212
N_("git archive --list"),
13-
N_("git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]"),
13+
N_("git archive --remote <repo> [--exec <cmd>] [<options>] <tree-ish> [<path>...]"),
1414
N_("git archive --remote <repo> [--exec <cmd>] --list"),
1515
NULL
1616
};

‎builtin/add.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
#include "argv-array.h"
2020

2121
static const char * const builtin_add_usage[] = {
22-
N_("git add [options] [--] <pathspec>..."),
22+
N_("git add [<options>] [--] <pathspec>..."),
2323
NULL
2424
};
2525
static int patch_interactive, add_interactive, edit_interactive;

‎builtin/apply.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ static const char *fake_ancestor;
5555
static int line_termination = '\n';
5656
static unsigned int p_context = UINT_MAX;
5757
static const char * const apply_usage[] = {
58-
N_("git apply [options] [<patch>...]"),
58+
N_("git apply [<options>] [<patch>...]"),
5959
NULL
6060
};
6161

‎builtin/blame.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,12 @@
2727
#include "line-range.h"
2828
#include "line-log.h"
2929

30-
static char blame_usage[] = N_("git blame [options] [rev-opts] [rev] [--] file");
30+
static char blame_usage[] = N_("git blame [<options>] [<rev-opts>] [<rev>] [--] file");
3131

3232
static const char *blame_opt_usage[] = {
3333
blame_usage,
3434
"",
35-
N_("[rev-opts] are documented in git-rev-list(1)"),
35+
N_("<rev-opts> are documented in git-rev-list(1)"),
3636
NULL
3737
};
3838

‎builtin/branch.c

+4-4
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@
2121
#include "wt-status.h"
2222

2323
static const char * const builtin_branch_usage[] = {
24-
N_("git branch [options] [-r | -a] [--merged | --no-merged]"),
25-
N_("git branch [options] [-l] [-f] <branchname> [<start-point>]"),
26-
N_("git branch [options] [-r] (-d | -D) <branchname>..."),
27-
N_("git branch [options] (-m | -M) [<oldbranch>] <newbranch>"),
24+
N_("git branch [<options>] [-r | -a] [--merged | --no-merged]"),
25+
N_("git branch [<options>] [-l] [-f] <branch-name> [<start-point>]"),
26+
N_("git branch [<options>] [-r] (-d | -D) <branch-name>..."),
27+
N_("git branch [<options>] (-m | -M) [<old-branch>] <new-branch>"),
2828
NULL
2929
};
3030

‎builtin/cat-file.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -329,8 +329,8 @@ static int batch_objects(struct batch_options *opt)
329329
}
330330

331331
static const char * const cat_file_usage[] = {
332-
N_("git cat-file (-t|-s|-e|-p|<type>|--textconv) <object>"),
333-
N_("git cat-file (--batch|--batch-check) < <list_of_objects>"),
332+
N_("git cat-file (-t | -s | -e | -p | <type> | --textconv) <object>"),
333+
N_("git cat-file (--batch | --batch-check) < <list-of-objects>"),
334334
NULL
335335
};
336336

‎builtin/check-attr.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ static int all_attrs;
88
static int cached_attrs;
99
static int stdin_paths;
1010
static const char * const check_attr_usage[] = {
11-
N_("git check-attr [-a | --all | attr...] [--] pathname..."),
12-
N_("git check-attr --stdin [-z] [-a | --all | attr...] < <list-of-paths>"),
11+
N_("git check-attr [-a | --all | <attr>...] [--] <pathname>..."),
12+
N_("git check-attr --stdin [-z] [-a | --all | <attr>...] < <list-of-paths>"),
1313
NULL
1414
};
1515

‎builtin/check-ignore.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77

88
static int quiet, verbose, stdin_paths, show_non_matching, no_index;
99
static const char * const check_ignore_usage[] = {
10-
"git check-ignore [options] pathname...",
11-
"git check-ignore [options] --stdin < <list-of-paths>",
10+
"git check-ignore [<options>] <pathname>...",
11+
"git check-ignore [<options>] --stdin < <list-of-paths>",
1212
NULL
1313
};
1414

‎builtin/check-mailmap.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
static int use_stdin;
77
static const char * const check_mailmap_usage[] = {
8-
N_("git check-mailmap [options] <contact>..."),
8+
N_("git check-mailmap [<options>] <contact>..."),
99
NULL
1010
};
1111

‎builtin/check-ref-format.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
#include "strbuf.h"
99

1010
static const char builtin_check_ref_format_usage[] =
11-
"git check-ref-format [--normalize] [options] <refname>\n"
11+
"git check-ref-format [--normalize] [<options>] <refname>\n"
1212
" or: git check-ref-format --branch <branchname-shorthand>";
1313

1414
/*

‎builtin/checkout-index.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ static void checkout_all(const char *prefix, int prefix_length)
123123
}
124124

125125
static const char * const builtin_checkout_index_usage[] = {
126-
N_("git checkout-index [options] [--] [<file>...]"),
126+
N_("git checkout-index [<options>] [--] [<file>...]"),
127127
NULL
128128
};
129129

‎builtin/checkout.c

+4-4
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@
2222
#include "argv-array.h"
2323

2424
static const char * const checkout_usage[] = {
25-
N_("git checkout [options] <branch>"),
26-
N_("git checkout [options] [<branch>] -- <file>..."),
25+
N_("git checkout [<options>] <branch>"),
26+
N_("git checkout [<options>] [<branch>] -- <file>..."),
2727
NULL,
2828
};
2929

@@ -746,7 +746,7 @@ static void suggest_reattach(struct commit *commit, struct rev_info *revs)
746746
_(
747747
"If you want to keep them by creating a new branch, "
748748
"this may be a good time\nto do so with:\n\n"
749-
" git branch new_branch_name %s\n\n"),
749+
" git branch <new-branch-name> %s\n\n"),
750750
find_unique_abbrev(commit->object.sha1, DEFAULT_ABBREV));
751751
}
752752

@@ -1127,7 +1127,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
11271127
OPT_BOOL(0, "ignore-skip-worktree-bits", &opts.ignore_skipworktree,
11281128
N_("do not limit pathspecs to sparse entries only")),
11291129
OPT_HIDDEN_BOOL(0, "guess", &dwim_new_local_branch,
1130-
N_("second guess 'git checkout no-such-branch'")),
1130+
N_("second guess 'git checkout <no-such-branch>'")),
11311131
OPT_END(),
11321132
};
11331133

‎builtin/clone.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
*
3535
*/
3636
static const char * const builtin_clone_usage[] = {
37-
N_("git clone [options] [--] <repo> [<dir>]"),
37+
N_("git clone [<options>] [--] <repo> [<dir>]"),
3838
NULL
3939
};
4040

‎builtin/column.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
#include "column.h"
77

88
static const char * const builtin_column_usage[] = {
9-
N_("git column [options]"),
9+
N_("git column [<options>]"),
1010
NULL
1111
};
1212
static unsigned int colopts;

‎builtin/commit.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,12 @@
3434
#include "mailmap.h"
3535

3636
static const char * const builtin_commit_usage[] = {
37-
N_("git commit [options] [--] <pathspec>..."),
37+
N_("git commit [<options>] [--] <pathspec>..."),
3838
NULL
3939
};
4040

4141
static const char * const builtin_status_usage[] = {
42-
N_("git status [options] [--] <pathspec>..."),
42+
N_("git status [<options>] [--] <pathspec>..."),
4343
NULL
4444
};
4545

‎builtin/config.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
#include "urlmatch.h"
66

77
static const char *const builtin_config_usage[] = {
8-
N_("git config [options]"),
8+
N_("git config [<options>]"),
99
NULL
1010
};
1111

‎builtin/describe.c

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@
1414
#define MAX_TAGS (FLAG_BITS - 1)
1515

1616
static const char * const describe_usage[] = {
17-
N_("git describe [options] <commit-ish>*"),
18-
N_("git describe [options] --dirty"),
17+
N_("git describe [<options>] [<commit-ish>...]"),
18+
N_("git describe [<options>] --dirty"),
1919
NULL
2020
};
2121

‎builtin/diff-files.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
#include "submodule.h"
1212

1313
static const char diff_files_usage[] =
14-
"git diff-files [-q] [-0/-1/2/3 |-c|--cc] [<common diff options>] [<path>...]"
14+
"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]"
1515
COMMON_DIFF_OPTIONS_HELP;
1616

1717
int cmd_diff_files(int argc, const char **argv, const char *prefix)

‎builtin/diff-index.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
static const char diff_cache_usage[] =
99
"git diff-index [-m] [--cached] "
10-
"[<common diff options>] <tree-ish> [<path>...]"
10+
"[<common-diff-options>] <tree-ish> [<path>...]"
1111
COMMON_DIFF_OPTIONS_HELP;
1212

1313
int cmd_diff_index(int argc, const char **argv, const char *prefix)

‎builtin/diff-tree.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ static int diff_tree_stdin(char *line)
8282

8383
static const char diff_tree_usage[] =
8484
"git diff-tree [--stdin] [-m] [-c] [--cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
85-
"[<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\n"
85+
"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
8686
" -r diff recursively\n"
8787
" --root include the initial commit as diff against /dev/null\n"
8888
COMMON_DIFF_OPTIONS_HELP;

‎builtin/fetch-pack.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
#include "sha1-array.h"
77

88
static const char fetch_pack_usage[] =
9-
"git fetch-pack [--all] [--stdin] [--quiet|-q] [--keep|-k] [--thin] "
9+
"git fetch-pack [--all] [--stdin] [--quiet | -q] [--keep | -k] [--thin] "
1010
"[--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] "
1111
"[--no-progress] [--diag-url] [-v] [<host>:]<directory> [<refs>...]";
1212

‎builtin/fmt-merge-msg.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
#include "gpg-interface.h"
1111

1212
static const char * const fmt_merge_msg_usage[] = {
13-
N_("git fmt-merge-msg [-m <message>] [--log[=<n>]|--no-log] [--file <file>]"),
13+
N_("git fmt-merge-msg [-m <message>] [--log[=<n>] | --no-log] [--file <file>]"),
1414
NULL
1515
};
1616

‎builtin/for-each-ref.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -1054,7 +1054,7 @@ static int opt_parse_sort(const struct option *opt, const char *arg, int unset)
10541054
}
10551055

10561056
static char const * const for_each_ref_usage[] = {
1057-
N_("git for-each-ref [options] [<pattern>]"),
1057+
N_("git for-each-ref [<options>] [<pattern>]"),
10581058
NULL
10591059
};
10601060

‎builtin/fsck.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -600,7 +600,7 @@ static int fsck_cache_tree(struct cache_tree *it)
600600
}
601601

602602
static char const * const fsck_usage[] = {
603-
N_("git fsck [options] [<object>...]"),
603+
N_("git fsck [<options>] [<object>...]"),
604604
NULL
605605
};
606606

‎builtin/gc.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
#define FAILED_RUN "failed to run %s"
2222

2323
static const char * const builtin_gc_usage[] = {
24-
N_("git gc [options]"),
24+
N_("git gc [<options>]"),
2525
NULL
2626
};
2727

‎builtin/grep.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
#include "pathspec.h"
2121

2222
static char const * const grep_usage[] = {
23-
N_("git grep [options] [-e] <pattern> [<rev>...] [[--] <path>...]"),
23+
N_("git grep [<options>] [-e] <pattern> [<rev>...] [[--] <path>...]"),
2424
NULL
2525
};
2626

‎builtin/hash-object.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
7979
int cmd_hash_object(int argc, const char **argv, const char *prefix)
8080
{
8181
static const char * const hash_object_usage[] = {
82-
N_("git hash-object [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>..."),
82+
N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
8383
N_("git hash-object --stdin-paths < <list-of-paths>"),
8484
NULL
8585
};

‎builtin/help.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ static struct option builtin_help_options[] = {
4949
};
5050

5151
static const char * const builtin_help_usage[] = {
52-
N_("git help [--all] [--guides] [--man|--web|--info] [command]"),
52+
N_("git help [--all] [--guides] [--man | --web | --info] [<command>]"),
5353
NULL
5454
};
5555

‎builtin/init-db.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -472,7 +472,7 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
472472
}
473473

474474
static const char *const init_db_usage[] = {
475-
N_("git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [directory]"),
475+
N_("git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]"),
476476
NULL
477477
};
478478

‎builtin/log.c

+3-3
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@ static const char *fmt_patch_subject_prefix = "PATCH";
3838
static const char *fmt_pretty;
3939

4040
static const char * const builtin_log_usage[] = {
41-
N_("git log [<options>] [<revision range>] [[--] <path>...]\n")
42-
N_(" or: git show [options] <object>..."),
41+
N_("git log [<options>] [<revision-range>] [[--] <path>...]\n")
42+
N_(" or: git show [<options>] <object>..."),
4343
NULL
4444
};
4545

@@ -1023,7 +1023,7 @@ static const char *set_outdir(const char *prefix, const char *output_directory)
10231023
}
10241024

10251025
static const char * const builtin_format_patch_usage[] = {
1026-
N_("git format-patch [options] [<since> | <revision range>]"),
1026+
N_("git format-patch [<options>] [<since> | <revision-range>]"),
10271027
NULL
10281028
};
10291029

‎builtin/ls-files.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -398,7 +398,7 @@ int report_path_error(const char *ps_matched,
398398
}
399399

400400
static const char * const ls_files_usage[] = {
401-
N_("git ls-files [options] [<file>...]"),
401+
N_("git ls-files [<options>] [<file>...]"),
402402
NULL
403403
};
404404

‎builtin/ls-remote.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
static const char ls_remote_usage[] =
77
"git ls-remote [--heads] [--tags] [-u <exec> | --upload-pack <exec>]\n"
8-
" [-q|--quiet] [--exit-code] [--get-url] [<repository> [<refs>...]]";
8+
" [-q | --quiet] [--exit-code] [--get-url] [<repository> [<refs>...]]";
99

1010
/*
1111
* Is there one among the list of patterns that match the tail part

‎builtin/mailinfo.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -1031,7 +1031,7 @@ static int git_mailinfo_config(const char *var, const char *value, void *unused)
10311031
}
10321032

10331033
static const char mailinfo_usage[] =
1034-
"git mailinfo [-k|-b] [-m | --message-id] [-u | --encoding=<encoding> | -n] [--scissors | --no-scissors] msg patch < mail >info";
1034+
"git mailinfo [-k | -b] [-m | --message-id] [-u | --encoding=<encoding> | -n] [--scissors | --no-scissors] <msg> <patch> < mail >info";
10351035

10361036
int cmd_mailinfo(int argc, const char **argv, const char *prefix)
10371037
{

0 commit comments

Comments
 (0)