X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-rev-parse.txt;h=5d4257062d1776ee18900b84e805197a9028e2f0;hb=cee7f245dcaef6dade28464f59420095a9949aac;hp=ab896fcf8353475ae3bf14b2c442ce49f1720530;hpb=288c0384505e6c25cc1a162242919a0485d50a74;p=git.git diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index ab896fcf8..5d4257062 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -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 @@ -91,7 +91,7 @@ OPTIONS --short, --short=number:: Instead of outputting the full SHA1 values of object names try to - abbriviate them to a shorter unique name. When no length is specified + abbreviate them to a shorter unique name. When no length is specified 7 is used. The minimum length is 4. --since=datestring, --after=datestring:: @@ -111,7 +111,9 @@ SPECIFYING REVISIONS A revision parameter typically, but not necessarily, names a commit object. They use what is called an 'extended SHA1' -syntax. +syntax. Here are various ways to spell object names. The +ones listed near the end of this list are to name trees and +blobs contained in a commit. * The full SHA1 object name (40-byte hexadecimal string), or a substring of such that is unique within the repository. @@ -119,11 +121,21 @@ syntax. name the same commit object if there are no other object in your repository whose object name starts with dae86e. +* An output from `git-describe`; i.e. a closest tag, followed by a + dash, a 'g', and an abbreviated object name. + * A symbolic ref name. E.g. 'master' typically means the commit object referenced by $GIT_DIR/refs/heads/master. If you 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}' @@ -131,7 +143,7 @@ syntax. '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. -* A suffix '~' to a revision parameter means the commit +* A suffix '{tilde}' to a revision parameter means the commit object that is the th generation grand-parent of the named commit object, following only the first parent. I.e. rev~3 is equivalent to rev{caret}{caret}{caret} which is equivalent to\ @@ -149,10 +161,14 @@ syntax. and dereference the tag recursively until a non-tag object is found. -'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 ':' followed by a path; this names the blob or tree + at the given path in the tree-ish object named by the part + before the colon. + +* A colon, optionally followed by a stage number (0 to 3) and a + colon, followed by a path; this names a blob object in the + index at the given path. Missing stage number (and the colon + that follows it) names an stage 0 entry. Here is an illustration, by Jon Loeliger. Both node B and C are a commit parents of commit node A. Parent commits are ordered @@ -161,9 +177,9 @@ left-to-right. G H I J \ / \ / D E F - \ | / - \ | / - \|/ + \ | / \ + \ | / | + \|/ | B C \ / \ / @@ -181,6 +197,40 @@ left-to-right. 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 ------ Written by Linus Torvalds and