| blob | 37218df3bb5f4c88750d12d6aae3120195e12062 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tgit-dug-showlog">\r
4 <title>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 <indexterm>\r
18 <primary>revision log dialog</primary>\r
19 </indexterm>\r
20 <?dbhh topicname="HIDD_LOGMESSAGE"?>\r
21 <?dbhh topicname="HIDD_LOGORDERING"?>\r
22 <para>\r
23 For every change you make and commit, you should provide\r
24 a log message for that change. That way you can later find out\r
25 what changes you made and why, and you have a detailed log for\r
26 your development process.\r
27 </para>\r
28 <para>\r
29 The Log Dialog retrieves all those log messages and shows them\r
30 to you.\r
31 The display is divided into 3 panes.\r
32 <itemizedlist>\r
33 <listitem>\r
34 <para>\r
35 The top pane shows a list of revisions where changes to the\r
36 file/folder have been committed. This summary includes the\r
37 date and time, the person who committed the revision and the\r
38 start of the log message.\r
39 </para>\r
40 <para>\r
41 The line shown in bold indicates the HEAD commit and the entry "Working tree changes" is a virtual entry representing the current (uncommitted) state of your working tree.\r
42 </para>\r
43 </listitem>\r
44 <listitem>\r
45 <para>\r
46 The middle pane shows the full log message for the selected\r
47 revision.\r
48 </para>\r
49 </listitem>\r
50 <listitem>\r
51 <para>\r
52 The bottom pane shows a list of all files and folders that\r
53 were changed as part of the selected revision.\r
54 </para>\r
55 </listitem>\r
56 </itemizedlist>\r
57 But it does much more than that - it provides context menu\r
58 commands which you can use to get even more information about the\r
59 project history.\r
60 </para>\r
61 <sect2 id="tgit-dug-showlog-1">\r
62 <title>Invoking the Revision Log Dialog</title>\r
63 <para>\r
64 <figure id="tgit-dug-showlog-1-dia-1">\r
65 <title>The Revision Log Dialog</title>\r
66 <graphic fileref="../images/LogMessages.png"/>\r
67 </figure>\r
68 There are several places from where you can show the Log dialog:\r
69 <itemizedlist>\r
70 <listitem>\r
71 <para>\r
72 From the explorer context menu using\r
73 <menuchoice>\r
74 <guimenu>TortoiseGit</guimenu>\r
75 <guimenuitem>Show log...</guimenuitem>\r
76 </menuchoice>.\r
77 </para>\r
78 </listitem>\r
79 <listitem>\r
80 <para>\r
81 From various TortoiseGit dialogs where you can select a commit (oftentimes using a <guibutton>...</guibutton> button).\r
82 </para>\r
83 </listitem>\r
84 <listitem>\r
85 <para>\r
86 From various TortoiseGit dialogs where commit entries or files are shown using the context menu.\r
87 </para>\r
88 </listitem>\r
89 </itemizedlist>\r
90 </para>\r
91 </sect2>\r
92 <sect2 id="tgit-dug-showlog-actions">\r
93 <title>Revision Log Actions</title>\r
94 <para>\r
95 The top pane has an <guilabel>Actions</guilabel> column containing\r
96 icons that summarize what has been done in that revision.\r
97 There are four different icons, each shown in its own column.\r
98 </para>\r
99 <para>\r
100 <graphic fileref="../images/ActionModifiedIcon.png"/>\r
101 If a revision modified a file or directory, the\r
102 <emphasis>modified</emphasis> icon is shown in the first column.\r
103 </para>\r
104 <para>\r
105 <graphic fileref="../images/ActionAddedIcon.png"/>\r
106 If a revision added a file or directory, the\r
107 <emphasis>added</emphasis> icon is shown in the second column.\r
108 </para>\r
109 <para>\r
110 <graphic fileref="../images/ActionDeletedIcon.png"/>\r
111 If a revision deleted a file or directory, the\r
112 <emphasis>deleted</emphasis> icon is shown in the third column.\r
113 </para>\r
114 <para>\r
115 <graphic fileref="../images/ActionReplacedIcon.png"/>\r
116 If a revision replaced(rename) a file, the\r
117 <emphasis>replaced</emphasis> icon is shown in the fourth column.\r
118 </para>\r
119 </sect2>\r
120 <sect2 id="tgit-dug-showlog-graph">\r
121 <title>The revision graph</title>\r
122 <para>\r
123 The top pane has a <guilabel>Graph</guilabel> column with a line showing\r
124 the commits, merges and branches. There are two types of shapes.\r
125 </para>\r
126 <para>\r
127 The circles indicate normal commits w/o any branching.\r
128 </para>\r
129 <para>\r
130 The squares indicate merges and branchings. In the first case these are merge commits\r
131 (i.e., a commit with more than one parent) and in the latter case these are also normal commits.\r
132 A square was chosen here to indicate that a branch goes off.\r
133 </para>\r
134 <para>\r
135 The colors of the lines (and of the shapes) are there to make the graph better readable (i.e., to see to which branch they belong).\r
136 The colors are configurable (cf. <xref linkend="tgit-dug-settings-colours3"/>).\r
137 </para>\r
138 </sect2>\r
139 <sect2 id="tgit-dug-showlog-messages">\r
140 <title>Commit messages and branch/tag indicators</title>\r
141 <para>\r
142 The top pane also has a <guilabel>message</guilabel> column.\r
143 In this column the subjects of the commits are shown.\r
144 Commits which have an associated reference are decorated with a label.\r
145 </para>\r
146 <para>\r
147 Tags are by default displayed as yellow rectangles. In Git there are two tag types: normal tags and annotated tags. The annotated ones have an apex at the right side.\r
148 </para>\r
149 <para>\r
150 Normally branches are displayed as normal rectangles. The active branch is displayed as a dark red rectangle (by default), the green ones are local branches and the peach ones are remote branches.\r
151 </para>\r
152 <para>\r
153 The boxes with rounded corners for local branches indicate that it has an associated remote tracking. The boxes with rounded corners for remote tracking branches are used to indicate which of (possible several remote branches) is the corresponding remote tracking branch (e.g., master and origin/master).\r
154 </para>\r
155 <para>\r
156 The stash has a dark gray rectangle.\r
157 </para>\r
158 <para>\r
159 There are also rectangles to indicate the bad versions (light red) on bisecting, blue for known good and gray for skip.\r
160 </para>\r
161 <para>\r
162 Depending on what branch/tag label you open the context menu, it is optimized for that ref it was opened on (e.g., a local branch offers directly to switch to it and to push it whereas a remote branch has no push option).\r
163 </para>\r
164 <para>\r
165 The colors are configurable (cf. <xref linkend="tgit-dug-settings-colours2"/>). Also, the labels can be configured to be a the right side of the commit message or the displayed text to contain the whole of the commit message (cf. <xref linkend="tgit-dug-settings-dialogs"/>).\r
166 </para>\r
167 </sect2>\r
168 <sect2 id="tgit-dug-showlog-2">\r
169 <title>Getting Additional Information</title>\r
170 <para>\r
171 <figure id="tgit-dug-showlog-2-dia-1">\r
172 <title>The Revision Log Dialog Top Pane with Context Menu</title>\r
173 <graphic fileref="../images/LogContextMenu.png"/>\r
174 </figure>\r
175 The top pane of the Log dialog has a context menu that allows you to\r
176 access much more information. <!-- Some of these menu entries appear only\r
177 when the log is shown for a file, and some only when the log is shown\r
178 for a folder. --> You can press the <keycap>Shift</keycap> key to see the extended menu with some more options (e.g., pushing and opening the log from every commit).\r
179 <variablelist>\r
180 <varlistentry>\r
181 <term>Compare with working tree</term>\r
182 <listitem>\r
183 <para>\r
184 Compare the selected revision with your working tree.\r
185 The default Diff-Tool is TortoiseGitMerge which\r
186 is supplied with TortoiseGit.\r
187 If the log dialog is for a folder, this will show you a list\r
188 of changed files, and allow you to review the changes made\r
189 to each file individually.\r
190 </para>\r
191 </listitem>\r
192 </varlistentry>\r
193 <varlistentry>\r
194 <term>Show changes as unified diff</term>\r
195 <listitem>\r
196 <para>\r
197 View the changes made in the selected revision as a\r
198 Unified-Diff file (GNU patch format). This shows\r
199 only the differences with a few lines of context. It\r
200 is harder to read than a visual file compare, but will\r
201 show all file changes together in a compact format.\r
202 </para>\r
203 </listitem>\r
204 </varlistentry>\r
205 <varlistentry>\r
206 <term>Compare with previous revision</term>\r
207 <listitem>\r
208 <para>\r
209 Compare the selected revision with the previous revision.\r
210 This works in a similar manner to comparing with your\r
211 working tree.\r
212 For folders this option will first show the changed files\r
213 dialog allowing you to select files to compare.\r
214 </para>\r
215 </listitem>\r
216 </varlistentry>\r
217 <varlistentry>\r
218 <term>Browse repository</term>\r
219 <listitem>\r
220 <para>\r
221 Open the repository browser to examine the selected file or\r
222 folder in the repository as it was at the selected revision (cf. <xref linkend="tgit-dug-repobrowser"/>).\r
223 </para>\r
224 </listitem>\r
225 </varlistentry>\r
226 <varlistentry>\r
227 <term>Reset (current branch) to this</term>\r
228 <listitem>\r
229 <para>\r
230 Resets the HEAD to the selected commit (cf. <xref linkend="tgit-dug-reset"/>).\r
231 </para>\r
232 </listitem>\r
233 </varlistentry>\r
234 <varlistentry>\r
235 <term>Switch / Checkout to revision</term>\r
236 <listitem>\r
237 <para>\r
238 Update your working tree to the selected revision.\r
239 Useful if you want to have your working tree reflect\r
240 a time in the past, or if there have been further commits to\r
241 the repository and you want to update your working tree one\r
242 step at a time.\r
243 </para>\r
244 </listitem>\r
245 </varlistentry>\r
246 \r
247 <varlistentry>\r
248 <term>Create branch from revision</term>\r
249 <listitem>\r
250 <para>\r
251 Create a branch based on the selected revision (cf. <xref linkend="tgit-dug-branchtag"/>).\r
252 </para>\r
253 </listitem>\r
254 </varlistentry>\r
255 <varlistentry>\r
256 <term>Create tag from revision</term>\r
257 <listitem>\r
258 <para>\r
259 Create a tag on a selected revision (cf. <xref linkend="tgit-dug-branchtag"/>).\r
260 </para>\r
261 </listitem>\r
262 </varlistentry>\r
263 <varlistentry>\r
264 <term>Rebase (current branch) to this</term>\r
265 <listitem>\r
266 <para>\r
267 Rebase current branch on top of the selected commit (cf. <xref linkend="tgit-dug-rebase"/>).\r
268 </para>\r
269 </listitem>\r
270 </varlistentry>\r
271 <varlistentry>\r
272 <term>Export this version...</term>\r
273 <listitem>\r
274 <para>\r
275 Export the selected revision to an archive file such as zip. This brings up a dialog for you to confirm the\r
276 revision, and select a location for the export (cf. <xref linkend="tgit-dug-export"/>).\r
277 </para>\r
278 </listitem>\r
279 </varlistentry>\r
280 <varlistentry>\r
281 <term>Revert change by this commit</term>\r
282 <listitem>\r
283 <para>\r
284 Revert changes from which were made in the selected\r
285 revision. All changes are integrated into your working tree.\r
286 You may choose to commit immediately or edit and commit later.\r
287 To abandon the reverted changes, perform a hard reset.\r
288 </para>\r
289 </listitem>\r
290 </varlistentry>\r
291 <varlistentry>\r
292 <term>Edit notes</term>\r
293 <listitem>\r
294 <para>\r
295 Edit notes of the selected commit.\r
296 </para>\r
297 </listitem>\r
298 </varlistentry>\r
299 <varlistentry>\r
300 <term>Collapse revisions</term>\r
301 <listitem>\r
302 <para>\r
303 Do not show parent commits up to a merge or branch point or a commit\r
304 marked with a branch or tag. This is similar to\r
305 <menuchoice>\r
306 <guimenu>Walk Behavior</guimenu>\r
307 <guimenuitem>Compressed Graph</guimenuitem>\r
308 </menuchoice>,\r
309 but only for selected revisions.\r
310 </para>\r
311 <para>\r
312 Collapsed items are displayed in the graph with hollow circles and squares.\r
313 In the following screenshot the commits of the merged branch in which issue 3764 was fixed and also all commits starting from the libgit2 update commit until the next merge commit were collapsed.\r
314 <figure id="tgit-dug-showlog-collapsed-dia-1">\r
315 <title>Collapsed revisions</title>\r
316 <graphic fileref="../images/LogCollapsedRevs.png"/>\r
317 </figure>\r
318 </para>\r
319 </listitem>\r
320 </varlistentry>\r
321 <varlistentry>\r
322 <term>Expand hidden revisions</term>\r
323 <listitem>\r
324 <para>\r
325 This is shown for collapsed items instead of <guilabel>Collapse revisions</guilabel>\r
326 and reverts the action.\r
327 </para>\r
328 </listitem>\r
329 </varlistentry>\r
330 <varlistentry>\r
331 <term>Cherry Pick this commit</term>\r
332 <listitem>\r
333 <para>\r
334 Cherry Pick this commit on top of HEAD (cf. <xref linkend="tgit-dug-cherrypick"/>).\r
335 </para>\r
336 </listitem>\r
337 </varlistentry>\r
338 <varlistentry>\r
339 <term>Bisect start</term>\r
340 <listitem>\r
341 <para>\r
342 Start bisection. Find by binary search the change that introduced a bug (cf. <xref linkend="tgit-dug-bisect"/>).\r
343 </para>\r
344 </listitem>\r
345 </varlistentry>\r
346 <varlistentry>\r
347 <term>Format Patch...</term>\r
348 <listitem>\r
349 <para>\r
350 Create Patches from this commit.\r
351 </para>\r
352 </listitem>\r
353 </varlistentry>\r
354 <varlistentry>\r
355 <term>Copy SHA-1 to clipboard</term>\r
356 <listitem>\r
357 <para>\r
358 Copy the commit hash of the selected revision to the clipboard.\r
359 </para>\r
360 </listitem>\r
361 </varlistentry>\r
362 <varlistentry>\r
363 <term>Copy to clipboard</term>\r
364 <listitem>\r
365 <para>\r
366 Copy the log details of the selected revisions to the clipboard.\r
367 This will copy the revision number, author, date, log message\r
368 and the list of changed items for each revision.\r
369 </para>\r
370 </listitem>\r
371 </varlistentry>\r
372 <varlistentry>\r
373 <term>Copy log message to clipboard</term>\r
374 <listitem>\r
375 <para>\r
376 Copy the log message of the selected revision to the clipboard.\r
377 </para>\r
378 </listitem>\r
379 </varlistentry>\r
380 <varlistentry>\r
381 <term>Search log messages...</term>\r
382 <listitem>\r
383 <figure id="tgit-dug-showlog-1-dia-2">\r
384 <title>The Search Log Messages Dialog</title>\r
385 <graphic fileref="../images/LogSearch.png"/>\r
386 </figure>\r
387 <para>\r
388 Search log messages for the text you enter. This searches\r
389 the log messages that you entered and also the action summaries\r
390 created by Git (shown in the bottom pane). The search\r
391 is not case sensitive.\r
392 </para>\r
393 <tip>\r
394 <para>\r
395 This allows you to easily search for refs (tags and branches).\r
396 </para>\r
397 <para>\r
398 If you press <keycap>SHIFT</keycap> while clicking on a ref or on <guibutton>Find</guibutton> you can navigate to the commit w/o selecting it.\r
399 </para>\r
400 </tip>\r
401 </listitem>\r
402 </varlistentry>\r
403 <varlistentry>\r
404 <term>Shows branches this commit is on</term>\r
405 <listitem>\r
406 <para>\r
407 Shows the branches that the select commit belongs to.\r
408 It shows both local and remote branches.\r
409 </para>\r
410 </listitem>\r
411 </varlistentry>\r
412 </variablelist>\r
413 </para>\r
414 <para>\r
415 <figure id="tgit-dug-showlog-2-dia-1a">\r
416 <title>Top Pane Context Menu for 2 Selected Revisions</title>\r
417 <graphic fileref="../images/LogContextMenu1.png"/>\r
418 </figure>\r
419 If you select two revisions at once (using the usual\r
420 <keycap>Ctrl</keycap>-modifier), the context menu changes and\r
421 gives you fewer options:\r
422 <variablelist>\r
423 <varlistentry>\r
424 <term>Compare revisions</term>\r
425 <listitem>\r
426 <para>\r
427 Compare the two selected revisions using a visual\r
428 difference tool. The default Diff-Tool is TortoiseGitMerge\r
429 which is supplied with TortoiseGit.\r
430 </para>\r
431 </listitem>\r
432 </varlistentry>\r
433 <varlistentry>\r
434 <term>Show differences as unified diff</term>\r
435 <listitem>\r
436 <para>\r
437 View the differences between the two selected revisions\r
438 as a Unified-Diff file. This works for files and folders.\r
439 </para>\r
440 </listitem>\r
441 </varlistentry>\r
442 <varlistentry>\r
443 <term>Revert changes by these commits</term>\r
444 <listitem>\r
445 <para>\r
446 Revert changes from which were made in the selected\r
447 revisions. All changes are integrated into your working tree.\r
448 You may choose to commit immediately or edit and commit later.\r
449 To abandon the reverted changes, perform a hard reset.\r
450 </para>\r
451 </listitem>\r
452 </varlistentry>\r
453 <varlistentry>\r
454 <term>Combine to one commit</term>\r
455 <listitem>\r
456 <para>\r
457 Combine continuous commits to one commit.\r
458 </para>\r
459 </listitem>\r
460 </varlistentry>\r
461 <varlistentry>\r
462 <term>Cherry Pick selected commits</term>\r
463 <listitem>\r
464 <para>\r
465 Cherry Pick chosen Commits on top of current HEAD (cf. <xref linkend="tgit-dug-cherrypick"/>).\r
466 </para>\r
467 </listitem>\r
468 </varlistentry>\r
469 <varlistentry>\r
470 <term>Format Patch...</term>\r
471 <listitem>\r
472 <para>\r
473 Create patches between two chosen commits.\r
474 </para>\r
475 </listitem>\r
476 </varlistentry>\r
477 <varlistentry>\r
478 <term>Copy SHA-1 to clipboard</term>\r
479 <listitem>\r
480 <para>\r
481 Copy the commit hashes of the selected revisions to the clipboard, delimited by CRLF.\r
482 </para>\r
483 </listitem>\r
484 </varlistentry>\r
485 <varlistentry>\r
486 <term>Copy to clipboard</term>\r
487 <listitem>\r
488 <para>\r
489 Copy log messages to clipboard as described above.\r
490 </para>\r
491 </listitem>\r
492 </varlistentry>\r
493 <varlistentry>\r
494 <term>Copy log messages to clipboard</term>\r
495 <listitem>\r
496 <para>\r
497 Copy the log messages of the selected revisions to the clipboard.\r
498 This will copy the log message for each revision.\r
499 This facilitates the preparation of release notes.\r
500 </para>\r
501 </listitem>\r
502 </varlistentry>\r
503 <varlistentry>\r
504 <term>Search log messages...</term>\r
505 <listitem>\r
506 <para>\r
507 Search log messages as described above.\r
508 </para>\r
509 </listitem>\r
510 </varlistentry>\r
511 </variablelist>\r
512 </para>\r
513 <para>\r
514 If you select two or more revisions (using the usual\r
515 <keycap>Ctrl</keycap> or <keycap>Shift</keycap> modifiers),\r
516 You can combine select commits to one commit. And cherry pick\r
517 these commits to current branch.\r
518 </para>\r
519 <para>\r
520 <figure id="tgit-dug-showlog-2-dia-2">\r
521 <title>The Log Dialog Bottom Pane with Context Menu</title>\r
522 <graphic fileref="../images/LogContextMenu2.png"/>\r
523 </figure>\r
524 The bottom pane of the Log dialog also has a context menu that allows you to\r
525 <variablelist>\r
526 <varlistentry>\r
527 <term>Compare with base</term>\r
528 <listitem>\r
529 <para>\r
530 Compare chosen file with base version.\r
531 </para>\r
532 </listitem>\r
533 </varlistentry>\r
534 \r
535 <varlistentry>\r
536 <term>Show as unified diff</term>\r
537 <listitem>\r
538 <para>\r
539 Show file changes in unified diff format.\r
540 This context menu is only available for\r
541 files shown as <emphasis>modified</emphasis>.\r
542 </para>\r
543 </listitem>\r
544 </varlistentry>\r
545 <varlistentry>\r
546 <term>Compare with working tree</term>\r
547 <listitem>\r
548 <para>\r
549 Compare chosen file with working tree.\r
550 </para>\r
551 </listitem>\r
552 </varlistentry>\r
553 \r
554 <varlistentry>\r
555 <term>Revert changes to this revision</term>\r
556 <listitem>\r
557 <para>\r
558 Revert chosen files to the state of this revision.\r
559 </para>\r
560 </listitem>\r
561 </varlistentry>\r
562 <varlistentry>\r
563 <term>Revert changes to parent revision</term>\r
564 <listitem>\r
565 <para>\r
566 Revert chosen files to the state before this revision.\r
567 </para>\r
568 </listitem>\r
569 </varlistentry>\r
570 <varlistentry>\r
571 <term>Show log</term>\r
572 <listitem>\r
573 <para>\r
574 Show the revision log for the selected single file.\r
575 </para>\r
576 </listitem>\r
577 </varlistentry>\r
578 \r
579 <varlistentry>\r
580 <term>Blame...</term>\r
581 <listitem>\r
582 <para>\r
583 Opens the Blame dialog, allowing you to blame up to the\r
584 selected revision (cf. <xref linkend="tgit-dug-blame"/>).\r
585 </para>\r
586 </listitem>\r
587 </varlistentry>\r
588 \r
589 <varlistentry>\r
590 <term>Save revision to...</term>\r
591 <listitem>\r
592 <para>\r
593 Save the selected revision to a file so you\r
594 have an older version of that file.\r
595 </para>\r
596 </listitem>\r
597 </varlistentry>\r
598 \r
599 <varlistentry>\r
600 <term>Export selection to...</term>\r
601 <listitem>\r
602 <para>\r
603 Saves the selected files to a target directory. Compared to "Save revision to..." this preserves the directory structure.\r
604 </para>\r
605 </listitem>\r
606 </varlistentry>\r
607 \r
608 <varlistentry>\r
609 <term>View revision in alternative editor</term>\r
610 <listitem>\r
611 <para>\r
612 Show chosen file with an alternative editor such as notepad2 with chosen commit.\r
613 </para>\r
614 </listitem>\r
615 </varlistentry>\r
616 \r
617 <varlistentry>\r
618 <term>Open/Open with...</term>\r
619 <listitem>\r
620 <para>\r
621 Open the selected file, either with the default viewer for\r
622 that file type, or with a program you choose.\r
623 </para>\r
624 </listitem>\r
625 </varlistentry>\r
626 \r
627 <varlistentry>\r
628 <term>Explore to</term>\r
629 <listitem>\r
630 <para>\r
631 Open directory of file with Explore.\r
632 </para>\r
633 </listitem>\r
634 </varlistentry>\r
635 \r
636 <varlistentry>\r
637 <term>Copy paths to clipboard</term>\r
638 <listitem>\r
639 <para>\r
640 Copy paths to clipboard\r
641 </para>\r
642 </listitem>\r
643 </varlistentry>\r
644 \r
645 <varlistentry>\r
646 <term>Copy all information to clipboard</term>\r
647 <listitem>\r
648 <para>\r
649 Copy all information to clipboard, include version info.\r
650 </para>\r
651 </listitem>\r
652 </varlistentry>\r
653 </variablelist>\r
654 </para>\r
655 <tip>\r
656 <para>\r
657 You may notice that sometimes we refer to changes and other times\r
658 to differences. What's the difference?\r
659 </para>\r
660 </tip>\r
661 </sect2>\r
662 <sect2 id="tgit-dug-showlog-filter">\r
663 <title>Filtering Log Messages</title>\r
664 <indexterm>\r
665 <primary>filter</primary>\r
666 </indexterm>\r
667 <para>\r
668 If you want to restrict the log messages to show only those\r
669 you are interested in rather than scrolling through a list\r
670 of hundreds, you can use the filter controls at the top of\r
671 the Log Dialog.\r
672 </para>\r
673 <para>\r
674 The first element is the branch/revision filter.\r
675 Clicking on it opens the Reference Browser (see <xref linkend="tgit-dug-browse-ref"/>).\r
676 There you can select single or multiple references. If you select exactly two references,\r
677 you can choose how to combine them (showing especially both A and B "A B"; showing\r
678 differences "A...B" or all commits between A and B "A..B").\r
679 This filter element also contains a special context menu. Here shortcuts for "HEAD",\r
680 "FETCH_HEAD", "All" and "All local branches" are available. Also, the last manual selected\r
681 filters are included there.\r
682 </para>\r
683 <para>\r
684 The start and end date controls allow you\r
685 to restrict the output to a known date range. The search\r
686 box allows you to show only messages which contain a\r
687 particular phrase. A default limitation for <guilabel>From</guilabel> can be configured in the settings dialog on the <guilabel>Dialogs 1</guilabel> page (cf. <xref linkend="tgit-dug-settings-dialogs"/>).\r
688 </para>\r
689 <para>\r
690 Click on the search icon to select which information you want\r
691 to search in, and to choose <emphasis>regex</emphasis> mode.\r
692 Normally you will only need a simple sub-string search, but if you\r
693 need to more flexible search terms, you can use regular expressions.\r
694 If you hover the mouse over the box, a tooltip will give hints\r
695 on how to use the regex functions.\r
696 To invert the results for the entire search expression, start the string with an exclamation mark ('!').\r
697 You can also find online documentation and a tutorial at\r
698 <ulink url="https://www.regular-expressions.info/">\r
699 <citetitle>https://www.regular-expressions.info/</citetitle>\r
700 </ulink>.\r
701 The filter works by checking whether your filter string matches\r
702 the log entries, and then only those entries which <emphasis>match</emphasis>\r
703 the filter string are shown.\r
704 </para>\r
705 <para>\r
706 Simple sub-string search works in a manner similar to a search engine.\r
707 Strings to search for are separated by spaces, and all strings must\r
708 match. You can use a leading <literal>-</literal> to specify that a\r
709 particular sub-string is not found (invert matching for that term),\r
710 and you can use <literal>!</literal> at the start of the expression\r
711 to invert matching for the entire expression.\r
712 You can use a leading <literal>+</literal> to specify that a sub-string\r
713 should be included, even if previously excluded with a <literal>-</literal>.\r
714 Note that the order of inclusion/exclusion is significant here.\r
715 You can use quotation marks to surround a string which must contain spaces,\r
716 and if you want to search for a literal quotation mark you can use two\r
717 quotation marks together as a self-escaping sequence.\r
718 Note that the backslash character is <emphasis>not</emphasis> used as\r
719 an escape character and has no special significance in simple sub-string\r
720 searches. Examples will make this easier:\r
721 <screen>\r
722 Alice Bob -Eve\r
723 </screen>\r
724 searches for strings containing both Alice and Bob but not Eve\r
725 <screen>\r
726 Alice -Bob +Eve\r
727 </screen>\r
728 searches for strings containing both Alice but not Bob, or strings\r
729 which contain Eve.\r
730 <screen>\r
731 -Case +SpecialCase\r
732 </screen>\r
733 searches for strings which do not contain Case, but still include\r
734 strings which contain SpecialCase.\r
735 <screen>\r
736 !Alice Bob\r
737 </screen>\r
738 searches for strings which do not contain both Alice and Bob\r
739 <screen>\r
740 !-Alice -Bob\r
741 </screen>\r
742 do you remember De Morgan's theorem? NOT(NOT Alice AND NOT Bob)\r
743 reduces to (Alice OR Bob).\r
744 <screen>\r
745 "Alice and Bob"\r
746 </screen>\r
747 searches for the literal expression <quote>Alice and Bob</quote>\r
748 <screen>\r
749 ""\r
750 </screen>\r
751 searches for a double-quote anywhere in the text\r
752 <screen>\r
753 "Alice says ""hi"" to Bob"\r
754 </screen>\r
755 searches for the literal expression <quote>Alice says "hi" to Bob</quote>.\r
756 </para>\r
757 <para>\r
758 You can also filter the path names in the bottom pane using the\r
759 <menuchoice>\r
760 <guimenu>View</guimenu>\r
761 <guimenuitem>Hide unrelated changed paths</guimenuitem>\r
762 </menuchoice>\r
763 Related paths are those which contain the path used to display\r
764 the log. If you fetch the log for a folder, that means anything\r
765 in that folder or below it. For a file it means just that one file.\r
766 If you want to gray out the unrelated ones, check\r
767 <menuchoice>\r
768 <guimenu>View</guimenu>\r
769 <guimenuitem>Gray unrelated changed paths</guimenuitem>\r
770 </menuchoice>\r
771 Uncheck both menu items to hide the unrelated paths completely.\r
772 </para>\r
773 <para>\r
774 In the lower left there are the checkboxes <guilabel>All branches</guilabel> and <guilabel>Show whole project</guilabel>. Use these to override the branch resp. a file/folder filter and show the log for the whole repository. Please note that these settings are remembered for a repository - even if you started the log dialog on a single file.\r
775 </para>\r
776 <para>\r
777 You can show whole project history, no choose directory or file by click\r
778 <guilabel>Show Whole Project</guilabel>\r
779 </para>\r
780 <para>\r
781 <menuchoice>\r
782 <guimenu>View</guimenu>\r
783 <guimenu>Labels</guimenu>\r
784 <guimenuitem>Tags</guimenuitem>\r
785 </menuchoice>\r
786 <menuchoice>\r
787 <guimenu>View</guimenu>\r
788 <guimenu>Labels</guimenu>\r
789 <guimenuitem>Local branches</guimenuitem>\r
790 </menuchoice>\r
791 <menuchoice>\r
792 <guimenu>View</guimenu>\r
793 <guimenu>Labels</guimenu>\r
794 <guimenuitem>Remote branches</guimenuitem>\r
795 </menuchoice>\r
796 You can disable showing some reference types in the log graph.\r
797 </para>\r
798 <para>\r
799 <menuchoice>\r
800 <guimenu>View</guimenu>\r
801 <guimenuitem>Gravatar</guimenuitem>\r
802 </menuchoice>\r
803 You can enable/disable Gravatar for a specific repository.\r
804 </para>\r
805 <para>\r
806 <menuchoice>\r
807 <guimenu>Walk Behavior</guimenu>\r
808 <guimenuitem>First Parent</guimenuitem>\r
809 </menuchoice>\r
810 just follow up first parent commit. This will help understand the overall history.\r
811 </para>\r
812 <para>\r
813 <menuchoice>\r
814 <guimenu>Walk Behavior</guimenu>\r
815 <guimenuitem>No merges</guimenuitem>\r
816 </menuchoice>\r
817 Skips all merge points.\r
818 </para>\r
819 <para>\r
820 <menuchoice>\r
821 <guimenu>Walk Behavior</guimenu>\r
822 <guimenuitem>Follow renames</guimenuitem>\r
823 </menuchoice>\r
824 This is available to a single file only, which tracks renames.\r
825 Otherwise, the log list stops at the commit that the current filename introduced.\r
826 </para>\r
827 <para>\r
828 <menuchoice>\r
829 <guimenu>Walk Behavior</guimenu>\r
830 <guimenuitem>Compressed Graph</guimenuitem>\r
831 </menuchoice>\r
832 The log graph is simplified to include merge points, commits with references, and possibly other commits.\r
833 </para>\r
834 <para>\r
835 <menuchoice>\r
836 <guimenu>Walk Behavior</guimenu>\r
837 <guimenuitem>Show labeled commits only</guimenuitem>\r
838 </menuchoice>\r
839 The log graph is simplified to include commits with references only.\r
840 </para>\r
841 </sect2>\r
842 <sect2 id="tgit-dug-showlog-navigation">\r
843 <title>Navigation</title>\r
844 <indexterm>\r
845 <primary>log navigation</primary>\r
846 </indexterm>\r
847 <para>\r
848 You can use the drop-down control on the upper right to select a navigation type\r
849 (e.g. Author Email, Parent 1, Selection history),\r
850 then use the <guibutton>Up</guibutton>\r
851 and <guibutton>Down</guibutton> green buttons\r
852 to navigate through the commits which match the navigation type\r
853 relative to the current selected one.\r
854 </para>\r
855 <para>\r
856 Alternatively to the <guibutton>Up</guibutton>\r
857 and <guibutton>Down</guibutton> green buttons,\r
858 hotkeys <keycap>ALT</keycap>+<keycap>UP</keycap>\r
859 and <keycap>ALT</keycap>+<keycap>DOWN</keycap>\r
860 are also available.\r
861 </para>\r
862 <para>\r
863 Regarding the navigation type "Selection History",\r
864 TortoiseGit memorizes the history of selected commits,\r
865 so that you can navigate through those commits\r
866 you selected in the past easily.\r
867 You can also navigate them by pressing\r
868 <keycap>ALT</keycap>+<keycap>LEFT</keycap>,\r
869 <keycap>ALT</keycap>+<keycap>RIGHT</keycap>,\r
870 <keycap>Browse Back</keycap>,\r
871 and <keycap>Browse Forward</keycap>.\r
872 <keycap>Back</keycap> and <keycap>Forward</keycap> buttons\r
873 on mouse are also available.\r
874 </para>\r
875 <para>\r
876 If you also press <keycap>SHIFT</keycap>\r
877 you can navigate through the selection history\r
878 without selecting the last commits\r
879 (i.e., just scrolling to and highlighting them).\r
880 This helps you to navigate through commits\r
881 and then select the commit(s) you really want to select\r
882 (e.g. you can compare the current selected commit\r
883 with the one you selected before).\r
884 </para>\r
885 <para>\r
886 If you want to jump to a commit with a particular hash, you may\r
887 do so by pressing <keycap>Ctrl+V</keycap> or <keycap>Shift+Insert</keycap>\r
888 (into any log dialog element other than the search box) to paste the hash\r
889 from the clipboard. If it has the form of a valid commit hash, the log\r
890 dialog will attempt to jump to it.\r
891 </para>\r
892 </sect2>\r
893 <sect2 id="tgit-dug-showlog-5">\r
894 <?dbhh topicname="HIDD_STATGRAPH"?>\r
895 <title>Statistical Information</title>\r
896 <indexterm>\r
897 <primary>statistics</primary>\r
898 </indexterm>\r
899 <para>\r
900 The <guibutton>Statistics</guibutton> button brings up a box\r
901 showing some interesting information about the revisions\r
902 shown in the Log dialog. This shows how many authors have\r
903 been at work, how many commits they have made, progress\r
904 by week, and much more. Now you can see at a glance who\r
905 has been working hardest and who is slacking ;-)\r
906 </para>\r
907 <sect3 id="tgit-dug-showlog-stats-1">\r
908 <title>Statistics Page</title>\r
909 <para>\r
910 This page gives you all the numbers you can think of,\r
911 in particular the period and number of revisions covered,\r
912 and some min/max/average values.\r
913 </para>\r
914 </sect3>\r
915 <sect3 id="tgit-dug-showlog-stats-2">\r
916 <title>Commits by Author Page</title>\r
917 <para>\r
918 <figure id="tgit-dug-showlog-stats-dia-2">\r
919 <title>Commits-by-Author Histogram</title>\r
920 <graphic fileref="../images/StatsByAuthor.png"/>\r
921 </figure>\r
922 This graph shows you which authors have been active on the\r
923 project as a simple histogram, stacked histogram or\r
924 pie chart.\r
925 <figure id="tgit-dug-showlog-stats-dia-3">\r
926 <title>Commits-by-Author Pie Chart</title>\r
927 <graphic fileref="../images/StatsByAuthPie.png"/>\r
928 </figure>\r
929 </para>\r
930 <para>\r
931 Where there are a few major authors and many minor contributors,\r
932 the number of tiny segments can make the graph more difficult to\r
933 read. The slider at the bottom allows you to set a threshold\r
934 (as a percentage of total commits) below which any activity is\r
935 grouped into an <emphasis>Others</emphasis> category.\r
936 </para>\r
937 </sect3>\r
938 <sect3 id="tgit-dug-showlog-stats-3">\r
939 <title>Commits by date Page</title>\r
940 <para>\r
941 <figure id="tgit-dug-showlog-stats-dia-4">\r
942 <title>Commits-by-date Graph</title>\r
943 <graphic fileref="../images/StatsByDate.png"/>\r
944 </figure>\r
945 This page gives you a graphical representation of project\r
946 activity in terms of number of commits <emphasis>and</emphasis>\r
947 author. This gives some idea of when a project is being worked\r
948 on, and who was working at which time.\r
949 </para>\r
950 <para>\r
951 When there are several authors, you will get many lines on the\r
952 graph. There are two views available here: <emphasis>normal</emphasis>,\r
953 where each author's activity is relative to the base line, and\r
954 <emphasis>stacked</emphasis>, where each author's activity is\r
955 relative to the line underneath.\r
956 The latter option avoids the lines crossing over, which can make\r
957 the graph easier to read, but less easy to see one author's output.\r
958 </para>\r
959 </sect3>\r
960 <para>\r
961 By default the analysis is case-sensitive, so users\r
962 <literal>PeterEgan</literal> and <literal>PeteRegan</literal>\r
963 are treated as different authors. However, in many cases user names\r
964 are not case-sensitive, and are sometimes entered inconsistently,\r
965 so you may want <literal>DavidMorgan</literal> and\r
966 <literal>davidmorgan</literal> to be treated as the same person.\r
967 Use the <guilabel>Authors case insensitive</guilabel> checkbox\r
968 to control how this is handled.\r
969 </para>\r
970 <para>\r
971 The statistics dialog also honors the <filename>.mailmap</filename> file\r
972 (see <gitdoclink cmd="gitmailmap" section="5"/>).\r
973 </para>\r
974 <para>\r
975 Note that the statistics cover the same period as the\r
976 Log dialog. If that is only displaying one revision\r
977 then the statistics will not tell you very much.\r
978 </para>\r
979 </sect2>\r
980 <sect2 id="tgit-dug-showlog-refresh">\r
981 <title>Refreshing the View</title>\r
982 <para>\r
983 If you want to check the repository again for newer log messages,\r
984 you can simply refresh the view using <keycap>F5</keycap>.\r
985 </para>\r
986 </sect2>\r
987 </sect1>\r