man1/git-annotate.1

   1 '\" t
   2 .\"     Title: git-annotate
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-30
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.rc0.18.ge9356ba3ea
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-ANNOTATE" "1" "2024-09-30" "Git 2\&.47\&.0\&.rc0\&.18\&.ge" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-annotate \- Annotate file lines with commit information
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit annotate\fR [<options>] [<rev\-opts>] [<rev>] [\-\-] <file>
  36 .fi
  37 .SH "DESCRIPTION"
  38 .sp
  39 Annotates each line in the given file with information from the commit which introduced the line\&. Optionally annotates from a given revision\&.
  40 .sp
  41 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\&.
  42 .SH "OPTIONS"
  43 .PP
  44 \-b
  45 .RS 4
  46 Show blank SHA\-1 for boundary commits\&. This can also be controlled via the
  47 \fBblame\&.blankBoundary\fR
  48 config option\&.
  49 .RE
  50 .PP
  51 \-\-root
  52 .RS 4
  53 Do not treat root commits as boundaries\&. This can also be controlled via the
  54 \fBblame\&.showRoot\fR
  55 config option\&.
  56 .RE
  57 .PP
  58 \-\-show\-stats
  59 .RS 4
  60 Include additional statistics at the end of blame output\&.
  61 .RE
  62 .PP
  63 \-L <start>,<end>, \-L :<funcname>
  64 .RS 4
  65 Annotate only the line range given by
  66 \fI<start>,<end>\fR, or by the function name regex
  67 \fI<funcname>\fR\&. May be specified multiple times\&. Overlapping ranges are allowed\&.
  68 .sp
  69 \fI<start>\fR
  70 and
  71 \fI<end>\fR
  72 are optional\&.
  73 \fB\-L <start>\fR
  74 or
  75 \fB\-L <start>,\fR
  76 spans from
  77 \fI<start>\fR
  78 to end of file\&.
  79 \fB\-L ,<end>\fR
  80 spans from start of file to
  81 \fI<end>\fR\&.
  82 .sp
  83 \fI<start>\fR
  84 and
  85 \fI<end>\fR
  86 can take one of these forms:
  87 .sp
  88 .RS 4
  89 .ie n \{\
  90 \h'-04'\(bu\h'+03'\c
  91 .\}
  92 .el \{\
  93 .sp -1
  94 .IP \(bu 2.3
  95 .\}
  96 number
  97 .sp
  98 If
  99 \fI<start>\fR
 100 or
 101 \fI<end>\fR
 102 is a number, it specifies an absolute line number (lines count from 1)\&.
 103 .RE
 104 .sp
 105 .RS 4
 106 .ie n \{\
 107 \h'-04'\(bu\h'+03'\c
 108 .\}
 109 .el \{\
 110 .sp -1
 111 .IP \(bu 2.3
 112 .\}
 113 \fB/regex/\fR
 114 .sp
 115 This form will use the first line matching the given POSIX regex\&. If
 116 \fI<start>\fR
 117 is a regex, it will search from the end of the previous
 118 \fB\-L\fR
 119 range, if any, otherwise from the start of file\&. If
 120 \fI<start>\fR
 121 is
 122 \fB^/regex/\fR, it will search from the start of file\&. If
 123 \fI<end>\fR
 124 is a regex, it will search starting at the line given by
 125 \fI<start>\fR\&.
 126 .RE
 127 .sp
 128 .RS 4
 129 .ie n \{\
 130 \h'-04'\(bu\h'+03'\c
 131 .\}
 132 .el \{\
 133 .sp -1
 134 .IP \(bu 2.3
 135 .\}
 136 +offset or \-offset
 137 .sp
 138 This is only valid for
 139 \fI<end>\fR
 140 and will specify a number of lines before or after the line given by
 141 \fI<start>\fR\&.
 142 .RE
 143 .sp
 144 If
 145 \fB:<funcname>\fR
 146 is given in place of
 147 \fI<start>\fR
 148 and
 149 \fI<end>\fR, it is a regular expression that denotes the range from the first funcname line that matches
 150 \fI<funcname>\fR, up to the next funcname line\&.
 151 \fB:<funcname>\fR
 152 searches from the end of the previous
 153 \fB\-L\fR
 154 range, if any, otherwise from the start of file\&.
 155 \fB^:<funcname>\fR
 156 searches from the start of file\&. The function names are determined in the same way as
 157 \fBgit diff\fR
 158 works out patch hunk headers (see
 159 \fIDefining a custom hunk\-header\fR
 160 in
 161 \fBgitattributes\fR(5))\&.
 162 .RE
 163 .PP
 164 \-l
 165 .RS 4
 166 Show long rev (Default: off)\&.
 167 .RE
 168 .PP
 169 \-t
 170 .RS 4
 171 Show raw timestamp (Default: off)\&.
 172 .RE
 173 .PP
 174 \-S <revs\-file>
 175 .RS 4
 176 Use revisions from revs\-file instead of calling
 177 \fBgit-rev-list\fR(1)\&.
 178 .RE
 179 .PP
 180 \-\-reverse <rev>\&.\&.<rev>
 181 .RS 4
 182 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\&.
 183 \fBgit blame \-\-reverse START\fR
 184 is taken as
 185 \fBgit blame \-\-reverse START\&.\&.HEAD\fR
 186 for convenience\&.
 187 .RE
 188 .PP
 189 \-\-first\-parent
 190 .RS 4
 191 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\&.
 192 .RE
 193 .PP
 194 \-p, \-\-porcelain
 195 .RS 4
 196 Show in a format designed for machine consumption\&.
 197 .RE
 198 .PP
 199 \-\-line\-porcelain
 200 .RS 4
 201 Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced\&. Implies \-\-porcelain\&.
 202 .RE
 203 .PP
 204 \-\-incremental
 205 .RS 4
 206 Show the result incrementally in a format designed for machine consumption\&.
 207 .RE
 208 .PP
 209 \-\-encoding=<encoding>
 210 .RS 4
 211 Specifies the encoding used to output author names and commit summaries\&. Setting it to
 212 \fBnone\fR
 213 makes blame output unconverted data\&. For more information see the discussion about encoding in the
 214 \fBgit-log\fR(1)
 215 manual page\&.
 216 .RE
 217 .PP
 218 \-\-contents <file>
 219 .RS 4
 220 Annotate using the contents from the named file, starting from <rev> if it is specified, and HEAD otherwise\&. You may specify
 221 \fI\-\fR
 222 to make the command read from the standard input for the file contents\&.
 223 .RE
 224 .PP
 225 \-\-date <format>
 226 .RS 4
 227 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
 228 \fBgit-log\fR(1)\&.
 229 .RE
 230 .PP
 231 \-\-[no\-]progress
 232 .RS 4
 233 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
 234 \fB\-\-progress\fR
 235 together with
 236 \fB\-\-porcelain\fR
 237 or
 238 \fB\-\-incremental\fR\&.
 239 .RE
 240 .PP
 241 \-M[<num>]
 242 .RS 4
 243 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
 244 \fIblame\fR
 245 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\&.
 246 .sp
 247 <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\&.
 248 .RE
 249 .PP
 250 \-C[<num>]
 251 .RS 4
 252 In addition to
 253 \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\&.
 254 .sp
 255 <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
 256 \fB\-C\fR
 257 options given, the <num> argument of the last
 258 \fB\-C\fR
 259 will take effect\&.
 260 .RE
 261 .PP
 262 \-\-ignore\-rev <rev>
 263 .RS 4
 264 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
 265 \fBblame\&.markIgnoredLines\fR
 266 config option is set, then lines that were changed by an ignored commit and attributed to another commit will be marked with a
 267 \fB?\fR
 268 in the blame output\&. If the
 269 \fBblame\&.markUnblamableLines\fR
 270 config option is set, then those lines touched by an ignored commit that we could not attribute to another revision are marked with a
 271 \fI*\fR\&.
 272 .RE
 273 .PP
 274 \-\-ignore\-revs\-file <file>
 275 .RS 4
 276 Ignore revisions listed in
 277 \fBfile\fR, which must be in the same format as an
 278 \fBfsck\&.skipList\fR\&. This option may be repeated, and these files will be processed after any files specified with the
 279 \fBblame\&.ignoreRevsFile\fR
 280 config option\&. An empty file name,
 281 \fB""\fR, will clear the list of revs from previously processed files\&.
 282 .RE
 283 .PP
 284 \-\-color\-lines
 285 .RS 4
 286 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
 287 \fBcolor\&.blame\&.repeatedLines\fR
 288 config option\&.
 289 .RE
 290 .PP
 291 \-\-color\-by\-age
 292 .RS 4
 293 Color line annotations depending on the age of the line in the default format\&. The
 294 \fBcolor\&.blame\&.highlightRecent\fR
 295 config option controls what color is used for each range of age\&.
 296 .RE
 297 .PP
 298 \-h
 299 .RS 4
 300 Show help message\&.
 301 .RE
 302 .SH "SEE ALSO"
 303 .sp
 304 \fBgit-blame\fR(1)
 305 .SH "GIT"
 306 .sp
 307 Part of the \fBgit\fR(1) suite