| blob | 4bf92122dadfe1173df3a17706de2db6edbe53cd |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tsvn-dug-showlog">\r
4 <title>Revision Log Dialog</title>\r
5 <indexterm>\r
6 <primary>log</primary>\r
7 </indexterm>\r
8 <indexterm>\r
9 <primary>history</primary>\r
10 </indexterm>\r
11 <indexterm>\r
12 <primary>commit messages</primary>\r
13 </indexterm>\r
14 <indexterm>\r
15 <primary>log messages</primary>\r
16 </indexterm>\r
17 <?dbhh topicname="HIDD_LOGMESSAGE"?>\r
18 <para>\r
19 For every change you make and commit, you should provide\r
20 a log message for that change. That way you can later find out\r
21 what changes you made and why, and you have a detailed log for\r
22 your development process.\r
23 </para>\r
24 <para>\r
25 The Revision Log Dialog retrieves all those log messages and shows them\r
26 to you.\r
27 The display is divided into 3 panes.\r
28 <itemizedlist>\r
29 <listitem>\r
30 <para>\r
31 The top pane shows a list of revisions where changes to the\r
32 file/folder have been committed. This summary includes the\r
33 date and time, the person who committed the revision and the\r
34 start of the log message.\r
35 </para>\r
36 <para>\r
37 Lines shown in bold indicate that that is HEAD commit.\r
38 </para>\r
39 </listitem>\r
40 <listitem>\r
41 <para>\r
42 The middle pane shows the full log message for the selected\r
43 revision.\r
44 </para>\r
45 </listitem>\r
46 <listitem>\r
47 <para>\r
48 The bottom pane shows a list of all files and folders that\r
49 were changed as part of the selected revision.\r
50 </para>\r
51 </listitem>\r
52 </itemizedlist>\r
53 But it does much more than that - it provides context menu\r
54 commands which you can use to get even more information about the\r
55 project history.\r
56 </para>\r
57 <sect2 id="tsvn-dug-showlog-1">\r
58 <title>Invoking the Revision Log Dialog</title>\r
59 <para>\r
60 <figure id="tsvn-dug-showlog-1-dia-1">\r
61 <title>The Revision Log Dialog</title>\r
62 <graphic fileref="../images/LogMessages.png"/>\r
63 </figure>\r
64 There are several places from where you can show the Log dialog:\r
65 <itemizedlist>\r
66 <listitem>\r
67 <para>\r
68 From the TortoiseGit context submenu\r
69 </para>\r
70 </listitem>\r
71 </itemizedlist>\r
72 </para>\r
73 </sect2>\r
74 <sect2 id="tsvn-dug-showlog-actions">\r
75 <title>Revision Log Actions</title>\r
76 <para>\r
77 The top pane has an <guilabel>Actions</guilabel> column containing\r
78 icons that summarize what has been done in that revision.\r
79 There are four different icons, each shown in its own column.\r
80 </para>\r
81 <para>\r
82 <graphic fileref="../images/ActionModifiedIcon.png"/>\r
83 If a revision modified a file or directory, the\r
84 <emphasis>modified</emphasis> icon is shown in the first column.\r
85 </para>\r
86 <para>\r
87 <graphic fileref="../images/ActionAddedIcon.png"/>\r
88 If a revision added a file or directory, the\r
89 <emphasis>added</emphasis> icon is shown in the second column.\r
90 </para>\r
91 <para>\r
92 <graphic fileref="../images/ActionDeletedIcon.png"/>\r
93 If a revision deleted a file or directory, the\r
94 <emphasis>deleted</emphasis> icon is shown in the third column.\r
95 </para>\r
96 <para>\r
97 <graphic fileref="../images/ActionReplacedIcon.png"/>\r
98 If a revision replaced(rename) a file, the\r
99 <emphasis>replaced</emphasis> icon is shown in the fourth column.\r
100 </para>\r
101 </sect2>\r
102 <sect2 id="tsvn-dug-showlog-2">\r
103 <title>Getting Additional Information</title>\r
104 <para>\r
105 <figure id="tsvn-dug-showlog-2-dia-1">\r
106 <title>The Revision Log Dialog Top Pane with Context Menu</title>\r
107 <graphic fileref="../images/LogContextMenu.png"/>\r
108 </figure>\r
109 The top pane of the Log dialog has a context menu that allows you to\r
110 access much more information. Some of these menu entries appear only\r
111 when the log is shown for a file, and some only when the log is shown\r
112 for a folder.\r
113 <variablelist>\r
114 <varlistentry>\r
115 <term>Compare with working tree</term>\r
116 <listitem>\r
117 <para>\r
118 Compare the selected revision with your working tree.\r
119 The default Diff-Tool is TortoiseMerge which\r
120 is supplied with TortoiseGit.\r
121 If the log dialog is for a folder, this will show you a list\r
122 of changed files, and allow you to review the changes made\r
123 to each file individually.\r
124 </para>\r
125 </listitem>\r
126 </varlistentry>\r
127 <varlistentry>\r
128 <term>Show changes as unified diff</term>\r
129 <listitem>\r
130 <para>\r
131 View the changes made in the selected revision as a\r
132 Unified-Diff file (GNU patch format). This shows\r
133 only the differences with a few lines of context. It\r
134 is harder to read than a visual file compare, but will\r
135 show all file changes together in a compact format.\r
136 </para>\r
137 </listitem>\r
138 </varlistentry>\r
139 <varlistentry>\r
140 <term>Compare with previous revision</term>\r
141 <listitem>\r
142 <para>\r
143 Compare the selected revision with the previous revision.\r
144 This works in a similar manner to comparing with your\r
145 working tree.\r
146 For folders this option will first show the changed files\r
147 dialog allowing you to select files to compare.\r
148 </para>\r
149 </listitem>\r
150 </varlistentry>\r
151 <varlistentry>\r
152 <term>Browse repository</term>\r
153 <listitem>\r
154 <para>\r
155 Open the repository browser to examine the selected file or\r
156 folder in the repository as it was at the selected revision.\r
157 </para>\r
158 </listitem>\r
159 </varlistentry>\r
160 <varlistentry>\r
161 <term>Reset (current branch) to this</term>\r
162 <listitem>\r
163 <para>\r
164 Reset current branch HEAD to selected commit.\r
165 <!-- todo refer reset -->\r
166 </para>\r
167 </listitem>\r
168 </varlistentry>\r
169 <varlistentry>\r
170 <term>Switch\Checkout to revision</term>\r
171 <listitem>\r
172 <para>\r
173 Update your working tree to the selected revision.\r
174 Useful if you want to have your working tree reflect\r
175 a time in the past, or if there have been further commits to\r
176 the repository and you want to update your working tree one\r
177 step at a time.\r
178 </para>\r
179 </listitem>\r
180 </varlistentry>\r
181 \r
182 <varlistentry>\r
183 <term>Create branch from revision</term>\r
184 <listitem>\r
185 <para>\r
186 Create a branch from a selected revision.\r
187 This is useful e.g.\r
188 </para>\r
189 </listitem>\r
190 </varlistentry>\r
191 <varlistentry>\r
192 <term>Create tag from revision</term>\r
193 <listitem>\r
194 <para>\r
195 Create a tag from a selected revision.\r
196 This is useful e.g.\r
197 </para>\r
198 </listitem>\r
199 </varlistentry>\r
200 <varlistentry>\r
201 <term>Rebase (current branch) to this</term>\r
202 <listitem>\r
203 <para>\r
204 Rebase current branch to selected commit.\r
205 <!-- todo refer rebase -->\r
206 </para>\r
207 </listitem>\r
208 </varlistentry>\r
209 <varlistentry>\r
210 <term>Cherry Pick this commit</term>\r
211 <listitem>\r
212 <para>\r
213 Cherry Pick this commit to current branch\r
214 <!-- todo refer cherry pick -->\r
215 </para>\r
216 </listitem>\r
217 </varlistentry>\r
218 <varlistentry>\r
219 <term>Export this version...</term>\r
220 <listitem>\r
221 <para>\r
222 Export the selected file/folder at the selected\r
223 revision. This brings up a dialog for you to confirm the\r
224 URL and revision, and select a location for the export.\r
225 </para>\r
226 </listitem>\r
227 </varlistentry>\r
228 <varlistentry>\r
229 <term>Copy to clipboard</term>\r
230 <listitem>\r
231 <para>\r
232 Copy the log details of the selected revisions to the clipboard.\r
233 This will copy the revision number, author, date, log message\r
234 and the list of changed items for each revision.\r
235 </para>\r
236 </listitem>\r
237 </varlistentry>\r
238 <varlistentry>\r
239 <term>Search log messages...</term>\r
240 <listitem>\r
241 <figure id="tsvn-dug-showlog-1-dia-2">\r
242 <title>The Search Log Messages Dialog</title>\r
243 <graphic fileref="../images/LogSearch.png"/>\r
244 </figure>\r
245 <para>\r
246 Search log messages for the text you enter. This searches\r
247 the log messages that you entered and also the action summaries\r
248 created by Git (shown in the bottom pane). The search\r
249 is not case sensitive.\r
250 </para>\r
251 <tip>\r
252 <para>\r
253 This allows you to easily search for refs (tags and branches).\r
254 </para>\r
255 </tip>\r
256 </listitem>\r
257 </varlistentry>\r
258 <varlistentry>\r
259 <term>Format Patch...</term>\r
260 <listitem>\r
261 <para>\r
262 Create Patchs from this commit.\r
263 </para>\r
264 </listitem>\r
265 </varlistentry>\r
266 </variablelist>\r
267 </para>\r
268 <para>\r
269 <figure id="tsvn-dug-showlog-2-dia-1a">\r
270 <title>Top Pane Context Menu for 2 Selected Revisions</title>\r
271 <graphic fileref="../images/LogContextMenu1.png"/>\r
272 </figure>\r
273 If you select two revisions at once (using the usual\r
274 <keycap>Ctrl</keycap>-modifier), the context menu changes and\r
275 gives you fewer options:\r
276 <variablelist>\r
277 <varlistentry>\r
278 <term>Compare revisions</term>\r
279 <listitem>\r
280 <para>\r
281 Compare the two selected revisions using a visual\r
282 difference tool. The default Diff-Tool is TortoiseMerge\r
283 which is supplied with TortoiseGit.\r
284 </para>\r
285 </listitem>\r
286 </varlistentry>\r
287 <varlistentry>\r
288 <term>Show differences as unified diff</term>\r
289 <listitem>\r
290 <para>\r
291 View the differences between the two selected revisions\r
292 as a Unified-Diff file. This works for files and folders.\r
293 </para>\r
294 </listitem>\r
295 </varlistentry>\r
296 <varlistentry>\r
297 <term>Combine to one commit</term>\r
298 <listitem>\r
299 <para>\r
300 Combine continuous commits to one commit.\r
301 </para>\r
302 </listitem>\r
303 </varlistentry>\r
304 <varlistentry>\r
305 <term>Cherry Pick this version</term>\r
306 <listitem>\r
307 <para>\r
308 Cherry Pick Chosen Commits.\r
309 </para>\r
310 </listitem>\r
311 </varlistentry>\r
312 <varlistentry>\r
313 <term>Fomat Patch...</term>\r
314 <listitem>\r
315 <para>\r
316 Create patchs between chosen two commits.\r
317 </para>\r
318 </listitem>\r
319 </varlistentry>\r
320 <varlistentry>\r
321 <term>Copy to clipboard</term>\r
322 <listitem>\r
323 <para>\r
324 Copy log messages to clipboard as described above.\r
325 </para>\r
326 </listitem>\r
327 </varlistentry>\r
328 <varlistentry>\r
329 <term>Search log messages...</term>\r
330 <listitem>\r
331 <para>\r
332 Search log messages as described above.\r
333 </para>\r
334 </listitem>\r
335 </varlistentry>\r
336 </variablelist>\r
337 </para>\r
338 \r
339 <para>\r
340 If you select two or more revisions (using the usual\r
341 <keycap>Ctrl</keycap> or <keycap>Shift</keycap> modifiers),\r
342 You can combine select commits to one commit. And cherry pick\r
343 these commits to current branch.\r
344 </para>\r
345 <para>\r
346 <figure id="tsvn-dug-showlog-2-dia-2">\r
347 <title>The Log Dialog Bottom Pane with Context Menu</title>\r
348 <graphic fileref="../images/LogContextMenu2.png"/>\r
349 </figure>\r
350 The bottom pane of the Log dialog also has a context menu that allows you to\r
351 <variablelist>\r
352 <varlistentry>\r
353 <term>Show as unified diff</term>\r
354 <listitem>\r
355 <para>\r
356 Show file changes in unified diff format.\r
357 This context menu is only available for\r
358 files shown as <emphasis>modified</emphasis>.\r
359 </para>\r
360 </listitem>\r
361 </varlistentry>\r
362 \r
363 <varlistentry>\r
364 <term>Open / Open with...</term>\r
365 <listitem>\r
366 <para>\r
367 Open the selected file, either with the default viewer for\r
368 that file type, or with a program you choose.\r
369 </para>\r
370 </listitem>\r
371 </varlistentry>\r
372 <varlistentry>\r
373 <term>Blame...</term>\r
374 <listitem>\r
375 <para>\r
376 Opens the Blame dialog, allowing you to blame up to the\r
377 selected revision.\r
378 </para>\r
379 </listitem>\r
380 </varlistentry>\r
381 \r
382 <varlistentry>\r
383 <term>Revert changes to this revision</term>\r
384 <listitem>\r
385 <para>\r
386 Revert chosen file to this revision.\r
387 </para>\r
388 </listitem>\r
389 </varlistentry>\r
390 <varlistentry>\r
391 <term>Save revision to...</term>\r
392 <listitem>\r
393 <para>\r
394 Save the selected revision to a file so you\r
395 have an older version of that file.\r
396 </para>\r
397 </listitem>\r
398 </varlistentry>\r
399 \r
400 <varlistentry>\r
401 <term>Export selection to...</term>\r
402 <listitem>\r
403 <para>\r
404 Saves the selected files to a target directory. Compared to "Save revision to..." this preserves the directory structure.\r
405 </para>\r
406 </listitem>\r
407 </varlistentry>\r
408 \r
409 <varlistentry>\r
410 <term>Show log</term>\r
411 <listitem>\r
412 <para>\r
413 Show the revision log for the selected single file.\r
414 </para>\r
415 </listitem>\r
416 </varlistentry>\r
417 \r
418 <varlistentry>\r
419 <term>Compare with base</term>\r
420 <listitem>\r
421 <para>\r
422 Compare chosen file with base version.\r
423 </para>\r
424 </listitem>\r
425 </varlistentry>\r
426 \r
427 <varlistentry>\r
428 <term>Compare with working tree</term>\r
429 <listitem>\r
430 <para>\r
431 Compare chosen file with working tree.\r
432 </para>\r
433 </listitem>\r
434 </varlistentry>\r
435 \r
436 <varlistentry>\r
437 <term>View revision in Notepad2</term>\r
438 <listitem>\r
439 <para>\r
440 Show chosen file with notepad2 with chosen commit.\r
441 </para>\r
442 </listitem>\r
443 </varlistentry>\r
444 \r
445 <varlistentry>\r
446 <term>Explore to</term>\r
447 <listitem>\r
448 <para>\r
449 Open directory of file with Explore.\r
450 </para>\r
451 </listitem>\r
452 </varlistentry>\r
453 \r
454 <varlistentry>\r
455 <term>Copy paths to clipboard</term>\r
456 <listitem>\r
457 <para>\r
458 Copy paths to clipboard\r
459 </para>\r
460 </listitem>\r
461 </varlistentry>\r
462 \r
463 <varlistentry>\r
464 <term>Copy all information to clipboard</term>\r
465 <listitem>\r
466 <para>\r
467 Copy all information to clipboard, include version info.\r
468 </para>\r
469 </listitem>\r
470 </varlistentry>\r
471 </variablelist>\r
472 </para>\r
473 <tip>\r
474 <para>\r
475 You may notice that sometimes we refer to changes and other times\r
476 to differences. What's the difference?\r
477 </para>\r
478 </tip>\r
479 </sect2>\r
480 <sect2 id="tsvn-dug-showlog-filter">\r
481 <title>Filtering Log Messages</title>\r
482 <indexterm>\r
483 <primary>filter</primary>\r
484 </indexterm>\r
485 <para>\r
486 If you want to restrict the log messages to show only those\r
487 you are interested in rather than scrolling through a list\r
488 of hundreds, you can use the filter controls at the top of\r
489 the Log Dialog. The start and end date controls allow you\r
490 to restrict the output to a known date range. The search\r
491 box allows you to show only messages which contain a\r
492 particular phrase.\r
493 </para>\r
494 <para>\r
495 Click on the search icon to select which information you want\r
496 to search in, and to choose <emphasis>regex</emphasis> mode.\r
497 Normally you will only need a simple text search, but if you\r
498 need to more flexible search terms, you can use regular expressions.\r
499 If you hover the mouse over the box, a tooltip will give hints\r
500 on how to use the regex functions.\r
501 You can also find online documentation and a tutorial at\r
502 <ulink url="http://www.regular-expressions.info/">\r
503 <citetitle>http://www.regular-expressions.info/</citetitle>\r
504 </ulink>.\r
505 The filter works by checking whether your filter string matches\r
506 the log entries, and then only those entries which <emphasis>match</emphasis>\r
507 the filter string are shown.\r
508 </para>\r
509 <para>\r
510 To make the filter show all log entries that do <emphasis>not</emphasis>\r
511 match the filter string, start the string with an exclamation mark ('!').\r
512 For example, a filter string <literal>!username</literal> will only\r
513 show those entries which were not committed by <literal>username</literal>.\r
514 </para>\r
515 <para>\r
516 Note that these filters act on the messages already retrieved.\r
517 They do not control downloading of messages from the repository.\r
518 </para>\r
519 <para>\r
520 You can also filter the path names in the bottom pane using the\r
521 <guilabel>Hide unrelated changed paths</guilabel> checkbox.\r
522 Related paths are those which contain the path used to display\r
523 the log. If you fetch the log for a folder, that means anything\r
524 in that folder or below it. For a file it means just that one file.\r
525 The checkbox is tristate: you can show all paths, grey out the\r
526 unrelated ones, or hide the unrelated paths completely.\r
527 </para>\r
528 \r
529 <para>\r
530 You can show all branches history by click <guilabel>All branches</guilabel>\r
531 </para>\r
532 <para>\r
533 You can show whole project history, no choose directory or file by click\r
534 <guilabel>Show Whole Project</guilabel>\r
535 </para>\r
536 <para>\r
537 <guilabel>First Parent</guilabel> just follow up first parent commit. This will\r
538 help understand overwhole history.\r
539 </para>\r
540 </sect2>\r
541 <sect2 id="tsvn-dug-showlog-5">\r
542 <?dbhh topicname="HIDD_STATGRAPH"?>\r
543 <title>Statistical Information</title>\r
544 <indexterm>\r
545 <primary>statistics</primary>\r
546 </indexterm>\r
547 <para>\r
548 The <guibutton>Statistics</guibutton> button brings up a box\r
549 showing some interesting information about the revisions\r
550 shown in the Log dialog. This shows how many authors have\r
551 been at work, how many commits they have made, progress\r
552 by week, and much more. Now you can see at a glance who\r
553 has been working hardest and who is slacking ;-)\r
554 </para>\r
555 <sect3 id="tsvn-dug-showlog-stats-1">\r
556 <title>Statistics Page</title>\r
557 <para>\r
558 This page gives you all the numbers you can think of,\r
559 in particular the period and number of revisions covered,\r
560 and some min/max/average values.\r
561 </para>\r
562 </sect3>\r
563 <sect3 id="tsvn-dug-showlog-stats-2">\r
564 <title>Commits by Author Page</title>\r
565 <para>\r
566 <figure id="tsvn-dug-showlog-stats-dia-2">\r
567 <title>Commits-by-Author Histogram</title>\r
568 <graphic fileref="../images/StatsByAuthor.png"/>\r
569 </figure>\r
570 This graph shows you which authors have been active on the\r
571 project as a simple histogram, stacked histogram or\r
572 pie chart.\r
573 <figure id="tsvn-dug-showlog-stats-dia-3">\r
574 <title>Commits-by-Author Pie Chart</title>\r
575 <graphic fileref="../images/StatsByAuthPie.png"/>\r
576 </figure>\r
577 </para>\r
578 <para>\r
579 Where there are a few major authors and many minor contributors,\r
580 the number of tiny segments can make the graph more difficult to\r
581 read. The slider at the bottom allows you to set a threshold\r
582 (as a percentage of total commits) below which any activity is\r
583 grouped into an <emphasis>Others</emphasis> category.\r
584 </para>\r
585 </sect3>\r
586 <sect3 id="tsvn-dug-showlog-stats-3">\r
587 <title>Commits by date Page</title>\r
588 <para>\r
589 <figure id="tsvn-dug-showlog-stats-dia-4">\r
590 <title>Commits-by-date Graph</title>\r
591 <graphic fileref="../images/StatsByDate.png"/>\r
592 </figure>\r
593 This page gives you a graphical representation of project\r
594 activity in terms of number of commits <emphasis>and</emphasis>\r
595 author. This gives some idea of when a project is being worked\r
596 on, and who was working at which time.\r
597 </para>\r
598 <para>\r
599 When there are several authors, you will get many lines on the\r
600 graph. There are two views available here: <emphasis>normal</emphasis>,\r
601 where each author's activity is relative to the base line, and\r
602 <emphasis>stacked</emphasis>, where each author's activity is\r
603 relative to the line underneath.\r
604 The latter option avoids the lines crossing over, which can make\r
605 the graph easier to read, but less easy to see one author's output.\r
606 </para>\r
607 </sect3>\r
608 <para>\r
609 By default the analysis is case-sensitive, so users\r
610 <literal>PeterEgan</literal> and <literal>PeteRegan</literal>\r
611 are treated as different authors. However, in many cases user names\r
612 are not case-sensitive, and are sometimes entered inconsistently,\r
613 so you may want <literal>DavidMorgan</literal> and\r
614 <literal>davidmorgan</literal> to be treated as the same person.\r
615 Use the <guilabel>Authors case insensitive</guilabel> checkbox\r
616 to control how this is handled.\r
617 </para>\r
618 <para>\r
619 Note that the statistics cover the same period as the\r
620 Log dialog. If that is only displaying one revision\r
621 then the statistics will not tell you very much.\r
622 </para>\r
623 </sect2>\r
624 <sect2 id="tsvn-dug-showlog-refresh">\r
625 <title>Refreshing the View</title>\r
626 <para>\r
627 If you want to check the repository again for newer log messages,\r
628 you can simply refresh the view using <keycap>F5</keycap>. If you\r
629 are using the log cache (enabled by default), this will check the\r
630 repository for newer messages and fetch only the new ones.\r
631 </para>\r
632 </sect2>\r
633 </sect1>\r