.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
-.TH "GIT\-BLAME" "1" "10/03/2006" "" ""
+.TH "GIT\-BLAME" "1" "10/25/2006" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.SH "NAME"
git\-blame \- Show what revision and author last modified each line of a file
.SH "SYNOPSIS"
-\fIgit\-blame\fR [\-c] [\-l] [\-t] [\-S <revs\-file>] [\-\-] <file> [<rev>]
+\fIgit\-blame\fR [\-c] [\-l] [\-t] [\-f] [\-n] [\-p] [\-S <revs\-file>] [\-\-] <file> [<rev>]
.sp
.SH "DESCRIPTION"
Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision.
Use revs from revs\-file instead of calling
\fBgit\-rev\-list\fR(1).
.TP
+\-f, \-\-show\-name
+Show filename in the original commit. By default filename is shown if there is any line that came from a file with different name, due to rename detection.
+.TP
+\-n, \-\-show\-number
+Show line number in the original commit (Default: off).
+.TP
+\-p, \-\-porcelain
+Show in a format designed for machine consumption.
+.TP
\-h, \-\-help
Show help message.
+.SH "THE PORCELAIN FORMAT"
+In this format, each line is output after a header; the header at the minumum has the first line which has:
+.sp
+.TP 3
+\(bu
+40\-byte SHA\-1 of the commit the line is attributed to;
+.TP
+\(bu
+the line number of the line in the original file;
+.TP
+\(bu
+the line number of the line in the final file;
+.TP
+\(bu
+on a line that starts a group of line from a different commit than the previous one, the number of lines in this group. On subsequent lines this field is absent.
+This header line is followed by the following information at least once for each commit:
+.sp
+.TP 3
+\(bu
+author name ("author"), email ("author\-mail"), time ("author\-time"), and timezone ("author\-tz"); similarly for committer.
+.TP
+\(bu
+filename in the commit the line is attributed to.
+.TP
+\(bu
+the first line of the commit log message ("summary").
+The contents of the actual line is output after the above header, prefixed by a TAB. This is to allow adding more header elements later.
+.sp
.SH "SEE ALSO"
\fBgit\-annotate\fR(1)
.sp
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
-.TH "GIT\-CHERRY" "1" "10/03/2006" "" ""
+.TH "GIT\-CHERRY" "1" "10/25/2006" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.SH "DESCRIPTION"
The changeset (or "diff") of each commit between the fork\-point and <head> is compared against each commit between the fork\-point and <upstream>.
.sp
-Every commit with a changeset that doesn't exist in the other branch has its id (sha1) reported, prefixed by a symbol. Those existing only in the <upstream> branch are prefixed with a minus (\-) sign, and those that only exist in the <head> branch are prefixed with a plus (+) symbol.
+Every commit that doesn't exist in the <upstream> branch has its id (sha1) reported, prefixed by a symbol. The ones that have equivalent change already in the <upstream> branch are prefixed with a minus (\-) sign, and those that only exist in the <head> branch are prefixed with a plus (+) symbol.
.sp
Because git\-cherry compares the changeset rather than the commit id (sha1), you can use git\-cherry to find out if a commit you made locally has been applied <upstream> under a different commit id. For example, this will happen if you're feeding patches <upstream> via email rather than pushing or pulling commits directly.
.sp
--- /dev/null
+.\" ** You probably do not want to edit this file directly **
+.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
+.\" Instead of manually editing it, you probably should edit the DocBook XML
+.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
+.TH "GIT\-FOR\-EACH\-REF" "1" "10/25/2006" "" ""
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+git\-for\-each\-ref \- Output information on each ref
+.SH "SYNOPSIS"
+\fIgit\-for\-each\-ref\fR [\-\-count=<count>]\fB [\-\-shell|\-\-perl|\-\-python] [\-\-sort=<key>]\fR [\-\-format=<format>] [<pattern>]
+.sp
+.SH "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>`s. If <max> is given, stop after showing that many refs. The interporated values in <format>` can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language.
+.sp
+.SH "OPTIONS"
+.TP
+<count>
+By default the command shows all refs that match
+<pattern>. This option makes it stop after showing that many refs.
+.TP
+<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.
+.TP
+<format>
+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).
+.TP
+<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.
+.TP
+\-\-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.
+.SH "FIELD NAMES"
+Various values from structured fields in referenced objects can be used to interpolate into the resulting output, or as sort keys.
+.sp
+For all objects, the following names can be used:
+.sp
+.TP
+refname
+The name of the ref (the part after $GIT_DIR/refs/).
+.TP
+objecttype
+The type of the object (blob,
+tree,
+commit,
+tag).
+.TP
+objectsize
+The size of the object (the same as
+git\-cat\-file \-s
+reports).
+.TP
+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.
+.sp
+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.
+.sp
+The first line of the message in a commit and tag object is subject, the remaining lines are body. The whole message is contents.
+.sp
+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.
+.sp
+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.
+.sp
+.SH "EXAMPLES"
+An example directly producing formatted text. Show the most recent 3 tagged commits::
+.sp
+.sp
+.nf
+#!/bin/sh
+
+git\-for\-each\-ref \-\-count=3 \-\-sort='\-*authordate' \\
+\-\-format='From: %(*authorname) %(*authoremail)
+Subject: %(*subject)
+Date: %(*authordate)
+Ref: %(*refname)
+
+%(*body)
+\' 'refs/tags'
+.fi
+A simple example showing the use of shell eval on the output, demonstrating the use of \-\-shell. List the prefixes of all heads::
+.sp
+.sp
+.nf
+#!/bin/sh
+
+git\-for\-each\-ref \-\-shell \-\-format="ref=%(refname)" refs/heads | \\
+while read entry
+do
+ eval "$entry"
+ echo `dirname $ref`
+done
+.fi
+A bit more elaborate report on tags, demonstrating that the format may be an entire script::
+.sp
+.sp
+.nf
+#!/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"
+.fi
projects / git.git / commitdiff