diff options
Diffstat (limited to 'Documentation/git-for-each-ref.txt')
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 81 |
1 files changed, 62 insertions, 19 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index f49b0d944c..42408752d0 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -7,14 +7,16 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- -'git-for-each-ref' [--count=<count>]\* [--shell|--perl|--python|--tcl] [--sort=<key>]\* [--format=<format>] [<pattern>] +[verse] +'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] + [(--sort=<key>)...] [--format=<format>] [<pattern>...] DESCRIPTION ----------- Iterate over all refs that match `<pattern>` and show them according to the given `<format>`, after sorting them according -to the given set of `<key>`. If `<max>` is given, stop after +to the given set of `<key>`. If `<count>` is given, stop after showing that many refs. The interpolated values in `<format>` can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language. @@ -29,8 +31,9 @@ OPTIONS <key>:: 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=<key> option + multiple times, in which case the last key becomes the primary + key. <format>:: A string that interpolates `%(fieldname)` from the @@ -44,12 +47,16 @@ OPTIONS `xx`; for example `%00` interpolates to `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). -<pattern>:: - If given, the name of the ref is matched against this - using fnmatch(3). Refs that do not match the pattern - are not shown. +<pattern>...:: + If one or more patterns are given, only refs are shown that + 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. ---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 @@ -67,15 +74,36 @@ 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`). 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). + For a non-ambiguous abbreviation of the object name append `:short`. + +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. Additionally respects `:track` to show + "[ahead N, behind M]" and `:trackshort` to show the terse + version: ">" (ahead), "<" (behind), "<>" (ahead and behind), + or "=" (in sync). Has no effect if the ref does not have + tracking information associated with it. + +HEAD:: + '*' if HEAD matches current ref (the checked out branch), ' ' + otherwise. + +color:: + Change output color. Followed by `:<colorname>`, where names + are described in `color.branch.*`. In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can @@ -85,9 +113,11 @@ 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`. +The complete message in a commit and tag object is `contents`. +Its first line is `contents:subject`, where subject is the concatenation +of all lines of the commit message up to the first blank line. The next +line is 'contents:body', where body is all of the lines after the first +blank line. Finally, the optional GPG signature is `contents:signature`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). @@ -97,17 +127,22 @@ 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`, `:rfc2822` or `:raw` to the end of the fieldname; e.g. +`%(taggerdate:relative)`. + EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/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) @@ -119,11 +154,11 @@ 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 -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" @@ -133,7 +168,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 @@ -177,9 +212,17 @@ 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` eval "$eval" ------------ + +SEE ALSO +-------- +linkgit:git-show-ref[1] + +GIT +--- +Part of the linkgit:git[1] suite |