[PATCHv2 0/8] docs: use metavariables consistently

[PATCHv2 0/8] docs: use metavariables consistently

[Mark Lodato]

Update the documentation and usage statements to use metavariables, such as
<commit>, more consistently.  The biggest change is to drop the <tree-ish> and
<commit-ish> (or <committish>) notation and just use <tree> or <commit>, since
every command but commit-tree accepts tree-ishes and commit-ishes.  The "-ish"
terms are still kept around in various places where it makes sense to
differentiate between an actual tree or commit and a tree-ish or commit-ish.

This is a rework of my earlier patch set from March [1], with the following
differences:

- Drop the patch to commit-tree that makes it accept a tree-ish.
- Drop the patch dealing with <tag> and <tagname>.
- Leave -ish terms in comments and in places where they make sense.
- Rebase onto master (1b97434).  Some of the patches from before have since
  been accepted from other authors.
- Fix a problem that Junio noticed with the "grep docs" patch.

[1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484

Mark Lodato (8):
  fsck docs: remove outdated and useless diagnostic
  docs: use `...' instead of `*' for multiplicity
  docs: use <sha1> to mean unabbreviated ID
  http-fetch docs: use <commit-id> consistently
  grep docs: grep accepts a <tree-ish>, not a <tree>
  docs: use <tree> instead of <tree-ish>
  docs: use <commit> instead of <commit-ish>
  describe docs: note that <commit> is optional

 Documentation/RelNotes/1.6.2.4.txt    |    2 +-
 Documentation/diff-format.txt         |   10 +++++-----
 Documentation/diff-generate-patch.txt |    2 +-
 Documentation/git-archive.txt         |    4 ++--
 Documentation/git-cat-file.txt        |    2 +-
 Documentation/git-checkout.txt        |   16 ++++++++--------
 Documentation/git-commit-tree.txt     |    3 ++-
 Documentation/git-describe.txt        |   15 ++++++++-------
 Documentation/git-diff-index.txt      |    4 ++--
 Documentation/git-diff-tree.txt       |   18 +++++++++---------
 Documentation/git-fast-import.txt     |   22 +++++++++++-----------
 Documentation/git-fsck.txt            |    5 +----
 Documentation/git-http-fetch.txt      |    4 ++--
 Documentation/git-ls-files.txt        |    6 +++---
 Documentation/git-ls-tree.txt         |    6 +++---
 Documentation/git-merge-index.txt     |    2 +-
 Documentation/git-merge-tree.txt      |    2 +-
 Documentation/git-name-rev.txt        |    2 +-
 Documentation/git-read-tree.txt       |   10 +++++-----
 Documentation/git-rebase.txt          |    2 +-
 Documentation/git-svn.txt             |    6 +++---
 Documentation/git-tar-tree.txt        |    4 ++--
 Documentation/git.txt                 |   27 +++++++++++++--------------
 Documentation/gitcli.txt              |    6 +++---
 Documentation/gittutorial-2.txt       |    6 ++----
 Documentation/glossary-content.txt    |    4 ++++
 archive.c                             |    4 ++--
 builtin/commit-tree.c                 |    2 +-
 builtin/describe.c                    |    4 ++--
 builtin/diff-index.c                  |    2 +-
 builtin/diff-tree.c                   |    2 +-
 builtin/ls-files.c                    |    4 ++--
 builtin/ls-tree.c                     |    2 +-
 builtin/merge-index.c                 |    2 +-
 builtin/read-tree.c                   |    2 +-
 builtin/revert.c                      |    4 ++--
 builtin/tar-tree.c                    |    2 +-
 contrib/examples/git-reset.sh         |    2 +-
 contrib/examples/git-revert.sh        |    4 ++--
 git-svn.perl                          |    6 +++---
 t/t4100/t-apply-3.patch               |    8 ++++----
 t/t4100/t-apply-7.patch               |    8 ++++----
 42 files changed, 124 insertions(+), 124 deletions(-)

-- 
1.7.3.2

[PATCH 1/8] 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.3.2

[PATCH 2/8] docs: use `...' instead of `*' for multiplicity

[Mark Lodato]

Finish the work of 0adda93 (Use parentheses and `...' where appropriate)
to follow the rules set forth in Documentation/CodingGuidelines.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-fsck.txt        |    2 +-
 Documentation/git-merge-index.txt |    2 +-
 Documentation/gitcli.txt          |    2 +-
 builtin/describe.c                |    2 +-
 builtin/merge-index.c             |    2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

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-merge-index.txt b/Documentation/git-merge-index.txt
index 921b38f..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/gitcli.txt b/Documentation/gitcli.txt
index 6928724..eb65dcf 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] <committish>...
 
     --contains            find the tag that comes after the commit
     --debug               debug search strategy on stderr
diff --git a/builtin/describe.c b/builtin/describe.c
index a0f52c1..34a8031 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -12,7 +12,7 @@
 #define MAX_TAGS	(FLAG_BITS - 1)
 
 static const char * const describe_usage[] = {
-	"git describe [options] <committish>*",
+	"git describe [options] <committish>...",
 	"git describe [options] --dirty",
 	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();
 
-- 
1.7.3.2

[PATCH 3/8] 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.
Use <tree> and <commit> in the usage statement for 'commit-tree'.

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

diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index a7e37b8..6b357a5 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 0128371..7929739 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -457,6 +457,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.
 
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index d083795..da572c3 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -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 <tree> [(-p <commit>)...] < changelog";
 
 static void new_parent(struct commit *parent, struct commit_list **parents_p)
 {
-- 
1.7.3.2

[PATCH 4/8] http-fetch docs: use <commit-id> consistently

[Mark Lodato]

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 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.3.2

[PATCH 5/8] 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 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index dab0a78..54ea24a 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -22,7 +22,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
@@ -176,7 +176,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.
 
-- 
1.7.3.2

[PATCH 6/8] docs: use <tree> instead of <tree-ish>

[Mark Lodato]

No git command, besides commit-tree, accepts only a tree and not
a tree-ish, so let us remove the latter term from common usage in the
documentation in order to reduce the amount of jargon.

The term "tree-ish" was left in the following situations:
 - all comments in the code
 - situations where "tree-ish" is being contrasted to "tree"
 - error messages, to prevent porcelains from changing
 - tests
 - the glossary

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/RelNotes/1.6.2.4.txt    |    2 +-
 Documentation/diff-format.txt         |   10 +++++-----
 Documentation/diff-generate-patch.txt |    2 +-
 Documentation/git-archive.txt         |    4 ++--
 Documentation/git-cat-file.txt        |    2 +-
 Documentation/git-checkout.txt        |   16 ++++++++--------
 Documentation/git-commit-tree.txt     |    3 ++-
 Documentation/git-diff-index.txt      |    4 ++--
 Documentation/git-diff-tree.txt       |   14 +++++++-------
 Documentation/git-grep.txt            |    4 ++--
 Documentation/git-ls-files.txt        |    6 +++---
 Documentation/git-ls-tree.txt         |    6 +++---
 Documentation/git-merge-tree.txt      |    2 +-
 Documentation/git-read-tree.txt       |   10 +++++-----
 Documentation/git-svn.txt             |    6 +++---
 Documentation/git-tar-tree.txt        |    4 ++--
 Documentation/git.txt                 |   11 ++++-------
 Documentation/gitcli.txt              |    4 ++--
 Documentation/gittutorial-2.txt       |    6 ++----
 archive.c                             |    4 ++--
 builtin/diff-index.c                  |    2 +-
 builtin/diff-tree.c                   |    2 +-
 builtin/ls-files.c                    |    4 ++--
 builtin/ls-tree.c                     |    2 +-
 builtin/read-tree.c                   |    2 +-
 builtin/tar-tree.c                    |    2 +-
 git-svn.perl                          |    6 +++---
 t/t4100/t-apply-3.patch               |    8 ++++----
 t/t4100/t-apply-7.patch               |    8 ++++----
 29 files changed, 76 insertions(+), 80 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..83272a0 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -7,13 +7,13 @@ 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>...]::
+git-diff-tree [-r] <tree-1> <tree-2> [<pattern>...]::
         compares the trees named by the two arguments.
 
 git-diff-files [<pattern>...]::
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 3ac2bea..e0802de 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -131,7 +131,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 4163a1b..bb4943f 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-cat-file.txt b/Documentation/git-cat-file.txt
index 544ba7b..4861007 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -54,7 +54,7 @@ OPTIONS
 
 --textconv::
 	Show the content as transformed by a textconv filter. In this case,
-	<object> has be of the form <treeish>:<path>, or :<path> in order
+	<object> has be of the form <tree>:<path>, or :<path> in order
 	to apply the filter to the content recorded in the index at <path>.
 
 --batch::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 880763d..0199e10 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|-B|--orphan] <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
 -----------
@@ -43,14 +43,14 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
-'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::
+'git checkout' [--patch] [<tree>] [--] <pathspec>...::
 
 	When <paths> or `--patch` are given, 'git checkout' 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
+	from 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 used to specify a specific tree-ish
+	<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.
 +
@@ -169,9 +169,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.
@@ -198,7 +198,7 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 	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 5dcf427..92687d8 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -36,7 +36,8 @@ state was.
 OPTIONS
 -------
 <tree>::
-	An existing tree object
+	An existing tree object.  Unlike other git commands, this must
+	be an actual tree object, not a commit or tag.
 
 -p <parent commit>::
 	Each '-p' indicates the id of a parent commit object.
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 6b357a5..692d83b 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-grep.txt b/Documentation/git-grep.txt
index 54ea24a..dab0a78 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -22,7 +22,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
@@ -176,7 +176,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 86abd13..1192859 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
@@ -99,11 +99,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 76ed625..b0bb226 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> [<path>...]
+	    <tree> [<path>...]
 
 DESCRIPTION
 -----------
@@ -35,8 +35,8 @@ in the current working directory.  Note that:
 
 OPTIONS
 -------
-<tree-ish>::
-	Id of a tree-ish.
+<tree>::
+	The id of a tree object.
 
 -d::
 	Show only the named tree entry itself, not its children.
diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
index f869a7f..0a9eb0d 100644
--- a/Documentation/git-merge-tree.txt
+++ b/Documentation/git-merge-tree.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Reads three treeish, and output trivial merge results and
+Reads three <tree>s, and output trivial merge results and
 conflicting stages to the standard output.  This is similar to
 what three-way 'git read-tree -m' does, but instead of storing the
 results in the index, the command outputs the entries to the
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index e88e9c2..24d9b87 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -11,12 +11,12 @@ SYNOPSIS
 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
 		[-u [--exclude-per-directory=<gitignore>] | -i]]
 		[--index-output=<file>] [--no-sparse-checkout]
-		(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
+		(--empty | <tree-1> [<tree-2> [<tree-3>]])
 
 
 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])
 
@@ -77,7 +77,7 @@ OPTIONS
 
 --prefix=<prefix>/::
 	Keep the current index contents, and read the contents
-	of named tree-ish under directory at `<prefix>`.  The
+	of named tree under directory at `<prefix>`.  The
 	original index file cannot have anything at the path
 	`<prefix>` itself, and have nothing in `<prefix>/`
 	directory.  Note that the `<prefix>/` value must end
@@ -118,7 +118,7 @@ OPTIONS
 	Instead of reading tree object(s) into the index, just empty
 	it.
 
-<tree-ish#>::
+<tree-#>::
 	The id of the tree object(s) to be read/merged.
 
 
@@ -278,7 +278,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-svn.txt b/Documentation/git-svn.txt
index 139d314..665a107 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -314,8 +314,8 @@ Any other arguments are passed directly to 'git log'
 'find-rev'::
 	When given an SVN revision number of the form 'rN', returns the
 	corresponding git commit hash (this can optionally be followed by a
-	tree-ish to specify which branch should be searched).  When given a
-	tree-ish, returns the corresponding SVN revision number.
+	<tree> to specify which branch should be searched).  When given a
+	<tree>, returns the corresponding SVN revision number.
 
 'set-tree'::
 	You should consider using 'dcommit' instead of this command.
@@ -345,7 +345,7 @@ Any other arguments are passed directly to 'git log'
 	for use after commands like "git checkout" or "git reset".
 
 'commit-diff'::
-	Commits the diff of two tree-ish arguments from the
+	Commits the diff of two <tree> arguments from the
 	command-line.  This command does not rely on being inside an `git svn
 	init`-ed repository.  This command takes three arguments, (a) the
 	original tree to diff against, (b) the new tree result, (c) the
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 7929739..376397c 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -469,17 +469,14 @@ Identifier Terminology
 	Indicates a blob object name.
 
 <tree>::
-	Indicates a tree object name.
+	Indicates a tree object name, or the name of 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
+	tag and commit objects until it finds a tree.
 
 <commit>::
 	Indicates a commit object name.
 
-<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>.
-
 <commit-ish>::
 	Indicates a commit or tag object name.  A
 	command that takes a <commit-ish> argument ultimately wants to
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index eb65dcf..eefee3d 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -15,8 +15,8 @@ DESCRIPTION
 
 This manual describes the convention used throughout git CLI.
 
-Many commands take revisions (most often "commits", but sometimes
-"tree-ish", depending on the context and command) and paths as their
+Many commands take revisions (most often <commit>s, but sometimes
+<tree>s, depending on the context and command) and paths as their
 arguments.  Here are the rules:
 
  * Revisions come first and then paths.
diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt
index 7fe5848..218b94d 100644
--- a/Documentation/gittutorial-2.txt
+++ b/Documentation/gittutorial-2.txt
@@ -209,10 +209,8 @@ Note, by the way, that lots of commands take a tree as an argument.
 But as we can see above, a tree can be referred to in many different
 ways--by the SHA1 name for that tree, by the name of a commit that
 refers to the tree, by the name of a branch whose head refers to that
-tree, etc.--and most such commands can accept any of these names.
-
-In command synopses, the word "tree-ish" is sometimes used to
-designate such an argument.
+tree, etc.--and all such commands can accept any of these names unless
+otherwise stated.
 
 The index file
 --------------
diff --git a/archive.c b/archive.c
index 1944ed4..50fb77e 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/diff-index.c b/builtin/diff-index.c
index 2eb32bd..605e326 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -7,7 +7,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 0d2a3e9..d0ea2db 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -88,7 +88,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 fb2d5f4..8592fd0 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -523,8 +523,8 @@ int cmd_ls_files(int argc, const char **argv, const char *cmd_prefix)
 			PARSE_OPT_NOARG | PARSE_OPT_NONEG, NULL },
 		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"),
+		OPT_STRING(0, "with-tree", &with_tree, "tree",
+			"pretend that paths removed since <tree> are still present"),
 		OPT__ABBREV(&abbrev),
 		OPT_BOOLEAN(0, "debug", &debug_mode, "show debugging data"),
 		OPT_END()
diff --git a/builtin/ls-tree.c b/builtin/ls-tree.c
index f73e6bd..a810d9a 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/read-tree.c b/builtin/read-tree.c
index 73c89ed..064711a 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -33,7 +33,7 @@ static int list_tree(unsigned char *sha1)
 }
 
 static const char * const read_tree_usage[] = {
-	"git read-tree [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])",
+	"git read-tree [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-1> [<tree-2> [<tree-3>]])",
 	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 177dd25..96197c0 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -172,7 +172,7 @@ my %cmd = (
 	           'username=s' => \$Git::SVN::Prompt::_username,
 	           'commit-url=s' => \$_commit_url } ],
 	'set-tree' => [ \&cmd_set_tree,
-	                "Set an SVN repository to a git tree-ish",
+	                "Set an SVN repository to a git tree",
 			{ 'stdin' => \$_stdin, %cmt_opts, %fc_opts, } ],
 	'create-ignore' => [ \&cmd_create_ignore,
 			     'Create a .gitignore per svn:ignore',
@@ -215,7 +215,7 @@ my %cmd = (
 			  'pager=s' => \$Git::SVN::Log::pager
 			} ],
 	'find-rev' => [ \&cmd_find_rev,
-	                "Translate between SVN revision numbers and tree-ish",
+	                "Translate between SVN revision numbers and trees",
 			{} ],
 	'rebase' => [ \&cmd_rebase, "Fetch and rebase your working directory",
 			{ 'merge|m|M' => \$_merge,
@@ -1002,7 +1002,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.3.2

[PATCH 7/8] docs: use <commit> instead of <commit-ish>

[Mark Lodato]

No git command accepts only a commit and not a commit-ish, so let us
remove the latter term from common usage in the documentation in order
to reduce the amount of jargon.  Note that the terms `committish' and
`commit-ish' were both previously used.

The "ish" terms were left in comments and were added to the glossary.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git-describe.txt     |   14 +++++++-------
 Documentation/git-fast-import.txt  |   22 +++++++++++-----------
 Documentation/git-name-rev.txt     |    2 +-
 Documentation/git-rebase.txt       |    2 +-
 Documentation/git.txt              |   11 ++++-------
 Documentation/gitcli.txt           |    2 +-
 Documentation/glossary-content.txt |    4 ++++
 builtin/describe.c                 |    4 ++--
 builtin/revert.c                   |    4 ++--
 contrib/examples/git-reset.sh      |    2 +-
 contrib/examples/git-revert.sh     |    4 ++--
 11 files changed, 36 insertions(+), 35 deletions(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 02e015a..ad173ed 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.
@@ -139,7 +139,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
@@ -148,10 +148,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 f56dfca..0509213 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -350,8 +350,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?
 ....
@@ -428,9 +428,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
@@ -475,7 +475,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`
@@ -649,7 +649,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>`)
@@ -662,13 +662,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`
@@ -699,7 +699,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
 ....
@@ -744,11 +744,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 96680c8..dbb5484 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.txt b/Documentation/git.txt
index 376397c..734acbe 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -475,13 +475,10 @@ Identifier Terminology
 	tag and commit objects until it finds a tree.
 
 <commit>::
-	Indicates a commit object name.
-
-<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 object name, or the name of a tag object that
+	points at a commit. A command that takes a <commit> argument
+	ultimately wants to operate on a commit object but automatically
+	dereferences tag objects until it finds a commit.
 
 <type>::
 	Indicates that an object type is required.
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index eefee3d..b56e7c3 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/glossary-content.txt b/Documentation/glossary-content.txt
index f04b48e..40a1f11 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -82,6 +82,10 @@ to point at the new commit.
 	to the top <<def_directory,directory>> of the stored
 	revision.
 
+[[def_commit-ish]][[def_committish]]commit-ish / committish::
+	A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
+	object>>, or a <<def_tag_object,tag object>> pointing to a tag or commit object.
+
 [[def_core_git]]core git::
 	Fundamental data structures and utilities of git. Exposes only limited
 	source code management tools.
diff --git a/builtin/describe.c b/builtin/describe.c
index 34a8031..4b5a217 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -12,7 +12,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
 };
@@ -462,7 +462,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/revert.c b/builtin/revert.c
index bb6e9e8..f00b6d6 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -27,12 +27,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-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 60a05a8..0b6b029 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 ;;
-- 
1.7.3.2

[PATCH 8/8] describe docs: note that <commit> is optional

[Mark Lodato]

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

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index ad173ed..8006d59 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>] <commit>...
+'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit>...]
 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
 
 DESCRIPTION
