<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-dug-showlog">
  <title>Revision Log Dialog</title>
  <indexterm>
    <primary>log</primary>
  </indexterm>
  <indexterm>
    <primary>history</primary>
  </indexterm>
  <indexterm>
    <primary>commit messages</primary>
  </indexterm>
  <indexterm>
    <primary>log messages</primary>
  </indexterm>
  <?dbhh topicname="HIDD_LOGMESSAGE"?>
  <para>
    For every change you make and commit, you should provide
    a log message for that change. That way you can later find out
    what changes you made and why, and you have a detailed log for
    your development process.
  </para>
  <para>
    The Revision Log Dialog retrieves all those log messages and shows them
    to you.
    The display is divided into 3 panes.
    <itemizedlist>
      <listitem>
        <para>
          The top pane shows a list of revisions where changes to the
          file/folder have been committed. This summary includes the
          date and time, the person who committed the revision and the
          start of the log message.
        </para>
        <para>
          Lines shown in blue indicate that something has been copied
          to this development line (perhaps from a branch).
        </para>
      </listitem>
      <listitem>
        <para>
          The middle pane shows the full log message for the selected
          revision.
        </para>
      </listitem>
      <listitem>
        <para>
          The bottom pane shows a list of all files and folders that
          were changed as part of the selected revision.
        </para>
      </listitem>
    </itemizedlist>
    But it does much more than that - it provides context menu
    commands which you can use to get even more information about the
    project history.
  </para>
  <sect2 id="tsvn-dug-showlog-1">
    <title>Invoking the Revision Log Dialog</title>
    <para>
      <figure id="tsvn-dug-showlog-1-dia-1">
        <title>The Revision Log Dialog</title>
        <graphic fileref="../images/LogMessages.png"/>
      </figure>
      There are several places from where you can show the Log dialog:
      <itemizedlist>
        <listitem>
          <para>
            From the TortoiseSVN context submenu
          </para>
        </listitem>
        <listitem>
          <para>
            From the property page
          </para>
        </listitem>
        <listitem>
          <para>
            From the Progress dialog after an update
            has finished. Then the Log dialog only shows those revisions
            which were changed since your last update
          </para>
        </listitem>
        <listitem>
          <para>
            From the repository browser
          </para>
        </listitem>
      </itemizedlist>
    </para>
    <para>
      If the repository is unavailable you will see the
      <guilabel>Want to go offline?</guilabel> dialog, described in
      <xref linkend="tsvn-dug-showlog-cache"/>.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-actions">
    <title>Revision Log Actions</title>
    <para>
      The top pane has an <guilabel>Actions</guilabel> column containing
      icons that summarize what has been done in that revision.
      There are four different icons, each shown in its own column.
    </para>
    <para>
      <graphic fileref="../images/ActionModifiedIcon.png"/>
      If a revision modified a file or directory, the
      <emphasis>modified</emphasis> icon is shown in the first column.
    </para>
    <para>
      <graphic fileref="../images/ActionAddedIcon.png"/>
      If a revision added a file or directory, the
      <emphasis>added</emphasis> icon is shown in the second column.
    </para>
    <para>
      <graphic fileref="../images/ActionDeletedIcon.png"/>
      If a revision deleted a file or directory, the
      <emphasis>deleted</emphasis> icon is shown in the third column.
    </para>
    <para>
      <graphic fileref="../images/ActionReplacedIcon.png"/>
      If a revision replaced a file or directory, the
      <emphasis>replaced</emphasis> icon is shown in the fourth column.
    </para>
    <para>
      <graphic fileref="../images/ActionMovedIcon.png"/>
      If a revision moved or renamed a file or directory, the
      <emphasis>moved</emphasis> icon is shown in the fourth column.
    </para>
    <para>
      <graphic fileref="../images/ActionMoveReplacedIcon.png"/>
      If a revision replaced a file or directory by moving/renaming it, the
      <emphasis>move replaced</emphasis> icon is shown in the fourth column.
    </para>
    <para>
      <graphic fileref="../images/ActionMergedIcon.png"/>
      If a revision merged a file or directory, the
      <emphasis>merged</emphasis> icon is shown in the fourth column.
    </para>
    <para>
      <graphic fileref="../images/ActionReverseMergedIcon.png"/>
      If a revision reverse merged a file or directory, the
      <emphasis>reverse merged</emphasis> icon is shown in the fourth column.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-2">
    <title>Getting Additional Information</title>
    <para>
      <figure id="tsvn-dug-showlog-2-dia-1">
        <title>The Revision Log Dialog Top Pane with Context Menu</title>
        <graphic fileref="../images/LogContextMenu.png"/>
      </figure>
      The top pane of the Log dialog has a context menu that allows you to
      access much more information. Some of these menu entries appear only
      when the log is shown for a file, and some only when the log is shown
      for a folder.
      <variablelist>
        <varlistentry>
          <term>Compare with working copy</term>
          <listitem>
            <para>
              Compare the selected revision with your working copy.
              The default Diff-Tool is TortoiseMerge which
              is supplied with TortoiseSVN.
              If the log dialog is for a folder, this will show you a list
              of changed files, and allow you to review the changes made
              to each file individually.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Compare and blame with working BASE</term>
          <listitem>
            <para>
              Blame the selected revision, and the file in your working BASE
              and compare the blame reports using a visual diff tool.
              Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.
              (files only)
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show changes as unified diff</term>
          <listitem>
            <para>
              View the changes made in the selected revision as a
              Unified-Diff file (GNU patch format). This shows
              only the differences with a few lines of context. It
              is harder to read than a visual file compare, but will
              show all file changes together in a compact format.
            </para>
            <para>
              If you hold down the <keycap>Shift</keycap> key when
              clicking on the menu item, a dialog shows up first
              where you can set options for the unified diff. These
              options include the ability to ignore changes in
              line endings and whitespaces.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Compare with previous revision</term>
          <listitem>
            <para>
              Compare the selected revision with the previous revision.
              This works in a similar manner to comparing with your
              working copy.
              For folders this option will first show the changed files
              dialog allowing you to select files to compare.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Compare and blame with previous revision</term>
          <listitem>
            <para>
              Show the changed files dialog allowing you to select files.
              Blame the selected revision, and the previous revision,
              and compare the results using a visual diff tool.
              (folders only)
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Save revision to...</term>
          <listitem>
            <para>
              Save the selected revision to a file so you have an older
              version of that file. (files only)
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Open / Open with...</term>
          <listitem>
            <para>
              Open the selected file, either with the default viewer for
              that file type, or with a program you choose. (files only)
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Blame...</term>
          <listitem>
            <para>
              Blame the file up to the selected revision. (files only)
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Browse repository</term>
          <listitem>
            <para>
              Open the repository browser to examine the selected file or
              folder in the repository as it was at the selected revision.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Create branch/tag from revision</term>
          <listitem>
            <para>
              Create a branch or tag from a selected revision.
              This is useful e.g. if you forgot to create a tag and already
              committed some changes which weren't supposed to get into
              that release.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Update item to revision</term>
          <listitem>
            <para>
              Update your working copy to the selected revision.
              Useful if you want to have your working copy reflect
              a time in the past, or if there have been further commits to
              the repository and you want to update your working copy one
              step at a time. It is best to update a whole directory
              in your working copy, not just one file, otherwise your
              working copy could be inconsistent.
            </para>
            <para>
              If you want to undo an earlier change permanently, use
              <guilabel>Revert to this revision</guilabel> instead.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Revert to this revision</term>
          <listitem>
            <para>
              Revert to an earlier revision. If you have made several
              changes, and then decide that you really want to go back to
              how things were in revision N, this is the command you need.
              The changes are undone in your working copy so
              this operation does <emphasis>not</emphasis> affect the
              repository until you commit the changes. Note that this
              will undo <emphasis>all</emphasis> changes made after the
              selected revision, replacing the file/folder with the
              earlier version.
            </para>
            <para>
              If your working copy is in an unmodified state, after you
              perform this action your working copy will show as modified.
              If you already have local changes, this command will merge
              the <emphasis>undo</emphasis> changes into your working copy.
            </para>
            <para>
              What is happening internally is that Subversion performs a
              reverse merge of all the changes made after the selected
              revision, undoing the effect of those previous commits.
            </para>
            <para>
              If after performing this action you decide that you want to
              <emphasis>undo the undo</emphasis> and get your working
              copy back to its previous unmodified state, you should use
              <menuchoice>
                <guimenu>TortoiseSVN</guimenu>
                <guimenuitem>Revert</guimenuitem>
              </menuchoice>
              from within Windows Explorer, which will discard the local
              modifications made by this reverse merge action.
            </para>
            <para>
              If you simply want to see what a file or folder looked like
              at an earlier revision, use
              <guilabel>Update to revision</guilabel> or
              <guilabel>Save revision as...</guilabel> instead.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Revert changes from this revision</term>
          <listitem>
            <para>
              Undo changes from which were made in the selected
              revision. The changes are undone in your working copy so
              this operation does <emphasis>not</emphasis> affect the
              repository at all! Note that this will undo the changes
              made in that revision only; it does not replace your
              working copy with the entire file at the earlier revision.
              This is very useful for undoing an earlier change when
              other unrelated changes have been made since.
            </para>
            <para>
              If your working copy is in an unmodified state, after you
              perform this action your working copy will show as modified.
              If you already have local changes, this command will merge
              the <emphasis>undo</emphasis> changes into your working copy.
            </para>
            <para>
              What is happening internally is that Subversion performs a
              reverse merge of that one revision, undoing its effect from
              a previous commit.
            </para>
            <para>
              You can <emphasis>undo the undo</emphasis> as described
              above in <guilabel>Revert to this revision</guilabel>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Merge revision to...</term>
          <listitem>
            <para>
              Merge the selected revision(s) into a different working copy.
              A folder selection dialog allows you to choose the working
              copy to merge into, but after that there is no confirmation
              dialog, nor any opportunity to try a test merge. It is a good
              idea to merge into an unmodified working copy so that you can
              revert the changes if it doesn't work out!
              This is a useful feature if you want to merge selected
              revisions from one branch to another.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Checkout...</term>
          <listitem>
            <para>
              Make a fresh checkout of the selected folder at the selected
              revision. This brings up a dialog for you to confirm the
              URL and revision, and select a location for the checkout.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Export...</term>
          <listitem>
            <para>
              Export the selected file/folder at the selected
              revision. This brings up a dialog for you to confirm the
              URL and revision, and select a location for the export.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Edit author / log message</term>
          <listitem>
            <para>
              Edit the log message or author attached to a previous commit.
              Read <xref linkend="tsvn-dug-showlog-4"/> to find out
              how this works.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show revision properties</term>
          <listitem>
            <para>
              View and edit any revision property, not just log message
              and author. Refer to <xref linkend="tsvn-dug-showlog-4"/>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Copy to clipboard</term>
          <listitem>
            <para>
              Copy the log details of the selected revisions to the clipboard.
              This will copy the revision number, author, date, log message
              and the list of changed items for each revision.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Search log messages...</term>
          <listitem>
            <para>
              Search log messages for the text you enter. This searches
              the log messages that you entered and also the action summaries
              created by Subversion (shown in the bottom pane). The search
              is not case sensitive.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Create code collaborator review...</term>
          <listitem>
            <para>
              This menu is shown only if the SmartBear code collaborator tool
              is installed.  When invoked for the first time, a dialog is shown
              prompting the user to enter user credentials for both code collaborator
              and SVN.  Once the settings are stored, the settings dialog is no
              longer shown when the menu is invoked, unless the user holds
              <keycap>Ctrl</keycap> while executing the menu item.
              The configuration and the chosen revision(s) are used to invoke
              the code collaborator graphical user interface client,
              which creates a new review with the selected revisions.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <figure id="tsvn-dug-show-collaborator-settings-1">
        <title>The Code Collaborator Settings Dialog</title>
        <graphic fileref="../images/CodeCollaboratorSettings.png"/>
      </figure>
    </para>
    <para>
      <figure id="tsvn-dug-showlog-2-dia-1a">
        <title>Top Pane Context Menu for 2 Selected Revisions</title>
        <graphic fileref="../images/LogContextMenu1.png"/>
      </figure>
      If you select two revisions at once (using the usual
      <keycap>Ctrl</keycap>-modifier), the context menu changes and
      gives you fewer options:
      <variablelist>
        <varlistentry>
          <term>Compare revisions</term>
          <listitem>
            <para>
              Compare the two selected revisions using a visual
              difference tool. The default Diff-Tool is TortoiseMerge
              which is supplied with TortoiseSVN.
            </para>
            <para>
              If you select this option for a folder, a further dialog pops
              up listing the changed files and offering you further
              diff options. Read more about the Compare Revisions
              dialog in <xref linkend="tsvn-dug-compare-revs"/>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Blame revisions</term>
          <listitem>
            <para>
              Blame the two revisions and compare the blame reports using
              a visual difference tool.
              Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show differences as unified diff</term>
          <listitem>
            <para>
              View the differences between the two selected revisions
              as a Unified-Diff file. This works for files and folders.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Copy to clipboard</term>
          <listitem>
            <para>
              Copy log messages to clipboard as described above.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Search log messages...</term>
          <listitem>
            <para>
              Search log messages as described above.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <para>
      If you select two or more revisions (using the usual
      <keycap>Ctrl</keycap> or <keycap>Shift</keycap> modifiers),
      the context menu will include an entry to Revert all changes
      which were made in the selected revisions. This is the easiest
      way to rollback a group of revisions in one go.
    </para>
    <para>
      You can also choose to merge the selected revisions to another
      working copy, as described above.
    </para>
    <para>
      If all selected revisions have the same author, you can edit
      the author of all those revisions in one go.
    </para>
    <para>
      <figure id="tsvn-dug-showlog-2-dia-2">
        <title>The Log Dialog Bottom Pane with Context Menu</title>
        <graphic fileref="../images/LogContextMenu2.png"/>
      </figure>
      The bottom pane of the Log dialog also has a context menu that allows you to
      <variablelist>
        <varlistentry>
          <term>Show changes</term>
          <listitem>
            <para>
              Show changes made in the selected revision for the
              selected file.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Blame changes</term>
          <listitem>
            <para>
              Blame the selected revision and the previous revision for the
              selected file, and compare the blame reports
              using a visual diff tool.
              Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show as unified diff</term>
          <listitem>
            <para>
              Show file changes in unified diff format.
              This context menu is only available for
              files shown as <emphasis>modified</emphasis>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Open / Open with...</term>
          <listitem>
            <para>
              Open the selected file, either with the default viewer for
              that file type, or with a program you choose.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Blame...</term>
          <listitem>
            <para>
              Opens the Blame dialog, allowing you to blame up to the
              selected revision.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Revert changes from this revision</term>
          <listitem>
            <para>
              Revert the changes made to the selected file in that revision.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show properties</term>
          <listitem>
            <para>
              View the Subversion properties for the selected item.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show log</term>
          <listitem>
            <para>
              Show the revision log for the selected single file.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Get merge logs</term>
          <listitem>
            <para>
              Show the revision log for the selected single file,
              including merged changes. Find out more in
              <xref linkend="tsvn-dug-showlog-mergetrack"/>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Save revision to...</term>
          <listitem>
            <para>
              Save the selected revision to a file so you
              have an older version of that file.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Export...</term>
          <listitem>
            <para>
              Export the selected items in this revision to a folder,
              preserving the file hierarchy.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      When multiple files are selected in the bottom pane of the Log dialog, the context menu changes
      to the following:
      <figure id="tsvn-dug-showlog-3-dia-3">
        <title>The Log Dialog Bottom Pane with Context Menu When Multiple Files Selected.</title>
        <graphic fileref="../images/LogContextMenu3.png"/>
      </figure>
      <variablelist>
        <varlistentry>
          <term>Save revision to...</term>
          <listitem>
            <para>
              Save the selected revision to a file so you
              have an older version of that file.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show multiple changes...</term>
          <listitem>
            <para>
              Show changes made in the selected revision for the
              selected files. Note that the show changes functionality
              is invoked multiple times, which may bring up multiple copies of
              your selected diff tool, or just add a new comparison tab in your diff tool.
              If you have selected more than 15 files, you will be prompted to confirm the action.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Open multiple local...</term>
          <listitem>
            <para>
              This will open local working copy files that correspond to your
              selected files using the application that is registered for the extension.
              [The behavior is the one you would get double-clicking the working-copy
              file(s) in Windows explorer].
              Depending on how your file extension is associated to an application and
              the capabilities of the application, this may be a slow operation.
              In the worst case, new instances of the application may be launched
              by Windows for each file that was selected.
            </para>
            <para>
              If you hold <keycap>Ctrl</keycap> while invoking this command, the working copy files
              are always loaded into Visual Studio.  This only works when the following conditions are met:
              Visual Studio must be running in the same user context while having the same process
              integrity level [running as admin or not] as TortoiseProc.exe. It may be desirable to have the
              solution containing the changed files loaded, although this is not strictly necessary.
              Only files that exist on disk with extensions [.cpp, .h, .cs, .rc, .resx,
              .xaml, .js, .html, .htm, .asp, .aspx, .php, .css and .xml] will be loaded. A maximum of
              100 files can be loaded into Visual Studio at one time, and the files are always loaded
              as new tabs into the currently open instance of Visual Studio. The benefit of reviewing code
              changes in Visual Studio lies in the fact that you can then use the built-in code navigation,
              reference finding, static code analysis and other tools built into Visual Studio.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Export...</term>
          <listitem>
            <para>
              Export the selected files/folder at the selected
              revision. This brings up a dialog for you to confirm the
              URL and revision, and select a location for the export.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <tip>
      <para>
        You may notice that sometimes we refer to changes and other times
        to differences. What's the difference?
      </para>
      <para>
        Subversion uses revision numbers to mean 2 different things.
        A revision generally represents the state of the repository at
        a point in time, but it can also be used to represent the changeset
        which created that revision, e.g. <quote>Done in r1234</quote> means
        that the changes committed in r1234 implement feature X.
        To make it clearer which sense is being used, we use two
        different terms.
      </para>
      <para>
        If you select two revisions N and M, the context menu will offer
        to show the <emphasis>difference</emphasis> between those two
        revisions. In Subversion terms this is
        <literal>diff -r M:N</literal>.
      </para>
      <para>
        If you select a single revision N, the context menu will offer
        to show the <emphasis>changes</emphasis> made in that revision.
        In Subversion terms this is <literal>diff -r N-1:N</literal>
        or <literal>diff -c N</literal>.
      </para>
      <para>
        The bottom pane shows the files changed in all selected revisions,
        so the context menu always offers to show <emphasis>changes</emphasis>.
      </para>
    </tip>
  </sect2>
  <sect2 id="tsvn-dug-showlog-3">
    <title>Getting more log messages</title>
    <?dbhh topicname="HIDD_REVISIONRANGE"?>
    <para>
      The Log dialog does not always show all changes ever made for a
      number of reasons:
      <itemizedlist>
        <listitem>
          <para>
            For a large repository there may be hundreds or even
            thousands of changes and fetching them all could take
            a long time. Normally you are only interested in the
            more recent changes. By default, the number of log
            messages fetched is limited to 100, but you can change
            this value in
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Settings</guimenuitem>
            </menuchoice>
            (<xref linkend="tsvn-dug-settings-dialogs"/>),
          </para>
        </listitem>
        <listitem>
          <para>
            When the <guilabel>Stop on copy/rename</guilabel>
            box is checked, Show Log will stop at the point that
            the selected file or folder was copied from somewhere
            else within the repository. This can be useful when
            looking at branches (or tags) as it stops at the root
            of that branch, and gives a quick indication of changes
            made in that branch only.
          </para>
          <para>
            Normally you will want to leave this option unchecked.
            TortoiseSVN remembers the state of the checkbox, so
            it will respect your preference.
          </para>
          <para>
            When the Show Log dialog is invoked from within the
            Merge dialog, the box is always checked by default.
            This is because merging is most often looking at
            changes on branches, and going back beyond the root
            of the branch does not make sense in that instance.
          </para>
          <para>
            Note that Subversion currently implements renaming
            as a copy/delete pair, so renaming a file or folder
            will also cause the log display to stop if this
            option is checked.
          </para>
        </listitem>
      </itemizedlist>
    </para>
    <para>
      If you want to see more log messages, click the
      <guibutton>Next 100</guibutton> to retrieve the next 100 log messages.
      You can repeat this as many times as needed.
    </para>
    <para>
      Next to this button there is a multi-function button which remembers
      the last option you used it for. Click on the arrow to see the other
      options offered.
    </para>
    <para>
      Use <guibutton>Show Range ...</guibutton> if you want to view a specific
      range of revisions. A dialog will then prompt you to enter the start
      and end revision.
    </para>
    <para>
      Use <guibutton>Show All</guibutton> if you want to see
      <emphasis>all</emphasis> log messages from HEAD right back to revision 1.
    </para>
    <para>
      To refresh the latest revision in case there were other commits
      while the log dialog was open, hit the <keycap>F5</keycap> key.
    </para>
    <para>
      To refresh the log cache, hit the <keycap>Ctrl-F5</keycap> keys.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-current-rev">
    <title>Current Working Copy Revision</title>
    <para>
      Because the log dialog shows you the log from HEAD, not from the
      current working copy revision, it often happens that there are
      log messages shown for content which has not yet been updated
      in your working copy. To help make this clearer, the commit
      message which corresponds to the revision you have in your
      working copy is shown in bold.
    </para>
    <para>
      When you show the log for a folder the revision highlighted
      is the highest revision found anywhere within that folder,
      which requires a crawl of the working copy. The crawl takes place
      within a separate thread so as not to delay showing the log,
      but as a result highlighting for folders may not appear immediately.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-mergetrack">
    <title>Merge Tracking Features</title>
    <indexterm>
      <primary>merge tracking log</primary>
    </indexterm>
    <para>
      Subversion 1.5 and later keeps a record of merges using properties.
      This allows us to get a more detailed history of merged changes.
      For example, if you develop a new feature on a branch and then merge
      that branch back to trunk, the feature development will show up on
      the trunk log as a single commit for the merge, even though there
      may have been 1000 commits during branch development.
    </para>
    <figure id="tsvn-dug-showlog-dia-mergetrack">
      <title>The Log Dialog Showing Merge Tracking Revisions</title>
      <graphic fileref="../images/LogMergeTrack.png"/>
    </figure>
    <para>
      If you want to see the detail of which revisions were merged as part
      of that commit, use the <guilabel>Include merged revisions</guilabel>
      checkbox. This will fetch the log messages again, but will also
      interleave the log messages from revisions which were merged.
      Merged revisions are shown in grey because they represent changes
      made on a different part of the tree.
    </para>
    <para>
      Of course, merging is never simple! During feature development on the
      branch there will probably be occasional merges back from trunk to
      keep the branch in sync with the main line code. So the merge history
      of the branch will also include another layer of merge history.
      These different layers are shown in the log dialog using indentation
      levels.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-4">
    <title>Changing the Log Message and Author</title>
    <indexterm>
      <primary>edit log/author</primary>
    </indexterm>
    <indexterm>
      <primary>revision properties</primary>
    </indexterm>
    <indexterm>
      <primary>revprops</primary>
    </indexterm>
    <para>
      Revision properties are completely different from the Subversion
      properties of each item. Revprops are descriptive items which are
      associated with one specific revision number in the repository,
      such as log message, commit date and committer name (author).
    </para>
    <para>
      Sometimes you might want to change a log message you once entered,
      maybe because there's a spelling error in it or you want to
      improve the message or change it for other reasons. Or you want to
      change the author of the commit because you forgot to set up
      authentication or...
    </para>
    <para>
      Subversion lets you change revision properties any time you want.
      But since such changes can't be
      undone (those changes are not versioned) this feature is disabled
      by default. To make this work, you must set up a pre-revprop-change
      hook. Please refer to the chapter on
      <ulink url="https://svnbook.red-bean.com/en/1.8/svn.reposadmin.create.html#svn.reposadmin.create.hooks">
        <citetitle>Hook Scripts</citetitle>
      </ulink>
      in the Subversion Book for details about how to do that.
      Read <xref linkend="tsvn-repository-hooks"/> to find some further
      notes on implementing hooks on a Windows machine.
    </para>
    <para>
      Once you've set up your server with the required hooks, you can
      change the author and log message (or any other revprop) of any revision,
      using the context menu from the top pane of the Log dialog.
      You can also edit a log message using the context menu for the middle pane.
    </para>
    <warning>
      <para>
        Because Subversion's revision properties are not versioned, making
        modifications to such a property (for example, the
        <literal>svn:log</literal> commit
        message property) will overwrite the previous value of that
        property <emphasis>forever</emphasis>.
      </para>
    </warning>
    <important>
      <para>
        Since TortoiseSVN keeps a cache of all the log information,
        edits made for author and log messages will only show up
        on your local installation. Other users using TortoiseSVN
        will still see the cached (old) authors and log messages until
        they refresh the log cache.
        Refer to <xref linkend="tsvn-dug-showlog-refresh"/>
      </para>
    </important>
  </sect2>
  <sect2 id="tsvn-dug-showlog-filter">
    <title>Filtering Log Messages</title>
    <indexterm>
      <primary>filter</primary>
    </indexterm>
    <para>
      If you want to restrict the log messages to show only those
      you are interested in rather than scrolling through a list
      of hundreds, you can use the filter controls at the top of
      the Log Dialog. The start and end date controls allow you
      to restrict the output to a known date range. The search
      box allows you to show only messages which contain a
      particular phrase.
    </para>
    <para>
      Click on the search icon to select which information you want
      to search in, and to choose <emphasis>regex</emphasis> mode.
      Normally you will only need a simple sub-string search, but if you
      need to more flexible search terms, you can use regular expressions.
      If you hover the mouse over the box, a tooltip will give hints
      on how to use the regex functions, or the sub-string functions.
      The filter works by checking whether your filter string matches
      the log entries, and then only those entries which <emphasis>match</emphasis>
      the filter string are shown.
    </para>
    <para>
      Simple sub-string search works in a manner similar to a search engine.
      Strings to search for are separated by spaces, and all strings must
      match. You can use a leading <literal>-</literal> to specify that a
      particular sub-string is not found (invert matching for that term),
      and you can use <literal>!</literal> at the start of the expression
      to invert matching for the entire expression.
      You can use a leading <literal>+</literal> to specify that a sub-string
      should be included, even if previously excluded with a <literal>-</literal>.
      Note that the order of inclusion/exclusion is significant here.
      You can use quote marks to surround a string which must contain spaces,
      and if you want to search for a literal quotation mark you can use two
      quotation marks together as a self-escaping sequence.
      Note that the backslash character is <emphasis>not</emphasis> used as
      an escape character and has no special significance in simple sub-string
      searches. Examples will make this easier:
      <screen>
