diff options
Diffstat (limited to 'Documentation/git-rev-parse.txt')
| -rw-r--r-- | Documentation/git-rev-parse.txt | 93 |
1 files changed, 86 insertions, 7 deletions
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4758c33dee..f02f6bbb49 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -23,6 +23,13 @@ distinguish between them. OPTIONS ------- +--parseopt:: + 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 + out the first `--` met instead of skipping it. + --revs-only:: Do not output flags and parameters not meant for `git-rev-list` command. @@ -63,6 +70,13 @@ OPTIONS possible '{caret}' prefix); this option makes them output in a form as close to the original input as possible. +--symbolic-full-name:: + This is similar to \--symbolic, but it omits input that + are not refs (i.e. branch or tag names; or more + explicitly disambiguating "heads/master" form, when you + want to name the "master" branch when there is an + unfortunately named tag "master"), and show them as full + refnames (e.g. "refs/heads/master"). --all:: Show all refs found in `$GIT_DIR/refs`. @@ -215,13 +229,13 @@ blobs contained in a commit. * 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. During a merge, stage + that follows it) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch's version (typically the current branch), and stage 3 is the version from the branch being merged. -Here is an illustration, by Jon Loeliger. Both node B and C are -a commit parents of commit node A. Parent commits are ordered +Here is an illustration, by Jon Loeliger. Both commit nodes B +and C are parents of commit node A. Parent commits are ordered left-to-right. G H I J @@ -277,7 +291,7 @@ and its parent commits exists. `r1{caret}@` notation means all parents of `r1`. `r1{caret}!` includes commit `r1` but excludes its all parents. -Here are a handful examples: +Here are a handful of examples: D G H D D F G H I J D F @@ -288,10 +302,75 @@ Here are a handful examples: C^@ I J F F^! D G H D F +PARSEOPT +-------- + +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. + +It takes on the standard input the specification of the options to parse and +understand, and echoes on the standard output a line suitable for `sh(1)` `eval` +to replace the arguments with normalized ones. In case of error, it outputs +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, +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. + +Each line of options has this format: + +------------ +<opt_spec><arg_spec>? SP+ help LF +------------ + +`<opt_spec>`:: + its format is the short option character, then the long option name + separated by a comma. Both parts are not required, though at least one + is necessary. `h,help`, `dry-run` and `f` are all three correct + `<opt_spec>`. + +`<arg_spec>`:: + an `<arg_spec>` tells the option parser if the option has an argument + (`=`), an optional one (`?` though its use is discouraged) or none + (no `<arg_spec>` in that case). + +The remainder of the line, after stripping the spaces, is used +as the help associated to the option. + +Blank lines are ignored, and lines that don't match this specification are used +as option group headers (start the line with a space to create such +lines on purpose). + +Example +~~~~~~~ + +------------ +OPTS_SPEC="\ +some-command [options] <args>... + +some-command does foo and bar! +-- +h,help show the help + +foo some nifty option --foo +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 $?` +------------ + + Author ------ -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> +Written by Linus Torvalds <torvalds@osdl.org> . +Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org> Documentation -------------- @@ -299,4 +378,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite |