From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 20 Jan 2016 19:43:30 +0000 (-0800)
Subject: Merge branch 'ew/for-each-ref-doc'
X-Git-Tag: v2.8.0-rc0~113
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/108cb77c868b541bb9bee43e9bfe9310827e1eb7?hp=-c

Merge branch 'ew/for-each-ref-doc'

* ew/for-each-ref-doc:
for-each-ref: document `creatordate` and `creator` fields
---

108cb77c868b541bb9bee43e9bfe9310827e1eb7
diff --combined Documentation/git-for-each-ref.txt
index c6f073cea4,338a6efa81..06208c4990
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@@ -10,8 -10,6 +10,8 @@@ SYNOPSI
  [verse]
  'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
  		   [(--sort=<key>)...] [--format=<format>] [<pattern>...]
 +		   [--points-at <object>] [(--merged | --no-merged) [<object>]]
 +		   [--contains [<object>]]
  
  DESCRIPTION
  -----------
@@@ -64,20 -62,6 +64,20 @@@ OPTION
  	the specified host language.  This is meant to produce
  	a scriptlet that can directly be `eval`ed.
  
 +--points-at <object>::
 +	Only list refs which points at the given object.
 +
 +--merged [<object>]::
 +	Only list refs whose tips are reachable from the
 +	specified commit (HEAD if not specified).
 +
 +--no-merged [<object>]::
 +	Only list refs whose tips are not reachable from the
 +	specified commit (HEAD if not specified).
 +
 +--contains [<object>]::
 +	Only list tags which contain the specified commit (HEAD if not
 +	specified).
  
  FIELD NAMES
  -----------
@@@ -113,12 -97,6 +113,12 @@@ upstream:
  	or "=" (in sync).  Has no effect if the ref does not have
  	tracking information associated with it.
  
 +push::
 +	The name of a local ref which represents the `@{push}` location
 +	for the displayed ref. Respects `:short`, `:track`, and
 +	`:trackshort` options as `upstream` does. Produces an empty
 +	string if no `@{push}` ref is configured.
 +
  HEAD::
  	'*' if HEAD matches current ref (the checked out branch), ' '
  	otherwise.
@@@ -127,21 -105,15 +127,26 @@@ color:
  	Change output color.  Followed by `:<colorname>`, where names
  	are described in `color.branch.*`.
  
 +align::
 +	Left-, middle-, or right-align the content between
 +	%(align:...) and %(end). The "align:" is followed by `<width>`
 +	and `<position>` in any order separated by a comma, where the
 +	`<position>` is either left, right or middle, default being
 +	left and `<width>` is the total length of the content with
 +	alignment. If the contents length is more than the width then
 +	no alignment is performed. If used with '--quote' everything
 +	in between %(align:...) and %(end) is quoted, but if nested
 +	then only the topmost level performs quoting.
 +
  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.
  
+ For commit and tag objects, the special `creatordate` and `creator`
+ fields will correspond to the appropriate date or name-email-date tuple
+ from the `committer` or `tagger` fields depending on the object type.
+ These are intended for working on a mix of annotated and lightweight tags.
+ 
  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.
@@@ -150,23 -122,20 +155,23 @@@ The complete message in a commit and ta
  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`.
 +blank line.  The optional GPG signature is `contents:signature`.  The
 +first `N` lines of the message is obtained using `contents:lines=N`.
  
- For sorting purposes, fields with numeric values sort in numeric
- order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
+ For sorting purposes, fields with numeric values sort in numeric order
+ (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).
  All other fields are used to sort in their byte-value order.
  
 +There is also an option to sort by versions, this can be done by using
 +the fieldname `version:refname` or its alias `v:refname`.
 +
  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)`.
 +the date by adding `:` followed by date format name (see the
 +values the `--date` option to linkgit::git-rev-list[1] takes).
  
  
  EXAMPLES