* [PATCH/RFC 01/12] commit-tree: allow indirect tree references
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 21:58 ` Junio C Hamano
2010-03-13 4:52 ` [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree> Mark Lodato
` (10 subsequent siblings)
11 siblings, 1 reply; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
'git commit-tree' was the last remaining built-in to accept a <tree> but
not a <tree-ish> (an indirect tree reference through a commit or tag
object.)
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
A similar thing should be done for the parent commits. As far as I can
tell, this is the only command that requires a commit object, not a tag.
Documentation/git-commit-tree.txt | 4 +-
builtin/commit-tree.c | 13 ++++++----
t/t1101-commit-tree-indirect.sh | 49 +++++++++++++++++++++++++++++++++++++
3 files changed, 59 insertions(+), 7 deletions(-)
create mode 100755 t/t1101-commit-tree-indirect.sh
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 6188854..67b6bc0 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
SYNOPSIS
--------
-'git commit-tree' <tree> [-p <parent commit>]\* < changelog
+'git commit-tree' <tree-ish> [-p <parent commit>]\* < changelog
DESCRIPTION
-----------
@@ -35,7 +35,7 @@ state was.
OPTIONS
-------
-<tree>::
+<tree-ish>::
An existing tree object
-p <parent commit>::
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 90dac34..96a421e 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -97,16 +97,19 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)
{
int i;
struct commit_list *parents = NULL;
- unsigned char tree_sha1[20];
- unsigned char commit_sha1[20];
+ unsigned char sha1[20];
struct strbuf buffer = STRBUF_INIT;
+ struct tree *tree;
git_config(git_default_config, NULL);
if (argc < 2 || !strcmp(argv[1], "-h"))
usage(commit_tree_usage);
- if (get_sha1(argv[1], tree_sha1))
+ if (get_sha1(argv[1], sha1))
die("Not a valid object name %s", argv[1]);
+ tree = parse_tree_indirect(sha1);
+ if (!tree)
+ die("%s is not a valid 'tree' object", argv[1]);
for (i = 2; i < argc; i += 2) {
unsigned char sha1[20];
@@ -124,8 +127,8 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)
if (strbuf_read(&buffer, 0, 0) < 0)
die_errno("git commit-tree: failed to read");
- if (!commit_tree(buffer.buf, tree_sha1, parents, commit_sha1, NULL)) {
- printf("%s\n", sha1_to_hex(commit_sha1));
+ if (!commit_tree(buffer.buf, tree->object.sha1, parents, sha1, NULL)) {
+ printf("%s\n", sha1_to_hex(sha1));
return 0;
}
else
diff --git a/t/t1101-commit-tree-indirect.sh b/t/t1101-commit-tree-indirect.sh
new file mode 100755
index 0000000..905bad7
--- /dev/null
+++ b/t/t1101-commit-tree-indirect.sh
@@ -0,0 +1,49 @@
+#!/bin/sh
+#
+# Copyright (c) 2010 Mark Lodato
+#
+
+test_description='git commit-tree works with indirect references'
+
+. ./test-lib.sh
+
+get_tree() {
+ git cat-file commit $1 | sed -n -e 's/^tree //p'
+}
+
+test_expect_success 'prepare the repository' '
+ touch a &&
+ git add a &&
+ git commit -m x &&
+ git tag -a -m x tag-commit &&
+ git tag -a -m x tag-tree HEAD^{tree} &&
+ git tag -a -m x tag-blob HEAD:a &&
+ git tag -a -m x tag-tag-commit tag-commit
+'
+
+expected_tree="$(get_tree HEAD)"
+
+test_success() {
+ test_expect_success "commit-tree succeeds with $2" '
+ id="$(echo x | git commit-tree '"$1"')" &&
+ tree="$(get_tree $id)" &&
+ test "x$tree" = "x$expected_tree"
+ '
+}
+test_failure() {
+ test_expect_code 128 "commit-tree fails with $2" '
+ echo x | git commit-tree '"$1"' 2>/dev/null
+ '
+}
+
+test_failure HEAD:a "a blob"
+test_success HEAD^{tree} "a tree"
+test_success HEAD "HEAD"
+test_success master "a branch"
+test_failure foo "an invalid object name"
+test_failure tag-blob "a tag pointing to a blob"
+test_success tag-tree "a tag pointing to a tree"
+test_success tag-commit "a tag pointing to a commit"
+test_success tag-tag-commit "a tag pointing to a tag (to a commit)"
+
+test_done
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH/RFC 01/12] commit-tree: allow indirect tree references
2010-03-13 4:52 ` [PATCH/RFC 01/12] commit-tree: allow indirect tree references Mark Lodato
@ 2010-03-13 21:58 ` Junio C Hamano
2010-03-16 0:44 ` Mark Lodato
0 siblings, 1 reply; 20+ messages in thread
From: Junio C Hamano @ 2010-03-13 21:58 UTC (permalink / raw
To: Mark Lodato; +Cc: git
Mark Lodato <lodatom@gmail.com> writes:
> 'git commit-tree' was the last remaining built-in to accept a <tree> but
> not a <tree-ish> (an indirect tree reference through a commit or tag
> object.)
Historically we deliberately chose not to DWIM things down to tree for
this plumbing command to catch mistakes by Porcelain scripts
(e.g. arguments given in wrong order---the order of commit-tree's
arguments are, eh, unintuitive).
I do not think that matters much anymore---I do not think this patch
is unsafe.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH/RFC 01/12] commit-tree: allow indirect tree references
2010-03-13 21:58 ` Junio C Hamano
@ 2010-03-16 0:44 ` Mark Lodato
0 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-16 0:44 UTC (permalink / raw
To: Junio C Hamano; +Cc: git
On Sat, Mar 13, 2010 at 5:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> 'git commit-tree' was the last remaining built-in to accept a <tree> but
>> not a <tree-ish> (an indirect tree reference through a commit or tag
>> object.)
>
> Historically we deliberately chose not to DWIM things down to tree for
> this plumbing command to catch mistakes by Porcelain scripts
> (e.g. arguments given in wrong order---the order of commit-tree's
> arguments are, eh, unintuitive).
>
> I do not think that matters much anymore---I do not think this patch
> is unsafe.
I thought about that, but upon investigation, the _only_ command that
doesn't DWIM with respect to object types (<tree> or <commit>) is
commit-tree. So, I thought it might make sense to treat this like all
the other commands. On the other hand, it may be a good idea to keep
this special for safety. If so, then I would just amend the
documentation to note that it does not automatically dereference
commit or tag objects.
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
2010-03-13 4:52 ` [PATCH/RFC 01/12] commit-tree: allow indirect tree references Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 21:59 ` Junio C Hamano
2010-03-13 4:52 ` [PATCH/RFC 03/12] fsck docs: remove outdated and useless diagnostic Mark Lodato
` (9 subsequent siblings)
11 siblings, 1 reply; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
Also document that -p accepts a <commit> in the usage message.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
Documentation/git-grep.txt | 4 ++--
builtin/commit-tree.c | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 4b32322..02d6306 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -21,7 +21,7 @@ SYNOPSIS
[-A <post-context>] [-B <pre-context>] [-C <context>]
[-f <file>] [-e] <pattern>
[--and|--or|--not|(|)|-e <pattern>...]
- [--cached | --no-index | <tree>...]
+ [--cached | --no-index | <tree-ish>...]
[--] [<pathspec>...]
DESCRIPTION
@@ -168,7 +168,7 @@ OPTIONS
Do not output matched lines; instead, exit with status 0 when
there is a match and with non-zero status when there isn't.
-<tree>...::
+<tree-ish>...::
Instead of searching tracked files in the working tree, search
blobs in the given trees.
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 96a421e..770baa2 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)
typename(expect));
}
-static const char commit_tree_usage[] = "git commit-tree <sha1> [-p <sha1>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <tree-ish> [-p <commit>]* < changelog";
static void new_parent(struct commit *parent, struct commit_list **parents_p)
{
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>
2010-03-13 4:52 ` [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree> Mark Lodato
@ 2010-03-13 21:59 ` Junio C Hamano
2010-03-16 0:47 ` Mark Lodato
0 siblings, 1 reply; 20+ messages in thread
From: Junio C Hamano @ 2010-03-13 21:59 UTC (permalink / raw
To: Mark Lodato; +Cc: git
Mark Lodato <lodatom@gmail.com> writes:
> Documentation/git-grep.txt | 4 ++--
> builtin/commit-tree.c | 2 +-
Yuck; plonk, try again.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree>
2010-03-13 21:59 ` Junio C Hamano
@ 2010-03-16 0:47 ` Mark Lodato
0 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-16 0:47 UTC (permalink / raw
To: Junio C Hamano; +Cc: git
On Sat, Mar 13, 2010 at 5:59 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> Documentation/git-grep.txt | 4 ++--
>> builtin/commit-tree.c | 2 +-
>
> Yuck; plonk, try again.
Oops, sorry about that. I'll fix it in v2, since the commit-tree.c
part should go in the previous patch.
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH/RFC 03/12] fsck docs: remove outdated and useless diagnostic
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
2010-03-13 4:52 ` [PATCH/RFC 01/12] commit-tree: allow indirect tree references Mark Lodato
2010-03-13 4:52 ` [PATCH/RFC 02/12] grep docs: grep accepts a <tree-ish>, not a <tree> Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 4:52 ` [PATCH/RFC 04/12] docs: use <sha1> to mean unabbreviated ID Mark Lodato
` (8 subsequent siblings)
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
In git-fsck(1), there was a reference to the warning "<tree> has full
pathnames in it". This exact wording has not been used since 2005
(commit f1f0d0889e55), when the wording was changed slightly. More
importantly, the description of that warning was useless, and there were
many other similar warning messages which were not document at all.
Since all these warnings are fairly obvious, there is no need for them
to be in the man page.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
Documentation/git-fsck.txt | 3 ---
1 files changed, 0 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 3ad48a6..86f9b2b 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -123,9 +123,6 @@ dangling <type> <object>::
The <type> object <object>, is present in the database but never
'directly' used. A dangling commit could be a root node.
-warning: git-fsck: tree <tree> has full pathnames in it::
- And it shouldn't...
-
sha1 mismatch <object>::
The database has an object who's sha1 doesn't match the
database value.
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 04/12] docs: use <sha1> to mean unabbreviated ID
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (2 preceding siblings ...)
2010-03-13 4:52 ` [PATCH/RFC 03/12] fsck docs: remove outdated and useless diagnostic Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 4:52 ` [PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname> Mark Lodato
` (7 subsequent siblings)
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
There are some places that literally require a full, 40-character SHA-1
ID, rather than a generic revision specifier. Introduce in git(1) the
<sha1> terminology to mean this. Use <sha1> in git-diff-tree(1) to note
that --stdin only takes <sha1>'s, not generic <tree>'s or <commit>'s.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
Documentation/git-diff-tree.txt | 4 ++--
Documentation/git.txt | 5 +++++
2 files changed, 7 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index a7e37b8..5d0310b 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -49,8 +49,8 @@ include::diff-options.txt[]
--stdin::
When '--stdin' is specified, the command does not take
<tree-ish> arguments from the command line. Instead, it
- reads lines containing either two <tree>, one <commit>, or a
- list of <commit> from its standard input. (Use a single space
+ reads lines containing <sha1>'s: either two trees, one commit, or
+ multiple commits from its standard input. (Use a single space
as separator.)
+
When two trees are given, it compares the first tree with the second.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 35c0c79..a635281 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -412,6 +412,11 @@ list.
Identifier Terminology
----------------------
+<sha1>::
+ Indicates a full, 40-character SHA-1 identifier of an object.
+ The type of the referenced object is unspecified.
+ Abbreviated or symbolic identifiers cannot be used.
+
<object>::
Indicates the object name for any type of object.
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname>
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (3 preceding siblings ...)
2010-03-13 4:52 ` [PATCH/RFC 04/12] docs: use <sha1> to mean unabbreviated ID Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 21:53 ` Junio C Hamano
2010-03-13 4:52 ` [PATCH/RFC 06/12] docs: clarify <object>, <commit>, <tree-ish>, etc Mark Lodato
` (6 subsequent siblings)
11 siblings, 1 reply; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
In the documentation and user messages, differentiate between <tag>,
which means an actual annotated tag object, and <tagname>, which is
a revision specifier for refs/tags/<tagname>.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
A similar thing should be done for <head> vs <branch> vs <branchname>.
The term <head> is not used anywhere to mean what it does in git(1);
instead, it is used as a more descriptive term for <commit-ish>. The
term <branchname> is used for what git(1) describes as <head>, but the
term <branch> is also used, and I'm not sure what it means. I'll have
to look into this.
Documentation/git-push.txt | 2 +-
Documentation/git.txt | 8 ++++++--
Documentation/pull-fetch-param.txt | 2 +-
builtin/push.c | 2 +-
4 files changed, 9 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 49b6bd9..5445443 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -55,7 +55,7 @@ you can tell git to update the <dst> ref even when the update is not a
fast-forward. This does *not* attempt to merge <src> into <dst>. See
EXAMPLES below for details.
+
-`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+`tag <tagname>` means the same as `refs/tags/<tagname>:refs/tags/<tagname>`.
+
Pushing an empty <src> allows you to delete the <dst> ref from
the remote repository.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index a635281..f06e4de 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -420,6 +420,10 @@ Identifier Terminology
<object>::
Indicates the object name for any type of object.
+<tag>::
+ Indicates a tag object name. This is an annotated tag object, as
+ opposed to <tagname>, which can refer to any type of object.
+
<blob>::
Indicates a blob object name.
@@ -458,9 +462,9 @@ HEAD::
indicates the head of the current branch (i.e. the
contents of `$GIT_DIR/HEAD`).
-<tag>::
+<tagname>::
a valid tag 'name'
- (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
+ (i.e. the contents of `$GIT_DIR/refs/tags/<tagname>`).
<head>::
a valid head 'name'
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 5dd6e5a..3a947b3 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -66,7 +66,7 @@ is often useful.
+
Some short-cut notations are also supported.
+
-* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;
+* `tag <tagname>` means the same as `refs/tags/<tagname>:refs/tags/<tagname>`;
it requests fetching everything up to the given tag.
* A parameter <ref> without a colon is equivalent to
<ref>: when pulling/fetching, so it merges <ref> into the current
diff --git a/builtin/push.c b/builtin/push.c
index f7bc2b2..4227a8e 100644
--- a/builtin/push.c
+++ b/builtin/push.c
@@ -38,7 +38,7 @@ static void set_refspecs(const char **refs, int nr)
char *tag;
int len;
if (nr <= ++i)
- die("tag shorthand without <tag>");
+ die("tag shorthand without <tagname>");
len = strlen(refs[i]) + 11;
if (deleterefs) {
tag = xmalloc(len+1);
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 06/12] docs: clarify <object>, <commit>, <tree-ish>, etc
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (4 preceding siblings ...)
2010-03-13 4:52 ` [PATCH/RFC 05/12] docs: differentiate between <tag> and <tagname> Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 4:52 ` [PATCH/RFC 07/12] docs: use <tree> instead of <tree-ish> Mark Lodato
` (5 subsequent siblings)
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
In git(1), give more precise definitions of <object>, <commit>,
<tree-ish>, and so on. In particular, differentiate <object> (which may
take generic revision specifiers) from <sha1>, which only accepts
a 40-character hex SHA-1 ID.
Also note that <rev> is another way to say <commit-ish>.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
Documentation/git.txt | 38 +++++++++++++++++++++-----------------
1 files changed, 21 insertions(+), 17 deletions(-)
diff --git a/Documentation/git.txt b/Documentation/git.txt
index f06e4de..55f3842 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -418,32 +418,36 @@ Identifier Terminology
Abbreviated or symbolic identifiers cannot be used.
<object>::
- Indicates the object name for any type of object.
+ Indicates the object name for any type of object. Symbolic name or
+ abbreviated SHA-1 identifiers may be used (see "SPECIFYING REVISIONS"
+ in linkgit:git-rev-parse[1] for details).
<tag>::
- Indicates a tag object name. This is an annotated tag object, as
+ Indicates a tag-type <object>. This is an annotated tag object, as
opposed to <tagname>, which can refer to any type of object.
-<blob>::
- Indicates a blob object name.
+<commit>::
+ Indicates a commit-type <object>.
<tree>::
- Indicates a tree object name.
-
-<commit>::
- Indicates a commit object name.
+ Indicates a tree-type <object>.
-<tree-ish>::
- Indicates a tree, commit or tag object name. A
- command that takes a <tree-ish> argument ultimately wants to
- operate on a <tree> object but automatically dereferences
- <commit> and <tag> objects that point at a <tree>.
+<blob>::
+ Indicates a blob-type <object>.
+<rev>::
<commit-ish>::
- Indicates a commit or tag object name. A
- command that takes a <commit-ish> argument ultimately wants to
- operate on a <commit> object but automatically dereferences
- <tag> objects that point at a <commit>.
+ Indicates a <commit>, or a <tag> that points at a <commit-ish>.
+ A command that takes a <commit-ish> argument ultimately wants to
+ operate on a commit object but automatically dereferences objects
+ until it finds a commit.
+ A <rev> is another name for a <commit-ish>.
+
+<tree-ish>::
+ Indicates a <tree>, or a <tag> or <commit> that points at a
+ <tree-ish>. A command that takes a <tree-ish> argument ultimately
+ wants to operate on a tree object but automatically dereferences
+ objects until it finds a tree.
<type>::
Indicates that an object type is required.
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 07/12] docs: use <tree> instead of <tree-ish>
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (5 preceding siblings ...)
2010-03-13 4:52 ` [PATCH/RFC 06/12] docs: clarify <object>, <commit>, <tree-ish>, etc Mark Lodato
@ 2010-03-13 4:52 ` Mark Lodato
2010-03-13 4:53 ` [PATCH/RFC 08/12] http-fetch docs: use <commit-id> consistently Mark Lodato
` (4 subsequent siblings)
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:52 UTC (permalink / raw
To: git; +Cc: Mark Lodato
There is no longer any reference to <tree> in the documentation, since
all commands now accept a <tree-ish>, so remove the latter in favor
of the former.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
I expect that this, along with the removal of <commit-ish>, is the most
controversial part of the patch series. I just don't see any reason to
use the ugly and long <tree-ish> when <tree> is going unused!
Documentation/RelNotes-1.6.2.4.txt | 2 +-
Documentation/diff-format.txt | 8 ++++----
Documentation/diff-generate-patch.txt | 2 +-
Documentation/git-archive.txt | 4 ++--
Documentation/git-checkout.txt | 14 +++++++-------
Documentation/git-commit-tree.txt | 4 ++--
Documentation/git-diff-index.txt | 4 ++--
Documentation/git-diff-tree.txt | 14 +++++++-------
Documentation/git-diff.txt | 2 +-
Documentation/git-grep.txt | 4 ++--
Documentation/git-ls-files.txt | 6 +++---
Documentation/git-ls-tree.txt | 4 ++--
Documentation/git-read-tree.txt | 4 ++--
Documentation/git-tar-tree.txt | 4 ++--
Documentation/git.txt | 11 ++++-------
archive.c | 4 ++--
builtin/commit-tree.c | 2 +-
builtin/diff-index.c | 2 +-
builtin/diff-tree.c | 2 +-
builtin/ls-files.c | 2 +-
builtin/ls-tree.c | 2 +-
builtin/tar-tree.c | 2 +-
git-svn.perl | 2 +-
t/t4100/t-apply-3.patch | 8 ++++----
t/t4100/t-apply-7.patch | 8 ++++----
25 files changed, 59 insertions(+), 62 deletions(-)
diff --git a/Documentation/RelNotes-1.6.2.4.txt b/Documentation/RelNotes-1.6.2.4.txt
index f4bf1d0..0e36786 100644
--- a/Documentation/RelNotes-1.6.2.4.txt
+++ b/Documentation/RelNotes-1.6.2.4.txt
@@ -13,7 +13,7 @@ Fixes since v1.6.2.3
* "git-add -p" lacked a way to say "q"uit to refuse staging any hunks for
the remaining paths. You had to say "d" and then ^C.
-* "git-checkout <tree-ish> <submodule>" did not update the index entry at
+* "git-checkout <tree> <submodule>" did not update the index entry at
the named path; it now does.
* "git-fast-export" choked when seeing a tag that does not point at commit.
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 15c7e79..e1311fb 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -7,11 +7,11 @@ The raw output format from "git-diff-index", "git-diff-tree",
These commands all compare two sets of things; what is
compared differs:
-git-diff-index <tree-ish>::
- compares the <tree-ish> and the files on the filesystem.
+git-diff-index <tree>::
+ compares the <tree> and the files on the filesystem.
-git-diff-index --cached <tree-ish>::
- compares the <tree-ish> and the index.
+git-diff-index --cached <tree>::
+ compares the <tree> and the index.
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
compares the trees named by the two arguments.
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 0f25ba7..e0eb126 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -110,7 +110,7 @@ The `mode <mode>,<mode>..<mode>` line appears only if at least one of
the <mode> is different from the rest. Extended headers with
information about detected contents movement (renames and
copying detection) are designed to work with diff of two
-<tree-ish> and are not used by combined diff format.
+<tree> and are not used by combined diff format.
3. It is followed by two-line from-file/to-file header
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 8d3e666..1d520fc 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
[-o | --output=<file>] [--worktree-attributes]
- [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
+ [--remote=<repo> [--exec=<git-upload-archive>]] <tree>
[path...]
DESCRIPTION
@@ -70,7 +70,7 @@ OPTIONS
Used with --remote to specify the path to the
'git-upload-archive' on the remote side.
-<tree-ish>::
+<tree>::
The tree or commit to produce an archive for.
path::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 37c1810..b1061d5 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -10,8 +10,8 @@ SYNOPSIS
[verse]
'git checkout' [-q] [-f] [-m] [<branch>]
'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
-'git checkout' --patch [<tree-ish>] [--] [<paths>...]
+'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree>] [--] <paths>...
+'git checkout' --patch [<tree>] [--] [<paths>...]
DESCRIPTION
-----------
@@ -28,9 +28,9 @@ creation; see the description of --track below.
When <paths> or --patch are given, this command does *not* switch
branches. It updates the named paths in the working tree from
-the index file, or from a named <tree-ish> (most often a commit). In
+the index file, or from a named <tree> (most often a commit). In
this case, the `-b` and `--track` options are meaningless and giving
-either of them results in an error. The <tree-ish> argument can be
+either of them results in an error. The <tree> argument can be
used to specify a specific tree-ish (i.e. commit, tag or tree)
to update the index for the given paths before updating the
working tree.
@@ -119,9 +119,9 @@ the conflicted merge in the specified paths.
-p::
--patch::
Interactively select hunks in the difference between the
- <tree-ish> (or the index, if unspecified) and the working
+ <tree> (or the index, if unspecified) and the working
tree. The chosen hunks are then applied in reverse to the
- working tree (and if a <tree-ish> was specified, the index).
+ working tree (and if a <tree> was specified, the index).
+
This means that you can use `git checkout -p` to selectively discard
edits from your current working tree.
@@ -144,7 +144,7 @@ checks out the branch (instead of detaching). You may also specify
The name of a commit at which to start the new branch; see
linkgit:git-branch[1] for details. Defaults to HEAD.
-<tree-ish>::
+<tree>::
Tree to checkout from (when paths are given). If not specified,
the index will be used.
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 67b6bc0..6188854 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
SYNOPSIS
--------
-'git commit-tree' <tree-ish> [-p <parent commit>]\* < changelog
+'git commit-tree' <tree> [-p <parent commit>]\* < changelog
DESCRIPTION
-----------
@@ -35,7 +35,7 @@ state was.
OPTIONS
-------
-<tree-ish>::
+<tree>::
An existing tree object
-p <parent commit>::
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 162cb74..c725357 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -8,7 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi
SYNOPSIS
--------
-'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...]
+'git diff-index' [-m] [--cached] [<common diff options>] <tree> [<path>...]
DESCRIPTION
-----------
@@ -22,7 +22,7 @@ OPTIONS
-------
include::diff-options.txt[]
-<tree-ish>::
+<tree>::
The id of a tree object to diff against.
--cached::
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 5d0310b..e566188 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -11,13 +11,13 @@ SYNOPSIS
[verse]
'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
[-t] [-r] [-c | --cc] [--root] [<common diff options>]
- <tree-ish> [<tree-ish>] [<path>...]
+ <tree> [<tree>] [<path>...]
DESCRIPTION
-----------
Compares the content and mode of the blobs found via two tree objects.
-If there is only one <tree-ish> given, the commit is compared with its parents
+If there is only one <tree> given, the commit is compared with its parents
(see --stdin below).
Note that 'git diff-tree' can use the tree encapsulated in a commit object.
@@ -26,7 +26,7 @@ OPTIONS
-------
include::diff-options.txt[]
-<tree-ish>::
+<tree>::
The id of a tree object.
<path>...::
@@ -48,7 +48,7 @@ include::diff-options.txt[]
--stdin::
When '--stdin' is specified, the command does not take
- <tree-ish> arguments from the command line. Instead, it
+ <tree> arguments from the command line. Instead, it
reads lines containing <sha1>'s: either two trees, one commit, or
multiple commits from its standard input. (Use a single space
as separator.)
@@ -91,7 +91,7 @@ include::pretty-options.txt[]
-c::
This flag changes the way a merge commit is displayed
(which means it is useful only when the command is given
- one <tree-ish>, or '--stdin'). It shows the differences
+ one <tree>, or '--stdin'). It shows the differences
from each of the parents to the merge result simultaneously
instead of showing pairwise diff between a parent and the
result one at a time (which is what the '-m' option does).
@@ -121,13 +121,13 @@ Limiting Output
If you're only interested in differences in a subset of files, for
example some architecture-specific files, you might do:
- git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
+ git diff-tree -r <tree> <tree> arch/ia64 include/asm-ia64
and it will only show you what changed in those two directories.
Or if you are searching for what changed in just `kernel/sched.c`, just do
- git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
+ git diff-tree -r <tree> <tree> kernel/sched.c
and it will ignore all differences to other files.
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 723a648..4582179 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -65,7 +65,7 @@ forced by --no-index.
Just in case if you are doing something exotic, it should be
noted that all of the <commit> in the above description, except
for the last two forms that use ".." notations, can be any
-<tree-ish>.
+<tree>.
For a more complete list of ways to spell <commit>, see
"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 02d6306..4b32322 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -21,7 +21,7 @@ SYNOPSIS
[-A <post-context>] [-B <pre-context>] [-C <context>]
[-f <file>] [-e] <pattern>
[--and|--or|--not|(|)|-e <pattern>...]
- [--cached | --no-index | <tree-ish>...]
+ [--cached | --no-index | <tree>...]
[--] [<pathspec>...]
DESCRIPTION
@@ -168,7 +168,7 @@ OPTIONS
Do not output matched lines; instead, exit with status 0 when
there is a match and with non-zero status when there isn't.
-<tree-ish>...::
+<tree>...::
Instead of searching tracked files in the working tree, search
blobs in the given trees.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..ed63f21 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -16,7 +16,7 @@ SYNOPSIS
[-X <file>|--exclude-from=<file>]
[--exclude-per-directory=<file>]
[--exclude-standard]
- [--error-unmatch] [--with-tree=<tree-ish>]
+ [--error-unmatch] [--with-tree=<tree>]
[--full-name] [--abbrev] [--] [<file>]\*
DESCRIPTION
@@ -98,11 +98,11 @@ OPTIONS
If any <file> does not appear in the index, treat this as an
error (return 1).
---with-tree=<tree-ish>::
+--with-tree=<tree>::
When using --error-unmatch to expand the user supplied
<file> (i.e. path pattern) arguments to paths, pretend
that paths which were removed in the index since the
- named <tree-ish> are still present. Using this option
+ named <tree> are still present. Using this option
with `-s` or `-u` options does not make any sense.
-t::
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 1f89d36..4964787 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git ls-tree' [-d] [-r] [-t] [-l] [-z]
[--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]
- <tree-ish> [paths...]
+ <tree> [paths...]
DESCRIPTION
-----------
@@ -35,7 +35,7 @@ in the current working directory. Note that:
OPTIONS
-------
-<tree-ish>::
+<tree>::
Id of a tree-ish.
-d::
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 567671c..979793e 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -16,7 +16,7 @@ SYNOPSIS
DESCRIPTION
-----------
-Reads the tree information given by <tree-ish> into the index,
+Reads the tree information given by <tree> into the index,
but does not actually *update* any of the files it "caches". (see:
linkgit:git-checkout-index[1])
@@ -272,7 +272,7 @@ merge. The different stages represent the "result tree" (stage 0, aka
you are trying to merge (stage 2 and 3 respectively).
The order of stages 1, 2 and 3 (hence the order of three
-<tree-ish> command line arguments) are significant when you
+<tree> command line arguments) are significant when you
start a 3-way merge with an index file that is already
populated. Here is an outline of how the algorithm works:
diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt
index 3c786bd..6d0a746 100644
--- a/Documentation/git-tar-tree.txt
+++ b/Documentation/git-tar-tree.txt
@@ -8,7 +8,7 @@ git-tar-tree - Create a tar archive of the files in the named tree object
SYNOPSIS
--------
-'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ]
+'git tar-tree' [--remote=<repo>] <tree> [ <base> ]
DESCRIPTION
-----------
@@ -29,7 +29,7 @@ It can be extracted using 'git get-tar-commit-id'.
OPTIONS
-------
-<tree-ish>::
+<tree>::
The tree or commit to produce tar archive for. If it is
the object name of a commit object.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 55f3842..eb87edb 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -430,7 +430,10 @@ Identifier Terminology
Indicates a commit-type <object>.
<tree>::
- Indicates a tree-type <object>.
+ Indicates a tree-type <object>, or a <tag> or <commit> that points at
+ a <tree>. A command that takes a <tree> argument ultimately
+ wants to operate on a tree object but automatically dereferences
+ objects until it finds a tree.
<blob>::
Indicates a blob-type <object>.
@@ -443,12 +446,6 @@ Identifier Terminology
until it finds a commit.
A <rev> is another name for a <commit-ish>.
-<tree-ish>::
- Indicates a <tree>, or a <tag> or <commit> that points at a
- <tree-ish>. A command that takes a <tree-ish> argument ultimately
- wants to operate on a tree object but automatically dereferences
- objects until it finds a tree.
-
<type>::
Indicates that an object type is required.
Currently one of: `blob`, `tree`, `commit`, or `tag`.
diff --git a/archive.c b/archive.c
index d700af3..4fefb64 100644
--- a/archive.c
+++ b/archive.c
@@ -7,9 +7,9 @@
#include "unpack-trees.h"
static char const * const archive_usage[] = {
- "git archive [options] <tree-ish> [path...]",
+ "git archive [options] <tree> [path...]",
"git archive --list",
- "git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]",
+ "git archive --remote <repo> [--exec <cmd>] [options] <tree> [path...]",
"git archive --remote <repo> [--exec <cmd>] --list",
NULL
};
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 770baa2..225e515 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)
typename(expect));
}
-static const char commit_tree_usage[] = "git commit-tree <tree-ish> [-p <commit>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <tree> [-p <commit>]* < changelog";
static void new_parent(struct commit *parent, struct commit_list **parents_p)
{
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index 0483749..5c4c5ce 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -6,7 +6,7 @@
static const char diff_cache_usage[] =
"git diff-index [-m] [--cached] "
-"[<common diff options>] <tree-ish> [<path>...]"
+"[<common diff options>] <tree> [<path>...]"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_index(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 2380c21..e446dd5 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -87,7 +87,7 @@ static int diff_tree_stdin(char *line)
static const char diff_tree_usage[] =
"git diff-tree [--stdin] [-m] [-c] [--cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
-"[<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"[<common diff options>] <tree> [<tree>] [<path>...]\n"
" -r diff recursively\n"
" --root include the initial commit as diff against /dev/null\n"
COMMON_DIFF_OPTIONS_HELP;
diff --git a/builtin/ls-files.c b/builtin/ls-files.c
index b065061..6dc885d 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -513,7 +513,7 @@ int cmd_ls_files(int argc, const char **argv, const char *prefix)
OPT_BOOLEAN(0, "error-unmatch", &error_unmatch,
"if any <file> is not in the index, treat this as an error"),
OPT_STRING(0, "with-tree", &with_tree, "tree-ish",
- "pretend that paths removed since <tree-ish> are still present"),
+ "pretend that paths removed since <tree> are still present"),
OPT__ABBREV(&abbrev),
OPT_END()
};
diff --git a/builtin/ls-tree.c b/builtin/ls-tree.c
index 4484185..8a52e42 100644
--- a/builtin/ls-tree.c
+++ b/builtin/ls-tree.c
@@ -24,7 +24,7 @@ static int chomp_prefix;
static const char *ls_tree_prefix;
static const char * const ls_tree_usage[] = {
- "git ls-tree [<options>] <tree-ish> [path...]",
+ "git ls-tree [<options>] <tree> [path...]",
NULL
};
diff --git a/builtin/tar-tree.c b/builtin/tar-tree.c
index 3f1e701..abdcd0b 100644
--- a/builtin/tar-tree.c
+++ b/builtin/tar-tree.c
@@ -8,7 +8,7 @@
#include "quote.h"
static const char tar_tree_usage[] =
-"git tar-tree [--remote=<repo>] <tree-ish> [basedir]\n"
+"git tar-tree [--remote=<repo>] <tree> [basedir]\n"
"*** Note that this command is now deprecated; use \"git archive\" instead.";
static const char builtin_get_tar_commit_id_usage[] =
diff --git a/git-svn.perl b/git-svn.perl
index 1a26843..c80eb49 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -997,7 +997,7 @@ sub cmd_multi_fetch {
sub cmd_commit_diff {
my ($ta, $tb, $url) = @_;
my $usage = "Usage: $0 commit-diff -r<revision> ".
- "<tree-ish> <tree-ish> [<URL>]";
+ "<tree> <tree> [<URL>]";
fatal($usage) if (!defined $ta || !defined $tb);
my $svn_path = '';
if (!defined $url) {
diff --git a/t/t4100/t-apply-3.patch b/t/t4100/t-apply-3.patch
index 90cdbaa..c702866 100644
--- a/t/t4100/t-apply-3.patch
+++ b/t/t4100/t-apply-3.patch
@@ -12,8 +12,8 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
SYNOPSIS
--------
--'git-ls-tree' [-r] [-z] <tree-ish> [paths...]
-+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
+-'git-ls-tree' [-r] [-z] <tree> [paths...]
++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...]
DESCRIPTION
-----------
@@ -24,7 +24,7 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
OPTIONS
-------
- <tree-ish>::
+ <tree>::
Id of a tree.
+-d::
@@ -485,7 +485,7 @@ dissimilarity index 82%
+}
+
+static const char *ls_tree_usage =
-+ "git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]";
++ "git-ls-tree [-d] [-r] [-z] <tree> [path...]";
+
+int main(int argc, char **argv)
+{
diff --git a/t/t4100/t-apply-7.patch b/t/t4100/t-apply-7.patch
index 07c6589..bf8737b 100644
--- a/t/t4100/t-apply-7.patch
+++ b/t/t4100/t-apply-7.patch
@@ -11,8 +11,8 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
SYNOPSIS
--------
--'git-ls-tree' [-r] [-z] <tree-ish> [paths...]
-+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
+-'git-ls-tree' [-r] [-z] <tree> [paths...]
++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...]
DESCRIPTION
-----------
@@ -23,7 +23,7 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
OPTIONS
-------
- <tree-ish>::
+ <tree>::
Id of a tree.
+-d::
@@ -415,7 +415,7 @@ diff a/ls-tree.c b/ls-tree.c
-static const char *ls_tree_usage = "git-ls-tree [-r] [-z] <key> [paths...]";
+static const char *ls_tree_usage =
-+ "git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]";
++ "git-ls-tree [-d] [-r] [-z] <tree> [path...]";
int main(int argc, char **argv)
{
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 08/12] http-fetch docs: use <commit-id> consistently
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (6 preceding siblings ...)
2010-03-13 4:52 ` [PATCH/RFC 07/12] docs: use <tree> instead of <tree-ish> Mark Lodato
@ 2010-03-13 4:53 ` Mark Lodato
2010-03-13 4:53 ` [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish> Mark Lodato
` (3 subsequent siblings)
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:53 UTC (permalink / raw
To: git; +Cc: Mark Lodato
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
It says that it can be "the filename under ...", but I couldn't get that
to work. Can anyone explain how to use something other than a SHA-1?
Documentation/git-http-fetch.txt | 4 ++--
1 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt
index d91cb7f..93449fd 100644
--- a/Documentation/git-http-fetch.txt
+++ b/Documentation/git-http-fetch.txt
@@ -8,7 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP
SYNOPSIS
--------
-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url>
+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit-id> <url>
DESCRIPTION
-----------
@@ -16,7 +16,7 @@ Downloads a remote git repository via HTTP.
OPTIONS
-------
-commit-id::
+<commit-id>::
Either the hash or the filename under [URL]/refs/ to
pull.
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (7 preceding siblings ...)
2010-03-13 4:53 ` [PATCH/RFC 08/12] http-fetch docs: use <commit-id> consistently Mark Lodato
@ 2010-03-13 4:53 ` Mark Lodato
2010-03-13 22:05 ` Junio C Hamano
2010-03-13 4:53 ` [PATCH/RFC 10/12] diff: use brackets for optional args in usage Mark Lodato
` (2 subsequent siblings)
11 siblings, 1 reply; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:53 UTC (permalink / raw
To: git; +Cc: Mark Lodato
There exist no commands that accept a <commit> but not a <commit-ish>,
so there is no reason to use the latter term anymore. Instead, use
<commit> everywhere the term <commit-ish>, <committish>, commit-ish, or
comittish was used.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
This was a little harder than the removal of tree-ish, since commit-ish
was used not only in the documentation but in the code. I tried to
replace the term without losing meaning, but the comments in particular
should be examined to see if they are just as clear as before.
The following commands already use the term <commit>, but actually
accept a <commit-ish>:
bisect, branch, cherry-pick, commit, merge, tag, diff, difftool,
format-patch, merge-base, rebase, reset, rev-list, revert
The only commands left that do not accept a commit-ish are:
http-fetch accepts a <commit-id>, as noted previously
commit-tree accepts an old <commit> (no tag objects)
Documentation/git-describe.txt | 14 +++++++-------
Documentation/git-fast-import.txt | 22 +++++++++++-----------
Documentation/git-name-rev.txt | 2 +-
Documentation/git-rebase.txt | 2 +-
Documentation/git-shortlog.txt | 2 +-
Documentation/git.txt | 15 ++++++---------
Documentation/gitcli.txt | 2 +-
Documentation/howto/revert-branch-rebase.txt | 2 +-
builtin/describe.c | 4 ++--
builtin/merge.c | 2 +-
builtin/revert.c | 4 ++--
contrib/examples/git-merge.sh | 2 +-
contrib/examples/git-reset.sh | 2 +-
contrib/examples/git-revert.sh | 4 ++--
fast-import.c | 16 ++++++++--------
remote.c | 4 ++--
16 files changed, 48 insertions(+), 51 deletions(-)
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 6fc5323..f272fa6 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit
SYNOPSIS
--------
[verse]
-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>...
+'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit>...
'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
DESCRIPTION
@@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1].
OPTIONS
-------
-<committish>...::
- Committish object names to describe.
+<commit>...::
+ Commit object names to describe.
--dirty[=<mark>]::
Describe the working tree.
@@ -57,7 +57,7 @@ OPTIONS
--candidates=<n>::
Instead of considering only the 10 most recent tags as
- candidates to describe the input committish consider
+ candidates to describe the input commit consider
up to <n> candidates. Increasing <n> above 10 will take
slightly longer but may produce a more accurate result.
An <n> of 0 will cause only exact matches to be output.
@@ -136,7 +136,7 @@ be sufficient to disambiguate these commits.
SEARCH STRATEGY
---------------
-For each committish supplied, 'git describe' will first look for
+For each commit supplied, 'git describe' will first look for
a tag which tags exactly that commit. Annotated tags will always
be preferred over lightweight tags, and tags with newer dates will
always be preferred over tags with older dates. If an exact match
@@ -145,10 +145,10 @@ is found, its name will be output and searching will stop.
If an exact match was not found, 'git describe' will walk back
through the commit history to locate an ancestor commit which
has been tagged. The ancestor's tag will be output along with an
-abbreviation of the input committish's SHA1.
+abbreviation of the input commit's SHA1.
If multiple tags were found during the walk then the tag which
-has the fewest commits different from the input committish will be
+has the fewest commits different from the input commit will be
selected and output. Here fewest commits different is defined as
the number of commits which would be shown by `git log tag..input`
will be the smallest number of commits possible.
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 19082b0..bdf369a 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -340,8 +340,8 @@ change to the project.
('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
'committer' (SP <name>)? SP LT <email> GT SP <when> LF
data
- ('from' SP <committish> LF)?
- ('merge' SP <committish> LF)?
+ ('from' SP <commit> LF)?
+ ('merge' SP <commit> LF)?
(filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
LF?
....
@@ -418,9 +418,9 @@ as the current commit on that branch is automatically assumed to
be the first ancestor of the new commit.
As `LF` is not valid in a Git refname or SHA-1 expression, no
-quoting or escaping syntax is supported within `<committish>`.
+quoting or escaping syntax is supported within `<commit>`.
-Here `<committish>` is any of the following:
+Here `<commit>` is any of the following:
* The name of an existing branch already in fast-import's internal branch
table. If fast-import doesn't know the name, it's treated as a SHA-1
@@ -465,7 +465,7 @@ additional ancestors (forming a 16-way merge). For this reason
it is suggested that frontends do not use more than 15 `merge`
commands per commit; 16, if starting a new, empty branch.
-Here `<committish>` is any of the commit specification expressions
+Here `<commit>` is any of the commit specification expressions
also accepted by `from` (see above).
`filemodify`
@@ -632,7 +632,7 @@ External data format::
commit that is to be annotated.
+
....
- 'N' SP <dataref> SP <committish> LF
+ 'N' SP <dataref> SP <commit> LF
....
+
Here `<dataref>` can be either a mark reference (`:<idnum>`)
@@ -645,13 +645,13 @@ Inline data format::
command.
+
....
- 'N' SP 'inline' SP <committish> LF
+ 'N' SP 'inline' SP <commit> LF
data
....
+
See below for a detailed description of the `data` command.
-In both formats `<committish>` is any of the commit specification
+In both formats `<commit>` is any of the commit specification
expressions also accepted by `from` (see above).
`mark`
@@ -682,7 +682,7 @@ lightweight (non-annotated) tags see the `reset` command below.
....
'tag' SP <name> LF
- 'from' SP <committish> LF
+ 'from' SP <commit> LF
'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
data
....
@@ -727,11 +727,11 @@ branch from an existing commit without creating a new commit.
....
'reset' SP <ref> LF
- ('from' SP <committish> LF)?
+ ('from' SP <commit> LF)?
LF?
....
-For a detailed description of `<ref>` and `<committish>` see above
+For a detailed description of `<ref>` and `<commit>` see above
under `commit` and `from`.
The `LF` after the command is optional (it used to be required).
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt
index 2108237..40af544 100644
--- a/Documentation/git-name-rev.txt
+++ b/Documentation/git-name-rev.txt
@@ -10,7 +10,7 @@ SYNOPSIS
--------
[verse]
'git name-rev' [--tags] [--refs=<pattern>]
- ( --all | --stdin | <committish>... )
+ ( --all | --stdin | <commit>... )
DESCRIPTION
-----------
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 823f2a4..e32c393 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -168,7 +168,7 @@ would result in the removal of commits F and G:
This is useful if F and G were flawed in some way, or should not be
part of topicA. Note that the argument to --onto and the <upstream>
-parameter can be any valid commit-ish.
+parameter can be any valid <commit>.
In case of conflict, 'git rebase' will stop at the first problematic commit
and leave conflict markers in the tree. You can use 'git diff' to locate
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index dfd4d0c..61dc039 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
-'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...]
+'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<commit>...]
DESCRIPTION
-----------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index eb87edb..b7c89f9 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -426,8 +426,13 @@ Identifier Terminology
Indicates a tag-type <object>. This is an annotated tag object, as
opposed to <tagname>, which can refer to any type of object.
+<rev>::
<commit>::
- Indicates a commit-type <object>.
+ Indicates a commit-type <object>, or a <tag> that points at a <commit>.
+ A command that takes a <commit> argument ultimately wants to
+ operate on a commit object but automatically dereferences objects
+ until it finds a commit.
+ A <rev> is another name for a <commit>.
<tree>::
Indicates a tree-type <object>, or a <tag> or <commit> that points at
@@ -438,14 +443,6 @@ Identifier Terminology
<blob>::
Indicates a blob-type <object>.
-<rev>::
-<commit-ish>::
- Indicates a <commit>, or a <tag> that points at a <commit-ish>.
- A command that takes a <commit-ish> argument ultimately wants to
- operate on a commit object but automatically dereferences objects
- until it finds a commit.
- A <rev> is another name for a <commit-ish>.
-
<type>::
Indicates that an object type is required.
Currently one of: `blob`, `tree`, `commit`, or `tag`.
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 6928724..de0630f 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -81,7 +81,7 @@ couple of magic command line options:
+
---------------------------------------------
$ git describe -h
-usage: git describe [options] <committish>*
+usage: git describe [options] <commit>*
--contains find the tag that comes after the commit
--debug debug search strategy on stderr
diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt
index 8c32da6..5272bb0 100644
--- a/Documentation/howto/revert-branch-rebase.txt
+++ b/Documentation/howto/revert-branch-rebase.txt
@@ -160,7 +160,7 @@ $ git pull . master
Packing 0 objects
Unpacking 0 objects
-* committish: e3a693c... refs/heads/master from .
+* commit: e3a693c... refs/heads/master from .
Trying to merge e3a693c... into 8c1f5f0... using 10d781b...
Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
cache.h | 8 ++++----
diff --git a/builtin/describe.c b/builtin/describe.c
index 71be2a9..4ece73f 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -11,7 +11,7 @@
#define MAX_TAGS (FLAG_BITS - 1)
static const char * const describe_usage[] = {
- "git describe [options] <committish>*",
+ "git describe [options] <commit>*",
"git describe [options] --dirty",
NULL
};
@@ -386,7 +386,7 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
dirty = NULL;
describe("HEAD", 1);
} else if (dirty) {
- die("--dirty is incompatible with committishes");
+ die("--dirty is incompatible with commits");
} else {
while (argc-- > 0) {
describe(*argv++, argc == 0);
diff --git a/builtin/merge.c b/builtin/merge.c
index 3aaec7b..8d62424 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -940,7 +940,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
* This could be traditional "merge <msg> HEAD <commit>..." and
* the way we can tell it is to see if the second token is HEAD,
* but some people might have misused the interface and used a
- * committish that is the same as HEAD there instead.
+ * <commit> that is the same as HEAD there instead.
* Traditional format never would have "-m" so it is an
* additional safety measure to check for it.
*/
diff --git a/builtin/revert.c b/builtin/revert.c
index eff5268..e06d2a0 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -26,12 +26,12 @@
*/
static const char * const revert_usage[] = {
- "git revert [options] <commit-ish>",
+ "git revert [options] <commit>",
NULL
};
static const char * const cherry_pick_usage[] = {
- "git cherry-pick [options] <commit-ish>",
+ "git cherry-pick [options] <commit>",
NULL
};
diff --git a/contrib/examples/git-merge.sh b/contrib/examples/git-merge.sh
index 8f617fc..5aeee46 100755
--- a/contrib/examples/git-merge.sh
+++ b/contrib/examples/git-merge.sh
@@ -221,7 +221,7 @@ fi
# This could be traditional "merge <msg> HEAD <commit>..." and the
# way we can tell it is to see if the second token is HEAD, but some
-# people might have misused the interface and used a committish that
+# people might have misused the interface and used a <commit> that
# is the same as HEAD there instead. Traditional format never would
# have "-m" so it is an additional safety measure to check for it.
diff --git a/contrib/examples/git-reset.sh b/contrib/examples/git-reset.sh
index bafeb52..d287a80 100755
--- a/contrib/examples/git-reset.sh
+++ b/contrib/examples/git-reset.sh
@@ -2,7 +2,7 @@
#
# Copyright (c) 2005, 2006 Linus Torvalds and Junio C Hamano
#
-USAGE='[--mixed | --soft | --hard] [<commit-ish>] [ [--] <paths>...]'
+USAGE='[--mixed | --soft | --hard] [<commit>] [ [--] <paths>...]'
SUBDIRECTORY_OK=Yes
. git-sh-setup
set_reflog_action "reset $*"
diff --git a/contrib/examples/git-revert.sh b/contrib/examples/git-revert.sh
index 49f0032..c543add 100755
--- a/contrib/examples/git-revert.sh
+++ b/contrib/examples/git-revert.sh
@@ -9,12 +9,12 @@ case "$0" in
test -t 0 && edit=-e
replay=
me=revert
- USAGE='[--edit | --no-edit] [-n] <commit-ish>' ;;
+ USAGE='[--edit | --no-edit] [-n] <commit>' ;;
*-cherry-pick* )
replay=t
edit=
me=cherry-pick
- USAGE='[--edit] [-n] [-r] [-x] <commit-ish>' ;;
+ USAGE='[--edit] [-n] [-r] [-x] <commit>' ;;
* )
echo >&2 "What are you talking about?"
exit 1 ;;
diff --git a/fast-import.c b/fast-import.c
index 309f2c5..08afdc3 100644
--- a/fast-import.c
+++ b/fast-import.c
@@ -22,8 +22,8 @@ Format of STDIN stream:
('author' (sp name)? sp '<' email '>' sp when lf)?
'committer' (sp name)? sp '<' email '>' sp when lf
commit_msg
- ('from' sp committish lf)?
- ('merge' sp committish lf)*
+ ('from' sp commit lf)?
+ ('merge' sp commit lf)*
file_change*
lf?;
commit_msg ::= data;
@@ -41,18 +41,18 @@ Format of STDIN stream:
file_obm ::= 'M' sp mode sp (hexsha1 | idnum) sp path_str lf;
file_inm ::= 'M' sp mode sp 'inline' sp path_str lf
data;
- note_obm ::= 'N' sp (hexsha1 | idnum) sp committish lf;
- note_inm ::= 'N' sp 'inline' sp committish lf
+ note_obm ::= 'N' sp (hexsha1 | idnum) sp commit lf;
+ note_inm ::= 'N' sp 'inline' sp commit lf
data;
new_tag ::= 'tag' sp tag_str lf
- 'from' sp committish lf
+ 'from' sp commit lf
('tagger' (sp name)? sp '<' email '>' sp when lf)?
tag_msg;
tag_msg ::= data;
reset_branch ::= 'reset' sp ref_str lf
- ('from' sp committish lf)?
+ ('from' sp commit lf)?
lf?;
checkpoint ::= 'checkpoint' lf
@@ -91,7 +91,7 @@ Format of STDIN stream:
# stream formatting is: \, " and LF. Otherwise these values
# are UTF8.
#
- committish ::= (ref_str | hexsha1 | sha1exp_str | idnum);
+ commit ::= (ref_str | hexsha1 | sha1exp_str | idnum);
ref_str ::= ref;
sha1exp_str ::= sha1exp;
tag_str ::= tag;
@@ -2288,7 +2288,7 @@ static void note_change_n(struct branch *b, unsigned char old_fanout)
if (*p++ != ' ')
die("Missing space after SHA1: %s", command_buf.buf);
- /* <committish> */
+ /* <commit> */
s = lookup_branch(p);
if (s) {
hashcpy(commit_sha1, s->sha1);
diff --git a/remote.c b/remote.c
index c70181c..3c5f8c6 100644
--- a/remote.c
+++ b/remote.c
@@ -1277,7 +1277,7 @@ void set_ref_status_for_push(struct ref *remote_refs, int send_mirror,
* to overwrite it; you would not know what you are losing
* otherwise.
*
- * (3) if both new and old are commit-ish, and new is a
+ * (3) if both new and old are <commit>'s, and new is a
* descendant of old, it is OK.
*
* (4) regardless of all of the above, removing :B is
@@ -1475,7 +1475,7 @@ int ref_newer(const unsigned char *new_sha1, const unsigned char *old_sha1)
struct commit_list *list, *used;
int found = 0;
- /* Both new and old must be commit-ish and new is descendant of
+ /* Both new and old must be <commit>'s and new is descendant of
* old. Otherwise we require --force.
*/
o = deref_tag(parse_object(old_sha1), NULL, 0);
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>
2010-03-13 4:53 ` [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish> Mark Lodato
@ 2010-03-13 22:05 ` Junio C Hamano
2010-03-16 1:12 ` Mark Lodato
0 siblings, 1 reply; 20+ messages in thread
From: Junio C Hamano @ 2010-03-13 22:05 UTC (permalink / raw
To: Mark Lodato; +Cc: git
Mark Lodato <lodatom@gmail.com> writes:
> There exist no commands that accept a <commit> but not a <commit-ish>,
I have one worry about this and [07/12]. The droppage of -ish would make
sense from the point of view of describing command line arguments,
i.e. what you can give to the commands, but it would make it impossible
for us to talk about places that _only_ tree not arbitrary tree-ish can
appear. For example, don't we ever talk about something like this?
A tree object is a sequence of records, each of which describes the
type of entry, object name, and the name of the entry in the tree.
When the type is "tree", the object name must name a tree, when the
type is "gitlink", the object name must name a commit, ...
Other than that small worry, I think the series goes in the right
direction.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>
2010-03-13 22:05 ` Junio C Hamano
@ 2010-03-16 1:12 ` Mark Lodato
0 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-16 1:12 UTC (permalink / raw
To: Junio C Hamano; +Cc: git
On Sat, Mar 13, 2010 at 6:05 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> There exist no commands that accept a <commit> but not a <commit-ish>,
>
> I have one worry about this and [07/12]. The droppage of -ish would make
> sense from the point of view of describing command line arguments,
> i.e. what you can give to the commands, but it would make it impossible
> for us to talk about places that _only_ tree not arbitrary tree-ish can
> appear. For example, don't we ever talk about something like this?
>
> A tree object is a sequence of records, each of which describes the
> type of entry, object name, and the name of the entry in the tree.
> When the type is "tree", the object name must name a tree, when the
> type is "gitlink", the object name must name a commit, ...
>
> Other than that small worry, I think the series goes in the right
> direction.
Yes, it would probably be best to leave the -ish terms in the glossary
(which I evidently did by mistake) and in the comments and
documentation, but just not use them as an identifier in angle
brackets. For example, a command accepting a <tree> would also accept
commits or tags unless otherwise noted, but the term "tree object"
would still only refer to an actual tree object, not a tree-ish. When
it is unclear, one can use the -ish term, like I just did in that last
sentence.
I'll wait a few days to see if there are any more comments, and then
I'll try fixing up this series.
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH/RFC 10/12] diff: use brackets for optional args in usage
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (8 preceding siblings ...)
2010-03-13 4:53 ` [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish> Mark Lodato
@ 2010-03-13 4:53 ` Mark Lodato
2010-03-13 4:53 ` [PATCH/RFC 11/12] docs: use ... instead of * for multiplicity Mark Lodato
2010-03-13 4:53 ` [PATCH/RFC 12/12] diff docs: remove <rev>{0,2} notation Mark Lodato
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:53 UTC (permalink / raw
To: git; +Cc: Mark Lodato
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
builtin/diff.c | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/builtin/diff.c b/builtin/diff.c
index ffcdd05..a716704 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -21,7 +21,7 @@ struct blobinfo {
};
static const char builtin_diff_usage[] =
-"git diff <options> <rev>{0,2} -- <path>*";
+"git diff [<options>] <rev>{0,2} [--] [<path>]*";
static void stuff_change(struct diff_options *opt,
unsigned old_mode, unsigned new_mode,
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 11/12] docs: use ... instead of * for multiplicity
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (9 preceding siblings ...)
2010-03-13 4:53 ` [PATCH/RFC 10/12] diff: use brackets for optional args in usage Mark Lodato
@ 2010-03-13 4:53 ` Mark Lodato
2010-03-13 4:53 ` [PATCH/RFC 12/12] diff docs: remove <rev>{0,2} notation Mark Lodato
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:53 UTC (permalink / raw
To: git; +Cc: Mark Lodato
In the documentation and in usage messages, use [<foo>...] to denote
arguments that can occur zero or more times, rather than [<foo>]* or the
like. The '...' should come inside the brackets if there is a single
word (e.g., "[<file>...]"), but outside the brackets if there is more
than one word (e.g. "[-p <commit>]...").
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
I don't like having to put the ellipses inside and outside the brackets,
but I couldn't come up with anything that was more clear. Leaving the
star just for these cases is a worse alternative in my opinion, since
then it would be even more of an oddball.
By the way, can anyone explain why git-pack-objects(1) has
[--revs [--unpacked | --all]*]
and not the following?
[--revs] [--unpacked] [--all]
Documentation/git-checkout-index.txt | 2 +-
Documentation/git-commit-tree.txt | 2 +-
Documentation/git-for-each-ref.txt | 2 +-
Documentation/git-fsck.txt | 2 +-
Documentation/git-ls-files.txt | 2 +-
Documentation/git-merge-index.txt | 2 +-
Documentation/git-mergetool.txt | 2 +-
Documentation/git-pack-objects.txt | 2 +-
Documentation/git-relink.txt | 2 +-
Documentation/git-update-index.txt | 4 ++--
Documentation/gitcli.txt | 2 +-
builtin/commit-tree.c | 2 +-
builtin/describe.c | 2 +-
builtin/diff.c | 2 +-
builtin/ls-files.c | 2 +-
builtin/merge-index.c | 2 +-
builtin/pack-objects.c | 2 +-
17 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index d6aa6e1..0c0a9c1 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -13,7 +13,7 @@ SYNOPSIS
[--stage=<number>|all]
[--temp]
[-z] [--stdin]
- [--] [<file>]\*
+ [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 6188854..55f0390 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
SYNOPSIS
--------
-'git commit-tree' <tree> [-p <parent commit>]\* < changelog
+'git commit-tree' <tree> [-p <parent commit>]... < changelog
DESCRIPTION
-----------
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 7e83288..993f79f 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
- [--sort=<key>]\* [--format=<format>] [<pattern>...]
+ [--sort=<key>]... [--format=<format>] [<pattern>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 86f9b2b..38207a1 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -10,7 +10,7 @@ SYNOPSIS
--------
[verse]
'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
- [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>*]
+ [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index ed63f21..cbd6661 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -17,7 +17,7 @@ SYNOPSIS
[--exclude-per-directory=<file>]
[--exclude-standard]
[--error-unmatch] [--with-tree=<tree>]
- [--full-name] [--abbrev] [--] [<file>]\*
+ [--full-name] [--abbrev] [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt
index 4d266de..3716309 100644
--- a/Documentation/git-merge-index.txt
+++ b/Documentation/git-merge-index.txt
@@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging
SYNOPSIS
--------
-'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*)
+'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>...)
DESCRIPTION
-----------
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index 55735fa..bd6b301 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
SYNOPSIS
--------
-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...
+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 8ed09c0..a19aa4b 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
[--no-reuse-delta] [--delta-base-offset] [--non-empty]
[--local] [--incremental] [--window=N] [--depth=N]
- [--revs [--unpacked | --all]*] [--stdout | base-name]
+ [--revs [--unpacked | --all]...] [--stdout | base-name]
[--keep-true-parents] < object-list
diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt
index 25ff8f9..362a5dc 100644
--- a/Documentation/git-relink.txt
+++ b/Documentation/git-relink.txt
@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories
SYNOPSIS
--------
-'git relink' [--safe] <dir> [<dir>]\* <master_dir>
+'git relink' [--safe] <dir> [<dir>...] <master_dir>
DESCRIPTION
-----------
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 68dc187..2753d73 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git update-index'
[--add] [--remove | --force-remove] [--replace]
[--refresh] [-q] [--unmerged] [--ignore-missing]
- [--cacheinfo <mode> <object> <file>]\*
+ [--cacheinfo <mode> <object> <file>]...
[--chmod=(+|-)x]
[--assume-unchanged | --no-assume-unchanged]
[--skip-worktree | --no-skip-worktree]
@@ -21,7 +21,7 @@ SYNOPSIS
[--info-only] [--index-info]
[-z] [--stdin]
[--verbose]
- [--] [<file>]\*
+ [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index de0630f..eb51ffc 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -81,7 +81,7 @@ couple of magic command line options:
+
---------------------------------------------
$ git describe -h
-usage: git describe [options] <commit>*
+usage: git describe [options] <commit>...
--contains find the tag that comes after the commit
--debug debug search strategy on stderr
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 225e515..22ceff1 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -22,7 +22,7 @@ static void check_valid(unsigned char *sha1, enum object_type expect)
typename(expect));
}
-static const char commit_tree_usage[] = "git commit-tree <tree> [-p <commit>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <tree> [-p <commit>]... < changelog";
static void new_parent(struct commit *parent, struct commit_list **parents_p)
{
diff --git a/builtin/describe.c b/builtin/describe.c
index 4ece73f..2bba2ba 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -11,7 +11,7 @@
#define MAX_TAGS (FLAG_BITS - 1)
static const char * const describe_usage[] = {
- "git describe [options] <commit>*",
+ "git describe [options] <commit>...",
"git describe [options] --dirty",
NULL
};
diff --git a/builtin/diff.c b/builtin/diff.c
index a716704..f73da93 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -21,7 +21,7 @@ struct blobinfo {
};
static const char builtin_diff_usage[] =
-"git diff [<options>] <rev>{0,2} [--] [<path>]*";
+"git diff [<options>] <rev>{0,2} [--] [<path>...]";
static void stuff_change(struct diff_options *opt,
unsigned old_mode, unsigned new_mode,
diff --git a/builtin/ls-files.c b/builtin/ls-files.c
index 6dc885d..c57c93e 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -414,7 +414,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_
}
static const char * const ls_files_usage[] = {
- "git ls-files [options] [<file>]*",
+ "git ls-files [options] [<file>...]",
NULL
};
diff --git a/builtin/merge-index.c b/builtin/merge-index.c
index 2c4cf5e..c683bbd 100644
--- a/builtin/merge-index.c
+++ b/builtin/merge-index.c
@@ -76,7 +76,7 @@ int cmd_merge_index(int argc, const char **argv, const char *prefix)
signal(SIGCHLD, SIG_DFL);
if (argc < 3)
- usage("git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>*)");
+ usage("git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>...)");
read_cache();
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 9780258..19d9f09 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -28,7 +28,7 @@ static const char pack_usage[] =
" [--max-pack-size=N] [--local] [--incremental]\n"
" [--window=N] [--window-memory=N] [--depth=N]\n"
" [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\n"
- " [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\n"
+ " [--threads=N] [--non-empty] [--revs [--unpacked | --all]...]\n"
" [--reflog] [--stdout | base-name] [--include-tag]\n"
" [--keep-unreachable | --unpack-unreachable \n"
" [<ref-list | <object-list]";
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH/RFC 12/12] diff docs: remove <rev>{0,2} notation
2010-03-13 4:52 [PATCH/RFC 00/12] docs: use metavariables consistently Mark Lodato
` (10 preceding siblings ...)
2010-03-13 4:53 ` [PATCH/RFC 11/12] docs: use ... instead of * for multiplicity Mark Lodato
@ 2010-03-13 4:53 ` Mark Lodato
11 siblings, 0 replies; 20+ messages in thread
From: Mark Lodato @ 2010-03-13 4:53 UTC (permalink / raw
To: git; +Cc: Mark Lodato
This notation is not used anywhere else, so it can be confusing when
first encountered. Instead, prefer the slightly longer but just as
clear "[<rev> [<rev>]]", which is consistent with other commands.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
When I first ran `git diff -h` and I saw the old syntax, I was rather
confused. It took me a minute to realize that this was the regular
expression syntax. I think it's best to stick with one syntax, even if
it is a bit more verbose.
Documentation/git-diff.txt | 2 +-
Documentation/git-difftool.txt | 2 +-
builtin/diff.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 4582179..e2d868d 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc
SYNOPSIS
--------
-'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...]
+'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 8250bad..a02e3b5 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -7,7 +7,7 @@ git-difftool - Show changes using common diff tools
SYNOPSIS
--------
-'git difftool' [<options>] <commit>{0,2} [--] [<path>...]
+'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
DESCRIPTION
-----------
diff --git a/builtin/diff.c b/builtin/diff.c
index f73da93..e2e2efc 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -21,7 +21,7 @@ struct blobinfo {
};
static const char builtin_diff_usage[] =
-"git diff [<options>] <rev>{0,2} [--] [<path>...]";
+"git diff [<options>] [<rev> [<rev>]] [--] [<path>...]";
static void stuff_change(struct diff_options *opt,
unsigned old_mode, unsigned new_mode,
--
1.7.0.2
^ permalink raw reply related [flat|nested] 20+ messages in thread