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>Revision Log Dialog</title>
\r
6 <primary>log</primary>
\r
9 <primary>history</primary>
\r
12 <primary>commit messages</primary>
\r
15 <primary>log messages</primary>
\r
17 <?dbhh topicname="HIDD_LOGMESSAGE"?>
\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
25 The Revision Log Dialog retrieves all those log messages and shows them
\r
27 The display is divided into 3 panes.
\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
37 Lines shown in bold indicate that that is HEAD commit.
\r
42 The middle pane shows the full log message for the selected
\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
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
57 <sect2 id="tgit-dug-showlog-1">
\r
58 <title>Invoking the Revision Log Dialog</title>
\r
60 <figure id="tgit-dug-showlog-1-dia-1">
\r
61 <title>The Revision Log Dialog</title>
\r
62 <graphic fileref="../images/LogMessages.png"/>
\r
64 There are several places from where you can show the Log dialog:
\r
68 From the TortoiseGit context submenu
\r
74 <sect2 id="tgit-dug-showlog-actions">
\r
75 <title>Revision Log Actions</title>
\r
77 The top pane has an <guilabel>Actions</guilabel> column containing
\r
78 icons that summarize what has been done in that revision.
\r
79 There are four different icons, each shown in its own column.
\r
82 <graphic fileref="../images/ActionModifiedIcon.png"/>
\r
83 If a revision modified a file or directory, the
\r
84 <emphasis>modified</emphasis> icon is shown in the first column.
\r
87 <graphic fileref="../images/ActionAddedIcon.png"/>
\r
88 If a revision added a file or directory, the
\r
89 <emphasis>added</emphasis> icon is shown in the second column.
\r
92 <graphic fileref="../images/ActionDeletedIcon.png"/>
\r
93 If a revision deleted a file or directory, the
\r
94 <emphasis>deleted</emphasis> icon is shown in the third column.
\r
97 <graphic fileref="../images/ActionReplacedIcon.png"/>
\r
98 If a revision replaced(rename) a file, the
\r
99 <emphasis>replaced</emphasis> icon is shown in the fourth column.
\r
102 <sect2 id="tgit-dug-showlog-2">
\r
103 <title>Getting Additional Information</title>
\r
105 <figure id="tgit-dug-showlog-2-dia-1">
\r
106 <title>The Revision Log Dialog Top Pane with Context Menu</title>
\r
107 <graphic fileref="../images/LogContextMenu.png"/>
\r
109 The top pane of the Log dialog has a context menu that allows you to
\r
110 access much more information. <!-- Some of these menu entries appear only
\r
111 when the log is shown for a file, and some only when the log is shown
\r
112 for a folder. --> You can press the <keycap>Shift</keycap> key to see the extended menu with some more options.
\r
115 <term>Compare with working tree</term>
\r
118 Compare the selected revision with your working tree.
\r
119 The default Diff-Tool is TortoiseGitMerge which
\r
120 is supplied with TortoiseGit.
\r
121 If the log dialog is for a folder, this will show you a list
\r
122 of changed files, and allow you to review the changes made
\r
123 to each file individually.
\r
128 <term>Show changes as unified diff</term>
\r
131 View the changes made in the selected revision as a
\r
132 Unified-Diff file (GNU patch format). This shows
\r
133 only the differences with a few lines of context. It
\r
134 is harder to read than a visual file compare, but will
\r
135 show all file changes together in a compact format.
\r
140 <term>Compare with previous revision</term>
\r
143 Compare the selected revision with the previous revision.
\r
144 This works in a similar manner to comparing with your
\r
146 For folders this option will first show the changed files
\r
147 dialog allowing you to select files to compare.
\r
152 <term>Browse repository</term>
\r
155 Open the repository browser to examine the selected file or
\r
156 folder in the repository as it was at the selected revision.
\r
161 <term>Reset (current branch) to this</term>
\r
164 Reset current branch HEAD to selected commit.
\r
165 <!-- todo refer reset -->
\r
170 <term>Switch / Checkout to revision</term>
\r
173 Update your working tree to the selected revision.
\r
174 Useful if you want to have your working tree reflect
\r
175 a time in the past, or if there have been further commits to
\r
176 the repository and you want to update your working tree one
\r
183 <term>Create branch from revision</term>
\r
186 Create a branch from a selected revision.
\r
187 This is useful e.g.
\r
192 <term>Create tag from revision</term>
\r
195 Create a tag from a selected revision.
\r
196 This is useful e.g.
\r
201 <term>Rebase (current branch) to this</term>
\r
204 Rebase current branch to selected commit.
\r
205 <!-- todo refer rebase -->
\r
210 <term>Export this version...</term>
\r
213 Export the selected revision to an archive file such as zip. This brings up a dialog for you to confirm the
\r
214 revision, and select a location for the export.
\r
219 <term>Revert change by this commit</term>
\r
222 Revert changes from which were made in the selected
\r
223 revision. All changes are integrated into your working tree.
\r
224 You may choose to commit immediately or edit and commit later.
\r
225 To abandon the reverted changes, perform a hard reset.
\r
230 <term>Edit notes</term>
\r
233 Edit notes of the selected commit.
\r
238 <term>Cherry Pick this commit</term>
\r
241 Cherry Pick this commit to current branch
\r
242 <!-- todo refer cherry pick -->
\r
247 <term>Format Patch...</term>
\r
250 Create Patches from this commit.
\r
255 <term>Copy SHA-1 to clipboard</term>
\r
258 Copy the commit hash of the selected revision to the clipboard.
\r
263 <term>Copy to clipboard</term>
\r
266 Copy the log details of the selected revisions to the clipboard.
\r
267 This will copy the revision number, author, date, log message
\r
268 and the list of changed items for each revision.
\r
273 <term>Copy log message to clipboard</term>
\r
276 Copy the log message of the selected revision to the clipboard.
\r
281 <term>Search log messages...</term>
\r
283 <figure id="tgit-dug-showlog-1-dia-2">
\r
284 <title>The Search Log Messages Dialog</title>
\r
285 <graphic fileref="../images/LogSearch.png"/>
\r
288 Search log messages for the text you enter. This searches
\r
289 the log messages that you entered and also the action summaries
\r
290 created by Git (shown in the bottom pane). The search
\r
291 is not case sensitive.
\r
295 This allows you to easily search for refs (tags and branches).
\r
298 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
304 <term>Shows branches this commit is on</term>
\r
307 Shows the branches that the select commit belongs to.
\r
308 It shows both local and remote branches.
\r
315 <figure id="tgit-dug-showlog-2-dia-1a">
\r
316 <title>Top Pane Context Menu for 2 Selected Revisions</title>
\r
317 <graphic fileref="../images/LogContextMenu1.png"/>
\r
319 If you select two revisions at once (using the usual
\r
320 <keycap>Ctrl</keycap>-modifier), the context menu changes and
\r
321 gives you fewer options:
\r
324 <term>Compare revisions</term>
\r
327 Compare the two selected revisions using a visual
\r
328 difference tool. The default Diff-Tool is TortoiseGitMerge
\r
329 which is supplied with TortoiseGit.
\r
334 <term>Show differences as unified diff</term>
\r
337 View the differences between the two selected revisions
\r
338 as a Unified-Diff file. This works for files and folders.
\r
343 <term>Revert changes by these commit</term>
\r
346 Revert changes from which were made in the selected
\r
347 revisions. All changes are integrated into your working tree.
\r
348 You may choose to commit immediately or edit and commit later.
\r
349 To abandon the reverted changes, perform a hard reset.
\r
354 <term>Combine to one commit</term>
\r
357 Combine continuous commits to one commit.
\r
362 <term>Cherry Pick selected commits</term>
\r
365 Cherry Pick Chosen Commits.
\r
370 <term>Bisect start</term>
\r
373 Start bisection. Find by binary search the change that introduced a bug.
\r
378 <term>Format Patch...</term>
\r
381 Create patches between two chosen commits.
\r
386 <term>Copy SHA-1 to clipboard</term>
\r
389 Copy the commit hashes of the selected revisions to the clipboard, delimited by CRLF.
\r
394 <term>Copy to clipboard</term>
\r
397 Copy log messages to clipboard as described above.
\r
402 <term>Copy log messages to clipboard</term>
\r
405 Copy the log messages of the selected revisions to the clipboard.
\r
406 This will copy the log message for each revision.
\r
407 This facilitates the preparation of release notes.
\r
412 <term>Search log messages...</term>
\r
415 Search log messages as described above.
\r
422 If you select two or more revisions (using the usual
\r
423 <keycap>Ctrl</keycap> or <keycap>Shift</keycap> modifiers),
\r
424 You can combine select commits to one commit. And cherry pick
\r
425 these commits to current branch.
\r
428 <figure id="tgit-dug-showlog-2-dia-2">
\r
429 <title>The Log Dialog Bottom Pane with Context Menu</title>
\r
430 <graphic fileref="../images/LogContextMenu2.png"/>
\r
432 The bottom pane of the Log dialog also has a context menu that allows you to
\r
435 <term>Compare with base</term>
\r
438 Compare chosen file with base version.
\r
444 <term>Show as unified diff</term>
\r
447 Show file changes in unified diff format.
\r
448 This context menu is only available for
\r
449 files shown as <emphasis>modified</emphasis>.
\r
454 <term>Compare with working tree</term>
\r
457 Compare chosen file with working tree.
\r
463 <term>Revert changes to this revision</term>
\r
466 Revert chosen files to this revision.
\r
471 <term>Revert changes to parent revision</term>
\r
474 Revert chosen files to parent revision.
\r
479 <term>Show log</term>
\r
482 Show the revision log for the selected single file.
\r
488 <term>Blame...</term>
\r
491 Opens the Blame dialog, allowing you to blame up to the
\r
498 <term>Save revision to...</term>
\r
501 Save the selected revision to a file so you
\r
502 have an older version of that file.
\r
508 <term>Export selection to...</term>
\r
511 Saves the selected files to a target directory. Compared to "Save revision to..." this preserves the directory structure.
\r
517 <term>View revision in alternative editor</term>
\r
520 Show chosen file with an alternative editor such as notepad2 with chosen commit.
\r
526 <term>Open / Open with...</term>
\r
529 Open the selected file, either with the default viewer for
\r
530 that file type, or with a program you choose.
\r
536 <term>Explore to</term>
\r
539 Open directory of file with Explore.
\r
545 <term>Copy paths to clipboard</term>
\r
548 Copy paths to clipboard
\r
554 <term>Copy all information to clipboard</term>
\r
557 Copy all information to clipboard, include version info.
\r
565 You may notice that sometimes we refer to changes and other times
\r
566 to differences. What's the difference?
\r
570 <sect2 id="tgit-dug-showlog-filter">
\r
571 <title>Filtering Log Messages</title>
\r
573 <primary>filter</primary>
\r
576 If you want to restrict the log messages to show only those
\r
577 you are interested in rather than scrolling through a list
\r
578 of hundreds, you can use the filter controls at the top of
\r
579 the Log Dialog. The start and end date controls allow you
\r
580 to restrict the output to a known date range. The search
\r
581 box allows you to show only messages which contain a
\r
585 Click on the search icon to select which information you want
\r
586 to search in, and to choose <emphasis>regex</emphasis> mode.
\r
587 Normally you will only need a simple text search, but if you
\r
588 need to more flexible search terms, you can use regular expressions.
\r
589 If you hover the mouse over the box, a tooltip will give hints
\r
590 on how to use the regex functions.
\r
591 You can also find online documentation and a tutorial at
\r
592 <ulink url="http://www.regular-expressions.info/">
\r
593 <citetitle>http://www.regular-expressions.info/</citetitle>
\r
595 The filter works by checking whether your filter string matches
\r
596 the log entries, and then only those entries which <emphasis>match</emphasis>
\r
597 the filter string are shown.
\r
600 To make the filter show all log entries that do <emphasis>not</emphasis>
\r
601 match the filter string, start the string with an exclamation mark ('!').
\r
602 For example, a filter string <literal>!username</literal> will only
\r
603 show those entries which were not committed by <literal>username</literal>.
\r
606 You can also filter the path names in the bottom pane using the
\r
608 <guimenu>View</guimenu>
\r
609 <guimenuitem>Hide unrelated changed paths</guimenuitem>
\r
611 Related paths are those which contain the path used to display
\r
612 the log. If you fetch the log for a folder, that means anything
\r
613 in that folder or below it. For a file it means just that one file.
\r
614 If you want to grey out the unrelated ones, check
\r
616 <guimenu>View</guimenu>
\r
617 <guimenuitem>Gray unrelated changed paths</guimenuitem>
\r
619 Uncheck both menu items to hide the unrelated paths completely.
\r
623 You can show all branches history by click <guilabel>All branches</guilabel>
\r
626 You can show whole project history, no choose directory or file by click
\r
627 <guilabel>Show Whole Project</guilabel>
\r
631 <guimenu>View</guimenu>
\r
632 <guimenu>Labels</guimenu>
\r
633 <guimenuitem>Tags</guimenuitem>
\r
636 <guimenu>View</guimenu>
\r
637 <guimenu>Labels</guimenu>
\r
638 <guimenuitem>Local branches</guimenuitem>
\r
641 <guimenu>View</guimenu>
\r
642 <guimenu>Labels</guimenu>
\r
643 <guimenuitem>Remote branches</guimenuitem>
\r
645 You can disable showing some reference types in the log graph.
\r
649 <guimenu>View</guimenu>
\r
650 <guimenuitem>Gravatar</guimenuitem>
\r
652 You can enable / disable Gravatar for a specific repository.
\r
656 <guimenu>Walk Behaviour</guimenu>
\r
657 <guimenuitem>First Parent</guimenuitem>
\r
659 just follow up first parent commit. This will help understand overwhole history.
\r
663 <guimenu>Walk Behaviour</guimenu>
\r
664 <guimenuitem>No merges</guimenuitem>
\r
666 Skips all merge points.
\r
670 <guimenu>Walk Behaviour</guimenu>
\r
671 <guimenuitem>Follow renames</guimenuitem>
\r
673 This is available to a single file only, which tracks rename.
\r
674 Otherwise, the log list stops at the commit that the current filename is introduced.
\r
678 <guimenu>Walk Behaviour</guimenu>
\r
679 <guimenuitem>Compressed Graph</guimenuitem>
\r
681 The log graph is simplified to include merge points, commits with references, and possibly other commits.
\r
685 <guimenu>Walk Behaviour</guimenu>
\r
686 <guimenuitem>Show labelled commits only</guimenuitem>
\r
688 The log graph is simplified to include commits with references only.
\r
691 <sect2 id="tgit-dug-showlog-navigation">
\r
692 <title>Navigation</title>
\r
694 <primary>log navigation</primary>
\r
697 You can use the dropdown control to select a navigation type
\r
698 (e.g. Author Email, Parent 1, Selection history),
\r
699 then use the <guibutton>Up</guibutton>
\r
700 and <guibutton>Down</guibutton> green buttons
\r
701 to navigate through the commits which match the navigation type
\r
702 relative to the current selected one.
\r
705 Alternatively to the <guibutton>Up</guibutton>
\r
706 and <guibutton>Down</guibutton> green buttons,
\r
707 hotkeys <keycap>ALT</keycap>+<keycap>UP</keycap>
\r
708 and <keycap>ALT</keycap>+<keycap>DOWN</keycap>
\r
709 are also available.
\r
712 Regarding the navigation type "Selection History",
\r
713 TortoiseGit memorizes the history of selected commits,
\r
714 so that you can navigate through those commits
\r
715 you selected in the past easily.
\r
716 You can also navigate them by pressing
\r
717 <keycap>ALT</keycap>+<keycap>LEFT</keycap>,
\r
718 <keycap>ALT</keycap>+<keycap>RIGHT</keycap>,
\r
719 <keycap>Browse Back</keycap>,
\r
720 and <keycap>Browse Forward</keycap>.
\r
721 <keycap>Back</keycap> and <keycap>Forward</keycap> buttons
\r
722 on mouse are also available.
\r
725 If you also press <keycap>SHIFT</keycap>
\r
726 you can navigate through the selection history
\r
727 without selecting the last commits
\r
728 (i.e., just scrolling to and highlighting them).
\r
729 This helps you to navigate through commits
\r
730 and then select the commit(s) you really want to select
\r
731 (e.g. you can compare the current selected commit
\r
732 with the one you selected before).
\r
735 <sect2 id="tgit-dug-showlog-5">
\r
736 <?dbhh topicname="HIDD_STATGRAPH"?>
\r
737 <title>Statistical Information</title>
\r
739 <primary>statistics</primary>
\r
742 The <guibutton>Statistics</guibutton> button brings up a box
\r
743 showing some interesting information about the revisions
\r
744 shown in the Log dialog. This shows how many authors have
\r
745 been at work, how many commits they have made, progress
\r
746 by week, and much more. Now you can see at a glance who
\r
747 has been working hardest and who is slacking ;-)
\r
749 <sect3 id="tgit-dug-showlog-stats-1">
\r
750 <title>Statistics Page</title>
\r
752 This page gives you all the numbers you can think of,
\r
753 in particular the period and number of revisions covered,
\r
754 and some min/max/average values.
\r
757 <sect3 id="tgit-dug-showlog-stats-2">
\r
758 <title>Commits by Author Page</title>
\r
760 <figure id="tgit-dug-showlog-stats-dia-2">
\r
761 <title>Commits-by-Author Histogram</title>
\r
762 <graphic fileref="../images/StatsByAuthor.png"/>
\r
764 This graph shows you which authors have been active on the
\r
765 project as a simple histogram, stacked histogram or
\r
767 <figure id="tgit-dug-showlog-stats-dia-3">
\r
768 <title>Commits-by-Author Pie Chart</title>
\r
769 <graphic fileref="../images/StatsByAuthPie.png"/>
\r
773 Where there are a few major authors and many minor contributors,
\r
774 the number of tiny segments can make the graph more difficult to
\r
775 read. The slider at the bottom allows you to set a threshold
\r
776 (as a percentage of total commits) below which any activity is
\r
777 grouped into an <emphasis>Others</emphasis> category.
\r
780 <sect3 id="tgit-dug-showlog-stats-3">
\r
781 <title>Commits by date Page</title>
\r
783 <figure id="tgit-dug-showlog-stats-dia-4">
\r
784 <title>Commits-by-date Graph</title>
\r
785 <graphic fileref="../images/StatsByDate.png"/>
\r
787 This page gives you a graphical representation of project
\r
788 activity in terms of number of commits <emphasis>and</emphasis>
\r
789 author. This gives some idea of when a project is being worked
\r
790 on, and who was working at which time.
\r
793 When there are several authors, you will get many lines on the
\r
794 graph. There are two views available here: <emphasis>normal</emphasis>,
\r
795 where each author's activity is relative to the base line, and
\r
796 <emphasis>stacked</emphasis>, where each author's activity is
\r
797 relative to the line underneath.
\r
798 The latter option avoids the lines crossing over, which can make
\r
799 the graph easier to read, but less easy to see one author's output.
\r
803 By default the analysis is case-sensitive, so users
\r
804 <literal>PeterEgan</literal> and <literal>PeteRegan</literal>
\r
805 are treated as different authors. However, in many cases user names
\r
806 are not case-sensitive, and are sometimes entered inconsistently,
\r
807 so you may want <literal>DavidMorgan</literal> and
\r
808 <literal>davidmorgan</literal> to be treated as the same person.
\r
809 Use the <guilabel>Authors case insensitive</guilabel> checkbox
\r
810 to control how this is handled.
\r
813 The statistics dialog also honours the .mailmap file
\r
814 (see <xref linkend="git-blame(1)__mapping_authors"/>).
\r
817 Note that the statistics cover the same period as the
\r
818 Log dialog. If that is only displaying one revision
\r
819 then the statistics will not tell you very much.
\r
822 <sect2 id="tgit-dug-showlog-refresh">
\r
823 <title>Refreshing the View</title>
\r
825 If you want to check the repository again for newer log messages,
\r
826 you can simply refresh the view using <keycap>F5</keycap>.
\r