@@ -28,6 +28,7 @@ OPTIONS
 -------
 <commit>...::
 	Commit object names to describe.
+	If not given, defaults to HEAD.
 
 --dirty[=<mark>]::
 	Describe the working tree.
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index b56e7c3..e57f88c 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/describe.c b/builtin/describe.c
index 4b5a217..82da278 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -12,7 +12,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
 };
-- 
1.7.3.2

Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID

[Jonathan Nieder]

Mark Lodato wrote:

> There are some places that literally require a full, 40-character SHA-1
> ID, rather than a generic revision specifier.

One name I have seen for these is "object IDs", as in git get-tar-commit-id
(to avoid putting too much emphasis on precisely how the identifiers are
chosen).

>                                   Use <sha1> in git-diff-tree(1) to note
> that --stdin only takes <sha1>s, not generic <tree>s or <commit>s.

In this example, maybe it would be cleanest to spell out "40-digit
object identifier".

Perhaps something like this?  (The text is more verbose than I'd
like and it would be nicer to include an example, though.)

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index a7e37b8..85ce185 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -49,9 +49,11 @@ 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
-	as separator.)
+	reads lines, each naming two trees, one commit, or multiple
+	commits, from its standard input.  Each line consists of a
+	list of full 40-digit object identifiers with a single space
+	as separator.  Objects must be named directly; for example,
+	a tag ID cannot be used to represent a commit.
 +
 When two trees are given, it compares the first tree with the second.
 When a single commit is given, it compares the commit with its

