1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
\r
3 <sect1 id="tsvn-dug-revgraph">
\r
4 <?dbhh topicname="HIDD_REVISIONGRAPH"?>
\r
5 <title>Revision Graphs</title>
\r
7 <primary>revision</primary>
\r
10 <primary>graph</primary>
\r
13 <primary>revision graph</primary>
\r
16 <figure id="tsvn-dug-revgraph-dia-1">
\r
17 <title>A Revision Graph</title>
\r
18 <graphic fileref="../images/RevisionGraph.png"/>
\r
20 Sometimes you need to know where branches and tags were taken from
\r
21 the trunk, and the ideal way to view this sort of information is
\r
22 as a graph or tree structure. That's when you need to use
\r
24 <guimenu>TortoiseGit</guimenu>
\r
25 <guimenuitem>Revision Graph...</guimenuitem>
\r
29 This command analyses the revision history and attempts to create
\r
30 a tree showing the points at which copies were taken, and when
\r
31 branches/tags were deleted.
\r
35 In order to generate the graph, TortoiseGit must fetch all log messages
\r
36 from the repository root. Needless to say this can take several minutes
\r
37 even with a repository of a few thousand revisions, depending on server
\r
38 speed, network bandwidth, etc. If you try this with something like the
\r
39 <emphasis>Apache</emphasis> project which currently has over 500,000
\r
40 revisions you could be waiting for some time.
\r
43 The good news is that if you are using Log Caching, you only have to
\r
44 suffer this delay once. After that, log data is held locally.
\r
45 Log caching is enabled in TortoiseGit's settings.
\r
48 <sect2 id="tsvn-dug-revgraph-nodes">
\r
49 <title>Revision Graph Nodes</title>
\r
51 Each revision graph node represents a revision in the repository
\r
52 where something changed in the tree you are looking at.
\r
53 Different types of node can be distinguished by shape and colour.
\r
54 The shapes are fixed, but colours can be set using
\r
56 <guimenu>TortoiseGit</guimenu>
\r
57 <guimenuitem>Settings</guimenuitem>
\r
61 <term>Added or copied items</term>
\r
64 Items which have been added, or created by copying
\r
65 another file/folder are shown using a rounded rectangle.
\r
66 The default colour is green. Tags are treated as a
\r
67 special case and use a different shade.
\r
72 <term>Deleted items</term>
\r
75 Deleted items eg. a branch which is no longer required,
\r
76 are shown using an octagon (rectangle with corners cut off).
\r
77 The default colour is red.
\r
82 <term>Renamed items</term>
\r
85 Renamed items are also shown using an octagon,
\r
86 but the default colour is blue.
\r
91 <term>Replaced items</term>
\r
94 A replaced item is one where the original item has been
\r
95 deleted and replaced with another item of the same name.
\r
96 The default colour is green.
\r
101 <term>Branch tip revision</term>
\r
104 Where a branch (or trunk or tag) has been modified since
\r
105 the last branch node, this is shown using an ellipse.
\r
106 Shown when the <guilabel>Show HEAD revisions</guilabel>
\r
107 option is selected.
\r
112 <term>Normal item</term>
\r
115 All other items are shown using a plain rectangle.
\r
122 Note that by default the graph only shows the points at which items were
\r
123 added, copied or deleted. Showing every revision of a project where simple
\r
124 modifications too place will generate a very large graph for non-trivial
\r
126 If you really want to see <emphasis>all</emphasis> revisions where
\r
127 changes were made, there is an option to do this in the
\r
128 <guilabel>View</guilabel> menu and on the toolbar.
\r
131 <sect2 id="tsvn-dug-revgraph-views">
\r
132 <title>Changing the View</title>
\r
134 Because a revision graph is often quite complex, there are a number
\r
135 of features which can be used to tailor the view the way you want it.
\r
136 These are available in the <guilabel>View</guilabel> menu and from the
\r
140 <term>Group branches</term>
\r
143 The default behavior (grouping off) will use one row per
\r
144 revision and all rows are sorted strictly by revision.
\r
145 As a result, long-living branches occupy a whole column
\r
146 for only a few changes and the graph becomes very broad.
\r
149 This mode groups changes by branch, so that there is no
\r
150 global revision ordering: Consecutive revisions on
\r
151 a branch will be shown in (often) consecutive lines.
\r
152 Sub-branches, however, are arranged in such a way that
\r
153 later branches will be shown in the same column above
\r
154 older branches to keep the graph slim. As a result, a
\r
155 given row may contain changes from different revisions.
\r
160 <term>Oldest on top</term>
\r
163 Normally the graph shows the oldest revision at the bottom,
\r
164 and the tree grows upwards. Use this option to grow down
\r
165 from the top instead.
\r
170 <term>Align trees on top</term>
\r
173 When a graph is broken into several smaller trees, the
\r
174 trees may appear either in natural revision order, or
\r
175 aligned at the bottom of the window, depending on whether
\r
176 you are using the <guilabel>Group Branches</guilabel>
\r
177 option. Use this option to grow all trees down from the
\r
183 <term>Reduce cross lines</term>
\r
186 If the layout of the graph has produced a lot of
\r
187 crossing lines, use this option to clean it up.
\r
188 This may make the layout columns appear in less
\r
189 logical places, for example in a diagonal line
\r
190 rather than a column, and it may take a little time
\r
196 <term>Differential path names</term>
\r
199 Long path names can take a lot of space and make the
\r
200 node boxes very large. Use this option to show only
\r
201 the changed part of a path, replacing the common part
\r
202 with dots. e.g. if you create a branch
\r
203 <literal>/branches/1.2.x/doc/html</literal> from
\r
204 <literal>/trunk/doc/html</literal> the branch could
\r
205 be shown in compact form as
\r
206 <literal>/branches/1.2.x/.</literal>
\r
211 <term>Show all revisions</term>
\r
214 This does just what you expect and shows every revision
\r
215 where something (in the tree that you are graphing) has
\r
216 changed. For long histories this can produce a truly
\r
222 <term>Show HEAD revisions</term>
\r
225 This ensures that the latest revision on every branch is
\r
226 always shown on the graph.
\r
231 <term>Exact copy sources</term>
\r
234 When a branch/tag is made, the default behaviour is to
\r
235 show the branch as taken from the last node where a
\r
236 change was made. Strictly speaking this is inaccurate
\r
237 since the branches are often made from the current HEAD
\r
238 rather than a specific revision. So it is possible to show
\r
239 the more correct (but less useful) revision that was
\r
240 used to create the copy.
\r
245 <term>Fold tags</term>
\r
248 If you want to see a graph of software development,
\r
249 tagged releases may be of little interest to you.
\r
250 This option hides the nodes for tags and shows them
\r
251 instead in the tooltip for the node that they were
\r
252 copied from. A tag icon on the right side of the
\r
253 source node indicates that tags were made.
\r
258 <term>Hide deleted paths</term>
\r
261 Hides paths which are no longer present at the HEAD
\r
262 revision of the repository, e.g. deleted branches.
\r
267 <term>Hide unused branches</term>
\r
270 Hides branches where no changes were committed that affect
\r
271 the tree being graphed before the branch was deleted. This
\r
272 does not necessarily indicate that the branch was not
\r
273 used, just that no changes were made to <emphasis>this</emphasis>
\r
279 <term>Show WC revision</term>
\r
282 Marks the revision on the graph which corresponds to the
\r
283 update revision of the item you fetched the graph for.
\r
284 If you have just updated, this will be HEAD, but if others
\r
285 have committed changes since your last update your WC
\r
286 may be a few revisions lower down.
\r
287 The node is marked by giving it a bold outline.
\r
292 <term>Show WC modifications</term>
\r
295 If your WC contains local changes, this option draws it
\r
296 as a separate elliptical node, linked back to the node
\r
297 that your WC was last updated to.
\r
298 The default outline colour is red.
\r
299 You may need to refresh the graph using
\r
300 <keycap>F5</keycap> to capture recent changes.
\r
305 <term>Filter</term>
\r
308 Sometimes the revision graph contains more revisions
\r
309 than you want to see. This option opens a dialog which
\r
310 allows you to restrict the range of revisions
\r
311 displayed, and to hide particular paths by name.
\r
316 <term>Tree stripes</term>
\r
319 Where the graph contains several trees, it is sometimes
\r
320 useful to use alternating colours on the background to
\r
321 help distinguish between trees,
\r
326 <term>Show overview</term>
\r
329 Shows a small picture of the entire graph, with the current
\r
330 view window as a rectangle which you can drag. This allows
\r
331 you to navigate the graph more easily.
\r
338 <sect2 id="tsvn-dug-revgraph-use">
\r
339 <title>Using the Graph</title>
\r
341 To make it easier to navigate a large graph, use the overview window.
\r
342 This shows the entire graph in a small window, with the currently
\r
343 displayed portion highlighted. You can drag the highlighted area to
\r
344 change the displayed region.
\r
347 The revision date, author and comments are shown in a hint box whenever
\r
348 the mouse hovers over a revision box.
\r
351 If you select two revisions (Use <keycap>Ctrl</keycap>-<action>left click</action>),
\r
352 you can use the context menu to show the
\r
353 differences between these revisions. You can choose to show differences
\r
354 as at the branch creation points, but usually you will want to show the
\r
355 differences at the branch end points, i.e. at the HEAD revision.
\r
358 You can view the differences as a Unified-Diff file, which shows all
\r
359 differences in a single file with minimal context. If you opt to
\r
361 <guimenu>Context Menu</guimenu>
\r
362 <guimenuitem>Compare Revisions</guimenuitem>
\r
364 you will be presented with a list of changed files.
\r
365 <action>Double click</action> on a file name to fetch both revisions
\r
366 of the file and compare them using the visual difference tool.
\r
369 If you <action>right click</action> on a revision you can use
\r
371 <guimenu>Context Menu</guimenu>
\r
372 <guimenuitem>Show Log</guimenuitem>
\r
374 to view the history.
\r
377 You can also merge changes in the selected revision(s) into a
\r
378 different working copy. A folder selection dialog allows you to
\r
379 choose the working copy to merge into, but after that there is
\r
380 no confirmation dialog, nor any opportunity to try a test merge.
\r
381 It is a good idea to merge into an unmodified working copy so
\r
382 that you can revert the changes if it doesn't work out!
\r
383 This is a useful feature if you want to merge selected
\r
384 revisions from one branch to another.
\r
388 Because Git cannot provide all the information required,
\r
389 a certain amount of interpretation is required, which can sometimes
\r
390 give strange results. Nevertheless, the output for the trunk will
\r
391 generally give useful results.
\r
395 <sect2 id="tsvn-dug-revgraph-refresh">
\r
396 <title>Refreshing the View</title>
\r
398 If you want to check the server again for newer information,
\r
399 you can simply refresh the view using <keycap>F5</keycap>. If you
\r
400 are using the log cache (enabled by default), this will check the
\r
401 repository for newer commits and fetch only the new ones.
\r
402 If the log cache was in offline mode, this will also attempt to
\r
406 If you are using the log cache and you think the message content
\r
407 or author may have changed, you should use the log dialog to
\r
408 refresh the messages you need. Since the revision graph works from
\r
409 the repository root, we would have to invalidate the entire log
\r
410 cache, and refilling it could take a <emphasis>very</emphasis>
\r
414 <sect2 id="tsvn-dug-revgraph-pruning">
\r
415 <title>Pruning Trees</title>
\r
417 A large tree can be difficult to navigate and sometimes you will
\r
418 want to hide parts of it, or break it down into a forest of
\r
419 smaller trees. If you hover the mouse over the point where a node
\r
420 link enters or leaves the node you will see one or more popup
\r
421 buttons which allow you to do this.
\r
424 <graphic fileref="../images/RevGraphCollapse.png"/>
\r
425 Click on the minus button to collapse the attached sub-tree.
\r
428 <graphic fileref="../images/RevGraphExpand.png"/>
\r
429 Click on the plus button to expand a collapsed tree.
\r
430 When a tree has been collapsed, this button remains visible
\r
431 to indicate the hidden sub-tree.
\r
434 <graphic fileref="../images/RevGraphSplit.png"/>
\r
435 Click on the cross button to split the attached sub-tree
\r
436 and show it as a separate tree on the graph.
\r
439 <graphic fileref="../images/RevGraphJoin.png"/>
\r
440 Click on the circle button to reattach a split tree.
\r
441 When a tree has been split away, this button remains visible
\r
442 to indicate that there is a separate sub-tree.
\r
OSDN Git Service
