Documentation/Makefile: allow man.base.url.for.relative.link to be set from Make

[thirdparty/git.git] / Documentation / git-rev-parse.txt

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 3ccef2f2b3295c6d5e14b8f3a9d354d7b57598da..82045a2522799ccf3a03479bf4f4cd1fa1809879 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -26,10 +26,20 @@ OPTIONS
 --parseopt::
        Use 'git-rev-parse' in option parsing mode (see PARSEOPT section below).
 
---keep-dash-dash::
+--keep-dashdash::
        Only meaningful in `--parseopt` mode. Tells the option parser to echo
        out the first `--` met instead of skipping it.
 
+--stop-at-non-option::
+       Only meaningful in `--parseopt` mode.  Lets the option parser stop at
+       the first non-option argument.  This can be used to parse sub-commands
+       that take options themself.
+
+--sq-quote::
+       Use 'git-rev-parse' in shell quoting mode (see SQ-QUOTE
+       section below). In contrast to the `--sq` option below, this
+       mode does only quoting. Nothing else is done to command input.
+
 --revs-only::
        Do not output flags and parameters not meant for
        'git-rev-list' command.
@@ -64,7 +74,8 @@ 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-\*'). In contrast to the `--sq-quote` option,
+       the command input is still interpreted as usual.
 
 --not::
        When showing object names, prefix them with '{caret}' and
@@ -84,6 +95,11 @@ OPTIONS
        unfortunately named tag "master"), and show them as full
        refnames (e.g. "refs/heads/master").
 
+--abbrev-ref[={strict|loose}]::
+       A non-ambiguous short name of the objects name.
+       The option core.warnAmbiguousRefs is used to select the strict
+       abbreviation mode.
+
 --all::
        Show all refs found in `$GIT_DIR/refs`.
 
@@ -299,18 +315,18 @@ 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
+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.  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`".
+from r1 by `{caret}r1 r2` and it can be written as `r1..r2`.
 
-A similar notation "`r1\...r2`" is called symmetric difference
+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.
 
@@ -401,6 +417,33 @@ C?        option C with an optional argument"
 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
 ------------
 
+SQ-QUOTE
+--------
+
+In `--sq-quote` mode, 'git-rev-parse' echoes on the standard output a
+single line suitable for `sh(1)` `eval`. This line is made by
+normalizing the arguments following `--sq-quote`. Nothing other than
+quoting the arguments is done.
+
+If you want command input to still be interpreted as usual by
+'git-rev-parse' before the output is shell quoted, see the `--sq`
+option.
+
+Example
+~~~~~~~
+
+------------
+$ cat >your-git-script.sh <<\EOF
+#!/bin/sh
+args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
+command="git frotz -n24 $args"          # and use it inside a handcrafted
+                                       # command line
+eval "$command"
+EOF
+
+$ sh your-git-script.sh "a b'c"
+------------
+
 EXAMPLES
 --------