Re: [PATCH 4/8] http-fetch docs: use <commit-id> consistently

[Jonathan Nieder]

Mark Lodato wrote:

> --- 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.

Does this mean the same thing as "commit id" in other manpages?

Re: [PATCH 6/8] docs: use <tree> instead of <tree-ish>

[Jonathan Nieder]

Mark Lodato wrote:

> The term "tree-ish" was left in the following situations:
>  - all comments in the code
>  - situations where "tree-ish" is being contrasted to "tree"
>  - error messages, to prevent porcelains from changing

Nit: to prevent plumbing from changing?  Or to prevent porcelains
from having to change in response to changes in plumbing?

> --- 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.

Is changing release notes for historical releases like this a good
idea?  (It not clear to me either way.)

> --- a/Documentation/diff-format.txt
> +++ b/Documentation/diff-format.txt
> @@ -7,13 +7,13 @@ 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.

Unrelated: we ought to remove the dash after "git" here.  (Thanks
for a reminder.)

> --- 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.

In this case, it might be less confusing to explicitly say (<commit> |
<tree>), since the behavior is:

 . commit id and timestamp recorded from commit if a commit is
   used
 . no commit id and time of invocation (!) recorded if a tree is
   used directly

meaning "git archive commit" and "git archive commit^{tree}" do not
always have the same behavior.

