logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-annotate.1 (10074B)


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