| blob | badf735b44f4b5d1e33ad9200b3430dd789d9889 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tsvn-dug-blame">\r
4 <title>Who Changed Which Line?</title>\r
5 <indexterm>\r
6 <primary>blame</primary>\r
7 </indexterm>\r
8 <indexterm>\r
9 <primary>annotate</primary>\r
10 </indexterm>\r
11 <indexterm>\r
12 <primary>praise</primary>\r
13 </indexterm>\r
14 <?dbhh topicname="HIDD_BLAME"?>\r
15 <para>\r
16 Sometimes you need to know not only what lines have changed, but also\r
17 who exactly changed specific lines in a file. That's when the\r
18 <menuchoice>\r
19 <guimenu>TortoiseGit</guimenu>\r
20 <guimenuitem>Blame...</guimenuitem>\r
21 </menuchoice>\r
22 command, sometimes also referred to as <firstterm>annotate</firstterm>\r
23 command comes in handy.\r
24 </para>\r
25 <para>\r
26 This command lists, for every line in a file, the author and the revision\r
27 the line was changed.\r
28 </para>\r
29 <sect2 id="tsvn-dug-blame-simple">\r
30 <title>Blame for Files</title>\r
31 <para>\r
32 By default the blame file is viewed using <firstterm>TortoiseGitBlame</firstterm>,\r
33 which highlights the different revisions to make it easier to read.\r
34 </para>\r
35 <para>\r
36 <figure id="tsvn-dug-blame-dia-2">\r
37 <title>TortoiseGitBlame</title>\r
38 <graphic fileref="../images/TortoiseBlame.png"/>\r
39 </figure>\r
40 TortoiseGitBlame, which is included with TortoiseGit. \r
41 When you hover the mouse over a line in the blame info\r
42 column, all lines with the same revision are shown with a darker\r
43 background. Lines from other revisions which were changed by the same author\r
44 are shown with a light background.\r
45 The colouring may not work as clearly if you have your display set to\r
46 256 colour mode.\r
47 </para>\r
48 <para>\r
49 If you <action>left click</action>\r
50 on a line, all lines with the same revision are highlighted, and lines from\r
51 other revisions by the same author are highlighted in a lighter colour.\r
52 This highlighting is sticky, allowing you to move the mouse without losing\r
53 the highlights. Click on that revision again to turn off highlighting.\r
54 </para>\r
55 <para>\r
56 The revision comments (log message) are shown in a hint box whenever\r
57 the mouse hovers over the blame info column. If you want to copy the\r
58 log message for that revision, use the context menu which appears when\r
59 you right click on the blame info column.\r
60 </para>\r
61 <para>\r
62 You can search within the Blame report using\r
63 <menuchoice>\r
64 <guimenu>Edit</guimenu>\r
65 <guimenuitem>Find...</guimenuitem>\r
66 </menuchoice>.\r
67 This allows you to search for revision numbers, authors and the content of\r
68 the file itself. Log messages are not included in the search - you should\r
69 use the Log Dialog to search those.\r
70 </para>\r
71 <para>\r
72 You can also jump to a specific line number using\r
73 <menuchoice>\r
74 <guimenu>Edit</guimenu>\r
75 <guimenuitem>Go To Line...</guimenuitem>\r
76 </menuchoice>.\r
77 </para>\r
78 <!--\r
79 <para>\r
80 When the mouse is over the blame info columns, a context menu is\r
81 available which helps with comparing revisions and examining history,\r
82 using the revision number of the line under the mouse as a reference.\r
83 <menuchoice>\r
84 <guimenu>Context menu</guimenu>\r
85 <guimenuitem>Blame previous revision</guimenuitem>\r
86 </menuchoice> generates a blame report for the same file, but using\r
87 the previous revision as the upper limit. This gives you the blame\r
88 report for the state of the file just before the line you are looking\r
89 at was last changed.\r
90 <menuchoice>\r
91 <guimenu>Context menu</guimenu>\r
92 <guimenuitem>Show changes</guimenuitem>\r
93 </menuchoice> starts your diff viewer, showing you what changed in\r
94 the referenced revision.\r
95 <menuchoice>\r
96 <guimenu>Context menu</guimenu>\r
97 <guimenuitem>Show log</guimenuitem>\r
98 </menuchoice> displays the revision log dialog starting with the\r
99 referenced revision.\r
100 </para>\r
101 <para>\r
102 If you need a better visual indicator of where the oldest and newest\r
103 changes are, select\r
104 <menuchoice>\r
105 <guimenu>View</guimenu>\r
106 <guimenuitem>Color age of lines</guimenuitem>\r
107 </menuchoice>.\r
108 This will use a colour gradient to show newer lines in red and older lines\r
109 in blue. The default colouring is quite light, but you can change it using\r
110 the TortoiseBlame settings.\r
111 </para>\r
112 <para>\r
113 If you are using Merge Tracking, where lines have changed as a result of\r
114 merging from another path, TortoiseBlame will show the revision and author\r
115 of the last change in the original file rather than the revision where the\r
116 merge took place. These lines are indicated by showing the revision and\r
117 author in italics.\r
118 If you do not want merged lines shown in this way, uncheck the\r
119 <guilabel>Include merge info</guilabel> checkbox.\r
120 </para>\r
121 <para>\r
122 If you want to see the paths involved in the merge, select\r
123 <menuchoice>\r
124 <guimenu>View</guimenu>\r
125 <guimenuitem>Merge paths</guimenuitem>\r
126 </menuchoice>.\r
127 </para>\r
128 <para>\r
129 The settings for TortoiseBlame can be accessed using\r
130 <menuchoice>\r
131 <guimenu>TortoiseGit</guimenu>\r
132 <guimenuitem>Settings...</guimenuitem>\r
133 </menuchoice>\r
134 on the TortoiseBlame tab. Refer to \r
135 <xref linkend="tsvn-dug-settings-tortoiseblame"/>.\r
136 </para>\r
137 -->\r
138 </sect2>\r
139 <!--\r
140 <sect2 id="tsvn-dug-blame-diffs">\r
141 <title>Blame Differences</title>\r
142 <para>\r
143 One of the limitations of the Blame report is that it only shows the file as\r
144 it was in a particular revision, and shows the last person to change each line.\r
145 Sometimes you want to know what change was made, as well as who made it. What\r
146 you need here is a combination of the diff and blame reports.\r
147 </para>\r
148 <para>\r
149 The revision log dialog includes several options which allow you to do this.\r
150 <variablelist>\r
151 <varlistentry>\r
152 <term>Blame Revisions</term>\r
153 <listitem>\r
154 <para>\r
155 In the top pane, select 2 revisions, then select\r
156 <menuchoice>\r
157 <guimenu>Context menu</guimenu>\r
158 <guimenuitem>Blame revisions</guimenuitem>\r
159 </menuchoice>.\r
160 This will fetch the blame data for the 2 revisions, then\r
161 use the diff viewer to compare the two blame files.\r
162 </para>\r
163 </listitem>\r
164 </varlistentry>\r
165 <varlistentry>\r
166 <term>Blame Changes</term>\r
167 <listitem>\r
168 <para>\r
169 Select one revision in the top pane, then pick one file\r
170 in the bottom pane and select\r
171 <menuchoice>\r
172 <guimenu>Context menu</guimenu>\r
173 <guimenuitem>Blame changes</guimenuitem>\r
174 </menuchoice>.\r
175 This will fetch the blame data for the selected revision\r
176 and the previous revision, then use the diff viewer to\r
177 compare the two blame files.\r
178 </para>\r
179 </listitem>\r
180 </varlistentry>\r
181 <varlistentry>\r
182 <term>Compare and Blame with Working BASE</term>\r
183 <listitem>\r
184 <para>\r
185 Show the log for a single file, and in the top pane, select\r
186 a single revision, then select\r
187 <menuchoice>\r
188 <guimenu>Context menu</guimenu>\r
189 <guimenuitem>Compare and Blame with Working BASE</guimenuitem>\r
190 </menuchoice>.\r
191 This will fetch the blame data for the selected revision,\r
192 and for the file in the working BASE, then use the diff\r
193 viewer to compare the two blame files.\r
194 </para>\r
195 </listitem>\r
196 </varlistentry>\r
197 </variablelist>\r
198 </para>\r
199 </sect2>\r
200 -->\r
201 </sect1>\r