From: Junio C Hamano Date: Mon, 13 May 2019 14:50:33 +0000 (+0900) Subject: Merge branch 'dl/rev-tilde-doc-clarify' X-Git-Tag: v2.22.0-rc0~6 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/7a188da354b0dd2525d8534a50e7684efbcf7039?hp=a505f62f6f1ebdacab075f1ce52f949f33f7450f Merge branch 'dl/rev-tilde-doc-clarify' Docfix. * dl/rev-tilde-doc-clarify: revisions.txt: remove ambibuity between : and : revisions.txt: mention ~ form revisions.txt: mark optional rev arguments with [] revisions.txt: change "rev" to "" --- diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 2337a995ec..82c1e5754e 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}' @@ -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 @@ -159,12 +161,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}{}':: @@ -194,19 +196,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 @@ -302,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