From: Junio C Hamano Date: Fri, 9 Sep 2016 04:49:49 +0000 (-0700) Subject: Merge branch 'po/range-doc' X-Git-Tag: v2.11.0-rc0~174 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/d0b61dc65faf6f20c6305d47b3deca978d1d5843?ds=inline;hp=-c Merge branch 'po/range-doc' Clarify various ways to specify the "revision ranges" in the documentation. * po/range-doc: doc: revisions: sort examples and fix alignment of the unchanged doc: revisions: show revision expansion in examples doc: revisions - clarify reachability examples doc: revisions - define `reachable` doc: gitrevisions - clarify 'latter case' is revision walk doc: gitrevisions - use 'reachable' in page description doc: revisions: single vs multi-parent notation comparison doc: revisions: extra clarification of ^! notation effects doc: revisions: give headings for the two and three dot notations doc: show the actual left, right, and boundary marks doc: revisions - name the left and right sides doc: use 'symmetric difference' consistently --- d0b61dc65faf6f20c6305d47b3deca978d1d5843 diff --combined Documentation/gitk.txt index a68d860fa3,6c3eb1582d..e382dd96df --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@@ -70,7 -70,7 +70,7 @@@ linkgit:git-rev-list[1] for a complete --left-right:: - Mark which side of a symmetric diff a commit is reachable + Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with a `<` symbol and those from the right with a `>` symbol. @@@ -82,7 -82,7 +82,7 @@@ --simplify-merges:: - Additional option to '--full-history' to remove some needless + Additional option to `--full-history` to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge. (See "History simplification" in linkgit:git-log[1] for a more detailed diff --combined Documentation/pretty-formats.txt index b95d67ec01,f4cb0f30b8..a942d57f73 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@@ -143,18 -143,12 +143,18 @@@ ifndef::git-rev-list[ - '%N': commit notes endif::git-rev-list[] - '%GG': raw verification message from GPG for a signed commit -- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good, - untrusted signature and "N" for no signature +- '%G?': show "G" for a good (valid) signature, "B" for a bad signature, + "U" for a good signature with unknown validity and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit -- '%gD': reflog selector, e.g., `refs/stash@{1}` -- '%gd': shortened reflog selector, e.g., `stash@{1}` +- '%gD': reflog selector, e.g., `refs/stash@{1}` or + `refs/stash@{2 minutes ago`}; the format follows the rules described + for the `-g` option. The portion before the `@` is the refname as + given on the command line (so `git log -g refs/heads/master` would + yield `refs/heads/master@{0}`). +- '%gd': shortened reflog selector; same as `%gD`, but the refname + portion is shortened for human readability (so `refs/heads/master` + becomes just `master`). - '%gn': reflog identity name - '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) @@@ -172,7 -166,7 +172,7 @@@ respecting the `auto` settings of the former if we are going to a terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring on the next placeholders until the color is switched again. - - '%m': left, right or boundary mark + - '%m': left (`<`), right (`>`) or boundary (`-`) mark - '%n': newline - '%%': a raw '%' - '%x00': print a byte from a hex code diff --combined Documentation/rev-list-options.txt index a779c9dfec,f7645cc72d..7e462d3841 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@@ -193,7 -193,7 +193,7 @@@ endif::git-rev-list[ --stdin:: In addition to the '' listed on the command - line, read them from the standard input. If a '--' separator is + line, read them from the standard input. If a `--` separator is seen, stop reading commits and start reading paths to limit the result. @@@ -225,7 -225,7 +225,7 @@@ excluded from the output --left-only:: --right-only:: - List only commits on the respective side of a symmetric range, + List only commits on the respective side of a symmetric difference, i.e. only those which would be marked `<` resp. `>` by `--left-right`. + @@@ -252,25 -252,10 +252,25 @@@ list + With `--pretty` format other than `oneline` (for obvious reasons), this causes the output to have two extra lines of information -taken from the reflog. By default, 'commit@\{Nth}' notation is -used in the output. When the starting commit is specified as -'commit@\{now}', output also uses 'commit@\{timestamp}' notation -instead. Under `--pretty=oneline`, the commit message is +taken from the reflog. The reflog designator in the output may be shown +as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the +reflog) or as `ref@{timestamp}` (with the timestamp for that entry), +depending on a few rules: ++ +-- +1. If the starting point is specified as `ref@{Nth}`, show the index +format. ++ +2. If the starting point was specified as `ref@{now}`, show the +timestamp format. ++ +3. If neither was used, but `--date` was given on the command line, show +the timestamp in the format requested by `--date`. ++ +4. Otherwise, show the index format. +-- ++ +Under `--pretty=oneline`, the commit message is prefixed with this information on the same line. This option cannot be combined with `--reverse`. See also linkgit:git-reflog[1]. @@@ -289,10 -274,6 +289,10 @@@ ifdef::git-rev-list[ Try to speed up the traversal using the pack bitmap index (if one is available). Note that when traversing with `--objects`, trees and blobs will not have their associated path printed. + +--progress=
:: + Show progress reports on stderr as objects are considered. The + `
` text will be printed with each progress update. endif::git-rev-list[] -- @@@ -720,19 -701,15 +720,19 @@@ include::pretty-options.txt[ --relative-date:: Synonym for `--date=relative`. ---date=(relative|local|default|iso|iso-strict|rfc|short|raw):: +--date=:: Only takes effect for dates shown in human-readable format, such as when using `--pretty`. `log.date` config variable sets a default - value for the log command's `--date` option. + value for the log command's `--date` option. By default, dates + are shown in the original time zone (either committer's or + author's). If `-local` is appended to the format (e.g., + `iso-local`), the user's local time zone is used instead. + `--date=relative` shows dates relative to the current time, -e.g. ``2 hours ago''. +e.g. ``2 hours ago''. The `-local` option has no effect for +`--date=relative`. + -`--date=local` shows timestamps in user's local time zone. +`--date=local` is an alias for `--date=default-local`. + `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. The differences to the strict ISO 8601 format are: @@@ -750,31 -727,15 +750,31 @@@ format, often found in email messages + `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. + -`--date=raw` shows the date in the internal raw Git format `%s %z` format. +`--date=raw` shows the date as seconds since the epoch (1970-01-01 +00:00:00 UTC), followed by a space, and then the timezone as an offset +from UTC (a `+` or `-` with four digits; the first two are hours, and +the second two are minutes). I.e., as if the timestamp were formatted +with `strftime("%s %z")`). +Note that the `-local` option does not affect the seconds-since-epoch +value (which is always measured in UTC), but does switch the accompanying +timezone value. ++ +`--date=unix` shows the date as a Unix epoch timestamp (seconds since +1970). As with `--raw`, this is always in UTC and therefore `-local` +has no effect. + `--date=format:...` feeds the format `...` to your system `strftime`. Use `--date=format:%c` to show the date in your system locale's preferred format. See the `strftime` manual for a complete list of -format placeholders. +format placeholders. When using `-local`, the correct syntax is +`--date=format-local:...`. + -`--date=default` shows timestamps in the original time zone -(either committer's or author's). +`--date=default` is the default format, and is similar to +`--date=rfc2822`, with a few exceptions: + + - there is no comma after the day-of-week + + - the time zone is omitted when the local time zone is used ifdef::git-rev-list[] --header:: @@@ -796,7 -757,7 +796,7 @@@ ifdef::git-rev-list[ endif::git-rev-list[] --left-right:: - Mark which side of a symmetric diff a commit is reachable from. + Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with `<` and those from the right with `>`. If combined with `--boundary`, those commits are prefixed with `-`. diff --combined Documentation/revisions.txt index abae363983,a7fbcd72cd..4bed5b1ab7 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@@ -28,8 -28,8 +28,8 @@@ blobs contained in a commit first match in the following rules: . If '$GIT_DIR/' exists, that is what you mean (this is usually - useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' - and 'CHERRY_PICK_HEAD'); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` + and `CHERRY_PICK_HEAD`); . otherwise, 'refs/' if it exists; @@@ -41,16 -41,16 +41,16 @@@ . otherwise, 'refs/remotes//HEAD' if it exists. + -'HEAD' names the commit on which you based the changes in the working tree. -'FETCH_HEAD' records the branch which you fetched from a remote repository +`HEAD` names the commit on which you based the changes in the working tree. +`FETCH_HEAD` records the branch which you fetched from a remote repository with your last `git fetch` invocation. -'ORIG_HEAD' is created by commands that move your 'HEAD' in a drastic -way, to record the position of the 'HEAD' before their operation, so that +`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic +way, to record the position of the `HEAD` before their operation, so that you can easily change the tip of the branch back to the state before you ran them. -'MERGE_HEAD' records the commit(s) which you are merging into your branch +`MERGE_HEAD` records the commit(s) which you are merging into your branch when you run `git merge`. -'CHERRY_PICK_HEAD' records the commit which you are cherry-picking +`CHERRY_PICK_HEAD` records the commit which you are cherry-picking when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from @@@ -59,21 -59,21 +59,21 @@@ While the ref name encoding is unspecif some output processing may assume ref names in UTF-8. '@':: - '@' alone is a shortcut for 'HEAD'. + '@' 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 - second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value + pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 + second ago}' or '{1979-02-26 18:30:00}') specifies the value of the ref at a prior point in time. This suffix may only be used immediately following a ref name and the ref must have an existing log ('$GIT_DIR/logs/'). Note that this looks up the state of your *local* ref at a given time; e.g., what was in your local 'master' branch last week. If you want to look at commits made during - certain times, see '--since' and '--until'. + certain times, see `--since` and `--until`. -'@\{\}', e.g. 'master@\{1\}':: +'@{}', e.g. 'master@\{1\}':: A ref followed by the suffix '@' with an ordinal specification enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies the n-th prior value of that ref. For example 'master@\{1\}' @@@ -82,13 -82,13 +82,13 @@@ immediately following a ref name and the ref must have an existing log ('$GIT_DIR/logs/'). -'@\{\}', e.g. '@\{1\}':: +'@{}', e.g. '@\{1\}':: You can use the '@' construct with an empty ref part to get at a reflog entry of the current branch. For example, if you are on branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. -'@\{-\}', e.g. '@\{-1\}':: - The construct '@\{-\}' means the th branch/commit checked out +'@{-}', e.g. '@{-1}':: + The construct '@{-}' means the th branch/commit checked out before the current one. '@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: @@@ -101,7 -101,7 +101,7 @@@ '@\{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 + `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/'). + @@@ -139,7 -139,7 +139,7 @@@ from one location and push to another. '{caret}1{caret}1{caret}1'. See below for an illustration of the usage of this form. -'{caret}\{\}', e.g. 'v0.99.8{caret}\{commit\}':: +'{caret}{}', e.g. 'v0.99.8{caret}\{commit\}':: A suffix '{caret}' followed by an object type name enclosed in brace pair means dereference the object at '' recursively until an object of type '' is found or the object cannot be @@@ -159,13 -159,13 +159,13 @@@ it does not have to be dereferenced eve 'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an existing tag object. -'{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: +'{caret}{}', e.g. 'v0.99.8{caret}{}':: A suffix '{caret}' followed by an empty brace pair means the object could be a tag, and dereference the tag recursively until a non-tag object is found. -'{caret}\{/\}', e.g. 'HEAD^{/fix nasty bug}':: +'{caret}{/}', e.g. 'HEAD^{/fix nasty bug}':: A suffix '{caret}' to a revision parameter, followed by a brace pair that contains a text led by a slash, is the same as the ':/fix nasty bug' syntax below except that @@@ -176,12 -176,11 +176,12 @@@ 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. If the commit message starts with a - '!' you have to repeat that; the special sequence ':/!', - followed by something else than '!', is reserved for now. - The regular expression can match any part of the commit message. To - match messages starting with a string, one can use e.g. ':/^foo'. + reachable from any ref. 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 + literal '!' character, followed by 'foo'. Any other sequence beginning with + ':/!' is reserved for now. ':', e.g. 'HEAD:README', ':README', 'master:./README':: A suffix ':' followed by a path names the blob or tree @@@ -237,58 -236,84 +237,84 @@@ SPECIFYING RANGE ----------------- History traversing commands such as `git log` operate on a set - of commits, not just a single commit. To these commands, - specifying a single revision with the notation described in the - previous section means the set of commits reachable from that - commit, following the commit ancestry chain. - - To exclude commits reachable from a commit, a prefix '{caret}' - notation is used. E.g. '{caret}r1 r2' means commits reachable - from 'r2' but exclude the ones reachable from 'r1'. - - This set operation appears so often that there is a shorthand - for it. When you have two commits 'r1' and 'r2' (named according - to the syntax explained in SPECIFYING REVISIONS above), you can ask - for commits that are reachable from r2 excluding those that are reachable - from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. - - A similar notation 'r1\...r2' is called symmetric difference - of 'r1' and 'r2' and is defined as - 'r1 r2 --not $(git merge-base --all r1 r2)'. - It is the set of commits that are reachable from either one of - 'r1' or 'r2' but not from both. - - In these two shorthands, you can omit one end and let it default to HEAD. + of commits, not just a single commit. + + For these commands, + specifying a single revision, using the notation described in the + previous section, means the set of commits `reachable` from the given + commit. + + A commit's reachable set is the commit itself and the commits in + its ancestry chain. + + + Commit Exclusions + ~~~~~~~~~~~~~~~~~ + + '{caret}' (caret) Notation:: + To exclude commits reachable from a commit, a prefix '{caret}' + notation is used. E.g. '{caret}r1 r2' means commits reachable + from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and + its ancestors). + + Dotted Range Notations + ~~~~~~~~~~~~~~~~~~~~~~ + + The '..' (two-dot) Range Notation:: + The '{caret}r1 r2' set operation appears so often that there is a shorthand + for it. When you have two commits 'r1' and 'r2' (named according + to the syntax explained in SPECIFYING REVISIONS above), you can ask + for commits that are reachable from r2 excluding those that are reachable + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. + + The '...' (three dot) Symmetric Difference Notation:: + A similar notation 'r1\...r2' is called symmetric difference + of 'r1' and 'r2' and is defined as + 'r1 r2 --not $(git merge-base --all r1 r2)'. + It is the set of commits that are reachable from either one of + 'r1' (left side) or 'r2' (right side) but not from both. + + In these two shorthand notations, you can omit one end and let it default to HEAD. For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What did I do since I forked from the origin branch?" Similarly, '..origin' is a shorthand for 'HEAD..origin' and asks "What did the origin do since I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an empty range that is both reachable and unreachable from HEAD. - Two other shorthands for naming a set that is formed by a commit - and its parent commits exist. The 'r1{caret}@' notation means all - parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes - all of its parents. + Other {caret} Parent Shorthand Notations + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Two other shorthands exist, particularly useful for merge commits, + for naming a set that is formed by a commit and its parent commits. + + 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'. + + While '{caret}' was about specifying a single commit parent, these + two notations consider all its parents. For example you can say + 'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'. - To summarize: + Revision Range Summary + ---------------------- '':: - Include commits that are reachable from (i.e. ancestors of) - . + Include commits that are reachable from (i.e. and its + ancestors). '{caret}':: - Exclude commits that are reachable from (i.e. ancestors of) - . + Exclude commits that are reachable from (i.e. and its + ancestors). '..':: Include commits that are reachable from but exclude those that are reachable from . When either or - is omitted, it defaults to 'HEAD'. + is omitted, it defaults to `HEAD`. '\...':: Include commits that are reachable from either or but exclude those that are reachable from both. When - either or is omitted, it defaults to 'HEAD'. + either or is omitted, it defaults to `HEAD`. '{caret}@', e.g. 'HEAD{caret}@':: A suffix '{caret}' followed by an at sign is the same as listing @@@ -300,16 -325,27 +326,27 @@@ as giving commit '' and then all its parents prefixed with '{caret}' to exclude them (and their ancestors). - Here are a handful of examples: - - D G H D - D F G H I J D F - ^G D H D - ^D B E I J F B - B..C C - B...C G H D E B C - ^D B C E I J F B C - C I J F C - C^@ I J F - C^! C - F^! D G H D F + Here are a handful of examples using the Loeliger illustration above, + with each step in the notation's expansion and selection carefully + spelt out: + + Args Expanded arguments Selected commits + D G H D + D F G H I J D F + ^G D H D + ^D B E I J F B + ^D B C E I J F B C + C I J F C + B..C = ^B C C + B...C = B ^F C G H D E B C + C^@ = C^1 + = F I J F + B^@ = B^1 B^2 B^3 + = D E F D G H E F I J + C^! = C ^C^@ + = C ^C^1 + = C ^F C + B^! = B ^B^@ + = B ^B^1 ^B^2 ^B^3 + = B ^D ^E ^F B + F^! D = F ^I ^J D G H D F