<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-dug-revgraph">
  <?dbhh topicname="HIDD_REVISIONGRAPH"?>
  <title>Revision Graphs</title>
  <indexterm>
    <primary>revision</primary>
  </indexterm>
  <indexterm>
    <primary>graph</primary>
  </indexterm>
  <indexterm>
    <primary>revision graph</primary>
  </indexterm>
  <para>
    <figure id="tsvn-dug-revgraph-dia-1">
      <title>A Revision Graph</title>
      <graphic fileref="../images/RevisionGraph.png"/>
    </figure>
    Sometimes you need to know where branches and tags were taken from
    the trunk, and the ideal way to view this sort of information is
    as a graph or tree structure. That's when you need to use
    <menuchoice>
      <guimenu>TortoiseSVN</guimenu>
      <guimenuitem>Revision Graph...</guimenuitem>
    </menuchoice>
  </para>
  <para>
    This command analyses the revision history and attempts to create
    a tree showing the points at which copies were taken, and when
    branches/tags were deleted.
  </para>
  <important>
    <para>
      In order to generate the graph, TortoiseSVN must fetch all log messages
      from the repository root. Needless to say this can take several minutes
      even with a repository of a few thousand revisions, depending on server
      speed, network bandwidth, etc. If you try this with something like the
      <emphasis>Apache</emphasis> project which currently has over 500,000
      revisions you could be waiting for some time.
    </para>
    <para>
      The good news is that if you are using log caching, you only have to
      suffer this delay once. After that, log data is held locally.
      Log caching is enabled in TortoiseSVN's settings.
    </para>
  </important>
  <sect2 id="tsvn-dug-revgraph-nodes">
    <title>Revision Graph Nodes</title>
    <para>
      Each revision graph node represents a revision in the repository
      where something changed in the tree you are looking at.
      Different types of node can be distinguished by shape and colour.
      The shapes are fixed, but colours can be set using
      <menuchoice>
        <guimenu>TortoiseSVN</guimenu>
        <guimenuitem>Settings</guimenuitem>
      </menuchoice>
      <variablelist>
        <varlistentry>
          <term>Added or copied items</term>
          <listitem>
            <para>
              Items which have been added, or created by copying
              another file/folder are shown using a rounded rectangle.
              The default colour is green. Tags and trunks are treated
              as a special case and use a different shade, depending
              on the
              <menuchoice>
                <guimenu>TortoiseSVN</guimenu>
                <guimenuitem>Settings</guimenuitem>
              </menuchoice>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Deleted items</term>
          <listitem>
            <para>
              Deleted items e.g. a branch which is no longer required,
              are shown using an octagon (rectangle with corners cut off).
              The default colour is red.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Renamed items</term>
          <listitem>
            <para>
              Renamed items are also shown using an octagon,
              but the default colour is blue.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Branch tip revision</term>
          <listitem>
            <para>
              The graph is normally restricted to showing branch points,
              but it is often useful to be able to see the respective HEAD
              revision for each branch too. If you select
              <guilabel>Show HEAD revisions</guilabel>, each HEAD
              revision nodes will be shown as an ellipse.
              Note that HEAD here refers to the last revision committed
              on that path, not to the HEAD revision of the repository.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Working copy revision</term>
          <listitem>
            <para>
              If you invoked the revision graph from a working copy,
              you can opt to show the BASE revision on the graph using
              <guilabel>Show WC revision</guilabel>, which marks
              the BASE node with a bold outline.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Modified working copy</term>
          <listitem>
            <para>
              If you invoked the revision graph from a working copy,
              you can opt to show an additional node representing your
              modified working copy using
              <guilabel>Show WC modifications</guilabel>. This is an
              elliptical node with a bold outline in red by default.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Normal item</term>
          <listitem>
            <para>
              All other items are shown using a plain rectangle.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <para>
      Note that by default the graph only shows the points at which items were
      added, copied or deleted. Showing every revision of a project will
      generate a very large graph for non-trivial cases.
      If you really want to see <emphasis>all</emphasis> revisions where
      changes were made, there is an option to do this in the
      <guilabel>View</guilabel> menu and on the toolbar.
    </para>
    <para>
      The default view (grouping off) places the nodes such that their vertical
      position is in strict revision order, so you have a visual cue for the
      order in which things were done. Where two nodes are in the same column
      the order is very obvious. When two nodes are in adjacent columns the
      offset is much smaller because there is no need to prevent the nodes
      from overlapping, and as a result the order is a little less obvious.
      Such optimisations are necessary to keep complex graphs to a reasonable
      size.
      Please note that this ordering uses the <emphasis>edge</emphasis> of
      the node on the <emphasis>older</emphasis> side as a reference, i.e.
      the bottom edge of the node when the graph is shown with oldest node
      at the bottom. The reference edge is significant because the node shapes
      are not all the same height.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-revgraph-views">
    <?dbhh topicname="HIDD_REVGRAPHFILTER"?>
    <title>Changing the View</title>
    <para>
      Because a revision graph is often quite complex, there are a number
      of features which can be used to tailor the view the way you want it.
      These are available in the <guilabel>View</guilabel> menu and from the
      toolbar.
      <variablelist>
        <varlistentry>
          <term>Group branches</term>
          <listitem>
            <para>
              The default behavior (grouping off) has all rows sorted
              strictly by revision. As a result, long-living branches
              with sparse commits occupy a whole column for only a few
              changes and the graph becomes very broad.
            </para>
            <para>
              This mode groups changes by branch, so that there is no
              global revision ordering: Consecutive revisions on
              a branch will be shown in (often) consecutive lines.
              Sub-branches, however, are arranged in such a way that
              later branches will be shown in the same column above
              earlier branches to keep the graph slim. As a result, a
              given row may contain changes from different revisions.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Oldest on top</term>
          <listitem>
            <para>
              Normally the graph shows the oldest revision at the bottom,
              and the tree grows upwards. Use this option to grow down
              from the top instead.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Align trees on top</term>
          <listitem>
            <para>
              When a graph is broken into several smaller trees, the
              trees may appear either in natural revision order, or
              aligned at the bottom of the window, depending on whether
              you are using the <guilabel>Group Branches</guilabel>
              option. Use this option to grow all trees down from the
              top instead.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Reduce cross lines</term>
          <listitem>
            <para>
              This option is normally enabled and avoids showing
              the graph with a lot of confused crossing lines.
              However this may also make the layout columns appear
              in less logical places, for example in a diagonal line
              rather than a column, and the graph may require a
              larger area to draw. If this is a problem you can disable
              the option from the <guilabel>View</guilabel> menu.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Differential path names</term>
          <listitem>
            <para>
              Long path names can take a lot of space and make the
              node boxes very large. Use this option to show only
              the changed part of a path, replacing the common part
              with dots. E.g. if you create a branch
              <literal>/branches/1.2.x/doc/html</literal> from
              <literal>/trunk/doc/html</literal> the branch could
              be shown in compact form as
              <literal>/branches/1.2.x/..</literal> because the last
              two levels, <literal>doc</literal> and
              <literal>html</literal>, did not change.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show all revisions</term>
          <listitem>
            <para>
              This does just what you expect and shows every revision
              where something (in the tree that you are graphing) has
              changed. For long histories this can produce a truly
              huge graph.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show HEAD revisions</term>
          <listitem>
            <para>
              This ensures that the latest revision on every branch is
              always shown on the graph.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Exact copy sources</term>
          <listitem>
            <para>
              When a branch/tag is made, the default behaviour is to
              show the branch as taken from the last node where a
              change was made. Strictly speaking this is inaccurate
              since the branches are often made from the current HEAD
              rather than a specific revision. So it is possible to show
              the more correct (but less useful) revision that was
              used to create the copy. Note that this revision may
              be younger than the HEAD revision of the source branch.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Fold tags</term>
          <listitem>
            <para>
              When a project has many tags, showing every tag as a
              separate node on the graph takes a lot of space and
              obscures the more interesting development branch structure.
              At the same time you may need to be able to access the
              tag content easily so that you can compare revisions.
              This option hides the nodes for tags and
              shows them instead in the tooltip for the node that
              they were copied from. A tag icon on the right side
              of the source node indicates that tags were made.
              This greatly simplifies the view.
            </para>
            <para>
              Note that if a tag is itself used as the source for a
              copy, perhaps a new branch based on a tag, then that
              tag will be shown as a separate node rather than folded.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Hide deleted paths</term>
          <listitem>
            <para>
              Hides paths which are no longer present at the HEAD
              revision of the repository, e.g. deleted branches.
            </para>
            <para>
              If you have selected the <guilabel>Fold tags</guilabel>
              option then a deleted branch from which tags were taken
              will still be shown, otherwise the tags would disappear too.
              The last revision that was tagged will be shown in the
              colour used for deleted nodes instead of showing a separate
              deletion revision.
            </para>
            <para>
              If you select the <guilabel>Hide tags</guilabel> option
              then these branches will disappear again as they are not
              needed to show the tags.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Hide unused branches</term>
          <listitem>
            <para>
              Hides branches where no changes were committed to the
              respective file or sub-folder. This does not necessarily
              indicate that the branch was not used, just that no
              changes were made to <emphasis>this</emphasis> part of it.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show WC revision</term>
          <listitem>
            <para>
              Marks the revision on the graph which corresponds to the
              update revision of the item you fetched the graph for.
              If you have just updated, this will be HEAD, but if others
              have committed changes since your last update your WC
              may be a few revisions lower down.
              The node is marked by giving it a bold outline.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show WC modifications</term>
          <listitem>
            <para>
              If your WC contains local changes, this option draws it
              as a separate elliptical node, linked back to the node
              that your WC was last updated to.
              The default outline colour is red.
              You may need to refresh the graph using
              <keycap>F5</keycap> to capture recent changes.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Filter</term>
          <listitem>
            <para>
              Sometimes the revision graph contains more revisions
              than you want to see. This option opens a dialog which
              allows you to restrict the range of revisions
              displayed, and to hide particular paths by name.
            </para>
            <para>
              If you hide a particular path and that node has child
              nodes, the children will be shown as a separate tree.
              If you want to hide all children as well, use the
              <guilabel>Remove the whole subtree(s)</guilabel> checkbox.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Tree stripes</term>
          <listitem>
            <para>
              Where the graph contains several trees, it is sometimes
              useful to use alternating colours on the background to
              help distinguish between trees.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show overview</term>
          <listitem>
            <para>
              Shows a small picture of the entire graph, with the current
              view window as a rectangle which you can drag. This allows
              you to navigate the graph more easily. Note that for very
              large graphs the overview may become useless due to the
              extreme zoom factor and will therefore not be shown in such
              cases.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
  </sect2>
  <sect2 id="tsvn-dug-revgraph-use">
    <title>Using the Graph</title>
    <para>
      To make it easier to navigate a large graph, use the overview window.
      This shows the entire graph in a small window, with the currently
      displayed portion highlighted. You can drag the highlighted area to
      change the displayed region.
    </para>
    <para>
      The revision date, author and comments are shown in a hint box whenever
      the mouse hovers over a revision box.
    </para>
    <para>
      If you select two revisions (Use <keycap>Ctrl</keycap>-<action>left click</action>),
      you can use the context menu to show the
      differences between these revisions. You can choose to show differences
      as at the branch creation points, but usually you will want to show the
      differences at the branch end points, i.e. at the HEAD revision.
    </para>
    <para>
      You can view the differences as a Unified-Diff file, which shows all
      differences in a single file with minimal context. If you opt to
      <menuchoice>
        <guimenu>Context Menu</guimenu>
        <guimenuitem>Compare Revisions</guimenuitem>
      </menuchoice>
      you will be presented with a list of changed files.
      <action>Double click</action> on a file name to fetch both revisions
      of the file and compare them using the visual difference tool.
    </para>
    <para>
      If you <action>right click</action> on a revision you can use
      <menuchoice>
        <guimenu>Context Menu</guimenu>
        <guimenuitem>Show Log</guimenuitem>
      </menuchoice>
      to view the history.
    </para>
    <para>
      You can also merge changes in 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>
    <tip>
      <title>Learn to Read the Revision Graph</title>
      <para>
        First-time users may be surprised by the fact that the revision
        graph shows something that does not match the user's mental model.
        If a revision changes multiple copies or branches of a file or
        folder, for instance, then there will be multiple nodes for that
        single revision. It is a good practice to start with the leftmost
        options in the toolbar and customize the graph step-by-step until
        it comes close to your mental model.
      </para>
      <para>
        All filter options try lose as little information as possible.
        That may cause some nodes to change their color, for instance.
        Whenever the result is unexpected, undo the last filter operation
        and try to understand what is special about that particular revision
        or branch. In most cases, the initially expected outcome of the
        filter operation would either be inaccurate or misleading.
      </para>
    </tip>
  </sect2>
  <sect2 id="tsvn-dug-revgraph-refresh">
    <title>Refreshing the View</title>
    <para>
      If you want to check the server again for newer information,
      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 commits 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 should use the log dialog to
      refresh the messages you need. Since the revision graph works from
      the repository root, we would have to invalidate the entire log
      cache, and refilling it could take a <emphasis>very</emphasis>
      long time.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-revgraph-pruning">
    <title>Pruning Trees</title>
    <para>
      A large tree can be difficult to navigate and sometimes you will
      want to hide parts of it, or break it down into a forest of
      smaller trees. If you hover the mouse over the point where a node
      link enters or leaves the node you will see one or more popup
      buttons which allow you to do this.
    </para>
    <para>
      <graphic fileref="../images/RevGraphCollapse.png"/>
      Click on the minus button to collapse the attached sub-tree.
    </para>
    <para>
      <graphic fileref="../images/RevGraphExpand.png"/>
      Click on the plus button to expand a collapsed tree.
      When a tree has been collapsed, this button remains visible
      to indicate the hidden sub-tree.
    </para>
    <para>
      <graphic fileref="../images/RevGraphSplit.png"/>
      Click on the cross button to split the attached sub-tree
      and show it as a separate tree on the graph.
    </para>
    <para>
      <graphic fileref="../images/RevGraphJoin.png"/>
      Click on the circle button to reattach a split tree.
      When a tree has been split away, this button remains visible
      to indicate that there is a separate sub-tree.
    </para>
    <para>
      Click on the graph background for the main context menu, which
      offers options to <guilabel>Expand all</guilabel> and
      <guilabel>Join all</guilabel>. If no branch has been collapsed
      or split, the context menu will not be shown.
    </para>
  </sect2>
</sect1>
