doc: blame-options: convert to new doc format
- Use _<placeholder>_ instead of <placeholder> in the description - Modify some samples to use <placeholders> - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Michael Lyons <git@michael.lyo.nz> Acked-by: Jean-Noël AVILA <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Lyons committed
Jan 8, 2026 at 10:30 UTC
2bfc69e648d049a72403a4aa3f11e9360516e470
1 file changed
+60
-60
Documentation/blame-options.adoc
+60
-60
@@ -1,105 +1,105 @@
1
--b::
1
+`-b`::
2
Show blank SHA-1 for boundary commits. This can also
3
be controlled via the `blame.blankBoundary` config option.
4
5
---root::
5
+`--root`::
6
Do not treat root commits as boundaries. This can also be
7
controlled via the `blame.showRoot` config option.
8
9
---show-stats::
9
+`--show-stats`::
10
Include additional statistics at the end of blame output.
11
12
--L <start>,<end>::
13
--L :<funcname>::
14
- Annotate only the line range given by '<start>,<end>',
15
- or by the function name regex '<funcname>'.
12
+`-L <start>,<end>`::
13
+`-L :<funcname>`::
14
+ Annotate only the line range given by `<start>,<end>`,
15
+ or by the function name regex _<funcname>_.
16
May be specified multiple times. Overlapping ranges are allowed.
17
+
18
-'<start>' and '<end>' are optional. `-L <start>` or `-L <start>,` spans from
19
-'<start>' to end of file. `-L ,<end>` spans from start of file to '<end>'.
18
+_<start>_ and _<end>_ are optional. `-L <start>` or `-L <start>,` spans from
19
+_<start>_ to end of file. `-L ,<end>` spans from start of file to _<end>_.
20
+
21
include::line-range-format.adoc[]
22
23
--l::
23
+`-l`::
24
Show long rev (Default: off).
25
26
--t::
26
+`-t`::
27
Show raw timestamp (Default: off).
28
29
--S <revs-file>::
30
- Use revisions from revs-file instead of calling linkgit:git-rev-list[1].
29
+`-S <revs-file>`::
30
+ Use revisions from _<revs-file>_ instead of calling
31
+ linkgit:git-rev-list[1].
32
32
---reverse <rev>..<rev>::
33
+`--reverse <start>..<end>`::
34
Walk history forward instead of backward. Instead of showing
35
the revision in which a line appeared, this shows the last
36
revision in which a line has existed. This requires a range of
36
- revision like START..END where the path to blame exists in
37
- START. `git blame --reverse START` is taken as `git blame
38
- --reverse START..HEAD` for convenience.
37
+ revision like `<start>..<end>` where the path to blame exists in
38
+ _<start>_. `git blame --reverse <start>` is taken as `git blame
39
+ --reverse <start>..HEAD` for convenience.
40
40
---first-parent::
41
+`--first-parent`::
42
Follow only the first parent commit upon seeing a merge
43
commit. This option can be used to determine when a line
44
was introduced to a particular integration branch, rather
45
than when it was introduced to the history overall.
46
46
--p::
47
---porcelain::
47
+`-p`::
48
+`--porcelain`::
49
Show in a format designed for machine consumption.
50
50
---line-porcelain::
51
+`--line-porcelain`::
52
Show the porcelain format, but output commit information for
53
each line, not just the first time a commit is referenced.
53
- Implies --porcelain.
54
+ Implies `--porcelain`.
55
55
---incremental::
56
+`--incremental`::
57
Show the result incrementally in a format designed for
58
machine consumption.
59
59
---encoding=<encoding>::
60
- Specifies the encoding used to output author names
60
+`--encoding=<encoding>`::
61
+ Specify the encoding used to output author names
62
and commit summaries. Setting it to `none` makes blame
63
output unconverted data. For more information see the
64
discussion about encoding in the linkgit:git-log[1]
65
manual page.
66
66
---contents <file>::
67
- Annotate using the contents from the named file, starting from <rev>
68
- if it is specified, and HEAD otherwise. You may specify '-' to make
67
+`--contents <file>`::
68
+ Annotate using the contents from _<file>_, starting from _<rev>_
69
+ if it is specified, and `HEAD` otherwise. You may specify `-` to make
70
the command read from the standard input for the file contents.
71
71
---date <format>::
72
- Specifies the format used to output dates. If --date is not
73
- provided, the value of the blame.date config variable is
74
- used. If the blame.date config variable is also not set, the
72
+`--date <format>`::
73
+ Specify the format used to output dates. If `--date` is not
74
+ provided, the value of the `blame.date` config variable is
75
+ used. If the `blame.date` config variable is also not set, the
76
iso format is used. For supported values, see the discussion
76
- of the --date option at linkgit:git-log[1].
77
+ of the `--date` option at linkgit:git-log[1].
78
78
---progress::
79
---no-progress::
80
- Progress status is reported on the standard error stream
81
- by default when it is attached to a terminal. This flag
82
- enables progress reporting even if not attached to a
83
- terminal. Can't use `--progress` together with `--porcelain`
84
- or `--incremental`.
79
+`--progress`::
80
+`--no-progress`::
81
+ Enable progress reporting on the standard error stream even if
82
+ not attached to a terminal. By default, progress status is
83
+ reported only when it is attached. You can't use `--progress`
84
+ together with `--porcelain` or `--incremental`.
85
86
--M[<num>]::
86
+`-M[<num>]`::
87
Detect moved or copied lines within a file. When a commit
88
moves or copies a block of lines (e.g. the original file
89
- has A and then B, and the commit changes it to B and then
90
- A), the traditional 'blame' algorithm notices only half of
89
+ has _A_ and then _B_, and the commit changes it to _B_ and then
90
+ _A_), the traditional `blame` algorithm notices only half of
91
the movement and typically blames the lines that were moved
92
- up (i.e. B) to the parent and assigns blame to the lines that
93
- were moved down (i.e. A) to the child commit. With this
92
+ up (i.e. _B_) to the parent and assigns blame to the lines that
93
+ were moved down (i.e. _A_) to the child commit. With this
94
option, both groups of lines are blamed on the parent by
95
running extra passes of inspection.
96
+
97
-<num> is optional but it is the lower bound on the number of
97
+_<num>_ is optional, but it is the lower bound on the number of
98
alphanumeric characters that Git must detect as moving/copying
99
within a file for it to associate those lines with the parent
100
commit. The default value is 20.
101
102
--C[<num>]::
102
+`-C[<num>]`::
103
In addition to `-M`, detect lines moved or copied from other
104
files that were modified in the same commit. This is
105
useful when you reorganize your program and move code
@@ -109,14 +109,14 @@ commit. The default value is 20.
109
option is given three times, the command additionally
110
looks for copies from other files in any commit.
111
+
112
-<num> is optional but it is the lower bound on the number of
112
+_<num>_ is optional, but it is the lower bound on the number of
113
alphanumeric characters that Git must detect as moving/copying
114
between files for it to associate those lines with the parent
115
commit. And the default value is 40. If there are more than one
116
-`-C` options given, the <num> argument of the last `-C` will
116
+`-C` options given, the _<num>_ argument of the last `-C` will
117
take effect.
118
119
---ignore-rev <rev>::
119
+`--ignore-rev <rev>`::
120
Ignore changes made by the revision when assigning blame, as if the
121
change never happened. Lines that were changed or added by an ignored
122
commit will be blamed on the previous commit that changed that line or
@@ -126,26 +126,26 @@ take effect.
126
another commit will be marked with a `?` in the blame output. If the
127
`blame.markUnblamableLines` config option is set, then those lines touched
128
by an ignored commit that we could not attribute to another revision are
129
- marked with a '*'. In the porcelain modes, we print 'ignored' and
130
- 'unblamable' on a newline respectively.
129
+ marked with a `*`. In the porcelain modes, we print `ignored` and
130
+ `unblamable` on a newline respectively.
131
132
---ignore-revs-file <file>::
133
- Ignore revisions listed in `file`, which must be in the same format as an
132
+`--ignore-revs-file <file>`::
133
+ Ignore revisions listed in _<file>_, which must be in the same format as an
134
`fsck.skipList`. This option may be repeated, and these files will be
135
processed after any files specified with the `blame.ignoreRevsFile` config
136
option. An empty file name, `""`, will clear the list of revs from
137
previously processed files.
138
139
---color-lines::
139
+`--color-lines`::
140
Color line annotations in the default format differently if they come from
141
the same commit as the preceding line. This makes it easier to distinguish
142
code blocks introduced by different commits. The color defaults to cyan and
143
can be adjusted using the `color.blame.repeatedLines` config option.
144
145
---color-by-age::
146
- Color line annotations depending on the age of the line in the default format.
147
- The `color.blame.highlightRecent` config option controls what color is used for
148
- each range of age.
145
+`--color-by-age`::
146
+ Color line annotations depending on the age of the line in
147
+ the default format. The `color.blame.highlightRecent` config
148
+ option controls what color is used for each range of age.
149
150
--h::
150
+`-h`::
151
Show help message.