about summary refs log tree commit diff
path: root/third_party/git/Documentation/git-for-each-ref.txt
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/Documentation/git-for-each-ref.txt')
-rw-r--r--third_party/git/Documentation/git-for-each-ref.txt420
1 files changed, 0 insertions, 420 deletions
diff --git a/third_party/git/Documentation/git-for-each-ref.txt b/third_party/git/Documentation/git-for-each-ref.txt
deleted file mode 100644
index 2962f85a502a..000000000000
--- a/third_party/git/Documentation/git-for-each-ref.txt
+++ /dev/null
@@ -1,420 +0,0 @@
-git-for-each-ref(1)
-===================
-
-NAME
-----
-git-for-each-ref - Output information on each ref
-
-SYNOPSIS
---------
-[verse]
-'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
-		   [(--sort=<key>)...] [--format=<format>] [<pattern>...]
-		   [--points-at=<object>]
-		   [--merged[=<object>]] [--no-merged[=<object>]]
-		   [--contains[=<object>]] [--no-contains[=<object>]]
-
-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 `<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.
-
-OPTIONS
--------
-<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.
-
---count=<count>::
-	By default the command shows all refs that match
-	`<pattern>`.  This option makes it stop after showing
-	that many refs.
-
---sort=<key>::
-	A field name to sort on.  Prefix `-` to sort in
-	descending order of the value.  When unspecified,
-	`refname` is used.  You may use the --sort=<key> option
-	multiple times, in which case the last key becomes the primary
-	key.
-
---format=<format>::
-	A string that interpolates `%(fieldname)` from a ref being shown
-	and the object it points at.  If `fieldname`
-	is prefixed with an asterisk (`*`) and the ref points
-	at a tag object, use the value for the field in the object
-	which the tag object refers to (instead of the field in the tag object).
-	When unspecified, `<format>` defaults to
-	`%(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).
-
---color[=<when>]::
-	Respect any colors specified in the `--format` option. The
-	`<when>` field must be one of `always`, `never`, or `auto` (if
-	`<when>` is absent, behave as if `always` was given).
-
---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
-	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 refs which contain the specified commit (HEAD if not
-	specified).
-
---no-contains[=<object>]::
-	Only list refs which don't contain the specified commit (HEAD
-	if not specified).
-
---ignore-case::
-	Sorting and filtering refs are case insensitive.
-
-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/).
-	For a non-ambiguous short name of the ref append `:short`.
-	The option core.warnAmbiguousRefs is used to select the strict
-	abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>`
-	slash-separated path components from the front (back) of the refname
-	(e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
-	`%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
-	If `<N>` is a negative number, strip as many path components as
-	necessary from the specified end to leave `-<N>` path components
-	(e.g. `%(refname:lstrip=-2)` turns
-	`refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
-	turns `refs/tags/foo` into `refs`). When the ref does not have
-	enough components, the result becomes an empty string if
-	stripping with positive <N>, or it becomes the full refname if
-	stripping with negative <N>.  Neither is an error.
-+
-`strip` can be used as a synonym to `lstrip`.
-
-objecttype::
-	The type of the object (`blob`, `tree`, `commit`, `tag`).
-
-objectsize::
-	The size of the object (the same as 'git cat-file -s' reports).
-	Append `:disk` to get the size, in bytes, that the object takes up on
-	disk. See the note about on-disk sizes in the `CAVEATS` section below.
-objectname::
-	The object name (aka SHA-1).
-	For a non-ambiguous abbreviation of the object name append `:short`.
-	For an abbreviation of the object name with desired length append
-	`:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
-	length may be exceeded to ensure unique object names.
-deltabase::
-	This expands to the object name of the delta base for the
-	given object, if it is stored as a delta.  Otherwise it
-	expands to the null object name (all zeroes).
-
-upstream::
-	The name of a local ref which can be considered ``upstream''
-	from the displayed ref. Respects `:short`, `:lstrip` and
-	`:rstrip` 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). `:track`
-	also prints "[gone]" whenever unknown upstream ref is
-	encountered. Append `:track,nobracket` to show tracking
-	information without brackets (i.e "ahead N, behind M").
-+
-For any remote-tracking branch `%(upstream)`, `%(upstream:remotename)`
-and `%(upstream:remoteref)` refer to the name of the remote and the
-name of the tracked remote ref, respectively. In other words, the
-remote-tracking branch can be updated explicitly and individually by
-using the refspec `%(upstream:remoteref):%(upstream)` to fetch from
-`%(upstream:remotename)`.
-+
-Has no effect if the ref does not have tracking information associated
-with it.  All the options apart from `nobracket` are mutually exclusive,
-but if used together the last option is selected.
-
-push::
-	The name of a local ref which represents the `@{push}`
-	location for the displayed ref. Respects `:short`, `:lstrip`,
-	`:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`
-	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.
-
-color::
-	Change output color. Followed by `:<colorname>`, where color
-	names are described under Values in the "CONFIGURATION FILE"
-	section of linkgit:git-config[1].  For example,
-	`%(color:bold red)`.
-
-align::
-	Left-, middle-, or right-align the content between
-	%(align:...) and %(end). The "align:" is followed by
-	`width=<width>` and `position=<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. For brevity, the
-	"width=" and/or "position=" prefixes may be omitted, and bare
-	<width> and <position> used instead.  For instance,
-	`%(align:<width>,<position>)`. 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.
-
-if::
-	Used as %(if)...%(then)...%(end) or
-	%(if)...%(then)...%(else)...%(end).  If there is an atom with
-	value or string literal after the %(if) then everything after
-	the %(then) is printed, else if the %(else) atom is used, then
-	everything after %(else) is printed. We ignore space when
-	evaluating the string before %(then), this is useful when we
-	use the %(HEAD) atom which prints either "*" or " " and we
-	want to apply the 'if' condition only on the 'HEAD' ref.
-	Append ":equals=<string>" or ":notequals=<string>" to compare
-	the value between the %(if:...) and %(then) atoms with the
-	given string.
-
-symref::
-	The ref which the given symbolic ref refers to. If not a
-	symbolic ref, nothing is printed. Respects the `:short`,
-	`:lstrip` and `:rstrip` options in the same way as `refname`
-	above.
-
-worktreepath::
-	The absolute path to the worktree in which the ref is checked
-	out, if it is checked out in any linked worktree. Empty string
-	otherwise.
-
-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 `tree` and `parent` can also be used with modifier `:short` and
-`:short=<length>` just like `objectname`.
-
-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.  For email fields (`authoremail`,
-`committeremail` and `taggeremail`), `:trim` can be appended to get the email
-without angle brackets, and `:localpart` to get the part before the `@` symbol
-out of the trimmed email.
-
-The message in a commit or a tag object is `contents`, from which
-`contents:<part>` can be used to extract various parts out of:
-
-contents:size::
-	The size in bytes of the commit or tag message.
-
-contents:subject::
-	The first paragraph of the message, which typically is a
-	single line, is taken as the "subject" of the commit or the
-	tag message.
-	Instead of `contents:subject`, field `subject` can also be used to
-	obtain same results. `:sanitize` can be appended to `subject` for
-	subject line suitable for filename.
-
-contents:body::
-	The remainder of the commit or the tag message that follows
-	the "subject".
-
-contents:signature::
-	The optional GPG signature of the tag.
-
-contents:lines=N::
-	The first `N` lines of the message.
-
-Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
-are obtained as `trailers` (or by using the historical alias
-`contents:trailers`).  Non-trailer lines from the trailer block can be omitted
-with `trailers:only`. Whitespace-continuations can be removed from trailers so
-that each trailer appears on a line by itself with its full content with
-`trailers:unfold`. Both can be used together as `trailers:unfold,only`.
-
-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 `:` followed by date format name (see the
-values the `--date` option to linkgit:git-rev-list[1] takes).
-
-Some atoms like %(align) and %(if) always require a matching %(end).
-We call them "opening atoms" and sometimes denote them as %($open).
-
-When a scripting language specific quoting is in effect, everything
-between a top-level opening atom and its matching %(end) is evaluated
-according to the semantics of the opening atom and only its result
-from the top-level is quoted.
-
-
-EXAMPLES
---------
-
-An example directly producing formatted text.  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 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
-
-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 --shell --format="$fmt" \
-	--sort='*objecttype' \
-	--sort=-taggerdate \
-	refs/tags`
-eval "$eval"
-------------
-
-
-An example to show the usage of %(if)...%(then)...%(else)...%(end).
-This prefixes the current branch with a star.
-
-------------
-git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/
-------------
-
-
-An example to show the usage of %(if)...%(then)...%(end).
-This prints the authorname, if present.
-
-------------
-git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
-------------
-
-CAVEATS
--------
-
-Note that the sizes of objects on disk are reported accurately, but care
-should be taken in drawing conclusions about which refs or objects are
-responsible for disk usage. The size of a packed non-delta object may be
-much larger than the size of objects which delta against it, but the
-choice of which object is the base and which is the delta is arbitrary
-and is subject to change during a repack.
-
-Note also that multiple copies of an object may be present in the object
-database; in this case, it is undefined which copy's size or delta base
-will be reported.
-
-NOTES
------
-
-include::ref-reachability-filters.txt[]
-
-SEE ALSO
---------
-linkgit:git-show-ref[1]
-
-GIT
----
-Part of the linkgit:git[1] suite