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