X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-rev-parse.txt;h=088f971b790ddd11d39ab2c3b441833961e53a0f;hb=0513f241cc2d757371dc7ba6b065366de044862e;hp=9e273bc5a6ee091ad7b81254228d33fd4df5541e;hpb=bc9c3e0b932c5e14de749e07f5045197e7d6cd76;p=git.git diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 9e273bc5a..088f971b7 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -8,23 +8,23 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- -'git-rev-parse' [ --option ] ... +'git rev-parse' [ --option ] ... 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 @@ -184,7 +194,10 @@ blobs contained in a commit. 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/). + 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`. * A ref followed by the suffix '@' with an ordinal specification enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify @@ -275,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 @@ -286,21 +299,21 @@ 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 -"`r1 r2 --not $(git-merge-base --all r1 r2)`". +"`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. 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: @@ -316,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. @@ -328,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. @@ -381,7 +394,7 @@ bar= some cool option --bar with an argument An option group Header C? option C with an optional argument" -eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?` +eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?` ------------ EXAMPLES