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=-c 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 "" --- 7a188da354b0dd2525d8534a50e7684efbcf7039 diff --combined Documentation/revisions.txt index 2337a995ec,b0ac4cf659..82c1e5754e --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@@ -58,14 -58,14 +58,14 @@@ when you run `git merge` when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from -the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. +the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. While the ref name encoding is unspecified, UTF-8 is preferred as 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 +95,7 @@@ 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,12 -103,12 +103,12 @@@ 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 in a remote repository, of course, we report the local tracking branch - that corresponds to that branch (i.e., something in 'refs/remotes/'). + that corresponds to that branch (i.e., something in `refs/remotes/`). + Here's an example to make it more clear: + @@@ -131,7 -131,7 +131,7 @@@ from one location and push to another. 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 +139,9 @@@ '{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 +161,12 @@@ '{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}{}':: @@@ -184,8 -186,7 +186,8 @@@ A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. The regular expression can match any part of the + reachable from any ref, including HEAD. + The regular expression can match any part of the commit message. To match messages starting with a string, one can use e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a @@@ -194,19 -195,16 +196,16 @@@ 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 -300,7 +301,7 @@@ The 'r1{caret}@' notation means all par 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