{"thread":{"id":"23006","subject":"[PATCH/RFC 01/12] commit-tree: allow indirect tree references","startedAt":"2010-03-13T04:52:52Z","lastAt":"2010-03-16T01:12:08Z","messageCount":20,"participants":["Mark Lodato","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":12},"messages":[{"id":"136700","messageId":"1268455984-19061-1-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":null,"subject":"[PATCH/RFC 00/12] docs: use metavariables consistently","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:52Z","receivedAt":"2010-03-13T04:52:52Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"Based on master, 90a2bf9ca155c8e0e43d9e30197d9562dd02ea96.\n\nThis patch series is an attempt to make the documentation and usage\nstatements consistent in how metavariables [1], such as <commit>, are\nused.  The biggest changes are to get rid of the terms <commit-ish> and\n<tree-ish>, and instead prefer simple <commit> and <tree>.  It ends up\nthat almost all commands, with the exception of git-commit-tree, accept\nthe -ish versions of these objects.  The first patch --- which should be\nthe only non-trivial change to actual code --- modifies commit-tree to\naccept any tree-ish.  The rest of the patches should all be confined to\ndocumentation, usage statements, or code comments.\n\nI submit this as an \"RFC\" because I don't expect this to be accepted\nright away.  The change set is fairly large, and I imagine some of these\nchanges will meet resistance.  My overall goal is to make the\ndocumentation consistent and readable throughout, and I hope that this\nseries makes progress toward that end.\n\n[1] I say \"metavariable\", from Python's optparse, for lack of a better\nterm.\n\nMark Lodato (12):\n  commit-tree: allow indirect tree references\n  grep docs: grep accepts a <tree-ish>, not a <tree>\n  fsck docs: remove outdated and useless diagnostic\n  docs: use <sha1> to mean unabbreviated ID\n  docs: differentiate between <tag> and <tagname>\n  docs: clarify <object>, <commit>, <tree-ish>, etc\n  docs: use <tree> instead of <tree-ish>\n  http-fetch docs: use <commit-id> consistently\n  docs: use <commit> instead of <commit-ish>\n  diff: use brackets for optional args in usage\n  docs: use ... instead of * for multiplicity\n  diff docs: remove <rev>{0,2} notation\n\n Documentation/RelNotes-1.6.2.4.txt           |    2 +-\n Documentation/diff-format.txt                |    8 ++--\n Documentation/diff-generate-patch.txt        |    2 +-\n Documentation/git-archive.txt                |    4 +-\n Documentation/git-checkout-index.txt         |    2 +-\n Documentation/git-checkout.txt               |   14 ++++----\n Documentation/git-commit-tree.txt            |    2 +-\n Documentation/git-describe.txt               |   14 ++++----\n Documentation/git-diff-index.txt             |    4 +-\n Documentation/git-diff-tree.txt              |   18 +++++-----\n Documentation/git-diff.txt                   |    4 +-\n Documentation/git-difftool.txt               |    2 +-\n Documentation/git-fast-import.txt            |   22 ++++++------\n Documentation/git-for-each-ref.txt           |    2 +-\n Documentation/git-fsck.txt                   |    5 +--\n Documentation/git-http-fetch.txt             |    4 +-\n Documentation/git-ls-files.txt               |    8 ++--\n Documentation/git-ls-tree.txt                |    4 +-\n Documentation/git-merge-index.txt            |    2 +-\n Documentation/git-mergetool.txt              |    2 +-\n Documentation/git-name-rev.txt               |    2 +-\n Documentation/git-pack-objects.txt           |    2 +-\n Documentation/git-push.txt                   |    2 +-\n Documentation/git-read-tree.txt              |    4 +-\n Documentation/git-rebase.txt                 |    2 +-\n Documentation/git-relink.txt                 |    2 +-\n Documentation/git-shortlog.txt               |    2 +-\n Documentation/git-tar-tree.txt               |    4 +-\n Documentation/git-update-index.txt           |    4 +-\n Documentation/git.txt                        |   45 ++++++++++++++----------\n Documentation/gitcli.txt                     |    2 +-\n Documentation/howto/revert-branch-rebase.txt |    2 +-\n Documentation/pull-fetch-param.txt           |    2 +-\n archive.c                                    |    4 +-\n builtin/commit-tree.c                        |   15 +++++---\n builtin/describe.c                           |    4 +-\n builtin/diff-index.c                         |    2 +-\n builtin/diff-tree.c                          |    2 +-\n builtin/diff.c                               |    2 +-\n builtin/ls-files.c                           |    4 +-\n builtin/ls-tree.c                            |    2 +-\n builtin/merge-index.c                        |    2 +-\n builtin/merge.c                              |    2 +-\n builtin/pack-objects.c                       |    2 +-\n builtin/push.c                               |    2 +-\n builtin/revert.c                             |    4 +-\n builtin/tar-tree.c                           |    2 +-\n contrib/examples/git-merge.sh                |    2 +-\n contrib/examples/git-reset.sh                |    2 +-\n contrib/examples/git-revert.sh               |    4 +-\n fast-import.c                                |   16 ++++----\n git-svn.perl                                 |    2 +-\n remote.c                                     |    4 +-\n t/t1101-commit-tree-indirect.sh              |   49 ++++++++++++++++++++++++++\n t/t4100/t-apply-3.patch                      |    8 ++--\n t/t4100/t-apply-7.patch                      |    8 ++--\n 56 files changed, 200 insertions(+), 144 deletions(-)\n create mode 100755 t/t1101-commit-tree-indirect.sh\n"},{"id":"136696","messageId":"1268455984-19061-2-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 01/12] commit-tree: allow indirect tree references","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:53Z","receivedAt":"2010-03-13T04:52:53Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"'git commit-tree' was the last remaining built-in to accept a <tree> but\nnot a <tree-ish> (an indirect tree reference through a commit or tag\nobject.)\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\nA similar thing should be done for the parent commits.  As far as I can \ntell, this is the only command that requires a commit object, not a tag.\n\n Documentation/git-commit-tree.txt |    4 +-\n builtin/commit-tree.c             |   13 ++++++----\n t/t1101-commit-tree-indirect.sh   |   49 +++++++++++++++++++++++++++++++++++++\n 3 files changed, 59 insertions(+), 7 deletions(-)\n create mode 100755 t/t1101-commit-tree-indirect.sh\n\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 6188854..67b6bc0 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object\n \n SYNOPSIS\n --------\n-'git commit-tree' <tree> [-p <parent commit>]\\* < changelog\n+'git commit-tree' <tree-ish> [-p <parent commit>]\\* < changelog\n \n DESCRIPTION\n -----------\n@@ -35,7 +35,7 @@ state was.\n \n OPTIONS\n -------\n-<tree>::\n+<tree-ish>::\n \tAn existing tree object\n \n -p <parent commit>::\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 90dac34..96a421e 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -97,16 +97,19 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)\n {\n \tint i;\n \tstruct commit_list *parents = NULL;\n-\tunsigned char tree_sha1[20];\n-\tunsigned char commit_sha1[20];\n+\tunsigned char sha1[20];\n \tstruct strbuf buffer = STRBUF_INIT;\n+\tstruct tree *tree;\n \n \tgit_config(git_default_config, NULL);\n \n \tif (argc < 2 || !strcmp(argv[1], \"-h\"))\n \t\tusage(commit_tree_usage);\n-\tif (get_sha1(argv[1], tree_sha1))\n+\tif (get_sha1(argv[1], sha1))\n \t\tdie(\"Not a valid object name %s\", argv[1]);\n+\ttree = parse_tree_indirect(sha1);\n+\tif (!tree)\n+\t\tdie(\"%s is not a valid 'tree' object\", argv[1]);\n \n \tfor (i = 2; i < argc; i += 2) {\n \t\tunsigned char sha1[20];\n@@ -124,8 +127,8 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)\n \tif (strbuf_read(&buffer, 0, 0) < 0)\n \t\tdie_errno(\"git commit-tree: failed to read\");\n \n-\tif (!commit_tree(buffer.buf, tree_sha1, parents, commit_sha1, NULL)) {\n-\t\tprintf(\"%s\\n\", sha1_to_hex(commit_sha1));\n+\tif (!commit_tree(buffer.buf, tree->object.sha1, parents, sha1, NULL)) {\n+\t\tprintf(\"%s\\n\", sha1_to_hex(sha1));\n \t\treturn 0;\n \t}\n \telse\ndiff --git a/t/t1101-commit-tree-indirect.sh b/t/t1101-commit-tree-indirect.sh\nnew file mode 100755\nindex 0000000..905bad7\n--- /dev/null\n+++ b/t/t1101-commit-tree-indirect.sh\n@@ -0,0 +1,49 @@\n+#!/bin/sh\n+#\n+# Copyright (c) 2010 Mark Lodato\n+#\n+\n+test_description='git commit-tree works with indirect references'\n+\n+. ./test-lib.sh\n+\n+get_tree() {\n+\tgit cat-file commit $1 | sed -n -e 's/^tree //p'\n+}\n+\n+test_expect_success 'prepare the repository' '\n+\ttouch a &&\n+\tgit add a &&\n+\tgit commit -m x &&\n+\tgit tag -a -m x tag-commit &&\n+\tgit tag -a -m x tag-tree HEAD^{tree} &&\n+\tgit tag -a -m x tag-blob HEAD:a &&\n+\tgit tag -a -m x tag-tag-commit tag-commit\n+'\n+\n+expected_tree=\"$(get_tree HEAD)\"\n+\n+test_success() {\n+\ttest_expect_success \"commit-tree succeeds with $2\" '\n+\t\tid=\"$(echo x | git commit-tree '\"$1\"')\" &&\n+\t\ttree=\"$(get_tree $id)\" &&\n+\t\ttest \"x$tree\" = \"x$expected_tree\"\n+\t'\n+}\n+test_failure() {\n+\ttest_expect_code 128 \"commit-tree fails with $2\" '\n+\t\techo x | git commit-tree '\"$1\"' 2>/dev/null\n+\t'\n+}\n+\n+test_failure HEAD:a \"a blob\"\n+test_success HEAD^{tree} \"a tree\"\n+test_success HEAD \"HEAD\"\n+test_success master \"a branch\"\n+test_failure foo \"an invalid object name\"\n+test_failure tag-blob \"a tag pointing to a blob\"\n+test_success tag-tree \"a tag pointing to a tree\"\n+test_success tag-commit \"a tag pointing to a commit\"\n+test_success tag-tag-commit \"a tag pointing to a tag (to a commit)\"\n+\n+test_done\n-- \n1.7.0.2\n"},{"id":"136698","messageId":"1268455984-19061-3-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:54Z","receivedAt":"2010-03-13T04:52:54Z","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 builtin/commit-tree.c      |    2 +-\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 4b32322..02d6306 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -21,7 +21,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@@ -168,7 +168,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 \ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 96a421e..770baa2 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)\n \t\t    typename(expect));\n }\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-ish> [-p <commit>]* < changelog\";\n \n static void new_parent(struct commit *parent, struct commit_list **parents_p)\n {\n-- \n1.7.0.2\n"},{"id":"136701","messageId":"1268455984-19061-4-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 03/12] fsck docs: remove outdated and useless diagnostic","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:55Z","receivedAt":"2010-03-13T04:52:55Z","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.0.2\n"},{"id":"136697","messageId":"1268455984-19061-5-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 04/12] docs: use <sha1> to mean unabbreviated ID","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:56Z","receivedAt":"2010-03-13T04:52:56Z","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.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git-diff-tree.txt |    4 ++--\n Documentation/git.txt           |    5 +++++\n 2 files changed, 7 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex a7e37b8..5d0310b 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 35c0c79..a635281 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -412,6 +412,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 \n-- \n1.7.0.2\n"},{"id":"136699","messageId":"1268455984-19061-6-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:57Z","receivedAt":"2010-03-13T04:52:57Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"In the documentation and user messages, differentiate between <tag>,\nwhich means an actual annotated tag object, and <tagname>, which is\na revision specifier for refs/tags/<tagname>.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\nA similar thing should be done for <head> vs <branch> vs <branchname>.  \nThe term <head> is not used anywhere to mean what it does in git(1); \ninstead, it is used as a more descriptive term for <commit-ish>.  The \nterm <branchname> is used for what git(1) describes as <head>, but the \nterm <branch> is also used, and I'm not sure what it means.  I'll have \nto look into this.\n\n Documentation/git-push.txt         |    2 +-\n Documentation/git.txt              |    8 ++++++--\n Documentation/pull-fetch-param.txt |    2 +-\n builtin/push.c                     |    2 +-\n 4 files changed, 9 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 49b6bd9..5445443 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -55,7 +55,7 @@ you can tell git to update the <dst> ref even when the update is not a\n fast-forward.  This does *not* attempt to merge <src> into <dst>.  See\n EXAMPLES below for details.\n +\n-`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.\n+`tag <tagname>` means the same as `refs/tags/<tagname>:refs/tags/<tagname>`.\n +\n Pushing an empty <src> allows you to delete the <dst> ref from\n the remote repository.\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex a635281..f06e4de 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -420,6 +420,10 @@ Identifier Terminology\n <object>::\n \tIndicates the object name for any type of object.\n \n+<tag>::\n+\tIndicates a tag object name.  This is an annotated tag object, as\n+\topposed to <tagname>, which can refer to any type of object.\n+\n <blob>::\n \tIndicates a blob object name.\n \n@@ -458,9 +462,9 @@ HEAD::\n \tindicates the head of the current branch (i.e. the\n \tcontents of `$GIT_DIR/HEAD`).\n \n-<tag>::\n+<tagname>::\n \ta valid tag 'name'\n-\t(i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).\n+\t(i.e. the contents of `$GIT_DIR/refs/tags/<tagname>`).\n \n <head>::\n \ta valid head 'name'\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex 5dd6e5a..3a947b3 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -66,7 +66,7 @@ is often useful.\n +\n Some short-cut notations are also supported.\n +\n-* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;\n+* `tag <tagname>` means the same as `refs/tags/<tagname>:refs/tags/<tagname>`;\n   it requests fetching everything up to the given tag.\n * A parameter <ref> without a colon is equivalent to\n   <ref>: when pulling/fetching, so it merges <ref> into the current\ndiff --git a/builtin/push.c b/builtin/push.c\nindex f7bc2b2..4227a8e 100644\n--- a/builtin/push.c\n+++ b/builtin/push.c\n@@ -38,7 +38,7 @@ static void set_refspecs(const char **refs, int nr)\n \t\t\tchar *tag;\n \t\t\tint len;\n \t\t\tif (nr <= ++i)\n-\t\t\t\tdie(\"tag shorthand without <tag>\");\n+\t\t\t\tdie(\"tag shorthand without <tagname>\");\n \t\t\tlen = strlen(refs[i]) + 11;\n \t\t\tif (deleterefs) {\n \t\t\t\ttag = xmalloc(len+1);\n-- \n1.7.0.2\n"},{"id":"136702","messageId":"1268455984-19061-7-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 06/12] docs: clarify <object>, <commit>, <tree-ish>, etc","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:58Z","receivedAt":"2010-03-13T04:52:58Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"In git(1), give more precise definitions of <object>, <commit>,\n<tree-ish>, and so on.  In particular, differentiate <object> (which may\ntake generic revision specifiers) from <sha1>, which only accepts\na 40-character hex SHA-1 ID.\n\nAlso note that <rev> is another way to say <commit-ish>.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\n Documentation/git.txt |   38 +++++++++++++++++++++-----------------\n 1 files changed, 21 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex f06e4de..55f3842 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -418,32 +418,36 @@ Identifier Terminology\n \tAbbreviated or symbolic identifiers cannot be used.\n \n <object>::\n-\tIndicates the object name for any type of object.\n+\tIndicates the object name for any type of object.  Symbolic name or\n+\tabbreviated SHA-1 identifiers may be used (see \"SPECIFYING REVISIONS\"\n+\tin linkgit:git-rev-parse[1] for details).\n \n <tag>::\n-\tIndicates a tag object name.  This is an annotated tag object, as\n+\tIndicates a tag-type <object>.  This is an annotated tag object, as\n \topposed to <tagname>, which can refer to any type of object.\n \n-<blob>::\n-\tIndicates a blob object name.\n+<commit>::\n+\tIndicates a commit-type <object>.\n \n <tree>::\n-\tIndicates a tree object name.\n-\n-<commit>::\n-\tIndicates a commit object name.\n+\tIndicates a tree-type <object>.\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+<blob>::\n+\tIndicates a blob-type <object>.\n \n+<rev>::\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>, or a <tag> that points at a <commit-ish>.\n+\tA command that takes a <commit-ish> argument ultimately wants to\n+\toperate on a commit object but automatically dereferences objects\n+\tuntil it finds a commit.\n+\tA <rev> is another name for a <commit-ish>.\n+\n+<tree-ish>::\n+\tIndicates a <tree>, or a <tag> or <commit> that points at a\n+\t<tree-ish>.  A command that takes a <tree-ish> argument ultimately\n+\twants to operate on a tree object but automatically dereferences\n+\tobjects until it finds a tree.\n \n <type>::\n \tIndicates that an object type is required.\n-- \n1.7.0.2\n"},{"id":"136707","messageId":"1268455984-19061-8-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 07/12] docs: use <tree> instead of <tree-ish>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:52:59Z","receivedAt":"2010-03-13T04:52:59Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"There is no longer any reference to <tree> in the documentation, since\nall commands now accept a <tree-ish>, so remove the latter in favor\nof the former.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\nI expect that this, along with the removal of <commit-ish>, is the most \ncontroversial part of the patch series.  I just don't see any reason to \nuse the ugly and long <tree-ish> when <tree> is going unused!\n\n Documentation/RelNotes-1.6.2.4.txt    |    2 +-\n Documentation/diff-format.txt         |    8 ++++----\n Documentation/diff-generate-patch.txt |    2 +-\n Documentation/git-archive.txt         |    4 ++--\n Documentation/git-checkout.txt        |   14 +++++++-------\n Documentation/git-commit-tree.txt     |    4 ++--\n Documentation/git-diff-index.txt      |    4 ++--\n Documentation/git-diff-tree.txt       |   14 +++++++-------\n Documentation/git-diff.txt            |    2 +-\n Documentation/git-grep.txt            |    4 ++--\n Documentation/git-ls-files.txt        |    6 +++---\n Documentation/git-ls-tree.txt         |    4 ++--\n Documentation/git-read-tree.txt       |    4 ++--\n Documentation/git-tar-tree.txt        |    4 ++--\n Documentation/git.txt                 |   11 ++++-------\n archive.c                             |    4 ++--\n builtin/commit-tree.c                 |    2 +-\n builtin/diff-index.c                  |    2 +-\n builtin/diff-tree.c                   |    2 +-\n builtin/ls-files.c                    |    2 +-\n builtin/ls-tree.c                     |    2 +-\n builtin/tar-tree.c                    |    2 +-\n git-svn.perl                          |    2 +-\n t/t4100/t-apply-3.patch               |    8 ++++----\n t/t4100/t-apply-7.patch               |    8 ++++----\n 25 files changed, 59 insertions(+), 62 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..e1311fb 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -7,11 +7,11 @@ 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         compares the trees named by the two arguments.\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 0f25ba7..e0eb126 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -110,7 +110,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 8d3e666..1d520fc 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-checkout.txt b/Documentation/git-checkout.txt\nindex 37c1810..b1061d5 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 <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@@ -28,9 +28,9 @@ creation; see the description of --track below.\n \n When <paths> or --patch are given, this command does *not* switch\n branches.  It updates the named paths in the working tree from\n-the index file, or from a named <tree-ish> (most often a commit).  In\n+the index file, or from a named <tree> (most often a commit).  In\n this case, the `-b` and `--track` options are meaningless and giving\n-either of them results in an error. The <tree-ish> argument can be\n+either of them results in an error. The <tree> argument can be\n used to specify a specific tree-ish (i.e. commit, tag or tree)\n to update the index for the given paths before updating the\n working tree.\n@@ -119,9 +119,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@@ -144,7 +144,7 @@ checks out the branch (instead of detaching).  You may also specify\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 67b6bc0..6188854 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object\n \n SYNOPSIS\n --------\n-'git commit-tree' <tree-ish> [-p <parent commit>]\\* < changelog\n+'git commit-tree' <tree> [-p <parent commit>]\\* < changelog\n \n DESCRIPTION\n -----------\n@@ -35,7 +35,7 @@ state was.\n \n OPTIONS\n -------\n-<tree-ish>::\n+<tree>::\n \tAn existing tree object\n \n -p <parent commit>::\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 5d0310b..e566188 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-diff.txt b/Documentation/git-diff.txt\nindex 723a648..4582179 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -65,7 +65,7 @@ forced by --no-index.\n Just in case if you are doing something exotic, it should be\n noted that all of the <commit> in the above description, except\n for the last two forms that use \"..\" notations, can be any\n-<tree-ish>.\n+<tree>.\n \n For a more complete list of ways to spell <commit>, see\n \"SPECIFYING REVISIONS\" section in linkgit:git-rev-parse[1].\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 02d6306..4b32322 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -21,7 +21,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@@ -168,7 +168,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 3521637..ed63f21 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@@ -98,11 +98,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 1f89d36..4964787 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> [paths...]\n+\t    <tree> [paths...]\n \n DESCRIPTION\n -----------\n@@ -35,7 +35,7 @@ in the current working directory.  Note that:\n \n OPTIONS\n -------\n-<tree-ish>::\n+<tree>::\n \tId of a tree-ish.\n \n -d::\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 567671c..979793e 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -16,7 +16,7 @@ SYNOPSIS\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@@ -272,7 +272,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-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 55f3842..eb87edb 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -430,7 +430,10 @@ Identifier Terminology\n \tIndicates a commit-type <object>.\n \n <tree>::\n-\tIndicates a tree-type <object>.\n+\tIndicates a tree-type <object>, or a <tag> or <commit> that points at\n+\ta <tree>.  A command that takes a <tree> argument ultimately\n+\twants to operate on a tree object but automatically dereferences\n+\tobjects until it finds a tree.\n \n <blob>::\n \tIndicates a blob-type <object>.\n@@ -443,12 +446,6 @@ Identifier Terminology\n \tuntil it finds a commit.\n \tA <rev> is another name for a <commit-ish>.\n \n-<tree-ish>::\n-\tIndicates a <tree>, or a <tag> or <commit> that points at a\n-\t<tree-ish>.  A command that takes a <tree-ish> argument ultimately\n-\twants to operate on a tree object but automatically dereferences\n-\tobjects until it finds a tree.\n-\n <type>::\n \tIndicates that an object type is required.\n \tCurrently one of: `blob`, `tree`, `commit`, or `tag`.\ndiff --git a/archive.c b/archive.c\nindex d700af3..4fefb64 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/commit-tree.c b/builtin/commit-tree.c\nindex 770baa2..225e515 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)\n \t\t    typename(expect));\n }\n \n-static const char commit_tree_usage[] = \"git commit-tree <tree-ish> [-p <commit>]* < 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 {\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 0483749..5c4c5ce 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -6,7 +6,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 2380c21..e446dd5 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -87,7 +87,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 b065061..6dc885d 100644\n--- a/builtin/ls-files.c\n+++ b/builtin/ls-files.c\n@@ -513,7 +513,7 @@ int cmd_ls_files(int argc, const char **argv, const char *prefix)\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\t\t\"pretend that paths removed since <tree> are still present\"),\n \t\tOPT__ABBREV(&abbrev),\n \t\tOPT_END()\n \t};\ndiff --git a/builtin/ls-tree.c b/builtin/ls-tree.c\nindex 4484185..8a52e42 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/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 1a26843..c80eb49 100755\n--- a/git-svn.perl\n+++ b/git-svn.perl\n@@ -997,7 +997,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.0.2\n"},{"id":"136703","messageId":"1268455984-19061-9-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 08/12] http-fetch docs: use <commit-id> consistently","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:53:00Z","receivedAt":"2010-03-13T04:53:00Z","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---\nIt says that it can be \"the filename under ...\", but I couldn't get that \nto work.  Can anyone explain how to use something other than a SHA-1?\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.0.2\n"},{"id":"136704","messageId":"1268455984-19061-10-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:53:01Z","receivedAt":"2010-03-13T04:53:01Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"There exist no commands that accept a <commit> but not a <commit-ish>,\nso there is no reason to use the latter term anymore.  Instead, use\n<commit> everywhere the term <commit-ish>, <committish>, commit-ish, or\ncomittish was used.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\nThis was a little harder than the removal of tree-ish, since commit-ish \nwas used not only in the documentation but in the code.  I tried to \nreplace the term without losing meaning, but the comments in particular \nshould be examined to see if they are just as clear as before.\n\nThe following commands already use the term <commit>, but actually \naccept a <commit-ish>:\n\tbisect, branch, cherry-pick, commit, merge, tag, diff, difftool, \n\tformat-patch, merge-base, rebase, reset, rev-list, revert\n\nThe only commands left that do not accept a commit-ish are:\n\thttp-fetch accepts a <commit-id>, as noted previously\n\tcommit-tree accepts an old <commit> (no tag objects)\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-shortlog.txt               |    2 +-\n Documentation/git.txt                        |   15 ++++++---------\n Documentation/gitcli.txt                     |    2 +-\n Documentation/howto/revert-branch-rebase.txt |    2 +-\n builtin/describe.c                           |    4 ++--\n builtin/merge.c                              |    2 +-\n builtin/revert.c                             |    4 ++--\n contrib/examples/git-merge.sh                |    2 +-\n contrib/examples/git-reset.sh                |    2 +-\n contrib/examples/git-revert.sh               |    4 ++--\n fast-import.c                                |   16 ++++++++--------\n remote.c                                     |    4 ++--\n 16 files changed, 48 insertions(+), 51 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex 6fc5323..f272fa6 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@@ -136,7 +136,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@@ -145,10 +145,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 19082b0..bdf369a 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -340,8 +340,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@@ -418,9 +418,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@@ -465,7 +465,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@@ -632,7 +632,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@@ -645,13 +645,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@@ -682,7 +682,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@@ -727,11 +727,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 823f2a4..e32c393 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-shortlog.txt b/Documentation/git-shortlog.txt\nindex dfd4d0c..61dc039 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]\n-'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...]\n+'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<commit>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex eb87edb..b7c89f9 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -426,8 +426,13 @@ Identifier Terminology\n \tIndicates a tag-type <object>.  This is an annotated tag object, as\n \topposed to <tagname>, which can refer to any type of object.\n \n+<rev>::\n <commit>::\n-\tIndicates a commit-type <object>.\n+\tIndicates a commit-type <object>, or a <tag> that points at a <commit>.\n+\tA command that takes a <commit> argument ultimately wants to\n+\toperate on a commit object but automatically dereferences objects\n+\tuntil it finds a commit.\n+\tA <rev> is another name for a <commit>.\n \n <tree>::\n \tIndicates a tree-type <object>, or a <tag> or <commit> that points at\n@@ -438,14 +443,6 @@ Identifier Terminology\n <blob>::\n \tIndicates a blob-type <object>.\n \n-<rev>::\n-<commit-ish>::\n-\tIndicates a <commit>, or a <tag> that points at a <commit-ish>.\n-\tA command that takes a <commit-ish> argument ultimately wants to\n-\toperate on a commit object but automatically dereferences objects\n-\tuntil it finds a commit.\n-\tA <rev> is another name for a <commit-ish>.\n-\n <type>::\n \tIndicates that an object type is required.\n \tCurrently one of: `blob`, `tree`, `commit`, or `tag`.\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 6928724..de0630f 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/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt\nindex 8c32da6..5272bb0 100644\n--- a/Documentation/howto/revert-branch-rebase.txt\n+++ b/Documentation/howto/revert-branch-rebase.txt\n@@ -160,7 +160,7 @@ $ git pull . master\n Packing 0 objects\n Unpacking 0 objects\n \n-* committish: e3a693c...\trefs/heads/master from .\n+* commit: e3a693c...\trefs/heads/master from .\n Trying to merge e3a693c... into 8c1f5f0... using 10d781b...\n Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f\n  cache.h        |    8 ++++----\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex 71be2a9..4ece73f 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -11,7 +11,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@@ -386,7 +386,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/merge.c b/builtin/merge.c\nindex 3aaec7b..8d62424 100644\n--- a/builtin/merge.c\n+++ b/builtin/merge.c\n@@ -940,7 +940,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)\n \t * This could be traditional \"merge <msg> HEAD <commit>...\"  and\n \t * the way we can tell it is to see if the second token is HEAD,\n \t * but some people might have misused the interface and used a\n-\t * committish that is the same as HEAD there instead.\n+\t * <commit> that is the same as HEAD there instead.\n \t * Traditional format never would have \"-m\" so it is an\n \t * additional safety measure to check for it.\n \t */\ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex eff5268..e06d2a0 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -26,12 +26,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-merge.sh b/contrib/examples/git-merge.sh\nindex 8f617fc..5aeee46 100755\n--- a/contrib/examples/git-merge.sh\n+++ b/contrib/examples/git-merge.sh\n@@ -221,7 +221,7 @@ fi\n \n # This could be traditional \"merge <msg> HEAD <commit>...\"  and the\n # way we can tell it is to see if the second token is HEAD, but some\n-# people might have misused the interface and used a committish that\n+# people might have misused the interface and used a <commit> that\n # is the same as HEAD there instead.  Traditional format never would\n # have \"-m\" so it is an additional safety measure to check for it.\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 49f0032..c543add 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 ;;\ndiff --git a/fast-import.c b/fast-import.c\nindex 309f2c5..08afdc3 100644\n--- a/fast-import.c\n+++ b/fast-import.c\n@@ -22,8 +22,8 @@ Format of STDIN stream:\n     ('author' (sp name)? sp '<' email '>' sp when lf)?\n     'committer' (sp name)? sp '<' email '>' sp when lf\n     commit_msg\n-    ('from' sp committish lf)?\n-    ('merge' sp committish lf)*\n+    ('from' sp commit lf)?\n+    ('merge' sp commit lf)*\n     file_change*\n     lf?;\n   commit_msg ::= data;\n@@ -41,18 +41,18 @@ Format of STDIN stream:\n   file_obm ::= 'M' sp mode sp (hexsha1 | idnum) sp path_str lf;\n   file_inm ::= 'M' sp mode sp 'inline' sp path_str lf\n     data;\n-  note_obm ::= 'N' sp (hexsha1 | idnum) sp committish lf;\n-  note_inm ::= 'N' sp 'inline' sp committish lf\n+  note_obm ::= 'N' sp (hexsha1 | idnum) sp commit lf;\n+  note_inm ::= 'N' sp 'inline' sp commit lf\n     data;\n \n   new_tag ::= 'tag' sp tag_str lf\n-    'from' sp committish lf\n+    'from' sp commit lf\n     ('tagger' (sp name)? sp '<' email '>' sp when lf)?\n     tag_msg;\n   tag_msg ::= data;\n \n   reset_branch ::= 'reset' sp ref_str lf\n-    ('from' sp committish lf)?\n+    ('from' sp commit lf)?\n     lf?;\n \n   checkpoint ::= 'checkpoint' lf\n@@ -91,7 +91,7 @@ Format of STDIN stream:\n      # stream formatting is: \\, \" and LF.  Otherwise these values\n      # are UTF8.\n      #\n-  committish  ::= (ref_str | hexsha1 | sha1exp_str | idnum);\n+  commit      ::= (ref_str | hexsha1 | sha1exp_str | idnum);\n   ref_str     ::= ref;\n   sha1exp_str ::= sha1exp;\n   tag_str     ::= tag;\n@@ -2288,7 +2288,7 @@ static void note_change_n(struct branch *b, unsigned char old_fanout)\n \tif (*p++ != ' ')\n \t\tdie(\"Missing space after SHA1: %s\", command_buf.buf);\n \n-\t/* <committish> */\n+\t/* <commit> */\n \ts = lookup_branch(p);\n \tif (s) {\n \t\thashcpy(commit_sha1, s->sha1);\ndiff --git a/remote.c b/remote.c\nindex c70181c..3c5f8c6 100644\n--- a/remote.c\n+++ b/remote.c\n@@ -1277,7 +1277,7 @@ void set_ref_status_for_push(struct ref *remote_refs, int send_mirror,\n \t\t *     to overwrite it; you would not know what you are losing\n \t\t *     otherwise.\n \t\t *\n-\t\t * (3) if both new and old are commit-ish, and new is a\n+\t\t * (3) if both new and old are <commit>'s, and new is a\n \t\t *     descendant of old, it is OK.\n \t\t *\n \t\t * (4) regardless of all of the above, removing :B is\n@@ -1475,7 +1475,7 @@ int ref_newer(const unsigned char *new_sha1, const unsigned char *old_sha1)\n \tstruct commit_list *list, *used;\n \tint found = 0;\n \n-\t/* Both new and old must be commit-ish and new is descendant of\n+\t/* Both new and old must be <commit>'s and new is descendant of\n \t * old.  Otherwise we require --force.\n \t */\n \to = deref_tag(parse_object(old_sha1), NULL, 0);\n-- \n1.7.0.2\n"},{"id":"136705","messageId":"1268455984-19061-11-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 10/12] diff: use brackets for optional args in usage","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:53:02Z","receivedAt":"2010-03-13T04:53:02Z","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 builtin/diff.c |    2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex ffcdd05..a716704 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -21,7 +21,7 @@ struct blobinfo {\n };\n \n static const char builtin_diff_usage[] =\n-\"git diff <options> <rev>{0,2} -- <path>*\";\n+\"git diff [<options>] <rev>{0,2} [--] [<path>]*\";\n \n static void stuff_change(struct diff_options *opt,\n \t\t\t unsigned old_mode, unsigned new_mode,\n-- \n1.7.0.2\n"},{"id":"136706","messageId":"1268455984-19061-12-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 11/12] docs: use ... instead of * for multiplicity","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:53:03Z","receivedAt":"2010-03-13T04:53:03Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"In the documentation and in usage messages, use [<foo>...] to denote\narguments that can occur zero or more times, rather than [<foo>]* or the\nlike.  The '...' should come inside the brackets if there is a single\nword (e.g., \"[<file>...]\"), but outside the brackets if there is more\nthan one word (e.g. \"[-p <commit>]...\").\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\nI don't like having to put the ellipses inside and outside the brackets, \nbut I couldn't come up with anything that was more clear.  Leaving the \nstar just for these cases is a worse alternative in my opinion, since \nthen it would be even more of an oddball.\n\nBy the way, can anyone explain why git-pack-objects(1) has\n\t[--revs [--unpacked | --all]*]\nand not the following?\n\t[--revs] [--unpacked] [--all]\n\n Documentation/git-checkout-index.txt |    2 +-\n Documentation/git-commit-tree.txt    |    2 +-\n Documentation/git-for-each-ref.txt   |    2 +-\n Documentation/git-fsck.txt           |    2 +-\n Documentation/git-ls-files.txt       |    2 +-\n Documentation/git-merge-index.txt    |    2 +-\n Documentation/git-mergetool.txt      |    2 +-\n Documentation/git-pack-objects.txt   |    2 +-\n Documentation/git-relink.txt         |    2 +-\n Documentation/git-update-index.txt   |    4 ++--\n Documentation/gitcli.txt             |    2 +-\n builtin/commit-tree.c                |    2 +-\n builtin/describe.c                   |    2 +-\n builtin/diff.c                       |    2 +-\n builtin/ls-files.c                   |    2 +-\n builtin/merge-index.c                |    2 +-\n builtin/pack-objects.c               |    2 +-\n 17 files changed, 18 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt\nindex d6aa6e1..0c0a9c1 100644\n--- a/Documentation/git-checkout-index.txt\n+++ b/Documentation/git-checkout-index.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n \t\t   [--stage=<number>|all]\n \t\t   [--temp]\n \t\t   [-z] [--stdin]\n-\t\t   [--] [<file>]\\*\n+\t\t   [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 6188854..55f0390 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object\n \n SYNOPSIS\n --------\n-'git commit-tree' <tree> [-p <parent commit>]\\* < changelog\n+'git commit-tree' <tree> [-p <parent commit>]... < changelog\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex 7e83288..993f79f 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]\n-\t\t   [--sort=<key>]\\* [--format=<format>] [<pattern>...]\n+\t\t   [--sort=<key>]... [--format=<format>] [<pattern>...]\n \n DESCRIPTION\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-ls-files.txt b/Documentation/git-ls-files.txt\nindex ed63f21..cbd6661 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -17,7 +17,7 @@ SYNOPSIS\n \t\t[--exclude-per-directory=<file>]\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=<tree>]\n-\t\t[--full-name] [--abbrev] [--] [<file>]\\*\n+\t\t[--full-name] [--abbrev] [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 4d266de..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/git-mergetool.txt b/Documentation/git-mergetool.txt\nindex 55735fa..bd6b301 100644\n--- a/Documentation/git-mergetool.txt\n+++ b/Documentation/git-mergetool.txt\n@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts\n \n SYNOPSIS\n --------\n-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...\n+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex 8ed09c0..a19aa4b 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n \t[--local] [--incremental] [--window=N] [--depth=N]\n-\t[--revs [--unpacked | --all]*] [--stdout | base-name]\n+\t[--revs [--unpacked | --all]...] [--stdout | base-name]\n \t[--keep-true-parents] < object-list\n \n \ndiff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt\nindex 25ff8f9..362a5dc 100644\n--- a/Documentation/git-relink.txt\n+++ b/Documentation/git-relink.txt\n@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories\n \n SYNOPSIS\n --------\n-'git relink' [--safe] <dir> [<dir>]\\* <master_dir>\n+'git relink' [--safe] <dir> [<dir>...] <master_dir>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex 68dc187..2753d73 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git update-index'\n \t     [--add] [--remove | --force-remove] [--replace]\n \t     [--refresh] [-q] [--unmerged] [--ignore-missing]\n-\t     [--cacheinfo <mode> <object> <file>]\\*\n+\t     [--cacheinfo <mode> <object> <file>]...\n \t     [--chmod=(+|-)x]\n \t     [--assume-unchanged | --no-assume-unchanged]\n \t     [--skip-worktree | --no-skip-worktree]\n@@ -21,7 +21,7 @@ SYNOPSIS\n \t     [--info-only] [--index-info]\n \t     [-z] [--stdin]\n \t     [--verbose]\n-\t     [--] [<file>]\\*\n+\t     [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex de0630f..eb51ffc 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/commit-tree.c b/builtin/commit-tree.c\nindex 225e515..22ceff1 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)\n \t\t    typename(expect));\n }\n \n-static const char commit_tree_usage[] = \"git commit-tree <tree> [-p <commit>]* < 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 {\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex 4ece73f..2bba2ba 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -11,7 +11,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 };\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex a716704..f73da93 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -21,7 +21,7 @@ struct blobinfo {\n };\n \n static const char builtin_diff_usage[] =\n-\"git diff [<options>] <rev>{0,2} [--] [<path>]*\";\n+\"git diff [<options>] <rev>{0,2} [--] [<path>...]\";\n \n static void stuff_change(struct diff_options *opt,\n \t\t\t unsigned old_mode, unsigned new_mode,\ndiff --git a/builtin/ls-files.c b/builtin/ls-files.c\nindex 6dc885d..c57c93e 100644\n--- a/builtin/ls-files.c\n+++ b/builtin/ls-files.c\n@@ -414,7 +414,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_\n }\n \n static const char * const ls_files_usage[] = {\n-\t\"git ls-files [options] [<file>]*\",\n+\t\"git ls-files [options] [<file>...]\",\n \tNULL\n };\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 \ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 9780258..19d9f09 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -28,7 +28,7 @@ static const char pack_usage[] =\n   \"        [--max-pack-size=N] [--local] [--incremental]\\n\"\n   \"        [--window=N] [--window-memory=N] [--depth=N]\\n\"\n   \"        [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\\n\"\n-  \"        [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\\n\"\n+  \"        [--threads=N] [--non-empty] [--revs [--unpacked | --all]...]\\n\"\n   \"        [--reflog] [--stdout | base-name] [--include-tag]\\n\"\n   \"        [--keep-unreachable | --unpack-unreachable \\n\"\n   \"        [<ref-list | <object-list]\";\n-- \n1.7.0.2\n"},{"id":"136708","messageId":"1268455984-19061-13-git-send-email-lodatom@gmail.com","threadId":"23006","inReplyTo":"1268455984-19061-1-git-send-email-lodatom@gmail.com","subject":"[PATCH/RFC 12/12] diff docs: remove <rev>{0,2} notation","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-13T04:53:04Z","receivedAt":"2010-03-13T04:53:04Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"This notation is not used anywhere else, so it can be confusing when\nfirst encountered.  Instead, prefer the slightly longer but just as\nclear \"[<rev> [<rev>]]\", which is consistent with other commands.\n\nSigned-off-by: Mark Lodato <lodatom@gmail.com>\n---\nWhen I first ran `git diff -h` and I saw the old syntax, I was rather\nconfused.  It took me a minute to realize that this was the regular\nexpression syntax.  I think it's best to stick with one syntax, even if\nit is a bit more verbose.\n\n Documentation/git-diff.txt     |    2 +-\n Documentation/git-difftool.txt |    2 +-\n builtin/diff.c                 |    2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 4582179..e2d868d 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...]\n+'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt\nindex 8250bad..a02e3b5 100644\n--- a/Documentation/git-difftool.txt\n+++ b/Documentation/git-difftool.txt\n@@ -7,7 +7,7 @@ git-difftool - Show changes using common diff tools\n \n SYNOPSIS\n --------\n-'git difftool' [<options>] <commit>{0,2} [--] [<path>...]\n+'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex f73da93..e2e2efc 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -21,7 +21,7 @@ struct blobinfo {\n };\n \n static const char builtin_diff_usage[] =\n-\"git diff [<options>] <rev>{0,2} [--] [<path>...]\";\n+\"git diff [<options>] [<rev> [<rev>]] [--] [<path>...]\";\n \n static void stuff_change(struct diff_options *opt,\n \t\t\t unsigned old_mode, unsigned new_mode,\n-- \n1.7.0.2\n"},{"id":"136732","messageId":"7vbper7ut9.fsf@alter.siamese.dyndns.org","threadId":"23006","inReplyTo":"1268455984-19061-6-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname>","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-13T21:53:06Z","receivedAt":"2010-03-13T21:53:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Lodato <lodatom@gmail.com> writes:\n\n> In the documentation and user messages, differentiate between <tag>,\n> which means an actual annotated tag object, and <tagname>, which is\n> a revision specifier for refs/tags/<tagname>.\n\nDo we talk about annotated tag objects that often?\n\nI would instead recommend you to consistently use \"tag object\", \"tag name\"\n(the string that appears on \"tag \" line in a \"tag object\"), and \"tag\" (the\nrefs that live under refs/tags/ namespace.\n"},{"id":"136733","messageId":"7v634z7uke.fsf@alter.siamese.dyndns.org","threadId":"23006","inReplyTo":"1268455984-19061-2-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH/RFC 01/12] commit-tree: allow indirect tree references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-13T21:58:25Z","receivedAt":"2010-03-13T21:58:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Lodato <lodatom@gmail.com> writes:\n\n> 'git commit-tree' was the last remaining built-in to accept a <tree> but\n> not a <tree-ish> (an indirect tree reference through a commit or tag\n> object.)\n\nHistorically we deliberately chose not to DWIM things down to tree for\nthis plumbing command to catch mistakes by Porcelain scripts\n(e.g. arguments given in wrong order---the order of commit-tree's\narguments are, eh, unintuitive).\n\nI do not think that matters much anymore---I do not think this patch\nis unsafe.\n"},{"id":"136734","messageId":"7v1vfn7uje.fsf@alter.siamese.dyndns.org","threadId":"23006","inReplyTo":"1268455984-19061-3-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-13T21:59:01Z","receivedAt":"2010-03-13T21:59:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Lodato <lodatom@gmail.com> writes:\n\n>  Documentation/git-grep.txt |    4 ++--\n>  builtin/commit-tree.c      |    2 +-\n\nYuck; plonk, try again.\n"},{"id":"136736","messageId":"7vwrxf6fnc.fsf@alter.siamese.dyndns.org","threadId":"23006","inReplyTo":"1268455984-19061-10-git-send-email-lodatom@gmail.com","subject":"Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-13T22:05:59Z","receivedAt":"2010-03-13T22:05:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Lodato <lodatom@gmail.com> writes:\n\n> There exist no commands that accept a <commit> but not a <commit-ish>,\n\nI have one worry about this and [07/12].  The droppage of -ish would make\nsense from the point of view of describing command line arguments,\ni.e. what you can give to the commands, but it would make it impossible\nfor us to talk about places that _only_ tree not arbitrary tree-ish can\nappear.  For example, don't we ever talk about something like this?\n\n    A tree object is a sequence of records, each of which describes the\n    type of entry, object name, and the name of the entry in the tree.\n    When the type is \"tree\", the object name must name a tree, when the\n    type is \"gitlink\", the object name must name a commit, ...\n\nOther than that small worry, I think the series goes in the right\ndirection.\n"},{"id":"136906","messageId":"ca433831003151744j80c5421n9cd1f310687dace3@mail.gmail.com","threadId":"23006","inReplyTo":"7v634z7uke.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC 01/12] commit-tree: allow indirect tree references","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-16T00:44:12Z","receivedAt":"2010-03-16T00:44:12Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Sat, Mar 13, 2010 at 5:58 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Mark Lodato <lodatom@gmail.com> writes:\n>\n>> 'git commit-tree' was the last remaining built-in to accept a <tree> but\n>> not a <tree-ish> (an indirect tree reference through a commit or tag\n>> object.)\n>\n> Historically we deliberately chose not to DWIM things down to tree for\n> this plumbing command to catch mistakes by Porcelain scripts\n> (e.g. arguments given in wrong order---the order of commit-tree's\n> arguments are, eh, unintuitive).\n>\n> I do not think that matters much anymore---I do not think this patch\n> is unsafe.\n\nI thought about that, but upon investigation, the _only_ command that\ndoesn't DWIM with respect to object types (<tree> or <commit>) is\ncommit-tree.  So, I thought it might make sense to treat this like all\nthe other commands.  On the other hand, it may be a good idea to keep\nthis special for safety.  If so, then I would just amend the\ndocumentation to note that it does not automatically dereference\ncommit or tag objects.\n"},{"id":"136908","messageId":"ca433831003151747r3e9d7a8bp7bc2ed43b8c694a9@mail.gmail.com","threadId":"23006","inReplyTo":"7v1vfn7uje.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-16T00:47:06Z","receivedAt":"2010-03-16T00:47:06Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Sat, Mar 13, 2010 at 5:59 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Mark Lodato <lodatom@gmail.com> writes:\n>\n>>  Documentation/git-grep.txt |    4 ++--\n>>  builtin/commit-tree.c      |    2 +-\n>\n> Yuck; plonk, try again.\n\nOops, sorry about that.  I'll fix it in v2, since the commit-tree.c\npart should go in the previous patch.\n"},{"id":"136910","messageId":"ca433831003151812l7cc2c1b4hc11c9748ec8ed570@mail.gmail.com","threadId":"23006","inReplyTo":"7vwrxf6fnc.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-16T01:12:08Z","receivedAt":"2010-03-16T01:12:08Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Sat, Mar 13, 2010 at 6:05 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Mark Lodato <lodatom@gmail.com> writes:\n>\n>> There exist no commands that accept a <commit> but not a <commit-ish>,\n>\n> I have one worry about this and [07/12].  The droppage of -ish would make\n> sense from the point of view of describing command line arguments,\n> i.e. what you can give to the commands, but it would make it impossible\n> for us to talk about places that _only_ tree not arbitrary tree-ish can\n> appear.  For example, don't we ever talk about something like this?\n>\n>    A tree object is a sequence of records, each of which describes the\n>    type of entry, object name, and the name of the entry in the tree.\n>    When the type is \"tree\", the object name must name a tree, when the\n>    type is \"gitlink\", the object name must name a commit, ...\n>\n> Other than that small worry, I think the series goes in the right\n> direction.\n\nYes, it would probably be best to leave the -ish terms in the glossary\n(which I evidently did by mistake) and in the comments and\ndocumentation, but just not use them as an identifier in angle\nbrackets.  For example, a command accepting a <tree> would also accept\ncommits or tags unless otherwise noted, but the term \"tree object\"\nwould still only refer to an actual tree object, not a tree-ish.  When\nit is unclear, one can use the -ish term, like I just did in that last\nsentence.\n\nI'll wait a few days to see if there are any more comments, and then\nI'll try fixing up this series.\n"}]}