[PATCH/RFC 00/12] docs: use metavariables consistently

[PATCH/RFC 00/12] docs: use metavariables consistently

[Mark Lodato]

Based on master, 90a2bf9ca155c8e0e43d9e30197d9562dd02ea96.

This patch series is an attempt to make the documentation and usage
statements consistent in how metavariables [1], such as <commit>, are
used.  The biggest changes are to get rid of the terms <commit-ish> and
<tree-ish>, and instead prefer simple <commit> and <tree>.  It ends up
that almost all commands, with the exception of git-commit-tree, accept
the -ish versions of these objects.  The first patch --- which should be
the only non-trivial change to actual code --- modifies commit-tree to
accept any tree-ish.  The rest of the patches should all be confined to
documentation, usage statements, or code comments.

I submit this as an "RFC" because I don't expect this to be accepted
right away.  The change set is fairly large, and I imagine some of these
changes will meet resistance.  My overall goal is to make the
documentation consistent and readable throughout, and I hope that this
series makes progress toward that end.

[1] I say "metavariable", from Python's optparse, for lack of a better
term.

Mark Lodato (12):
  commit-tree: allow indirect tree references
  grep docs: grep accepts a <tree-ish>, not a <tree>
  fsck docs: remove outdated and useless diagnostic
  docs: use <sha1> to mean unabbreviated ID
  docs: differentiate between <tag> and <tagname>
  docs: clarify <object>, <commit>, <tree-ish>, etc
  docs: use <tree> instead of <tree-ish>
  http-fetch docs: use <commit-id> consistently
  docs: use <commit> instead of <commit-ish>
  diff: use brackets for optional args in usage
  docs: use ... instead of * for multiplicity
  diff docs: remove <rev>{0,2} notation

 Documentation/RelNotes-1.6.2.4.txt           |    2 +-
 Documentation/diff-format.txt                |    8 ++--
 Documentation/diff-generate-patch.txt        |    2 +-
 Documentation/git-archive.txt                |    4 +-
 Documentation/git-checkout-index.txt         |    2 +-
 Documentation/git-checkout.txt               |   14 ++++----
 Documentation/git-commit-tree.txt            |    2 +-
 Documentation/git-describe.txt               |   14 ++++----
 Documentation/git-diff-index.txt             |    4 +-
 Documentation/git-diff-tree.txt              |   18 +++++-----
 Documentation/git-diff.txt                   |    4 +-
 Documentation/git-difftool.txt               |    2 +-
 Documentation/git-fast-import.txt            |   22 ++++++------
 Documentation/git-for-each-ref.txt           |    2 +-
 Documentation/git-fsck.txt                   |    5 +--
 Documentation/git-http-fetch.txt             |    4 +-
 Documentation/git-ls-files.txt               |    8 ++--
 Documentation/git-ls-tree.txt                |    4 +-
 Documentation/git-merge-index.txt            |    2 +-
 Documentation/git-mergetool.txt              |    2 +-
 Documentation/git-name-rev.txt               |    2 +-
 Documentation/git-pack-objects.txt           |    2 +-
 Documentation/git-push.txt                   |    2 +-
 Documentation/git-read-tree.txt              |    4 +-
 Documentation/git-rebase.txt                 |    2 +-
 Documentation/git-relink.txt                 |    2 +-
 Documentation/git-shortlog.txt               |    2 +-
 Documentation/git-tar-tree.txt               |    4 +-
 Documentation/git-update-index.txt           |    4 +-
 Documentation/git.txt                        |   45 ++++++++++++++----------
 Documentation/gitcli.txt                     |    2 +-
 Documentation/howto/revert-branch-rebase.txt |    2 +-
 Documentation/pull-fetch-param.txt           |    2 +-
 archive.c                                    |    4 +-
 builtin/commit-tree.c                        |   15 +++++---
 builtin/describe.c                           |    4 +-
 builtin/diff-index.c                         |    2 +-
 builtin/diff-tree.c                          |    2 +-
 builtin/diff.c                               |    2 +-
 builtin/ls-files.c                           |    4 +-
 builtin/ls-tree.c                            |    2 +-
 builtin/merge-index.c                        |    2 +-
 builtin/merge.c                              |    2 +-
 builtin/pack-objects.c                       |    2 +-
 builtin/push.c                               |    2 +-
 builtin/revert.c                             |    4 +-
 builtin/tar-tree.c                           |    2 +-
 contrib/examples/git-merge.sh                |    2 +-
 contrib/examples/git-reset.sh                |    2 +-
 contrib/examples/git-revert.sh               |    4 +-
 fast-import.c                                |   16 ++++----
 git-svn.perl                                 |    2 +-
 remote.c                                     |    4 +-
 t/t1101-commit-tree-indirect.sh              |   49 ++++++++++++++++++++++++++
 t/t4100/t-apply-3.patch                      |    8 ++--
 t/t4100/t-apply-7.patch                      |    8 ++--
 56 files changed, 200 insertions(+), 144 deletions(-)
 create mode 100755 t/t1101-commit-tree-indirect.sh

[PATCH/RFC 01/12] commit-tree: allow indirect tree references

[Mark Lodato]

'git commit-tree' was the last remaining built-in to accept a <tree> but
not a <tree-ish> (an indirect tree reference through a commit or tag
object.)

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
A similar thing should be done for the parent commits.  As far as I can 
tell, this is the only command that requires a commit object, not a tag.

 Documentation/git-commit-tree.txt |    4 +-
 builtin/commit-tree.c             |   13 ++++++----
 t/t1101-commit-tree-indirect.sh   |   49 +++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 7 deletions(-)
 create mode 100755 t/t1101-commit-tree-indirect.sh

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 6188854..67b6bc0 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -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-ish> [-p <parent commit>]\* < changelog
 
 DESCRIPTION
 -----------
@@ -35,7 +35,7 @@ state was.
 
 OPTIONS
 -------
-<tree>::
+<tree-ish>::
 	An existing tree object
 
 -p <parent commit>::
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 90dac34..96a421e 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -97,16 +97,19 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)
 {
 	int i;
 	struct commit_list *parents = NULL;
-	unsigned char tree_sha1[20];
-	unsigned char commit_sha1[20];
+	unsigned char sha1[20];
 	struct strbuf buffer = STRBUF_INIT;
+	struct tree *tree;
 
 	git_config(git_default_config, NULL);
 
 	if (argc < 2 || !strcmp(argv[1], "-h"))
 		usage(commit_tree_usage);
-	if (get_sha1(argv[1], tree_sha1))
+	if (get_sha1(argv[1], sha1))
 		die("Not a valid object name %s", argv[1]);
+	tree = parse_tree_indirect(sha1);
+	if (!tree)
+		die("%s is not a valid 'tree' object", argv[1]);
 
 	for (i = 2; i < argc; i += 2) {
 		unsigned char sha1[20];
@@ -124,8 +127,8 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)
 	if (strbuf_read(&buffer, 0, 0) < 0)
 		die_errno("git commit-tree: failed to read");
 
-	if (!commit_tree(buffer.buf, tree_sha1, parents, commit_sha1, NULL)) {
-		printf("%s\n", sha1_to_hex(commit_sha1));
+	if (!commit_tree(buffer.buf, tree->object.sha1, parents, sha1, NULL)) {
+		printf("%s\n", sha1_to_hex(sha1));
 		return 0;
 	}
 	else
diff --git a/t/t1101-commit-tree-indirect.sh b/t/t1101-commit-tree-indirect.sh
new file mode 100755
index 0000000..905bad7
--- /dev/null
+++ b/t/t1101-commit-tree-indirect.sh
@@ -0,0 +1,49 @@
+#!/bin/sh
+#
+# Copyright (c) 2010 Mark Lodato
+#
+
+test_description='git commit-tree works with indirect references'
+
+. ./test-lib.sh
+
+get_tree() {
+	git cat-file commit $1 | sed -n -e 's/^tree //p'
+}
+
+test_expect_success 'prepare the repository' '
+	touch a &&
+	git add a &&
+	git commit -m x &&
+	git tag -a -m x tag-commit &&
+	git tag -a -m x tag-tree HEAD^{tree} &&
+	git tag -a -m x tag-blob HEAD:a &&
+	git tag -a -m x tag-tag-commit tag-commit
+'
+
+expected_tree="$(get_tree HEAD)"
+
+test_success() {
+	test_expect_success "commit-tree succeeds with $2" '
+		id="$(echo x | git commit-tree '"$1"')" &&
+		tree="$(get_tree $id)" &&
+		test "x$tree" = "x$expected_tree"
+	'
+}
+test_failure() {
+	test_expect_code 128 "commit-tree fails with $2" '
+		echo x | git commit-tree '"$1"' 2>/dev/null
+	'
+}
+
+test_failure HEAD:a "a blob"
+test_success HEAD^{tree} "a tree"
+test_success HEAD "HEAD"
+test_success master "a branch"
+test_failure foo "an invalid object name"
+test_failure tag-blob "a tag pointing to a blob"
+test_success tag-tree "a tag pointing to a tree"
+test_success tag-commit "a tag pointing to a commit"
+test_success tag-tag-commit "a tag pointing to a tag (to a commit)"
+
+test_done
-- 
1.7.0.2

[PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>

[Mark Lodato]

Also document that -p accepts a <commit> in the usage message.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-grep.txt |    4 ++--
 builtin/commit-tree.c      |    2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 4b32322..02d6306 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -21,7 +21,7 @@ SYNOPSIS
 	   [-A <post-context>] [-B <pre-context>] [-C <context>]
 	   [-f <file>] [-e] <pattern>
 	   [--and|--or|--not|(|)|-e <pattern>...]
-	   [--cached | --no-index | <tree>...]
+	   [--cached | --no-index | <tree-ish>...]
 	   [--] [<pathspec>...]
 
 DESCRIPTION
@@ -168,7 +168,7 @@ OPTIONS
 	Do not output matched lines; instead, exit with status 0 when
 	there is a match and with non-zero status when there isn't.
 
-<tree>...::
+<tree-ish>...::
 	Instead of searching tracked files in the working tree, search
 	blobs in the given trees.
 
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 96a421e..770baa2 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)
 		    typename(expect));
 }
 