> --- a/Documentation/git-commit-tree.txt
> +++ b/Documentation/git-commit-tree.txt
> @@ -36,7 +36,8 @@ state was.
>  OPTIONS
>  -------
>  <tree>::
> -	An existing tree object
> +	An existing tree object.  Unlike other git commands, this must
> +	be an actual tree object, not a commit or tag.

Maybe it would be worth dropping that constraint (in the code) for
simplicity?

If not, it would be nice to give a fuller explanation, something to
this effect:

	An existing tree object.  To [reason here], the argument will
	not be automatically dereferenced to a tree if it names a commit
	or tag; you must instead specify the tree explicitly, for
	example by ending the argument with ^{tree}.

Wording could surely be improved.

> --- 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.

Is an arbitrary tree name okay, or only tree ids?

> --- a/Documentation/git-ls-tree.txt
> +++ b/Documentation/git-ls-tree.txt
> @@ -35,8 +35,8 @@ in the current working directory.  Note that:
>  
>  OPTIONS
>  -------
> -<tree-ish>::
> -	Id of a tree-ish.
> +<tree>::
> +	The id of a tree object.

Likewise.

> --- a/Documentation/git-merge-tree.txt
> +++ b/Documentation/git-merge-tree.txt
> @@ -12,7 +12,7 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Reads three treeish, and output trivial merge results and
> +Reads three <tree>s, and output trivial merge results and

