From 9f613ddd21cbd05bfc139d9b1551b5780aa171f6 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 15 Sep 2006 13:30:02 -0700 Subject: Add git-for-each-ref: helper for language bindings This adds a new command, git-for-each-ref. You can have it iterate over refs and have it output various aspects of the objects they refer to. Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 164 +++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 Documentation/git-for-each-ref.txt (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt new file mode 100644 index 0000000000..6649f795e8 --- /dev/null +++ b/Documentation/git-for-each-ref.txt @@ -0,0 +1,164 @@ +git-for-each-ref(1) +=================== + +NAME +---- +git-for-each-ref - Output information on each ref + +SYNOPSIS +-------- +'git-for-each-ref' [--count=]* [--shell|--perl|--python] [--sort=]* [--format=] [] + +DESCRIPTION +----------- + +Iterate over all refs that match `` and show them +according to the given ``, after sorting them according +to the given set of ``s. If `` is given, stop after +showing that many refs. The interporated values in `` +can optionally be quoted as string literals in the specified +host language. + +OPTIONS +------- +:: + By default the command shows all refs that match + ``. This option makes it stop after showing + that many refs. + +:: + A field name to sort on. Prefix `-` to sort in + descending order of the value. When unspecified, + `refname` is used. More than one sort keys can be + given. + +:: + A string that interpolates `%(fieldname)` from the + object pointed at by a ref being shown. If `fieldname` + is prefixed with an asterisk (`*`) and the ref points + at a tag object, the value for the field in the object + tag refers is used. When unspecified, defaults to + `%(refname)`. + +:: + If given, the name of the ref is matched against this + using fnmatch(3). Refs that do not match the pattern + are not shown. + +--shell, --perl, --python:: + If given, strings that substitute `%(fieldname)` + placeholders are quoted as string literals suitable for + the specified host language. This is meant to produce + a scriptlet that can directly be `eval`ed. + + +FIELD NAMES +----------- + +Various values from structured fields in referenced objects can +be used to interpolate into the resulting output, or as sort +keys. + +For all objects, the following names can be used: + +refname:: + The name of the ref (the part after $GIT_DIR/refs/). + +objecttype:: + The type of the object (`blob`, `tree`, `commit`, `tag`). + +objectsize:: + The size of the object (the same as `git-cat-file -s` reports). + +objectname:: + The object name (aka SHA-1). + +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. + +Fields that have name-email-date tuple as its value (`author`, +`committer`, and `tagger`) can be suffixed with `name`, `email`, +and `date` to extract the named component. + +The first line of the message in a commit and tag object is +`subject`, the remaining lines are `body`. The whole message +is `contents`. + +For sorting purposes, fields with numeric values sort in numeric +order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). +All other fields are used to sort in their byte-value order. + +In any case, a field name that refers to a field inapplicable to +the object referred by the ref does not cause an error. It +returns an empty string instead. + + +EXAMPLES +-------- + +Show the most recent 3 tagged commits:: + +------------ +#!/bin/sh + +git-for-each-ref --count=3 --sort='-*authordate' \ +--format='From: %(*authorname) %(*authoremail) +Subject: %(*subject) +Date: %(*authordate) +Ref: %(*refname) + +%(*body) +' 'refs/tags' +------------ + +A bit more elaborate report on tags:: +------------ +#!/bin/sh + +fmt=' + r=%(refname) + t=%(*objecttype) + T=${r#refs/tags/} + + o=%(*objectname) + n=%(*authorname) + e=%(*authoremail) + s=%(*subject) + d=%(*authordate) + b=%(*body) + + kind=Tag + if test "z$t" = z + then + # could be a lightweight tag + t=%(objecttype) + kind="Lightweight tag" + o=%(objectname) + n=%(authorname) + e=%(authoremail) + s=%(subject) + d=%(authordate) + b=%(body) + fi + echo "$kind $T points at a $t object $o" + if test "z$t" = zcommit + then + echo "The commit was authored by $n $e +at $d, and titled + + $s + +Its message reads as: +" + echo "$b" | sed -e "s/^/ /" + echo + fi +' + +eval=`git-for-each-ref -s --format="$fmt" \ + --sort='*objecttype' \ + --sort=-taggerdate \ + refs/tags` +eval "$eval" +------------ -- cgit v1.2.3 From 1729fa9878ed8c99ae0bb2aecced557618d0c894 Mon Sep 17 00:00:00 2001 From: Andy Whitcroft Date: Thu, 21 Sep 2006 10:19:17 +0100 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) (limited to 'Documentation/git-for-each-ref.txt') 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 ``, after sorting them according to the given set of ``s. If `` is given, stop after showing that many refs. The interporated values in `` 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` -- cgit v1.2.3 From ba7545adab83e6bea43353937eabb467bcb7d4f7 Mon Sep 17 00:00:00 2001 From: Jakub Narebski Date: Sat, 28 Oct 2006 19:30:05 +0200 Subject: Documentation: Update information about in git-for-each-ref Update information about value of used when it is left unspecified. Add information about `%%` and `%xx` interpolation (URL encoding). Signed-off-by: Jakub Narebski Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index d5fdcef8d9..4af1ebf5dd 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -38,7 +38,11 @@ OPTIONS is prefixed with an asterisk (`*`) and the ref points at a tag object, the value for the field in the object tag refers is used. When unspecified, defaults to - `%(refname)`. + `%(objectname) SPC %(objecttype) TAB %(refname)`. + It also interpolates `%%` to `%`, and `%xx` where `xx` + are hex digits interpolates to character with hex code + `xx`; for example `%00` interpolates to `\0` (NUL), + `%09` to `\t` (TAB) and `%0a` to `\n` (LF). :: If given, the name of the ref is matched against this -- cgit v1.2.3 From 1dc5e55f2d2cab9ca24dc435dc2bc4f466f15ade Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 28 Oct 2006 14:25:41 -0700 Subject: Documentation: fix git-format-patch mark-up and link it from git.txt Two asterisks the SYNOPSIS section were mistaken as emphasis, and the latter backtick in "``s" were not recognized as closing backtick. Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 4af1ebf5dd..2bf6aef735 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -7,14 +7,14 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- -'git-for-each-ref' [--count=]* [--shell|--perl|--python] [--sort=]* [--format=] [] +'git-for-each-ref' [--count=]\* [--shell|--perl|--python] [--sort=]\* [--format=] [] DESCRIPTION ----------- Iterate over all refs that match `` and show them according to the given ``, after sorting them according -to the given set of ``s. If `` is given, stop after +to the given set of ``. If `` is given, stop after showing that many refs. The interporated values in `` can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. -- cgit v1.2.3 From 23bfbb815d7d71ff20c014f4610732597f0a75db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Scharfe?= Date: Wed, 17 Jan 2007 16:32:41 +0100 Subject: Documentation: a few spelling fixes Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 2bf6aef735..06e7ab1ec1 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -15,7 +15,7 @@ DESCRIPTION Iterate over all refs that match `` and show them according to the given ``, after sorting them according to the given set of ``. If `` is given, stop after -showing that many refs. The interporated values in `` +showing that many refs. The interpolated values in `` can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. -- cgit v1.2.3 From 5558e55c06a1e897f3064f0c8a343d5c9858f6b2 Mon Sep 17 00:00:00 2001 From: "Shawn O. Pearce" Date: Sun, 28 Jan 2007 02:39:13 -0500 Subject: Teach for-each-ref about a little language called Tcl. Love it or hate it, some people actually still program in Tcl. Some of those programs are meant for interfacing with Git. Programs such as gitk and git-gui. It may be useful to have Tcl-safe output available from for-each-ref, just like shell, Perl and Python already enjoy. Thanks to Sergey Vlasov for pointing out the horrible flaws in the first and second version of this patch, and steering me in the right direction for Tcl value quoting. Signed-off-by: Shawn O. Pearce Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 06e7ab1ec1..da52eba7b3 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -7,7 +7,7 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- -'git-for-each-ref' [--count=]\* [--shell|--perl|--python] [--sort=]\* [--format=] [] +'git-for-each-ref' [--count=]\* [--shell|--perl|--python|--tcl] [--sort=]\* [--format=] [] DESCRIPTION ----------- @@ -49,7 +49,7 @@ OPTIONS using fnmatch(3). Refs that do not match the pattern are not shown. ---shell, --perl, --python:: +--shell, --perl, --python, --tcl:: If given, strings that substitute `%(fieldname)` placeholders are quoted as string literals suitable for the specified host language. This is meant to produce -- cgit v1.2.3 From 69057cf39f87ecfe7446b14aa7df87ccf19b1151 Mon Sep 17 00:00:00 2001 From: Andy Parkins Date: Mon, 5 Feb 2007 19:58:47 +0000 Subject: git-for-each-ref doesn't return "the bit after $GIT_DIR/refs" The documentation for git-for-each-ref said that the refname variable would return "the part after $GIT_DIR/refs/", which isn't true. Signed-off-by: Andy Parkins Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index da52eba7b3..f49b0d944c 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -66,7 +66,7 @@ keys. For all objects, the following names can be used: refname:: - The name of the ref (the part after $GIT_DIR/refs/). + The name of the ref (the part after $GIT_DIR/). objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). -- cgit v1.2.3 From 97925fde00743e557fa5e792004483a27e31fbd8 Mon Sep 17 00:00:00 2001 From: Matthias Kestenholz Date: Fri, 18 May 2007 15:39:34 +0200 Subject: Documentation: Reformatted SYNOPSIS for several commands Signed-off-by: Matthias Kestenholz Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index f49b0d944c..6df8e85004 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -7,7 +7,10 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- -'git-for-each-ref' [--count=]\* [--shell|--perl|--python|--tcl] [--sort=]\* [--format=] [] +[verse] +'git-for-each-ref' [--count=]\* + [--shell|--perl|--python|--tcl] + [--sort=]\* [--format=] [] DESCRIPTION ----------- -- cgit v1.2.3 From d392e712a844e6ce029aa901902e08a3da82f89d Mon Sep 17 00:00:00 2001 From: Andy Parkins Date: Fri, 28 Sep 2007 15:17:45 +0100 Subject: Make for-each-ref's grab_date() support per-atom formatting grab_date() gets an extra parameter - atomname; this extra parameter is checked to see if it has a ":" extra component in it, and if so that "" string is passed to parse_date_format() to produce an enum date_mode value which is then further passed to show_date(). In short it allows the user of git-for-each-ref to do things like this: $ git-for-each-ref --format='%(taggerdate:default)' refs/tags/v1.5.2 Sun May 20 00:30:42 2007 -0700 $ git-for-each-ref --format='%(taggerdate:relative)' refs/tags/v1.5.2 4 months ago $ git-for-each-ref --format='%(taggerdate:short)' refs/tags/v1.5.2 2007-05-20 $ git-for-each-ref --format='%(taggerdate:local)' refs/tags/v1.5.2 Sun May 20 08:30:42 2007 $ git-for-each-ref --format='%(taggerdate:iso8601)' refs/tags/v1.5.2 2007-05-20 00:30:42 -0700 $ git-for-each-ref --format='%(taggerdate:rfc2822)' refs/tags/v1.5.2 Sun, 20 May 2007 00:30:42 -0700 The default, when no ":" is specified is ":default", leaving the existing behaviour unchanged. Signed-off-by: Andy Parkins Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 6df8e85004..f1f90cca62 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -100,6 +100,11 @@ In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. +As a special case for the date-type fields, you may specify a format for +the date by adding one of `:default`, `:relative`, `:short`, `:local`, +`:iso8601` or `:rfc2822` to the end of the fieldname; e.g. +`%(taggerdate:relative)`. + EXAMPLES -------- -- cgit v1.2.3 From c0f6dc9b20523a569e567d3be4cabbc949c71b43 Mon Sep 17 00:00:00 2001 From: Lea Wiemann Date: Thu, 5 Jun 2008 23:01:38 +0200 Subject: git-for-each-ref.txt: minor improvements Rewrapped synopsis and removed wrong asterisk behind --count option; clarified --sort= description for multiple keys; documented that for-each-ref supports not only glob patterns but also prefixes like "refs/heads" as patterns, and that multiple patterns can be given. Signed-off-by: Lea Wiemann Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index f1f90cca62..6325ff9a68 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -8,9 +8,8 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- [verse] -'git-for-each-ref' [--count=]\* - [--shell|--perl|--python|--tcl] - [--sort=]\* [--format=] [] +'git-for-each-ref' [--count=] [--shell|--perl|--python|--tcl] + [--sort=]\* [--format=] [...] DESCRIPTION ----------- @@ -32,8 +31,9 @@ OPTIONS :: A field name to sort on. Prefix `-` to sort in descending order of the value. When unspecified, - `refname` is used. More than one sort keys can be - given. + `refname` is used. You may use the --sort= option + multiple times, in which case the last key becomes the primary + key. :: A string that interpolates `%(fieldname)` from the @@ -48,9 +48,10 @@ OPTIONS `%09` to `\t` (TAB) and `%0a` to `\n` (LF). :: - If given, the name of the ref is matched against this - using fnmatch(3). Refs that do not match the pattern - are not shown. + If one or more patterns are given, only refs are shown that + match againt at least one pattern, either using fnmatch(3) or + literally, in the latter case matching completely or from the + beginning up to a slash. --shell, --perl, --python, --tcl:: If given, strings that substitute `%(fieldname)` -- cgit v1.2.3 From 3240240ff427fa2e26a847c7c9fd89e6a4313daa Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Sun, 8 Jun 2008 03:36:09 +0200 Subject: Docs: Use "-l::\n--long\n" format in OPTIONS sections The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 6325ff9a68..b347bfbb14 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -53,7 +53,10 @@ OPTIONS literally, in the latter case matching completely or from the beginning up to a slash. ---shell, --perl, --python, --tcl:: +--shell:: +--perl:: +--python:: +--tcl:: If given, strings that substitute `%(fieldname)` placeholders are quoted as string literals suitable for the specified host language. This is meant to produce -- cgit v1.2.3 From b1889c36d85514e5e70462294c561a02c2edfe2b Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 01:09:04 -0500 Subject: Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command " in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index b347bfbb14..29c29f8830 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -8,7 +8,7 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- [verse] -'git-for-each-ref' [--count=] [--shell|--perl|--python|--tcl] +'git for-each-ref' [--count=] [--shell|--perl|--python|--tcl] [--sort=]\* [--format=] [...] DESCRIPTION @@ -119,7 +119,7 @@ An example directly producing formatted text. Show the most recent ------------ #!/bin/sh -git-for-each-ref --count=3 --sort='-*authordate' \ +git for-each-ref --count=3 --sort='-*authordate' \ --format='From: %(*authorname) %(*authoremail) Subject: %(*subject) Date: %(*authordate) @@ -135,7 +135,7 @@ demonstrating the use of --shell. List the prefixes of all heads:: ------------ #!/bin/sh -git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \ +git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ while read entry do eval "$entry" @@ -189,7 +189,7 @@ Its message reads as: fi ' -eval=`git-for-each-ref --shell --format="$fmt" \ +eval=`git for-each-ref --shell --format="$fmt" \ --sort='*objecttype' \ --sort=-taggerdate \ refs/tags` -- cgit v1.2.3 From ba020ef5eb5fca3d757bd580ff117adaf81ca079 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 3 Jul 2008 00:41:41 -0500 Subject: manpages: italicize git command names (which were in teletype font) The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 29c29f8830..727d84e673 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -79,7 +79,7 @@ objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). objectsize:: - The size of the object (the same as `git-cat-file -s` reports). + The size of the object (the same as 'git-cat-file -s' reports). objectname:: The object name (aka SHA-1). -- cgit v1.2.3 From f448e24e2fe336621306b04b84e947bdd04f7ecc Mon Sep 17 00:00:00 2001 From: Abhijit Menon-Sen Date: Wed, 30 Jul 2008 15:03:43 +0530 Subject: Make the DESCRIPTION match ... items in the SYNOPSIS When the SYNOPSIS says e.g. "...", it is nice if the DESCRIPTION also mentions "..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 727d84e673..609f9496ba 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -47,7 +47,7 @@ OPTIONS `xx`; for example `%00` interpolates to `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). -:: +...:: If one or more patterns are given, only refs are shown that match againt at least one pattern, either using fnmatch(3) or literally, in the latter case matching completely or from the -- cgit v1.2.3 From 1168d402d2962f56cbc921bbc954d8f2179c8ba7 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Tue, 5 Aug 2008 17:12:05 +0100 Subject: Documentation: typos / spelling fixes Signed-off-by: Mike Ralphson Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 609f9496ba..eae6c0e7bc 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -49,7 +49,7 @@ OPTIONS ...:: If one or more patterns are given, only refs are shown that - match againt at least one pattern, either using fnmatch(3) or + match against at least one pattern, either using fnmatch(3) or literally, in the latter case matching completely or from the beginning up to a slash. -- cgit v1.2.3 From d4040e0a1728035af34fc67907be088ca14d31c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?SZEDER=20G=C3=A1bor?= Date: Mon, 1 Sep 2008 23:02:09 +0200 Subject: Documentation: fix reference to a for-each-ref option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ... to match the synopsis section Signed-off-by: SZEDER Gábor Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index eae6c0e7bc..ebd7c5fbb3 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -16,7 +16,7 @@ DESCRIPTION Iterate over all refs that match `` and show them according to the given ``, after sorting them according -to the given set of ``. If `` is given, stop after +to the given set of ``. If `` is given, stop after showing that many refs. The interpolated values in `` can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. -- cgit v1.2.3 From 7d66f21a1bfd2d6ea8b1e234befbcc187111cee6 Mon Sep 17 00:00:00 2001 From: Bert Wesarg Date: Fri, 5 Sep 2008 23:16:23 +0200 Subject: for-each-ref: `:short` format for `refname` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tries to shorten the refname to a non-ambiguous name. Szeder Gábor noticed that the git bash completion takes a tremendous amount of time to strip leading components from heads and tags refs (i.e. refs/heads, refs/tags, ...). He proposed a new atom called 'refbasename' which removes at most two leading components from the ref name. I myself, proposed a more dynamic solution, which strips off common leading components with the matched pattern. But the current bash solution and both proposals suffer from one mayor problem: ambiguous refs. A ref is ambiguous, if it resolves to more than one full refs. I.e. given the refs refs/heads/xyzzy and refs/tags/xyzzy. The (short) ref xyzzy can point to both refs. ( Note: Its irrelevant whether the referenced objects are the same or not. ) This proposal solves this by checking for ambiguity of the shorten ref name. The shortening is done with the same rules for resolving refs but in the reverse order. The short name is checked if it resolves to a different ref. To continue the above example, the output would be like this: heads/xyzzy xyzzy So, if you want just tags, xyzzy is not ambiguous, because it will resolve to a tag. If you need the heads you get a also a non-ambiguous short form of the ref. To integrate this new format into the bash completion to get only non-ambiguous refs is beyond the scope of this patch. Signed-off-by: Bert Wesarg Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index ebd7c5fbb3..5061d3e4e7 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -74,6 +74,7 @@ For all objects, the following names can be used: refname:: The name of the ref (the part after $GIT_DIR/). + For a non-ambiguous short name of the ref append `:short`. objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). -- cgit v1.2.3 From 8cae19d987b1bbd43258558f591e39d9d216dcb3 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Tue, 7 Apr 2009 03:09:39 -0400 Subject: for-each-ref: add "upstream" format field The logic for determining the upstream ref of a branch is somewhat complex to perform in a shell script. This patch provides a plumbing mechanism for scripts to access the C logic used internally by git-status, git-branch, etc. For example: $ git for-each-ref \ --format='%(refname:short) %(upstream:short)' \ refs/heads/ master origin/master Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 5061d3e4e7..b362e9ed12 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -85,6 +85,11 @@ objectsize:: objectname:: The object name (aka SHA-1). +upstream:: + The name of a local ref which can be considered ``upstream'' + from the displayed ref. Respects `:short` in the same way as + `refname` above. + 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. -- cgit v1.2.3 From 2bb98169be7b0ac4f70815b4490904c652edae61 Mon Sep 17 00:00:00 2001 From: Bert Wesarg Date: Mon, 13 Apr 2009 12:25:47 +0200 Subject: for-each-ref: utilize core.warnAmbiguousRefs for :short-format core.warnAmbiguousRefs is used to select strict mode for the abbreviation for the ":short" format specifier of "refname" and "upstream". In strict mode, the abbreviated ref will never trigger the 'warn_ambiguous_refs' warning. I.e. for these refs: refs/heads/xyzzy refs/tags/xyzzy the abbreviated forms are: heads/xyzzy tags/xyzzy Signed-off-by: Bert Wesarg Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index b362e9ed12..8dc873fd44 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -75,6 +75,8 @@ For all objects, the following names can be used: refname:: The name of the ref (the part after $GIT_DIR/). For a non-ambiguous short name of the ref append `:short`. + The option core.warnAmbiguousRefs is used to select the strict + abbreviation mode. objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). -- cgit v1.2.3 From 0b444cdb19bcfcc7f59b7b00783cbfbbc5ddcf63 Mon Sep 17 00:00:00 2001 From: Thomas Rast Date: Sun, 10 Jan 2010 00:33:00 +0100 Subject: Documentation: spell 'git cmd' without dash throughout The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH. --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 8dc873fd44..7e83288d18 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -82,7 +82,7 @@ objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). objectsize:: - The size of the object (the same as 'git-cat-file -s' reports). + The size of the object (the same as 'git cat-file -s' reports). objectname:: The object name (aka SHA-1). -- cgit v1.2.3 From 67687feae52ff2d3ab7edf3ac42a39c5e44be299 Mon Sep 17 00:00:00 2001 From: Michael J Gruber Date: Thu, 13 May 2010 14:31:46 +0200 Subject: for-each-ref: Field with abbreviated objectname Introduce a :short modifier to objectname which outputs the abbreviated object name. Signed-off-by: Michael J Gruber Reviewed-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 7e83288d18..390d85ccae 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -86,6 +86,7 @@ objectsize:: objectname:: The object name (aka SHA-1). + For a non-ambiguous abbreviation of the object name append `:short`. upstream:: The name of a local ref which can be considered ``upstream'' -- cgit v1.2.3 From 12378c0aa8d06cb0e965935ca6d393a9b66b095a Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Fri, 20 Aug 2010 05:31:58 -0500 Subject: Documentation: remove backslashes in manpage synopses For some reason, various manual pages have an asterisk escaped with \ in the synopsis. Since there is no other asterisk to pair it with, Asciidoc does not consider this asterisk escapable, so it passes the backslash through. Each page either uses [verse] or has only one asterisk, so it is safe to drop the backslashes (checked with asciidoc 8.5.2). Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 390d85ccae..d66fd9d231 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git for-each-ref' [--count=] [--shell|--perl|--python|--tcl] - [--sort=]\* [--format=] [...] + [--sort=]* [--format=] [...] DESCRIPTION ----------- -- cgit v1.2.3 From 0adda9362ab080b0994355c5a3183a896a606cc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= Date: Fri, 8 Oct 2010 19:31:17 +0200 Subject: Use parentheses and `...' where appropriate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove some stray usage of other bracket types and asterisks for the same purpose. Signed-off-by: Štěpán Němec Acked-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index d66fd9d231..fac1cf55e5 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git for-each-ref' [--count=] [--shell|--perl|--python|--tcl] - [--sort=]* [--format=] [...] + [(--sort=)...] [--format=] [...] DESCRIPTION ----------- -- cgit v1.2.3 From 22817b400cefe320b89065ee4c7a6864957e1f00 Mon Sep 17 00:00:00 2001 From: Alexei Sholik Date: Tue, 8 Mar 2011 15:16:09 +0200 Subject: Documentation: remove redundant colons in git-for-each-ref.txt Signed-off-by: Alexei Sholik Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index fac1cf55e5..bffb5d24f8 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -123,7 +123,7 @@ EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/bin/sh @@ -140,7 +140,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads:: +demonstrating the use of --shell. List the prefixes of all heads: ------------ #!/bin/sh @@ -154,7 +154,7 @@ done A bit more elaborate report on tags, demonstrating that the format -may be an entire script:: +may be an entire script: ------------ #!/bin/sh -- cgit v1.2.3 From 621c39de223f80d7014c39c5791db8b2b066fa18 Mon Sep 17 00:00:00 2001 From: Alexei Sholik Date: Tue, 8 Mar 2011 15:16:10 +0200 Subject: Add Author and Documentation sections to git-for-each-ref.txt Signed-off-by: Alexei Sholik Signed-off-by: Junio C Hamano --- Documentation/git-for-each-ref.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation/git-for-each-ref.txt') diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index bffb5d24f8..152e695c81 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -204,3 +204,15 @@ eval=`git for-each-ref --shell --format="$fmt" \ refs/tags` eval "$eval" ------------ + +Author +------ +Written by Junio C Hamano . + +Documentation +------------- +Documentation by Junio C Hamano and the git-list . + +GIT +--- +Part of the linkgit:git[1] suite -- cgit v1.2.3