{"thread":{"id":"26096","subject":"[PATCH 3/8] docs: use <sha1> to mean unabbreviated ID","startedAt":"2010-12-18T05:38:37Z","lastAt":"2010-12-18T20:27:25Z","messageCount":19,"participants":["Mark Lodato","Jonathan Nieder","Jakub Narebski","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":8},"messages":[{"id":"158301","messageId":"1292650725-21149-1-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":null,"subject":"[PATCHv2 0/8] docs: use metavariables consistently","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:37Z","receivedAt":"2010-12-18T05:38:37Z","isPatch":false,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"Update the documentation and usage statements to use metavariables, such as\n<commit>, more consistently.  The biggest change is to drop the <tree-ish> and\n<commit-ish> (or <committish>) notation and just use <tree> or <commit>, since\nevery command but commit-tree accepts tree-ishes and commit-ishes.  The \"-ish\"\nterms are still kept around in various places where it makes sense to\ndifferentiate between an actual tree or commit and a tree-ish or commit-ish.\n\nThis is a rework of my earlier patch set from March [1], with the following\ndifferences:\n\n- Drop the patch to commit-tree that makes it accept a tree-ish.\n- Drop the patch dealing with <tag> and <tagname>.\n- Leave -ish terms in comments and in places where they make sense.\n- Rebase onto master (1b97434).  Some of the patches from before have since\n  been accepted from other authors.\n- Fix a problem that Junio noticed with the \"grep docs\" patch.\n\n[1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484\n\nMark Lodato (8):\n  fsck docs: remove outdated and useless diagnostic\n  docs: use `...' instead of `*' for multiplicity\n  docs: use <sha1> to mean unabbreviated ID\n  http-fetch docs: use <commit-id> consistently\n  grep docs: grep accepts a <tree-ish>, not a <tree>\n  docs: use <tree> instead of <tree-ish>\n  docs: use <commit> instead of <commit-ish>\n  describe docs: note that <commit> is optional\n\n Documentation/RelNotes/1.6.2.4.txt    |    2 +-\n Documentation/diff-format.txt         |   10 +++++-----\n Documentation/diff-generate-patch.txt |    2 +-\n Documentation/git-archive.txt         |    4 ++--\n Documentation/git-cat-file.txt        |    2 +-\n Documentation/git-checkout.txt        |   16 ++++++++--------\n Documentation/git-commit-tree.txt     |    3 ++-\n Documentation/git-describe.txt        |   15 ++++++++-------\n Documentation/git-diff-index.txt      |    4 ++--\n Documentation/git-diff-tree.txt       |   18 +++++++++---------\n Documentation/git-fast-import.txt     |   22 +++++++++++-----------\n Documentation/git-fsck.txt            |    5 +----\n Documentation/git-http-fetch.txt      |    4 ++--\n Documentation/git-ls-files.txt        |    6 +++---\n Documentation/git-ls-tree.txt         |    6 +++---\n Documentation/git-merge-index.txt     |    2 +-\n Documentation/git-merge-tree.txt      |    2 +-\n Documentation/git-name-rev.txt        |    2 +-\n Documentation/git-read-tree.txt       |   10 +++++-----\n Documentation/git-rebase.txt          |    2 +-\n Documentation/git-svn.txt             |    6 +++---\n Documentation/git-tar-tree.txt        |    4 ++--\n Documentation/git.txt                 |   27 +++++++++++++--------------\n Documentation/gitcli.txt              |    6 +++---\n Documentation/gittutorial-2.txt       |    6 ++----\n Documentation/glossary-content.txt    |    4 ++++\n archive.c                             |    4 ++--\n builtin/commit-tree.c                 |    2 +-\n builtin/describe.c                    |    4 ++--\n builtin/diff-index.c                  |    2 +-\n builtin/diff-tree.c                   |    2 +-\n builtin/ls-files.c                    |    4 ++--\n builtin/ls-tree.c                     |    2 +-\n builtin/merge-index.c                 |    2 +-\n builtin/read-tree.c                   |    2 +-\n builtin/revert.c                      |    4 ++--\n builtin/tar-tree.c                    |    2 +-\n contrib/examples/git-reset.sh         |    2 +-\n contrib/examples/git-revert.sh        |    4 ++--\n git-svn.perl                          |    6 +++---\n t/t4100/t-apply-3.patch               |    8 ++++----\n t/t4100/t-apply-7.patch               |    8 ++++----\n 42 files changed, 124 insertions(+), 124 deletions(-)\n\n-- \n1.7.3.2\n"},{"id":"158304","messageId":"1292650725-21149-2-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 1/8] fsck docs: remove outdated and useless diagnostic","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:38Z","receivedAt":"2010-12-18T05:38:38Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"In git-fsck(1), there was a reference to the warning \"<tree> has full\npathnames in it\".  This exact wording has not been used since 2005\n(commit f1f0d0889e55), when the wording was changed slightly.  More\nimportantly, the description of that warning was useless, and there were\nmany other similar warning messages which were not document at all.\nSince all these warnings are fairly obvious, there is no need for them\nto be in the man page.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-fsck.txt |    3 ---\n 1 files changed, 0 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex 3ad48a6..86f9b2b 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -123,9 +123,6 @@ dangling <type> <object>::\n \tThe <type> object <object>, is present in the database but never\n \t'directly' used. A dangling commit could be a root node.\n \n-warning: git-fsck: tree <tree> has full pathnames in it::\n-\tAnd it shouldn't...\n-\n sha1 mismatch <object>::\n \tThe database has an object who's sha1 doesn't match the\n \tdatabase value.\n-- \n1.7.3.2\n"},{"id":"158303","messageId":"1292650725-21149-3-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 2/8] docs: use `...' instead of `*' for multiplicity","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:39Z","receivedAt":"2010-12-18T05:38:39Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"Finish the work of 0adda93 (Use parentheses and `...' where appropriate)\nto follow the rules set forth in Documentation/CodingGuidelines.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-fsck.txt        |    2 +-\n Documentation/git-merge-index.txt |    2 +-\n Documentation/gitcli.txt          |    2 +-\n builtin/describe.c                |    2 +-\n builtin/merge-index.c             |    2 +-\n 5 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex 86f9b2b..38207a1 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n-\t [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>*]\n+\t [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 921b38f..3716309 100644\n--- a/Documentation/git-merge-index.txt\n+++ b/Documentation/git-merge-index.txt\n@@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging\n \n SYNOPSIS\n --------\n-'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)\n+'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>...)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 6928724..eb65dcf 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -81,7 +81,7 @@ couple of magic command line options:\n +\n ---------------------------------------------\n $ git describe -h\n-usage: git describe [options] <committish>*\n+usage: git describe [options] <committish>...\n \n     --contains            find the tag that comes after the commit\n     --debug               debug search strategy on stderr\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex a0f52c1..34a8031 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -12,7 +12,7 @@\n #define MAX_TAGS\t(FLAG_BITS - 1)\n \n static const char * const describe_usage[] = {\n-\t\"git describe [options] <committish>*\",\n+\t\"git describe [options] <committish>...\",\n \t\"git describe [options] --dirty\",\n \tNULL\n };\ndiff --git a/builtin/merge-index.c b/builtin/merge-index.c\nindex 2c4cf5e..c683bbd 100644\n--- a/builtin/merge-index.c\n+++ b/builtin/merge-index.c\n@@ -76,7 +76,7 @@ int cmd_merge_index(int argc, const char **argv, const char *prefix)\n \tsignal(SIGCHLD, SIG_DFL);\n \n \tif (argc < 3)\n-\t\tusage(\"git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>*)\");\n+\t\tusage(\"git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>...)\");\n \n \tread_cache();\n \n-- \n1.7.3.2\n"},{"id":"158300","messageId":"1292650725-21149-4-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 3/8] docs: use <sha1> to mean unabbreviated ID","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:40Z","receivedAt":"2010-12-18T05:38:40Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"There are some places that literally require a full, 40-character SHA-1\nID, rather than a generic revision specifier.  Introduce in git(1) the\n<sha1> terminology to mean this.  Use <sha1> in git-diff-tree(1) to note\nthat --stdin only takes <sha1>s, not generic <tree>s or <commit>s.\nUse <tree> and <commit> in the usage statement for 'commit-tree'.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-diff-tree.txt |    4 ++--\n Documentation/git.txt           |    5 +++++\n builtin/commit-tree.c           |    2 +-\n 3 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex a7e37b8..6b357a5 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -49,8 +49,8 @@ include::diff-options.txt[]\n --stdin::\n \tWhen '--stdin' is specified, the command does not take\n \t<tree-ish> arguments from the command line.  Instead, it\n-\treads lines containing either two <tree>, one <commit>, or a\n-\tlist of <commit> from its standard input.  (Use a single space\n+\treads lines containing <sha1>s: either two trees, one commit, or\n+\tmultiple commits from its standard input.  (Use a single space\n \tas separator.)\n +\n When two trees are given, it compares the first tree with the second.\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 0128371..7929739 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -457,6 +457,11 @@ list.\n \n Identifier Terminology\n ----------------------\n+<sha1>::\n+\tIndicates a full, 40-character SHA-1 identifier of an object.\n+\tThe type of the referenced object is unspecified.\n+\tAbbreviated or symbolic identifiers cannot be used.\n+\n <object>::\n \tIndicates the object name for any type of object.\n \ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex d083795..da572c3 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -9,7 +9,7 @@\n #include \"builtin.h\"\n #include \"utf8.h\"\n \n-static const char commit_tree_usage[] = \"git commit-tree <sha1> [(-p <sha1>)...] < changelog\";\n+static const char commit_tree_usage[] = \"git commit-tree <tree> [(-p <commit>)...] < changelog\";\n \n static void new_parent(struct commit *parent, struct commit_list **parents_p)\n {\n-- \n1.7.3.2\n"},{"id":"158302","messageId":"1292650725-21149-5-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 4/8] http-fetch docs: use <commit-id> consistently","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:41Z","receivedAt":"2010-12-18T05:38:41Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"Signed-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-http-fetch.txt |    4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt\nindex d91cb7f..93449fd 100644\n--- a/Documentation/git-http-fetch.txt\n+++ b/Documentation/git-http-fetch.txt\n@@ -8,7 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP\n \n SYNOPSIS\n --------\n-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url>\n+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit-id> <url>\n \n DESCRIPTION\n -----------\n@@ -16,7 +16,7 @@ Downloads a remote git repository via HTTP.\n \n OPTIONS\n -------\n-commit-id::\n+<commit-id>::\n         Either the hash or the filename under [URL]/refs/ to\n         pull.\n \n-- \n1.7.3.2\n"},{"id":"158305","messageId":"1292650725-21149-6-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 5/8] grep docs: grep accepts a <tree-ish>, not a <tree>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:42Z","receivedAt":"2010-12-18T05:38:42Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"Also document that -p accepts a <commit> in the usage message.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-grep.txt |    4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex dab0a78..54ea24a 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -22,7 +22,7 @@ SYNOPSIS\n \t   [-A <post-context>] [-B <pre-context>] [-C <context>]\n \t   [-f <file>] [-e] <pattern>\n \t   [--and|--or|--not|(|)|-e <pattern>...]\n-\t   [--cached | --no-index | <tree>...]\n+\t   [--cached | --no-index | <tree-ish>...]\n \t   [--] [<pathspec>...]\n \n DESCRIPTION\n@@ -176,7 +176,7 @@ OPTIONS\n \tDo not output matched lines; instead, exit with status 0 when\n \tthere is a match and with non-zero status when there isn't.\n \n-<tree>...::\n+<tree-ish>...::\n \tInstead of searching tracked files in the working tree, search\n \tblobs in the given trees.\n \n-- \n1.7.3.2\n"},{"id":"158308","messageId":"1292650725-21149-7-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 6/8] docs: use <tree> instead of <tree-ish>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:43Z","receivedAt":"2010-12-18T05:38:43Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"No git command, besides commit-tree, accepts only a tree and not\na tree-ish, so let us remove the latter term from common usage in the\ndocumentation in order to reduce the amount of jargon.\n\nThe term \"tree-ish\" was left in the following situations:\n - all comments in the code\n - situations where \"tree-ish\" is being contrasted to \"tree\"\n - error messages, to prevent porcelains from changing\n - tests\n - the glossary\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/RelNotes/1.6.2.4.txt    |    2 +-\n Documentation/diff-format.txt         |   10 +++++-----\n Documentation/diff-generate-patch.txt |    2 +-\n Documentation/git-archive.txt         |    4 ++--\n Documentation/git-cat-file.txt        |    2 +-\n Documentation/git-checkout.txt        |   16 ++++++++--------\n Documentation/git-commit-tree.txt     |    3 ++-\n Documentation/git-diff-index.txt      |    4 ++--\n Documentation/git-diff-tree.txt       |   14 +++++++-------\n Documentation/git-grep.txt            |    4 ++--\n Documentation/git-ls-files.txt        |    6 +++---\n Documentation/git-ls-tree.txt         |    6 +++---\n Documentation/git-merge-tree.txt      |    2 +-\n Documentation/git-read-tree.txt       |   10 +++++-----\n Documentation/git-svn.txt             |    6 +++---\n Documentation/git-tar-tree.txt        |    4 ++--\n Documentation/git.txt                 |   11 ++++-------\n Documentation/gitcli.txt              |    4 ++--\n Documentation/gittutorial-2.txt       |    6 ++----\n archive.c                             |    4 ++--\n builtin/diff-index.c                  |    2 +-\n builtin/diff-tree.c                   |    2 +-\n builtin/ls-files.c                    |    4 ++--\n builtin/ls-tree.c                     |    2 +-\n builtin/read-tree.c                   |    2 +-\n builtin/tar-tree.c                    |    2 +-\n git-svn.perl                          |    6 +++---\n t/t4100/t-apply-3.patch               |    8 ++++----\n t/t4100/t-apply-7.patch               |    8 ++++----\n 29 files changed, 76 insertions(+), 80 deletions(-)\n\ndiff --git a/Documentation/RelNotes/1.6.2.4.txt b/Documentation/RelNotes/1.6.2.4.txt\nindex f4bf1d0..0e36786 100644\n--- a/Documentation/RelNotes/1.6.2.4.txt\n+++ b/Documentation/RelNotes/1.6.2.4.txt\n@@ -13,7 +13,7 @@ Fixes since v1.6.2.3\n * \"git-add -p\" lacked a way to say \"q\"uit to refuse staging any hunks for\n   the remaining paths.  You had to say \"d\" and then ^C.\n \n-* \"git-checkout <tree-ish> <submodule>\" did not update the index entry at\n+* \"git-checkout <tree> <submodule>\" did not update the index entry at\n   the named path; it now does.\n \n * \"git-fast-export\" choked when seeing a tag that does not point at commit.\ndiff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt\nindex 15c7e79..83272a0 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -7,13 +7,13 @@ The raw output format from \"git-diff-index\", \"git-diff-tree\",\n These commands all compare two sets of things; what is\n compared differs:\n \n-git-diff-index <tree-ish>::\n-        compares the <tree-ish> and the files on the filesystem.\n+git-diff-index <tree>::\n+        compares the <tree> and the files on the filesystem.\n \n-git-diff-index --cached <tree-ish>::\n-        compares the <tree-ish> and the index.\n+git-diff-index --cached <tree>::\n+        compares the <tree> and the index.\n \n-git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::\n+git-diff-tree [-r] <tree-1> <tree-2> [<pattern>...]::\n         compares the trees named by the two arguments.\n \n git-diff-files [<pattern>...]::\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 3ac2bea..e0802de 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -131,7 +131,7 @@ The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n the <mode> is different from the rest. Extended headers with\n information about detected contents movement (renames and\n copying detection) are designed to work with diff of two\n-<tree-ish> and are not used by combined diff format.\n+<tree> and are not used by combined diff format.\n \n 3.   It is followed by two-line from-file/to-file header\n \ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 4163a1b..bb4943f 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]\n \t      [-o | --output=<file>] [--worktree-attributes]\n-\t      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>\n+\t      [--remote=<repo> [--exec=<git-upload-archive>]] <tree>\n \t      [<path>...]\n \n DESCRIPTION\n@@ -70,7 +70,7 @@ OPTIONS\n \tUsed with --remote to specify the path to the\n \t'git-upload-archive' on the remote side.\n \n-<tree-ish>::\n+<tree>::\n \tThe tree or commit to produce an archive for.\n \n <path>::\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 544ba7b..4861007 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -54,7 +54,7 @@ OPTIONS\n \n --textconv::\n \tShow the content as transformed by a textconv filter. In this case,\n-\t<object> has be of the form <treeish>:<path>, or :<path> in order\n+\t<object> has be of the form <tree>:<path>, or :<path> in order\n \tto apply the filter to the content recorded in the index at <path>.\n \n --batch::\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 880763d..0199e10 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -10,8 +10,8 @@ SYNOPSIS\n [verse]\n 'git checkout' [-q] [-f] [-m] [<branch>]\n 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n-'git checkout' --patch [<tree-ish>] [--] [<paths>...]\n+'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree>] [--] <paths>...\n+'git checkout' --patch [<tree>] [--] [<paths>...]\n \n DESCRIPTION\n -----------\n@@ -43,14 +43,14 @@ $ git checkout <branch>\n that is to say, the branch is not reset/created unless \"git checkout\" is\n successful.\n \n-'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::\n+'git checkout' [--patch] [<tree>] [--] <pathspec>...::\n \n \tWhen <paths> or `--patch` are given, 'git checkout' does *not*\n \tswitch branches.  It updates the named paths in the working tree\n-\tfrom the index file or from a named <tree-ish> (most often a\n+\tfrom the index file or from a named <tree> (most often a\n \tcommit).  In this case, the `-b` and `--track` options are\n \tmeaningless and giving either of them results in an error.  The\n-\t<tree-ish> argument can be used to specify a specific tree-ish\n+\t<tree> argument can be used to specify a specific tree-ish\n \t(i.e.  commit, tag or tree) to update the index for the given\n \tpaths before updating the working tree.\n +\n@@ -169,9 +169,9 @@ the conflicted merge in the specified paths.\n -p::\n --patch::\n \tInteractively select hunks in the difference between the\n-\t<tree-ish> (or the index, if unspecified) and the working\n+\t<tree> (or the index, if unspecified) and the working\n \ttree.  The chosen hunks are then applied in reverse to the\n-\tworking tree (and if a <tree-ish> was specified, the index).\n+\tworking tree (and if a <tree> was specified, the index).\n +\n This means that you can use `git checkout -p` to selectively discard\n edits from your current working tree.\n@@ -198,7 +198,7 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n \tThe name of a commit at which to start the new branch; see\n \tlinkgit:git-branch[1] for details. Defaults to HEAD.\n \n-<tree-ish>::\n+<tree>::\n \tTree to checkout from (when paths are given). If not specified,\n \tthe index will be used.\n \ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 5dcf427..92687d8 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -36,7 +36,8 @@ state was.\n OPTIONS\n -------\n <tree>::\n-\tAn existing tree object\n+\tAn existing tree object.  Unlike other git commands, this must\n+\tbe an actual tree object, not a commit or tag.\n \n -p <parent commit>::\n \tEach '-p' indicates the id of a parent commit object.\ndiff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt\nindex 162cb74..c725357 100644\n--- a/Documentation/git-diff-index.txt\n+++ b/Documentation/git-diff-index.txt\n@@ -8,7 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi\n \n SYNOPSIS\n --------\n-'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...]\n+'git diff-index' [-m] [--cached] [<common diff options>] <tree> [<path>...]\n \n DESCRIPTION\n -----------\n@@ -22,7 +22,7 @@ OPTIONS\n -------\n include::diff-options.txt[]\n \n-<tree-ish>::\n+<tree>::\n \tThe id of a tree object to diff against.\n \n --cached::\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 6b357a5..692d83b 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -11,13 +11,13 @@ SYNOPSIS\n [verse]\n 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\n \t      [-t] [-r] [-c | --cc] [--root] [<common diff options>]\n-\t      <tree-ish> [<tree-ish>] [<path>...]\n+\t      <tree> [<tree>] [<path>...]\n \n DESCRIPTION\n -----------\n Compares the content and mode of the blobs found via two tree objects.\n \n-If there is only one <tree-ish> given, the commit is compared with its parents\n+If there is only one <tree> given, the commit is compared with its parents\n (see --stdin below).\n \n Note that 'git diff-tree' can use the tree encapsulated in a commit object.\n@@ -26,7 +26,7 @@ OPTIONS\n -------\n include::diff-options.txt[]\n \n-<tree-ish>::\n+<tree>::\n \tThe id of a tree object.\n \n <path>...::\n@@ -48,7 +48,7 @@ include::diff-options.txt[]\n \n --stdin::\n \tWhen '--stdin' is specified, the command does not take\n-\t<tree-ish> arguments from the command line.  Instead, it\n+\t<tree> arguments from the command line.  Instead, it\n \treads lines containing <sha1>s: either two trees, one commit, or\n \tmultiple commits from its standard input.  (Use a single space\n \tas separator.)\n@@ -91,7 +91,7 @@ include::pretty-options.txt[]\n -c::\n \tThis flag changes the way a merge commit is displayed\n \t(which means it is useful only when the command is given\n-\tone <tree-ish>, or '--stdin').  It shows the differences\n+\tone <tree>, or '--stdin').  It shows the differences\n \tfrom each of the parents to the merge result simultaneously\n \tinstead of showing pairwise diff between a parent and the\n \tresult one at a time (which is what the '-m' option does).\n@@ -121,13 +121,13 @@ Limiting Output\n If you're only interested in differences in a subset of files, for\n example some architecture-specific files, you might do:\n \n-\tgit diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64\n+\tgit diff-tree -r <tree> <tree> arch/ia64 include/asm-ia64\n \n and it will only show you what changed in those two directories.\n \n Or if you are searching for what changed in just `kernel/sched.c`, just do\n \n-\tgit diff-tree -r <tree-ish> <tree-ish> kernel/sched.c\n+\tgit diff-tree -r <tree> <tree> kernel/sched.c\n \n and it will ignore all differences to other files.\n \ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 54ea24a..dab0a78 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -22,7 +22,7 @@ SYNOPSIS\n \t   [-A <post-context>] [-B <pre-context>] [-C <context>]\n \t   [-f <file>] [-e] <pattern>\n \t   [--and|--or|--not|(|)|-e <pattern>...]\n-\t   [--cached | --no-index | <tree-ish>...]\n+\t   [--cached | --no-index | <tree>...]\n \t   [--] [<pathspec>...]\n \n DESCRIPTION\n@@ -176,7 +176,7 @@ OPTIONS\n \tDo not output matched lines; instead, exit with status 0 when\n \tthere is a match and with non-zero status when there isn't.\n \n-<tree-ish>...::\n+<tree>...::\n \tInstead of searching tracked files in the working tree, search\n \tblobs in the given trees.\n \ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 86abd13..1192859 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -16,7 +16,7 @@ SYNOPSIS\n \t\t[-X <file>|--exclude-from=<file>]\n \t\t[--exclude-per-directory=<file>]\n \t\t[--exclude-standard]\n-\t\t[--error-unmatch] [--with-tree=<tree-ish>]\n+\t\t[--error-unmatch] [--with-tree=<tree>]\n \t\t[--full-name] [--abbrev] [--] [<file>...]\n \n DESCRIPTION\n@@ -99,11 +99,11 @@ OPTIONS\n \tIf any <file> does not appear in the index, treat this as an\n \terror (return 1).\n \n---with-tree=<tree-ish>::\n+--with-tree=<tree>::\n \tWhen using --error-unmatch to expand the user supplied\n \t<file> (i.e. path pattern) arguments to paths, pretend\n \tthat paths which were removed in the index since the\n-\tnamed <tree-ish> are still present.  Using this option\n+\tnamed <tree> are still present.  Using this option\n \twith `-s` or `-u` options does not make any sense.\n \n -t::\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex 76ed625..b0bb226 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git ls-tree' [-d] [-r] [-t] [-l] [-z]\n \t    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]\n-\t    <tree-ish> [<path>...]\n+\t    <tree> [<path>...]\n \n DESCRIPTION\n -----------\n@@ -35,8 +35,8 @@ in the current working directory.  Note that:\n \n OPTIONS\n -------\n-<tree-ish>::\n-\tId of a tree-ish.\n+<tree>::\n+\tThe id of a tree object.\n \n -d::\n \tShow only the named tree entry itself, not its children.\ndiff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt\nindex f869a7f..0a9eb0d 100644\n--- a/Documentation/git-merge-tree.txt\n+++ b/Documentation/git-merge-tree.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Reads three treeish, and output trivial merge results and\n+Reads three <tree>s, and output trivial merge results and\n conflicting stages to the standard output.  This is similar to\n what three-way 'git read-tree -m' does, but instead of storing the\n results in the index, the command outputs the entries to the\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex e88e9c2..24d9b87 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -11,12 +11,12 @@ SYNOPSIS\n 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n \t\t[-u [--exclude-per-directory=<gitignore>] | -i]]\n \t\t[--index-output=<file>] [--no-sparse-checkout]\n-\t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n+\t\t(--empty | <tree-1> [<tree-2> [<tree-3>]])\n \n \n DESCRIPTION\n -----------\n-Reads the tree information given by <tree-ish> into the index,\n+Reads the tree information given by <tree> into the index,\n but does not actually *update* any of the files it \"caches\". (see:\n linkgit:git-checkout-index[1])\n \n@@ -77,7 +77,7 @@ OPTIONS\n \n --prefix=<prefix>/::\n \tKeep the current index contents, and read the contents\n-\tof named tree-ish under directory at `<prefix>`.  The\n+\tof named tree under directory at `<prefix>`.  The\n \toriginal index file cannot have anything at the path\n \t`<prefix>` itself, and have nothing in `<prefix>/`\n \tdirectory.  Note that the `<prefix>/` value must end\n@@ -118,7 +118,7 @@ OPTIONS\n \tInstead of reading tree object(s) into the index, just empty\n \tit.\n \n-<tree-ish#>::\n+<tree-#>::\n \tThe id of the tree object(s) to be read/merged.\n \n \n@@ -278,7 +278,7 @@ merge. The different stages represent the \"result tree\" (stage 0, aka\n you are trying to merge (stage 2 and 3 respectively).\n \n The order of stages 1, 2 and 3 (hence the order of three\n-<tree-ish> command line arguments) are significant when you\n+<tree> command line arguments) are significant when you\n start a 3-way merge with an index file that is already\n populated.  Here is an outline of how the algorithm works:\n \ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 139d314..665a107 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -314,8 +314,8 @@ Any other arguments are passed directly to 'git log'\n 'find-rev'::\n \tWhen given an SVN revision number of the form 'rN', returns the\n \tcorresponding git commit hash (this can optionally be followed by a\n-\ttree-ish to specify which branch should be searched).  When given a\n-\ttree-ish, returns the corresponding SVN revision number.\n+\t<tree> to specify which branch should be searched).  When given a\n+\t<tree>, returns the corresponding SVN revision number.\n \n 'set-tree'::\n \tYou should consider using 'dcommit' instead of this command.\n@@ -345,7 +345,7 @@ Any other arguments are passed directly to 'git log'\n \tfor use after commands like \"git checkout\" or \"git reset\".\n \n 'commit-diff'::\n-\tCommits the diff of two tree-ish arguments from the\n+\tCommits the diff of two <tree> arguments from the\n \tcommand-line.  This command does not rely on being inside an `git svn\n \tinit`-ed repository.  This command takes three arguments, (a) the\n \toriginal tree to diff against, (b) the new tree result, (c) the\ndiff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt\nindex 3c786bd..6d0a746 100644\n--- a/Documentation/git-tar-tree.txt\n+++ b/Documentation/git-tar-tree.txt\n@@ -8,7 +8,7 @@ git-tar-tree - Create a tar archive of the files in the named tree object\n \n SYNOPSIS\n --------\n-'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ]\n+'git tar-tree' [--remote=<repo>] <tree> [ <base> ]\n \n DESCRIPTION\n -----------\n@@ -29,7 +29,7 @@ It can be extracted using 'git get-tar-commit-id'.\n OPTIONS\n -------\n \n-<tree-ish>::\n+<tree>::\n \tThe tree or commit to produce tar archive for.  If it is\n \tthe object name of a commit object.\n \ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 7929739..376397c 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -469,17 +469,14 @@ Identifier Terminology\n \tIndicates a blob object name.\n \n <tree>::\n-\tIndicates a tree object name.\n+\tIndicates a tree object name, or the name of tag or commit that points\n+\tat a tree.  A command that takes a <tree> argument ultimately\n+\twants to operate on a tree object but automatically dereferences\n+\ttag and commit objects until it finds a tree.\n \n <commit>::\n \tIndicates a commit object name.\n \n-<tree-ish>::\n-\tIndicates a tree, commit or tag object name.  A\n-\tcommand that takes a <tree-ish> argument ultimately wants to\n-\toperate on a <tree> object but automatically dereferences\n-\t<commit> and <tag> objects that point at a <tree>.\n-\n <commit-ish>::\n \tIndicates a commit or tag object name.  A\n \tcommand that takes a <commit-ish> argument ultimately wants to\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex eb65dcf..eefee3d 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -15,8 +15,8 @@ DESCRIPTION\n \n This manual describes the convention used throughout git CLI.\n \n-Many commands take revisions (most often \"commits\", but sometimes\n-\"tree-ish\", depending on the context and command) and paths as their\n+Many commands take revisions (most often <commit>s, but sometimes\n+<tree>s, depending on the context and command) and paths as their\n arguments.  Here are the rules:\n \n  * Revisions come first and then paths.\ndiff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt\nindex 7fe5848..218b94d 100644\n--- a/Documentation/gittutorial-2.txt\n+++ b/Documentation/gittutorial-2.txt\n@@ -209,10 +209,8 @@ Note, by the way, that lots of commands take a tree as an argument.\n But as we can see above, a tree can be referred to in many different\n ways--by the SHA1 name for that tree, by the name of a commit that\n refers to the tree, by the name of a branch whose head refers to that\n-tree, etc.--and most such commands can accept any of these names.\n-\n-In command synopses, the word \"tree-ish\" is sometimes used to\n-designate such an argument.\n+tree, etc.--and all such commands can accept any of these names unless\n+otherwise stated.\n \n The index file\n --------------\ndiff --git a/archive.c b/archive.c\nindex 1944ed4..50fb77e 100644\n--- a/archive.c\n+++ b/archive.c\n@@ -7,9 +7,9 @@\n #include \"unpack-trees.h\"\n \n static char const * const archive_usage[] = {\n-\t\"git archive [options] <tree-ish> [<path>...]\",\n+\t\"git archive [options] <tree> [<path>...]\",\n \t\"git archive --list\",\n-\t\"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]\",\n+\t\"git archive --remote <repo> [--exec <cmd>] [options] <tree> [<path>...]\",\n \t\"git archive --remote <repo> [--exec <cmd>] --list\",\n \tNULL\n };\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 2eb32bd..605e326 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -7,7 +7,7 @@\n \n static const char diff_cache_usage[] =\n \"git diff-index [-m] [--cached] \"\n-\"[<common diff options>] <tree-ish> [<path>...]\"\n+\"[<common diff options>] <tree> [<path>...]\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_index(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 0d2a3e9..d0ea2db 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -88,7 +88,7 @@ static int diff_tree_stdin(char *line)\n \n static const char diff_tree_usage[] =\n \"git diff-tree [--stdin] [-m] [-c] [--cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n-\"[<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"[<common diff options>] <tree> [<tree>] [<path>...]\\n\"\n \"  -r            diff recursively\\n\"\n \"  --root        include the initial commit as diff against /dev/null\\n\"\n COMMON_DIFF_OPTIONS_HELP;\ndiff --git a/builtin/ls-files.c b/builtin/ls-files.c\nindex fb2d5f4..8592fd0 100644\n--- a/builtin/ls-files.c\n+++ b/builtin/ls-files.c\n@@ -523,8 +523,8 @@ int cmd_ls_files(int argc, const char **argv, const char *cmd_prefix)\n \t\t\tPARSE_OPT_NOARG | PARSE_OPT_NONEG, NULL },\n \t\tOPT_BOOLEAN(0, \"error-unmatch\", &error_unmatch,\n \t\t\t\"if any <file> is not in the index, treat this as an error\"),\n-\t\tOPT_STRING(0, \"with-tree\", &with_tree, \"tree-ish\",\n-\t\t\t\"pretend that paths removed since <tree-ish> are still present\"),\n+\t\tOPT_STRING(0, \"with-tree\", &with_tree, \"tree\",\n+\t\t\t\"pretend that paths removed since <tree> are still present\"),\n \t\tOPT__ABBREV(&abbrev),\n \t\tOPT_BOOLEAN(0, \"debug\", &debug_mode, \"show debugging data\"),\n \t\tOPT_END()\ndiff --git a/builtin/ls-tree.c b/builtin/ls-tree.c\nindex f73e6bd..a810d9a 100644\n--- a/builtin/ls-tree.c\n+++ b/builtin/ls-tree.c\n@@ -24,7 +24,7 @@ static int chomp_prefix;\n static const char *ls_tree_prefix;\n \n static const  char * const ls_tree_usage[] = {\n-\t\"git ls-tree [<options>] <tree-ish> [<path>...]\",\n+\t\"git ls-tree [<options>] <tree> [<path>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex 73c89ed..064711a 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -33,7 +33,7 @@ static int list_tree(unsigned char *sha1)\n }\n \n static const char * const read_tree_usage[] = {\n-\t\"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>]])\",\n+\t\"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>]])\",\n \tNULL\n };\n \ndiff --git a/builtin/tar-tree.c b/builtin/tar-tree.c\nindex 3f1e701..abdcd0b 100644\n--- a/builtin/tar-tree.c\n+++ b/builtin/tar-tree.c\n@@ -8,7 +8,7 @@\n #include \"quote.h\"\n \n static const char tar_tree_usage[] =\n-\"git tar-tree [--remote=<repo>] <tree-ish> [basedir]\\n\"\n+\"git tar-tree [--remote=<repo>] <tree> [basedir]\\n\"\n \"*** Note that this command is now deprecated; use \\\"git archive\\\" instead.\";\n \n static const char builtin_get_tar_commit_id_usage[] =\ndiff --git a/git-svn.perl b/git-svn.perl\nindex 177dd25..96197c0 100755\n--- a/git-svn.perl\n+++ b/git-svn.perl\n@@ -172,7 +172,7 @@ my %cmd = (\n \t           'username=s' => \\$Git::SVN::Prompt::_username,\n \t           'commit-url=s' => \\$_commit_url } ],\n \t'set-tree' => [ \\&cmd_set_tree,\n-\t                \"Set an SVN repository to a git tree-ish\",\n+\t                \"Set an SVN repository to a git tree\",\n \t\t\t{ 'stdin' => \\$_stdin, %cmt_opts, %fc_opts, } ],\n \t'create-ignore' => [ \\&cmd_create_ignore,\n \t\t\t     'Create a .gitignore per svn:ignore',\n@@ -215,7 +215,7 @@ my %cmd = (\n \t\t\t  'pager=s' => \\$Git::SVN::Log::pager\n \t\t\t} ],\n \t'find-rev' => [ \\&cmd_find_rev,\n-\t                \"Translate between SVN revision numbers and tree-ish\",\n+\t                \"Translate between SVN revision numbers and trees\",\n \t\t\t{} ],\n \t'rebase' => [ \\&cmd_rebase, \"Fetch and rebase your working directory\",\n \t\t\t{ 'merge|m|M' => \\$_merge,\n@@ -1002,7 +1002,7 @@ sub cmd_multi_fetch {\n sub cmd_commit_diff {\n \tmy ($ta, $tb, $url) = @_;\n \tmy $usage = \"Usage: $0 commit-diff -r<revision> \".\n-\t            \"<tree-ish> <tree-ish> [<URL>]\";\n+\t            \"<tree> <tree> [<URL>]\";\n \tfatal($usage) if (!defined $ta || !defined $tb);\n \tmy $svn_path = '';\n \tif (!defined $url) {\ndiff --git a/t/t4100/t-apply-3.patch b/t/t4100/t-apply-3.patch\nindex 90cdbaa..c702866 100644\n--- a/t/t4100/t-apply-3.patch\n+++ b/t/t4100/t-apply-3.patch\n@@ -12,8 +12,8 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\n  \n  SYNOPSIS\n  --------\n--'git-ls-tree' [-r] [-z] <tree-ish> [paths...]\n-+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]\n+-'git-ls-tree' [-r] [-z] <tree> [paths...]\n++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...]\n  \n  DESCRIPTION\n  -----------\n@@ -24,7 +24,7 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\n  \n  OPTIONS\n  -------\n- <tree-ish>::\n+ <tree>::\n  \tId of a tree.\n  \n +-d::\n@@ -485,7 +485,7 @@ dissimilarity index 82%\n +}\n +\n +static const char *ls_tree_usage =\n-+\t\"git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]\";\n++\t\"git-ls-tree [-d] [-r] [-z] <tree> [path...]\";\n +\n +int main(int argc, char **argv)\n +{\ndiff --git a/t/t4100/t-apply-7.patch b/t/t4100/t-apply-7.patch\nindex 07c6589..bf8737b 100644\n--- a/t/t4100/t-apply-7.patch\n+++ b/t/t4100/t-apply-7.patch\n@@ -11,8 +11,8 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\n  \n  SYNOPSIS\n  --------\n--'git-ls-tree' [-r] [-z] <tree-ish> [paths...]\n-+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]\n+-'git-ls-tree' [-r] [-z] <tree> [paths...]\n++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...]\n  \n  DESCRIPTION\n  -----------\n@@ -23,7 +23,7 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\n  \n  OPTIONS\n  -------\n- <tree-ish>::\n+ <tree>::\n  \tId of a tree.\n  \n +-d::\n@@ -415,7 +415,7 @@ diff a/ls-tree.c b/ls-tree.c\n  \n -static const char *ls_tree_usage = \"git-ls-tree [-r] [-z] <key> [paths...]\";\n +static const char *ls_tree_usage =\n-+\t\"git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]\";\n++\t\"git-ls-tree [-d] [-r] [-z] <tree> [path...]\";\n  \n  int main(int argc, char **argv)\n  {\n-- \n1.7.3.2\n"},{"id":"158307","messageId":"1292650725-21149-8-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 7/8] docs: use <commit> instead of <commit-ish>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:44Z","receivedAt":"2010-12-18T05:38:44Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"No git command accepts only a commit and not a commit-ish, so let us\nremove the latter term from common usage in the documentation in order\nto reduce the amount of jargon.  Note that the terms `committish' and\n`commit-ish' were both previously used.\n\nThe \"ish\" terms were left in comments and were added to the glossary.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-describe.txt     |   14 +++++++-------\n Documentation/git-fast-import.txt  |   22 +++++++++++-----------\n Documentation/git-name-rev.txt     |    2 +-\n Documentation/git-rebase.txt       |    2 +-\n Documentation/git.txt              |   11 ++++-------\n Documentation/gitcli.txt           |    2 +-\n Documentation/glossary-content.txt |    4 ++++\n builtin/describe.c                 |    4 ++--\n builtin/revert.c                   |    4 ++--\n contrib/examples/git-reset.sh      |    2 +-\n contrib/examples/git-revert.sh     |    4 ++--\n 11 files changed, 36 insertions(+), 35 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex 02e015a..ad173ed 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit\n SYNOPSIS\n --------\n [verse]\n-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>...\n+'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit>...\n 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\n \n DESCRIPTION\n@@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1].\n \n OPTIONS\n -------\n-<committish>...::\n-\tCommittish object names to describe.\n+<commit>...::\n+\tCommit object names to describe.\n \n --dirty[=<mark>]::\n \tDescribe the working tree.\n@@ -57,7 +57,7 @@ OPTIONS\n \n --candidates=<n>::\n \tInstead of considering only the 10 most recent tags as\n-\tcandidates to describe the input committish consider\n+\tcandidates to describe the input commit consider\n \tup to <n> candidates.  Increasing <n> above 10 will take\n \tslightly longer but may produce a more accurate result.\n \tAn <n> of 0 will cause only exact matches to be output.\n@@ -139,7 +139,7 @@ be sufficient to disambiguate these commits.\n SEARCH STRATEGY\n ---------------\n \n-For each committish supplied, 'git describe' will first look for\n+For each commit supplied, 'git describe' will first look for\n a tag which tags exactly that commit.  Annotated tags will always\n be preferred over lightweight tags, and tags with newer dates will\n always be preferred over tags with older dates.  If an exact match\n@@ -148,10 +148,10 @@ is found, its name will be output and searching will stop.\n If an exact match was not found, 'git describe' will walk back\n through the commit history to locate an ancestor commit which\n has been tagged.  The ancestor's tag will be output along with an\n-abbreviation of the input committish's SHA1.\n+abbreviation of the input commit's SHA1.\n \n If multiple tags were found during the walk then the tag which\n-has the fewest commits different from the input committish will be\n+has the fewest commits different from the input commit will be\n selected and output.  Here fewest commits different is defined as\n the number of commits which would be shown by `git log tag..input`\n will be the smallest number of commits possible.\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex f56dfca..0509213 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -350,8 +350,8 @@ change to the project.\n \t('author' (SP <name>)? SP LT <email> GT SP <when> LF)?\n \t'committer' (SP <name>)? SP LT <email> GT SP <when> LF\n \tdata\n-\t('from' SP <committish> LF)?\n-\t('merge' SP <committish> LF)?\n+\t('from' SP <commit> LF)?\n+\t('merge' SP <commit> LF)?\n \t(filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*\n \tLF?\n ....\n@@ -428,9 +428,9 @@ as the current commit on that branch is automatically assumed to\n be the first ancestor of the new commit.\n \n As `LF` is not valid in a Git refname or SHA-1 expression, no\n-quoting or escaping syntax is supported within `<committish>`.\n+quoting or escaping syntax is supported within `<commit>`.\n \n-Here `<committish>` is any of the following:\n+Here `<commit>` is any of the following:\n \n * The name of an existing branch already in fast-import's internal branch\n   table.  If fast-import doesn't know the name, it's treated as a SHA-1\n@@ -475,7 +475,7 @@ additional ancestors (forming a 16-way merge).  For this reason\n it is suggested that frontends do not use more than 15 `merge`\n commands per commit; 16, if starting a new, empty branch.\n \n-Here `<committish>` is any of the commit specification expressions\n+Here `<commit>` is any of the commit specification expressions\n also accepted by `from` (see above).\n \n `filemodify`\n@@ -649,7 +649,7 @@ External data format::\n \tcommit that is to be annotated.\n +\n ....\n-\t'N' SP <dataref> SP <committish> LF\n+\t'N' SP <dataref> SP <commit> LF\n ....\n +\n Here `<dataref>` can be either a mark reference (`:<idnum>`)\n@@ -662,13 +662,13 @@ Inline data format::\n \tcommand.\n +\n ....\n-\t'N' SP 'inline' SP <committish> LF\n+\t'N' SP 'inline' SP <commit> LF\n \tdata\n ....\n +\n See below for a detailed description of the `data` command.\n \n-In both formats `<committish>` is any of the commit specification\n+In both formats `<commit>` is any of the commit specification\n expressions also accepted by `from` (see above).\n \n `mark`\n@@ -699,7 +699,7 @@ lightweight (non-annotated) tags see the `reset` command below.\n \n ....\n \t'tag' SP <name> LF\n-\t'from' SP <committish> LF\n+\t'from' SP <commit> LF\n \t'tagger' (SP <name>)? SP LT <email> GT SP <when> LF\n \tdata\n ....\n@@ -744,11 +744,11 @@ branch from an existing commit without creating a new commit.\n \n ....\n \t'reset' SP <ref> LF\n-\t('from' SP <committish> LF)?\n+\t('from' SP <commit> LF)?\n \tLF?\n ....\n \n-For a detailed description of `<ref>` and `<committish>` see above\n+For a detailed description of `<ref>` and `<commit>` see above\n under `commit` and `from`.\n \n The `LF` after the command is optional (it used to be required).\ndiff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt\nindex 2108237..40af544 100644\n--- a/Documentation/git-name-rev.txt\n+++ b/Documentation/git-name-rev.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git name-rev' [--tags] [--refs=<pattern>]\n-\t       ( --all | --stdin | <committish>... )\n+\t       ( --all | --stdin | <commit>... )\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 96680c8..dbb5484 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -168,7 +168,7 @@ would result in the removal of commits F and G:\n \n This is useful if F and G were flawed in some way, or should not be\n part of topicA.  Note that the argument to --onto and the <upstream>\n-parameter can be any valid commit-ish.\n+parameter can be any valid <commit>.\n \n In case of conflict, 'git rebase' will stop at the first problematic commit\n and leave conflict markers in the tree.  You can use 'git diff' to locate\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 376397c..734acbe 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -475,13 +475,10 @@ Identifier Terminology\n \ttag and commit objects until it finds a tree.\n \n <commit>::\n-\tIndicates a commit object name.\n-\n-<commit-ish>::\n-\tIndicates a commit or tag object name.  A\n-\tcommand that takes a <commit-ish> argument ultimately wants to\n-\toperate on a <commit> object but automatically dereferences\n-\t<tag> objects that point at a <commit>.\n+\tIndicates a commit object name, or the name of a tag object that\n+\tpoints at a commit. A command that takes a <commit> argument\n+\tultimately wants to operate on a commit object but automatically\n+\tdereferences tag objects until it finds a commit.\n \n <type>::\n \tIndicates that an object type is required.\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex eefee3d..b56e7c3 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -81,7 +81,7 @@ couple of magic command line options:\n +\n ---------------------------------------------\n $ git describe -h\n-usage: git describe [options] <committish>...\n+usage: git describe [options] <commit>...\n \n     --contains            find the tag that comes after the commit\n     --debug               debug search strategy on stderr\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex f04b48e..40a1f11 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -82,6 +82,10 @@ to point at the new commit.\n \tto the top <<def_directory,directory>> of the stored\n \trevision.\n \n+[[def_commit-ish]][[def_committish]]commit-ish / committish::\n+\tA <<def_ref,ref>> pointing to either a <<def_commit_object,commit\n+\tobject>>, or a <<def_tag_object,tag object>> pointing to a tag or commit object.\n+\n [[def_core_git]]core git::\n \tFundamental data structures and utilities of git. Exposes only limited\n \tsource code management tools.\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex 34a8031..4b5a217 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -12,7 +12,7 @@\n #define MAX_TAGS\t(FLAG_BITS - 1)\n \n static const char * const describe_usage[] = {\n-\t\"git describe [options] <committish>...\",\n+\t\"git describe [options] <commit>...\",\n \t\"git describe [options] --dirty\",\n \tNULL\n };\n@@ -462,7 +462,7 @@ int cmd_describe(int argc, const char **argv, const char *prefix)\n \t\t\tdirty = NULL;\n \t\tdescribe(\"HEAD\", 1);\n \t} else if (dirty) {\n-\t\tdie(\"--dirty is incompatible with committishes\");\n+\t\tdie(\"--dirty is incompatible with commits\");\n \t} else {\n \t\twhile (argc-- > 0) {\n \t\t\tdescribe(*argv++, argc == 0);\ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex bb6e9e8..f00b6d6 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -27,12 +27,12 @@\n  */\n \n static const char * const revert_usage[] = {\n-\t\"git revert [options] <commit-ish>\",\n+\t\"git revert [options] <commit>\",\n \tNULL\n };\n \n static const char * const cherry_pick_usage[] = {\n-\t\"git cherry-pick [options] <commit-ish>\",\n+\t\"git cherry-pick [options] <commit>\",\n \tNULL\n };\n \ndiff --git a/contrib/examples/git-reset.sh b/contrib/examples/git-reset.sh\nindex bafeb52..d287a80 100755\n--- a/contrib/examples/git-reset.sh\n+++ b/contrib/examples/git-reset.sh\n@@ -2,7 +2,7 @@\n #\n # Copyright (c) 2005, 2006 Linus Torvalds and Junio C Hamano\n #\n-USAGE='[--mixed | --soft | --hard]  [<commit-ish>] [ [--] <paths>...]'\n+USAGE='[--mixed | --soft | --hard]  [<commit>] [ [--] <paths>...]'\n SUBDIRECTORY_OK=Yes\n . git-sh-setup\n set_reflog_action \"reset $*\"\ndiff --git a/contrib/examples/git-revert.sh b/contrib/examples/git-revert.sh\nindex 60a05a8..0b6b029 100755\n--- a/contrib/examples/git-revert.sh\n+++ b/contrib/examples/git-revert.sh\n@@ -9,12 +9,12 @@ case \"$0\" in\n \ttest -t 0 && edit=-e\n \treplay=\n \tme=revert\n-\tUSAGE='[--edit | --no-edit] [-n] <commit-ish>' ;;\n+\tUSAGE='[--edit | --no-edit] [-n] <commit>' ;;\n *-cherry-pick* )\n \treplay=t\n \tedit=\n \tme=cherry-pick\n-\tUSAGE='[--edit] [-n] [-r] [-x] <commit-ish>'  ;;\n+\tUSAGE='[--edit] [-n] [-r] [-x] <commit>'  ;;\n * )\n \techo >&2 \"What are you talking about?\"\n \texit 1 ;;\n-- \n1.7.3.2\n"},{"id":"158306","messageId":"1292650725-21149-9-git-send-email-lodatom@gmail.com","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"[PATCH 8/8] describe docs: note that <commit> is optional","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T05:38:45Z","receivedAt":"2010-12-18T05:38:45Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"Signed-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-describe.txt |    3 ++-\n Documentation/gitcli.txt       |    2 +-\n builtin/describe.c             |    2 +-\n 3 files changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex ad173ed..8006d59 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit\n SYNOPSIS\n --------\n [verse]\n-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit>...\n+'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit>...]\n 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\n \n DESCRIPTION\n@@ -28,6 +28,7 @@ OPTIONS\n -------\n <commit>...::\n \tCommit object names to describe.\n+\tIf not given, defaults to HEAD.\n \n --dirty[=<mark>]::\n \tDescribe the working tree.\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex b56e7c3..e57f88c 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -81,7 +81,7 @@ couple of magic command line options:\n +\n ---------------------------------------------\n $ git describe -h\n-usage: git describe [options] <commit>...\n+usage: git describe [options] [<commit>...]\n \n     --contains            find the tag that comes after the commit\n     --debug               debug search strategy on stderr\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex 4b5a217..82da278 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -12,7 +12,7 @@\n #define MAX_TAGS\t(FLAG_BITS - 1)\n \n static const char * const describe_usage[] = {\n-\t\"git describe [options] <commit>...\",\n+\t\"git describe [options] [<commit>...]\",\n \t\"git describe [options] --dirty\",\n \tNULL\n };\n-- \n1.7.3.2\n"},{"id":"158310","messageId":"20101218074718.GA6187@burratino","threadId":"26096","inReplyTo":"1292650725-21149-4-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-12-18T07:47:18Z","receivedAt":"2010-12-18T07:47:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Mark Lodato wrote:\n\n> There are some places that literally require a full, 40-character SHA-1\n> ID, rather than a generic revision specifier.\n\nOne name I have seen for these is \"object IDs\", as in git get-tar-commit-id\n(to avoid putting too much emphasis on precisely how the identifiers are\nchosen).\n\n>                                   Use <sha1> in git-diff-tree(1) to note\n> that --stdin only takes <sha1>s, not generic <tree>s or <commit>s.\n\nIn this example, maybe it would be cleanest to spell out \"40-digit\nobject identifier\".\n\nPerhaps something like this?  (The text is more verbose than I'd\nlike and it would be nicer to include an example, though.)\n\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex a7e37b8..85ce185 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -49,9 +49,11 @@ include::diff-options.txt[]\n --stdin::\n \tWhen '--stdin' is specified, the command does not take\n \t<tree-ish> arguments from the command line.  Instead, it\n-\treads lines containing either two <tree>, one <commit>, or a\n-\tlist of <commit> from its standard input.  (Use a single space\n-\tas separator.)\n+\treads lines, each naming two trees, one commit, or multiple\n+\tcommits, from its standard input.  Each line consists of a\n+\tlist of full 40-digit object identifiers with a single space\n+\tas separator.  Objects must be named directly; for example,\n+\ta tag ID cannot be used to represent a commit.\n +\n When two trees are given, it compares the first tree with the second.\n When a single commit is given, it compares the commit with its\n"},{"id":"158309","messageId":"20101218075142.GB6187@burratino","threadId":"26096","inReplyTo":"1292650725-21149-5-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH 4/8] http-fetch docs: use <commit-id> consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-12-18T07:51:42Z","receivedAt":"2010-12-18T07:51:42Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Mark Lodato wrote:\n\n> --- a/Documentation/git-http-fetch.txt\n> +++ b/Documentation/git-http-fetch.txt\n> @@ -8,7 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP\n>  \n>  SYNOPSIS\n>  --------\n> -'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url>\n> +'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit-id> <url>\n>  \n>  DESCRIPTION\n>  -----------\n> @@ -16,7 +16,7 @@ Downloads a remote git repository via HTTP.\n>  \n>  OPTIONS\n>  -------\n> -commit-id::\n> +<commit-id>::\n>          Either the hash or the filename under [URL]/refs/ to\n>          pull.\n\nDoes this mean the same thing as \"commit id\" in other manpages?\n"},{"id":"158311","messageId":"20101218083516.GC6187@burratino","threadId":"26096","inReplyTo":"1292650725-21149-7-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH 6/8] docs: use <tree> instead of <tree-ish>","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-12-18T08:35:16Z","receivedAt":"2010-12-18T08:35:16Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Mark Lodato wrote:\n\n> The term \"tree-ish\" was left in the following situations:\n>  - all comments in the code\n>  - situations where \"tree-ish\" is being contrasted to \"tree\"\n>  - error messages, to prevent porcelains from changing\n\nNit: to prevent plumbing from changing?  Or to prevent porcelains\nfrom having to change in response to changes in plumbing?\n\n> --- a/Documentation/RelNotes/1.6.2.4.txt\n> +++ b/Documentation/RelNotes/1.6.2.4.txt\n> @@ -13,7 +13,7 @@ Fixes since v1.6.2.3\n>  * \"git-add -p\" lacked a way to say \"q\"uit to refuse staging any hunks for\n>    the remaining paths.  You had to say \"d\" and then ^C.\n>  \n> -* \"git-checkout <tree-ish> <submodule>\" did not update the index entry at\n> +* \"git-checkout <tree> <submodule>\" did not update the index entry at\n>    the named path; it now does.\n\nIs changing release notes for historical releases like this a good\nidea?  (It not clear to me either way.)\n\n> --- a/Documentation/diff-format.txt\n> +++ b/Documentation/diff-format.txt\n> @@ -7,13 +7,13 @@ The raw output format from \"git-diff-index\", \"git-diff-tree\",\n>  These commands all compare two sets of things; what is\n>  compared differs:\n>  \n> -git-diff-index <tree-ish>::\n> -        compares the <tree-ish> and the files on the filesystem.\n> +git-diff-index <tree>::\n> +        compares the <tree> and the files on the filesystem.\n\nUnrelated: we ought to remove the dash after \"git\" here.  (Thanks\nfor a reminder.)\n\n> --- a/Documentation/git-archive.txt\n> +++ b/Documentation/git-archive.txt\n> @@ -11,7 +11,7 @@ SYNOPSIS\n>  [verse]\n>  'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]\n>  \t      [-o | --output=<file>] [--worktree-attributes]\n> -\t      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>\n> +\t      [--remote=<repo> [--exec=<git-upload-archive>]] <tree>\n>  \t      [<path>...]\n>  \n>  DESCRIPTION\n> @@ -70,7 +70,7 @@ OPTIONS\n>  \tUsed with --remote to specify the path to the\n>  \t'git-upload-archive' on the remote side.\n>  \n> -<tree-ish>::\n> +<tree>::\n>  \tThe tree or commit to produce an archive for.\n\nIn this case, it might be less confusing to explicitly say (<commit> |\n<tree>), since the behavior is:\n\n . commit id and timestamp recorded from commit if a commit is\n   used\n . no commit id and time of invocation (!) recorded if a tree is\n   used directly\n\nmeaning \"git archive commit\" and \"git archive commit^{tree}\" do not\nalways have the same behavior.\n\n> --- a/Documentation/git-commit-tree.txt\n> +++ b/Documentation/git-commit-tree.txt\n> @@ -36,7 +36,8 @@ state was.\n>  OPTIONS\n>  -------\n>  <tree>::\n> -\tAn existing tree object\n> +\tAn existing tree object.  Unlike other git commands, this must\n> +\tbe an actual tree object, not a commit or tag.\n\nMaybe it would be worth dropping that constraint (in the code) for\nsimplicity?\n\nIf not, it would be nice to give a fuller explanation, something to\nthis effect:\n\n\tAn existing tree object.  To [reason here], the argument will\n\tnot be automatically dereferenced to a tree if it names a commit\n\tor tag; you must instead specify the tree explicitly, for\n\texample by ending the argument with ^{tree}.\n\nWording could surely be improved.\n\n> --- a/Documentation/git-diff-index.txt\n> +++ b/Documentation/git-diff-index.txt\n> @@ -8,7 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi\n>  \n>  SYNOPSIS\n>  --------\n> -'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...]\n> +'git diff-index' [-m] [--cached] [<common diff options>] <tree> [<path>...]\n>  \n>  DESCRIPTION\n>  -----------\n> @@ -22,7 +22,7 @@ OPTIONS\n>  -------\n>  include::diff-options.txt[]\n>  \n> -<tree-ish>::\n> +<tree>::\n>  \tThe id of a tree object to diff against.\n\nIs an arbitrary tree name okay, or only tree ids?\n\n> --- a/Documentation/git-ls-tree.txt\n> +++ b/Documentation/git-ls-tree.txt\n> @@ -35,8 +35,8 @@ in the current working directory.  Note that:\n>  \n>  OPTIONS\n>  -------\n> -<tree-ish>::\n> -\tId of a tree-ish.\n> +<tree>::\n> +\tThe id of a tree object.\n\nLikewise.\n\n> --- a/Documentation/git-merge-tree.txt\n> +++ b/Documentation/git-merge-tree.txt\n> @@ -12,7 +12,7 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> -Reads three treeish, and output trivial merge results and\n> +Reads three <tree>s, and output trivial merge results and\n\nSince the string \"<tree>\" does not appear in the synopsis, it seems\nodd to mention it here.  Maybe it would be clearer to say:\n\nSYNOPSIS\n\tgit merge-tree <base-tree> <branch1> <branch2>\n\nDESCRIPTION\n\tReads three trees and outputs trivial merge results and\n\tconflicting entries to the standard output. This\n\nor (though I like the previous synopsis much more)\n\nSYNOPSIS\n\tgit merge-tree <tree> <tree> <tree>\n\nDESCRIPTION\n\tReads three trees and outputs trivial merge results and\n\tconflicting entries to the standard output.  The arguments\n\tare in the same order as those for \"git read-tree\": the\n\tfirst represents the original (basis) state and the other\n\ttwo represent versions with improvements that need to be\n\tmerged. This\n\n> --- a/Documentation/git-read-tree.txt\n> +++ b/Documentation/git-read-tree.txt\n> @@ -118,7 +118,7 @@ OPTIONS\n>  \tInstead of reading tree object(s) into the index, just empty\n>  \tit.\n>  \n> -<tree-ish#>::\n> +<tree-#>::\n>  \tThe id of the tree object(s) to be read/merged.\n\nJust \"The tree objects to be read or merged\", not necessarily named\nby id, right?\n\n> --- a/Documentation/git-svn.txt\n> +++ b/Documentation/git-svn.txt\n> @@ -314,8 +314,8 @@ Any other arguments are passed directly to 'git log'\n>  'find-rev'::\n>  \tWhen given an SVN revision number of the form 'rN', returns the\n>  \tcorresponding git commit hash (this can optionally be followed by a\n> -\ttree-ish to specify which branch should be searched).  When given a\n> -\ttree-ish, returns the corresponding SVN revision number.\n> +\t<tree> to specify which branch should be searched).  When given a\n> +\t<tree>, returns the corresponding SVN revision number.\n\nThe placeholder <tree> sounds odd in descriptive text like this.\nMaybe:\n\n\tIf the first argument is of the form 'rN', prints the\n\tcorresponding git commit id.  An optional second argument can\n\tname a commit, to limit the search to commits accessible from\n\tthat commit.\n\n\tOtherwise, the first (and only) argument is interpreted as a\n\tgit tree name and this subcommand prints the corresponding\n\tSVN revision number.\n\n> @@ -345,7 +345,7 @@ Any other arguments are passed directly to 'git log'\n>  \tfor use after commands like \"git checkout\" or \"git reset\".\n>  \n>  'commit-diff'::\n> -\tCommits the diff of two tree-ish arguments from the\n> +\tCommits the diff of two <tree> arguments from the\n\nLikewise.  \"Two trees named on the command line\" should be clear.\n\n> --- a/Documentation/git-tar-tree.txt\n> +++ b/Documentation/git-tar-tree.txt\n> @@ -29,7 +29,7 @@ It can be extracted using 'git get-tar-commit-id'.\n>  OPTIONS\n>  -------\n>  \n> -<tree-ish>::\n> +<tree>::\n>  \tThe tree or commit to produce tar archive for.  If it is\n>  \tthe object name of a commit object.\n\nHuh?  (Not a problem introduced by this patch, but...)\n\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -469,17 +469,14 @@ Identifier Terminology\n>  \tIndicates a blob object name.\n>  \n>  <tree>::\n> -\tIndicates a tree object name.\n> +\tIndicates a tree object name, or the name of tag or commit that points\n> +\tat a tree.  A command that takes a <tree> argument ultimately\n> +\twants to operate on a tree object but automatically dereferences\n> +\ttag and commit objects until it finds a tree.\n>  \n>  <commit>::\n>  \tIndicates a commit object name.\n>  \n> -<tree-ish>::\n> -\tIndicates a tree, commit or tag object name.  A\n> -\tcommand that takes a <tree-ish> argument ultimately wants to\n> -\toperate on a <tree> object but automatically dereferences\n> -\t<commit> and <tag> objects that point at a <tree>.\n> -\n\nI first read the new description as\n\n\tIndicates a tree name, or the name of a tag or commit ...\n\nwhich seemed odd --- this always is a tree name.  Maybe\n\n <tree>::\n\tIndicates a parameter specifying a tree, commit, or tag object.\n\tA command that takes a <tree> argument ultimately wants to\n\toperate on a tree object so it automatically dereferences\n\ttag and commit objects until it finds a tree.\n\nThanks for eliminating the confusing <commit>, <tag>, etc markup.\n\n> --- a/Documentation/gitcli.txt\n> +++ b/Documentation/gitcli.txt\n> @@ -15,8 +15,8 @@ DESCRIPTION\n>  \n>  This manual describes the convention used throughout git CLI.\n>  \n> -Many commands take revisions (most often \"commits\", but sometimes\n> -\"tree-ish\", depending on the context and command) and paths as their\n> +Many commands take revisions (most often <commit>s, but sometimes\n> +<tree>s, depending on the context and command) and paths as their\n\nMaybe\n\n Many commands take revisions (most often commits but sometimes\n trees, depending on the context and command) and paths as their\n arguments.  Here are the rules:\n\nto avoid emphasizing a technicality.\n\n> --- a/Documentation/gittutorial-2.txt\n> +++ b/Documentation/gittutorial-2.txt\n> @@ -209,10 +209,8 @@ Note, by the way, that lots of commands take a tree as an argument.\n>  But as we can see above, a tree can be referred to in many different\n>  ways--by the SHA1 name for that tree, by the name of a commit that\n>  refers to the tree, by the name of a branch whose head refers to that\n> -tree, etc.--and most such commands can accept any of these names.\n> -\n> -In command synopses, the word \"tree-ish\" is sometimes used to\n> -designate such an argument.\n> +tree, etc.--and all such commands can accept any of these names unless\n> +otherwise stated.\n\n... otherwise stated in the manual pages?\n\n> --- a/t/t4100/t-apply-3.patch\n> +++ b/t/t4100/t-apply-3.patch\n[...]\n> --- a/t/t4100/t-apply-7.patch\n> +++ b/t/t4100/t-apply-7.patch\n[...]\n\nThese last two aren't worth it, I think. :)\n\nI very much like this change.  Ideally it should be possible to deal\nwith some of the nontrivial parts first in separate patches before\na last trivial one that does not do much more than change tree-ish ->\ntree.\n"},{"id":"158312","messageId":"20101218083925.GD6187@burratino","threadId":"26096","inReplyTo":"1292650725-21149-8-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH 7/8] docs: use <commit> instead of <commit-ish>","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-12-18T08:39:25Z","receivedAt":"2010-12-18T08:39:25Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Mark Lodato wrote:\n\n> --- a/Documentation/git-describe.txt\n> +++ b/Documentation/git-describe.txt\n> @@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1].\n>  \n>  OPTIONS\n>  -------\n> -<committish>...::\n> -\tCommittish object names to describe.\n> +<commit>...::\n> +\tCommit object names to describe.\n\nOr even\n\n\tCommits to describe.\n\n:)\n\n> --- a/Documentation/git-fast-import.txt\n> +++ b/Documentation/git-fast-import.txt\n> @@ -350,8 +350,8 @@ change to the project.\n>  \t('author' (SP <name>)? SP LT <email> GT SP <when> LF)?\n>  \t'committer' (SP <name>)? SP LT <email> GT SP <when> LF\n>  \tdata\n> -\t('from' SP <committish> LF)?\n> -\t('merge' SP <committish> LF)?\n> +\t('from' SP <commit> LF)?\n> +\t('merge' SP <commit> LF)?\n\nAs the audience of this manual page is people mostly familiar with\nother version control systems, it needs to be very explicit.  Not sure\nwhat the best solution is, just pointing out the worry.\n"},{"id":"158313","messageId":"20101218084908.GE6187@burratino","threadId":"26096","inReplyTo":"1292650725-21149-1-git-send-email-lodatom@gmail.com","subject":"Re: [PATCHv2 0/8] docs: use metavariables consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-12-18T08:49:08Z","receivedAt":"2010-12-18T08:49:08Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Mark Lodato wrote:\n\n>                               The biggest change is to drop the <tree-ish> and\n> <commit-ish> (or <committish>) notation and just use <tree> or <commit>, since\n> every command but commit-tree accepts tree-ishes and commit-ishes.\n\nThanks.  I think this will encourage UI consistency (\"where you accept\na tree, accepts commits and tags, too\") as a side effect.\n\n> This is a rework of my earlier patch set from March [1], with the following\n> differences:\n>\n> - Drop the patch to commit-tree that makes it accept a tree-ish.\n\nAh, missed this before.  It is not clear to me why this difference ---\nis it just to be conservative about changing behavior?\n\n> [1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484\nhttp://thread.gmane.org/gmane.comp.version-control.git/142078\n"},{"id":"158314","messageId":"m3hbebl7tv.fsf@localhost.localdomain","threadId":"26096","inReplyTo":"1292650725-21149-3-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH 2/8] docs: use `...' instead of `*' for multiplicity","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-12-18T10:00:42Z","receivedAt":"2010-12-18T10:00:42Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Mark Lodato <lodatom@gmail.com> writes:\n\n> Finish the work of 0adda93 (Use parentheses and `...' where appropriate)\n> to follow the rules set forth in Documentation/CodingGuidelines.\n> \n> Signed-off-by: Mark Lodato <lodatom@gmail.com>\n\n[...]\n\n> -\t\"git describe [options] <committish>*\",\n> +\t\"git describe [options] <committish>...\",\n\nIsn't <sth>... one or more, while <sth>* is zero or more, i.e. shouldn't\n<sth>* be replaced by [<sth>...]?\n\nHmmm... I see that <sth>* was actively wrong if it was to mean zero or\nmore, so your change doesn't only make documentation more consistent,\nbut fixes errorneous use of convention.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"158324","messageId":"AANLkTikKFSNC0MiZ0be6mUZFqR3atZspD9JfgKVyrrek@mail.gmail.com","threadId":"26096","inReplyTo":"m3hbebl7tv.fsf@localhost.localdomain","subject":"Re: [PATCH 2/8] docs: use `...' instead of `*' for multiplicity","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T16:32:02Z","receivedAt":"2010-12-18T16:32:02Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Sat, Dec 18, 2010 at 5:00 AM, Jakub Narebski <jnareb@gmail.com> wrote:\n> Mark Lodato <lodatom@gmail.com> writes:\n>\n>> Finish the work of 0adda93 (Use parentheses and `...' where appropriate)\n>> to follow the rules set forth in Documentation/CodingGuidelines.\n>>\n>> Signed-off-by: Mark Lodato <lodatom@gmail.com>\n>\n> [...]\n>\n>> -     \"git describe [options] <committish>*\",\n>> +     \"git describe [options] <committish>...\",\n>\n> Isn't <sth>... one or more, while <sth>* is zero or more, i.e. shouldn't\n> <sth>* be replaced by [<sth>...]?\n\nYes, I was confused by the * notation - one more reason to get rid of it!\n\n> Hmmm... I see that <sth>* was actively wrong if it was to mean zero or\n> more, so your change doesn't only make documentation more consistent,\n> but fixes errorneous use of convention.\n\nI think zero or more is correct, which is why I submitted patch 8/8 to\nchange from <commit>... to [<commit>...].  Now I understand that all\n8/8 was doing was fixing a mistake I introduced in this patch.  I'll\ncorrect it in the next version.\n"},{"id":"158325","messageId":"AANLkTi=vj=9-JO9QCb52qJin3Ezoi7WO_uoZaoX=ZEfY@mail.gmail.com","threadId":"26096","inReplyTo":"20101218084908.GE6187@burratino","subject":"Re: [PATCHv2 0/8] docs: use metavariables consistently","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-12-18T16:45:11Z","receivedAt":"2010-12-18T16:45:11Z","isPatch":false,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Sat, Dec 18, 2010 at 3:49 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Mark Lodato wrote:\n>> This is a rework of my earlier patch set from March [1], with the following\n>> differences:\n>>\n>> - Drop the patch to commit-tree that makes it accept a tree-ish.\n>\n> Ah, missed this before.  It is not clear to me why this difference ---\n> is it just to be conservative about changing behavior?\n\nExactly.  Junio replied to my original email saying he did not think\nthis patch was unsafe, so if you think the patch is a good idea, I'll\nre-send it.\n\n>> [1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484\n> http://thread.gmane.org/gmane.comp.version-control.git/142078\n\nAs an aside, how do you actually find threads on gmane?  I can't find\nanything on Google.\n"},{"id":"158326","messageId":"7voc8ihq4a.fsf@alter.siamese.dyndns.org","threadId":"26096","inReplyTo":"20101218074718.GA6187@burratino","subject":"Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-18T18:50:45Z","receivedAt":"2010-12-18T18:50:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Mark Lodato wrote:\n>\n>> There are some places that literally require a full, 40-character SHA-1\n>> ID, rather than a generic revision specifier.\n>\n> One name I have seen for these is \"object IDs\", as in git get-tar-commit-id\n> (to avoid putting too much emphasis on precisely how the identifiers are\n> chosen).\n\nYes, I think I also saw \"a full object name\" (cf. diff --full-index) and\nevan \"object name\" (cf. git-pack-objects(1)).  These are all deliberate\nefforts to stay away from spelling SHA-1 explicitly, and I think it makes\nsense to do so here.  \"40-digit object ID\" is a mouthful, though.\n\nAs to what this series tries to do, I think it is generally a good idea to\nstart allowing documents to say <tree> when a reader can plug either a\ncommit or a tree, rather than <tree-ish>, only because all Porcelains\nautomatically dereference object names to needed types these days.\n\nBut such a change needs to mark places that _must_ take the name of an\nobject of the specific type somehow.  It is Ok to say ls-tree takes a\ntree, but then we must say you should feed commit-tree nothing but a tree.\n\nIt is a separate issue to allow plumbings to automatically dereference\nwhen both of the following two conditions hold: (1) the intent is clear\nfrom the context; (2) nobody sane would have been relying on the side\neffect of the current typechecking.\n\nLetting commit-tree to unwrap a tree-ish to a tree would be a good example\nthat clearly satisfies (1)---I am not sure about the other one.\n"},{"id":"158331","messageId":"7vhbeahln6.fsf@alter.siamese.dyndns.org","threadId":"26096","inReplyTo":"20101218084908.GE6187@burratino","subject":"Re: [PATCHv2 0/8] docs: use metavariables consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-18T20:27:25Z","receivedAt":"2010-12-18T20:27:25Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Ah, missed this before.  It is not clear to me why this difference ---\n> is it just to be conservative about changing behavior?\n\nYes.  It is clear from the context you mean its tree if you feed a commit\nto commit-tree, but the original intent of not dereferncing was to avoid\nmistakes by scripts and people, so you need to make a convincing argument\nthat not derefencing does not help avoiding mistakes, and prove that\nnobody's script is relying on the current behaviour for type-checking\npurposes.\n"}]}