Only list refs which contain the specified commit (HEAD if not
specified).
+--ignore-case::
+ Sorting and filtering refs are case insensitive.
+
FIELD NAMES
-----------
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>`
+ abbreviation mode. If `lstrip=<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`.
+ (e.g., `%(refname:lstrip=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.
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` and `:lstrip` 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`,
+ `: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), ' '
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` and
+ `:lstrip` 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.
line is 'contents:body', where body is all of the lines after the first
blank line. The optional GPG signature is `contents:signature`. The
first `N` lines of the message is obtained using `contents:lines=N`.
+Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
+are obtained as 'contents:trailers'.
For sorting purposes, fields with numeric values sort in numeric order
(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).
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
--------
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]