cleanup revisions.txt
v3 cover cleanup revisions.txt
In reply to a message not in the archiveThanks again for the comments, Andreas! I've incorporated all of them into this reroll.
---
Changes since v2:
* Marked more optional arguments with []
* Added Andreas' "revisions.txt: remove ambibuity between <rev>:<path> and :<path>" patch
Changes since v1:
* Added patch to fix instances of "rev" to "<rev>"
* Marked all optional rev arguments with []
Andreas Heiduk (1):
revisions.txt: remove ambibuity between <rev>:<path> and :<path>
Denton Liu (3):
revisions.txt: change "rev" to "<rev>" revisions.txt: mark optional rev arguments with [] revisions.txt: mention <rev>~ form
Documentation/revisions.txt | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-)
Signature · 1 line
2.21.0.1049.geb646f7864
PATCH v3 1/4 revisions.txt: change "rev" to "<rev>"
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 "<rev>", instead.
--- Documentation/revisions.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/revisions.txt +4 -4
@@ -159,12 +159,12 @@ thing no matter the case. '<rev>{caret}0' is a short-hand for '<rev>{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, +'<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, 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 +'<rev>{caret}\{tag\}' can be used to ensure that '<rev>' identifies an existing tag object. '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::
Signature · 1 line
2.21.0.1049.geb646f7864
PATCH v3 2/4 revisions.txt: mark optional rev arguments with []
In reply to Denton LiuIn 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.
--- Documentation/revisions.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/revisions.txt +5 -5
@@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8. '@':: '@' alone is a shortcut for `HEAD`. -'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: +'[<refname>]@{<date>}', 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 '@{-<n>}' means the <n>th branch/commit checked out before the current one. -'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: +'[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') refers to the branch that the branch specified by branchname is set to build on top of (configured with `branch.<name>.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. -'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: +'[<branchname>]@\{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. -'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: +'<rev>{caret}[<n>]', 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}<n>' means the <n>th parent (i.e. '<rev>{caret}'
@@ -302,7 +302,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 '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th +The '<rev>{caret}-[<n>]' notation includes '<rev>' but excludes the <n>th parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if not given. This is typically useful for merge commits where you can just pass '<commit>{caret}-' to get all the commits in the branch
Signature · 1 line
2.21.0.1049.geb646f7864
PATCH v3 3/4 revisions.txt: mention <rev>~ form
In reply to Denton LiuIn revisions.txt, the '<rev>^' form is mentioned but the '<rev>~' 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.
--- Documentation/revisions.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/revisions.txt +3 -1
@@ -139,7 +139,9 @@ thing no matter the case. '<rev>{caret}0' means the commit itself and is used when '<rev>' is the object name of a tag object that refers to a commit object. -'<rev>{tilde}<n>', e.g. 'master{tilde}3':: +'<rev>{tilde}[<n>]', 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}<n>' to a revision parameter means the commit object that is the <n>th generation ancestor of the named commit object, following only the first parents. I.e. '<rev>{tilde}3' is
Signature · 1 line
2.21.0.1049.geb646f7864
PATCH v3 4/4 revisions.txt: remove ambibuity between <rev>:<path> and :<path>
In reply to Denton LiuFrom: Andreas Heiduk <[email protected]>
The revision ':README' is mentioned as an example for '<rev>:<path>' but the explanation forwards to the ':<n>:<path>' syntax. At the same time ':<n>:<path>' did not mark the '<n>:' as optional.
---
Just for clarification, the correct procedure is to include my sign-off on top of Andreas' when I'm forwarding patches, correct? If it's not, Junio, please take my sign-off for me.
Documentation/revisions.txt | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-)
Documentation/revisions.txt +2 -5
@@ -196,19 +196,16 @@ existing tag object. Depending on the given text, the shell's word splitting rules might require additional quoting. -'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: +'<rev>:<path>', 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. -':<n>:<path>', e.g. ':0:README', ':README':: +':[<n>:]<path>', 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
Signature · 1 line
2.21.0.1049.geb646f7864
Sorry, I specified the wrong --in-reply-to. The correct parent message should be this[1].
[1]: https://public-inbox.org/git/[email protected]/
Quoted 31 lines · Denton Liu
Thanks again for the comments, Andreas! I've incorporated all of them into this reroll.
---
Changes since v2:
* Marked more optional arguments with []
* Added Andreas' "revisions.txt: remove ambibuity between <rev>:<path> and :<path>" patchChanges since v1:
* Added patch to fix instances of "rev" to "<rev>"
* Marked all optional rev arguments with []Andreas Heiduk (1):
revisions.txt: remove ambibuity between <rev>:<path> and :<path>Denton Liu (3):
revisions.txt: change "rev" to "<rev>" revisions.txt: mark optional rev arguments with [] revisions.txt: mention <rev>~ formDocumentation/revisions.txt | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-)Signature · 1 line
2.21.0.1049.geb646f7864
Hi Junio,
I noticed that there are both dl/rev-tilde-doc-clarify and dl/revisions-doc-update branches. The latter comes from this patchset and is a complete replacement for the former.
Thanks,
Denton
Quoted 31 lines · Denton Liu
Thanks again for the comments, Andreas! I've incorporated all of them into this reroll.
---
Changes since v2:
* Marked more optional arguments with []
* Added Andreas' "revisions.txt: remove ambibuity between <rev>:<path> and :<path>" patchChanges since v1:
* Added patch to fix instances of "rev" to "<rev>"
* Marked all optional rev arguments with []Andreas Heiduk (1):
revisions.txt: remove ambibuity between <rev>:<path> and :<path>Denton Liu (3):
revisions.txt: change "rev" to "<rev>" revisions.txt: mark optional rev arguments with [] revisions.txt: mention <rev>~ formDocumentation/revisions.txt | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-)Signature · 1 line
2.21.0.1049.geb646f7864
Quoted 3 lines · Denton Liu
I noticed that there are both
dl/rev-tilde-doc-clarifyanddl/revisions-doc-updatebranches. The latter comes from this patchset and is a complete replacement for the former.
Thanks for spotting. Will replace the former with the updated patches.
Thanks.