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