git-annotate.1 (10074B)
- '\" t
- .\" Title: git-annotate
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-ANNOTATE" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- git-annotate \- Annotate file lines with commit information
- .SH "SYNOPSIS"
- .sp
- .nf
- \fIgit annotate\fR [<options>] [<rev\-opts>] [<rev>] [\-\-] <file>
- .fi
- .SH "DESCRIPTION"
- .sp
- Annotates each line in the given file with information from the commit which introduced the line\&. Optionally annotates from a given revision\&.
- .sp
- The only difference between this command and \fBgit-blame\fR(1) is that they use slightly different output formats, and this command exists only for backward compatibility to support existing scripts, and provide a more familiar command name for people coming from other SCM systems\&.
- .SH "OPTIONS"
- .PP
- \-b
- .RS 4
- Show blank SHA\-1 for boundary commits\&. This can also be controlled via the
- \fBblame\&.blankBoundary\fR
- config option\&.
- .RE
- .PP
- \-\-root
- .RS 4
- Do not treat root commits as boundaries\&. This can also be controlled via the
- \fBblame\&.showRoot\fR
- config option\&.
- .RE
- .PP
- \-\-show\-stats
- .RS 4
- Include additional statistics at the end of blame output\&.
- .RE
- .PP
- \-L <start>,<end>, \-L :<funcname>
- .RS 4
- Annotate only the line range given by
- \fI<start>,<end>\fR, or by the function name regex
- \fI<funcname>\fR\&. May be specified multiple times\&. Overlapping ranges are allowed\&.
- .sp
- \fI<start>\fR
- and
- \fI<end>\fR
- are optional\&.
- \fB\-L\fR
- \fI<start>\fR
- or
- \fB\-L\fR
- \fI<start>\fR\fB,\fR
- spans from
- \fI<start>\fR
- to end of file\&.
- \fB\-L\fR
- \fB,\fR\fI<end>\fR
- spans from start of file to
- \fI<end>\fR\&.
- .sp
- \fI<start>\fR
- and
- \fI<end>\fR
- can take one of these forms:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- number
- .sp
- If
- \fI<start>\fR
- or
- \fI<end>\fR
- is a number, it specifies an absolute line number (lines count from 1)\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- \fB/regex/\fR
- .sp
- This form will use the first line matching the given POSIX regex\&. If
- \fI<start>\fR
- is a regex, it will search from the end of the previous
- \fB\-L\fR
- range, if any, otherwise from the start of file\&. If
- \fI<start>\fR
- is
- \fB^/regex/\fR, it will search from the start of file\&. If
- \fI<end>\fR
- is a regex, it will search starting at the line given by
- \fI<start>\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- +offset or \-offset
- .sp
- This is only valid for
- \fI<end>\fR
- and will specify a number of lines before or after the line given by
- \fI<start>\fR\&.
- .RE
- .sp
- If
- \fB:\fR\fI<funcname>\fR
- is given in place of
- \fI<start>\fR
- and
- \fI<end>\fR, it is a regular expression that denotes the range from the first funcname line that matches
- \fI<funcname>\fR, up to the next funcname line\&.
- \fB:\fR\fI<funcname>\fR
- searches from the end of the previous
- \fB\-L\fR
- range, if any, otherwise from the start of file\&.
- \fB^:\fR\fI<funcname>\fR
- searches from the start of file\&. The function names are determined in the same way as
- \fBgit\fR
- \fBdiff\fR
- works out patch hunk headers (see
- \fIDefining a custom hunk\-header\fR
- in
- \fBgitattributes\fR(5))\&.
- .RE
- .PP
- \-l
- .RS 4
- Show long rev (Default: off)\&.
- .RE
- .PP
- \-t
- .RS 4
- Show raw timestamp (Default: off)\&.
- .RE
- .PP
- \-S <revs\-file>
- .RS 4
- Use revisions from revs\-file instead of calling
- \fBgit-rev-list\fR(1)\&.
- .RE
- .PP
- \-\-reverse <rev>\&.\&.<rev>
- .RS 4
- Walk history forward instead of backward\&. Instead of showing the revision in which a line appeared, this shows the last revision in which a line has existed\&. This requires a range of revision like START\&.\&.END where the path to blame exists in START\&.
- \fBgit\fR
- \fBblame\fR
- \fB\-\-reverse\fR
- \fBSTART\fR
- is taken as
- \fBgit\fR
- \fBblame\fR
- \fB\-\-reverse\fR
- \fBSTART\fR\fB\&.\&.\fR\fBHEAD\fR
- for convenience\&.
- .RE
- .PP
- \-\-first\-parent
- .RS 4
- Follow only the first parent commit upon seeing a merge commit\&. This option can be used to determine when a line was introduced to a particular integration branch, rather than when it was introduced to the history overall\&.
- .RE
- .PP
- \-p, \-\-porcelain
- .RS 4
- Show in a format designed for machine consumption\&.
- .RE
- .PP
- \-\-line\-porcelain
- .RS 4
- Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced\&. Implies \-\-porcelain\&.
- .RE
- .PP
- \-\-incremental
- .RS 4
- Show the result incrementally in a format designed for machine consumption\&.
- .RE
- .PP
- \-\-encoding=<encoding>
- .RS 4
- Specifies the encoding used to output author names and commit summaries\&. Setting it to
- \fBnone\fR
- makes blame output unconverted data\&. For more information see the discussion about encoding in the
- \fBgit-log\fR(1)
- manual page\&.
- .RE
- .PP
- \-\-contents <file>
- .RS 4
- Annotate using the contents from the named file, starting from <rev> if it is specified, and HEAD otherwise\&. You may specify
- \fI\-\fR
- to make the command read from the standard input for the file contents\&.
- .RE
- .PP
- \-\-date <format>
- .RS 4
- Specifies the format used to output dates\&. If \-\-date is not provided, the value of the blame\&.date config variable is used\&. If the blame\&.date config variable is also not set, the iso format is used\&. For supported values, see the discussion of the \-\-date option at
- \fBgit-log\fR(1)\&.
- .RE
- .PP
- \-\-[no\-]progress
- .RS 4
- Progress status is reported on the standard error stream by default when it is attached to a terminal\&. This flag enables progress reporting even if not attached to a terminal\&. Can\(cqt use
- \fB\-\-progress\fR
- together with
- \fB\-\-porcelain\fR
- or
- \fB\-\-incremental\fR\&.
- .RE
- .PP
- \-M[<num>]
- .RS 4
- Detect moved or copied lines within a file\&. When a commit moves or copies a block of lines (e\&.g\&. the original file has A and then B, and the commit changes it to B and then A), the traditional
- \fIblame\fR
- algorithm notices only half of the movement and typically blames the lines that were moved up (i\&.e\&. B) to the parent and assigns blame to the lines that were moved down (i\&.e\&. A) to the child commit\&. With this option, both groups of lines are blamed on the parent by running extra passes of inspection\&.
- .sp
- <num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit\&. The default value is 20\&.
- .RE
- .PP
- \-C[<num>]
- .RS 4
- In addition to
- \fB\-M\fR, detect lines moved or copied from other files that were modified in the same commit\&. This is useful when you reorganize your program and move code around across files\&. When this option is given twice, the command additionally looks for copies from other files in the commit that creates the file\&. When this option is given three times, the command additionally looks for copies from other files in any commit\&.
- .sp
- <num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit\&. And the default value is 40\&. If there are more than one
- \fB\-C\fR
- options given, the <num> argument of the last
- \fB\-C\fR
- will take effect\&.
- .RE
- .PP
- \-\-ignore\-rev <rev>
- .RS 4
- Ignore changes made by the revision when assigning blame, as if the change never happened\&. Lines that were changed or added by an ignored commit will be blamed on the previous commit that changed that line or nearby lines\&. This option may be specified multiple times to ignore more than one revision\&. If the
- \fBblame\&.markIgnoredLines\fR
- config option is set, then lines that were changed by an ignored commit and attributed to another commit will be marked with a ? in the blame output\&. If the
- \fBblame\&.markUnblamableLines\fR
- config option is set, then those lines touched by an ignored commit that we could not attribute to another revision are marked with a
- \fI*\fR\&.
- .RE
- .PP
- \-\-ignore\-revs\-file <file>
- .RS 4
- Ignore revisions listed in
- \fBfile\fR, which must be in the same format as an
- \fBfsck\&.skipList\fR\&. This option may be repeated, and these files will be processed after any files specified with the
- \fBblame\&.ignoreRevsFile\fR
- config option\&. An empty file name, "", will clear the list of revs from previously processed files\&.
- .RE
- .PP
- \-\-color\-lines
- .RS 4
- Color line annotations in the default format differently if they come from the same commit as the preceding line\&. This makes it easier to distinguish code blocks introduced by different commits\&. The color defaults to cyan and can be adjusted using the
- \fBcolor\&.blame\&.repeatedLines\fR
- config option\&.
- .RE
- .PP
- \-\-color\-by\-age
- .RS 4
- Color line annotations depending on the age of the line in the default format\&. The
- \fBcolor\&.blame\&.highlightRecent\fR
- config option controls what color is used for each range of age\&.
- .RE
- .PP
- \-h
- .RS 4
- Show help message\&.
- .RE
- .SH "SEE ALSO"
- .sp
- \fBgit-blame\fR(1)
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite