| blob | c246dae4724f6494638532c423784a217cdf8ee4 |
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
6 <indexterm>\r
7 <primary>revision</primary>\r
8 </indexterm>\r
9 <indexterm>\r
10 <primary>graph</primary>\r
11 </indexterm>\r
12 <indexterm>\r
13 <primary>revision graph</primary>\r
14 </indexterm>\r
15 <para>\r
16 <figure id="tsvn-dug-revgraph-dia-1">\r
17 <title>A Revision Graph</title>\r
18 <graphic fileref="../images/RevisionGraph.png"/>\r
19 </figure>\r
20 Sometimes you need to know where branches and tags were taken from\r
21 the point, 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
23 <menuchoice>\r
24 <guimenu>TortoiseGit</guimenu>\r
25 <guimenuitem>Revision Graph...</guimenuitem>\r
26 </menuchoice>\r
27 </para>\r
28 <para>\r
29 This command analyses the revision history and attempts to create\r
30 a direct graph showing the points at tag, branch and other reference.\r
31 </para>\r
32 <important>\r
33 <para>\r
34 In order to generate the graph, TortoiseGit must fetch all log messages\r
35 from the repository root. Just show commits which have some reference point to.\r
36 </para>\r
37 </important>\r
38 <sect2 id="tsvn-dug-revgraph-nodes">\r
39 <title>Revision Graph Nodes</title>\r
40 <para>\r
41 Each revision graph node represents a revision in the repository\r
42 where something changed in the tree you are looking at.\r
43 Different types of node can be distinguished by colour.\r
44 but colours can be set using\r
45 <menuchoice>\r
46 <guimenu>TortoiseGit</guimenu>\r
47 <guimenuitem>Settings</guimenuitem>\r
48 </menuchoice>\r
49 <!--\r
50 <variablelist>\r
51 <varlistentry>\r
52 <term>Added or copied items</term>\r
53 <listitem>\r
54 <para>\r
55 Items which have been added, or created by copying\r
56 another file/folder are shown using a rounded rectangle.\r
57 The default colour is green. Tags and trunks are treated\r
58 as a special case and use a different shade, depending\r
59 on the\r
60 <menuchoice>\r
61 <guimenu>TortoiseSVN</guimenu>\r
62 <guimenuitem>Settings</guimenuitem>\r
63 </menuchoice>.\r
64 </para>\r
65 </listitem>\r
66 </varlistentry>\r
67 <varlistentry>\r
68 <term>Deleted items</term>\r
69 <listitem>\r
70 <para>\r
71 Deleted items e.g. a branch which is no longer required,\r
72 are shown using an octagon (rectangle with corners cut off).\r
73 The default colour is red.\r
74 </para>\r
75 </listitem>\r
76 </varlistentry>\r
77 <varlistentry>\r
78 <term>Renamed items</term>\r
79 <listitem>\r
80 <para>\r
81 Renamed items are also shown using an octagon,\r
82 but the default colour is blue.\r
83 </para>\r
84 </listitem>\r
85 </varlistentry>\r
86 <varlistentry>\r
87 <term>Branch tip revision</term>\r
88 <listitem>\r
89 <para>\r
90 The graph is normally restricted to showing branch points,\r
91 but it is often useful to be able to see the respective HEAD\r
92 revision for each branch too. If you select\r
93 <guilabel>Show HEAD revisions</guilabel>, each HEAD\r
94 revision nodes will be shown as an ellipse.\r
95 Note that HEAD here refers to the last revision committed\r
96 on that path, not to the HEAD revision of the repository.\r
97 </para>\r
98 </listitem>\r
99 </varlistentry>\r
100 <varlistentry>\r
101 <term>Working copy revision</term>\r
102 <listitem>\r
103 <para>\r
104 If you invoked the revision graph from a working copy,\r
105 you can opt to show the BASE revision on the graph using\r
106 <guilabel>Show WC revision</guilabel>, which marks\r
107 the BASE node with a bold outline.\r
108 </para>\r
109 </listitem>\r
110 </varlistentry>\r
111 <varlistentry>\r
112 <term>Modified working copy</term>\r
113 <listitem>\r
114 <para>\r
115 If you invoked the revision graph from a working copy,\r
116 you can opt to show an additional node representing your\r
117 modified working copy using\r
118 <guilabel>Show WC modifications</guilabel>. This is an\r
119 elliptical node with a bold outline in red by default.\r
120 </para>\r
121 </listitem>\r
122 </varlistentry>\r
123 <varlistentry>\r
124 <term>Normal item</term>\r
125 <listitem>\r
126 <para>\r
127 All other items are shown using a plain rectangle.\r
128 </para>\r
129 </listitem>\r
130 </varlistentry>\r
131 </variablelist>\r
132 -->\r
133 </para>\r
134 <para>\r
135 Note that the graph only shows the points at which items were\r
136 reference by tag, branch or the other ref. Showing every revision of a project will\r
137 generate a very large graph for non-trivial cases.\r
138 </para>\r
139 <!--\r
140 <para>\r
141 The default view (grouping off) places the nodes such that their vertical\r
142 position is in strict revision order, so you have a visual cue for the\r
143 order in which things were done. Where two nodes are in the same column\r
144 the order is very obvious. When two nodes are in adjacent columns the\r
145 offset is much smaller because there is no need to prevent the nodes\r
146 from overlapping, and as a result the order is a little less obvious.\r
147 Such optimisations are necessary to keep complex graphs to a reasonable\r
148 size.\r
149 Please note that this ordering uses the <emphasis>edge</emphasis> of\r
150 the node on the <emphasis>older</emphasis> side as a reference, i.e.\r
151 the bottom edge of the node when the graph is shown with oldest node\r
152 at the bottom. The reference edge is significant because the node shapes\r
153 are not all the same height.\r
154 </para>\r
155 -->\r
156 </sect2>\r
157 <!--\r
158 <sect2 id="tsvn-dug-revgraph-views">\r
159 <?dbhh topicname="HIDD_REVGRAPHFILTER"?>\r
160 <title>Changing the View</title>\r
161 <para>\r
162 Because a revision graph is often quite complex, there are a number\r
163 of features which can be used to tailor the view the way you want it.\r
164 These are available in the <guilabel>View</guilabel> menu and from the\r
165 toolbar.\r
166 <variablelist>\r
167 <varlistentry>\r
168 <term>Group branches</term>\r
169 <listitem>\r
170 <para>\r
171 The default behavior (grouping off) has all rows sorted\r
172 strictly by revision. As a result, long-living branches\r
173 with sparse commits occupy a whole column for only a few\r
174 changes and the graph becomes very broad.\r
175 </para>\r
176 <para>\r
177 This mode groups changes by branch, so that there is no\r
178 global revision ordering: Consecutive revisions on\r
179 a branch will be shown in (often) consecutive lines.\r
180 Sub-branches, however, are arranged in such a way that\r
181 later branches will be shown in the same column above\r
182 earlier branches to keep the graph slim. As a result, a\r
183 given row may contain changes from different revisions.\r
184 </para>\r
185 </listitem>\r
186 </varlistentry>\r
187 <varlistentry>\r
188 <term>Oldest on top</term>\r
189 <listitem>\r
190 <para>\r
191 Normally the graph shows the oldest revision at the bottom,\r
192 and the tree grows upwards. Use this option to grow down\r
193 from the top instead.\r
194 </para>\r
195 </listitem>\r
196 </varlistentry>\r
197 <varlistentry>\r
198 <term>Align trees on top</term>\r
199 <listitem>\r
200 <para>\r
201 When a graph is broken into several smaller trees, the\r
202 trees may appear either in natural revision order, or\r
203 aligned at the bottom of the window, depending on whether\r
204 you are using the <guilabel>Group Branches</guilabel>\r
205 option. Use this option to grow all trees down from the\r
206 top instead.\r
207 </para>\r
208 </listitem>\r
209 </varlistentry>\r
210 <varlistentry>\r
211 <term>Reduce cross lines</term>\r
212 <listitem>\r
213 <para>\r
214 This option is normally enabled and avoids showing\r
215 the graph with a lot of confused crossing lines.\r
216 However this may also make the layout columns appear\r
217 in less logical places, for example in a diagonal line\r
218 rather than a column, and the graph may require a\r
219 larger area to draw. If this is a problem you can disable\r
220 the option from the <guilabel>View</guilabel> menu.\r
221 </para>\r
222 </listitem>\r
223 </varlistentry>\r
224 <varlistentry>\r
225 <term>Differential path names</term>\r
226 <listitem>\r
227 <para>\r
228 Long path names can take a lot of space and make the\r
229 node boxes very large. Use this option to show only\r
230 the changed part of a path, replacing the common part\r
231 with dots. E.g. if you create a branch\r
232 <literal>/branches/1.2.x/doc/html</literal> from\r
233 <literal>/trunk/doc/html</literal> the branch could\r
234 be shown in compact form as\r
235 <literal>/branches/1.2.x/..</literal> because the last\r
236 two levels, <literal>doc</literal> and\r
237 <literal>html</literal>, did not change.\r
238 </para>\r
239 </listitem>\r
240 </varlistentry>\r
241 <varlistentry>\r
242 <term>Show all revisions</term>\r
243 <listitem>\r
244 <para>\r
245 This does just what you expect and shows every revision\r
246 where something (in the tree that you are graphing) has\r
247 changed. For long histories this can produce a truly\r
248 huge graph.\r
249 </para>\r
250 </listitem>\r
251 </varlistentry>\r
252 <varlistentry>\r
253 <term>Show HEAD revisions</term>\r
254 <listitem>\r
255 <para>\r
256 This ensures that the latest revision on every branch is\r
257 always shown on the graph.\r
258 </para>\r
259 </listitem>\r
260 </varlistentry>\r
261 <varlistentry>\r
262 <term>Exact copy sources</term>\r
263 <listitem>\r
264 <para>\r
265 When a branch/tag is made, the default behaviour is to\r
266 show the branch as taken from the last node where a\r
267 change was made. Strictly speaking this is inaccurate\r
268 since the branches are often made from the current HEAD\r
269 rather than a specific revision. So it is possible to show\r
270 the more correct (but less useful) revision that was\r
271 used to create the copy. Note that this revision may\r
272 be younger than the HEAD revision of the source branch.\r
273 </para>\r
274 </listitem>\r
275 </varlistentry>\r
276 <varlistentry>\r
277 <term>Fold tags</term>\r
278 <listitem>\r
279 <para>\r
280 When a project has many tags, showing every tag as a\r
281 separate node on the graph takes a lot of space and\r
282 obscures the more interesting development branch structure.\r
283 At the same time you may need to be able to access the\r
284 tag content easily so that you can compare revisions.\r
285 This option hides the nodes for tags and\r
286 shows them instead in the tooltip for the node that\r
287 they were copied from. A tag icon on the right side\r
288 of the source node indicates that tags were made.\r
289 This greatly simplifies the view.\r
290 </para>\r
291 <para>\r
292 Note that if a tag is itself used as the source for a\r
293 copy, perhaps a new branch based on a tag, then that\r
294 tag will be shown as a separate node rather than folded.\r
295 </para>\r
296 </listitem>\r
297 </varlistentry>\r
298 <varlistentry>\r
299 <term>Hide deleted paths</term>\r
300 <listitem>\r
301 <para>\r
302 Hides paths which are no longer present at the HEAD\r
303 revision of the repository, e.g. deleted branches.\r
304 </para>\r
305 <para>\r
306 If you have selected the <guilabel>Fold tags</guilabel>\r
307 option then a deleted branch from which tags were taken\r
308 will still be shown, otherwise the tags would disappear too.\r
309 The last revision that was tagged will be shown in the\r
310 colour used for deleted nodes instead of showing a separate\r
311 deletion revision.\r
312 </para>\r
313 <para>\r
314 If you select the <guilabel>Hide tags</guilabel> option\r
315 then these branches will disappear again as they are not\r
316 needed to show the tags.\r
317 </para>\r
318 </listitem>\r
319 </varlistentry>\r
320 <varlistentry>\r
321 <term>Hide unused branches</term>\r
322 <listitem>\r
323 <para>\r
324 Hides branches where no changes were committed to the\r
325 respective file or sub-folder. This does not necessarily\r
326 indicate that the branch was not used, just that no\r
327 changes were made to <emphasis>this</emphasis> part of it.\r
328 </para>\r
329 </listitem>\r
330 </varlistentry>\r
331 <varlistentry>\r
332 <term>Show WC revision</term>\r
333 <listitem>\r
334 <para>\r
335 Marks the revision on the graph which corresponds to the\r
336 update revision of the item you fetched the graph for.\r
337 If you have just updated, this will be HEAD, but if others\r
338 have committed changes since your last update your WC\r
339 may be a few revisions lower down.\r
340 The node is marked by giving it a bold outline.\r
341 </para>\r
342 </listitem>\r
343 </varlistentry>\r
344 <varlistentry>\r
345 <term>Show WC modifications</term>\r
346 <listitem>\r
347 <para>\r
348 If your WC contains local changes, this option draws it\r
349 as a separate elliptical node, linked back to the node\r
350 that your WC was last updated to.\r
351 The default outline colour is red.\r
352 You may need to refresh the graph using\r
353 <keycap>F5</keycap> to capture recent changes.\r
354 </para>\r
355 </listitem>\r
356 </varlistentry>\r
357 <varlistentry>\r
358 <term>Filter</term>\r
359 <listitem>\r
360 <para>\r
361 Sometimes the revision graph contains more revisions\r
362 than you want to see. This option opens a dialog which\r
363 allows you to restrict the range of revisions\r
364 displayed, and to hide particular paths by name.\r
365 </para>\r
366 <para>\r
367 If you hide a particular path and that node has child\r
368 nodes, the children will be shown as a separate tree.\r
369 If you want to hide all children as well, use the\r
370 <guilabel>Remove the whole subtree(s)</guilabel> checkbox.\r
371 </para>\r
372 </listitem>\r
373 </varlistentry>\r
374 <varlistentry>\r
375 <term>Tree stripes</term>\r
376 <listitem>\r
377 <para>\r
378 Where the graph contains several trees, it is sometimes\r
379 useful to use alternating colours on the background to\r
380 help distinguish between trees.\r
381 </para>\r
382 </listitem>\r
383 </varlistentry>\r
384 <varlistentry>\r
385 <term>Show overview</term>\r
386 <listitem>\r
387 <para>\r
388 Shows a small picture of the entire graph, with the current\r
389 view window as a rectangle which you can drag. This allows\r
390 you to navigate the graph more easily. Note that for very\r
391 large graphs the overview may become useless due to the\r
392 extreme zoom factor and will therefore not be shown in such\r
393 cases.\r
394 </para>\r
395 </listitem>\r
396 </varlistentry>\r
397 </variablelist>\r
398 </para>\r
399 </sect2>\r
400 -->\r
401 <sect2 id="tsvn-dug-revgraph-use">\r
402 <title>Using the Graph</title>\r
403 <para>\r
404 To make it easier to navigate a large graph, use the overview window.\r
405 This shows the entire graph in a small window, with the currently\r
406 displayed portion highlighted. You can drag the highlighted area to\r
407 change the displayed region.\r
408 </para>\r
409 <para>\r
410 The revision date, author and comments are shown in a hint box whenever\r
411 the mouse hovers over a revision box.\r
412 </para>\r
413 <para>\r
414 If you select two revisions (Use <keycap>Ctrl</keycap>-<action>left click</action>),\r
415 you can use the context menu to show the\r
416 differences between these revisions. You can choose to show differences\r
417 as at the branch creation points, but usually you will want to show the\r
418 differences at the branch end points, i.e. at the HEAD revision.\r
419 </para>\r
420 <para>\r
421 You can view the differences as a Unified-Diff file, which shows all\r
422 differences in a single file with minimal context. If you opt to\r
423 <menuchoice>\r
424 <guimenu>Context Menu</guimenu>\r
425 <guimenuitem>Compare Revisions</guimenuitem>\r
426 </menuchoice>\r
427 you will be presented with a list of changed files.\r
428 <action>Double click</action> on a file name to fetch both revisions\r
429 of the file and compare them using the visual difference tool.\r
430 </para>\r
431 <para>\r
432 If you <action>right click</action> on a revision you can use\r
433 <menuchoice>\r
434 <guimenu>Context Menu</guimenu>\r
435 <guimenuitem>Show Log</guimenuitem>\r
436 </menuchoice>\r
437 to view the history.\r
438 </para>\r
439 <!--\r
440 <para>\r
441 You can also merge changes in the selected revision(s) into a\r
442 different working copy. A folder selection dialog allows you to\r
443 choose the working copy to merge into, but after that there is\r
444 no confirmation dialog, nor any opportunity to try a test merge.\r
445 It is a good idea to merge into an unmodified working copy so\r
446 that you can revert the changes if it doesn't work out!\r
447 This is a useful feature if you want to merge selected\r
448 revisions from one branch to another.\r
449 </para>\r
450 -->\r
451 <!--\r
452 <tip>\r
453 <title>Learn to Read the Revision Graph</title>\r
454 <para>\r
455 First-time users may be surprised by the fact that the revision\r
456 graph shows something that does not match the user's mental model.\r
457 If a revision changes multiple copies or branches of a file or\r
458 folder, for instance, then there will be multiple nodes for that\r
459 single revision. It is a good practice to start with the leftmost\r
460 options in the toolbar and customize the graph step-by-step until\r
461 it comes close to your mental model.\r
462 </para>\r
463 <para>\r
464 All filter options try lose as little information as possible.\r
465 That may cause some nodes to change their color, for instance.\r
466 Whenever the result is unexpected, undo the last filter operation\r
467 and try to understand what is special about that particular revision\r
468 or branch. In most cases, the initially expected outcome of the\r
469 filter operation would either be inaccurate or misleading.\r
470 </para>\r
471 </tip>\r
472 -->\r
473 </sect2>\r
474 <sect2 id="tsvn-dug-revgraph-refresh">\r
475 <title>Refreshing the View</title>\r
476 <para>\r
477 If you want to check the server again for newer information,\r
478 you can simply refresh the view using <keycap>F5</keycap>.\r
479 </para>\r
480 </sect2>\r
481 </sect1>\r