From e277ff43d34af1f9f5fbbde92307737f85afaa56 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Sun, 5 May 2019 12:06:59 -0400 Subject: revisions.txt: change "rev" to "" In revisions.txt, there were some instances of a rev argument being written as "rev". However, since they didn't mean the string literal, write "", instead. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/revisions.txt') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 7d1bd44094..2859d7734a 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -159,12 +159,12 @@ thing no matter the case. '{caret}0' is a short-hand for '{caret}\{commit\}'. + -'rev{caret}\{object\}' can be used to make sure 'rev' names an -object that exists, without requiring 'rev' to be a tag, and -without dereferencing 'rev'; because a tag is already an object, +'{caret}\{object\}' can be used to make sure '' names an +object that exists, without requiring '' to be a tag, and +without dereferencing ''; because a tag is already an object, it does not have to be dereferenced even once to get to an object. + -'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an +'{caret}\{tag\}' can be used to ensure that '' identifies an existing tag object. '{caret}{}', e.g. 'v0.99.8{caret}{}':: -- cgit v1.2.3 From d86d207471e3411ceb2969f1066e31fb4ca144dc Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Sun, 5 May 2019 12:07:03 -0400 Subject: revisions.txt: mark optional rev arguments with [] In revisions.txt, an optional rev argument was not distinguised. Instead, a user had to continue and read the description in order to learn that the argument was optional. Since the [] notation for an optional argument is common-knowledge in the Git documentation, mark optional arguments with [] so that it's more obvious for the reader. Helped-by: Andreas Heiduk Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/revisions.txt') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 2859d7734a..6f2f83f8a2 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8. '@':: '@' alone is a shortcut for `HEAD`. -'@{}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: +'[]@{}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: A ref followed by the suffix '@' with a date specification enclosed in a brace pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8. The construct '@{-}' means the th branch/commit checked out before the current one. -'@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: +'[]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: The suffix '@\{upstream\}' to a branchname (short form '@\{u\}') refers to the branch that the branch specified by branchname is set to build on top of (configured with `branch..remote` and @@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8. current one. These suffixes are also accepted when spelled in uppercase, and they mean the same thing no matter the case. -'@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: +'[]@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: The suffix '@\{push}' reports the branch "where we would push to" if `git push` were run while `branchname` was checked out (or the current `HEAD` if no branchname is specified). Since our push destination is @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow, This suffix is also accepted when spelled in uppercase, and means the same thing no matter the case. -'{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: +'{caret}[]', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}' means the th parent (i.e. '{caret}' @@ -301,7 +301,7 @@ The 'r1{caret}@' notation means all parents of 'r1'. The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. By itself, this notation denotes the single commit 'r1'. -The '{caret}-' notation includes '' but excludes the th +The '{caret}-[]' notation includes '' but excludes the th parent (i.e. a shorthand for '{caret}..'), with '' = 1 if not given. This is typically useful for merge commits where you can just pass '{caret}-' to get all the commits in the branch -- cgit v1.2.3 From 6a12e99a52d2d01ea84e5040a87e0dac0a4b0b35 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Sun, 5 May 2019 12:07:07 -0400 Subject: revisions.txt: mention ~ form In revisions.txt, the '^' form is mentioned but the '~' form is missing. Although both forms are essentially equivalent (they each get the first parent of the specified revision), we should mention the latter for completeness. Make this change. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation/revisions.txt') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 6f2f83f8a2..b5d9d1b381 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -139,7 +139,9 @@ thing no matter the case. '{caret}0' means the commit itself and is used when '' is the object name of a tag object that refers to a commit object. -'{tilde}', e.g. 'master{tilde}3':: +'{tilde}[]', e.g. 'HEAD{tilde}, master{tilde}3':: + A suffix '{tilde}' to a revision parameter means the first parent of + that commit object. A suffix '{tilde}' to a revision parameter means the commit object that is the th generation ancestor of the named commit object, following only the first parents. I.e. '{tilde}3' is -- cgit v1.2.3 From 4ad1b2c7a6bf4c7ef017cd2b3baeb7bea8b8c48d Mon Sep 17 00:00:00 2001 From: Andreas Heiduk Date: Sun, 5 May 2019 12:07:10 -0400 Subject: revisions.txt: remove ambibuity between : and : The revision ':README' is mentioned as an example for ':' but the explanation forwards to the '::' syntax. At the same time '::' did not mark the ':' as optional. Signed-off-by: Andreas Heiduk Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'Documentation/revisions.txt') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index b5d9d1b381..b0ac4cf659 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -195,19 +195,16 @@ existing tag object. Depending on the given text, the shell's word splitting rules might require additional quoting. -':', e.g. 'HEAD:README', ':README', 'master:./README':: +':', e.g. 'HEAD:README', 'master:./README':: A suffix ':' followed by a path names the blob or tree at the given path in the tree-ish object named by the part before the colon. - ':path' (with an empty part before the colon) - is a special case of the syntax described next: content - recorded in the index at the given path. A path starting with './' or '../' is relative to the current working directory. The given path will be converted to be relative to the working tree's root directory. This is most useful to address a blob or tree from a commit or tree that has the same tree structure as the working tree. -'::', e.g. ':0:README', ':README':: +':[:]', e.g. ':0:README', ':README':: A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path, names a blob object in the index at the given path. A missing stage number (and the colon -- cgit v1.2.3