X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-rev-parse.txt;h=b761b4b9656eebf5b9caafc9d702c02e3f243fff;hb=95676853b2dc5d610a6f917aac37cbb12c57fcd2;hp=694f3a09d493fcbfbfed6e3f3d708a82d16c0e4c;hpb=72e9340cfde90189d76ef3c8a4793ea7764ff8ee;p=git.git diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 694f3a09d..b761b4b96 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -3,7 +3,7 @@ git-rev-parse(1) NAME ---- -git-rev-parse - Pick out and massage parameters. +git-rev-parse - Pick out and massage parameters SYNOPSIS @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION ----------- -Many git Porcelainish commands take mixture of flags +Many git porcelainish commands take mixture of flags (i.e. parameters that begin with a dash '-') and parameters meant for underlying `git-rev-list` command they use internally and flags and parameters for other commands they use as the @@ -67,11 +67,41 @@ OPTIONS --all:: Show all refs found in `$GIT_DIR/refs`. +--branches:: + Show branch refs found in `$GIT_DIR/refs/heads`. + +--tags:: + Show tag refs found in `$GIT_DIR/refs/tags`. + +--remotes:: + Show tag refs found in `$GIT_DIR/refs/remotes`. + --show-prefix:: - When the command is invoked from a directory show the + When the command is invoked from a subdirectory, show the path of the current directory relative to the top-level directory. +--show-cdup:: + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + +--git-dir:: + Show `$GIT_DIR` if defined else show the path to the .git directory. + +--short, --short=number:: + Instead of outputting the full SHA1 values of object names try to + abbreviate them to a shorter unique name. When no length is specified + 7 is used. The minimum length is 4. + +--since=datestring, --after=datestring:: + Parses the date string, and outputs corresponding + --max-age= parameter for git-rev-list command. + +--until=datestring, --before=datestring:: + Parses the date string, and outputs corresponding + --min-age= parameter for git-rev-list command. + ...:: Flags and parameters to be parsed. @@ -79,8 +109,9 @@ OPTIONS SPECIFYING REVISIONS -------------------- -A revision parameter typically names a commit object. They use -what is called an 'extended SHA1' syntax. +A revision parameter typically, but not necessarily, names a +commit object. They use what is called an 'extended SHA1' +syntax. * The full SHA1 object name (40-byte hexadecimal string), or a substring of such that is unique within the repository. @@ -93,6 +124,13 @@ what is called an 'extended SHA1' syntax. happen to have both heads/master and tags/master, you can explicitly say 'heads/master' to tell git which one you mean. +* A suffix '@' followed by 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\}') to specify 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/). + * A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}' means the th parent (i.e. 'rev{caret}' @@ -106,11 +144,78 @@ what is called an 'extended SHA1' syntax. equivalent to rev{caret}{caret}{caret} which is equivalent to\ rev{caret}1{caret}1{caret}1. -'git-rev-parse' also accepts a prefix '{caret}' to revision parameter, -which is passed to 'git-rev-list'. Two revision parameters -concatenated with '..' is a short-hand for writing a range -between them. I.e. 'r1..r2' is equivalent to saying '{caret}r1 r2' - +* A suffix '{caret}' followed by an object type name enclosed in + brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object + could be a tag, and dereference the tag recursively until an + object of that type is found or the object cannot be + dereferenced anymore (in which case, barf). `rev{caret}0` + introduced earlier is a short-hand for `rev{caret}\{commit\}`. + +* A suffix '{caret}' followed by an empty brace pair + (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, + and dereference the tag recursively until a non-tag object is + found. + +Here is an illustration, by Jon Loeliger. Both node B and C are +a commit parents of commit node A. Parent commits are ordered +left-to-right. + + G H I J + \ / \ / + D E F + \ | / \ + \ | / | + \|/ | + B C + \ / + \ / + A + + A = = A^0 + B = A^ = A^1 = A~1 + C = A^2 = A^2 + D = A^^ = A^1^1 = A~2 + E = B^2 = A^^2 + F = B^3 = A^^3 + G = A^^^ = A^1^1^1 = A~3 + H = D^2 = B^^2 = A^^^2 = A~2^2 + I = F^ = B^3^ = A^^3^ + J = F^2 = B^3^2 = A^^3^2 + + +SPECIFYING RANGES +----------------- + +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. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is +the difference of two sets (subtract the set of commits +reachable from `r1` from the set of commits reachable from +`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 it the set of commits that are reachable from either one of +`r1` or `r2` but not from both. + +Here are a few examples: + + D A B D + D F A B C D F + ^A G B D + ^A F B C F + G...I C D F G I + ^B G I C D F G I Author ------