Since the string "<tree>" does not appear in the synopsis, it seems
odd to mention it here.  Maybe it would be clearer to say:

SYNOPSIS
	git merge-tree <base-tree> <branch1> <branch2>

DESCRIPTION
	Reads three trees and outputs trivial merge results and
	conflicting entries to the standard output. This

or (though I like the previous synopsis much more)

SYNOPSIS
	git merge-tree <tree> <tree> <tree>

DESCRIPTION
	Reads three trees and outputs trivial merge results and
	conflicting entries to the standard output.  The arguments
	are in the same order as those for "git read-tree": the
	first represents the original (basis) state and the other
	two represent versions with improvements that need to be
	merged. This

> --- a/Documentation/git-read-tree.txt
> +++ b/Documentation/git-read-tree.txt
> @@ -118,7 +118,7 @@ OPTIONS
>  	Instead of reading tree object(s) into the index, just empty
>  	it.
>  
> -<tree-ish#>::
> +<tree-#>::
>  	The id of the tree object(s) to be read/merged.

Just "The tree objects to be read or merged", not necessarily named
by id, right?

> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -314,8 +314,8 @@ Any other arguments are passed directly to 'git log'
>  'find-rev'::
>  	When given an SVN revision number of the form 'rN', returns the
>  	corresponding git commit hash (this can optionally be followed by a
> -	tree-ish to specify which branch should be searched).  When given a
> -	tree-ish, returns the corresponding SVN revision number.
> +	<tree> to specify which branch should be searched).  When given a
> +	<tree>, returns the corresponding SVN revision number.

