Unify argument and option notation in the docs

---
 builtin/pack-objects.c |   16 ++++------------
 1 files changed, 4 insertions(+), 12 deletions(-)

builtin/pack-objects.c +4 ~~-12~~

index 3756cf3..6ab2878 100644
@@ -896,13 +896,9 @@ static int check_pbase_path(unsigned hash)
 	if (0 <= pos)
 		return 1;
 	pos = -pos - 1;
-	if (done_pbase_paths_alloc <= done_pbase_paths_num) {
-		done_pbase_paths_alloc = alloc_nr(done_pbase_paths_alloc);
-		done_pbase_paths = xrealloc(done_pbase_paths,
-					    done_pbase_paths_alloc *
-					    sizeof(unsigned));
-	}
-	done_pbase_paths_num++;
+	ALLOC_GROW(done_pbase_paths,
+		   ++done_pbase_paths_num,
+		   done_pbase_paths_alloc);
 	if (pos < done_pbase_paths_num)
 		memmove(done_pbase_paths + pos + 1,
 			done_pbase_paths + pos,

@@ -2248,11 +2244,7 @@ int cmd_pack_objects(int argc, const char **argv, const char *prefix)
 		    !strcmp("--reflog", arg) ||
 		    !strcmp("--all", arg)) {
 			use_internal_rev_list = 1;
-			if (rp_ac >= rp_ac_alloc - 1) {
-				rp_ac_alloc = alloc_nr(rp_ac_alloc);
-				rp_av = xrealloc(rp_av,
-						 rp_ac_alloc * sizeof(*rp_av));
-			}
+			ALLOC_GROW(rp_av, rp_ac + 2, rp_ac_alloc);
 			rp_av[rp_ac++] = arg;
 			continue;
 		}

Signature · 1 line

1.7.2.3

Jonathan Nieder

2016-06-15 22:49 UTC #2 lore raw

cover pack-objects: use ALLOC_GROW in place of manual growth

builtin/pack-objects.c static int check_pbase_path(unsigned hash) · line 901

Quoted 4 lines · Jonathan Nieder

builtin/pack-objects.c +3 -1

-	done_pbase_paths_num++;
+	ALLOC_GROW(done_pbase_paths,
+		   ++done_pbase_paths_num,
+		   done_pbase_paths_alloc);

Junio noticed that this makes done_pbase_paths_num grow by 3 rather than by 1 as intended. Sorry.

Patch 1 corrects some documentation that could lead one astray. Patch 2 is a corrected patch that uses ALLOC_GROW correctly (I hope).

Jonathan Nieder (2):
Documentation: No argument of ALLOC_GROW cannot have side-effects
pack-objects: use ALLOC_GROW

 builtin/pack-objects.c |   15 ++++-----------
 cache.h                |    2 +-
 2 files changed, 5 insertions(+), 12 deletions(-)

Signature · 1 line

1.7.2.3

Jonathan Nieder

2016-06-15 22:49 UTC #3 lore raw

PATCH 1/2 Documentation: No argument of ALLOC_GROW should have side-effects

The explanatory comment before the definition of ALLOC_GROW carefully lists arguments that will be used more than once and thus cannot have side-effects; a lazy reader might conclude that the arguments not listed are used only once and side effects safe.

Correct it to list all three arguments, avoiding this confusion.

In reply to Jonathan Nieder

---
 cache.h |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

cache.h +1 -1

index 2ef2fa3..23d6d45 100644
@@ -438,7 +438,7 @@ extern int init_db(const char *template_dir, unsigned int flags);
  * at least 'nr' entries; the number of entries currently allocated
  * is 'alloc', using the standard growing factor alloc_nr() macro.
  *
