Andy Whitcroftgit-for-each-ref: improve the documentation on scripting modes
When reading the synopsis for git-for-each-ref it is easy to miss the obvious power of --shell and family. Call this feature out in the primary paragragh. Also add more description to the examples to indicate which features we are demonstrating. Finally add a very simple eval based example in addition to the very complex one to give a gentler introduction.
Signed-off-by: Andy Whitcroft <apw@shadowen.org> ---
Show changes to Documentation/git-for-each-ref.txt +21 −4
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 6649f79..d5fdcef 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -17,7 +17,7 @@ according to the given `<format>`, after to the given set of `<key>`s. If `<max>` is given, stop after showing that many refs. The interporated values in `<format>` can optionally be quoted as string literals in the specified -host language. +host language allowing their direct evaluation in that language. OPTIONS ------- @@ -97,7 +97,8 @@ returns an empty string instead. EXAMPLES -------- -Show the most recent 3 tagged commits:: +An example directly producing formatted text. Show the most recent +3 tagged commits:: ------------ #!/bin/sh @@ -112,7 +113,23 @@ Ref: %(*refname) ' 'refs/tags' ------------ -A bit more elaborate report on tags:: + +A simple example showing the use of shell eval on the output, +demonstrating the use of --shell. List the prefixes of all heads:: +------------ +#!/bin/sh + +git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \ +while read entry +do + eval "$entry" + echo `dirname $ref` +done +------------ + + +A bit more elaborate report on tags, demonstrating that the format +may be an entire script:: ------------ #!/bin/sh @@ -156,7 +173,7 @@ Its message reads as: fi ' -eval=`git-for-each-ref -s --format="$fmt" \ +eval=`git-for-each-ref --shell --format="$fmt" \ --sort='*objecttype' \ --sort=-taggerdate \ refs/tags`