The placeholder <tree> sounds odd in descriptive text like this.
Maybe:

	If the first argument is of the form 'rN', prints the
	corresponding git commit id.  An optional second argument can
	name a commit, to limit the search to commits accessible from
	that commit.

	Otherwise, the first (and only) argument is interpreted as a
	git tree name and this subcommand prints the corresponding
	SVN revision number.

> @@ -345,7 +345,7 @@ Any other arguments are passed directly to 'git log'
>  	for use after commands like "git checkout" or "git reset".
>  
>  'commit-diff'::
> -	Commits the diff of two tree-ish arguments from the
> +	Commits the diff of two <tree> arguments from the

Likewise.  "Two trees named on the command line" should be clear.

> --- a/Documentation/git-tar-tree.txt
> +++ b/Documentation/git-tar-tree.txt
> @@ -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.

Huh?  (Not a problem introduced by this patch, but...)

> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -469,17 +469,14 @@ Identifier Terminology
>  	Indicates a blob object name.
>  
>  <tree>::
> -	Indicates a tree object name.
> +	Indicates a tree object name, or the name of 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
> +	tag and commit objects until it finds a tree.
>  
>  <commit>::
>  	Indicates a commit object name.
>  
> -<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>.
> -

I first read the new description as

	Indicates a tree name, or the name of a tag or commit ...