-static const char commit_tree_usage[] = "git commit-tree <sha1> [-p <sha1>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <tree-ish> [-p <commit>]* < changelog";
 
 static void new_parent(struct commit *parent, struct commit_list **parents_p)
 {
-- 
1.7.0.2

[PATCH/RFC 03/12] fsck docs: remove outdated and useless diagnostic

[Mark Lodato]

In git-fsck(1), there was a reference to the warning "<tree> has full
pathnames in it".  This exact wording has not been used since 2005
(commit f1f0d0889e55), when the wording was changed slightly.  More
importantly, the description of that warning was useless, and there were
many other similar warning messages which were not document at all.
Since all these warnings are fairly obvious, there is no need for them
to be in the man page.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-fsck.txt |    3 ---
 1 files changed, 0 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 3ad48a6..86f9b2b 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -123,9 +123,6 @@ dangling <type> <object>::
 	The <type> object <object>, is present in the database but never
 	'directly' used. A dangling commit could be a root node.
 
-warning: git-fsck: tree <tree> has full pathnames in it::
-	And it shouldn't...
-
 sha1 mismatch <object>::
 	The database has an object who's sha1 doesn't match the
 	database value.
-- 
1.7.0.2

[PATCH/RFC 04/12] docs: use <sha1> to mean unabbreviated ID

[Mark Lodato]

There are some places that literally require a full, 40-character SHA-1
ID, rather than a generic revision specifier.  Introduce in git(1) the
<sha1> terminology to mean this.  Use <sha1> in git-diff-tree(1) to note
that --stdin only takes <sha1>'s, not generic <tree>'s or <commit>'s.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-diff-tree.txt |    4 ++--
 Documentation/git.txt           |    5 +++++
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index a7e37b8..5d0310b 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -49,8 +49,8 @@ include::diff-options.txt[]
 --stdin::
 	When '--stdin' is specified, the command does not take
 	<tree-ish> arguments from the command line.  Instead, it
-	reads lines containing either two <tree>, one <commit>, or a
-	list of <commit> from its standard input.  (Use a single space
+	reads lines containing <sha1>'s: either two trees, one commit, or
+	multiple commits from its standard input.  (Use a single space
 	as separator.)
 +
 When two trees are given, it compares the first tree with the second.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 35c0c79..a635281 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -412,6 +412,11 @@ list.
 
 Identifier Terminology
 ----------------------
+<sha1>::
+	Indicates a full, 40-character SHA-1 identifier of an object.
+	The type of the referenced object is unspecified.
+	Abbreviated or symbolic identifiers cannot be used.
+
 <object>::
 	Indicates the object name for any type of object.
 
-- 
1.7.0.2

[PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname>

[Mark Lodato]

In the documentation and user messages, differentiate between <tag>,
which means an actual annotated tag object, and <tagname>, which is
a revision specifier for refs/tags/<tagname>.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
A similar thing should be done for <head> vs <branch> vs <branchname>.  
The term <head> is not used anywhere to mean what it does in git(1); 
instead, it is used as a more descriptive term for <commit-ish>.  The 
term <branchname> is used for what git(1) describes as <head>, but the 
term <branch> is also used, and I'm not sure what it means.  I'll have 
to look into this.

 Documentation/git-push.txt         |    2 +-
 Documentation/git.txt              |    8 ++++++--
 Documentation/pull-fetch-param.txt |    2 +-
 builtin/push.c                     |    2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 49b6bd9..5445443 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -55,7 +55,7 @@ you can tell git to update the <dst> ref even when the update is not a
 fast-forward.  This does *not* attempt to merge <src> into <dst>.  See
 EXAMPLES below for details.
 +
-`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+`tag <tagname>` means the same as `refs/tags/<tagname>:refs/tags/<tagname>`.
 +
 Pushing an empty <src> allows you to delete the <dst> ref from
 the remote repository.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index a635281..f06e4de 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -420,6 +420,10 @@ Identifier Terminology
 <object>::
 	Indicates the object name for any type of object.
 
+<tag>::
+	Indicates a tag object name.  This is an annotated tag object, as
+	opposed to <tagname>, which can refer to any type of object.
+
 <blob>::
 	Indicates a blob object name.
 
@@ -458,9 +462,9 @@ HEAD::
 	indicates the head of the current branch (i.e. the
 	contents of `$GIT_DIR/HEAD`).
 
-<tag>::
+<tagname>::
 	a valid tag 'name'
-	(i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
+	(i.e. the contents of `$GIT_DIR/refs/tags/<tagname>`).
 
 <head>::
 	a valid head 'name'
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 5dd6e5a..3a947b3 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -66,7 +66,7 @@ is often useful.
 +
 Some short-cut notations are also supported.
 +
-* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;
+* `tag <tagname>` means the same as `refs/tags/<tagname>:refs/tags/<tagname>`;
   it requests fetching everything up to the given tag.
 * A parameter <ref> without a colon is equivalent to
   <ref>: when pulling/fetching, so it merges <ref> into the current
diff --git a/builtin/push.c b/builtin/push.c
index f7bc2b2..4227a8e 100644
--- a/builtin/push.c
+++ b/builtin/push.c
@@ -38,7 +38,7 @@ static void set_refspecs(const char **refs, int nr)
 			char *tag;
 			int len;
 			if (nr <= ++i)
-				die("tag shorthand without <tag>");
+				die("tag shorthand without <tagname>");
 			len = strlen(refs[i]) + 11;
 			if (deleterefs) {
 				tag = xmalloc(len+1);
-- 
1.7.0.2

[PATCH/RFC 06/12] docs: clarify <object>, <commit>, <tree-ish>, etc

[Mark Lodato]

In git(1), give more precise definitions of <object>, <commit>,
<tree-ish>, and so on.  In particular, differentiate <object> (which may
take generic revision specifiers) from <sha1>, which only accepts
a 40-character hex SHA-1 ID.

Also note that <rev> is another way to say <commit-ish>.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git.txt |   38 +++++++++++++++++++++-----------------
 1 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index f06e4de..55f3842 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -418,32 +418,36 @@ Identifier Terminology
 	Abbreviated or symbolic identifiers cannot be used.
 
 <object>::
-	Indicates the object name for any type of object.
+	Indicates the object name for any type of object.  Symbolic name or
+	abbreviated SHA-1 identifiers may be used (see "SPECIFYING REVISIONS"
+	in linkgit:git-rev-parse[1] for details).
 
 <tag>::
-	Indicates a tag object name.  This is an annotated tag object, as
+	Indicates a tag-type <object>.  This is an annotated tag object, as
 	opposed to <tagname>, which can refer to any type of object.
 
-<blob>::
-	Indicates a blob object name.
+<commit>::
+	Indicates a commit-type <object>.
 
 <tree>::
-	Indicates a tree object name.
-
-<commit>::
-	Indicates a commit object name.
+	Indicates a tree-type <object>.
 
-<tree-ish>::
-	Indicates a tree, commit or tag object name.  A
-	command that takes a <tree-ish> argument ultimately wants to
-	operate on a <tree> object but automatically dereferences
-	<commit> and <tag> objects that point at a <tree>.
+<blob>::
+	Indicates a blob-type <object>.
 
+<rev>::
 <commit-ish>::
-	Indicates a commit or tag object name.  A
-	command that takes a <commit-ish> argument ultimately wants to
-	operate on a <commit> object but automatically dereferences
-	<tag> objects that point at a <commit>.
+	Indicates a <commit>, or a <tag> that points at a <commit-ish>.
+	A command that takes a <commit-ish> argument ultimately wants to
+	operate on a commit object but automatically dereferences objects
+	until it finds a commit.
+	A <rev> is another name for a <commit-ish>.
+
+<tree-ish>::
+	Indicates a <tree>, or a <tag> or <commit> that points at a
+	<tree-ish>.  A command that takes a <tree-ish> argument ultimately
+	wants to operate on a tree object but automatically dereferences
+	objects until it finds a tree.
 
 <type>::
 	Indicates that an object type is required.
-- 
1.7.0.2

[PATCH/RFC 07/12] docs: use <tree> instead of <tree-ish>

[Mark Lodato]

There is no longer any reference to <tree> in the documentation, since
all commands now accept a <tree-ish>, so remove the latter in favor
of the former.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
I expect that this, along with the removal of <commit-ish>, is the most 
controversial part of the patch series.  I just don't see any reason to 
use the ugly and long <tree-ish> when <tree> is going unused!

 Documentation/RelNotes-1.6.2.4.txt    |    2 +-
 Documentation/diff-format.txt         |    8 ++++----
 Documentation/diff-generate-patch.txt |    2 +-
 Documentation/git-archive.txt         |    4 ++--
 Documentation/git-checkout.txt        |   14 +++++++-------
 Documentation/git-commit-tree.txt     |    4 ++--
 Documentation/git-diff-index.txt      |    4 ++--
 Documentation/git-diff-tree.txt       |   14 +++++++-------
 Documentation/git-diff.txt            |    2 +-
 Documentation/git-grep.txt            |    4 ++--
 Documentation/git-ls-files.txt        |    6 +++---
 Documentation/git-ls-tree.txt         |    4 ++--
 Documentation/git-read-tree.txt       |    4 ++--
 Documentation/git-tar-tree.txt        |    4 ++--
 Documentation/git.txt                 |   11 ++++-------
 archive.c                             |    4 ++--
 builtin/commit-tree.c                 |    2 +-
 builtin/diff-index.c                  |    2 +-
 builtin/diff-tree.c                   |    2 +-
 builtin/ls-files.c                    |    2 +-
 builtin/ls-tree.c                     |    2 +-
 builtin/tar-tree.c                    |    2 +-
 git-svn.perl                          |    2 +-
 t/t4100/t-apply-3.patch               |    8 ++++----
 t/t4100/t-apply-7.patch               |    8 ++++----
 25 files changed, 59 insertions(+), 62 deletions(-)

diff --git a/Documentation/RelNotes-1.6.2.4.txt b/Documentation/RelNotes-1.6.2.4.txt
index f4bf1d0..0e36786 100644
--- a/Documentation/RelNotes-1.6.2.4.txt
+++ b/Documentation/RelNotes-1.6.2.4.txt
@@ -13,7 +13,7 @@ Fixes since v1.6.2.3
 * "git-add -p" lacked a way to say "q"uit to refuse staging any hunks for
   the remaining paths.  You had to say "d" and then ^C.
 
-* "git-checkout <tree-ish> <submodule>" did not update the index entry at
+* "git-checkout <tree> <submodule>" did not update the index entry at
   the named path; it now does.
 
 * "git-fast-export" choked when seeing a tag that does not point at commit.
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 15c7e79..e1311fb 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -7,11 +7,11 @@ The raw output format from "git-diff-index", "git-diff-tree",
 These commands all compare two sets of things; what is
 compared differs:
 
-git-diff-index <tree-ish>::
-        compares the <tree-ish> and the files on the filesystem.
+git-diff-index <tree>::
+        compares the <tree> and the files on the filesystem.
 
-git-diff-index --cached <tree-ish>::
-        compares the <tree-ish> and the index.
+git-diff-index --cached <tree>::
+        compares the <tree> and the index.
 
 git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
         compares the trees named by the two arguments.
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 0f25ba7..e0eb126 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -110,7 +110,7 @@ The `mode <mode>,<mode>..<mode>` line appears only if at least one of
 the <mode> is different from the rest. Extended headers with
 information about detected contents movement (renames and
 copying detection) are designed to work with diff of two
-<tree-ish> and are not used by combined diff format.
+<tree> and are not used by combined diff format.
 
 3.   It is followed by two-line from-file/to-file header
 
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 8d3e666..1d520fc 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
 	      [-o | --output=<file>] [--worktree-attributes]
-	      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
+	      [--remote=<repo> [--exec=<git-upload-archive>]] <tree>
 	      [path...]
 
 DESCRIPTION
@@ -70,7 +70,7 @@ OPTIONS
 	Used with --remote to specify the path to the
 	'git-upload-archive' on the remote side.
 
-<tree-ish>::
+<tree>::
 	The tree or commit to produce an archive for.
 
 path::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 37c1810..b1061d5 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -10,8 +10,8 @@ SYNOPSIS
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
 'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
-'git checkout' --patch [<tree-ish>] [--] [<paths>...]
+'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree>] [--] <paths>...
+'git checkout' --patch [<tree>] [--] [<paths>...]
 
 DESCRIPTION
 -----------
@@ -28,9 +28,9 @@ creation; see the description of --track below.
 
 When <paths> or --patch are given, this command does *not* switch
 branches.  It updates the named paths in the working tree from
-the index file, or from a named <tree-ish> (most often a commit).  In
+the index file, or from a named <tree> (most often a commit).  In
 this case, the `-b` and `--track` options are meaningless and giving
-either of them results in an error. The <tree-ish> argument can be
+either of them results in an error. The <tree> argument can be
 used to specify a specific tree-ish (i.e. commit, tag or tree)
 to update the index for the given paths before updating the
 working tree.
@@ -119,9 +119,9 @@ the conflicted merge in the specified paths.
 -p::
 --patch::
 	Interactively select hunks in the difference between the
-	<tree-ish> (or the index, if unspecified) and the working
+	<tree> (or the index, if unspecified) and the working
 	tree.  The chosen hunks are then applied in reverse to the
-	working tree (and if a <tree-ish> was specified, the index).
+	working tree (and if a <tree> was specified, the index).
 +
 This means that you can use `git checkout -p` to selectively discard
 edits from your current working tree.
@@ -144,7 +144,7 @@ checks out the branch (instead of detaching).  You may also specify
 	The name of a commit at which to start the new branch; see
 	linkgit:git-branch[1] for details. Defaults to HEAD.
 
-<tree-ish>::
+<tree>::
 	Tree to checkout from (when paths are given). If not specified,
 	the index will be used.
 
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 67b6bc0..6188854 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
 
 SYNOPSIS
 --------
-'git commit-tree' <tree-ish> [-p <parent commit>]\* < changelog
+'git commit-tree' <tree> [-p <parent commit>]\* < changelog
 
 DESCRIPTION
 -----------
@@ -35,7 +35,7 @@ state was.
 
 OPTIONS
 -------
-<tree-ish>::
+<tree>::
 	An existing tree object
 
 -p <parent commit>::
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 162cb74..c725357 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -8,7 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi
 
 SYNOPSIS
 --------
-'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...]
+'git diff-index' [-m] [--cached] [<common diff options>] <tree> [<path>...]
 
 DESCRIPTION
 -----------
@@ -22,7 +22,7 @@ OPTIONS
 -------
 include::diff-options.txt[]
 
-<tree-ish>::
+<tree>::
 	The id of a tree object to diff against.
 
 --cached::
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 5d0310b..e566188 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -11,13 +11,13 @@ SYNOPSIS
 [verse]
 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
 	      [-t] [-r] [-c | --cc] [--root] [<common diff options>]
-	      <tree-ish> [<tree-ish>] [<path>...]
+	      <tree> [<tree>] [<path>...]
 
 DESCRIPTION
 -----------
 Compares the content and mode of the blobs found via two tree objects.
 
-If there is only one <tree-ish> given, the commit is compared with its parents
+If there is only one <tree> given, the commit is compared with its parents
 (see --stdin below).
 
 Note that 'git diff-tree' can use the tree encapsulated in a commit object.
@@ -26,7 +26,7 @@ OPTIONS
 -------
 include::diff-options.txt[]
 
-<tree-ish>::
+<tree>::
 	The id of a tree object.
 
 <path>...::
@@ -48,7 +48,7 @@ include::diff-options.txt[]
 
 --stdin::
 	When '--stdin' is specified, the command does not take
-	<tree-ish> arguments from the command line.  Instead, it
+	<tree> arguments from the command line.  Instead, it
 	reads lines containing <sha1>'s: either two trees, one commit, or
 	multiple commits from its standard input.  (Use a single space
 	as separator.)
@@ -91,7 +91,7 @@ include::pretty-options.txt[]
 -c::
 	This flag changes the way a merge commit is displayed
 	(which means it is useful only when the command is given
-	one <tree-ish>, or '--stdin').  It shows the differences
+	one <tree>, or '--stdin').  It shows the differences
 	from each of the parents to the merge result simultaneously
 	instead of showing pairwise diff between a parent and the
 	result one at a time (which is what the '-m' option does).
@@ -121,13 +121,13 @@ Limiting Output
 If you're only interested in differences in a subset of files, for
 example some architecture-specific files, you might do:
 
-	git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
+	git diff-tree -r <tree> <tree> arch/ia64 include/asm-ia64
 
 and it will only show you what changed in those two directories.
 
 Or if you are searching for what changed in just `kernel/sched.c`, just do
 
-	git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
+	git diff-tree -r <tree> <tree> kernel/sched.c
 
 and it will ignore all differences to other files.
 
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 723a648..4582179 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -65,7 +65,7 @@ forced by --no-index.
 Just in case if you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
 for the last two forms that use ".." notations, can be any
-<tree-ish>.
+<tree>.
 
 For a more complete list of ways to spell <commit>, see
 "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 02d6306..4b32322 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -21,7 +21,7 @@ SYNOPSIS
 	   [-A <post-context>] [-B <pre-context>] [-C <context>]
 	   [-f <file>] [-e] <pattern>
 	   [--and|--or|--not|(|)|-e <pattern>...]
-	   [--cached | --no-index | <tree-ish>...]
+	   [--cached | --no-index | <tree>...]
 	   [--] [<pathspec>...]
 
 DESCRIPTION
@@ -168,7 +168,7 @@ OPTIONS
 	Do not output matched lines; instead, exit with status 0 when
 	there is a match and with non-zero status when there isn't.
 
-<tree-ish>...::
+<tree>...::
 	Instead of searching tracked files in the working tree, search
 	blobs in the given trees.
 
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..ed63f21 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -16,7 +16,7 @@ SYNOPSIS
 		[-X <file>|--exclude-from=<file>]
 		[--exclude-per-directory=<file>]
 		[--exclude-standard]
-		[--error-unmatch] [--with-tree=<tree-ish>]
+		[--error-unmatch] [--with-tree=<tree>]
 		[--full-name] [--abbrev] [--] [<file>]\*
 
 DESCRIPTION
@@ -98,11 +98,11 @@ OPTIONS
 	If any <file> does not appear in the index, treat this as an
 	error (return 1).
 
---with-tree=<tree-ish>::
+--with-tree=<tree>::
 	When using --error-unmatch to expand the user supplied
 	<file> (i.e. path pattern) arguments to paths, pretend
 	that paths which were removed in the index since the
-	named <tree-ish> are still present.  Using this option
+	named <tree> are still present.  Using this option
 	with `-s` or `-u` options does not make any sense.
 
 -t::
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 1f89d36..4964787 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git ls-tree' [-d] [-r] [-t] [-l] [-z]
 	    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]
-	    <tree-ish> [paths...]
+	    <tree> [paths...]
 
 DESCRIPTION
 -----------
@@ -35,7 +35,7 @@ in the current working directory.  Note that:
 
 OPTIONS
 -------
-<tree-ish>::
+<tree>::
 	Id of a tree-ish.
 
 -d::
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 567671c..979793e 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -16,7 +16,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Reads the tree information given by <tree-ish> into the index,
+Reads the tree information given by <tree> into the index,
 but does not actually *update* any of the files it "caches". (see:
 linkgit:git-checkout-index[1])
 
@@ -272,7 +272,7 @@ merge. The different stages represent the "result tree" (stage 0, aka
 you are trying to merge (stage 2 and 3 respectively).
 
 The order of stages 1, 2 and 3 (hence the order of three
-<tree-ish> command line arguments) are significant when you
+<tree> command line arguments) are significant when you
 start a 3-way merge with an index file that is already
 populated.  Here is an outline of how the algorithm works:
 
diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt
index 3c786bd..6d0a746 100644
--- a/Documentation/git-tar-tree.txt
+++ b/Documentation/git-tar-tree.txt
@@ -8,7 +8,7 @@ git-tar-tree - Create a tar archive of the files in the named tree object
 
 SYNOPSIS
 --------
-'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ]
+'git tar-tree' [--remote=<repo>] <tree> [ <base> ]
 
 DESCRIPTION
 -----------
@@ -29,7 +29,7 @@ It can be extracted using 'git get-tar-commit-id'.
 OPTIONS
 -------
 
-<tree-ish>::
+<tree>::
 	The tree or commit to produce tar archive for.  If it is
 	the object name of a commit object.
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 55f3842..eb87edb 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -430,7 +430,10 @@ Identifier Terminology
 	Indicates a commit-type <object>.
 
 <tree>::
-	Indicates a tree-type <object>.
+	Indicates a tree-type <object>, or a <tag> or <commit> that points at
+	a <tree>.  A command that takes a <tree> argument ultimately
+	wants to operate on a tree object but automatically dereferences
+	objects until it finds a tree.
 
 <blob>::
 	Indicates a blob-type <object>.
@@ -443,12 +446,6 @@ Identifier Terminology
 	until it finds a commit.
 	A <rev> is another name for a <commit-ish>.
 
-<tree-ish>::
-	Indicates a <tree>, or a <tag> or <commit> that points at a
-	<tree-ish>.  A command that takes a <tree-ish> argument ultimately
-	wants to operate on a tree object but automatically dereferences
-	objects until it finds a tree.
-
 <type>::
 	Indicates that an object type is required.
 	Currently one of: `blob`, `tree`, `commit`, or `tag`.
diff --git a/archive.c b/archive.c
index d700af3..4fefb64 100644
--- a/archive.c
+++ b/archive.c
@@ -7,9 +7,9 @@
 #include "unpack-trees.h"
 
 static char const * const archive_usage[] = {
-	"git archive [options] <tree-ish> [path...]",
+	"git archive [options] <tree> [path...]",
 	"git archive --list",
-	"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]",
+	"git archive --remote <repo> [--exec <cmd>] [options] <tree> [path...]",
 	"git archive --remote <repo> [--exec <cmd>] --list",
 	NULL
 };
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 770baa2..225e515 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)
 		    typename(expect));
 }
 
-static const char commit_tree_usage[] = "git commit-tree <tree-ish> [-p <commit>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <tree> [-p <commit>]* < changelog";
 
 static void new_parent(struct commit *parent, struct commit_list **parents_p)
 {
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index 0483749..5c4c5ce 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -6,7 +6,7 @@
 
 static const char diff_cache_usage[] =
 "git diff-index [-m] [--cached] "
-"[<common diff options>] <tree-ish> [<path>...]"
+"[<common diff options>] <tree> [<path>...]"
 COMMON_DIFF_OPTIONS_HELP;
 
 int cmd_diff_index(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 2380c21..e446dd5 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -87,7 +87,7 @@ static int diff_tree_stdin(char *line)
 
 static const char diff_tree_usage[] =
 "git diff-tree [--stdin] [-m] [-c] [--cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
-"[<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"[<common diff options>] <tree> [<tree>] [<path>...]\n"
 "  -r            diff recursively\n"
 "  --root        include the initial commit as diff against /dev/null\n"
 COMMON_DIFF_OPTIONS_HELP;
diff --git a/builtin/ls-files.c b/builtin/ls-files.c
index b065061..6dc885d 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -513,7 +513,7 @@ int cmd_ls_files(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN(0, "error-unmatch", &error_unmatch,
 			"if any <file> is not in the index, treat this as an error"),
 		OPT_STRING(0, "with-tree", &with_tree, "tree-ish",
-			"pretend that paths removed since <tree-ish> are still present"),
+			"pretend that paths removed since <tree> are still present"),
 		OPT__ABBREV(&abbrev),
 		OPT_END()
 	};
diff --git a/builtin/ls-tree.c b/builtin/ls-tree.c
index 4484185..8a52e42 100644
--- a/builtin/ls-tree.c
+++ b/builtin/ls-tree.c
@@ -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> [path...]",
 	NULL
 };
 
diff --git a/builtin/tar-tree.c b/builtin/tar-tree.c
index 3f1e701..abdcd0b 100644
--- a/builtin/tar-tree.c
+++ b/builtin/tar-tree.c
@@ -8,7 +8,7 @@
 #include "quote.h"
 
 static const char tar_tree_usage[] =
-"git tar-tree [--remote=<repo>] <tree-ish> [basedir]\n"
+"git tar-tree [--remote=<repo>] <tree> [basedir]\n"
 "*** Note that this command is now deprecated; use \"git archive\" instead.";
 
 static const char builtin_get_tar_commit_id_usage[] =
diff --git a/git-svn.perl b/git-svn.perl
index 1a26843..c80eb49 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -997,7 +997,7 @@ sub cmd_multi_fetch {
 sub cmd_commit_diff {
 	my ($ta, $tb, $url) = @_;
 	my $usage = "Usage: $0 commit-diff -r<revision> ".
-	            "<tree-ish> <tree-ish> [<URL>]";
+	            "<tree> <tree> [<URL>]";
 	fatal($usage) if (!defined $ta || !defined $tb);
 	my $svn_path = '';
 	if (!defined $url) {
diff --git a/t/t4100/t-apply-3.patch b/t/t4100/t-apply-3.patch
index 90cdbaa..c702866 100644
--- a/t/t4100/t-apply-3.patch
+++ b/t/t4100/t-apply-3.patch
@@ -12,8 +12,8 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
  
  SYNOPSIS
  --------
--'git-ls-tree' [-r] [-z] <tree-ish> [paths...]
-+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
+-'git-ls-tree' [-r] [-z] <tree> [paths...]
++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...]
  
  DESCRIPTION
  -----------
@@ -24,7 +24,7 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
  
  OPTIONS
  -------
- <tree-ish>::
+ <tree>::
  	Id of a tree.
  
 +-d::
@@ -485,7 +485,7 @@ dissimilarity index 82%
 +}
 +
 +static const char *ls_tree_usage =
-+	"git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]";
++	"git-ls-tree [-d] [-r] [-z] <tree> [path...]";
 +
 +int main(int argc, char **argv)
 +{
diff --git a/t/t4100/t-apply-7.patch b/t/t4100/t-apply-7.patch
index 07c6589..bf8737b 100644
--- a/t/t4100/t-apply-7.patch
+++ b/t/t4100/t-apply-7.patch
@@ -11,8 +11,8 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
  
  SYNOPSIS
  --------
--'git-ls-tree' [-r] [-z] <tree-ish> [paths...]
-+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
+-'git-ls-tree' [-r] [-z] <tree> [paths...]
++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...]
  
  DESCRIPTION
  -----------
@@ -23,7 +23,7 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
  
  OPTIONS
  -------
- <tree-ish>::
+ <tree>::
  	Id of a tree.
  
 +-d::
@@ -415,7 +415,7 @@ diff a/ls-tree.c b/ls-tree.c
  
 -static const char *ls_tree_usage = "git-ls-tree [-r] [-z] <key> [paths...]";
 +static const char *ls_tree_usage =
-+	"git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]";
++	"git-ls-tree [-d] [-r] [-z] <tree> [path...]";
  
  int main(int argc, char **argv)
  {
-- 
1.7.0.2

[PATCH/RFC 08/12] http-fetch docs: use <commit-id> consistently

[Mark Lodato]

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
It says that it can be "the filename under ...", but I couldn't get that 
to work.  Can anyone explain how to use something other than a SHA-1?

 Documentation/git-http-fetch.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt
index d91cb7f..93449fd 100644
--- a/Documentation/git-http-fetch.txt
+++ b/Documentation/git-http-fetch.txt
@@ -8,7 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP
 
 SYNOPSIS
 --------
-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url>
+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit-id> <url>
 
 DESCRIPTION
 -----------
@@ -16,7 +16,7 @@ Downloads a remote git repository via HTTP.
 
 OPTIONS
 -------
-commit-id::
+<commit-id>::
         Either the hash or the filename under [URL]/refs/ to
         pull.
 
-- 
1.7.0.2

[PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>

[Mark Lodato]

There exist no commands that accept a <commit> but not a <commit-ish>,
so there is no reason to use the latter term anymore.  Instead, use
<commit> everywhere the term <commit-ish>, <committish>, commit-ish, or
comittish was used.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
This was a little harder than the removal of tree-ish, since commit-ish 
was used not only in the documentation but in the code.  I tried to 
replace the term without losing meaning, but the comments in particular 
should be examined to see if they are just as clear as before.

The following commands already use the term <commit>, but actually 
accept a <commit-ish>:
	bisect, branch, cherry-pick, commit, merge, tag, diff, difftool, 
	format-patch, merge-base, rebase, reset, rev-list, revert

The only commands left that do not accept a commit-ish are:
	http-fetch accepts a <commit-id>, as noted previously
	commit-tree accepts an old <commit> (no tag objects)

 Documentation/git-describe.txt               |   14 +++++++-------
 Documentation/git-fast-import.txt            |   22 +++++++++++-----------
 Documentation/git-name-rev.txt               |    2 +-
 Documentation/git-rebase.txt                 |    2 +-
 Documentation/git-shortlog.txt               |    2 +-
 Documentation/git.txt                        |   15 ++++++---------
 Documentation/gitcli.txt                     |    2 +-
 Documentation/howto/revert-branch-rebase.txt |    2 +-
 builtin/describe.c                           |    4 ++--
 builtin/merge.c                              |    2 +-
 builtin/revert.c                             |    4 ++--
 contrib/examples/git-merge.sh                |    2 +-
 contrib/examples/git-reset.sh                |    2 +-
 contrib/examples/git-revert.sh               |    4 ++--
 fast-import.c                                |   16 ++++++++--------
 remote.c                                     |    4 ++--
 16 files changed, 48 insertions(+), 51 deletions(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 6fc5323..f272fa6 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit
 SYNOPSIS
 --------
 [verse]
-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>...
+'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit>...
 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
 
 DESCRIPTION
@@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1].
 
 OPTIONS
 -------
-<committish>...::
-	Committish object names to describe.
+<commit>...::
+	Commit object names to describe.
 
 --dirty[=<mark>]::
 	Describe the working tree.
@@ -57,7 +57,7 @@ OPTIONS
 
 --candidates=<n>::
 	Instead of considering only the 10 most recent tags as
-	candidates to describe the input committish consider
+	candidates to describe the input commit consider
 	up to <n> candidates.  Increasing <n> above 10 will take
 	slightly longer but may produce a more accurate result.
 	An <n> of 0 will cause only exact matches to be output.
@@ -136,7 +136,7 @@ be sufficient to disambiguate these commits.
 SEARCH STRATEGY
 ---------------
 
-For each committish supplied, 'git describe' will first look for
+For each commit supplied, 'git describe' will first look for
 a tag which tags exactly that commit.  Annotated tags will always
 be preferred over lightweight tags, and tags with newer dates will
 always be preferred over tags with older dates.  If an exact match
@@ -145,10 +145,10 @@ is found, its name will be output and searching will stop.
 If an exact match was not found, 'git describe' will walk back
 through the commit history to locate an ancestor commit which
 has been tagged.  The ancestor's tag will be output along with an
-abbreviation of the input committish's SHA1.
+abbreviation of the input commit's SHA1.
 
 If multiple tags were found during the walk then the tag which
-has the fewest commits different from the input committish will be
+has the fewest commits different from the input commit will be
 selected and output.  Here fewest commits different is defined as
 the number of commits which would be shown by `git log tag..input`
 will be the smallest number of commits possible.
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 19082b0..bdf369a 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -340,8 +340,8 @@ change to the project.
 	('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
 	'committer' (SP <name>)? SP LT <email> GT SP <when> LF
 	data
-	('from' SP <committish> LF)?
-	('merge' SP <committish> LF)?
+	('from' SP <commit> LF)?
+	('merge' SP <commit> LF)?
 	(filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
 	LF?
 ....
@@ -418,9 +418,9 @@ as the current commit on that branch is automatically assumed to
 be the first ancestor of the new commit.
 
 As `LF` is not valid in a Git refname or SHA-1 expression, no
-quoting or escaping syntax is supported within `<committish>`.
+quoting or escaping syntax is supported within `<commit>`.
 
-Here `<committish>` is any of the following:
+Here `<commit>` is any of the following:
 
 * The name of an existing branch already in fast-import's internal branch
   table.  If fast-import doesn't know the name, it's treated as a SHA-1
@@ -465,7 +465,7 @@ additional ancestors (forming a 16-way merge).  For this reason
 it is suggested that frontends do not use more than 15 `merge`
 commands per commit; 16, if starting a new, empty branch.
 
-Here `<committish>` is any of the commit specification expressions
+Here `<commit>` is any of the commit specification expressions
 also accepted by `from` (see above).
 
 `filemodify`
@@ -632,7 +632,7 @@ External data format::
 	commit that is to be annotated.
 +
 ....
-	'N' SP <dataref> SP <committish> LF
+	'N' SP <dataref> SP <commit> LF
 ....
 +
 Here `<dataref>` can be either a mark reference (`:<idnum>`)
@@ -645,13 +645,13 @@ Inline data format::
 	command.
 +
 ....
-	'N' SP 'inline' SP <committish> LF
+	'N' SP 'inline' SP <commit> LF
 	data
 ....
 +
 See below for a detailed description of the `data` command.
 
-In both formats `<committish>` is any of the commit specification
+In both formats `<commit>` is any of the commit specification
 expressions also accepted by `from` (see above).
 
 `mark`
@@ -682,7 +682,7 @@ lightweight (non-annotated) tags see the `reset` command below.
 
 ....
 	'tag' SP <name> LF
-	'from' SP <committish> LF
+	'from' SP <commit> LF
 	'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
 	data
 ....
@@ -727,11 +727,11 @@ branch from an existing commit without creating a new commit.
 
 ....
 	'reset' SP <ref> LF
-	('from' SP <committish> LF)?
+	('from' SP <commit> LF)?
 	LF?
 ....
 
-For a detailed description of `<ref>` and `<committish>` see above
+For a detailed description of `<ref>` and `<commit>` see above
 under `commit` and `from`.
 
 The `LF` after the command is optional (it used to be required).
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt
index 2108237..40af544 100644
--- a/Documentation/git-name-rev.txt
+++ b/Documentation/git-name-rev.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git name-rev' [--tags] [--refs=<pattern>]
-	       ( --all | --stdin | <committish>... )
+	       ( --all | --stdin | <commit>... )
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 823f2a4..e32c393 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -168,7 +168,7 @@ would result in the removal of commits F and G:
 
 This is useful if F and G were flawed in some way, or should not be
 part of topicA.  Note that the argument to --onto and the <upstream>
-parameter can be any valid commit-ish.
+parameter can be any valid <commit>.
 
 In case of conflict, 'git rebase' will stop at the first problematic commit
 and leave conflict markers in the tree.  You can use 'git diff' to locate
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index dfd4d0c..61dc039 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
-'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...]
+'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<commit>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index eb87edb..b7c89f9 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -426,8 +426,13 @@ Identifier Terminology
 	Indicates a tag-type <object>.  This is an annotated tag object, as
 	opposed to <tagname>, which can refer to any type of object.
 
+<rev>::
 <commit>::
-	Indicates a commit-type <object>.
+	Indicates a commit-type <object>, or a <tag> that points at a <commit>.
+	A command that takes a <commit> argument ultimately wants to
+	operate on a commit object but automatically dereferences objects
+	until it finds a commit.
+	A <rev> is another name for a <commit>.
 
 <tree>::
 	Indicates a tree-type <object>, or a <tag> or <commit> that points at
@@ -438,14 +443,6 @@ Identifier Terminology
 <blob>::
 	Indicates a blob-type <object>.
 
-<rev>::
-<commit-ish>::
-	Indicates a <commit>, or a <tag> that points at a <commit-ish>.
-	A command that takes a <commit-ish> argument ultimately wants to
-	operate on a commit object but automatically dereferences objects
-	until it finds a commit.
-	A <rev> is another name for a <commit-ish>.
-
 <type>::
 	Indicates that an object type is required.
 	Currently one of: `blob`, `tree`, `commit`, or `tag`.
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 6928724..de0630f 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -81,7 +81,7 @@ couple of magic command line options:
 +
 ---------------------------------------------
 $ git describe -h
-usage: git describe [options] <committish>*
+usage: git describe [options] <commit>*
 
     --contains            find the tag that comes after the commit
     --debug               debug search strategy on stderr
diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt
index 8c32da6..5272bb0 100644
--- a/Documentation/howto/revert-branch-rebase.txt
+++ b/Documentation/howto/revert-branch-rebase.txt
@@ -160,7 +160,7 @@ $ git pull . master
 Packing 0 objects
 Unpacking 0 objects
 
-* committish: e3a693c...	refs/heads/master from .
+* commit: e3a693c...	refs/heads/master from .
 Trying to merge e3a693c... into 8c1f5f0... using 10d781b...
 Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
  cache.h        |    8 ++++----
diff --git a/builtin/describe.c b/builtin/describe.c
index 71be2a9..4ece73f 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -11,7 +11,7 @@
 #define MAX_TAGS	(FLAG_BITS - 1)
 
 static const char * const describe_usage[] = {
-	"git describe [options] <committish>*",
+	"git describe [options] <commit>*",
 	"git describe [options] --dirty",
 	NULL
 };
@@ -386,7 +386,7 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
 			dirty = NULL;
 		describe("HEAD", 1);
 	} else if (dirty) {
-		die("--dirty is incompatible with committishes");
+		die("--dirty is incompatible with commits");
 	} else {
 		while (argc-- > 0) {
 			describe(*argv++, argc == 0);
diff --git a/builtin/merge.c b/builtin/merge.c
index 3aaec7b..8d62424 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -940,7 +940,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 	 * This could be traditional "merge <msg> HEAD <commit>..."  and
 	 * the way we can tell it is to see if the second token is HEAD,
 	 * but some people might have misused the interface and used a
-	 * committish that is the same as HEAD there instead.
+	 * <commit> that is the same as HEAD there instead.
 	 * Traditional format never would have "-m" so it is an
 	 * additional safety measure to check for it.
 	 */
diff --git a/builtin/revert.c b/builtin/revert.c
index eff5268..e06d2a0 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -26,12 +26,12 @@
  */
 
 static const char * const revert_usage[] = {
-	"git revert [options] <commit-ish>",
+	"git revert [options] <commit>",
 	NULL
 };
 
 static const char * const cherry_pick_usage[] = {
-	"git cherry-pick [options] <commit-ish>",
+	"git cherry-pick [options] <commit>",
 	NULL
 };
 
diff --git a/contrib/examples/git-merge.sh b/contrib/examples/git-merge.sh
index 8f617fc..5aeee46 100755
--- a/contrib/examples/git-merge.sh
+++ b/contrib/examples/git-merge.sh
@@ -221,7 +221,7 @@ fi
 
 # This could be traditional "merge <msg> HEAD <commit>..."  and the
 # way we can tell it is to see if the second token is HEAD, but some
-# people might have misused the interface and used a committish that
+# people might have misused the interface and used a <commit> that
 # is the same as HEAD there instead.  Traditional format never would
 # have "-m" so it is an additional safety measure to check for it.
 
diff --git a/contrib/examples/git-reset.sh b/contrib/examples/git-reset.sh
index bafeb52..d287a80 100755
--- a/contrib/examples/git-reset.sh
+++ b/contrib/examples/git-reset.sh
@@ -2,7 +2,7 @@
 #
 # Copyright (c) 2005, 2006 Linus Torvalds and Junio C Hamano
 #
-USAGE='[--mixed | --soft | --hard]  [<commit-ish>] [ [--] <paths>...]'
+USAGE='[--mixed | --soft | --hard]  [<commit>] [ [--] <paths>...]'
 SUBDIRECTORY_OK=Yes
 . git-sh-setup
 set_reflog_action "reset $*"
diff --git a/contrib/examples/git-revert.sh b/contrib/examples/git-revert.sh
index 49f0032..c543add 100755
--- a/contrib/examples/git-revert.sh
+++ b/contrib/examples/git-revert.sh
@@ -9,12 +9,12 @@ case "$0" in
 	test -t 0 && edit=-e
 	replay=
 	me=revert
-	USAGE='[--edit | --no-edit] [-n] <commit-ish>' ;;
+	USAGE='[--edit | --no-edit] [-n] <commit>' ;;
 *-cherry-pick* )
 	replay=t
 	edit=
 	me=cherry-pick
-	USAGE='[--edit] [-n] [-r] [-x] <commit-ish>'  ;;
+	USAGE='[--edit] [-n] [-r] [-x] <commit>'  ;;
 * )
 	echo >&2 "What are you talking about?"
 	exit 1 ;;
diff --git a/fast-import.c b/fast-import.c
index 309f2c5..08afdc3 100644
--- a/fast-import.c
+++ b/fast-import.c
@@ -22,8 +22,8 @@ Format of STDIN stream:
     ('author' (sp name)? sp '<' email '>' sp when lf)?
     'committer' (sp name)? sp '<' email '>' sp when lf
     commit_msg
-    ('from' sp committish lf)?
-    ('merge' sp committish lf)*
+    ('from' sp commit lf)?
+    ('merge' sp commit lf)*
     file_change*
     lf?;
   commit_msg ::= data;
@@ -41,18 +41,18 @@ Format of STDIN stream:
   file_obm ::= 'M' sp mode sp (hexsha1 | idnum) sp path_str lf;
   file_inm ::= 'M' sp mode sp 'inline' sp path_str lf
     data;
-  note_obm ::= 'N' sp (hexsha1 | idnum) sp committish lf;
-  note_inm ::= 'N' sp 'inline' sp committish lf
+  note_obm ::= 'N' sp (hexsha1 | idnum) sp commit lf;
+  note_inm ::= 'N' sp 'inline' sp commit lf
     data;
 
   new_tag ::= 'tag' sp tag_str lf
-    'from' sp committish lf
+    'from' sp commit lf
     ('tagger' (sp name)? sp '<' email '>' sp when lf)?
     tag_msg;
   tag_msg ::= data;
 
   reset_branch ::= 'reset' sp ref_str lf
-    ('from' sp committish lf)?
+    ('from' sp commit lf)?
     lf?;
 
   checkpoint ::= 'checkpoint' lf
@@ -91,7 +91,7 @@ Format of STDIN stream:
      # stream formatting is: \, " and LF.  Otherwise these values
      # are UTF8.
      #
-  committish  ::= (ref_str | hexsha1 | sha1exp_str | idnum);
+  commit      ::= (ref_str | hexsha1 | sha1exp_str | idnum);
   ref_str     ::= ref;
   sha1exp_str ::= sha1exp;
   tag_str     ::= tag;
@@ -2288,7 +2288,7 @@ static void note_change_n(struct branch *b, unsigned char old_fanout)
 	if (*p++ != ' ')
 		die("Missing space after SHA1: %s", command_buf.buf);
 
-	/* <committish> */
+	/* <commit> */
 	s = lookup_branch(p);
 	if (s) {
 		hashcpy(commit_sha1, s->sha1);
diff --git a/remote.c b/remote.c
index c70181c..3c5f8c6 100644
--- a/remote.c
+++ b/remote.c
@@ -1277,7 +1277,7 @@ void set_ref_status_for_push(struct ref *remote_refs, int send_mirror,
 		 *     to overwrite it; you would not know what you are losing
 		 *     otherwise.
 		 *
-		 * (3) if both new and old are commit-ish, and new is a
+		 * (3) if both new and old are <commit>'s, and new is a
 		 *     descendant of old, it is OK.
 		 *
 		 * (4) regardless of all of the above, removing :B is
@@ -1475,7 +1475,7 @@ int ref_newer(const unsigned char *new_sha1, const unsigned char *old_sha1)
 	struct commit_list *list, *used;
 	int found = 0;
 
-	/* Both new and old must be commit-ish and new is descendant of
+	/* Both new and old must be <commit>'s and new is descendant of
 	 * old.  Otherwise we require --force.
 	 */
 	o = deref_tag(parse_object(old_sha1), NULL, 0);
-- 
1.7.0.2

[PATCH/RFC 10/12] diff: use brackets for optional args in usage

[Mark Lodato]

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 builtin/diff.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin/diff.c b/builtin/diff.c
index ffcdd05..a716704 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -21,7 +21,7 @@ struct blobinfo {
 };
 
 static const char builtin_diff_usage[] =
-"git diff <options> <rev>{0,2} -- <path>*";
+"git diff [<options>] <rev>{0,2} [--] [<path>]*";
 
 static void stuff_change(struct diff_options *opt,
 			 unsigned old_mode, unsigned new_mode,
-- 
1.7.0.2

[PATCH/RFC 11/12] docs: use ... instead of * for multiplicity

[Mark Lodato]

In the documentation and in usage messages, use [<foo>...] to denote
arguments that can occur zero or more times, rather than [<foo>]* or the
like.  The '...' should come inside the brackets if there is a single
word (e.g., "[<file>...]"), but outside the brackets if there is more
than one word (e.g. "[-p <commit>]...").

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
I don't like having to put the ellipses inside and outside the brackets, 
but I couldn't come up with anything that was more clear.  Leaving the 
star just for these cases is a worse alternative in my opinion, since 
then it would be even more of an oddball.

By the way, can anyone explain why git-pack-objects(1) has
	[--revs [--unpacked | --all]*]
and not the following?
	[--revs] [--unpacked] [--all]

 Documentation/git-checkout-index.txt |    2 +-
 Documentation/git-commit-tree.txt    |    2 +-
 Documentation/git-for-each-ref.txt   |    2 +-
 Documentation/git-fsck.txt           |    2 +-
 Documentation/git-ls-files.txt       |    2 +-
 Documentation/git-merge-index.txt    |    2 +-
 Documentation/git-mergetool.txt      |    2 +-
 Documentation/git-pack-objects.txt   |    2 +-
 Documentation/git-relink.txt         |    2 +-
 Documentation/git-update-index.txt   |    4 ++--
 Documentation/gitcli.txt             |    2 +-
 builtin/commit-tree.c                |    2 +-
 builtin/describe.c                   |    2 +-
 builtin/diff.c                       |    2 +-
 builtin/ls-files.c                   |    2 +-
 builtin/merge-index.c                |    2 +-
 builtin/pack-objects.c               |    2 +-
 17 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index d6aa6e1..0c0a9c1 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 		   [--stage=<number>|all]
 		   [--temp]
 		   [-z] [--stdin]
-		   [--] [<file>]\*
+		   [--] [<file>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 6188854..55f0390 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -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
 -----------
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 7e83288..993f79f 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -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
 -----------
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 86f9b2b..38207a1 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
-	 [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>*]
+	 [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index ed63f21..cbd6661 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -17,7 +17,7 @@ SYNOPSIS
 		[--exclude-per-directory=<file>]
 		[--exclude-standard]
 		[--error-unmatch] [--with-tree=<tree>]
-		[--full-name] [--abbrev] [--] [<file>]\*
+		[--full-name] [--abbrev] [--] [<file>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt
index 4d266de..3716309 100644
--- a/Documentation/git-merge-index.txt
+++ b/Documentation/git-merge-index.txt
@@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging
 
 SYNOPSIS
 --------
-'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*)
+'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>...)
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index 55735fa..bd6b301 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -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
 -----------
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 8ed09c0..a19aa4b 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -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
 
 
diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt
index 25ff8f9..362a5dc 100644
--- a/Documentation/git-relink.txt
+++ b/Documentation/git-relink.txt
@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories
 
 SYNOPSIS
 --------
-'git relink' [--safe] <dir> [<dir>]\* <master_dir>
+'git relink' [--safe] <dir> [<dir>...] <master_dir>
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 68dc187..2753d73 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git update-index'
 	     [--add] [--remove | --force-remove] [--replace]
 	     [--refresh] [-q] [--unmerged] [--ignore-missing]
-	     [--cacheinfo <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
 -----------
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index de0630f..eb51ffc 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -81,7 +81,7 @@ couple of magic command line options:
 +
 ---------------------------------------------
 $ git describe -h
-usage: git describe [options] <commit>*
+usage: git describe [options] <commit>...
 
     --contains            find the tag that comes after the commit
     --debug               debug search strategy on stderr
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 225e515..22ceff1 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)
 		    typename(expect));
 }
 
-static const char commit_tree_usage[] = "git commit-tree <tree> [-p <commit>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <tree> [-p <commit>]... < changelog";
 
 static void new_parent(struct commit *parent, struct commit_list **parents_p)
 {
diff --git a/builtin/describe.c b/builtin/describe.c
index 4ece73f..2bba2ba 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -11,7 +11,7 @@
 #define MAX_TAGS	(FLAG_BITS - 1)
 
 static const char * const describe_usage[] = {
-	"git describe [options] <commit>*",
+	"git describe [options] <commit>...",
 	"git describe [options] --dirty",
 	NULL
 };
diff --git a/builtin/diff.c b/builtin/diff.c
index a716704..f73da93 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -21,7 +21,7 @@ struct blobinfo {
 };
 
 static const char builtin_diff_usage[] =
-"git diff [<options>] <rev>{0,2} [--] [<path>]*";
+"git diff [<options>] <rev>{0,2} [--] [<path>...]";
 
 static void stuff_change(struct diff_options *opt,
 			 unsigned old_mode, unsigned new_mode,
diff --git a/builtin/ls-files.c b/builtin/ls-files.c
index 6dc885d..c57c93e 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -414,7 +414,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
 };
 
diff --git a/builtin/merge-index.c b/builtin/merge-index.c
index 2c4cf5e..c683bbd 100644
--- a/builtin/merge-index.c
+++ b/builtin/merge-index.c
@@ -76,7 +76,7 @@ int cmd_merge_index(int argc, const char **argv, const char *prefix)
 	signal(SIGCHLD, SIG_DFL);
 
 	if (argc < 3)
-		usage("git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>*)");
+		usage("git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>...)");
 
 	read_cache();
 
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 9780258..19d9f09 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -28,7 +28,7 @@ static const char pack_usage[] =
   "        [--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]";
-- 
1.7.0.2

[PATCH/RFC 12/12] diff docs: remove <rev>{0,2} notation

[Mark Lodato]

This notation is not used anywhere else, so it can be confusing when
first encountered.  Instead, prefer the slightly longer but just as
clear "[<rev> [<rev>]]", which is consistent with other commands.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
When I first ran `git diff -h` and I saw the old syntax, I was rather
confused.  It took me a minute to realize that this was the regular
expression syntax.  I think it's best to stick with one syntax, even if
it is a bit more verbose.

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

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 4582179..e2d868d 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -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
 -----------
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 8250bad..a02e3b5 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -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
 -----------
diff --git a/builtin/diff.c b/builtin/diff.c
index f73da93..e2e2efc 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -21,7 +21,7 @@ struct blobinfo {
 };
 
 static const char builtin_diff_usage[] =
-"git diff [<options>] <rev>{0,2} [--] [<path>...]";
+"git diff [<options>] [<rev> [<rev>]] [--] [<path>...]";
 
 static void stuff_change(struct diff_options *opt,
 			 unsigned old_mode, unsigned new_mode,
-- 
1.7.0.2

Re: [PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname>

[Junio C Hamano]

Mark Lodato <lodatom@gmail.com> writes:

> In the documentation and user messages, differentiate between <tag>,
> which means an actual annotated tag object, and <tagname>, which is
> a revision specifier for refs/tags/<tagname>.

Do we talk about annotated tag objects that often?

I would instead recommend you to consistently use "tag object", "tag name"
(the string that appears on "tag " line in a "tag object"), and "tag" (the
refs that live under refs/tags/ namespace.

Re: [PATCH/RFC 01/12] commit-tree: allow indirect tree references

[Junio C Hamano]

Mark Lodato <lodatom@gmail.com> writes:

> 'git commit-tree' was the last remaining built-in to accept a <tree> but
> not a <tree-ish> (an indirect tree reference through a commit or tag
> object.)

Historically we deliberately chose not to DWIM things down to tree for
this plumbing command to catch mistakes by Porcelain scripts
(e.g. arguments given in wrong order---the order of commit-tree's
arguments are, eh, unintuitive).

I do not think that matters much anymore---I do not think this patch
is unsafe.

Re: [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>

[Junio C Hamano]

Mark Lodato <lodatom@gmail.com> writes:

>  Documentation/git-grep.txt |    4 ++--
>  builtin/commit-tree.c      |    2 +-

Yuck; plonk, try again.

Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>

[Junio C Hamano]

Mark Lodato <lodatom@gmail.com> writes:

> There exist no commands that accept a <commit> but not a <commit-ish>,

I have one worry about this and [07/12].  The droppage of -ish would make
sense from the point of view of describing command line arguments,
i.e. what you can give to the commands, but it would make it impossible
for us to talk about places that _only_ tree not arbitrary tree-ish can
appear.  For example, don't we ever talk about something like this?

    A tree object is a sequence of records, each of which describes the
    type of entry, object name, and the name of the entry in the tree.
    When the type is "tree", the object name must name a tree, when the
    type is "gitlink", the object name must name a commit, ...

Other than that small worry, I think the series goes in the right
direction.

Re: [PATCH/RFC 01/12] commit-tree: allow indirect tree references

[Mark Lodato]

On Sat, Mar 13, 2010 at 5:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> 'git commit-tree' was the last remaining built-in to accept a <tree> but
>> not a <tree-ish> (an indirect tree reference through a commit or tag
>> object.)
>
> Historically we deliberately chose not to DWIM things down to tree for
> this plumbing command to catch mistakes by Porcelain scripts
> (e.g. arguments given in wrong order---the order of commit-tree's
> arguments are, eh, unintuitive).
>
> I do not think that matters much anymore---I do not think this patch
> is unsafe.

I thought about that, but upon investigation, the _only_ command that
doesn't DWIM with respect to object types (<tree> or <commit>) is
commit-tree.  So, I thought it might make sense to treat this like all
the other commands.  On the other hand, it may be a good idea to keep
this special for safety.  If so, then I would just amend the
documentation to note that it does not automatically dereference
commit or tag objects.

Re: [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>

[Mark Lodato]

On Sat, Mar 13, 2010 at 5:59 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>>  Documentation/git-grep.txt |    4 ++--
>>  builtin/commit-tree.c      |    2 +-
>
> Yuck; plonk, try again.

Oops, sorry about that.  I'll fix it in v2, since the commit-tree.c
part should go in the previous patch.

Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>

[Mark Lodato]

On Sat, Mar 13, 2010 at 6:05 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> There exist no commands that accept a <commit> but not a <commit-ish>,
>
> I have one worry about this and [07/12].  The droppage of -ish would make
> sense from the point of view of describing command line arguments,
> i.e. what you can give to the commands, but it would make it impossible
> for us to talk about places that _only_ tree not arbitrary tree-ish can
> appear.  For example, don't we ever talk about something like this?
>
>    A tree object is a sequence of records, each of which describes the
>    type of entry, object name, and the name of the entry in the tree.
>    When the type is "tree", the object name must name a tree, when the
>    type is "gitlink", the object name must name a commit, ...
>
> Other than that small worry, I think the series goes in the right
> direction.

Yes, it would probably be best to leave the -ish terms in the glossary
(which I evidently did by mistake) and in the comments and
documentation, but just not use them as an identifier in angle
brackets.  For example, a command accepting a <tree> would also accept
commits or tags unless otherwise noted, but the term "tree object"
would still only refer to an actual tree object, not a tree-ish.  When
it is unclear, one can use the -ish term, like I just did in that last
sentence.

I'll wait a few days to see if there are any more comments, and then
I'll try fixing up this series.