diff options
| author |  Andy Whitcroft <apw@shadowen.org> | 2006-09-21 10:19:17 +0100 |
|---|---|---|
| committer |  Junio C Hamano <junkio@cox.net> | 2006-09-21 12:38:38 -0700 |
| commit | 1729fa9878ed8c99ae0bb2aecced557618d0c894 (patch) | |
| tree | eaba12f105f34f4777bcd9b3a1c81a1818e3d886 | |
| parent | Add git-for-each-ref: helper for language bindings (diff) | |
| download | tgif-1729fa9878ed8c99ae0bb2aecced557618d0c894.tar.xz | |
git-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>
Signed-off-by: Junio C Hamano <junkio@cox.net>
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 25 |
1 files changed, 21 insertions, 4 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 6649f795e8..d5fdcef8d9 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 sorting them according 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` |