X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-rev-parse.txt;h=088f971b790ddd11d39ab2c3b441833961e53a0f;hb=0513f241cc2d757371dc7ba6b065366de044862e;hp=e9fb2b15795e213580ee78230d3db0b28dddc698;hpb=b1889c36d85514e5e70462294c561a02c2edfe2b;p=git.git diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index e9fb2b157..088f971b7 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -15,16 +15,16 @@ DESCRIPTION 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 -downstream of `git-rev-list`. This command is used to +meant for the underlying 'git-rev-list' command they use internally +and flags and parameters for the other commands they use +downstream of 'git-rev-list'. This command is used to distinguish between them. OPTIONS ------- --parseopt:: - Use `git-rev-parse` in option parsing mode (see PARSEOPT section below). + Use 'git-rev-parse' in option parsing mode (see PARSEOPT section below). --keep-dash-dash:: Only meaningful in `--parseopt` mode. Tells the option parser to echo @@ -32,11 +32,11 @@ OPTIONS --revs-only:: Do not output flags and parameters not meant for - `git-rev-list` command. + 'git-rev-list' command. --no-revs:: Do not output flags and parameters meant for - `git-rev-list` command. + 'git-rev-list' command. --flags:: Do not output non-flag parameters. @@ -64,7 +64,7 @@ OPTIONS properly quoted for consumption by shell. Useful when you expect your parameter to contain whitespaces and newlines (e.g. when using pickaxe `-S` with - `git-diff-\*`). + 'git-diff-\*'). --not:: When showing object names, prefix them with '{caret}' and @@ -128,13 +128,13 @@ OPTIONS --since=datestring:: --after=datestring:: - Parses the date string, and outputs corresponding - --max-age= parameter for git-rev-list command. + Parse the date string, and output the corresponding + --max-age= parameter for 'git-rev-list'. --until=datestring:: --before=datestring:: - Parses the date string, and outputs corresponding - --min-age= parameter for git-rev-list command. + Parse the date string, and output the corresponding + --min-age= parameter for 'git-rev-list'. ...:: Flags and parameters to be parsed. @@ -155,7 +155,7 @@ blobs contained in a commit. 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 +* 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 @@ -166,7 +166,7 @@ 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` and `MERGE_HEAD`); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); . otherwise, `$GIT_DIR/refs/` if exists; @@ -177,6 +177,16 @@ blobs contained in a commit. . otherwise, `$GIT_DIR/refs/remotes/` if exists; . otherwise, `$GIT_DIR/refs/remotes//HEAD` if exists. ++ +HEAD names the commit your changes in the working tree is based on. +FETCH_HEAD records the branch you fetched from a remote repository +with your last 'git-fetch' invocation. +ORIG_HEAD is created by commands that moves your HEAD in a drastic +way, to record the position of the HEAD before their operation, so that +you can change the tip of the branch back to the state before you ran +them easily. +MERGE_HEAD records the commit(s) you are merging into your branch +when you run 'git-merge'. * A ref followed by the suffix '@' with a date specification enclosed in a brace @@ -278,7 +288,7 @@ G H I J SPECIFYING RANGES ----------------- -History traversing commands such as `git-log` operate on a set +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 @@ -289,10 +299,10 @@ 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`). +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 @@ -301,9 +311,9 @@ It is the set of commits that are reachable from either one of `r1` or `r2` but not from both. Two other shorthands for naming a set that is formed by a commit -and its parent commits exists. `r1{caret}@` notation means all +and its parent commits exist. The `r1{caret}@` notation means all parents of `r1`. `r1{caret}!` includes commit `r1` but excludes -its all parents. +all of its parents. Here are a handful of examples: @@ -319,7 +329,7 @@ Here are a handful of examples: PARSEOPT -------- -In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell +In `--parseopt` mode, 'git-rev-parse' helps massaging options to bring to shell scripts the same facilities C builtins have. It works as an option normalizer (e.g. splits single switches aggregate values), a bit like `getopt(1)` does. @@ -331,7 +341,7 @@ usage on the standard error stream, and exits with code 129. Input Format ~~~~~~~~~~~~ -`git-rev-parse --parseopt` input format is fully text based. It has two parts, +'git-rev-parse --parseopt' input format is fully text based. It has two parts, separated by a line that contains only `--`. The lines before the separator (should be more than one) are used for the usage. The lines after the separator describe the options.