<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-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="tgit-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 point, 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 direct graph showing the points at tag, branch and other reference.
	</para>
	<important>
		<para>
			In order to generate the graph, TortoiseGit must fetch all log messages
			from the repository root. Just show commits which have some reference point to.
		</para>
	</important>
	<sect2 id="tgit-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 nodes can be distinguished by color which can be configured 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 color 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 color is red.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Renamed items</term>
					<listitem>
						<para>
							Renamed items are also shown using an octagon,
							but the default color 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 the graph only shows the points at which items were
			reference by tag, branch or the other ref. Showing every revision of a project will
			generate a very large graph for non-trivial cases.
		</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="tgit-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 behavior 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
							color 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 color 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 colors 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="tgit-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="tgit-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>.
		</para>
	</sect2>
</sect1>
