path: root/Documentation/git-for-each-ref.txt
diff options
authorKarthik Nayak <>2017-01-10 08:49:34 (GMT)
committerJunio C Hamano <>2017-01-10 20:44:30 (GMT)
commitc58492d4347fb6ee68fbb59b40e34ffde4dc2389 (patch)
tree1a381c301e49e029f183f71a420d1096837d91a4 /Documentation/git-for-each-ref.txt
parent1d1bdafd64266e5ee3bd46c6965228f32e4022ea (diff)
ref-filter: implement %(if), %(then), and %(else) atoms
Implement %(if), %(then) and %(else) atoms. Used as %(if)...%(then)...%(end) or %(if)...%(then)...%(else)...%(end). If the format string between %(if) and %(then) expands to an empty string, or to only whitespaces, then the whole %(if)...%(end) expands to the string following %(then). Otherwise, it expands to the string following %(else), if any. Nesting of this construct is possible. This is in preparation for porting over `git branch -l` to use ref-filter APIs for printing. Add documentation and tests regarding the same. Mentored-by: Christian Couder <> Mentored-by: Matthieu Moy <> Signed-off-by: Karthik Nayak <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-for-each-ref.txt')
1 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index abe13f3..6b671ae 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -149,6 +149,16 @@ align::
quoted, but if nested then only the topmost level performs
+ 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.
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 +196,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.
@@ -273,6 +291,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)"