<?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>TortoiseGit</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, TortoiseGit 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 TortoiseGit'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>TortoiseGit</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 are treated as a
							special case and use a different shade.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Deleted items</term>
					<listitem>
						<para>
							Deleted items eg. 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>Replaced items</term>
					<listitem>
						<para>
							A replaced item is one where the original item has been
							deleted and replaced with another item of the same name.
							The default colour is green.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Branch tip revision</term>
					<listitem>
						<para>
							Where a branch (or trunk or tag) has been modified since
							the last branch node, this is shown using an ellipse.
							Shown when the <guilabel>Show HEAD revisions</guilabel>
							option is selected.
						</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 where simple
			modifications too place 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>
	</sect2>
	<sect2 id="tsvn-dug-revgraph-views">
		<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) will use one row per
							revision and all rows are sorted strictly by revision.
							As a result, long-living branches 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
							older 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>
							If the layout of the graph has produced a lot of
							crossing lines, use this option to clean it up.
							This may make the layout columns appear in less
							logical places, for example in a diagonal line
							rather than a column, and it may take a little time
							to optimise.
						</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>
						</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.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Fold tags</term>
					<listitem>
						<para>
							If you want to see a graph of software development,
							tagged releases may be of little interest to you.
							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.
						</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>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Hide unused branches</term>
					<listitem>
						<para>
							Hides branches where no changes were committed that affect
							the tree being graphed before the branch was deleted. 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>
					</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.
						</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>
		<caution>
			<para>
				Because Git cannot provide all the information required,
				a certain amount of interpretation is required, which can sometimes
				give strange results. Nevertheless, the output for the trunk will
				generally give useful results.
			</para>
		</caution>
	</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>
	</sect2>
</sect1>
