| blob | bc0f5e70539b93e823587229f01379e22d437e39 |
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 <!--\r
72 <listitem>\r
73 <para>\r
74 From the property page\r
75 </para>\r
76 </listitem>\r
77 -->\r
78 <!--\r
79 <listitem>\r
80 <para>\r
81 From the Progress dialog after an update\r
82 has finished. Then the Log dialog only shows those revisions\r
83 which were changed since your last update\r
84 </para>\r
85 </listitem>\r
86 -->\r
87 </itemizedlist>\r
88 </para>\r
89 </sect2>\r
90 <sect2 id="tsvn-dug-showlog-actions">\r
91 <title>Revision Log Actions</title>\r
92 <para>\r
93 The top pane has an <guilabel>Actions</guilabel> column containing\r
94 icons that summarize what has been done in that revision.\r
95 There are four different icons, each shown in its own column.\r
96 </para>\r
97 <para>\r
98 <graphic fileref="../images/ActionModifiedIcon.png"/>\r
99 If a revision modified a file or directory, the\r
100 <emphasis>modified</emphasis> icon is shown in the first column.\r
101 </para>\r
102 <para>\r
103 <graphic fileref="../images/ActionAddedIcon.png"/>\r
104 If a revision added a file or directory, the\r
105 <emphasis>added</emphasis> icon is shown in the second column.\r
106 </para>\r
107 <para>\r
108 <graphic fileref="../images/ActionDeletedIcon.png"/>\r
109 If a revision deleted a file or directory, the\r
110 <emphasis>deleted</emphasis> icon is shown in the third column.\r
111 </para>\r
112 <para>\r
113 <graphic fileref="../images/ActionReplacedIcon.png"/>\r
114 If a revision replaced(rename) a file, the\r
115 <emphasis>replaced</emphasis> icon is shown in the fourth column.\r
116 </para>\r
117 </sect2>\r
118 <sect2 id="tsvn-dug-showlog-2">\r
119 <title>Getting Additional Information</title>\r
120 <para>\r
121 <figure id="tsvn-dug-showlog-2-dia-1">\r
122 <title>The Revision Log Dialog Top Pane with Context Menu</title>\r
123 <graphic fileref="../images/LogContextMenu.png"/>\r
124 </figure>\r
125 The top pane of the Log dialog has a context menu that allows you to\r
126 access much more information. Some of these menu entries appear only\r
127 when the log is shown for a file, and some only when the log is shown\r
128 for a folder.\r
129 <variablelist>\r
130 <varlistentry>\r
131 <term>Compare with working copy</term>\r
132 <listitem>\r
133 <para>\r
134 Compare the selected revision with your working copy.\r
135 The default Diff-Tool is TortoiseMerge which\r
136 is supplied with TortoiseGit.\r
137 If the log dialog is for a folder, this will show you a list\r
138 of changed files, and allow you to review the changes made\r
139 to each file individually.\r
140 </para>\r
141 </listitem>\r
142 </varlistentry>\r
143 <!--\r
144 <varlistentry>\r
145 <term>Compare and blame with working BASE</term>\r
146 <listitem>\r
147 <para>\r
148 Blame the selected revision, and the file in your working BASE\r
149 and compare the blame reports using a visual diff tool.\r
150 Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.\r
151 (files only).\r
152 </para>\r
153 </listitem>\r
154 </varlistentry>\r
155 -->\r
156 <varlistentry>\r
157 <term>Show changes as unified diff</term>\r
158 <listitem>\r
159 <para>\r
160 View the changes made in the selected revision as a\r
161 Unified-Diff file (GNU patch format). This shows\r
162 only the differences with a few lines of context. It\r
163 is harder to read than a visual file compare, but will\r
164 show all file changes together in a compact format.\r
165 </para>\r
166 </listitem>\r
167 </varlistentry>\r
168 <varlistentry>\r
169 <term>Compare with previous revision</term>\r
170 <listitem>\r
171 <para>\r
172 Compare the selected revision with the previous revision.\r
173 This works in a similar manner to comparing with your\r
174 working copy.\r
175 For folders this option will first show the changed files\r
176 dialog allowing you to select files to compare.\r
177 </para>\r
178 </listitem>\r
179 </varlistentry>\r
180 <!--\r
181 <varlistentry>\r
182 <term>Compare and blame with previous revision</term>\r
183 <listitem>\r
184 <para>\r
185 Show the changed files dialog allowing you to select files.\r
186 Blame the selected revision, and the previous revision,\r
187 and compare the results using a visual diff tool.\r
188 (folders only).\r
189 </para>\r
190 </listitem>\r
191 </varlistentry>\r
192 -->\r
193 <!--\r
194 <varlistentry>\r
195 <term>Save revision to...</term>\r
196 <listitem>\r
197 <para>\r
198 Save the selected revision to a file so you have an older\r
199 version of that file. (files only).\r
200 </para>\r
201 </listitem>\r
202 </varlistentry>\r
203 -->\r
204 <varlistentry>\r
205 <term>Open / Open with...</term>\r
206 <listitem>\r
207 <para>\r
208 Open the selected file, either with the default viewer for\r
209 that file type, or with a program you choose. (files only).\r
210 </para>\r
211 </listitem>\r
212 </varlistentry>\r
213 <varlistentry>\r
214 <term>Blame...</term>\r
215 <listitem>\r
216 <para>\r
217 Blame the file up to the selected revision. (files only).\r
218 </para>\r
219 </listitem>\r
220 </varlistentry>\r
221 <!--\r
222 <varlistentry>\r
223 <term>Browse repository</term>\r
224 <listitem>\r
225 <para>\r
226 Open the repository browser to examine the selected file or\r
227 folder in the repository as it was at the selected revision.\r
228 </para>\r
229 </listitem>\r
230 </varlistentry>\r
231 -->\r
232 <varlistentry>\r
233 <term>Create branch from revision</term>\r
234 <listitem>\r
235 <para>\r
236 Create a branch from a selected revision.\r
237 This is useful e.g. \r
238 </para>\r
239 </listitem>\r
240 </varlistentry>\r
241 <varlistentry>\r
242 <term>Create tag from revision</term>\r
243 <listitem>\r
244 <para>\r
245 Create a tag from a selected revision.\r
246 This is useful e.g. \r
247 </para>\r
248 </listitem>\r
249 </varlistentry>\r
250 <varlistentry>\r
251 <term>Switch\Checkout to revision</term>\r
252 <listitem>\r
253 <para>\r
254 Update your working copy to the selected revision.\r
255 Useful if you want to have your working copy reflect\r
256 a time in the past, or if there have been further commits to\r
257 the repository and you want to update your working copy one\r
258 step at a time. \r
259 </para>\r
260 </listitem>\r
261 </varlistentry>\r
262 <varlistentry>\r
263 <term>Reset (current branch) to this</term>\r
264 <listitem>\r
265 <para>\r
266 Reset current branch HEAD to selected commit. \r
267 <!-- todo refer reset -->\r
268 </para>\r
269 </listitem>\r
270 </varlistentry>\r
271 <varlistentry>\r
272 <term>Rebase (current branch) to this</term>\r
273 <listitem>\r
274 <para>\r
275 Rebase current branch to selected commit. \r
276 <!-- todo refer rebase -->\r
277 </para>\r
278 </listitem>\r
279 </varlistentry>\r
280 <varlistentry>\r
281 <term>Cherry Pick this commit</term>\r
282 <listitem>\r
283 <para>\r
284 Cherry Pick this commit to current branch\r
285 <!-- todo refer cherry pick -->\r
286 </para>\r
287 </listitem>\r
288 </varlistentry>\r
289 <!--\r
290 <varlistentry>\r
291 <term>Revert changes from this revision</term>\r
292 <listitem>\r
293 <para>\r
294 Revert changes from which were made in the selected\r
295 revision. The changes are reverted in your working copy so\r
296 this operation does <emphasis>not</emphasis> affect the\r
297 repository at all! Note that this will undo the changes\r
298 made in that revision only. It does not replace your\r
299 working copy with the entire file at the earlier revision.\r
300 This is very useful for undoing an earlier change when\r
301 other unrelated changes have been made since. If you have\r
302 made local changes, this command will merge these changes\r
303 into your working copy.\r
304 </para>\r
305 </listitem>\r
306 </varlistentry>\r
307 -->\r
308 <!--\r
309 <varlistentry>\r
310 <term>Revert to this revision</term>\r
311 <listitem>\r
312 <para>\r
313 Revert to an earlier revision. If you have made several\r
314 changes, and then decide that you really want to go back to\r
315 how things were in revision N, this is the command you need.\r
316 Again, the changes are reverted in your working copy so\r
317 this operation does <emphasis>not</emphasis> affect the\r
318 repository until you commit the changes. Note that this\r
319 will undo <emphasis>all</emphasis> changes made after the\r
320 selected revision, replacing the file/folder with the\r
321 earlier version. If you have made local changes, this\r
322 command will merge these changes into your working copy.\r
323 </para>\r
324 </listitem>\r
325 </varlistentry>\r
326 -->\r
327 <!--\r
328 <varlistentry>\r
329 <term>Merge revision to...</term>\r
330 <listitem>\r
331 <para>\r
332 Merge the selected revision(s) into a different working copy.\r
333 A folder selection dialog allows you to choose the working\r
334 copy to merge into, but after that there is no confirmation\r
335 dialog, nor any opportunity to try a test merge. It is a good\r
336 idea to merge into an unmodified working copy so that you can\r
337 revert the changes if it doesn't work out!\r
338 This is a useful feature if you want to merge selected\r
339 revisions from one branch to another.\r
340 </para>\r
341 </listitem>\r
342 </varlistentry>\r
343 -->\r
344 <!--\r
345 <varlistentry>\r
346 <term>Checkout...</term>\r
347 <listitem>\r
348 <para>\r
349 Make a fresh checkout of the selected folder at the selected\r
350 revision. This brings up a dialog for you to confirm the\r
351 URL and revision, and select a location for the checkout.\r
352 </para>\r
353 </listitem>\r
354 </varlistentry>\r
355 -->\r
356 <varlistentry>\r
357 <term>Export...</term>\r
358 <listitem>\r
359 <para>\r
360 Export the selected file/folder at the selected\r
361 revision. This brings up a dialog for you to confirm the\r
362 URL and revision, and select a location for the export.\r
363 </para>\r
364 </listitem>\r
365 </varlistentry>\r
366 <!--\r
367 <varlistentry>\r
368 <term>Edit author / log message</term>\r
369 <listitem>\r
370 <para>\r
371 Edit the log message or author attached to a previous commit.\r
372 Read <xref linkend="tsvn-dug-showlog-4"/> to find out\r
373 how this works.\r
374 </para>\r
375 </listitem>\r
376 </varlistentry>\r
377 -->\r
378 <!--\r
379 <varlistentry>\r
380 <term>Show revision properties</term>\r
381 <listitem>\r
382 <para>\r
383 View and edit any revision property, not just log message\r
384 and author. Refer to <xref linkend="tsvn-dug-showlog-4"/>.\r
385 </para>\r
386 </listitem>\r
387 </varlistentry>\r
388 -->\r
389 <varlistentry>\r
390 <term>Copy to clipboard</term>\r
391 <listitem>\r
392 <para>\r
393 Copy the log details of the selected revisions to the clipboard.\r
394 This will copy the revision number, author, date, log message\r
395 and the list of changed items for each revision.\r
396 </para>\r
397 </listitem>\r
398 </varlistentry>\r
399 <varlistentry>\r
400 <term>Search log messages...</term>\r
401 <listitem>\r
402 <para>\r
403 Search log messages for the text you enter. This searches\r
404 the log messages that you entered and also the action summaries\r
405 created by Git (shown in the bottom pane). The search\r
406 is not case sensitive.\r
407 </para>\r
408 </listitem>\r
409 </varlistentry>\r
410 </variablelist>\r
411 </para>\r
412 <para>\r
413 <figure id="tsvn-dug-showlog-2-dia-1a">\r
414 <title>Top Pane Context Menu for 2 Selected Revisions</title>\r
415 <graphic fileref="../images/LogContextMenu1.png"/>\r
416 </figure>\r
417 If you select two revisions at once (using the usual\r
418 <keycap>Ctrl</keycap>-modifier), the context menu changes and\r
419 gives you fewer options:\r
420 <variablelist>\r
421 <varlistentry>\r
422 <term>Compare revisions</term>\r
423 <listitem>\r
424 <para>\r
425 Compare the two selected revisions using a visual\r
426 difference tool. The default Diff-Tool is TortoiseMerge\r
427 which is supplied with TortoiseGit.\r
428 </para>\r
429 <!--\r
430 <para>\r
431 If you select this option for a folder, a further dialog pops\r
432 up listing the changed files and offering you further\r
433 diff options. Read more about the Compare Revisions\r
434 dialog in <xref linkend="tsvn-dug-compare-revs"/>.\r
435 </para>\r
436 -->\r
437 </listitem>\r
438 </varlistentry>\r
439 <!--\r
440 <varlistentry>\r
441 <term>Blame revisions</term>\r
442 <listitem>\r
443 <para>\r
444 Blame the two revisions and compare the blame reports using\r
445 a visual difference tool.\r
446 Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.\r
447 </para>\r
448 </listitem>\r
449 </varlistentry>\r
450 -->\r
451 <varlistentry>\r
452 <term>Show differences as unified diff</term>\r
453 <listitem>\r
454 <para>\r
455 View the differences between the two selected revisions\r
456 as a Unified-Diff file. This works for files and folders.\r
457 </para>\r
458 </listitem>\r
459 </varlistentry>\r
460 <varlistentry>\r
461 <term>Copy to clipboard</term>\r
462 <listitem>\r
463 <para>\r
464 Copy log messages to clipboard as described above.\r
465 </para>\r
466 </listitem>\r
467 </varlistentry>\r
468 <varlistentry>\r
469 <term>Search log messages...</term>\r
470 <listitem>\r
471 <para>\r
472 Search log messages as described above.\r
473 </para>\r
474 </listitem>\r
475 </varlistentry>\r
476 </variablelist>\r
477 </para>\r
478 \r
479 <para>\r
480 If you select two or more revisions (using the usual\r
481 <keycap>Ctrl</keycap> or <keycap>Shift</keycap> modifiers),\r
482 You can combine select commits to one commit. And cherry pick \r
483 these commits to current branch.\r
484 </para>\r
485 <!--\r
486 <para>\r
487 You can also choose to merge the selected revisions to another\r
488 working copy, as described above.\r
489 </para>\r
490 <para>\r
491 If all selected revisions have the same author, you can edit\r
492 the author of all those revisions in one go.\r
493 </para>\r
494 -->\r
495 <para>\r
496 <figure id="tsvn-dug-showlog-2-dia-2">\r
497 <title>The Log Dialog Bottom Pane with Context Menu</title>\r
498 <graphic fileref="../images/LogContextMenu2.png"/>\r
499 </figure>\r
500 The bottom pane of the Log dialog also has a context menu that allows you to\r
501 <variablelist>\r
502 <!--\r
503 <varlistentry>\r
504 <term>Show changes</term>\r
505 <listitem>\r
506 <para>\r
507 Show changes made in the selected revision for the\r
508 selected file. This context menu is only available for\r
509 files shown as <emphasis>modified</emphasis>.\r
510 </para>\r
511 </listitem>\r
512 </varlistentry>\r
513 <varlistentry>\r
514 <term>Blame changes</term>\r
515 <listitem>\r
516 <para>\r
517 Blame the selected revision and the previous revision for the\r
518 selected file, and compare the blame reports\r
519 using a visual diff tool.\r
520 Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.\r
521 </para>\r
522 </listitem>\r
523 </varlistentry>\r
524 <varlistentry>\r
525 <term>Show as unified diff</term>\r
526 <listitem>\r
527 <para>\r
528 Show file changes in unified diff format.\r
529 This context menu is only available for\r
530 files shown as <emphasis>modified</emphasis>.\r
531 </para>\r
532 </listitem>\r
533 </varlistentry>\r
534 -->\r
535 <varlistentry>\r
536 <term>Open / Open with...</term>\r
537 <listitem>\r
538 <para>\r
539 Open the selected file, either with the default viewer for\r
540 that file type, or with a program you choose.\r
541 </para>\r
542 </listitem>\r
543 </varlistentry>\r
544 <varlistentry>\r
545 <term>Blame...</term>\r
546 <listitem>\r
547 <para>\r
548 Opens the Blame dialog, allowing you to blame up to the\r
549 selected revision.\r
550 </para>\r
551 </listitem>\r
552 </varlistentry>\r
553 <!--\r
554 <varlistentry>\r
555 <term>Revert changes from this revision</term>\r
556 <listitem>\r
557 <para>\r
558 Revert the changes made to the selected file in that revision.\r
559 </para>\r
560 </listitem>\r
561 </varlistentry>\r
562 <varlistentry>\r
563 <term>Show properties</term>\r
564 <listitem>\r
565 <para>\r
566 View the Git properties for the selected item.\r
567 </para>\r
568 </listitem>\r
569 </varlistentry>\r
570 -->\r
571 <!--\r
572 <varlistentry>\r
573 <term>Show log</term>\r
574 <listitem>\r
575 <para>\r
576 Show the revision log for the selected single file.\r
577 </para>\r
578 </listitem>\r
579 </varlistentry>\r
580 <varlistentry>\r
581 <term>Get merge logs</term>\r
582 <listitem>\r
583 <para>\r
584 Show the revision log for the selected single file,\r
585 including merged changes. Find out more in\r
586 <xref linkend="tsvn-dug-showlog-mergetrack"/>.\r
587 </para>\r
588 </listitem>\r
589 </varlistentry>\r
590 <varlistentry>\r
591 <term>Save revision to...</term>\r
592 <listitem>\r
593 <para>\r
594 Save the selected revision to a file so you\r
595 have an older version of that file.\r
596 </para>\r
597 </listitem>\r
598 </varlistentry>\r
599 -->\r
600 </variablelist>\r
601 </para>\r
602 <tip>\r
603 <para>\r
604 You may notice that sometimes we refer to changes and other times\r
605 to differences. What's the difference?\r
606 </para>\r
607 <!--\r
608 <para>\r
609 Git uses commit hash to mean 2 different things.\r
610 A revision generally represents the state of the repository at\r
611 a point in time, but it can also be used to represent the changeset\r
612 which created that revision, eg. <quote>Done in r1234</quote> means \r
613 that the changes committed in r1234 implement feature X.\r
614 To make it clearer which sense is being used, we use two\r
615 different terms.\r
616 </para>\r
617 <para>\r
618 If you select two revisions N and M, the context menu will offer\r
619 to show the <emphasis>difference</emphasis> between those two\r
620 revisions. In Git terms this is\r
621 <literal>diff -r M:N</literal>.\r
622 </para>\r
623 <para>\r
624 If you select a single revision N, the context menu will offer\r
625 to show the <emphasis>changes</emphasis> made in that revision.\r
626 In Git terms this is <literal>diff -r N-1:N</literal>\r
627 or <literal>diff -c N</literal>.\r
628 </para>\r
629 <para>\r
630 The bottom pane shows the files changed in all selected revisions,\r
631 so the context menu always offers to show <emphasis>changes</emphasis>.\r
632 </para>\r
633 -->\r
634 </tip>\r
635 </sect2>\r
636 <!--\r
637 <sect2 id="tsvn-dug-showlog-3">\r
638 <title>Getting more log messages</title>\r
639 <para>\r
640 The Log dialog does not always show all changes ever made for a\r
641 number of reasons:\r
642 <itemizedlist>\r
643 <listitem>\r
644 <para>\r
645 For a large repository there may be hundreds or even\r
646 thousands of changes and fetching them all could take\r
647 a long time. Normally you are only interested in the\r
648 more recent changes. By default, the number of log\r
649 messages fetched is limited to 100, but you can change\r
650 this value in \r
651 <menuchoice>\r
652 <guimenu>TortoiseGit</guimenu>\r
653 <guimenuitem>Settings</guimenuitem>\r
654 </menuchoice>\r
655 (<xref linkend="tsvn-dug-settings-dialogs"/>),\r
656 </para>\r
657 </listitem>\r
658 <listitem>\r
659 <para>\r
660 When the <guilabel>Stop on copy/rename</guilabel>\r
661 box is checked, Show Log will stop at the point that\r
662 the selected file or folder was copied from somewhere\r
663 else within the repository. This can be useful when\r
664 looking at branches (or tags) as it stops at the root\r
665 of that branch, and gives a quick indication of changes\r
666 made in that branch only.\r
667 </para>\r
668 <para>\r
669 Normally you will want to leave this option unchecked.\r
670 TortoiseGit remembers the state of the checkbox, so\r
671 it will respect your preference.\r
672 </para>\r
673 <para>\r
674 When the Show Log dialog is invoked from within the\r
675 Merge dialog, the box is always checked by default.\r
676 This is because merging is most often looking at\r
677 changes on branches, and going back beyond the root\r
678 of the branch does not make sense in that instance.\r
679 </para>\r
680 <para>\r
681 Note that Git currently implements renaming\r
682 as a copy/delete pair, so renaming a file or folder\r
683 will also cause the log display to stop if this\r
684 option is checked.\r
685 </para>\r
686 </listitem>\r
687 </itemizedlist>\r
688 </para>\r
689 <para>\r
690 If you want to see more log messages, click the\r
691 <guibutton>Next 100</guibutton> to retrieve the next 100 log messages.\r
692 You can repeat this as many times as needed.\r
693 </para>\r
694 <para>\r
695 Next to this button there is a multi-function button which remembers\r
696 the last option you used it for. Click on the arrow to see the other\r
697 options offered.\r
698 </para>\r
699 <para>\r
700 Use <guibutton>Show Range ...</guibutton> if you want to view a specific\r
701 range of revisions. A dialog will then prompt you to enter the start\r
702 and end revision.\r
703 </para>\r
704 <para>\r
705 Use <guibutton>Show All</guibutton> if you want to see\r
706 <emphasis>all</emphasis> log messages from HEAD right back to revision 1.\r
707 </para>\r
708 </sect2>\r
709 -->\r
710 <!--\r
711 <sect2 id="tsvn-dug-showlog-current-rev">\r
712 <title>Current Working Copy Revision</title>\r
713 <para>\r
714 Because the log dialog shows you the log from HEAD, not from the\r
715 current working copy revision, it often happens that there are\r
716 log messages shown for content which has not yet been updated\r
717 in your working copy. To help make this clearer, the commit\r
718 message which corresponds to the revision you have in your\r
719 working copy is shown in bold.\r
720 </para>\r
721 <para>\r
722 By default this only works for files. This is because the\r
723 update revision for a folder may not correspond to the update\r
724 revision of its content, and the only way to find the effective\r
725 update revision for the folder is to crawl the working copy.\r
726 This can be a slow operation for large working copies so if\r
727 you want to enable this feature you must create a\r
728 <literal>DWORD</literal> registry key with value 1 at\r
729 <literal>HKCU\Software\TortoiseGit\RecursiveLogRev</literal>.\r
730 </para>\r
731 </sect2>\r
732 -->\r
733 <!--\r
734 <sect2 id="tsvn-dug-showlog-mergetrack">\r
735 <title>Merge Tracking Features</title>\r
736 <indexterm>\r
737 <primary>merge tracking log</primary>\r
738 </indexterm>\r
739 <para>\r
740 Git 1.5 and later keeps a record of merges using properties.\r
741 This allows us to get a more detailed history of merged changes.\r
742 For example, if you develop a new feature on a branch and then merge\r
743 that branch back to trunk, the feature development will show up on\r
744 the trunk log as a single commit for the merge, even though there\r
745 may have been 1000 commits during branch development.\r
746 </para>\r
747 <figure id="tsvn-dug-showlog-dia-mergetrack">\r
748 <title>The Log Dialog Showing Merge Tracking Revisions</title>\r
749 <graphic fileref="../images/LogMergeTrack.png"/>\r
750 </figure>\r
751 <para>\r
752 If you want to see the detail of which revisions were merged as part\r
753 of that commit, use the <guilabel>Include merged revisions</guilabel>\r
754 checkbox. This will fetch the log messages again, but will also\r
755 interleave the log messages from revisions which were merged.\r
756 Merged revisions are shown in grey because they represent changes\r
757 made on a different part of the tree.\r
758 </para>\r
759 <para>\r
760 Of course, merging is never simple! During feature development on the\r
761 branch there will probably be occasional merges back from trunk to\r
762 keep the branch in sync with the main line code. So the merge history\r
763 of the branch will also include another layer of merge history.\r
764 These different layers are shown in the log dialog using indentation\r
765 levels.\r
766 </para>\r
767 </sect2>\r
768 -->\r
769 <!--\r
770 <sect2 id="tsvn-dug-showlog-4">\r
771 <title>Changing the Log Message and Author</title>\r
772 <indexterm>\r
773 <primary>edit log/author</primary>\r
774 </indexterm>\r
775 <indexterm>\r
776 <primary>revision properties</primary>\r
777 </indexterm>\r
778 <indexterm>\r
779 <primary>revprops</primary>\r
780 </indexterm>\r
781 <para>\r
782 Revision properties are completely different from the Git\r
783 properties of each item. Revprops are descriptive items which are\r
784 associated with one specific revision number in the repository,\r
785 such as log message, commit date and committer name (author).\r
786 </para>\r
787 <para>\r
788 Sometimes you might want to change a log message you once entered,\r
789 maybe because there's a spelling error in it or you want to\r
790 improve the message or change it for other reasons. Or you want to\r
791 change the author of the commit because you forgot to set up\r
792 authentication or...\r
793 </para>\r
794 <para>\r
795 Git lets you change revision properties any time you want.\r
796 But since such changes can't be\r
797 undone (those changes are not versioned) this feature is disabled\r
798 by default. To make this work, you must set up a pre-revprop-change\r
799 hook. Please refer to the chapter on\r
800 <ulink url="http://svnbook.red-bean.com/en/1.5/svn.reposadmin.create.html#svn.reposadmin.create.hooks">\r
801 <citetitle>Hook Scripts</citetitle>\r
802 </ulink>\r
803 in the Git Book for details about how to do that.\r
804 Read <xref linkend="tsvn-repository-hooks"/> to find some further\r
805 notes on implementing hooks on a Windows machine.\r
806 </para>\r
807 <para>\r
808 Once you've set up your server with the required hooks, you can\r
809 change the author and log message (or any other revprop) of any revision,\r
810 using the context menu from the top pane of the Log dialog.\r
811 You can also edit a log message using the context menu for the middle pane.\r
812 </para>\r
813 <warning>\r
814 <para>\r
815 Because Git's revision properties are not versioned, making \r
816 modifications to such a property (for example, the\r
817 <literal>svn:log</literal> commit \r
818 message property) will overwrite the previous value of that \r
819 property <emphasis>forever</emphasis>.\r
820 </para>\r
821 </warning>\r
822 </sect2>\r
823 -->\r
824 <sect2 id="tsvn-dug-showlog-filter">\r
825 <title>Filtering Log Messages</title>\r
826 <indexterm>\r
827 <primary>filter</primary>\r
828 </indexterm>\r
829 <para>\r
830 If you want to restrict the log messages to show only those\r
831 you are interested in rather than scrolling through a list\r
832 of hundreds, you can use the filter controls at the top of\r
833 the Log Dialog. The start and end date controls allow you\r
834 to restrict the output to a known date range. The search\r
835 box allows you to show only messages which contain a\r
836 particular phrase.\r
837 </para>\r
838 <para>\r
839 Click on the search icon to select which information you want\r
840 to search in, and to choose <emphasis>regex</emphasis> mode.\r
841 Normally you will only need a simple text search, but if you\r
842 need to more flexible search terms, you can use regular expressions.\r
843 If you hover the mouse over the box, a tooltip will give hints\r
844 on how to use the regex functions.\r
845 You can also find online documentation and a tutorial at\r
846 <ulink url="http://www.regular-expressions.info/">\r
847 <citetitle>http://www.regular-expressions.info/</citetitle>\r
848 </ulink>.\r
849 The filter works by checking whether your filter string matches\r
850 the log entries, and then only those entries which <emphasis>match</emphasis>\r
851 the filter string are shown.\r
852 </para>\r
853 <para>\r
854 To make the filter show all log entries that do <emphasis>not</emphasis>\r
855 match the filter string, start the string with an exclamation mark ('!').\r
856 For example, a filter string <literal>!username</literal> will only\r
857 show those entries which were not committed by <literal>username</literal>.\r
858 </para>\r
859 <para>\r
860 Note that these filters act on the messages already retrieved.\r
861 They do not control downloading of messages from the repository.\r
862 </para>\r
863 <para>\r
864 You can also filter the path names in the bottom pane using the\r
865 <guilabel>Hide unrelated changed paths</guilabel> checkbox.\r
866 Related paths are those which contain the path used to display\r
867 the log. If you fetch the log for a folder, that means anything\r
868 in that folder or below it. For a file it means just that one file.\r
869 The checkbox is tristate: you can show all paths, grey out the\r
870 unrelated ones, or hide the unrelated paths completely.\r
871 </para>\r
872 <para>\r
873 Sometimes your working practices will require log messages to follow\r
874 a particular format, which means that the text describing the changes\r
875 is not visible in the abbreviated summary shown in the top pane.\r
876 The property <literal>tsvn:logsummary</literal> can be used to\r
877 extract a portion of the log message to be shown in the top pane.\r
878 Read <xref linkend="tsvn-dug-propertypage-tsvn-props"/> to find\r
879 out how to use this property.\r
880 </para>\r
881 <tip>\r
882 <title>No Log Formatting from Repository Browser</title>\r
883 <para>\r
884 Because the formatting depends upon accessing Git\r
885 properties, you will only see the results when using a checked\r
886 out working copy. Fetching properties remotely is a slow operation,\r
887 so you will not see this feature in action from the repo browser.\r
888 </para>\r
889 </tip>\r
890 </sect2>\r
891 <sect2 id="tsvn-dug-showlog-5">\r
892 <?dbhh topicname="HIDD_STATGRAPH"?>\r
893 <title>Statistical Information</title>\r
894 <indexterm>\r
895 <primary>statistics</primary>\r
896 </indexterm>\r
897 <para>\r
898 The <guibutton>Statistics</guibutton> button brings up a box\r
899 showing some interesting information about the revisions\r
900 shown in the Log dialog. This shows how many authors have\r
901 been at work, how many commits they have made, progress\r
902 by week, and much more. Now you can see at a glance who\r
903 has been working hardest and who is slacking ;-)\r
904 </para>\r
905 <sect3 id="tsvn-dug-showlog-stats-1">\r
906 <title>Statistics Page</title>\r
907 <para>\r
908 This page gives you all the numbers you can think of,\r
909 in particular the period and number of revisions covered,\r
910 and some min/max/average values.\r
911 </para>\r
912 </sect3>\r
913 <sect3 id="tsvn-dug-showlog-stats-2">\r
914 <title>Commits by Author Page</title>\r
915 <para>\r
916 <figure id="tsvn-dug-showlog-stats-dia-2">\r
917 <title>Commits-by-Author Histogram</title>\r
918 <graphic fileref="../images/StatsByAuthor.png"/>\r
919 </figure>\r
920 This graph shows you which authors have been active on the\r
921 project as a simple histogram, stacked histogram or\r
922 pie chart.\r
923 <figure id="tsvn-dug-showlog-stats-dia-3">\r
924 <title>Commits-by-Author Pie Chart</title>\r
925 <graphic fileref="../images/StatsByAuthPie.png"/>\r
926 </figure>\r
927 </para>\r
928 <para>\r
929 Where there are a few major authors and many minor contributors,\r
930 the number of tiny segments can make the graph more difficult to\r
931 read. The slider at the bottom allows you to set a threshold\r
932 (as a percentage of total commits) below which any activity is\r
933 grouped into an <emphasis>Others</emphasis> category.\r
934 </para>\r
935 </sect3>\r
936 <sect3 id="tsvn-dug-showlog-stats-3">\r
937 <title>Commits by date Page</title>\r
938 <para>\r
939 <figure id="tsvn-dug-showlog-stats-dia-4">\r
940 <title>Commits-by-date Graph</title>\r
941 <graphic fileref="../images/StatsByDate.png"/>\r
942 </figure>\r
943 This page gives you a graphical representation of project\r
944 activity in terms of number of commits <emphasis>and</emphasis>\r
945 author. This gives some idea of when a project is being worked\r
946 on, and who was working at which time.\r
947 </para>\r
948 <para>\r
949 When there are several authors, you will get many lines on the\r
950 graph. There are two views available here: <emphasis>normal</emphasis>,\r
951 where each author's activity is relative to the base line, and\r
952 <emphasis>stacked</emphasis>, where each author's activity is\r
953 relative to the line underneath.\r
954 The latter option avoids the lines crossing over, which can make\r
955 the graph easier to read, but less easy to see one author's output.\r
956 </para>\r
957 </sect3>\r
958 <para>\r
959 By default the analysis is case-sensitive, so users\r
960 <literal>PeterEgan</literal> and <literal>PeteRegan</literal>\r
961 are treated as different authors. However, in many cases user names\r
962 are not case-sensitive, and are sometimes entered inconsistently,\r
963 so you may want <literal>DavidMorgan</literal> and\r
964 <literal>davidmorgan</literal> to be treated as the same person.\r
965 Use the <guilabel>Authors case insensitive</guilabel> checkbox\r
966 to control how this is handled.\r
967 </para>\r
968 <para>\r
969 Note that the statistics cover the same period as the\r
970 Log dialog. If that is only displaying one revision\r
971 then the statistics will not tell you very much.\r
972 </para>\r
973 </sect2>\r
974 <!--\r
975 <sect2 id="tsvn-dug-showlog-cache">\r
976 <?dbhh topicname="HIDD_GOOFFLINE"?>\r
977 <title>Offline Mode</title>\r
978 <para>\r
979 If the server is not reachable, and you have log caching enabled\r
980 you can use the log dialog and revision graph in offline mode.\r
981 This uses data from the cache, which allows you to continue working\r
982 although the information may not be up-to-date or even complete.\r
983 </para>\r
984 </sect2>\r
985 -->\r
986 <sect2 id="tsvn-dug-showlog-refresh">\r
987 <title>Refreshing the View</title>\r
988 <para>\r
989 If you want to check the repository again for newer log messages,\r
990 you can simply refresh the view using <keycap>F5</keycap>. If you\r
991 are using the log cache (enabled by default), this will check the\r
992 repository for newer messages and fetch only the new ones.\r
993 </para>\r
994 <!--\r
995 <para>\r
996 If you are using the log cache and you think the message content\r
997 or author may have changed, you can use <keycap>Shift-F5</keycap>\r
998 or <keycap>Ctrl-F5</keycap> to re-fetch the displayed messages from\r
999 the server and update the log cache. Note that this only affects\r
1000 messages currently shown and does not invalidate the entire cache\r
1001 for that repository.\r
1002 </para>\r
1003 -->\r
1004 </sect2>\r
1005 </sect1>\r