diff options
| author | Andy Whitcroft <apw@shadowen.org> | 2006-09-21 09:19:17 (GMT) |
|---|---|---|
| committer | Junio C Hamano <junkio@cox.net> | 2006-09-21 19:38:38 (GMT) |
| commit | 1729fa9878ed8c99ae0bb2aecced557618d0c894 (patch) | |
| tree | eaba12f105f34f4777bcd9b3a1c81a1818e3d886 | |
| parent | 9f613ddd21cbd05bfc139d9b1551b5780aa171f6 (diff) | |
| download | git-1729fa9878ed8c99ae0bb2aecced557618d0c894.zip git-1729fa9878ed8c99ae0bb2aecced557618d0c894.tar.gz git-1729fa9878ed8c99ae0bb2aecced557618d0c894.tar.bz2 | |
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 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 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` |