Merge branch 'ah/doc-rev-parse-short-default' into maint
[gitweb.git] / Documentation / git-for-each-ref.txt
index abe13f3bedaf55dbefc03d26b934351107ff50af..03e187a105b1bd5ffa6e615c2dc9199f0b803e44 100644 (file)
@@ -11,7 +11,7 @@ SYNOPSIS
 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
                   [(--sort=<key>)...] [--format=<format>] [<pattern>...]
                   [--points-at <object>] [(--merged | --no-merged) [<object>]]
-                  [--contains [<object>]]
+                  [--contains [<object>]] [--no-contains [<object>]]
 
 DESCRIPTION
 -----------
@@ -69,16 +69,22 @@ OPTIONS
 
 --merged [<object>]::
        Only list refs whose tips are reachable from the
-       specified commit (HEAD if not specified).
+       specified commit (HEAD if not specified),
+       incompatible with `--no-merged`.
 
 --no-merged [<object>]::
        Only list refs whose tips are not reachable from the
-       specified commit (HEAD if not specified).
+       specified commit (HEAD if not specified),
+       incompatible with `--merged`.
 
 --contains [<object>]::
        Only list refs which contain the specified commit (HEAD if not
        specified).
 
+--no-contains [<object>]::
+       Only list refs which don't contain the specified commit (HEAD
+       if not specified).
+
 --ignore-case::
        Sorting and filtering refs are case insensitive.
 
@@ -95,11 +101,20 @@ refname::
        The name of the ref (the part after $GIT_DIR/).
        For a non-ambiguous short name of the ref append `:short`.
        The option core.warnAmbiguousRefs is used to select the strict
-       abbreviation mode. If `strip=<N>` is appended, strips `<N>`
-       slash-separated path components from the front of the refname
-       (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`.
-       `<N>` must be a positive integer.  If a displayed ref has fewer
-       components than `<N>`, the command aborts with an error.
+       abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>`
+       slash-separated path components from the front (back) of the refname
+       (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
+       `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
+       If `<N>` is a negative number, strip as many path components as
+       necessary from the specified end to leave `-<N>` path components
+       (e.g. `%(refname:lstrip=-2)` turns
+       `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
+       turns `refs/tags/foo` into `refs`). When the ref does not have
+       enough components, the result becomes an empty string if
+       stripping with positive <N>, or it becomes the full refname if
+       stripping with negative <N>.  Neither is an error.
++
+`strip` can be used as a synomym to `lstrip`.
 
 objecttype::
        The type of the object (`blob`, `tree`, `commit`, `tag`).
@@ -110,21 +125,31 @@ objectsize::
 objectname::
        The object name (aka SHA-1).
        For a non-ambiguous abbreviation of the object name append `:short`.
+       For an abbreviation of the object name with desired length append
+       `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
+       length may be exceeded to ensure unique object names.
 
 upstream::
        The name of a local ref which can be considered ``upstream''
-       from the displayed ref. Respects `:short` in the same way as
-       `refname` above.  Additionally respects `:track` to show
-       "[ahead N, behind M]" and `:trackshort` to show the terse
-       version: ">" (ahead), "<" (behind), "<>" (ahead and behind),
-       or "=" (in sync).  Has no effect if the ref does not have
-       tracking information associated with it.
+       from the displayed ref. Respects `:short`, `:lstrip` and
+       `:rstrip` in the same way as `refname` above.  Additionally
+       respects `:track` to show "[ahead N, behind M]" and
+       `:trackshort` to show the terse version: ">" (ahead), "<"
+       (behind), "<>" (ahead and behind), or "=" (in sync). `:track`
+       also prints "[gone]" whenever unknown upstream ref is
+       encountered. Append `:track,nobracket` to show tracking
+       information without brackets (i.e "ahead N, behind M").  Has
+       no effect if the ref does not have tracking information
+       associated with it.  All the options apart from `nobracket`
+       are mutually exclusive, but if used together the last option
+       is selected.
 
 push::
-       The name of a local ref which represents the `@{push}` location
-       for the displayed ref. Respects `:short`, `:track`, and
-       `:trackshort` options as `upstream` does. Produces an empty
-       string if no `@{push}` ref is configured.
+       The name of a local ref which represents the `@{push}`
+       location for the displayed ref. Respects `:short`, `:lstrip`,
+       `:rstrip`, `:track`, and `:trackshort` options as `upstream`
+       does. Produces an empty string if no `@{push}` ref is
+       configured.
 
 HEAD::
        '*' if HEAD matches current ref (the checked out branch), ' '
@@ -149,6 +174,25 @@ align::
        quoted, but if nested then only the topmost level performs
        quoting.
 
+if::
+       Used as %(if)...%(then)...%(end) or
+       %(if)...%(then)...%(else)...%(end).  If there is an atom with
+       value or string literal after the %(if) then everything after
+       the %(then) is printed, else if the %(else) atom is used, then
+       everything after %(else) is printed. We ignore space when
+       evaluating the string before %(then), this is useful when we
+       use the %(HEAD) atom which prints either "*" or " " and we
+       want to apply the 'if' condition only on the 'HEAD' ref.
+       Append ":equals=<string>" or ":notequals=<string>" to compare
+       the value between the %(if:...) and %(then) atoms with the
+       given string.
+
+symref::
+       The ref which the given symbolic ref refers to. If not a
+       symbolic ref, nothing is printed. Respects the `:short`,
+       `:lstrip` and `:rstrip` options in the same way as `refname`
+       above.
+
 In addition to the above, for commit and tag objects, the header
 field names (`tree`, `parent`, `object`, `type`, and `tag`) can
 be used to specify the value in the header field.
@@ -186,6 +230,14 @@ As a special case for the date-type fields, you may specify a format for
 the date by adding `:` followed by date format name (see the
 values the `--date` option to linkgit:git-rev-list[1] takes).
 
+Some atoms like %(align) and %(if) always require a matching %(end).
+We call them "opening atoms" and sometimes denote them as %($open).
+
+When a scripting language specific quoting is in effect, everything
+between a top-level opening atom and its matching %(end) is evaluated
+according to the semantics of the opening atom and only its result
+from the top-level is quoted.
+
 
 EXAMPLES
 --------
@@ -273,6 +325,22 @@ eval=`git for-each-ref --shell --format="$fmt" \
 eval "$eval"
 ------------
 
+
+An example to show the usage of %(if)...%(then)...%(else)...%(end).
+This prefixes the current branch with a star.
+
+------------
+git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/
+------------
+
+
+An example to show the usage of %(if)...%(then)...%(end).
+This prints the authorname, if present.
+
+------------
+git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
+------------
+
 SEE ALSO
 --------
 linkgit:git-show-ref[1]