which seemed odd --- this always is a tree name.  Maybe

 <tree>::
	Indicates a parameter specifying a tree, commit, or tag object.
	A command that takes a <tree> argument ultimately wants to
	operate on a tree object so it automatically dereferences
	tag and commit objects until it finds a tree.

Thanks for eliminating the confusing <commit>, <tag>, etc markup.

> --- a/Documentation/gitcli.txt
> +++ b/Documentation/gitcli.txt
> @@ -15,8 +15,8 @@ DESCRIPTION
>  
>  This manual describes the convention used throughout git CLI.
>  
> -Many commands take revisions (most often "commits", but sometimes
> -"tree-ish", depending on the context and command) and paths as their
> +Many commands take revisions (most often <commit>s, but sometimes
> +<tree>s, depending on the context and command) and paths as their

Maybe

 Many commands take revisions (most often commits but sometimes
 trees, depending on the context and command) and paths as their
 arguments.  Here are the rules:

to avoid emphasizing a technicality.

> --- a/Documentation/gittutorial-2.txt
> +++ b/Documentation/gittutorial-2.txt
> @@ -209,10 +209,8 @@ Note, by the way, that lots of commands take a tree as an argument.
>  But as we can see above, a tree can be referred to in many different
>  ways--by the SHA1 name for that tree, by the name of a commit that
>  refers to the tree, by the name of a branch whose head refers to that
> -tree, etc.--and most such commands can accept any of these names.
> -
> -In command synopses, the word "tree-ish" is sometimes used to
> -designate such an argument.
> +tree, etc.--and all such commands can accept any of these names unless
> +otherwise stated.

... otherwise stated in the manual pages?

> --- a/t/t4100/t-apply-3.patch
> +++ b/t/t4100/t-apply-3.patch
[...]
> --- a/t/t4100/t-apply-7.patch
> +++ b/t/t4100/t-apply-7.patch
[...]

These last two aren't worth it, I think. :)

I very much like this change.  Ideally it should be possible to deal
with some of the nontrivial parts first in separate patches before
a last trivial one that does not do much more than change tree-ish ->
tree.

Re: [PATCH 7/8] docs: use <commit> instead of <commit-ish>

[Jonathan Nieder]

Mark Lodato wrote:

> --- a/Documentation/git-describe.txt
> +++ b/Documentation/git-describe.txt
> @@ -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.

Or even

	Commits to describe.

:)

> --- a/Documentation/git-fast-import.txt
> +++ b/Documentation/git-fast-import.txt
> @@ -350,8 +350,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)?

As the audience of this manual page is people mostly familiar with
other version control systems, it needs to be very explicit.  Not sure
what the best solution is, just pointing out the worry.

Re: [PATCHv2 0/8] docs: use metavariables consistently

[Jonathan Nieder]

Mark Lodato wrote:

>                               The biggest change is to drop the <tree-ish> and
> <commit-ish> (or <committish>) notation and just use <tree> or <commit>, since
> every command but commit-tree accepts tree-ishes and commit-ishes.

