@matheusbsbs / matheus-bagliano / commits / 1729fa9878
Fork 0

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>

Andy Whitcroft committed Sep 21, 2006 at 10:19 UTC 1729fa9878ed8c99ae0bb2aecced557618d0c894
1 file changed +21 -4
Documentation/git-for-each-ref.txt
+21 -4
@@ -17,7 +17,7 @@ according to the given `<format>`, after sorting them according
17 to the given set of `<key>`s. If `<max>` is given, stop after
18 showing that many refs. The interporated values in `<format>`
19 can optionally be quoted as string literals in the specified
20 -host language.
20 +host language allowing their direct evaluation in that language.
21
22 OPTIONS
23 -------
@@ -97,7 +97,8 @@ returns an empty string instead.
97 EXAMPLES
98 --------
99
100 -Show the most recent 3 tagged commits::
100 +An example directly producing formatted text. Show the most recent
101 +3 tagged commits::
102
103 ------------
104 #!/bin/sh
@@ -112,7 +113,23 @@ Ref: %(*refname)
113 ' 'refs/tags'
114 ------------
115
115 -A bit more elaborate report on tags::
116 +
117 +A simple example showing the use of shell eval on the output,
118 +demonstrating the use of --shell. List the prefixes of all heads::
119 +------------
120 +#!/bin/sh
121 +
122 +git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \
123 +while read entry
124 +do
125 + eval "$entry"
126 + echo `dirname $ref`
127 +done
128 +------------
129 +
130 +
131 +A bit more elaborate report on tags, demonstrating that the format
132 +may be an entire script::
133 ------------
134 #!/bin/sh
135
@@ -156,7 +173,7 @@ Its message reads as:
173 fi
174 '
175
159 -eval=`git-for-each-ref -s --format="$fmt" \
176 +eval=`git-for-each-ref --shell --format="$fmt" \
177 --sort='*objecttype' \
178 --sort=-taggerdate \
179 refs/tags`