* [PATCHv2 0/8] docs: use metavariables consistently
@ 2010-12-18 5:38 Mark Lodato
2010-12-18 5:38 ` [PATCH 1/8] fsck docs: remove outdated and useless diagnostic Mark Lodato
` (8 more replies)
0 siblings, 9 replies; 19+ messages in thread
From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano, Mark Lodato
Update the documentation and usage statements to use metavariables, such as
<commit>, more consistently. The biggest change is to drop the <tree-ish> and
<commit-ish> (or <committish>) notation and just use <tree> or <commit>, since
every command but commit-tree accepts tree-ishes and commit-ishes. The "-ish"
terms are still kept around in various places where it makes sense to
differentiate between an actual tree or commit and a tree-ish or commit-ish.
This is a rework of my earlier patch set from March [1], with the following
differences:
- Drop the patch to commit-tree that makes it accept a tree-ish.
- Drop the patch dealing with <tag> and <tagname>.
- Leave -ish terms in comments and in places where they make sense.
- Rebase onto master (1b97434). Some of the patches from before have since
been accepted from other authors.
- Fix a problem that Junio noticed with the "grep docs" patch.
[1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484
Mark Lodato (8):
fsck docs: remove outdated and useless diagnostic
docs: use `...' instead of `*' for multiplicity
docs: use <sha1> to mean unabbreviated ID
http-fetch docs: use <commit-id> consistently
grep docs: grep accepts a <tree-ish>, not a <tree>
docs: use <tree> instead of <tree-ish>
docs: use <commit> instead of <commit-ish>
describe docs: note that <commit> is optional
Documentation/RelNotes/1.6.2.4.txt | 2 +-
Documentation/diff-format.txt | 10 +++++-----
Documentation/diff-generate-patch.txt | 2 +-
Documentation/git-archive.txt | 4 ++--
Documentation/git-cat-file.txt | 2 +-
Documentation/git-checkout.txt | 16 ++++++++--------
Documentation/git-commit-tree.txt | 3 ++-
Documentation/git-describe.txt | 15 ++++++++-------
Documentation/git-diff-index.txt | 4 ++--
Documentation/git-diff-tree.txt | 18 +++++++++---------
Documentation/git-fast-import.txt | 22 +++++++++++-----------
Documentation/git-fsck.txt | 5 +----
Documentation/git-http-fetch.txt | 4 ++--
Documentation/git-ls-files.txt | 6 +++---
Documentation/git-ls-tree.txt | 6 +++---
Documentation/git-merge-index.txt | 2 +-
Documentation/git-merge-tree.txt | 2 +-
Documentation/git-name-rev.txt | 2 +-
Documentation/git-read-tree.txt | 10 +++++-----
Documentation/git-rebase.txt | 2 +-
Documentation/git-svn.txt | 6 +++---
Documentation/git-tar-tree.txt | 4 ++--
Documentation/git.txt | 27 +++++++++++++--------------
Documentation/gitcli.txt | 6 +++---
Documentation/gittutorial-2.txt | 6 ++----
Documentation/glossary-content.txt | 4 ++++
archive.c | 4 ++--
builtin/commit-tree.c | 2 +-
builtin/describe.c | 4 ++--
builtin/diff-index.c | 2 +-
builtin/diff-tree.c | 2 +-
builtin/ls-files.c | 4 ++--
builtin/ls-tree.c | 2 +-
builtin/merge-index.c | 2 +-
builtin/read-tree.c | 2 +-
builtin/revert.c | 4 ++--
builtin/tar-tree.c | 2 +-
contrib/examples/git-reset.sh | 2 +-
contrib/examples/git-revert.sh | 4 ++--
git-svn.perl | 6 +++---
t/t4100/t-apply-3.patch | 8 ++++----
t/t4100/t-apply-7.patch | 8 ++++----
42 files changed, 124 insertions(+), 124 deletions(-)
--
1.7.3.2
^ permalink raw reply [flat|nested] 19+ messages in thread* [PATCH 1/8] fsck docs: remove outdated and useless diagnostic 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 5:38 ` [PATCH 2/8] docs: use `...' instead of `*' for multiplicity Mark Lodato ` (7 subsequent siblings) 8 siblings, 0 replies; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato In git-fsck(1), there was a reference to the warning "<tree> has full pathnames in it". This exact wording has not been used since 2005 (commit f1f0d0889e55), when the wording was changed slightly. More importantly, the description of that warning was useless, and there were many other similar warning messages which were not document at all. Since all these warnings are fairly obvious, there is no need for them to be in the man page. Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-fsck.txt | 3 --- 1 files changed, 0 insertions(+), 3 deletions(-) diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 3ad48a6..86f9b2b 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -123,9 +123,6 @@ dangling <type> <object>:: The <type> object <object>, is present in the database but never 'directly' used. A dangling commit could be a root node. -warning: git-fsck: tree <tree> has full pathnames in it:: - And it shouldn't... - sha1 mismatch <object>:: The database has an object who's sha1 doesn't match the database value. -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* [PATCH 2/8] docs: use `...' instead of `*' for multiplicity 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato 2010-12-18 5:38 ` [PATCH 1/8] fsck docs: remove outdated and useless diagnostic Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 10:00 ` Jakub Narebski 2010-12-18 5:38 ` [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID Mark Lodato ` (6 subsequent siblings) 8 siblings, 1 reply; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato Finish the work of 0adda93 (Use parentheses and `...' where appropriate) to follow the rules set forth in Documentation/CodingGuidelines. Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-fsck.txt | 2 +- Documentation/git-merge-index.txt | 2 +- Documentation/gitcli.txt | 2 +- builtin/describe.c | 2 +- builtin/merge-index.c | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 86f9b2b..38207a1 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] - [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>*] + [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>...] DESCRIPTION ----------- diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 921b38f..3716309 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- -'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) +'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>...) DESCRIPTION ----------- diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 6928724..eb65dcf 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -81,7 +81,7 @@ couple of magic command line options: + --------------------------------------------- $ git describe -h -usage: git describe [options] <committish>* +usage: git describe [options] <committish>... --contains find the tag that comes after the commit --debug debug search strategy on stderr diff --git a/builtin/describe.c b/builtin/describe.c index a0f52c1..34a8031 100644 --- a/builtin/describe.c +++ b/builtin/describe.c @@ -12,7 +12,7 @@ #define MAX_TAGS (FLAG_BITS - 1) static const char * const describe_usage[] = { - "git describe [options] <committish>*", + "git describe [options] <committish>...", "git describe [options] --dirty", NULL }; diff --git a/builtin/merge-index.c b/builtin/merge-index.c index 2c4cf5e..c683bbd 100644 --- a/builtin/merge-index.c +++ b/builtin/merge-index.c @@ -76,7 +76,7 @@ int cmd_merge_index(int argc, const char **argv, const char *prefix) signal(SIGCHLD, SIG_DFL); if (argc < 3) - usage("git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>*)"); + usage("git merge-index [-o] [-q] <merge-program> (-a | [--] <filename>...)"); read_cache(); -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH 2/8] docs: use `...' instead of `*' for multiplicity 2010-12-18 5:38 ` [PATCH 2/8] docs: use `...' instead of `*' for multiplicity Mark Lodato @ 2010-12-18 10:00 ` Jakub Narebski 2010-12-18 16:32 ` Mark Lodato 0 siblings, 1 reply; 19+ messages in thread From: Jakub Narebski @ 2010-12-18 10:00 UTC (permalink / raw) To: Mark Lodato; +Cc: git, Junio C Hamano Mark Lodato <lodatom@gmail.com> writes: > Finish the work of 0adda93 (Use parentheses and `...' where appropriate) > to follow the rules set forth in Documentation/CodingGuidelines. > > Signed-off-by: Mark Lodato <lodatom@gmail.com> [...] > - "git describe [options] <committish>*", > + "git describe [options] <committish>...", Isn't <sth>... one or more, while <sth>* is zero or more, i.e. shouldn't <sth>* be replaced by [<sth>...]? Hmmm... I see that <sth>* was actively wrong if it was to mean zero or more, so your change doesn't only make documentation more consistent, but fixes errorneous use of convention. -- Jakub Narebski Poland ShadeHawk on #git ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 2/8] docs: use `...' instead of `*' for multiplicity 2010-12-18 10:00 ` Jakub Narebski @ 2010-12-18 16:32 ` Mark Lodato 0 siblings, 0 replies; 19+ messages in thread From: Mark Lodato @ 2010-12-18 16:32 UTC (permalink / raw) To: Jakub Narebski; +Cc: git, Junio C Hamano On Sat, Dec 18, 2010 at 5:00 AM, Jakub Narebski <jnareb@gmail.com> wrote: > Mark Lodato <lodatom@gmail.com> writes: > >> Finish the work of 0adda93 (Use parentheses and `...' where appropriate) >> to follow the rules set forth in Documentation/CodingGuidelines. >> >> Signed-off-by: Mark Lodato <lodatom@gmail.com> > > [...] > >> - "git describe [options] <committish>*", >> + "git describe [options] <committish>...", > > Isn't <sth>... one or more, while <sth>* is zero or more, i.e. shouldn't > <sth>* be replaced by [<sth>...]? Yes, I was confused by the * notation - one more reason to get rid of it! > Hmmm... I see that <sth>* was actively wrong if it was to mean zero or > more, so your change doesn't only make documentation more consistent, > but fixes errorneous use of convention. I think zero or more is correct, which is why I submitted patch 8/8 to change from <commit>... to [<commit>...]. Now I understand that all 8/8 was doing was fixing a mistake I introduced in this patch. I'll correct it in the next version. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato 2010-12-18 5:38 ` [PATCH 1/8] fsck docs: remove outdated and useless diagnostic Mark Lodato 2010-12-18 5:38 ` [PATCH 2/8] docs: use `...' instead of `*' for multiplicity Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 7:47 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 4/8] http-fetch docs: use <commit-id> consistently Mark Lodato ` (5 subsequent siblings) 8 siblings, 1 reply; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato There are some places that literally require a full, 40-character SHA-1 ID, rather than a generic revision specifier. Introduce in git(1) the <sha1> terminology to mean this. Use <sha1> in git-diff-tree(1) to note that --stdin only takes <sha1>s, not generic <tree>s or <commit>s. Use <tree> and <commit> in the usage statement for 'commit-tree'. Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-diff-tree.txt | 4 ++-- Documentation/git.txt | 5 +++++ builtin/commit-tree.c | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index a7e37b8..6b357a5 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -49,8 +49,8 @@ include::diff-options.txt[] --stdin:: When '--stdin' is specified, the command does not take <tree-ish> arguments from the command line. Instead, it - reads lines containing either two <tree>, one <commit>, or a - list of <commit> from its standard input. (Use a single space + reads lines containing <sha1>s: either two trees, one commit, or + multiple commits from its standard input. (Use a single space as separator.) + When two trees are given, it compares the first tree with the second. diff --git a/Documentation/git.txt b/Documentation/git.txt index 0128371..7929739 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -457,6 +457,11 @@ list. Identifier Terminology ---------------------- +<sha1>:: + Indicates a full, 40-character SHA-1 identifier of an object. + The type of the referenced object is unspecified. + Abbreviated or symbolic identifiers cannot be used. + <object>:: Indicates the object name for any type of object. diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c index d083795..da572c3 100644 --- a/builtin/commit-tree.c +++ b/builtin/commit-tree.c @@ -9,7 +9,7 @@ #include "builtin.h" #include "utf8.h" -static const char commit_tree_usage[] = "git commit-tree <sha1> [(-p <sha1>)...] < changelog"; +static const char commit_tree_usage[] = "git commit-tree <tree> [(-p <commit>)...] < changelog"; static void new_parent(struct commit *parent, struct commit_list **parents_p) { -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID 2010-12-18 5:38 ` [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID Mark Lodato @ 2010-12-18 7:47 ` Jonathan Nieder 2010-12-18 18:50 ` Junio C Hamano 0 siblings, 1 reply; 19+ messages in thread From: Jonathan Nieder @ 2010-12-18 7:47 UTC (permalink / raw) To: Mark Lodato; +Cc: git, Junio C Hamano Mark Lodato wrote: > There are some places that literally require a full, 40-character SHA-1 > ID, rather than a generic revision specifier. One name I have seen for these is "object IDs", as in git get-tar-commit-id (to avoid putting too much emphasis on precisely how the identifiers are chosen). > Use <sha1> in git-diff-tree(1) to note > that --stdin only takes <sha1>s, not generic <tree>s or <commit>s. In this example, maybe it would be cleanest to spell out "40-digit object identifier". Perhaps something like this? (The text is more verbose than I'd like and it would be nicer to include an example, though.) Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index a7e37b8..85ce185 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -49,9 +49,11 @@ include::diff-options.txt[] --stdin:: When '--stdin' is specified, the command does not take <tree-ish> arguments from the command line. Instead, it - reads lines containing either two <tree>, one <commit>, or a - list of <commit> from its standard input. (Use a single space - as separator.) + reads lines, each naming two trees, one commit, or multiple + commits, from its standard input. Each line consists of a + list of full 40-digit object identifiers with a single space + as separator. Objects must be named directly; for example, + a tag ID cannot be used to represent a commit. + When two trees are given, it compares the first tree with the second. When a single commit is given, it compares the commit with its ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID 2010-12-18 7:47 ` Jonathan Nieder @ 2010-12-18 18:50 ` Junio C Hamano 0 siblings, 0 replies; 19+ messages in thread From: Junio C Hamano @ 2010-12-18 18:50 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Mark Lodato, git Jonathan Nieder <jrnieder@gmail.com> writes: > Mark Lodato wrote: > >> There are some places that literally require a full, 40-character SHA-1 >> ID, rather than a generic revision specifier. > > One name I have seen for these is "object IDs", as in git get-tar-commit-id > (to avoid putting too much emphasis on precisely how the identifiers are > chosen). Yes, I think I also saw "a full object name" (cf. diff --full-index) and evan "object name" (cf. git-pack-objects(1)). These are all deliberate efforts to stay away from spelling SHA-1 explicitly, and I think it makes sense to do so here. "40-digit object ID" is a mouthful, though. As to what this series tries to do, I think it is generally a good idea to start allowing documents to say <tree> when a reader can plug either a commit or a tree, rather than <tree-ish>, only because all Porcelains automatically dereference object names to needed types these days. But such a change needs to mark places that _must_ take the name of an object of the specific type somehow. It is Ok to say ls-tree takes a tree, but then we must say you should feed commit-tree nothing but a tree. It is a separate issue to allow plumbings to automatically dereference when both of the following two conditions hold: (1) the intent is clear from the context; (2) nobody sane would have been relying on the side effect of the current typechecking. Letting commit-tree to unwrap a tree-ish to a tree would be a good example that clearly satisfies (1)---I am not sure about the other one. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 4/8] http-fetch docs: use <commit-id> consistently 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato ` (2 preceding siblings ...) 2010-12-18 5:38 ` [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 7:51 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 5/8] grep docs: grep accepts a <tree-ish>, not a <tree> Mark Lodato ` (4 subsequent siblings) 8 siblings, 1 reply; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-http-fetch.txt | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index d91cb7f..93449fd 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -8,7 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP SYNOPSIS -------- -'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url> +'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit-id> <url> DESCRIPTION ----------- @@ -16,7 +16,7 @@ Downloads a remote git repository via HTTP. OPTIONS ------- -commit-id:: +<commit-id>:: Either the hash or the filename under [URL]/refs/ to pull. -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH 4/8] http-fetch docs: use <commit-id> consistently 2010-12-18 5:38 ` [PATCH 4/8] http-fetch docs: use <commit-id> consistently Mark Lodato @ 2010-12-18 7:51 ` Jonathan Nieder 0 siblings, 0 replies; 19+ messages in thread From: Jonathan Nieder @ 2010-12-18 7:51 UTC (permalink / raw) To: Mark Lodato; +Cc: git, Junio C Hamano Mark Lodato wrote: > --- a/Documentation/git-http-fetch.txt > +++ b/Documentation/git-http-fetch.txt > @@ -8,7 +8,7 @@ git-http-fetch - Download from a remote git repository via HTTP > > SYNOPSIS > -------- > -'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url> > +'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit-id> <url> > > DESCRIPTION > ----------- > @@ -16,7 +16,7 @@ Downloads a remote git repository via HTTP. > > OPTIONS > ------- > -commit-id:: > +<commit-id>:: > Either the hash or the filename under [URL]/refs/ to > pull. Does this mean the same thing as "commit id" in other manpages? ^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 5/8] grep docs: grep accepts a <tree-ish>, not a <tree> 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato ` (3 preceding siblings ...) 2010-12-18 5:38 ` [PATCH 4/8] http-fetch docs: use <commit-id> consistently Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 5:38 ` [PATCH 6/8] docs: use <tree> instead of <tree-ish> Mark Lodato ` (3 subsequent siblings) 8 siblings, 0 replies; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato Also document that -p accepts a <commit> in the usage message. Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-grep.txt | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index dab0a78..54ea24a 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -22,7 +22,7 @@ SYNOPSIS [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] - [--cached | --no-index | <tree>...] + [--cached | --no-index | <tree-ish>...] [--] [<pathspec>...] DESCRIPTION @@ -176,7 +176,7 @@ OPTIONS Do not output matched lines; instead, exit with status 0 when there is a match and with non-zero status when there isn't. -<tree>...:: +<tree-ish>...:: Instead of searching tracked files in the working tree, search blobs in the given trees. -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* [PATCH 6/8] docs: use <tree> instead of <tree-ish> 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato ` (4 preceding siblings ...) 2010-12-18 5:38 ` [PATCH 5/8] grep docs: grep accepts a <tree-ish>, not a <tree> Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 8:35 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 7/8] docs: use <commit> instead of <commit-ish> Mark Lodato ` (2 subsequent siblings) 8 siblings, 1 reply; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato No git command, besides commit-tree, accepts only a tree and not a tree-ish, so let us remove the latter term from common usage in the documentation in order to reduce the amount of jargon. The term "tree-ish" was left in the following situations: - all comments in the code - situations where "tree-ish" is being contrasted to "tree" - error messages, to prevent porcelains from changing - tests - the glossary Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/RelNotes/1.6.2.4.txt | 2 +- Documentation/diff-format.txt | 10 +++++----- Documentation/diff-generate-patch.txt | 2 +- Documentation/git-archive.txt | 4 ++-- Documentation/git-cat-file.txt | 2 +- Documentation/git-checkout.txt | 16 ++++++++-------- Documentation/git-commit-tree.txt | 3 ++- Documentation/git-diff-index.txt | 4 ++-- Documentation/git-diff-tree.txt | 14 +++++++------- Documentation/git-grep.txt | 4 ++-- Documentation/git-ls-files.txt | 6 +++--- Documentation/git-ls-tree.txt | 6 +++--- Documentation/git-merge-tree.txt | 2 +- Documentation/git-read-tree.txt | 10 +++++----- Documentation/git-svn.txt | 6 +++--- Documentation/git-tar-tree.txt | 4 ++-- Documentation/git.txt | 11 ++++------- Documentation/gitcli.txt | 4 ++-- Documentation/gittutorial-2.txt | 6 ++---- archive.c | 4 ++-- builtin/diff-index.c | 2 +- builtin/diff-tree.c | 2 +- builtin/ls-files.c | 4 ++-- builtin/ls-tree.c | 2 +- builtin/read-tree.c | 2 +- builtin/tar-tree.c | 2 +- git-svn.perl | 6 +++--- t/t4100/t-apply-3.patch | 8 ++++---- t/t4100/t-apply-7.patch | 8 ++++---- 29 files changed, 76 insertions(+), 80 deletions(-) diff --git a/Documentation/RelNotes/1.6.2.4.txt b/Documentation/RelNotes/1.6.2.4.txt index f4bf1d0..0e36786 100644 --- a/Documentation/RelNotes/1.6.2.4.txt +++ b/Documentation/RelNotes/1.6.2.4.txt @@ -13,7 +13,7 @@ Fixes since v1.6.2.3 * "git-add -p" lacked a way to say "q"uit to refuse staging any hunks for the remaining paths. You had to say "d" and then ^C. -* "git-checkout <tree-ish> <submodule>" did not update the index entry at +* "git-checkout <tree> <submodule>" did not update the index entry at the named path; it now does. * "git-fast-export" choked when seeing a tag that does not point at commit. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 15c7e79..83272a0 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -7,13 +7,13 @@ The raw output format from "git-diff-index", "git-diff-tree", These commands all compare two sets of things; what is compared differs: -git-diff-index <tree-ish>:: - compares the <tree-ish> and the files on the filesystem. +git-diff-index <tree>:: + compares the <tree> and the files on the filesystem. -git-diff-index --cached <tree-ish>:: - compares the <tree-ish> and the index. +git-diff-index --cached <tree>:: + compares the <tree> and the index. -git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]:: +git-diff-tree [-r] <tree-1> <tree-2> [<pattern>...]:: compares the trees named by the two arguments. git-diff-files [<pattern>...]:: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 3ac2bea..e0802de 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -131,7 +131,7 @@ The `mode <mode>,<mode>..<mode>` line appears only if at least one of the <mode> is different from the rest. Extended headers with information about detected contents movement (renames and copying detection) are designed to work with diff of two -<tree-ish> and are not used by combined diff format. +<tree> and are not used by combined diff format. 3. It is followed by two-line from-file/to-file header diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 4163a1b..bb4943f 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] [-o | --output=<file>] [--worktree-attributes] - [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> + [--remote=<repo> [--exec=<git-upload-archive>]] <tree> [<path>...] DESCRIPTION @@ -70,7 +70,7 @@ OPTIONS Used with --remote to specify the path to the 'git-upload-archive' on the remote side. -<tree-ish>:: +<tree>:: The tree or commit to produce an archive for. <path>:: diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 544ba7b..4861007 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -54,7 +54,7 @@ OPTIONS --textconv:: Show the content as transformed by a textconv filter. In this case, - <object> has be of the form <treeish>:<path>, or :<path> in order + <object> has be of the form <tree>:<path>, or :<path> in order to apply the filter to the content recorded in the index at <path>. --batch:: diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 880763d..0199e10 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -10,8 +10,8 @@ SYNOPSIS [verse] 'git checkout' [-q] [-f] [-m] [<branch>] 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... -'git checkout' --patch [<tree-ish>] [--] [<paths>...] +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree>] [--] <paths>... +'git checkout' --patch [<tree>] [--] [<paths>...] DESCRIPTION ----------- @@ -43,14 +43,14 @@ $ git checkout <branch> that is to say, the branch is not reset/created unless "git checkout" is successful. -'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...:: +'git checkout' [--patch] [<tree>] [--] <pathspec>...:: When <paths> or `--patch` are given, 'git checkout' does *not* switch branches. It updates the named paths in the working tree - from the index file or from a named <tree-ish> (most often a + from the index file or from a named <tree> (most often a commit). In this case, the `-b` and `--track` options are meaningless and giving either of them results in an error. The - <tree-ish> argument can be used to specify a specific tree-ish + <tree> argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. + @@ -169,9 +169,9 @@ the conflicted merge in the specified paths. -p:: --patch:: Interactively select hunks in the difference between the - <tree-ish> (or the index, if unspecified) and the working + <tree> (or the index, if unspecified) and the working tree. The chosen hunks are then applied in reverse to the - working tree (and if a <tree-ish> was specified, the index). + working tree (and if a <tree> was specified, the index). + This means that you can use `git checkout -p` to selectively discard edits from your current working tree. @@ -198,7 +198,7 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. The name of a commit at which to start the new branch; see linkgit:git-branch[1] for details. Defaults to HEAD. -<tree-ish>:: +<tree>:: Tree to checkout from (when paths are given). If not specified, the index will be used. diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 5dcf427..92687d8 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -36,7 +36,8 @@ state was. OPTIONS ------- <tree>:: - An existing tree object + An existing tree object. Unlike other git commands, this must + be an actual tree object, not a commit or tag. -p <parent commit>:: Each '-p' indicates the id of a parent commit object. diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 162cb74..c725357 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -8,7 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi SYNOPSIS -------- -'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] +'git diff-index' [-m] [--cached] [<common diff options>] <tree> [<path>...] DESCRIPTION ----------- @@ -22,7 +22,7 @@ OPTIONS ------- include::diff-options.txt[] -<tree-ish>:: +<tree>:: The id of a tree object to diff against. --cached:: diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 6b357a5..692d83b 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -11,13 +11,13 @@ SYNOPSIS [verse] 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r] [-c | --cc] [--root] [<common diff options>] - <tree-ish> [<tree-ish>] [<path>...] + <tree> [<tree>] [<path>...] DESCRIPTION ----------- Compares the content and mode of the blobs found via two tree objects. -If there is only one <tree-ish> given, the commit is compared with its parents +If there is only one <tree> given, the commit is compared with its parents (see --stdin below). Note that 'git diff-tree' can use the tree encapsulated in a commit object. @@ -26,7 +26,7 @@ OPTIONS ------- include::diff-options.txt[] -<tree-ish>:: +<tree>:: The id of a tree object. <path>...:: @@ -48,7 +48,7 @@ include::diff-options.txt[] --stdin:: When '--stdin' is specified, the command does not take - <tree-ish> arguments from the command line. Instead, it + <tree> arguments from the command line. Instead, it reads lines containing <sha1>s: either two trees, one commit, or multiple commits from its standard input. (Use a single space as separator.) @@ -91,7 +91,7 @@ include::pretty-options.txt[] -c:: This flag changes the way a merge commit is displayed (which means it is useful only when the command is given - one <tree-ish>, or '--stdin'). It shows the differences + one <tree>, or '--stdin'). It shows the differences from each of the parents to the merge result simultaneously instead of showing pairwise diff between a parent and the result one at a time (which is what the '-m' option does). @@ -121,13 +121,13 @@ Limiting Output If you're only interested in differences in a subset of files, for example some architecture-specific files, you might do: - git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 + git diff-tree -r <tree> <tree> arch/ia64 include/asm-ia64 and it will only show you what changed in those two directories. Or if you are searching for what changed in just `kernel/sched.c`, just do - git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c + git diff-tree -r <tree> <tree> kernel/sched.c and it will ignore all differences to other files. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 54ea24a..dab0a78 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -22,7 +22,7 @@ SYNOPSIS [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] - [--cached | --no-index | <tree-ish>...] + [--cached | --no-index | <tree>...] [--] [<pathspec>...] DESCRIPTION @@ -176,7 +176,7 @@ OPTIONS Do not output matched lines; instead, exit with status 0 when there is a match and with non-zero status when there isn't. -<tree-ish>...:: +<tree>...:: Instead of searching tracked files in the working tree, search blobs in the given trees. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 86abd13..1192859 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -16,7 +16,7 @@ SYNOPSIS [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] [--exclude-standard] - [--error-unmatch] [--with-tree=<tree-ish>] + [--error-unmatch] [--with-tree=<tree>] [--full-name] [--abbrev] [--] [<file>...] DESCRIPTION @@ -99,11 +99,11 @@ OPTIONS If any <file> does not appear in the index, treat this as an error (return 1). ---with-tree=<tree-ish>:: +--with-tree=<tree>:: When using --error-unmatch to expand the user supplied <file> (i.e. path pattern) arguments to paths, pretend that paths which were removed in the index since the - named <tree-ish> are still present. Using this option + named <tree> are still present. Using this option with `-s` or `-u` options does not make any sense. -t:: diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 76ed625..b0bb226 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git ls-tree' [-d] [-r] [-t] [-l] [-z] [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]] - <tree-ish> [<path>...] + <tree> [<path>...] DESCRIPTION ----------- @@ -35,8 +35,8 @@ in the current working directory. Note that: OPTIONS ------- -<tree-ish>:: - Id of a tree-ish. +<tree>:: + The id of a tree object. -d:: Show only the named tree entry itself, not its children. diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index f869a7f..0a9eb0d 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -Reads three treeish, and output trivial merge results and +Reads three <tree>s, and output trivial merge results and conflicting stages to the standard output. This is similar to what three-way 'git read-tree -m' does, but instead of storing the results in the index, the command outputs the entries to the diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index e88e9c2..24d9b87 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -11,12 +11,12 @@ SYNOPSIS 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--index-output=<file>] [--no-sparse-checkout] - (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) + (--empty | <tree-1> [<tree-2> [<tree-3>]]) DESCRIPTION ----------- -Reads the tree information given by <tree-ish> into the index, +Reads the tree information given by <tree> into the index, but does not actually *update* any of the files it "caches". (see: linkgit:git-checkout-index[1]) @@ -77,7 +77,7 @@ OPTIONS --prefix=<prefix>/:: Keep the current index contents, and read the contents - of named tree-ish under directory at `<prefix>`. The + of named tree under directory at `<prefix>`. The original index file cannot have anything at the path `<prefix>` itself, and have nothing in `<prefix>/` directory. Note that the `<prefix>/` value must end @@ -118,7 +118,7 @@ OPTIONS Instead of reading tree object(s) into the index, just empty it. -<tree-ish#>:: +<tree-#>:: The id of the tree object(s) to be read/merged. @@ -278,7 +278,7 @@ merge. The different stages represent the "result tree" (stage 0, aka you are trying to merge (stage 2 and 3 respectively). The order of stages 1, 2 and 3 (hence the order of three -<tree-ish> command line arguments) are significant when you +<tree> command line arguments) are significant when you start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 139d314..665a107 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -314,8 +314,8 @@ Any other arguments are passed directly to 'git log' 'find-rev':: When given an SVN revision number of the form 'rN', returns the corresponding git commit hash (this can optionally be followed by a - tree-ish to specify which branch should be searched). When given a - tree-ish, returns the corresponding SVN revision number. + <tree> to specify which branch should be searched). When given a + <tree>, returns the corresponding SVN revision number. 'set-tree':: You should consider using 'dcommit' instead of this command. @@ -345,7 +345,7 @@ Any other arguments are passed directly to 'git log' for use after commands like "git checkout" or "git reset". 'commit-diff':: - Commits the diff of two tree-ish arguments from the + Commits the diff of two <tree> arguments from the command-line. This command does not rely on being inside an `git svn init`-ed repository. This command takes three arguments, (a) the original tree to diff against, (b) the new tree result, (c) the diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 3c786bd..6d0a746 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -8,7 +8,7 @@ git-tar-tree - Create a tar archive of the files in the named tree object SYNOPSIS -------- -'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ] +'git tar-tree' [--remote=<repo>] <tree> [ <base> ] DESCRIPTION ----------- @@ -29,7 +29,7 @@ It can be extracted using 'git get-tar-commit-id'. OPTIONS ------- -<tree-ish>:: +<tree>:: The tree or commit to produce tar archive for. If it is the object name of a commit object. diff --git a/Documentation/git.txt b/Documentation/git.txt index 7929739..376397c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -469,17 +469,14 @@ Identifier Terminology Indicates a blob object name. <tree>:: - Indicates a tree object name. + Indicates a tree object name, or the name of tag or commit that points + at a tree. A command that takes a <tree> argument ultimately + wants to operate on a tree object but automatically dereferences + tag and commit objects until it finds a tree. <commit>:: Indicates a commit object name. -<tree-ish>:: - Indicates a tree, commit or tag object name. A - command that takes a <tree-ish> argument ultimately wants to - operate on a <tree> object but automatically dereferences - <commit> and <tag> objects that point at a <tree>. - <commit-ish>:: Indicates a commit or tag object name. A command that takes a <commit-ish> argument ultimately wants to diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index eb65dcf..eefee3d 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -15,8 +15,8 @@ DESCRIPTION This manual describes the convention used throughout git CLI. -Many commands take revisions (most often "commits", but sometimes -"tree-ish", depending on the context and command) and paths as their +Many commands take revisions (most often <commit>s, but sometimes +<tree>s, depending on the context and command) and paths as their arguments. Here are the rules: * Revisions come first and then paths. diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index 7fe5848..218b94d 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -209,10 +209,8 @@ Note, by the way, that lots of commands take a tree as an argument. But as we can see above, a tree can be referred to in many different ways--by the SHA1 name for that tree, by the name of a commit that refers to the tree, by the name of a branch whose head refers to that -tree, etc.--and most such commands can accept any of these names. - -In command synopses, the word "tree-ish" is sometimes used to -designate such an argument. +tree, etc.--and all such commands can accept any of these names unless +otherwise stated. The index file -------------- diff --git a/archive.c b/archive.c index 1944ed4..50fb77e 100644 --- a/archive.c +++ b/archive.c @@ -7,9 +7,9 @@ #include "unpack-trees.h" static char const * const archive_usage[] = { - "git archive [options] <tree-ish> [<path>...]", + "git archive [options] <tree> [<path>...]", "git archive --list", - "git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]", + "git archive --remote <repo> [--exec <cmd>] [options] <tree> [<path>...]", "git archive --remote <repo> [--exec <cmd>] --list", NULL }; diff --git a/builtin/diff-index.c b/builtin/diff-index.c index 2eb32bd..605e326 100644 --- a/builtin/diff-index.c +++ b/builtin/diff-index.c @@ -7,7 +7,7 @@ static const char diff_cache_usage[] = "git diff-index [-m] [--cached] " -"[<common diff options>] <tree-ish> [<path>...]" +"[<common diff options>] <tree> [<path>...]" COMMON_DIFF_OPTIONS_HELP; int cmd_diff_index(int argc, const char **argv, const char *prefix) diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c index 0d2a3e9..d0ea2db 100644 --- a/builtin/diff-tree.c +++ b/builtin/diff-tree.c @@ -88,7 +88,7 @@ static int diff_tree_stdin(char *line) static const char diff_tree_usage[] = "git diff-tree [--stdin] [-m] [-c] [--cc] [-s] [-v] [--pretty] [-t] [-r] [--root] " -"[<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\n" +"[<common diff options>] <tree> [<tree>] [<path>...]\n" " -r diff recursively\n" " --root include the initial commit as diff against /dev/null\n" COMMON_DIFF_OPTIONS_HELP; diff --git a/builtin/ls-files.c b/builtin/ls-files.c index fb2d5f4..8592fd0 100644 --- a/builtin/ls-files.c +++ b/builtin/ls-files.c @@ -523,8 +523,8 @@ int cmd_ls_files(int argc, const char **argv, const char *cmd_prefix) PARSE_OPT_NOARG | PARSE_OPT_NONEG, NULL }, OPT_BOOLEAN(0, "error-unmatch", &error_unmatch, "if any <file> is not in the index, treat this as an error"), - OPT_STRING(0, "with-tree", &with_tree, "tree-ish", - "pretend that paths removed since <tree-ish> are still present"), + OPT_STRING(0, "with-tree", &with_tree, "tree", + "pretend that paths removed since <tree> are still present"), OPT__ABBREV(&abbrev), OPT_BOOLEAN(0, "debug", &debug_mode, "show debugging data"), OPT_END() diff --git a/builtin/ls-tree.c b/builtin/ls-tree.c index f73e6bd..a810d9a 100644 --- a/builtin/ls-tree.c +++ b/builtin/ls-tree.c @@ -24,7 +24,7 @@ static int chomp_prefix; static const char *ls_tree_prefix; static const char * const ls_tree_usage[] = { - "git ls-tree [<options>] <tree-ish> [<path>...]", + "git ls-tree [<options>] <tree> [<path>...]", NULL }; diff --git a/builtin/read-tree.c b/builtin/read-tree.c index 73c89ed..064711a 100644 --- a/builtin/read-tree.c +++ b/builtin/read-tree.c @@ -33,7 +33,7 @@ static int list_tree(unsigned char *sha1) } static const char * const read_tree_usage[] = { - "git read-tree [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])", + "git read-tree [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-1> [<tree-2> [<tree-3>]])", NULL }; diff --git a/builtin/tar-tree.c b/builtin/tar-tree.c index 3f1e701..abdcd0b 100644 --- a/builtin/tar-tree.c +++ b/builtin/tar-tree.c @@ -8,7 +8,7 @@ #include "quote.h" static const char tar_tree_usage[] = -"git tar-tree [--remote=<repo>] <tree-ish> [basedir]\n" +"git tar-tree [--remote=<repo>] <tree> [basedir]\n" "*** Note that this command is now deprecated; use \"git archive\" instead."; static const char builtin_get_tar_commit_id_usage[] = diff --git a/git-svn.perl b/git-svn.perl index 177dd25..96197c0 100755 --- a/git-svn.perl +++ b/git-svn.perl @@ -172,7 +172,7 @@ my %cmd = ( 'username=s' => \$Git::SVN::Prompt::_username, 'commit-url=s' => \$_commit_url } ], 'set-tree' => [ \&cmd_set_tree, - "Set an SVN repository to a git tree-ish", + "Set an SVN repository to a git tree", { 'stdin' => \$_stdin, %cmt_opts, %fc_opts, } ], 'create-ignore' => [ \&cmd_create_ignore, 'Create a .gitignore per svn:ignore', @@ -215,7 +215,7 @@ my %cmd = ( 'pager=s' => \$Git::SVN::Log::pager } ], 'find-rev' => [ \&cmd_find_rev, - "Translate between SVN revision numbers and tree-ish", + "Translate between SVN revision numbers and trees", {} ], 'rebase' => [ \&cmd_rebase, "Fetch and rebase your working directory", { 'merge|m|M' => \$_merge, @@ -1002,7 +1002,7 @@ sub cmd_multi_fetch { sub cmd_commit_diff { my ($ta, $tb, $url) = @_; my $usage = "Usage: $0 commit-diff -r<revision> ". - "<tree-ish> <tree-ish> [<URL>]"; + "<tree> <tree> [<URL>]"; fatal($usage) if (!defined $ta || !defined $tb); my $svn_path = ''; if (!defined $url) { diff --git a/t/t4100/t-apply-3.patch b/t/t4100/t-apply-3.patch index 90cdbaa..c702866 100644 --- a/t/t4100/t-apply-3.patch +++ b/t/t4100/t-apply-3.patch @@ -12,8 +12,8 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt SYNOPSIS -------- --'git-ls-tree' [-r] [-z] <tree-ish> [paths...] -+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...] +-'git-ls-tree' [-r] [-z] <tree> [paths...] ++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...] DESCRIPTION ----------- @@ -24,7 +24,7 @@ diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt OPTIONS ------- - <tree-ish>:: + <tree>:: Id of a tree. +-d:: @@ -485,7 +485,7 @@ dissimilarity index 82% +} + +static const char *ls_tree_usage = -+ "git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]"; ++ "git-ls-tree [-d] [-r] [-z] <tree> [path...]"; + +int main(int argc, char **argv) +{ diff --git a/t/t4100/t-apply-7.patch b/t/t4100/t-apply-7.patch index 07c6589..bf8737b 100644 --- a/t/t4100/t-apply-7.patch +++ b/t/t4100/t-apply-7.patch @@ -11,8 +11,8 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt SYNOPSIS -------- --'git-ls-tree' [-r] [-z] <tree-ish> [paths...] -+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...] +-'git-ls-tree' [-r] [-z] <tree> [paths...] ++'git-ls-tree' [-d] [-r] [-z] <tree> [paths...] DESCRIPTION ----------- @@ -23,7 +23,7 @@ diff a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt OPTIONS ------- - <tree-ish>:: + <tree>:: Id of a tree. +-d:: @@ -415,7 +415,7 @@ diff a/ls-tree.c b/ls-tree.c -static const char *ls_tree_usage = "git-ls-tree [-r] [-z] <key> [paths...]"; +static const char *ls_tree_usage = -+ "git-ls-tree [-d] [-r] [-z] <tree-ish> [path...]"; ++ "git-ls-tree [-d] [-r] [-z] <tree> [path...]"; int main(int argc, char **argv) { -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH 6/8] docs: use <tree> instead of <tree-ish> 2010-12-18 5:38 ` [PATCH 6/8] docs: use <tree> instead of <tree-ish> Mark Lodato @ 2010-12-18 8:35 ` Jonathan Nieder 0 siblings, 0 replies; 19+ messages in thread From: Jonathan Nieder @ 2010-12-18 8:35 UTC (permalink / raw) To: Mark Lodato; +Cc: git, Junio C Hamano Mark Lodato wrote: > The term "tree-ish" was left in the following situations: > - all comments in the code > - situations where "tree-ish" is being contrasted to "tree" > - error messages, to prevent porcelains from changing Nit: to prevent plumbing from changing? Or to prevent porcelains from having to change in response to changes in plumbing? > --- a/Documentation/RelNotes/1.6.2.4.txt > +++ b/Documentation/RelNotes/1.6.2.4.txt > @@ -13,7 +13,7 @@ Fixes since v1.6.2.3 > * "git-add -p" lacked a way to say "q"uit to refuse staging any hunks for > the remaining paths. You had to say "d" and then ^C. > > -* "git-checkout <tree-ish> <submodule>" did not update the index entry at > +* "git-checkout <tree> <submodule>" did not update the index entry at > the named path; it now does. Is changing release notes for historical releases like this a good idea? (It not clear to me either way.) > --- a/Documentation/diff-format.txt > +++ b/Documentation/diff-format.txt > @@ -7,13 +7,13 @@ The raw output format from "git-diff-index", "git-diff-tree", > These commands all compare two sets of things; what is > compared differs: > > -git-diff-index <tree-ish>:: > - compares the <tree-ish> and the files on the filesystem. > +git-diff-index <tree>:: > + compares the <tree> and the files on the filesystem. Unrelated: we ought to remove the dash after "git" here. (Thanks for a reminder.) > --- a/Documentation/git-archive.txt > +++ b/Documentation/git-archive.txt > @@ -11,7 +11,7 @@ SYNOPSIS > [verse] > 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] > [-o | --output=<file>] [--worktree-attributes] > - [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> > + [--remote=<repo> [--exec=<git-upload-archive>]] <tree> > [<path>...] > > DESCRIPTION > @@ -70,7 +70,7 @@ OPTIONS > Used with --remote to specify the path to the > 'git-upload-archive' on the remote side. > > -<tree-ish>:: > +<tree>:: > The tree or commit to produce an archive for. In this case, it might be less confusing to explicitly say (<commit> | <tree>), since the behavior is: . commit id and timestamp recorded from commit if a commit is used . no commit id and time of invocation (!) recorded if a tree is used directly meaning "git archive commit" and "git archive commit^{tree}" do not always have the same behavior. > --- a/Documentation/git-commit-tree.txt > +++ b/Documentation/git-commit-tree.txt > @@ -36,7 +36,8 @@ state was. > OPTIONS > ------- > <tree>:: > - An existing tree object > + An existing tree object. Unlike other git commands, this must > + be an actual tree object, not a commit or tag. Maybe it would be worth dropping that constraint (in the code) for simplicity? If not, it would be nice to give a fuller explanation, something to this effect: An existing tree object. To [reason here], the argument will not be automatically dereferenced to a tree if it names a commit or tag; you must instead specify the tree explicitly, for example by ending the argument with ^{tree}. Wording could surely be improved. > --- a/Documentation/git-diff-index.txt > +++ b/Documentation/git-diff-index.txt > @@ -8,7 +8,7 @@ git-diff-index - Compares content and mode of blobs between the index and reposi > > SYNOPSIS > -------- > -'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] > +'git diff-index' [-m] [--cached] [<common diff options>] <tree> [<path>...] > > DESCRIPTION > ----------- > @@ -22,7 +22,7 @@ OPTIONS > ------- > include::diff-options.txt[] > > -<tree-ish>:: > +<tree>:: > The id of a tree object to diff against. Is an arbitrary tree name okay, or only tree ids? > --- a/Documentation/git-ls-tree.txt > +++ b/Documentation/git-ls-tree.txt > @@ -35,8 +35,8 @@ in the current working directory. Note that: > > OPTIONS > ------- > -<tree-ish>:: > - Id of a tree-ish. > +<tree>:: > + The id of a tree object. Likewise. > --- a/Documentation/git-merge-tree.txt > +++ b/Documentation/git-merge-tree.txt > @@ -12,7 +12,7 @@ SYNOPSIS > > DESCRIPTION > ----------- > -Reads three treeish, and output trivial merge results and > +Reads three <tree>s, and output trivial merge results and Since the string "<tree>" does not appear in the synopsis, it seems odd to mention it here. Maybe it would be clearer to say: SYNOPSIS git merge-tree <base-tree> <branch1> <branch2> DESCRIPTION Reads three trees and outputs trivial merge results and conflicting entries to the standard output. This or (though I like the previous synopsis much more) SYNOPSIS git merge-tree <tree> <tree> <tree> DESCRIPTION Reads three trees and outputs trivial merge results and conflicting entries to the standard output. The arguments are in the same order as those for "git read-tree": the first represents the original (basis) state and the other two represent versions with improvements that need to be merged. This > --- a/Documentation/git-read-tree.txt > +++ b/Documentation/git-read-tree.txt > @@ -118,7 +118,7 @@ OPTIONS > Instead of reading tree object(s) into the index, just empty > it. > > -<tree-ish#>:: > +<tree-#>:: > The id of the tree object(s) to be read/merged. Just "The tree objects to be read or merged", not necessarily named by id, right? > --- a/Documentation/git-svn.txt > +++ b/Documentation/git-svn.txt > @@ -314,8 +314,8 @@ Any other arguments are passed directly to 'git log' > 'find-rev':: > When given an SVN revision number of the form 'rN', returns the > corresponding git commit hash (this can optionally be followed by a > - tree-ish to specify which branch should be searched). When given a > - tree-ish, returns the corresponding SVN revision number. > + <tree> to specify which branch should be searched). When given a > + <tree>, returns the corresponding SVN revision number. The placeholder <tree> sounds odd in descriptive text like this. Maybe: If the first argument is of the form 'rN', prints the corresponding git commit id. An optional second argument can name a commit, to limit the search to commits accessible from that commit. Otherwise, the first (and only) argument is interpreted as a git tree name and this subcommand prints the corresponding SVN revision number. > @@ -345,7 +345,7 @@ Any other arguments are passed directly to 'git log' > for use after commands like "git checkout" or "git reset". > > 'commit-diff':: > - Commits the diff of two tree-ish arguments from the > + Commits the diff of two <tree> arguments from the Likewise. "Two trees named on the command line" should be clear. > --- a/Documentation/git-tar-tree.txt > +++ b/Documentation/git-tar-tree.txt > @@ -29,7 +29,7 @@ It can be extracted using 'git get-tar-commit-id'. > OPTIONS > ------- > > -<tree-ish>:: > +<tree>:: > The tree or commit to produce tar archive for. If it is > the object name of a commit object. Huh? (Not a problem introduced by this patch, but...) > --- a/Documentation/git.txt > +++ b/Documentation/git.txt > @@ -469,17 +469,14 @@ Identifier Terminology > Indicates a blob object name. > > <tree>:: > - Indicates a tree object name. > + Indicates a tree object name, or the name of tag or commit that points > + at a tree. A command that takes a <tree> argument ultimately > + wants to operate on a tree object but automatically dereferences > + tag and commit objects until it finds a tree. > > <commit>:: > Indicates a commit object name. > > -<tree-ish>:: > - Indicates a tree, commit or tag object name. A > - command that takes a <tree-ish> argument ultimately wants to > - operate on a <tree> object but automatically dereferences > - <commit> and <tag> objects that point at a <tree>. > - I first read the new description as Indicates a tree name, or the name of a tag or commit ... which seemed odd --- this always is a tree name. Maybe <tree>:: Indicates a parameter specifying a tree, commit, or tag object. A command that takes a <tree> argument ultimately wants to operate on a tree object so it automatically dereferences tag and commit objects until it finds a tree. Thanks for eliminating the confusing <commit>, <tag>, etc markup. > --- a/Documentation/gitcli.txt > +++ b/Documentation/gitcli.txt > @@ -15,8 +15,8 @@ DESCRIPTION > > This manual describes the convention used throughout git CLI. > > -Many commands take revisions (most often "commits", but sometimes > -"tree-ish", depending on the context and command) and paths as their > +Many commands take revisions (most often <commit>s, but sometimes > +<tree>s, depending on the context and command) and paths as their Maybe Many commands take revisions (most often commits but sometimes trees, depending on the context and command) and paths as their arguments. Here are the rules: to avoid emphasizing a technicality. > --- a/Documentation/gittutorial-2.txt > +++ b/Documentation/gittutorial-2.txt > @@ -209,10 +209,8 @@ Note, by the way, that lots of commands take a tree as an argument. > But as we can see above, a tree can be referred to in many different > ways--by the SHA1 name for that tree, by the name of a commit that > refers to the tree, by the name of a branch whose head refers to that > -tree, etc.--and most such commands can accept any of these names. > - > -In command synopses, the word "tree-ish" is sometimes used to > -designate such an argument. > +tree, etc.--and all such commands can accept any of these names unless > +otherwise stated. ... otherwise stated in the manual pages? > --- a/t/t4100/t-apply-3.patch > +++ b/t/t4100/t-apply-3.patch [...] > --- a/t/t4100/t-apply-7.patch > +++ b/t/t4100/t-apply-7.patch [...] These last two aren't worth it, I think. :) I very much like this change. Ideally it should be possible to deal with some of the nontrivial parts first in separate patches before a last trivial one that does not do much more than change tree-ish -> tree. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 7/8] docs: use <commit> instead of <commit-ish> 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato ` (5 preceding siblings ...) 2010-12-18 5:38 ` [PATCH 6/8] docs: use <tree> instead of <tree-ish> Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 8:39 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 8/8] describe docs: note that <commit> is optional Mark Lodato 2010-12-18 8:49 ` [PATCHv2 0/8] docs: use metavariables consistently Jonathan Nieder 8 siblings, 1 reply; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato No git command accepts only a commit and not a commit-ish, so let us remove the latter term from common usage in the documentation in order to reduce the amount of jargon. Note that the terms `committish' and `commit-ish' were both previously used. The "ish" terms were left in comments and were added to the glossary. Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-describe.txt | 14 +++++++------- Documentation/git-fast-import.txt | 22 +++++++++++----------- Documentation/git-name-rev.txt | 2 +- Documentation/git-rebase.txt | 2 +- Documentation/git.txt | 11 ++++------- Documentation/gitcli.txt | 2 +- Documentation/glossary-content.txt | 4 ++++ builtin/describe.c | 4 ++-- builtin/revert.c | 4 ++-- contrib/examples/git-reset.sh | 2 +- contrib/examples/git-revert.sh | 4 ++-- 11 files changed, 36 insertions(+), 35 deletions(-) diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 02e015a..ad173ed 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- [verse] -'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>... +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit>... 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] DESCRIPTION @@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- -<committish>...:: - Committish object names to describe. +<commit>...:: + Commit object names to describe. --dirty[=<mark>]:: Describe the working tree. @@ -57,7 +57,7 @@ OPTIONS --candidates=<n>:: Instead of considering only the 10 most recent tags as - candidates to describe the input committish consider + candidates to describe the input commit consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. An <n> of 0 will cause only exact matches to be output. @@ -139,7 +139,7 @@ be sufficient to disambiguate these commits. SEARCH STRATEGY --------------- -For each committish supplied, 'git describe' will first look for +For each commit supplied, 'git describe' will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match @@ -148,10 +148,10 @@ is found, its name will be output and searching will stop. If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an -abbreviation of the input committish's SHA1. +abbreviation of the input commit's SHA1. If multiple tags were found during the walk then the tag which -has the fewest commits different from the input committish will be +has the fewest commits different from the input commit will be selected and output. Here fewest commits different is defined as the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index f56dfca..0509213 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -350,8 +350,8 @@ change to the project. ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? 'committer' (SP <name>)? SP LT <email> GT SP <when> LF data - ('from' SP <committish> LF)? - ('merge' SP <committish> LF)? + ('from' SP <commit> LF)? + ('merge' SP <commit> LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* LF? .... @@ -428,9 +428,9 @@ as the current commit on that branch is automatically assumed to be the first ancestor of the new commit. As `LF` is not valid in a Git refname or SHA-1 expression, no -quoting or escaping syntax is supported within `<committish>`. +quoting or escaping syntax is supported within `<commit>`. -Here `<committish>` is any of the following: +Here `<commit>` is any of the following: * The name of an existing branch already in fast-import's internal branch table. If fast-import doesn't know the name, it's treated as a SHA-1 @@ -475,7 +475,7 @@ additional ancestors (forming a 16-way merge). For this reason it is suggested that frontends do not use more than 15 `merge` commands per commit; 16, if starting a new, empty branch. -Here `<committish>` is any of the commit specification expressions +Here `<commit>` is any of the commit specification expressions also accepted by `from` (see above). `filemodify` @@ -649,7 +649,7 @@ External data format:: commit that is to be annotated. + .... - 'N' SP <dataref> SP <committish> LF + 'N' SP <dataref> SP <commit> LF .... + Here `<dataref>` can be either a mark reference (`:<idnum>`) @@ -662,13 +662,13 @@ Inline data format:: command. + .... - 'N' SP 'inline' SP <committish> LF + 'N' SP 'inline' SP <commit> LF data .... + See below for a detailed description of the `data` command. -In both formats `<committish>` is any of the commit specification +In both formats `<commit>` is any of the commit specification expressions also accepted by `from` (see above). `mark` @@ -699,7 +699,7 @@ lightweight (non-annotated) tags see the `reset` command below. .... 'tag' SP <name> LF - 'from' SP <committish> LF + 'from' SP <commit> LF 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF data .... @@ -744,11 +744,11 @@ branch from an existing commit without creating a new commit. .... 'reset' SP <ref> LF - ('from' SP <committish> LF)? + ('from' SP <commit> LF)? LF? .... -For a detailed description of `<ref>` and `<committish>` see above +For a detailed description of `<ref>` and `<commit>` see above under `commit` and `from`. The `LF` after the command is optional (it used to be required). diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 2108237..40af544 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git name-rev' [--tags] [--refs=<pattern>] - ( --all | --stdin | <committish>... ) + ( --all | --stdin | <commit>... ) DESCRIPTION ----------- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 96680c8..dbb5484 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -168,7 +168,7 @@ would result in the removal of commits F and G: This is useful if F and G were flawed in some way, or should not be part of topicA. Note that the argument to --onto and the <upstream> -parameter can be any valid commit-ish. +parameter can be any valid <commit>. In case of conflict, 'git rebase' will stop at the first problematic commit and leave conflict markers in the tree. You can use 'git diff' to locate diff --git a/Documentation/git.txt b/Documentation/git.txt index 376397c..734acbe 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -475,13 +475,10 @@ Identifier Terminology tag and commit objects until it finds a tree. <commit>:: - Indicates a commit object name. - -<commit-ish>:: - Indicates a commit or tag object name. A - command that takes a <commit-ish> argument ultimately wants to - operate on a <commit> object but automatically dereferences - <tag> objects that point at a <commit>. + Indicates a commit object name, or the name of a tag object that + points at a commit. A command that takes a <commit> argument + ultimately wants to operate on a commit object but automatically + dereferences tag objects until it finds a commit. <type>:: Indicates that an object type is required. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index eefee3d..b56e7c3 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -81,7 +81,7 @@ couple of magic command line options: + --------------------------------------------- $ git describe -h -usage: git describe [options] <committish>... +usage: git describe [options] <commit>... --contains find the tag that comes after the commit --debug debug search strategy on stderr diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f04b48e..40a1f11 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -82,6 +82,10 @@ to point at the new commit. to the top <<def_directory,directory>> of the stored revision. +[[def_commit-ish]][[def_committish]]commit-ish / committish:: + A <<def_ref,ref>> pointing to either a <<def_commit_object,commit + object>>, or a <<def_tag_object,tag object>> pointing to a tag or commit object. + [[def_core_git]]core git:: Fundamental data structures and utilities of git. Exposes only limited source code management tools. diff --git a/builtin/describe.c b/builtin/describe.c index 34a8031..4b5a217 100644 --- a/builtin/describe.c +++ b/builtin/describe.c @@ -12,7 +12,7 @@ #define MAX_TAGS (FLAG_BITS - 1) static const char * const describe_usage[] = { - "git describe [options] <committish>...", + "git describe [options] <commit>...", "git describe [options] --dirty", NULL }; @@ -462,7 +462,7 @@ int cmd_describe(int argc, const char **argv, const char *prefix) dirty = NULL; describe("HEAD", 1); } else if (dirty) { - die("--dirty is incompatible with committishes"); + die("--dirty is incompatible with commits"); } else { while (argc-- > 0) { describe(*argv++, argc == 0); diff --git a/builtin/revert.c b/builtin/revert.c index bb6e9e8..f00b6d6 100644 --- a/builtin/revert.c +++ b/builtin/revert.c @@ -27,12 +27,12 @@ */ static const char * const revert_usage[] = { - "git revert [options] <commit-ish>", + "git revert [options] <commit>", NULL }; static const char * const cherry_pick_usage[] = { - "git cherry-pick [options] <commit-ish>", + "git cherry-pick [options] <commit>", NULL }; diff --git a/contrib/examples/git-reset.sh b/contrib/examples/git-reset.sh index bafeb52..d287a80 100755 --- a/contrib/examples/git-reset.sh +++ b/contrib/examples/git-reset.sh @@ -2,7 +2,7 @@ # # Copyright (c) 2005, 2006 Linus Torvalds and Junio C Hamano # -USAGE='[--mixed | --soft | --hard] [<commit-ish>] [ [--] <paths>...]' +USAGE='[--mixed | --soft | --hard] [<commit>] [ [--] <paths>...]' SUBDIRECTORY_OK=Yes . git-sh-setup set_reflog_action "reset $*" diff --git a/contrib/examples/git-revert.sh b/contrib/examples/git-revert.sh index 60a05a8..0b6b029 100755 --- a/contrib/examples/git-revert.sh +++ b/contrib/examples/git-revert.sh @@ -9,12 +9,12 @@ case "$0" in test -t 0 && edit=-e replay= me=revert - USAGE='[--edit | --no-edit] [-n] <commit-ish>' ;; + USAGE='[--edit | --no-edit] [-n] <commit>' ;; *-cherry-pick* ) replay=t edit= me=cherry-pick - USAGE='[--edit] [-n] [-r] [-x] <commit-ish>' ;; + USAGE='[--edit] [-n] [-r] [-x] <commit>' ;; * ) echo >&2 "What are you talking about?" exit 1 ;; -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH 7/8] docs: use <commit> instead of <commit-ish> 2010-12-18 5:38 ` [PATCH 7/8] docs: use <commit> instead of <commit-ish> Mark Lodato @ 2010-12-18 8:39 ` Jonathan Nieder 0 siblings, 0 replies; 19+ messages in thread From: Jonathan Nieder @ 2010-12-18 8:39 UTC (permalink / raw) To: Mark Lodato; +Cc: git, Junio C Hamano Mark Lodato wrote: > --- a/Documentation/git-describe.txt > +++ b/Documentation/git-describe.txt > @@ -26,8 +26,8 @@ see the -a and -s options to linkgit:git-tag[1]. > > OPTIONS > ------- > -<committish>...:: > - Committish object names to describe. > +<commit>...:: > + Commit object names to describe. Or even Commits to describe. :) > --- a/Documentation/git-fast-import.txt > +++ b/Documentation/git-fast-import.txt > @@ -350,8 +350,8 @@ change to the project. > ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? > 'committer' (SP <name>)? SP LT <email> GT SP <when> LF > data > - ('from' SP <committish> LF)? > - ('merge' SP <committish> LF)? > + ('from' SP <commit> LF)? > + ('merge' SP <commit> LF)? As the audience of this manual page is people mostly familiar with other version control systems, it needs to be very explicit. Not sure what the best solution is, just pointing out the worry. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 8/8] describe docs: note that <commit> is optional 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato ` (6 preceding siblings ...) 2010-12-18 5:38 ` [PATCH 7/8] docs: use <commit> instead of <commit-ish> Mark Lodato @ 2010-12-18 5:38 ` Mark Lodato 2010-12-18 8:49 ` [PATCHv2 0/8] docs: use metavariables consistently Jonathan Nieder 8 siblings, 0 replies; 19+ messages in thread From: Mark Lodato @ 2010-12-18 5:38 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Mark Lodato Signed-off-by: Mark Lodato <lodatom@gmail.com> --- Documentation/git-describe.txt | 3 ++- Documentation/gitcli.txt | 2 +- builtin/describe.c | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index ad173ed..8006d59 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -9,7 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- [verse] -'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit>... +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit>...] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] DESCRIPTION @@ -28,6 +28,7 @@ OPTIONS ------- <commit>...:: Commit object names to describe. + If not given, defaults to HEAD. --dirty[=<mark>]:: Describe the working tree. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index b56e7c3..e57f88c 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -81,7 +81,7 @@ couple of magic command line options: + --------------------------------------------- $ git describe -h -usage: git describe [options] <commit>... +usage: git describe [options] [<commit>...] --contains find the tag that comes after the commit --debug debug search strategy on stderr diff --git a/builtin/describe.c b/builtin/describe.c index 4b5a217..82da278 100644 --- a/builtin/describe.c +++ b/builtin/describe.c @@ -12,7 +12,7 @@ #define MAX_TAGS (FLAG_BITS - 1) static const char * const describe_usage[] = { - "git describe [options] <commit>...", + "git describe [options] [<commit>...]", "git describe [options] --dirty", NULL }; -- 1.7.3.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCHv2 0/8] docs: use metavariables consistently 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato ` (7 preceding siblings ...) 2010-12-18 5:38 ` [PATCH 8/8] describe docs: note that <commit> is optional Mark Lodato @ 2010-12-18 8:49 ` Jonathan Nieder 2010-12-18 16:45 ` Mark Lodato 2010-12-18 20:27 ` Junio C Hamano 8 siblings, 2 replies; 19+ messages in thread From: Jonathan Nieder @ 2010-12-18 8:49 UTC (permalink / raw) To: Mark Lodato; +Cc: git, Junio C Hamano Mark Lodato wrote: > The biggest change is to drop the <tree-ish> and > <commit-ish> (or <committish>) notation and just use <tree> or <commit>, since > every command but commit-tree accepts tree-ishes and commit-ishes. Thanks. I think this will encourage UI consistency ("where you accept a tree, accepts commits and tags, too") as a side effect. > This is a rework of my earlier patch set from March [1], with the following > differences: > > - Drop the patch to commit-tree that makes it accept a tree-ish. Ah, missed this before. It is not clear to me why this difference --- is it just to be conservative about changing behavior? > [1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484 http://thread.gmane.org/gmane.comp.version-control.git/142078 ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCHv2 0/8] docs: use metavariables consistently 2010-12-18 8:49 ` [PATCHv2 0/8] docs: use metavariables consistently Jonathan Nieder @ 2010-12-18 16:45 ` Mark Lodato 2010-12-18 20:27 ` Junio C Hamano 1 sibling, 0 replies; 19+ messages in thread From: Mark Lodato @ 2010-12-18 16:45 UTC (permalink / raw) To: Jonathan Nieder; +Cc: git, Junio C Hamano On Sat, Dec 18, 2010 at 3:49 AM, Jonathan Nieder <jrnieder@gmail.com> wrote: > Mark Lodato wrote: >> This is a rework of my earlier patch set from March [1], with the following >> differences: >> >> - Drop the patch to commit-tree that makes it accept a tree-ish. > > Ah, missed this before. It is not clear to me why this difference --- > is it just to be conservative about changing behavior? Exactly. Junio replied to my original email saying he did not think this patch was unsafe, so if you think the patch is a good idea, I'll re-send it. >> [1] http://kerneltrap.org/mailarchive/git/2010/3/13/25484 > http://thread.gmane.org/gmane.comp.version-control.git/142078 As an aside, how do you actually find threads on gmane? I can't find anything on Google. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCHv2 0/8] docs: use metavariables consistently 2010-12-18 8:49 ` [PATCHv2 0/8] docs: use metavariables consistently Jonathan Nieder 2010-12-18 16:45 ` Mark Lodato @ 2010-12-18 20:27 ` Junio C Hamano 1 sibling, 0 replies; 19+ messages in thread From: Junio C Hamano @ 2010-12-18 20:27 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Mark Lodato, git Jonathan Nieder <jrnieder@gmail.com> writes: > Ah, missed this before. It is not clear to me why this difference --- > is it just to be conservative about changing behavior? Yes. It is clear from the context you mean its tree if you feed a commit to commit-tree, but the original intent of not dereferncing was to avoid mistakes by scripts and people, so you need to make a convincing argument that not derefencing does not help avoiding mistakes, and prove that nobody's script is relying on the current behaviour for type-checking purposes. ^ permalink raw reply [flat|nested] 19+ messages in thread
end of thread, other threads:[~2010-12-18 20:27 UTC | newest] Thread overview: 19+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2010-12-18 5:38 [PATCHv2 0/8] docs: use metavariables consistently Mark Lodato 2010-12-18 5:38 ` [PATCH 1/8] fsck docs: remove outdated and useless diagnostic Mark Lodato 2010-12-18 5:38 ` [PATCH 2/8] docs: use `...' instead of `*' for multiplicity Mark Lodato 2010-12-18 10:00 ` Jakub Narebski 2010-12-18 16:32 ` Mark Lodato 2010-12-18 5:38 ` [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID Mark Lodato 2010-12-18 7:47 ` Jonathan Nieder 2010-12-18 18:50 ` Junio C Hamano 2010-12-18 5:38 ` [PATCH 4/8] http-fetch docs: use <commit-id> consistently Mark Lodato 2010-12-18 7:51 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 5/8] grep docs: grep accepts a <tree-ish>, not a <tree> Mark Lodato 2010-12-18 5:38 ` [PATCH 6/8] docs: use <tree> instead of <tree-ish> Mark Lodato 2010-12-18 8:35 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 7/8] docs: use <commit> instead of <commit-ish> Mark Lodato 2010-12-18 8:39 ` Jonathan Nieder 2010-12-18 5:38 ` [PATCH 8/8] describe docs: note that <commit> is optional Mark Lodato 2010-12-18 8:49 ` [PATCHv2 0/8] docs: use metavariables consistently Jonathan Nieder 2010-12-18 16:45 ` Mark Lodato 2010-12-18 20:27 ` Junio C Hamano
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).