Thanks.  I think this will encourage UI consistency ("where you accept
a tree, accepts commits and tags, too") as a side effect.

> This is a rework of my earlier patch set from March [1], with the following
> differences:
>
> - Drop the patch to commit-tree that makes it accept a tree-ish.

Ah, missed this before.  It is not clear to me why this difference ---
is it just to be conservative about changing behavior?

> [1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484
http://thread.gmane.org/gmane.comp.version-control.git/142078

Re: [PATCH 2/8] docs: use `...' instead of `*' for multiplicity

[Jakub Narebski]

Mark Lodato <lodatom@gmail.com> writes:

> Finish the work of 0adda93 (Use parentheses and `...' where appropriate)
> to follow the rules set forth in Documentation/CodingGuidelines.
> 
> Signed-off-by: Mark Lodato <lodatom@gmail.com>

[...]

> -	"git describe [options] <committish>*",
> +	"git describe [options] <committish>...",

Isn't <sth>... one or more, while <sth>* is zero or more, i.e. shouldn't
<sth>* be replaced by [<sth>...]?

Hmmm... I see that <sth>* was actively wrong if it was to mean zero or
more, so your change doesn't only make documentation more consistent,
but fixes errorneous use of convention.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH 2/8] docs: use `...' instead of `*' for multiplicity

[Mark Lodato]

On Sat, Dec 18, 2010 at 5:00 AM, Jakub Narebski <jnareb@gmail.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> Finish the work of 0adda93 (Use parentheses and `...' where appropriate)
>> to follow the rules set forth in Documentation/CodingGuidelines.
>>
>> Signed-off-by: Mark Lodato <lodatom@gmail.com>
>
> [...]
>
>> -     "git describe [options] <committish>*",
>> +     "git describe [options] <committish>...",
>
> Isn't <sth>... one or more, while <sth>* is zero or more, i.e. shouldn't
> <sth>* be replaced by [<sth>...]?

Yes, I was confused by the * notation - one more reason to get rid of it!

> Hmmm... I see that <sth>* was actively wrong if it was to mean zero or
> more, so your change doesn't only make documentation more consistent,
> but fixes errorneous use of convention.

I think zero or more is correct, which is why I submitted patch 8/8 to
change from <commit>... to [<commit>...].  Now I understand that all
8/8 was doing was fixing a mistake I introduced in this patch.  I'll
correct it in the next version.

Re: [PATCHv2 0/8] docs: use metavariables consistently

[Mark Lodato]

On Sat, Dec 18, 2010 at 3:49 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Mark Lodato wrote:
>> This is a rework of my earlier patch set from March [1], with the following
>> differences:
>>
>> - Drop the patch to commit-tree that makes it accept a tree-ish.
>
> Ah, missed this before.  It is not clear to me why this difference ---
> is it just to be conservative about changing behavior?

Exactly.  Junio replied to my original email saying he did not think
this patch was unsafe, so if you think the patch is a good idea, I'll
re-send it.

>> [1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484
> http://thread.gmane.org/gmane.comp.version-control.git/142078

As an aside, how do you actually find threads on gmane?  I can't find
anything on Google.

Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Mark Lodato wrote:
>
>> There are some places that literally require a full, 40-character SHA-1
>> ID, rather than a generic revision specifier.
>
> One name I have seen for these is "object IDs", as in git get-tar-commit-id
> (to avoid putting too much emphasis on precisely how the identifiers are
> chosen).

Yes, I think I also saw "a full object name" (cf. diff --full-index) and
evan "object name" (cf. git-pack-objects(1)).  These are all deliberate
efforts to stay away from spelling SHA-1 explicitly, and I think it makes
sense to do so here.  "40-digit object ID" is a mouthful, though.

As to what this series tries to do, I think it is generally a good idea to
start allowing documents to say <tree> when a reader can plug either a
commit or a tree, rather than <tree-ish>, only because all Porcelains
automatically dereference object names to needed types these days.

But such a change needs to mark places that _must_ take the name of an
object of the specific type somehow.  It is Ok to say ls-tree takes a
tree, but then we must say you should feed commit-tree nothing but a tree.

It is a separate issue to allow plumbings to automatically dereference
when both of the following two conditions hold: (1) the intent is clear
from the context; (2) nobody sane would have been relying on the side
effect of the current typechecking.

Letting commit-tree to unwrap a tree-ish to a tree would be a good example
that clearly satisfies (1)---I am not sure about the other one.

Re: [PATCHv2 0/8] docs: use metavariables consistently

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Ah, missed this before.  It is not clear to me why this difference ---
> is it just to be conservative about changing behavior?

Yes.  It is clear from the context you mean its tree if you feed a commit
to commit-tree, but the original intent of not dereferncing was to avoid
mistakes by scripts and people, so you need to make a convincing argument
that not derefencing does not help avoiding mistakes, and prove that
nobody's script is relying on the current behaviour for type-checking
purposes.