Alice Bob -Eve
      </screen>
      searches for strings containing both Alice and Bob but not Eve
      <screen>
Alice -Bob +Eve
      </screen>
      searches for strings containing both Alice but not Bob, or strings
      which contain Eve.
      <screen>
-Case +SpecialCase
      </screen>
      searches for strings which do not contain Case, but still include
      strings which contain SpecialCase.
      <screen>
!Alice Bob
      </screen>
      searches for strings which do not contain both Alice and Bob
      <screen>
!-Alice -Bob
      </screen>
      do you remember De Morgan's theorem? NOT(NOT Alice AND NOT Bob)
      reduces to (Alice OR Bob).
      <screen>
"Alice and Bob"
      </screen>
      searches for the literal expression <quote>Alice and Bob</quote>
      <screen>
""
      </screen>
      searches for a double-quote anywhere in the text
      <screen>
"Alice says ""hi"" to Bob"
      </screen>
      searches for the literal expression <quote>Alice says "hi" to Bob</quote>.
    </para>
    <para>
      Describing the use of regular expression searches is beyond the scope
      of this manual, but
      you can find online documentation and a tutorial at
      <ulink url="https://www.regular-expressions.info/">
        <citetitle>https://www.regular-expressions.info/</citetitle>
      </ulink>.
    </para>
    <para>
      Note that these filters act on the messages already retrieved.
      They do not control downloading of messages from the repository.
    </para>
    <para>
      You can also filter the path names in the bottom pane using the
      <guilabel>Show only affected paths</guilabel> checkbox.
      Affected paths are those which contain the path used to display
      the log. If you fetch the log for a folder, that means anything
      in that folder or below it. For a file it means just that one file.
      Normally the path list shows any other paths which are affected by
      the same commit, but in grey. If the box is checked, those paths
      are hidden.
    </para>
    <para>
      Sometimes your working practices will require log messages to follow
      a particular format, which means that the text describing the changes
      is not visible in the abbreviated summary shown in the top pane.
      The property <literal>tsvn:logsummary</literal> can be used to
      extract a portion of the log message to be shown in the top pane.
      Read <xref linkend="tsvn-dug-propertypage-tsvn-props"/> to find
      out how to use this property.
    </para>
    <tip>
      <title>No Log Formatting from Repository Browser</title>
      <para>
        Because the formatting depends upon accessing Subversion
        properties, you will only see the results when using a checked
        out working copy. Fetching properties remotely is a slow operation,
        so you will not see this feature in action from the repo browser.
      </para>
    </tip>
  </sect2>
  <sect2 id="tsvn-dug-showlog-5">
    <?dbhh topicname="HIDD_STATGRAPH"?>
    <title>Statistical Information</title>
    <indexterm>
      <primary>statistics</primary>
    </indexterm>
    <para>
      The <guibutton>Statistics</guibutton> button brings up a box
      showing some interesting information about the revisions
      shown in the Log dialog. This shows how many authors have
      been at work, how many commits they have made, progress
      by week, and much more. Now you can see at a glance who
      has been working hardest and who is slacking ;-)
    </para>
    <sect3 id="tsvn-dug-showlog-stats-1">
      <title>Statistics Page</title>
      <para>
        This page gives you all the numbers you can think of,
        in particular the period and number of revisions covered,
        and some min/max/average values.
      </para>
    </sect3>
    <sect3 id="tsvn-dug-showlog-stats-2">
      <title>Commits by Author Page</title>
      <para>
        <figure id="tsvn-dug-showlog-stats-dia-2">
          <title>Commits-by-Author Histogram</title>
          <graphic fileref="../images/StatsByAuthor.png"/>
        </figure>
        This graph shows you which authors have been active on the
        project as a simple histogram, stacked histogram or
        pie chart.
        <figure id="tsvn-dug-showlog-stats-dia-3">
          <title>Commits-by-Author Pie Chart</title>
          <graphic fileref="../images/StatsByAuthPie.png"/>
        </figure>
      </para>
      <para>
        Where there are a few major authors and many minor contributors,
        the number of tiny segments can make the graph more difficult to
        read. The slider at the bottom allows you to set a threshold
        (as a percentage of total commits) below which any activity is
        grouped into an <emphasis>Others</emphasis> category.
      </para>
    </sect3>
    <sect3 id="tsvn-dug-showlog-stats-3">
      <title>Commits by date Page</title>
      <para>
        <figure id="tsvn-dug-showlog-stats-dia-4">
          <title>Commits-by-date Graph</title>
          <graphic fileref="../images/StatsByDate.png"/>
        </figure>
        This page gives you a graphical representation of project
        activity in terms of number of commits <emphasis>and</emphasis>
        author. This gives some idea of when a project is being worked
        on, and who was working at which time.
      </para>
      <para>
        When there are several authors, you will get many lines on the
        graph. There are two views available here: <emphasis>normal</emphasis>,
        where each author's activity is relative to the base line, and
        <emphasis>stacked</emphasis>, where each author's activity is
        relative to the line underneath.
        The latter option avoids the lines crossing over, which can make
        the graph easier to read, but less easy to see one author's output.
      </para>
    </sect3>
    <para>
      By default the analysis is case-sensitive, so users
      <literal>PeterEgan</literal> and <literal>PeteRegan</literal>
      are treated as different authors. However, in many cases user names
      are not case-sensitive, and are sometimes entered inconsistently,
      so you may want <literal>DavidMorgan</literal> and
      <literal>davidmorgan</literal> to be treated as the same person.
      Use the <guilabel>Authors case insensitive</guilabel> checkbox
      to control how this is handled.
    </para>
    <para>
      Note that the statistics cover the same period as the
      Log dialog. If that is only displaying one revision
      then the statistics will not tell you very much.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-cache">
    <?dbhh topicname="HIDD_GOOFFLINE"?>
    <title>Offline Mode</title>
    <para>
      <figure id="tsvn-dug-showlog-offline">
        <title>Go Offline Dialog</title>
        <graphic fileref="../images/LogCacheOffline.png"/>
      </figure>
      If the server is not reachable, and you have log caching enabled
      you can use the log dialog and revision graph in offline mode.
      This uses data from the cache, which allows you to continue working
      although the information may not be up-to-date or even complete.
    </para>
    <para>
      Here you have three options:
      <variablelist>
        <varlistentry>
          <term>Offline for now</term>
          <listitem>
            <para>
              Complete the current operation in offline mode,
              but retry the repository next time log data is
              requested.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Permanently offline</term>
          <listitem>
            <para>
              Remain in offline mode until a repository check
              is specifically requested. See
              <xref linkend="tsvn-dug-showlog-refresh"/>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Cancel</term>
          <listitem>
            <para>
              If you don't want to continue the operation with
              possibly stale data, just cancel.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <para>
      The <guilabel>Make this the default</guilabel> checkbox prevents this
      dialog from re-appearing and always picks the option you choose next.
      You can still change (or remove) the default after doing this from
      <menuchoice>
        <guimenu>TortoiseSVN</guimenu>
        <guimenuitem>Settings</guimenuitem>
      </menuchoice>.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-showlog-refresh">
    <title>Refreshing the View</title>
    <para>
      If you want to check the server again for newer log messages,
      you can simply refresh the view using <keycap>F5</keycap>. If you
      are using the log cache (enabled by default), this will check the
      repository for newer messages and fetch only the new ones.
      If the log cache was in offline mode, this will also attempt to
      go back online.
    </para>
    <para>
      If you are using the log cache and you think the message content
      or author may have changed, you can use <keycap>Shift-F5</keycap>
      or <keycap>Ctrl-F5</keycap> to re-fetch the displayed messages from
      the server and update the log cache. Note that this only affects
      messages currently shown and does not invalidate the entire cache
      for that repository.
    </para>
  </sect2>
</sect1>