- * DO NOT USE any expression with side-effect for 'x' or 'alloc'.
+ * DO NOT USE any expression with side-effect for 'x', 'nr', or 'alloc'.
  */
 #define ALLOC_GROW(x, nr, alloc) \
 	do { \

Signature · 1 line

1.7.2.3

Jonathan Nieder

2016-06-15 22:49 UTC #4 lore raw

PATCH 2/2 pack-objects: use ALLOC_GROW

No functional change intended.

In reply to Jonathan Nieder

---
 builtin/pack-objects.c |   15 ++++-----------
 1 files changed, 4 insertions(+), 11 deletions(-)

builtin/pack-objects.c +4 ~~-11~~

index 3756cf3..60b792d 100644
@@ -896,12 +896,9 @@ static int check_pbase_path(unsigned hash)
 	if (0 <= pos)
 		return 1;
 	pos = -pos - 1;
-	if (done_pbase_paths_alloc <= done_pbase_paths_num) {
-		done_pbase_paths_alloc = alloc_nr(done_pbase_paths_alloc);
-		done_pbase_paths = xrealloc(done_pbase_paths,
-					    done_pbase_paths_alloc *
-					    sizeof(unsigned));
-	}
+	ALLOC_GROW(done_pbase_paths,
+		   done_pbase_paths_num + 1,
+		   done_pbase_paths_alloc);
 	done_pbase_paths_num++;
 	if (pos < done_pbase_paths_num)
 		memmove(done_pbase_paths + pos + 1,

@@ -2248,11 +2245,7 @@ int cmd_pack_objects(int argc, const char **argv, const char *prefix)
 		    !strcmp("--reflog", arg) ||
 		    !strcmp("--all", arg)) {
 			use_internal_rev_list = 1;
-			if (rp_ac >= rp_ac_alloc - 1) {
-				rp_ac_alloc = alloc_nr(rp_ac_alloc);
-				rp_av = xrealloc(rp_av,
-						 rp_ac_alloc * sizeof(*rp_av));
-			}
+			ALLOC_GROW(rp_av, rp_ac + 2, rp_ac_alloc);
 			rp_av[rp_ac++] = arg;
 			continue;
 		}

Signature · 1 line

1.7.2.3

Jonathan Nieder

2016-06-15 22:49 UTC #5 lore raw

[PATCH 3/2] Allow side-effects in second argument to ALLOC_GROW

One might be tempted to try

	ALLOC_GROW(ary, ++nr, alloc);

to increase the size of an array by one, and if one tries, the compiler will happily accept it. Unfortunately ALLOC_GROW evaluates its argument at least twice, so the results are generally not what the caller wanted.

Luckily, it is simple enough to do what the caller meant by storing the value of the second argument in a temporary.

The first and third arguments still need to be side-effect-free. The name of the temporary is nr_ to avoid conflicting with variables the caller might use in the expansion of ary, nr, or alloc.

In reply to Jonathan Nieder

---
 cache.h |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

cache.h +5 -4

index 23d6d45..5c9e338 100644
@@ -438,13 +438,14 @@ extern int init_db(const char *template_dir, unsigned int flags);
  * at least 'nr' entries; the number of entries currently allocated
  * is 'alloc', using the standard growing factor alloc_nr() macro.
  *
- * DO NOT USE any expression with side-effect for 'x', 'nr', or 'alloc'.
+ * DO NOT USE any expression with side-effect for 'x' or 'alloc'.
  */
 #define ALLOC_GROW(x, nr, alloc) \
 	do { \
-		if ((nr) > alloc) { \
-			if (alloc_nr(alloc) < (nr)) \
-				alloc = (nr); \
+		const size_t nr_ = (nr); \
+		if (nr_ > (alloc)) { \
+			if (alloc_nr(alloc) < nr_) \
+				alloc = nr_; \
 			else \
 				alloc = alloc_nr(alloc); \
 			x = xrealloc((x), alloc * sizeof(*(x))); \

Signature · 1 line

1.7.2.3

Štěpán Němec

author

2016-06-15 22:49 UTC #6 lore raw

Quoted 8 lines · Jonathan Nieder

Quoted 3 lines · Štěpán Němec
[It is conceivable I could submit this as a series of smaller patches, but the problems this is solving didn't seem diverse enough to me to warrant that.
Since the documentation processor is known to be, um, picky, could you do that? That way after bisecting a formatting problem, one has a diff addressing a single issue to look at.

OK. Another reason I didn't do that is that my patch actually does not introduce any mark-up not already present in the sources, so it shouldn't introduce any new breakage AFAICT.

Quoted 11 lines

On the other hand, I am happy enough to comment on a single, monolithic patch on list if you publish the smaller patches making it up in a git repository somewhere.
Quoted 4 lines
1. Is [--refs [--unpacked | --all]]' in git-pack-object' documentation correct? From my reading of builtin/pack-objects.c, --unpacked' and --all' do the same thing and both imply --refs, so perhaps [--refs | --unpacked | --all] would make more sense?
Doesn't the OPTIONS section explain what --revs, --unpacked, and --all mean?

It does, but IMO it contradicts the synopsis. Doesn't the fact that --unpacked and --all _imply_ --rev mean that you don't need to supply the latter if you already gave one of the former two? That's also what I understood from looking at pack-objects.c. So neither [--revs [(--unpacked|--all)...]] nor [--revs [--unpacked|--all]] seem correct to me.

I also don't see why you would want to supply --unpacked or --all multiple times, so `...' would be definitely wrong, no?

Quoted 4 lines

Quoted 2 lines
(I also noticed that the
--reflog option is shown in the usage string but undocumented.)
Looks like someone forgot to add it to the man page.

OK. I'll leave that to someone who knows what the option is supposed to do; it's a matter for a separate patch anyway.

Quoted 6 lines

Quoted 2 lines
2. I left in one special case, namely the GIT_* variables in git(1)' synopsis section as values for the --exec-path' and other options.
Hmm, --exec-path=GIT_EXEC_PATH currently serves as a reminder of the name of the corresponding environment variable, but I don't think that's very important. --exec-path[=<path>] should be fine.

Yes, that's my opinion as well, thanks for confirmation. I'll include it in the next round.

Štěpán

Štěpán Němec

2016-06-15 22:49 UTC #7 lore raw

cover Unify argument and option notation in the docs

Other than splitting up the patch, the only change since the RFC version is having got rid of the GIT_* special cases in `git(1)' synopsis.

[PATCH 1/6] Use angles for placeholders consistently
[PATCH 2/6] Fix odd markup in --diff-filter documentation
[PATCH 3/6] Use parentheses and `...' where appropriate
[PATCH 4/6] Remove stray quotes in --pretty and --format documentation [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string [PATCH 6/6] Fix {update,checkout}-index usage strings

Jonathan Nieder

Acked-by on the v1 series

2016-06-15 22:49 UTC #8 lore raw

Quoted 6 lines · Štěpán Němec

[PATCH 1/6] Use angles for placeholders consistently
[PATCH 2/6] Fix odd markup in --diff-filter documentation
[PATCH 3/6] Use parentheses and `...' where appropriate
[PATCH 4/6] Remove stray quotes in --pretty and --format documentation [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string [PATCH 6/6] Fix {update,checkout}-index usage strings

All these seem like improvements to me. So:

Acked-by Jonathan Nieder <[email protected]>

Thanks.

Junio C Hamano

2016-06-15 22:49 UTC #9 lore raw

I had to fix up the whitespace damage in the rerolled 2/6 but otherwise looked good.

Thanks, both. It might make sense to outline the rules applied somewhere in CodingGuidelines to help people who add to our documents. Something along the lines of...

- A placeholder is spelled inside angle brackets, e.g. <file>, <object>.

- Choosing one from many is written with possible choices separated with a vertical bar and the whole thing enclosed in parentheses, e.g. answer=(yes|no|true|false)

- Repetition of zero or more times of X is spelled as [(X)...], e.g. [(-p <parent>)...]

Štěpán Němec

author

2016-06-15 22:49 UTC #10 lore raw

Quoted 2 lines · Junio C Hamano

I had to fix up the whitespace damage in the rerolled 2/6 but otherwise looked good.

Yeah, sorry for that. Obviously the tabs got replaced by spaces when I copy-pasted the hunk and I didn't notice.

Quoted 4 lines

Thanks, both. It might make sense to outline the rules applied somewhere in CodingGuidelines to help people who add to our documents. Something along the lines of...

Quoted 8 lines

- A placeholder is spelled inside angle brackets, e.g. <file>, <object>.
- Choosing one from many is written with possible choices separated with a vertical bar and the whole thing enclosed in parentheses, e.g. answer=(yes|no|true|false)
- Repetition of zero or more times of X is spelled as [(X)...], e.g. [(-p <parent>)...]

:-) I was actually considering just that, so I'm glad you mention it.

I can try to compile an initial version of such a document, based on the commit message of the original single-patch version
(<http://article.gmane.org/gmane.comp.version-control.git/158467>) and including some more cases/examples.

Where do you think would be the most appropriate place for it? Just add a section to CodingGuidelines, or a separate Documentation/WritingGuidelines or something?

Štěpán

Jonathan Nieder

2016-06-15 22:49 UTC #11 lore raw

Quoted 10 lines · Štěpán Němec

:-) I was actually considering just that, so I'm glad you mention it.
I can try to compile an initial version of such a document, based on the commit message of the original single-patch version
(<http://article.gmane.org/gmane.comp.version-control.git/158467>) and including some more cases/examples.
Where do you think would be the most appropriate place for it? Just add a section to CodingGuidelines, or a separate Documentation/WritingGuidelines or something?

Sorry for the slow response. Documentation/CodingGuidelines makes sense to me, since it affects the usage strings in code.

Štěpán Němec

author

2016-06-15 22:49 UTC #12 lore raw

PATCH 1/1 CodingGuidelines: Add a section on writing documentation

Provide a few examples on argument and option notation in usage strings and command synopses.

---

Quoted 1 line · Jonathan Nieder

Štěpán Němec wrote:

[...]

Quoted 11 lines

Quoted 8 lines
I can try to compile an initial version of such a document, based on the commit message of the original single-patch version
(<http://article.gmane.org/gmane.comp.version-control.git/158467>) and including some more cases/examples.
Where do you think would be the most appropriate place for it? Just add a section to CodingGuidelines, or a separate Documentation/WritingGuidelines or something?
Sorry for the slow response. Documentation/CodingGuidelines makes sense to me, since it affects the usage strings in code.

Thanks, here's a patch.

 Documentation/CodingGuidelines |   53 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 53 insertions(+), 0 deletions(-)

Documentation/CodingGuidelines +53 -0

index 09ffc46..0ac7aac 100644
@@ -139,3 +139,56 @@ For C programs:
 
  - When we pass <string, length> pair to functions, we should try to
    pass them in that order.
+
+Writing Documentation:
+
+ Every user-visible change should be reflected in the documentation.
+ The same general rule as for code applies -- imitate the existing
+ conventions.  A few commented examples follow to provide reference
+ when writing or modifying command usage strings and synopsis sections
+ in the manual pages:
+
+ Placeholders are enclosed in angle brackets:
+   <file>
+   --sort=<key>
+   --abbrev[=<n>]
+
+ Possibility of multiple occurences is indicated by three dots:
+   <file>...
+   (One or more of <file>.)
+
+ Optional parts are enclosed in square brackets:
+   [<extra>]
+   (Zero or one <extra>.)
+
+   --exec-path[=<path>]
+   (Option with an optional argument.  Note that the "=" is inside the
+   brackets.)
+
+   [<patch>...]
+   (Zero or more of <patch>.  Note that the dots are inside, not
+   outside the brackets.)
+
+ Parentheses are used for grouping, often combined with vertical bar
+ to indicate alternatives:
+   [(<rev>|<range>)...]
+   (Any number of either <rev> or <range>.  Parens are needed to make
+   it clear that "..." pertains to both <rev> and <range>.)
+
+   [(-p <parent>)...]
+   (Any number of option -p, each with one <parent> argument.)
+
+   git remote set-head <name> (-a | -d | <branch>)
+   (One and only one of "-a", "-d" or "<branch>" _must_ (no square
+   brackets) be provided.)
+
+ Specific number of occurences is indicated as follows:
+   <commit>{0,2}
+   (Up to two <commit>s.)
+
+ And a somewhat more contrived example:
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
+   Here "=" is outside the brackets, because "--diff-filter=" is a
+   valid usage.  "*" has its own pair of brackets, because it can
+   (optionally) be specified only when one or more of the letters is
+   also provided.

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Mark Lodato

2016-06-15 22:49 UTC #13 lore raw

Re: [PATCH] CodingGuidelines: Add a section on writing documentation

Quoted 2 lines · Štěpán Němec

Provide a few examples on argument and option notation in usage strings and command synopses.

I think this is a great idea.

Documentation/CodingGuidelines For C programs: · line 187

Quoted 3 lines

+ Specific number of occurences is indicated as follows:
Documentation/CodingGuidelines +2 -0
+   <commit>{0,2}
+   (Up to two <commit>s.)

I suggest removing this notation - it is confusing and is only used by git-diff.txt and git-difftool.txt. We already have notation to serve this purpose:

    [<commit> [<commit>]]

Documentation/CodingGuidelines For C programs: · line 176

Quoted 5 lines

+ Parentheses are used for grouping, often combined with vertical bar
+ to indicate alternatives:
Documentation/CodingGuidelines +3 -0
+   [(<rev>|<range>)...]
+   (Any number of either <rev> or <range>.  Parens are needed to make
+   it clear that "..." pertains to both <rev> and <range>.)

You could also mention that parentheses are not needed if square brackets will do:

    [-q | --quiet]

Also, should there be a standard for spacing and for whether the short or the long option comes first?

git-add.txt:

    [--patch | -p]
git-commit.txt:
    [-a | --interactive]
git-stash.txt:
    [-q|--quiet]

Otherwise, I think this patch looks good.

Štěpán Němec

author

2016-06-15 22:49 UTC #14 lore raw

Re: [PATCH] CodingGuidelines: Add a section on writing documentation

Quoted 10 lines · Mark Lodato

Documentation/CodingGuidelines For C programs: · line 187
Quoted 3 lines · Štěpán Němec
+ Specific number of occurences is indicated as follows:
Documentation/CodingGuidelines +2 -0
+   <commit>{0,2}
+   (Up to two <commit>s.)
I suggest removing this notation - it is confusing and is only used by git-diff.txt and git-difftool.txt. We already have notation to serve this purpose:
    [<commit> [<commit>]]

Yeah, it's kind of an oddball, although I don't really find it confusing. I guess it might be useful in cases where you have a bigger number of "things", say 4 or more, where the brackets could get unwieldy.

But given that it's only used as {0,2} at the two places right now (disregarding occurences of "0{40}" in the documentation), I agree it might be better to get rid of it, although I don't feel strongly about it. Any other opinions?

Quoted 9 lines

Documentation/CodingGuidelines For C programs: · line 176
Quoted 5 lines
+ Parentheses are used for grouping, often combined with vertical bar
+ to indicate alternatives:
Documentation/CodingGuidelines +3 -0
+   [(<rev>|<range>)...]
+   (Any number of either <rev> or <range>.  Parens are needed to make
+   it clear that "..." pertains to both <rev> and <range>.)
You could also mention that parentheses are not needed if square brackets will do:
    [-q | --quiet]

Good point, will do.

Quoted 9 lines

Also, should there be a standard for spacing and for whether the short or the long option comes first?
git-add.txt:
    [--patch | -p]
git-commit.txt:
    [-a | --interactive]
git-stash.txt:
    [-q|--quiet]

I thought about this already when preparing the recent unification series, and came to the conclusion "no, there shouldn't". :-) As the examples you give show, the current usage is inconsistent, but given that it brings no semantic ambiguity, I don't think it is a problem. You could find more similar cosmetic inconsistencies and I don't think it makes much sense to mandate any rules for such things. (But again, I don't feel _too_ strongly about this either, so if more people think it's worth it, I can prepare a patch that unifies them and mention the preference in CodingGuidelines.)

Quoted 1 line

Otherwise, I think this patch looks good.

Thank you for the feedback!

Štěpán

Sverre Rabbelier

2016-06-15 22:49 UTC #15 lore raw

Re: [PATCH] CodingGuidelines: Add a section on writing documentation

Heya,

Quoted 4 lines · Štěpán Němec

But given that it's only used as {0,2} at the two places right now (disregarding occurences of "0{40}" in the documentation), I agree it might be better to get rid of it, although I don't feel strongly about it. Any other opinions?

Let's get rid of it for now, we can always resurrect it later if we have a need for it.

Quoted 9 lines

I thought about this already when preparing the recent unification series, and came to the conclusion "no, there shouldn't". :-) As the examples you give show, the current usage is inconsistent, but given that it brings no semantic ambiguity, I don't think it is a problem. You could find more similar cosmetic inconsistencies and I don't think it makes much sense to mandate any rules for such things. (But again, I don't feel _too_ strongly about this either, so if more people think it's worth it, I can prepare a patch that unifies them and mention the preference in CodingGuidelines.)

Perhaps we can set a standard to do it, but just leave the existing cases as is (to prevent unneeded churn)? That way we'll eventually converge on something.

Signature · 3 lines

Cheers,

Sverre Rabbelier

Štěpán Němec

author

2016-06-15 22:49 UTC #16 lore raw

Re: [PATCH] CodingGuidelines: Add a section on writing documentation

Quoted 10 lines · Sverre Rabbelier

Heya,
Quoted 4 lines · Štěpán Němec
But given that it's only used as {0,2} at the two places right now (disregarding occurences of "0{40}" in the documentation), I agree it might be better to get rid of it, although I don't feel strongly about it. Any other opinions?
Let's get rid of it for now, we can always resurrect it later if we have a need for it.

OK.

Quoted 10 lines

Quoted 9 lines
I thought about this already when preparing the recent unification series, and came to the conclusion "no, there shouldn't". :-) As the examples you give show, the current usage is inconsistent, but given that it brings no semantic ambiguity, I don't think it is a problem. You could find more similar cosmetic inconsistencies and I don't think it makes much sense to mandate any rules for such things. (But again, I don't feel _too_ strongly about this either, so if more people think it's worth it, I can prepare a patch that unifies them and mention the preference in CodingGuidelines.)

Quoted 3 lines

Perhaps we can set a standard to do it, but just leave the existing cases as is (to prevent unneeded churn)? That way we'll eventually converge on something.

Hm... that seems like the worst solution to me -- if we do end up standardizing this after all, any occurence of non-standard usage would be a bug that needs fixing (think about it from the POV of a new contributor who reads CodingGuidelines but sees the actual usage being different).

I guess it wouldn't be so much of a code churn to unify the spacing, but I'm still not convinced we should be enforcing this kind of thing.

Štěpán

Štěpán Němec

author

2016-06-15 22:49 UTC #17 lore raw

PATCH 1/1 diff,difftool: Don't use the {0,2} notation in usage strings

This was the only occurence of that usage, and square brackets are sufficient and already well-established for that purpose.

[1]
http://thread.gmane.org/gmane.comp.version-control.git/158467/focus=160330

---

As per discussion upthread, this notation is not worth keeping; hence not mentioning it in the v2 of the CodingGuidlines patch and this removal.

 Documentation/git-diff.txt     |    2 +-
 Documentation/git-difftool.txt |    2 +-
 builtin/diff.c                 |    2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

Documentation/git-diff.txt +1 -1

index dd1fb32..61728f6 100644
@@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc
 
 SYNOPSIS
 --------
-'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...]
+'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]
 
 DESCRIPTION
 -----------

Documentation/git-difftool.txt +1 -1

index 8250bad..a02e3b5 100644
@@ -7,7 +7,7 @@ git-difftool - Show changes using common diff tools
 
 SYNOPSIS
 --------
-'git difftool' [<options>] <commit>{0,2} [--] [<path>...]
+'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
 
 DESCRIPTION
 -----------

builtin/diff.c +1 -1

index a43d326..945e758 100644
@@ -22,7 +22,7 @@ struct blobinfo {
 };
 
 static const char builtin_diff_usage[] =
-"git diff <options> <rev>{0,2} -- <path>*";
+"git diff [<options>] [<commit> [<commit>]] [--] [<path>...]";
 
 static void stuff_change(struct diff_options *opt,
 			 unsigned old_mode, unsigned new_mode,

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Jeff King

2016-06-15 22:49 UTC #18 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Quoted 9 lines · Štěpán Němec

This was the only occurence of that usage, and square brackets are sufficient and already well-established for that purpose.
Signed-off-by Štěpán Němec <[email protected]>
---
As per discussion upthread, this notation is not worth keeping; hence not mentioning it in the v2 of the CodingGuidlines patch and this removal.

I agree the notation is kind of odd. But the intent of the original is to point out that diff has several modes of operation, depending on the number of arguments it is given. Your change seems to make that even more subtle. I would be more in favor of showing the major modes of operation, one per line, which is what we do in other places. E.g., see git-branch(1).

Now in the case of diff, as soon as the "description" section starts, we do start talking about those modes (and there are a lot of them). But I think it may make sense to cover them with a short comment in the synopsis. Something like:

  # diff between index and working tree
  git diff [options] [--] [<path>...]

  # diff between HEAD and index
  git diff --cached [options] [--] [<path>...]

  # diff between commit and working tree
  git diff [options] <commit> [--] [<path>...]

  # diff between commit and index
  git diff --cached [options] <commit> [--] [<path>...]

  # diff between commits
  git diff [options] <commit> <commit> [--] [<path>...]

  # diff two paths
  git diff [options] [--] <path> <path>

which obviously is way more verbose, but I think it improves in two ways:

1. New users will immediately see what diff is for: it is the all-purpose diffing tool in git, and it has several modes of operation.

2. People who know what diff does but need a quick reference on which mode they are looking for can quickly scan the list.

If it's too verbose, we could collapse a few cases (e.g., "HEAD and index" and "commit and index" could come in one line).

-Peff

Jonathan Nieder

2016-06-15 22:49 UTC #19 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Quoted 12 lines · Jeff King

  # diff between index and working tree
  git diff [options] [--] [<path>...]

  # diff between HEAD and index
  git diff --cached [options] [--] [<path>...]

  # diff between commit and working tree
  git diff [options] <commit> [--] [<path>...]

  # diff between commit and index
  git diff --cached [options] <commit> [--] [<path>...]

Quoted 7 lines

  # diff between commits
  git diff [options] <commit> <commit> [--] [<path>...]

  # diff two paths
  git diff [options] [--] <path> <path>

which obviously is way more verbose

Yes, that's way more verbose than a typical manpage synopsis. For example, from printf(3):

SYNOPSIS

       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const char *format, ...);

       #include <stdarg.h>

       int vprintf(const char *format, va_list ap);
       int vfprintf(FILE *stream, const char *format, va_list ap);
       int vsprintf(char *str, const char *format, va_list ap);
       int vsnprintf(char *str, size_t size, const char *format, va_list ap);

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99

which would suggest that for git-diff(!) we should say something like:

SYNOPSIS

	git diff [options] [--] [<path>...]
	git diff [options] --cached [--] [<path>...]
	git diff [options] <commit> [--] [<path>...]
	git diff [options] --cached <commit> [--] [<path>...]
	git diff [options] <commit> <commit> [--] [<path>...]
	git diff [options] --no-index [--] <path> <path>

I would rather treat --cached as one of the options ("instead of comparing the worktree, compare its cached content in the index to the specified commit"), and if I were running the world, I'd leave off the [options]. :)

SYNOPSIS

	git diff [--] [<path>...]
	git diff <commit> [--] [<path>...]
	git diff <commit> <commit> [--] [<path>...]
	git diff --no-index [--] <path> <path>

perhaps with some kind of reminder about --cached:

The first two forms accept a --cached option to compare to staged content in the index instead of the work tree.

Jeff King

2016-06-15 22:49 UTC #20 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Quoted 1 line · Jonathan Nieder

Yes, that's way more verbose than a typical manpage synopsis.

Well, yes, but...

Quoted 17 lines

For example, from printf(3):

SYNOPSIS

       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const char *format, ...);

       #include <stdarg.h>

       int vprintf(const char *format, va_list ap);
       int vfprintf(FILE *stream, const char *format, va_list ap);
       int vsprintf(char *str, const char *format, va_list ap);
       int vsnprintf(char *str, size_t size, const char *format, va_list ap);

Quoted 3 lines

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
       snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99

That's a little unfair as a comparison, as it's from a different section. Try "man IO::Handle", or most other perl modules, for example. They are quite a bit more verbose.

But yes, in general it is more verbose than other commands in section 1.

Quoted 10 lines

which would suggest that for git-diff(!) we should say something like:

SYNOPSIS

	git diff [options] [--] [<path>...]
	git diff [options] --cached [--] [<path>...]
	git diff [options] <commit> [--] [<path>...]
	git diff [options] --cached <commit> [--] [<path>...]
	git diff [options] <commit> <commit> [--] [<path>...]
	git diff [options] --no-index [--] <path> <path>

I would be OK with that; my comment lines were an attempt to make it a bit more clear to the user. But reading your revised versions, they seem pretty clear to me. I think your example there can actually be collapsed down to:

	git diff [options] [<commit>] [--] [<path>...]
	git diff [options] --cached [<commit>] [--] [<path>...]
	git diff [options] <commit> <commit> [--] [<path>...]
	git diff [options] [--no-index] [--] <path> <path>

which covers the four major modes.

Quoted 3 lines

I would rather treat --cached as one of the options ("instead of comparing the worktree, compare its cached content in the index to the specified commit"),

Except it is not quite that. For the first two that I listed above, --cached makes that distinction. But --cached doesn't make sense at all in the third or fourth ones. So I think in practice it ends up defining a mode of operation more than simply an option.

But I do recognize that such a distinction is largely in the mental model of the user. On the other hand, this is documentation, so we are trying to promote healthy mental models for users. :)

Quoted 1 line

and if I were running the world, I'd leave off the [options]. :)

I have no strong opinion on that. There are pretty few unix programs that don't take [options] at the beginning, so it really is kind of superfluous. But it's also pretty standard, and clues the user in that we are a normal program.

-Peff

Jonathan Nieder

2016-06-15 22:49 UTC #21 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Quoted 6 lines · Jeff King

	git diff [options] [<commit>] [--] [<path>...]
	git diff [options] --cached [<commit>] [--] [<path>...]
	git diff [options] <commit> <commit> [--] [<path>...]
	git diff [options] [--no-index] [--] <path> <path>

which covers the four major modes.

Makes sense. There is just one particularity of

	git diff --cached [<commit>]

I am worried about. Namely: according to a recent patch,

	git diff --cached

should not be considered as

	git diff --cached HEAD

with the "HEAD" implicit, but a distinct operation meaning "show me what changes git commit would store".

Quoted 10 lines · Jonathan Nieder

Quoted 4 lines
I would rather treat --cached as one of the options ("instead of comparing the worktree, compare its cached content in the index to the specified commit"),
Except it is not quite that. For the first two that I listed above, --cached makes that distinction. But --cached doesn't make sense at all in the third or fourth ones. So I think in practice it ends up defining a mode of operation more than simply an option.

Not sure I understand your logic. Is your point that --cached in those cases does not print

fatal: --cached does not make sense in this operation mode

but

	usage: git diff <options> <rev>{0,2} -- <path>*

that implies the operation mode is not known?

Quoted 4 lines

There are pretty few unix programs
that don't take [options] at the beginning, so it really is kind of superfluous. But it's also pretty standard, and clues the user in that we are a normal program.

Yes, sorry about the tangent.

Jeff King

2016-06-15 22:49 UTC #22 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Quoted 6 lines · Jonathan Nieder

Makes sense. There is just one particularity of
	git diff --cached [<commit>]
I am worried about. Namely: according to a recent patch,

Quoted 8 lines

	git diff --cached
should not be considered as
	git diff --cached HEAD
with the "HEAD" implicit, but a distinct operation meaning "show me what changes git commit would store".

Yeah, I'm not sure I agree with that change, for the reason that it makes "git diff" more conceptually complex. Generally we think of "no commit" as "behave as if HEAD was given". But now it's not, but only in this one particular place.

I guess I should go complain in that thread, though...

Quoted 12 lines

Quoted 8 lines
Quoted 3 lines
I would rather treat --cached as one of the options ("instead of comparing the worktree, compare its cached content in the index to the specified commit"),
Except it is not quite that. For the first two that I listed above, --cached makes that distinction. But --cached doesn't make sense at all in the third or fourth ones. So I think in practice it ends up defining a mode of operation more than simply an option.
Not sure I understand your logic. Is your point that --cached in those cases does not print

Quoted 7 lines

fatal: --cached does not make sense in this operation mode
but
	usage: git diff <options> <rev>{0,2} -- <path>*
that implies the operation mode is not known?

No, I am fine with what it actually prints[1]. But my point is that "--cached" is not simply an option that should go in [options] in each synopsis line. Even though it _looks_ like an option (because it starts with --, and can go anywhere in the options list) it changes the syntax of the rest of the command line (in particular, you can provide 0 or 1 commits, not 2, and you cannot use --no-index)[2].

Removing it from the synopsis and just listing it as an option does not capture that aspect.

And yes, it's obviously a gray area. There are other mutually exclusive options that are really just normal options. I just happen to think that the action of "--cached" changes the operation significantly enough to be considered a separate mode. Just as we do with "-m" and "-d" for git-branch.

-Peff

[1] If we are on a quest to remove <rev>{0,2}, this is one other spot to do it.

[2] This ties in with an idea mentioned in years past (but never actually implemented) to have some symbolic name for referring to the working tree and index, like:

git diff HEAD INDEX

which makes it quite obvious what is going on, and that diff really only has one syntactic mode: diff thing A and thing B. The details of that depend on what thing A and thing B actually resolve to. But in theory that is identical to "git diff --cached HEAD".

Štěpán Němec

author

2016-06-15 22:49 UTC #23 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Jeff King <[email protected]> writes:

[...]

Quoted 1 line

	usage: git diff <options> <rev>{0,2} -- <path>*

[...]

Quoted 2 lines

[1] If we are on a quest to remove <rev>{0,2}, this is one other spot to do it.

That's already included in the patch.

I think this thread already has nothing to do with the purpose of the patch, though. I find your suggestion that <commit>{0,2} better conveys some information about git-diff's operation modes than [<commit> [<commit>]] does (which seems to have been your starting point) rather far-fetched.

Note that I do not feel strongly about removing the {M,N} notation (I expressed my opinion in the thread already[1]), but I see the notation problem as orthogonal to the issues you are discussing here.

So AIUI the patch can still be applied and we/you can then work on improving the usage string in other ways -- providing that we agree that the {M,N} notation should go, of course, which we apparently still don't?

In any case this seems to be less and less my itch to scratch, so I'm not sure I'm going to be of much help in this discussion. The thing I need to know for the CodingGuidelines patch is whether we're going to preserve and encourage the {M,N} usage or not (so please let's arrive to some conclusion on that matter -- I waited for several days before sending the updated version and nobody chimed in, so I assumed nobody other than Mark and Sverre really cared). Although, that's actually somewhat orthogonal, too -- we can always re-add the {M,N} subsection later.

Thanks,

Štěpán

Jeff King

2016-06-15 22:49 UTC #24 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Quoted 4 lines · Štěpán Němec

Quoted 2 lines
[1] If we are on a quest to remove <rev>{0,2}, this is one other spot to do it.
That's already included in the patch.

Ah, sorry, I missed that hunk.

Quoted 5 lines

I think this thread already has nothing to do with the purpose of the patch, though. I find your suggestion that <commit>{0,2} better conveys some information about git-diff's operation modes than [<commit> [<commit>]] does (which seems to have been your starting point) rather far-fetched.

I find your version slightly harder to read than the original, which is why I complained. However, I find both way worse than what Jonathan and I ended up with.

Quoted 4 lines

So AIUI the patch can still be applied and we/you can then work on improving the usage string in other ways -- providing that we agree that the {M,N} notation should go, of course, which we apparently still don't?

My main argument against that would be that if we are planning on changing it to something totally different right now anyway, your patch will just end up making textual conflicts for Junio to resolve. :)

Quoted 9 lines

In any case this seems to be less and less my itch to scratch, so I'm not sure I'm going to be of much help in this discussion. The thing I need to know for the CodingGuidelines patch is whether we're going to preserve and encourage the {M,N} usage or not (so please let's arrive to some conclusion on that matter -- I waited for several days before sending the updated version and nobody chimed in, so I assumed nobody other than Mark and Sverre really cared). Although, that's actually somewhat orthogonal, too -- we can always re-add the {M,N} subsection later.

Yeah, sorry to come in late to the discussion. I missed the other thread entirely. I think getting rid of {M,N} is fine. In general, your proposed replacement is better. It's just that in this case it seemed to be obfuscating a subtle point that the original syntax (as ugly and incomprehensible as it was) called out.

So yes, go ahead with your coding guidelines patch. I'll summarize what Jonathan and I discussed with a new patch.

-Peff

Jeff King

2016-06-15 22:49 UTC #25 lore raw

PATCH 1/1 docs: clarify git diff modes of operation

It is an oversimplification to say that we can take "[<commit> [<commit>]]", as it really depends on what options have been given. Instead, let's list the major modes of operation separately, as we do in other manpages.

This patch also adjusts the text immediately after the synopsis to match the lines given in the synopsis.

For git-difftool, which has the same issue, let's refer the user to the git-diff manpage rather than spelling it all out again.

Signed-off-by Jeff King <[email protected]>

---

Quoted 8 lines · Jeff King

Quoted 4 lines
So AIUI the patch can still be applied and we/you can then work on improving the usage string in other ways -- providing that we agree that the {M,N} notation should go, of course, which we apparently still don't?
My main argument against that would be that if we are planning on changing it to something totally different right now anyway, your patch will just end up making textual conflicts for Junio to resolve. :)

I had intially thought I would tweak all three sites that you did, but after thinking about it, I really just want to change the one in Documentation/git-diff.txt. Which turned my patch into a mix of two different changes, and means it probably should just go on top of yours.

So here is my patch, which should apply on top of yours.

Note that in all versions (the original, yours, and mine) we gloss over the fact that <commit> can actually be any two objects (as long as they are bother either tree-ishs or blobs). I'm not sure if it is worth documenting that subtlety here (at least the tree-ish thing gets mentioned later in the description; I'm not sure we ever document "git diff HEAD:Makefile HEAD^:Makefile" anywhere).

Jonathan, does this look ok based on our earlier discussion?

 Documentation/git-diff.txt     |   11 ++++++++---
 Documentation/git-difftool.txt |    3 ++-
 2 files changed, 10 insertions(+), 4 deletions(-)

Documentation/git-diff.txt +8 -3

index 61728f6..f6ac847 100644
@@ -8,12 +8,17 @@ git-diff - Show changes between commits, commit and working tree, etc
 
 SYNOPSIS
 --------
-'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]
+[verse]
+'git diff' [options] [<commit>] [--] [<path>...]
+'git diff' [options] --cached [<commit>] [--] [<path>...]
+'git diff' [options] <commit> <commit> [--] [<path>...]
+'git diff' [options] [--no-index] [--] <path> <path>
 
 DESCRIPTION
 -----------
-Show changes between two trees, a tree and the working tree, a
-tree and the index file, or the index file and the working tree.
+Show changes between the working tree and the index or a tree, changes
+between the index and a tree, changes between two trees, or changes
+between two files on disk.
 
 'git diff' [--options] [--] [<path>...]::

Documentation/git-difftool.txt +2 -1

index a02e3b5..6fffbc7 100644
@@ -13,7 +13,8 @@ DESCRIPTION
 -----------
 'git difftool' is a git command that allows you to compare and edit files
 between revisions using common diff tools.  'git difftool' is a frontend
-to 'git diff' and accepts the same options and arguments.
+to 'git diff' and accepts the same options and arguments. See
+linkgit:git-diff[1].
 
 OPTIONS
 -------

Signature · 1 line

1.7.3.2.218.g4ee9d

Jonathan Nieder

2016-06-15 22:49 UTC #26 lore raw

Re: [PATCH] docs: clarify git diff modes of operation

Quoted 1 line · Jeff King

Jonathan, does this look ok based on our earlier discussion?

Yep, it's way better than the current state.

The list of operation modes still seems wrong: in addition to the meaning of

	git diff --cached

from an unborn branch not fitting the model of implicit HEAD as mentioned before, there is also

git diff

not meaning the same thing as

git diff HEAD

. So I guess technically the separate operation modes are

git diff [--cached]
git diff [--cached] <tree>
git diff <tree> <tree>
git diff --no-index <path> <path>
git diff <blob> <blob>

where --cached means "use the version of the work tree stored in the index in place of the real thing".

Mark Lodato

2016-06-15 22:49 UTC #27 lore raw

Re: [PATCH] docs: clarify git diff modes of operation

Quoted 10 lines · Jonathan Nieder

. So I guess technically the separate operation modes are
git diff [--cached]
git diff [--cached] <tree>
git diff <tree> <tree>
git diff --no-index <path> <path>
git diff <blob> <blob>
where --cached means "use the version of the work tree stored in the index in place of the real thing".

I prefer this above the other proposals. This breakdown makes the most sense to me, and I see no reason to use <commit> when we really mean <tree>. One minor thing: should the "<blob> <blob>" form be moved above "<path> <path>" so that all the git object forms are together?

On a related note, I find it a bit confusing that <path> is used to mean two very different things. For "<path> <path>", it means a file that must exist on disk. For "[<path>...]", it means a pattern on which to filter the output of the command. Since we already have a name for the latter, perhaps we should use the term "[<pathspec>...]".

Štěpán Němec

author

2016-06-15 22:49 UTC #28 lore raw

Re: [PATCH] docs: clarify git diff modes of operation

In reply to Jeff King

Quoted 3 lines · Jeff King

Note that in all versions (the original, yours, and mine) we gloss over the fact that <commit> can actually be any two objects (as long as they are bother either tree-ishs or blobs).

Yeah, I thought about that, too. I think it would be nice to use more precise placeholders like <tree-ish> or <object> (which do already occur in other places), but I suspect it might be needed/useful at more places and would better be done as a separate patch (preferably by someone who is more familiar with the internals than me).

Quoted 4 lines

I'm not sure if it is worth documenting that subtlety here (at least the tree-ish thing gets mentioned later in the description; I'm not sure we ever document "git diff HEAD:Makefile HEAD^:Makefile" anywhere).

There's gitrevisions(7) (also pointed to from the git-diff manpage) which describes those in some detail.

Štěpán

Štěpán Němec

author

2016-06-15 22:49 UTC #29 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

In reply to Jeff King

Quoted 3 lines · Jeff King

My main argument against that would be that if we are planning on changing it to something totally different right now anyway, your patch will just end up making textual conflicts for Junio to resolve. :)

Right. I hoped you'd come up with a patch yourself, which now happend, so, thank you. :-)

Quoted 8 lines

Yeah, sorry to come in late to the discussion. I missed the other thread entirely. I think getting rid of {M,N} is fine. In general, your proposed replacement is better. It's just that in this case it seemed to be obfuscating a subtle point that the original syntax (as ugly and incomprehensible as it was) called out.
So yes, go ahead with your coding guidelines patch. I'll summarize what Jonathan and I discussed with a new patch.

In that case the v2 [1] is still a valid review target, thanks.

Štěpán

[1] Earlier in the thread and here for anyone interested:
http://article.gmane.org/gmane.comp.version-control.git/160733

Sverre Rabbelier

2016-06-15 22:49 UTC #30 lore raw

Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

Heya,

2010/11/4 Štěpán Němec <[email protected]>:

Quoted 4 lines

This was the only occurence of that usage, and square brackets are sufficient and already well-established for that purpose.
Signed-off-by Štěpán Němec <[email protected]>

Not sure if it's appropriate for Documentation patches, but fwiw:

Acked by: Sverre Rabbelier <[email protected]>

Signature · 3 lines

Cheers,

Sverre Rabbelier

Štěpán Němec

author

2016-06-15 22:49 UTC #31 lore raw

PATCH v2 1/1 CodingGuidelines: Add a section on writing documentation

Provide a few examples on argument and option notation in usage strings and command synopses.

---
Changes since the last version:

- add a separate subsection on vertical bar without parentheses (suggested by Mark Lodato)

- do not include the <thing>{M,N} usage for fixed number of occurences (Mark Lodato and Sverre Rabbelier)

 Documentation/CodingGuidelines |   52 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 52 insertions(+), 0 deletions(-)

Documentation/CodingGuidelines +52 -0

index 09ffc46..5aa2d34 100644
@@ -139,3 +139,55 @@ For C programs:
 
  - When we pass <string, length> pair to functions, we should try to
    pass them in that order.
+
+Writing Documentation:
+
+ Every user-visible change should be reflected in the documentation.
+ The same general rule as for code applies -- imitate the existing
+ conventions.  A few commented examples follow to provide reference
+ when writing or modifying command usage strings and synopsis sections
+ in the manual pages:
+
+ Placeholders are enclosed in angle brackets:
+   <file>
+   --sort=<key>
+   --abbrev[=<n>]
+
+ Possibility of multiple occurences is indicated by three dots:
+   <file>...
+   (One or more of <file>.)
+
+ Optional parts are enclosed in square brackets:
+   [<extra>]
+   (Zero or one <extra>.)
+
+   --exec-path[=<path>]
+   (Option with an optional argument.  Note that the "=" is inside the
+   brackets.)
+
+   [<patch>...]
+   (Zero or more of <patch>.  Note that the dots are inside, not
+   outside the brackets.)
+
+ Multiple alternatives are indicated with vertical bar:
+   [-q | --quiet]
+   [--utf8 | --no-utf8]
+
+ Parentheses are used for grouping:
+   [(<rev>|<range>)...]
+   (Any number of either <rev> or <range>.  Parens are needed to make
+   it clear that "..." pertains to both <rev> and <range>.)
+
+   [(-p <parent>)...]
+   (Any number of option -p, each with one <parent> argument.)
+
+   git remote set-head <name> (-a | -d | <branch>)
+   (One and only one of "-a", "-d" or "<branch>" _must_ (no square
+   brackets) be provided.)
+
+ And a somewhat more contrived example:
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
+   Here "=" is outside the brackets, because "--diff-filter=" is a
+   valid usage.  "*" has its own pair of brackets, because it can
+   (optionally) be specified only when one or more of the letters is
+   also provided.

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Štěpán Němec

2016-06-15 22:49 UTC #32 lore raw

PATCH 1/6 Use angles for placeholders consistently

---
 Documentation/diff-options.txt     |   10 +++---
 Documentation/git-apply.txt        |    4 +-
 Documentation/git-archive.txt      |    4 +-
 Documentation/git-bundle.txt       |    6 ++--
 Documentation/git-daemon.txt       |   48 ++++++++++++++++++------------------
 Documentation/git-fast-export.txt  |    2 +-
 Documentation/git-index-pack.txt   |    4 +-
 Documentation/git-ls-tree.txt      |   10 +++---
 Documentation/git-pack-objects.txt |   14 +++++-----
 Documentation/git-remote.txt       |    2 +-
 Documentation/git-repack.txt       |   12 ++++----
 Documentation/git-rev-list.txt     |   16 ++++++------
 Documentation/git-web--browse.txt  |   16 ++++++------
 Documentation/git.txt              |   12 ++++----
 Documentation/merge-strategies.txt |    2 +-
 Documentation/rev-list-options.txt |   16 ++++++------
 archive.c                          |    4 +-
 builtin/bundle.c                   |    4 +-
 builtin/grep.c                     |    2 +-
 builtin/ls-tree.c                  |    2 +-
 builtin/pack-objects.c             |    6 ++--
 builtin/remote.c                   |    2 +-
 builtin/rev-list.c                 |    8 +++---
 daemon.c                           |   18 ++++++------
 fast-import.c                      |    2 +-
 git.c                              |    8 +++---
 upload-pack.c                      |    2 +-
 27 files changed, 118 insertions(+), 118 deletions(-)

Documentation/diff-options.txt +5 -5

index f77a0f8..cbf3c92 100644
@@ -48,9 +48,9 @@ endif::git-format-patch[]
 --patience::
 	Generate a diff using the "patience diff" algorithm.
 
---stat[=width[,name-width]]::
+--stat[=<width>[,<name-width>]]::
 	Generate a diffstat.  You can override the default
-	output width for 80-column terminal by `--stat=width`.
+	output width for 80-column terminal by `--stat=<width>`.
 	The width of the filename part can be controlled by
 	giving another width to it separated by a comma.

@@ -66,14 +66,14 @@ endif::git-format-patch[]
 	number of modified files, as well as number of added and deleted
 	lines.
 
---dirstat[=limit]::
+--dirstat[=<limit>]::
 	Output the distribution of relative amount of changes (number of lines added or
 	removed) for each sub-directory. Directories with changes below
 	a cut-off percent (3% by default) are not shown. The cut-off percent
-	can be set with `--dirstat=limit`. Changes in a child directory is not
+	can be set with `--dirstat=<limit>`. Changes in a child directory are not
 	counted for the parent directory, unless `--cumulative` is used.
 
---dirstat-by-file[=limit]::
+--dirstat-by-file[=<limit>]::
 	Same as `--dirstat`, but counts changed files instead of lines.
 
 --summary::

Documentation/git-apply.txt +2 -2

index 4a74b23..08bf6e7 100644
@@ -12,10 +12,10 @@ SYNOPSIS
 'git apply' [--stat] [--numstat] [--summary] [--check] [--index]
 	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
-	  [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached]
+	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
 	  [--ignore-space-change | --ignore-whitespace ]
 	  [--whitespace=<nowarn|warn|fix|error|error-all>]
-	  [--exclude=PATH] [--include=PATH] [--directory=<root>]
+	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
 	  [--verbose] [<patch>...]
 
 DESCRIPTION

Documentation/git-archive.txt +2 -2

index 8d3e666..4163a1b 100644
@@ -12,7 +12,7 @@ SYNOPSIS
 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
 	      [-o | --output=<file>] [--worktree-attributes]
 	      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
-	      [path...]
+	      [<path>...]
 
 DESCRIPTION
 -----------

@@ -73,7 +73,7 @@ OPTIONS
 <tree-ish>::
 	The tree or commit to produce an archive for.
 
-path::
+<path>::
 	Without an optional path parameter, all files and subdirectories
 	of the current working directory are included in the archive.
 	If one or more paths are specified, only these are included.

Documentation/git-bundle.txt +3 -3

index 38e59af..6266a3a 100644
@@ -11,8 +11,8 @@ SYNOPSIS
 [verse]
 'git bundle' create <file> <git-rev-list-args>
 'git bundle' verify <file>
-'git bundle' list-heads <file> [refname...]
-'git bundle' unbundle <file> [refname...]
+'git bundle' list-heads <file> [<refname>...]
+'git bundle' unbundle <file> [<refname>...]
 
 DESCRIPTION
 -----------

@@ -68,7 +68,7 @@ unbundle <file>::
 	packaged.
 
 
-[refname...]::
+[<refname>...]::
 	A list of references used to limit the references reported as
 	available. This is principally of use to 'git fetch', which
 	expects to receive only those references asked for and not

Documentation/git-daemon.txt +24 ~~-24~~

115 lines not on this page · raw message

Documentation/git-fast-export.txt +1 -1

index fcad113..e05b686 100644
@@ -96,7 +96,7 @@ marks the same across runs.
 	in the commit (as opposed to just listing the files which are
 	different from the commit's first parent).
 
-[git-rev-list-args...]::
+[<git-rev-list-args>...]::
        A list of arguments, acceptable to 'git rev-parse' and
        'git rev-list', that specifies the specific objects and references
        to export.  For example, `master{tilde}10..master` causes the

Documentation/git-index-pack.txt +2 -2

index f3ccc72..c2bb810 100644
@@ -59,10 +59,10 @@ OPTIONS
 	the newly constructed pack and index before refs can be
 	updated to use objects contained in the pack.
 
---keep='why'::
+--keep=<msg>::
 	Like --keep create a .keep file before moving the index into
 	its final destination, but rather than creating an empty file
-	place 'why' followed by an LF into the .keep file.  The 'why'
+	place '<msg>' followed by an LF into the .keep file.  The '<msg>'
 	message can later be searched for within all .keep files to
 	locate any which have outlived their usefulness.

Documentation/git-ls-tree.txt +5 -5

index 1f89d36..76ed625 100644
@@ -10,8 +10,8 @@ SYNOPSIS
 --------
 [verse]
 'git ls-tree' [-d] [-r] [-t] [-l] [-z]
-	    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]
-	    <tree-ish> [paths...]
+	    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]
+	    <tree-ish> [<path>...]
 
 DESCRIPTION
 -----------

@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does
 in the current working directory.  Note that:
 
  - the behaviour is slightly different from that of "/bin/ls" in that the
-   'paths' denote just a list of patterns to match, e.g. so specifying
+   '<path>' denotes just a list of patterns to match, e.g. so specifying
    directory name (without '-r') will behave differently, and order of the
    arguments does not matter.
 
- - the behaviour is similar to that of "/bin/ls" in that the 'paths' is
+ - the behaviour is similar to that of "/bin/ls" in that the '<path>' is
    taken as relative to the current working directory.  E.g. when you are
    in a directory 'sub' that has a directory 'dir', you can run 'git
    ls-tree -r HEAD dir' to list the contents of the tree (that is

@@ -72,7 +72,7 @@ OPTIONS
 	Do not limit the listing to the current working directory.
 	Implies --full-name.
 
-paths::
+[<path>...]::
 	When paths are given, show them (note that this isn't really raw
 	pathnames, but rather a list of patterns to match).  Otherwise
 	implicitly uses the root level of the tree as the sole path argument.

Documentation/git-pack-objects.txt +7 -7

index 8ed09c0..a1dd3e9 100644
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
 	[--no-reuse-delta] [--delta-base-offset] [--non-empty]
-	[--local] [--incremental] [--window=N] [--depth=N]
+	[--local] [--incremental] [--window=<n>] [--depth=<n>]
 	[--revs [--unpacked | --all]*] [--stdout | base-name]
 	[--keep-true-parents] < object-list

@@ -82,8 +82,8 @@ base-name::
 	reference was included in the resulting packfile.  This
 	can be useful to send new tags to native git clients.
 
---window=[N]::
---depth=[N]::
+--window=<n>::
+--depth=<n>::
 	These two options affect how the objects contained in
 	the pack are stored using delta compression.  The
 	objects are first internally sorted by type, size and

@@ -95,10 +95,10 @@ base-name::
 	times to get to the necessary object.
 	The default value for --window is 10 and --depth is 50.
 
---window-memory=[N]::
+--window-memory=<n>::
 	This option provides an additional limit on top of `--window`;
 	the window size will dynamically scale down so as to not take
-	up more than N bytes in memory.  This is useful in
+	up more than '<n>' bytes in memory.  This is useful in
 	repositories with a mix of large and small objects to not run
 	out of memory with a large window, but still be able to take
 	advantage of the large window for the smaller objects.  The

@@ -106,7 +106,7 @@ base-name::
 	`--window-memory=0` makes memory usage unlimited, which is the
 	default.
 
---max-pack-size=[N]::
+--max-pack-size=<n>::
 	Maximum size of each output pack file. The size can be suffixed with
 	"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
 	If specified,  multiple packfiles may be created.

@@ -171,7 +171,7 @@ base-name::
 	wholesale enforcement of a different compression level on the
 	packed data is desired.
 
---compression=[N]::
+--compression=<n>::
 	Specifies compression level for newly-compressed data in the
 	generated pack.  If not specified,  pack compression level is
 	determined first by pack.compression,  then by core.compression,

Documentation/git-remote.txt +1 -1

index aa021b0..b317086 100644
@@ -20,7 +20,7 @@ SYNOPSIS
 'git remote set-url --delete' [--push] <name> <url>
 'git remote' [-v | --verbose] 'show' [-n] <name>
 'git remote prune' [-n | --dry-run] <name>
-'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]...
+'git remote' [-v | --verbose] 'update' [-p | --prune] [<group> | <remote>]...
 
 DESCRIPTION
 -----------

Documentation/git-repack.txt +6 -6

index 9566727..27f7865 100644
@@ -8,7 +8,7 @@ git-repack - Pack unpacked objects in a repository
 
 SYNOPSIS
 --------
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=N] [--depth=N]
+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>]
 
 DESCRIPTION
 -----------

@@ -80,8 +80,8 @@ other objects in that pack they already have locally.
 	this repository (or a direct copy of it)
 	over HTTP or FTP.  See linkgit:git-update-server-info[1].
 
---window=[N]::
---depth=[N]::
+--window=<n>::
+--depth=<n>::
 	These two options affect how the objects contained in the pack are
 	stored using delta compression. The objects are first internally
 	sorted by type, size and optionally names and compared against the

@@ -91,10 +91,10 @@ other objects in that pack they already have locally.
 	to be applied that many times to get to the necessary object.
 	The default value for --window is 10 and --depth is 50.
 
---window-memory=[N]::
+--window-memory=<n>::
 	This option provides an additional limit on top of `--window`;
 	the window size will dynamically scale down so as to not take
-	up more than N bytes in memory.  This is useful in
+	up more than '<n>' bytes in memory.  This is useful in
 	repositories with a mix of large and small objects to not run
 	out of memory with a large window, but still be able to take
 	advantage of the large window for the smaller objects.  The

@@ -102,7 +102,7 @@ other objects in that pack they already have locally.
 	`--window-memory=0` makes memory usage unlimited, which is the
 	default.
 
---max-pack-size=[N]::
+--max-pack-size=<n>::
 	Maximum size of each output pack file. The size can be suffixed with
 	"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
 	If specified,  multiple packfiles may be created.

Documentation/git-rev-list.txt +8 -8

index 173f3fc..cfb1d21 100644
@@ -9,10 +9,10 @@ git-rev-list - Lists commit objects in reverse chronological order
 SYNOPSIS
 --------
 [verse]
-'git rev-list' [ \--max-count=number ]
-	     [ \--skip=number ]
-	     [ \--max-age=timestamp ]
-	     [ \--min-age=timestamp ]
+'git rev-list' [ \--max-count=<number> ]
+	     [ \--skip=<number> ]
+	     [ \--max-age=<timestamp> ]
+	     [ \--min-age=<timestamp> ]
 	     [ \--sparse ]
 	     [ \--merges ]
 	     [ \--no-merges ]

@@ -21,10 +21,10 @@ SYNOPSIS
 	     [ \--full-history ]
 	     [ \--not ]
 	     [ \--all ]
-	     [ \--branches[=pattern] ]
-	     [ \--tags[=pattern] ]
-	     [ \--remotes[=pattern] ]
-	     [ \--glob=glob-pattern ]
+	     [ \--branches[=<pattern>] ]
+	     [ \--tags[=<pattern>] ]
+	     [ \--remotes[=<pattern>] ]
+	     [ \--glob=<glob-pattern> ]
 	     [ \--stdin ]
 	     [ \--quiet ]
 	     [ \--topo-order ]

Documentation/git-web--browse.txt +8 -8

index e1586c7..51e8e0a 100644
@@ -32,19 +32,19 @@ Custom commands may also be specified.
 
 OPTIONS
 -------
--b BROWSER::
---browser=BROWSER::
-	Use the specified BROWSER. It must be in the list of supported
+-b <browser>::
+--browser=<browser>::
+	Use the specified browser. It must be in the list of supported
 	browsers.
 
--t BROWSER::
---tool=BROWSER::
+-t <browser>::
+--tool=<browser>::
 	Same as above.
 
--c CONF.VAR::
---config=CONF.VAR::
+-c <conf.var>::
+--config=<conf.var>::
 	CONF.VAR is looked up in the git config files. If it's set,
-	then its value specify the browser that should be used.
+	then its value specifies the browser that should be used.
 
 CONFIGURATION VARIABLES
 -----------------------

Documentation/git.txt +6 -6

index dd57bdc..8de8617 100644
@@ -9,11 +9,11 @@ git - the stupid content tracker
 SYNOPSIS
 --------
 [verse]
-'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]
+'git' [--version] [--exec-path[=<path>]] [--html-path]
     [-p|--paginate|--no-pager] [--no-replace-objects]
-    [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
-    [-c name=value]
-    [--help] COMMAND [ARGS]
+    [--bare] [--git-dir=<path>] [--work-tree=<path>]
+    [-c <name>=<value>]
+    [--help] <command> [<args>]
 
 DESCRIPTION
 -----------

@@ -28,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7].  See
 the link:user-manual.html[Git User's Manual] for a more in-depth
 introduction.
 
-The COMMAND is either a name of a Git command (see below) or an alias
+The '<command>' is either a name of a Git command (see below) or an alias
 as defined in the configuration file (see linkgit:git-config[1]).
 
 Formatted and hyperlinked version of the latest git

@@ -252,7 +252,7 @@ help ...`.
 	The <name> is expected in the same format as listed by
 	'git config' (subkeys separated by dots).
 
---exec-path::
+--exec-path[=<path>]::
 	Path to wherever your core git programs are installed.
 	This can also be controlled by setting the GIT_EXEC_PATH
 	environment variable. If no path is given, 'git' will print

Documentation/merge-strategies.txt +1 -1

index 049313d..8676e26 100644
@@ -52,7 +52,7 @@ no-renormalize;;
 	Disables the `renormalize` option.  This overrides the
 	`merge.renormalize` configuration variable.
 
-subtree[=path];;
+subtree[=<path>];;
 	This option is a more advanced form of 'subtree' strategy, where
 	the strategy makes a guess on how two trees must be shifted to
 	match with each other when merging.  Instead, the specified path

Documentation/rev-list-options.txt +8 -8

index ebc0108..1b13c1f 100644
@@ -246,29 +246,29 @@ endif::git-rev-list[]
 	Pretend as if all the refs in `refs/` are listed on the
 	command line as '<commit>'.
 
---branches[=pattern]::
+--branches[=<pattern>]::
 
 	Pretend as if all the refs in `refs/heads` are listed
-	on the command line as '<commit>'. If `pattern` is given, limit
+	on the command line as '<commit>'. If '<pattern>' is given, limit
 	branches to ones matching given shell glob. If pattern lacks '?',
 	'*', or '[', '/*' at the end is implied.
 
---tags[=pattern]::
+--tags[=<pattern>]::
 
 	Pretend as if all the refs in `refs/tags` are listed
-	on the command line as '<commit>'. If `pattern` is given, limit
+	on the command line as '<commit>'. If '<pattern>' is given, limit
 	tags to ones matching given shell glob. If pattern lacks '?', '*',
 	or '[', '/*' at the end is implied.
 
---remotes[=pattern]::
+--remotes[=<pattern>]::
 
 	Pretend as if all the refs in `refs/remotes` are listed
-	on the command line as '<commit>'. If `pattern`is given, limit
+	on the command line as '<commit>'. If '<pattern>' is given, limit
 	remote tracking branches to ones matching given shell glob.
 	If pattern lacks '?', '*', or '[', '/*' at the end is implied.
 
---glob=glob-pattern::
-	Pretend as if all the refs matching shell glob `glob-pattern`
+--glob=<glob-pattern>::
+	Pretend as if all the refs matching shell glob '<glob-pattern>'
 	are listed on the command line as '<commit>'. Leading 'refs/',
 	is automatically prepended if missing. If pattern lacks '?', '*',
 	or '[', '/*' at the end is implied.

archive.c +2 -2

index edd6853..f59afda 100644
@@ -7,9 +7,9 @@
 #include "unpack-trees.h"
 
 static char const * const archive_usage[] = {
-	"git archive [options] <tree-ish> [path...]",
+	"git archive [options] <tree-ish> [<path>...]",
 	"git archive --list",
-	"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]",
+	"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]",
 	"git archive --remote <repo> [--exec <cmd>] --list",
 	NULL
 };

builtin/bundle.c +2 -2

index 80649ba..9b87fb9 100644
@@ -12,8 +12,8 @@
 static const char builtin_bundle_usage[] =
   "git bundle create <file> <git-rev-list args>\n"
   "   or: git bundle verify <file>\n"
-  "   or: git bundle list-heads <file> [refname...]\n"
-  "   or: git bundle unbundle <file> [refname...]";
+  "   or: git bundle list-heads <file> [<refname>...]\n"
+  "   or: git bundle unbundle <file> [<refname>...]";
 
 int cmd_bundle(int argc, const char **argv, const char *prefix)
 {

builtin/grep.c +1 -1

index da32f3d..3d5f6ac 100644
@@ -24,7 +24,7 @@
 #endif
 
 static char const * const grep_usage[] = {
-	"git grep [options] [-e] <pattern> [<rev>...] [[--] path...]",
+	"git grep [options] [-e] <pattern> [<rev>...] [[--] <path>...]",
 	NULL
 };

builtin/ls-tree.c +1 -1

index a818756..f73e6bd 100644
@@ -24,7 +24,7 @@ static int chomp_prefix;
 static const char *ls_tree_prefix;
 
 static const  char * const ls_tree_usage[] = {
-	"git ls-tree [<options>] <tree-ish> [path...]",
+	"git ls-tree [<options>] <tree-ish> [<path>...]",
 	NULL
 };

builtin/pack-objects.c +3 -3

index d5a8db1..1e4c386 100644
@@ -25,10 +25,10 @@
 static const char pack_usage[] =
   "git pack-objects [{ -q | --progress | --all-progress }]\n"
   "        [--all-progress-implied]\n"
-  "        [--max-pack-size=N] [--local] [--incremental]\n"
-  "        [--window=N] [--window-memory=N] [--depth=N]\n"
+  "        [--max-pack-size=<n>] [--local] [--incremental]\n"
+  "        [--window=<n>] [--window-memory=<n>] [--depth=<n>]\n"
   "        [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\n"
-  "        [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\n"
+  "        [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\n"
   "        [--reflog] [--stdout | base-name] [--include-tag]\n"
   "        [--keep-unreachable | --unpack-unreachable]\n"
   "        [<ref-list | <object-list]";

builtin/remote.c +1 -1

index 48e0a6b..c0198fc 100644
@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {
 	"git remote set-head <name> (-a | -d | <branch>)",
 	"git remote [-v | --verbose] show [-n] <name>",
 	"git remote prune [-n | --dry-run] <name>",
-	"git remote [-v | --verbose] update [-p | --prune] [group | remote]",
+	"git remote [-v | --verbose] update [-p | --prune] [<group> | <remote>]",
 	"git remote set-branches <name> [--add] <branch>...",
 	"git remote set-url <name> <newurl> [<oldurl>]",
 	"git remote set-url --add <name> <newurl>",

builtin/rev-list.c +4 -4

index efe9360..158ce11 100644
@@ -11,9 +11,9 @@
 static const char rev_list_usage[] =
 "git rev-list [OPTION] <commit-id>... [ -- paths... ]\n"
 "  limiting output:\n"
-"    --max-count=nr\n"
-"    --max-age=epoch\n"
-"    --min-age=epoch\n"
+"    --max-count=<n>\n"
+"    --max-age=<epoch>\n"
+"    --min-age=<epoch>\n"
 "    --sparse\n"
 "    --no-merges\n"
 "    --remove-empty\n"

@@ -33,7 +33,7 @@ static const char rev_list_usage[] =
 "    --objects | --objects-edge\n"
 "    --unpacked\n"
 "    --header | --pretty\n"
-"    --abbrev=nr | --no-abbrev\n"
+"    --abbrev=<n> | --no-abbrev\n"
 "    --abbrev-commit\n"
 "    --left-right\n"
 "  special purpose:\n"

daemon.c +9 -9

index e22a2b7..9326d3a 100644
@@ -20,15 +20,15 @@ static int reuseaddr;
 
 static const char daemon_usage[] =
 "git daemon [--verbose] [--syslog] [--export-all]\n"
-"           [--timeout=n] [--init-timeout=n] [--max-connections=n]\n"
-"           [--strict-paths] [--base-path=path] [--base-path-relaxed]\n"
-"           [--user-path | --user-path=path]\n"
-"           [--interpolated-path=path]\n"
-"           [--reuseaddr] [--detach] [--pid-file=file]\n"
-"           [--[enable|disable|allow-override|forbid-override]=service]\n"
-"           [--inetd | [--listen=host_or_ipaddr] [--port=n]\n"
-"                      [--user=user [--group=group]]\n"
-"           [directory...]";
+"           [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\n"
+"           [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\n"
+"           [--user-path | --user-path=<path>]\n"
+"           [--interpolated-path=<path>]\n"
+"           [--reuseaddr] [--detach] [--pid-file=<file>]\n"
+"           [--(enable|disable|allow-override|forbid-override)=<service>]\n"
+"           [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>]\n"
+"                      [--user=<user> [--group=<group>]]\n"
+"           [<directory>...]";
 
 /* List of acceptable pathname prefixes */
 static char **ok_paths;

fast-import.c +1 -1

index 2317b0f..eab68d5 100644
@@ -2884,7 +2884,7 @@ static int git_pack_config(const char *k, const char *v, void *cb)
 }
 
 static const char fast_import_usage[] =
-"git fast-import [--date-format=f] [--max-pack-size=n] [--big-file-threshold=n] [--depth=n] [--active-branches=n] [--export-marks=marks.file]";
+"git fast-import [--date-format=<f>] [--max-pack-size=<n>] [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>] [--export-marks=<marks.file>]";
 
 static void parse_argv(void)
 {

git.c +4 -4

index 50a1401..0409ac9 100644
@@ -6,14 +6,14 @@
 #include "run-command.h"
 
 const char git_usage_string[] =
-	"git [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]\n"
+	"git [--version] [--exec-path[=<path>]] [--html-path]\n"
 	"           [-p|--paginate|--no-pager] [--no-replace-objects]\n"
-	"           [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\n"
+	"           [--bare] [--git-dir=<path>] [--work-tree=<path>]\n"
 	"           [-c name=value] [--help]\n"
-	"           COMMAND [ARGS]";
+	"           <command> [<args>]";
 
 const char git_more_info_string[] =
-	"See 'git help COMMAND' for more information on a specific command.";
+	"See 'git help <command>' for more information on a specific command.";
 
 static struct startup_info git_startup_info;
 static int use_pager = -1;

upload-pack.c +1 -1

index 92f9530..f05e422 100644
@@ -11,7 +11,7 @@
 #include "list-objects.h"
 #include "run-command.h"
 
-static const char upload_pack_usage[] = "git upload-pack [--strict] [--timeout=nn] <dir>";
+static const char upload_pack_usage[] = "git upload-pack [--strict] [--timeout=<n>] <dir>";
 
 /* bits #0..7 in revision.h, #8..10 in commit.c */
 #define THEY_HAVE	(1u << 11)

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Štěpán Němec

2016-06-15 22:49 UTC #33 lore raw

PATCH 2/6 Fix odd markup in --diff-filter documentation

Use a `<spec>' placeholder instead of the regex-like bracket expression to make it more consistent with other similar places.

---
 Documentation/diff-options.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

Documentation/diff-options.txt +2 -2

index cbf3c92..719f589 100644
@@ -248,13 +248,13 @@ endif::git-log[]
 	If `n` is specified, it has the same meaning as for `-M<n>`.
 
 ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=<spec>::
+	'<spec>' can be any combination of the characters `ACDMRTUXB*`.
 	Select only files that are Added (`A`), Copied (`C`),
 	Deleted (`D`), Modified (`M`), Renamed (`R`), have their
 	type (i.e. regular file, symlink, submodule, ...) changed (`T`),
 	are Unmerged (`U`), are
 	Unknown (`X`), or have had their pairing Broken (`B`).
-	Any combination of the filter characters may be used.
 	When `*` (All-or-none) is added to the combination, all
 	paths are selected if there is any file that matches
 	other criteria in the comparison; if there is no file

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Jonathan Nieder

2016-06-15 22:49 UTC #34 lore raw

Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation

Documentation/diff-options.txt endif::git-log[] · line 251

Quoted 8 lines · Štěpán Němec

Documentation/diff-options.txt +1 -1

@@ -248,13 +248,13 @@ endif::git-log[]
 	If `n` is specified, it has the same meaning as for `-M<n>`.
 
 ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=<spec>::

Maybe something like

--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])

to keep the overview while following the conventions you've set out?

Strictly speaking, --diff-filter= (with empty argument) is allowed, too, but I don't know if it's worth fitting that in.

Štěpán Němec

2016-06-15 22:49 UTC #35 lore raw

Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation

Quoted 13 lines · Jonathan Nieder

Documentation/diff-options.txt endif::git-log[] · line 251
Quoted 8 lines · Štěpán Němec
Documentation/diff-options.txt +1 -1
@@ -248,13 +248,13 @@ endif::git-log[]
 	If `n` is specified, it has the same meaning as for `-M<n>`.
 
 ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=<spec>::
Maybe something like

Quoted 3 lines

--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])
to keep the overview while following the conventions you've set out?

Looks good to me as well, thanks.

Quoted 2 lines

Strictly speaking, --diff-filter= (with empty argument) is allowed, too, but I don't know if it's worth fitting that in.

If it provides some kind of useful behaviour (I don't know and you didn't clarify that either), then it should be documented I guess?

Štěpán

Jonathan Nieder

2016-06-15 22:49 UTC #36 lore raw

Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation

Quoted 7 lines · Štěpán Němec

Quoted 2 lines · Jonathan Nieder
Strictly speaking, --diff-filter= (with empty argument) is allowed, too, but I don't know if it's worth fitting that in.
If it provides some kind of useful behaviour (I don't know and you didn't clarify that either), then it should be documented I guess?

Just a special case of the usual behavior: it selects the empty set of files. Doesn't sound useful to me, but maybe someone writing a front-end would want to be reassured that --diff-filter will still work if the user unchecks all the boxes.

Of course, one can also just try it...

If you can find a way to format it nicely (using brackets?), then I think it should be part of the documented syntax, yes.

Štěpán Němec

2016-06-15 22:49 UTC #37 lore raw

Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation

Quoted 14 lines · Jonathan Nieder

Quoted 7 lines · Štěpán Němec
Quoted 2 lines · Jonathan Nieder
Strictly speaking, --diff-filter= (with empty argument) is allowed, too, but I don't know if it's worth fitting that in.
If it provides some kind of useful behaviour (I don't know and you didn't clarify that either), then it should be documented I guess?
Just a special case of the usual behavior: it selects the empty set of files. Doesn't sound useful to me, but maybe someone writing a front-end would want to be reassured that --diff-filter will still work if the user unchecks all the boxes.

Quoted 4 lines

Of course, one can also just try it...
If you can find a way to format it nicely (using brackets?), then I think it should be part of the documented syntax, yes.

Well, in that case simply replacing parens with brackets would do, i.e.

--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]

instead of

--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])

That would mean the following instead of the original [2/6]:

--- 8< ---
Subject: Fix odd markup in --diff-filter documentation

Instead of using the regex-like bracket expression, use grouping to make it more consistent with other similar places. The brackets now have the same meaning as in other documentation (i.e., the argument is optional).

Mentored-by Jonathan Nieder <[email protected]>

---
 Documentation/diff-options.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

Documentation/diff-options.txt +2 -2

index cbf3c92..e954af0 100644
@@ -248,13 +248,13 @@ endif::git-log[]
        If `n` is specified, it has the same meaning as for `-M<n>`.
 
 ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::
        Select only files that are Added (`A`), Copied (`C`),
        Deleted (`D`), Modified (`M`), Renamed (`R`), have their
        type (i.e. regular file, symlink, submodule, ...) changed (`T`),
        are Unmerged (`U`), are
        Unknown (`X`), or have had their pairing Broken (`B`).
-       Any combination of the filter characters may be used.
+       Any combination of the filter characters (including none) can be used.
        When `*` (All-or-none) is added to the combination, all
        paths are selected if there is any file that matches
        other criteria in the comparison; if there is no file

Jonathan Nieder

2016-06-15 22:49 UTC #38 lore raw

Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation

Quoted 1 line · Štěpán Němec

That would mean the following instead of the original [2/6]:

Looks good, thanks.

Štěpán Němec

2016-06-15 22:49 UTC #39 lore raw

PATCH 3/6 Use parentheses and `...' where appropriate

Remove some stray usage of other bracket types and asterisks for the same purpose.

---
 Documentation/git-am.txt             |    4 ++--
 Documentation/git-apply.txt          |    2 +-
 Documentation/git-checkout-index.txt |    2 +-
 Documentation/git-commit-tree.txt    |    2 +-
 Documentation/git-fetch.txt          |    2 +-
 Documentation/git-filter-branch.txt  |    2 +-
 Documentation/git-for-each-ref.txt   |    2 +-
 Documentation/git-init.txt           |    2 +-
 Documentation/git-ls-files.txt       |    2 +-
 Documentation/git-mailsplit.txt      |    2 +-
 Documentation/git-mergetool.txt      |    2 +-
 Documentation/git-pack-objects.txt   |    2 +-
 Documentation/git-relink.txt         |    2 +-
 Documentation/git-remote.txt         |    2 +-
 Documentation/git-rev-list.txt       |    2 +-
 Documentation/git-rev-parse.txt      |    2 +-
 Documentation/git-show-branch.txt    |    2 +-
 Documentation/git-svn.txt            |    2 +-
 Documentation/git-update-index.txt   |    4 ++--
 Documentation/rev-list-options.txt   |    2 +-
 Documentation/user-manual.txt        |    2 +-
 builtin/commit-tree.c                |    2 +-
 builtin/fetch.c                      |    2 +-
 builtin/index-pack.c                 |    2 +-
 builtin/ls-files.c                   |    2 +-
 builtin/mailsplit.c                  |    2 +-
 builtin/pack-objects.c               |    2 +-
 builtin/remote.c                     |    2 +-
 builtin/show-branch.c                |    2 +-
 git-am.sh                            |    2 +-
 git-relink.perl                      |    2 +-
 31 files changed, 33 insertions(+), 33 deletions(-)

Documentation/git-am.txt +2 -2

index 9e62f87..51297d0 100644
@@ -14,7 +14,7 @@ SYNOPSIS
 	 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
 	 [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
 	 [--reject] [-q | --quiet] [--scissors | --no-scissors]
-	 [<mbox> | <Maildir>...]
+	 [(<mbox> | <Maildir>)...]
 'git am' (--continue | --skip | --abort)
 
 DESCRIPTION

@@ -25,7 +25,7 @@ current branch.
 
 OPTIONS
 -------
-<mbox>|<Maildir>...::
+(<mbox>|<Maildir>)...::
 	The list of mailbox files to read patches from. If you do not
 	supply this argument, the command reads from the standard input.
 	If you supply directories, they will be treated as Maildirs.

Documentation/git-apply.txt +1 -1

index 08bf6e7..881652f 100644
@@ -14,7 +14,7 @@ SYNOPSIS
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
 	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
 	  [--ignore-space-change | --ignore-whitespace ]
-	  [--whitespace=<nowarn|warn|fix|error|error-all>]
+	  [--whitespace=(nowarn|warn|fix|error|error-all)]
 	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
 	  [--verbose] [<patch>...]

Documentation/git-checkout-index.txt +1 -1

index 62f9ab2..0c0a9c1 100644
@@ -13,7 +13,7 @@ SYNOPSIS
 		   [--stage=<number>|all]
 		   [--temp]
 		   [-z] [--stdin]
-		   [--] [<file>]*
+		   [--] [<file>...]
 
 DESCRIPTION
 -----------

Documentation/git-commit-tree.txt +1 -1

index 349366e..5dcf427 100644
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
 
 SYNOPSIS
 --------
-'git commit-tree' <tree> [-p <parent commit>]* < changelog
+'git commit-tree' <tree> [(-p <parent commit>)...] < changelog
 
 DESCRIPTION
 -----------

Documentation/git-fetch.txt +1 -1

index 400fe7f..d159e88 100644
@@ -12,7 +12,7 @@ SYNOPSIS
 
 'git fetch' [<options>] <group>
 
-'git fetch' --multiple [<options>] [<repository> | <group>]...
+'git fetch' --multiple [<options>] [(<repository> | <group>)...]
 
 'git fetch' --all [<options>]

Documentation/git-filter-branch.txt +1 -1

index f51860d..796e748 100644
@@ -117,7 +117,7 @@ OPTIONS
 	This is the filter for performing the commit.
 	If this filter is specified, it will be called instead of the
 	'git commit-tree' command, with arguments of the form
-	"<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
+	"<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on
 	stdin.  The commit id is expected on stdout.
 +
 As a special extension, the commit filter may emit multiple

Documentation/git-for-each-ref.txt +1 -1

index d66fd9d..fac1cf5 100644
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
-		   [--sort=<key>]* [--format=<format>] [<pattern>...]
+		   [(--sort=<key>)...] [--format=<format>] [<pattern>...]
 
 DESCRIPTION
 -----------

Documentation/git-init.txt +1 -1

index 246b07e..00d4a12 100644
@@ -31,7 +31,7 @@ current working directory.
 Specify the directory from which templates will be used.  (See the "TEMPLATE
 DIRECTORY" section below.)
 
---shared[={false|true|umask|group|all|world|everybody|0xxx}]::
+--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
 
 Specify that the git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that

Documentation/git-ls-files.txt +1 -1

index 347f447..86abd13 100644
@@ -17,7 +17,7 @@ SYNOPSIS
 		[--exclude-per-directory=<file>]
 		[--exclude-standard]
 		[--error-unmatch] [--with-tree=<tree-ish>]
-		[--full-name] [--abbrev] [--] [<file>]*
+		[--full-name] [--abbrev] [--] [<file>...]
 
 DESCRIPTION
 -----------

Documentation/git-mailsplit.txt +1 -1

index a634485..71912a1 100644
@@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program
 
 SYNOPSIS
 --------
-'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...]
+'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...]
 
 DESCRIPTION
 -----------

Documentation/git-mergetool.txt +1 -1

index e4ed016..1f75a84 100644
@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
 
 SYNOPSIS
 --------
-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...
+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]
 
 DESCRIPTION
 -----------

Documentation/git-pack-objects.txt +1 -1

index a1dd3e9..65eff66 100644
@@ -12,7 +12,7 @@ SYNOPSIS
 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
 	[--no-reuse-delta] [--delta-base-offset] [--non-empty]
 	[--local] [--incremental] [--window=<n>] [--depth=<n>]
-	[--revs [--unpacked | --all]*] [--stdout | base-name]
+	[--revs [--unpacked | --all]] [--stdout | base-name]
 	[--keep-true-parents] < object-list

Documentation/git-relink.txt +1 -1

index 8a5842b..8fc809f 100644
@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories
 
 SYNOPSIS
 --------
-'git relink' [--safe] <dir> [<dir>]* <master_dir>
+'git relink' [--safe] <dir>... <master_dir>
 
 DESCRIPTION
 -----------

Documentation/git-remote.txt +1 -1

index b317086..0d28feb 100644
@@ -20,7 +20,7 @@ SYNOPSIS
 'git remote set-url --delete' [--push] <name> <url>
 'git remote' [-v | --verbose] 'show' [-n] <name>
 'git remote prune' [-n | --dry-run] <name>
-'git remote' [-v | --verbose] 'update' [-p | --prune] [<group> | <remote>]...
+'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]
 
 DESCRIPTION
 -----------

Documentation/git-rev-list.txt +1 -1

index cfb1d21..8e1e329 100644
@@ -37,7 +37,7 @@ SYNOPSIS
 	     [ \--regexp-ignore-case | -i ]
 	     [ \--extended-regexp | -E ]
 	     [ \--fixed-strings | -F ]
-	     [ \--date={local|relative|default|iso|rfc|short} ]
+	     [ \--date=(local|relative|default|iso|rfc|short) ]
 	     [ [\--objects | \--objects-edge] [ \--unpacked ] ]
 	     [ \--pretty | \--header ]
 	     [ \--bisect ]

Documentation/git-rev-parse.txt +1 -1

index 341ca90..4a27643 100644
@@ -95,7 +95,7 @@ OPTIONS
 	unfortunately named tag "master"), and show them as full
 	refnames (e.g. "refs/heads/master").
 
---abbrev-ref[={strict|loose}]::
+--abbrev-ref[=(strict|loose)]::
 	A non-ambiguous short name of the objects name.
 	The option core.warnAmbiguousRefs is used to select the strict
 	abbreviation mode.

Documentation/git-show-branch.txt +1 -1

index 6453263..bd9f886 100644
@@ -12,7 +12,7 @@ SYNOPSIS
 		[--current] [--color[=<when>] | --no-color] [--sparse]
 		[--more=<n> | --list | --independent | --merge-base]
 		[--no-name | --sha1-name] [--topics]
-		[<rev> | <glob>]...
+		[(<rev> | <glob>)...]
 
 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]

Documentation/git-svn.txt +1 -1

index be8a51f..139d314 100644
@@ -438,7 +438,7 @@ git rebase --onto remotes/git-svn A^ master
 OPTIONS
 -------
 
---shared[={false|true|umask|group|all|world|everybody}]::
+--shared[=(false|true|umask|group|all|world|everybody)]::
 --template=<template_directory>::
 	Only used with the 'init' command.
 	These are passed directly to 'git init'.

Documentation/git-update-index.txt +2 -2

index 74d1d49..a5782a6 100644
@@ -12,7 +12,7 @@ SYNOPSIS
 'git update-index'
 	     [--add] [--remove | --force-remove] [--replace]
 	     [--refresh] [-q] [--unmerged] [--ignore-missing]
-	     [--cacheinfo <mode> <object> <file>]*
+	     [(--cacheinfo <mode> <object> <file>)...]
 	     [--chmod=(+|-)x]
 	     [--assume-unchanged | --no-assume-unchanged]
 	     [--skip-worktree | --no-skip-worktree]

@@ -21,7 +21,7 @@ SYNOPSIS
 	     [--info-only] [--index-info]
 	     [-z] [--stdin]
 	     [--verbose]
-	     [--] [<file>]*
+	     [--] [<file>...]
 
 DESCRIPTION
 -----------

Documentation/rev-list-options.txt +1 -1

index 1b13c1f..7a42567 100644
@@ -13,7 +13,7 @@ include::pretty-options.txt[]
 
 	Synonym for `--date=relative`.
 
---date={relative,local,default,iso,rfc,short,raw}::
+--date=(relative|local|default|iso|rfc|short|raw)::
 
 	Only takes effect for dates shown in human-readable format, such
 	as when using "--pretty". `log.date` config variable sets a default

Documentation/user-manual.txt +1 -1

index ce45bfc..cb3b98a 100644
@@ -3850,7 +3850,7 @@ You create a commit object by giving it the tree that describes the
 state at the time of the commit, and a list of parents:
 
 -------------------------------------------------
-$ git commit-tree <tree> -p <parent> [-p <parent2> ..]
+$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
 -------------------------------------------------
 
 and then giving the reason for the commit on stdin (either through

builtin/commit-tree.c +1 -1

index 87f0591..e065739 100644
@@ -9,7 +9,7 @@
 #include "builtin.h"
 #include "utf8.h"
 
-static const char commit_tree_usage[] = "git commit-tree <sha1> [-p <sha1>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <sha1> [(-p <sha1>)...] < changelog";
 
 static void new_parent(struct commit *parent, struct commit_list **parents_p)
 {

builtin/fetch.c +1 -1

index 6fc5047..d35f000 100644
@@ -16,7 +16,7 @@
 static const char * const builtin_fetch_usage[] = {
 	"git fetch [<options>] [<repository> [<refspec>...]]",
 	"git fetch [<options>] <group>",
-	"git fetch --multiple [<options>] [<repository> | <group>]...",
+	"git fetch --multiple [<options>] [(<repository> | <group>)...]",
 	"git fetch --all [<options>]",
 	NULL
 };

builtin/index-pack.c +1 -1

index e243d9d..8dc5c0b 100644
@@ -11,7 +11,7 @@
 #include "exec_cmd.h"
 
 static const char index_pack_usage[] =
-"git index-pack [-v] [-o <index-file>] [{ --keep | --keep=<msg> }] [--strict] { <pack-file> | --stdin [--fix-thin] [<pack-file>] }";
+"git index-pack [-v] [-o <index-file>] [ --keep | --keep=<msg> ] [--strict] (<pack-file> | --stdin [--fix-thin] [<pack-file>])";
 
 struct object_entry
 {

builtin/ls-files.c +1 -1

index bb4f612..6a307ab 100644
@@ -424,7 +424,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_
 }
 
 static const char * const ls_files_usage[] = {
-	"git ls-files [options] [<file>]*",
+	"git ls-files [options] [<file>...]",
 	NULL
 };

builtin/mailsplit.c +1 -1

index 99654d0..2d43278 100644
@@ -10,7 +10,7 @@
 #include "strbuf.h"
 
 static const char git_mailsplit_usage[] =
-"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [<mbox>|<Maildir>...]";
+"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [(<mbox>|<Maildir>)...]";
 
 static int is_from_line(const char *line, int len)
 {

builtin/pack-objects.c +1 -1

index 1e4c386..26f2304 100644
@@ -23,7 +23,7 @@
 #endif
 
 static const char pack_usage[] =
-  "git pack-objects [{ -q | --progress | --all-progress }]\n"
+  "git pack-objects [ -q | --progress | --all-progress ]\n"
   "        [--all-progress-implied]\n"
   "        [--max-pack-size=<n>] [--local] [--incremental]\n"
   "        [--window=<n>] [--window-memory=<n>] [--depth=<n>]\n"

builtin/remote.c +1 -1

index c0198fc..e9a6e09 100644
@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {
 	"git remote set-head <name> (-a | -d | <branch>)",
 	"git remote [-v | --verbose] show [-n] <name>",
 	"git remote prune [-n | --dry-run] <name>",
-	"git remote [-v | --verbose] update [-p | --prune] [<group> | <remote>]",
+	"git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]",
 	"git remote set-branches <name> [--add] <branch>...",
 	"git remote set-url <name> <newurl> [<oldurl>]",
 	"git remote set-url --add <name> <newurl>",

builtin/show-branch.c +1 -1

index e8719aa..8663cca 100644
@@ -6,7 +6,7 @@
 #include "parse-options.h"
 
 static const char* show_branch_usage[] = {
-    "git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]...",
+    "git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]",
     "git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]",
     NULL
 };

git-am.sh +1 -1

index 9317b38..763fd20 100755
@@ -5,7 +5,7 @@
 SUBDIRECTORY_OK=Yes
 OPTIONS_KEEPDASHDASH=
 OPTIONS_SPEC="\
-git am [options] [<mbox>|<Maildir>...]
+git am [options] [(<mbox>|<Maildir>)...]
 git am [options] (--resolved | --skip | --abort)
 --
 i,interactive   run interactively

git-relink.perl +1 -1

index 937c69a..c2a0ef8 100755
@@ -163,7 +163,7 @@ sub link_two_files($$) {
 
 
 sub usage() {
-	print("Usage: git relink [--safe] <dir> [<dir> ...] <master_dir> \n");
+	print("Usage: git relink [--safe] <dir>... <master_dir> \n");
 	print("All directories should contain a .git/objects/ subdirectory.\n");
 	print("Options\n");
 	print("\t--safe\t" .

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Štěpán Němec

2016-06-15 22:49 UTC #40 lore raw

PATCH 4/6 Remove stray quotes in --pretty and --format documentation

Quotes (for emphasis) are used in option explanations, not the headings.

---
 Documentation/git-shortlog.txt   |    2 +-
 Documentation/pretty-options.txt |    4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

Documentation/git-shortlog.txt +1 -1

index bc1ac77..5cc3baf 100644
@@ -44,7 +44,7 @@ OPTIONS
 --email::
 	Show the email address of each author.
 
---format[='<format>']::
+--format[=<format>]::
 	Instead of the commit subject, use some other information to
 	describe each commit.  '<format>' can be any string accepted
 	by the `--format` option of 'git log', such as '{asterisk} [%h] %s'.

Documentation/pretty-options.txt +2 -2

index 9b6f389..50923e2 100644
@@ -1,5 +1,5 @@
---pretty[='<format>']::
---format='<format>'::
+--pretty[=<format>]::
+--format=<format>::
 
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Štěpán Němec

2016-06-15 22:49 UTC #41 lore raw

PATCH 5/6 Put a space between `<' and argument in pack-objects usage string

This makes it cosistent with other places (including the git-pack-objects(1) manpage itself) and avoids possible confusion (I, for one, mistook <object-list' for a <object-list>' typo at first when preparing this series).

---
 builtin/pack-objects.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

builtin/pack-objects.c +1 -1

index 26f2304..f8eba53 100644
@@ -31,7 +31,7 @@ static const char pack_usage[] =
   "        [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\n"
   "        [--reflog] [--stdout | base-name] [--include-tag]\n"
   "        [--keep-unreachable | --unpack-unreachable]\n"
-  "        [<ref-list | <object-list]";
+  "        [< ref-list | < object-list]";
 
 struct object_entry {
 	struct pack_idx_entry idx;

Signature · 1 line

1.7.3.rc2.221.gbf93f.dirty

Štěpán Němec

2016-06-15 22:49 UTC #42 lore raw

PATCH 6/6 Fix {update,checkout}-index usage strings

The `<file>' argument is optional in both cases (the man pages are already correct).