1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
---|
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
---|
3 | |
---|
4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
---|
5 | <head> |
---|
6 | <meta name="generator" content= |
---|
7 | "HTML Tidy for Linux/x86 (vers 1st December 2004), see www.w3.org" /> |
---|
8 | |
---|
9 | <title>FCM User Guide: Code Management</title> |
---|
10 | <meta name="author" content="FCM development team" /> |
---|
11 | <meta name="descriptions" content="User Guide - Code Management" /> |
---|
12 | <meta name="keywords" content="FCM, user guide" /> |
---|
13 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
---|
14 | <link rel="stylesheet" type="text/css" href="style.css" /> |
---|
15 | <script type="text/javascript" src="fcm.js"> |
---|
16 | </script> |
---|
17 | </head> |
---|
18 | |
---|
19 | <body onload= |
---|
20 | "javascript: FCM.load('doc/user_guide/', null, [['.', 'FCM User Guide']]);"> |
---|
21 | <div id="document-info"> |
---|
22 | <address id="fcm-js-trail"></address> |
---|
23 | |
---|
24 | <address id="fcm-js-maintenance"></address> |
---|
25 | </div> |
---|
26 | |
---|
27 | <h1>Code Management</h1> |
---|
28 | |
---|
29 | <div id="fcm-content"></div> |
---|
30 | |
---|
31 | <h2 id="svn">Using Subversion</h2> |
---|
32 | |
---|
33 | <p>One of the key strengths of Subversion is its documentation. <a href= |
---|
34 | "http://svnbook.red-bean.com/en/1.4/">Version Control with Subversion</a> |
---|
35 | (which we'll just refer to as the <cite>Subversion book</cite> from now on) |
---|
36 | is an excellent book which explains in detail how to use Subversion and also |
---|
37 | provides a good introduction to all the basic concepts of version control. |
---|
38 | Rather than trying to write our own explanations (and not doing as good a |
---|
39 | job) we will simply refer you to the <cite>Subversion book</cite>, where |
---|
40 | appropriate, for the relevant information.</p> |
---|
41 | |
---|
42 | <p>In general, the approach taken in this section is to make sure that you |
---|
43 | first understand how to perform a particular action using the Subversion |
---|
44 | tools and then describe how this differs using FCM.</p> |
---|
45 | |
---|
46 | <h3 id="svn_concepts">Basic Concepts</h3> |
---|
47 | |
---|
48 | <p>In order to use FCM you need to have a basic understanding of version |
---|
49 | control. If you're not already familiar with Subversion or CVS then please |
---|
50 | read the chapter <a href= |
---|
51 | "http://svnbook.red-bean.com/en/1.4/svn.basic.html">Fundamental Concepts</a> |
---|
52 | from the <cite>Subversion book</cite>. In particular, make sure that you |
---|
53 | understand:</p> |
---|
54 | |
---|
55 | <ul> |
---|
56 | <li>The <q title= |
---|
57 | "http://svnbook.red-bean.com/en/1.4/svn.basic.vsn-models.html#svn.basic.vsn-models.copy-merge"> |
---|
58 | Copy-Modify-Merge</q> approach to file sharing.</li> |
---|
59 | |
---|
60 | <li>Global Revision Numbers.</li> |
---|
61 | </ul> |
---|
62 | |
---|
63 | <p>Note that this chapter states that <q title= |
---|
64 | "http://svnbook.red-bean.com/en/1.4/svn.basic.in-action.html#svn.basic.in-action.wc"> |
---|
65 | working copies do not always correspond to any single revision in the |
---|
66 | repository</q>. However, the FCM working practises do not encourage this and |
---|
67 | the wrapper scripts provided by FCM should ensure that your working copy (a |
---|
68 | local copy of the repository's files and directories where you can prepare |
---|
69 | changes) always corresponds to exactly one revision.</p> |
---|
70 | |
---|
71 | <p><acronym title="Concurrent Versions System">CVS</acronym> users should |
---|
72 | already be familiar with all the basic concepts. This is not surprising since |
---|
73 | Subversion was designed as a replacement for CVS and it uses the same |
---|
74 | development model. However, there are some important differences which may |
---|
75 | confuse those more familiar with CVS. Fortunately, the appendix in the |
---|
76 | <cite>Subversion book</cite> <a href= |
---|
77 | "http://svnbook.red-bean.com/en/1.4/svn.forcvs.html">Subversion for CVS |
---|
78 | Users</a> is specifically written for those moving from CVS to Subversion and |
---|
79 | you should read this if you are a CVS user.</p> |
---|
80 | |
---|
81 | <h3 id="svn_basic">Basic Command Line Usage</h3> |
---|
82 | |
---|
83 | <p>Before we discuss the FCM system you need to have a good understanding of |
---|
84 | how to perform most of the normal day-to-day tasks using Subversion. |
---|
85 | Therefore, unless you are already familiar with Subversion, please read the |
---|
86 | chapter <a href="http://svnbook.red-bean.com/en/1.4/svn.tour.html">Basic |
---|
87 | Usage</a> from the <cite>Subversion book</cite>.</p> |
---|
88 | |
---|
89 | <p>So, now you have an understanding of how to do basic tasks using |
---|
90 | Subversion (you did read the <cite>Basic Usage</cite> chapter didn't you?), |
---|
91 | how is using FCM different? Well, the key thing to remember is that, instead |
---|
92 | of using the command <code>svn</code> you need to use the command |
---|
93 | <code>fcm</code>. The advantages of this are as follows:</p> |
---|
94 | |
---|
95 | <ul> |
---|
96 | <li><code>fcm</code> implements all of the commands that <code>svn</code> |
---|
97 | does (including all the command abbreviations).</li> |
---|
98 | |
---|
99 | <li>In some cases <code>fcm</code> does very little and basically passes on |
---|
100 | the command to <code>svn</code>.</li> |
---|
101 | |
---|
102 | <li>In other cases <code>fcm</code> has a lot of additional functionality |
---|
103 | compared with the equivalent <code>svn</code> command.</li> |
---|
104 | |
---|
105 | <li><code>fcm</code> also implements several commands not provided by |
---|
106 | <code>svn</code>.</li> |
---|
107 | |
---|
108 | <li><code>fcm</code> provides support for URL and revision keywords.</li> |
---|
109 | |
---|
110 | <li>Most of the additional features and commands are discussed later in |
---|
111 | this section or in the following sections.</li> |
---|
112 | </ul> |
---|
113 | |
---|
114 | <p>Full details of all the <code>fcm</code> commands available are provided |
---|
115 | in the <a href="command_ref.html">FCM Command Reference</a> section.</p> |
---|
116 | |
---|
117 | <h4 id="svn_basic_keywords">URL & Revision Keywords</h4> |
---|
118 | |
---|
119 | <p>URL keywords can be used to specify URLs in <code>fcm</code> commands. The |
---|
120 | syntax is <code>fcm:<keyword></code>. Keywords can be defined globally |
---|
121 | (see the file <samp>../etc/fcm.cfg</samp> where-ever the <code>fcm</code> |
---|
122 | command has been installed) or individually in a user configuration file |
---|
123 | <samp>$HOME/.fcm</samp>. See the <a href="command_ref.html#fcm_config">FCM |
---|
124 | Command Reference</a> for further details about configuration files.</p> |
---|
125 | |
---|
126 | <p>For example, if you define a keyword in your configuration file as |
---|
127 | follows:</p> |
---|
128 | <pre> |
---|
129 | set::url::fcm svn://fcm1/FCM_svn/FCM |
---|
130 | </pre> |
---|
131 | |
---|
132 | <p>then you can abbreviate the URL as in the following examples:</p> |
---|
133 | <pre> |
---|
134 | # fcm ls svn://fcm1/FCM_svn/FCM |
---|
135 | fcm ls fcm:fcm |
---|
136 | |
---|
137 | # fcm ls svn://fcm1/FCM_svn/FCM/trunk |
---|
138 | fcm ls fcm:fcm_tr # OR: fcm ls fcm:fcm-tr |
---|
139 | |
---|
140 | # fcm ls svn://fcm1/FCM_svn/FCM/branches |
---|
141 | fcm ls fcm:fcm_br # OR: fcm ls fcm:fcm-br |
---|
142 | |
---|
143 | # fcm ls svn://fcm1/FCM_svn/FCM/tags |
---|
144 | fcm ls fcm:fcm_tg # OR: fcm ls fcm:fcm-tg |
---|
145 | </pre> |
---|
146 | |
---|
147 | <p>Using URL keywords has two advantages.</p> |
---|
148 | |
---|
149 | <ul> |
---|
150 | <li>They are shorter and easier to remember.</li> |
---|
151 | |
---|
152 | <li>If the repository needs to be moved then only the keyword definitions |
---|
153 | need to be updated (although any working copies you have will still need to |
---|
154 | be <em>relocated</em> by issuing a <a href= |
---|
155 | "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.switch.html"><code>fcm |
---|
156 | switch --relocate</code></a> command).</li> |
---|
157 | </ul> |
---|
158 | |
---|
159 | <p>In a similar way, revision keywords can be used to specify revision |
---|
160 | numbers in <code>fcm</code> commands. The keyword can be used anywhere a |
---|
161 | revision number can be used. Each keyword is associated with a URL keyword |
---|
162 | and can only be used when referring to that repository.</p> |
---|
163 | |
---|
164 | <p>For example, if you define a keyword in your configuration file as |
---|
165 | follows:</p> |
---|
166 | <pre> |
---|
167 | set::revision::fcm::vn1.0 112 |
---|
168 | </pre> |
---|
169 | |
---|
170 | <p>then the following commands are equivalent:<br /> |
---|
171 | <code>fcm log -r 112 svn://fcm1/FCM_svn/trunk</code><br /> |
---|
172 | <code>fcm log -r vn1.0 fcm:fcm_tr</code></p> |
---|
173 | |
---|
174 | <p>You can use the <code>fcm keyword-print</code> command to print all |
---|
175 | registered URL keywords. You can also print the URL keyword, its implied |
---|
176 | keywords and the revision keywords of a particular project. For example, to |
---|
177 | print the keywords for the <samp>UM</samp> project, you can type <code>fcm |
---|
178 | keyword-print fcm:um</code>.</p> |
---|
179 | |
---|
180 | <h4 id="svn_basic_diff">Examining Changes</h4> |
---|
181 | |
---|
182 | <p>Code differences can be displayed graphically using <code>xxdiff</code> by |
---|
183 | using the <code>--graphical</code> (or <code>-g</code>) option to <code>fcm |
---|
184 | diff</code>. This option can be used in combination with any other options |
---|
185 | which are accepted by <code>svn diff</code>.</p> |
---|
186 | |
---|
187 | <p>An example display from <code>xxdiff</code> is shown below.</p> |
---|
188 | |
---|
189 | <p class="image"><img src="xxdiff1.png" alt="xxdiff 2-way display" /><br /> |
---|
190 | <code>xxdiff</code> 2-way display</p> |
---|
191 | |
---|
192 | <p>Points to note:</p> |
---|
193 | |
---|
194 | <ul> |
---|
195 | <li>By default <code>xxdiff</code> is configured to show horizontal |
---|
196 | differences. This means that the parts of the line which have changed are |
---|
197 | highlighted (e.g. the text <samp>useful</samp> is highlighted in the |
---|
198 | example above).</li> |
---|
199 | |
---|
200 | <li>The number shown to the right of each file name shows the current line |
---|
201 | number. The number on the far right is the number of differences found (2 |
---|
202 | in the example above).</li> |
---|
203 | |
---|
204 | <li>You may find the following keyboard shortcuts useful. |
---|
205 | |
---|
206 | <ul> |
---|
207 | <li><kbd>N</kbd> - move to the next difference</li> |
---|
208 | |
---|
209 | <li><kbd>P</kbd> - move to the previous difference</li> |
---|
210 | |
---|
211 | <li><kbd>Ctrl-Q</kbd> - exit</li> |
---|
212 | </ul> |
---|
213 | </li> |
---|
214 | |
---|
215 | <li>If you want to use another diff tool instead of <code>xxdiff</code> to |
---|
216 | examine changes, you can either set the <var>FCM_GRAPHIC_DIFF</var> |
---|
217 | environment variable or define the <code>set::tool::graphic_diff</code> |
---|
218 | setting in your <samp>$HOME/.fcm</samp> file. For example, to use |
---|
219 | <code>tkdiff</code>, you will do: |
---|
220 | <pre> |
---|
221 | # EITHER: in bash/ksh: |
---|
222 | (SHELL PROMPT)$ export FCM_GRAPHIC_DIFF=tkdiff |
---|
223 | |
---|
224 | # OR: in your $HOME/.fcm: |
---|
225 | set::tool::graphic_diff tkdiff |
---|
226 | </pre> |
---|
227 | </li> |
---|
228 | </ul> |
---|
229 | |
---|
230 | <h4 id="svn_basic_conflicts">Resolving Conflicts</h4> |
---|
231 | |
---|
232 | <p>Your working copy may contain files <em>in conflict</em> as a result of an |
---|
233 | update or a merge (covered later). Conflicts arise from the situation where |
---|
234 | two changes being applied to a file <em>overlap</em>. For conflicts in text |
---|
235 | files, the command <code>fcm conflicts</code> can be used to help resolve |
---|
236 | them. (A discussion on binary files is given in the section <a href= |
---|
237 | "working_practices.html#binary">Working with Binary Files</a> later in this |
---|
238 | document.) The <code>fcm conflicts</code> command calls a graphical merge |
---|
239 | tool (i.e. <code>xxdiff</code> by default) to display a 3-way diff for each |
---|
240 | of the files in conflict.</p> |
---|
241 | |
---|
242 | <p>An example display from <code>xxdiff</code> is shown below.</p> |
---|
243 | |
---|
244 | <p class="image"><img src="xxdiff2.png" alt="xxdiff 3-way display" /><br /> |
---|
245 | <code>xxdiff</code> 3-way display</p> |
---|
246 | |
---|
247 | <p>Points to note:</p> |
---|
248 | |
---|
249 | <ul> |
---|
250 | <li>The file in the middle is the common ancestor from the merge. The file |
---|
251 | on the left is your original file and the file on the right is the file |
---|
252 | containing the changes which you are merging in.</li> |
---|
253 | |
---|
254 | <li><code>xxdiff</code> is configured to automatically select regions that |
---|
255 | would end up being selected by an automatic merge (e.g. there are only |
---|
256 | changes in one of the files). Any difference <em>hunks</em> which cannot be |
---|
257 | resolved automatically are left <em>unselected</em>.</li> |
---|
258 | |
---|
259 | <li>Before you can save a merged version you need to go through each |
---|
260 | unselected difference hunk and decide which text you wish to use. |
---|
261 | |
---|
262 | <ul> |
---|
263 | <li>Selecting a diff hunk can be carried out by clicking on it with the |
---|
264 | left mouse button (or refer to the keyboard shortcuts shown under the |
---|
265 | <kbd>Region</kbd> menu). The colours update to display which side is |
---|
266 | selected for output. You can select individual lines with the middle |
---|
267 | mouse button.</li> |
---|
268 | |
---|
269 | <li>If you want to select more than one side, you have to invoke the |
---|
270 | <kbd>Region->Split/swap/join</kbd> command (keyboard shortcut: |
---|
271 | <kbd>S</kbd>). This will split the current diff hunk so you can select |
---|
272 | the pieces you want from both sides. Further invocations of this |
---|
273 | command will cause swapping of the regions, looping through all the |
---|
274 | different ordering possibilities, and finally joining the regions again |
---|
275 | (preserving selections where it is possible).</li> |
---|
276 | </ul> |
---|
277 | </li> |
---|
278 | |
---|
279 | <li>The number on the far right is the number of unselected difference |
---|
280 | hunks (1 in the example above). Once this number is 0 then you are ready to |
---|
281 | save the merged file.</li> |
---|
282 | |
---|
283 | <li>If you want to see how the merged file will look with the current |
---|
284 | selections then select <kbd>Windows->Toggle Merged View</kbd> (keyboard |
---|
285 | shortcut: <kbd>Alt+Y</kbd>). An extra window then appears showing the |
---|
286 | merged output that updates interactively as you make selections.</li> |
---|
287 | |
---|
288 | <li>You may find the following keyboard shortcuts useful. |
---|
289 | |
---|
290 | <ul> |
---|
291 | <li><kbd>B</kbd> - move to the next unselected hunk</li> |
---|
292 | |
---|
293 | <li><kbd>O</kbd> - move to the previous unselected hunk</li> |
---|
294 | </ul> |
---|
295 | </li> |
---|
296 | |
---|
297 | <li>There are several different ways to exit the 3-way diff (available from |
---|
298 | the <kbd>File</kbd> menu): |
---|
299 | |
---|
300 | <ul> |
---|
301 | <li>Exit with MERGE (keyboard shortcut: <kbd>M</kbd>) - This saves the |
---|
302 | merge result. If there are any unselected difference hunks remaining |
---|
303 | then you will be warned and given the option of saving the file with |
---|
304 | conflict markers.</li> |
---|
305 | |
---|
306 | <li>Exit with ACCEPT (keyboard shortcut: <kbd>A</kbd>) - This saves the |
---|
307 | file you are merging in (i.e. the middle one) as the merge result (i.e. |
---|
308 | you have <em>accepted</em> all the changes).</li> |
---|
309 | |
---|
310 | <li>Exit with REJECT (keyboard shortcut: <kbd>R</kbd>) - This saves the |
---|
311 | original working copy file (i.e. the left one) as the merge result |
---|
312 | (i.e. you have <em>rejected</em> all the changes).</li> |
---|
313 | </ul> |
---|
314 | |
---|
315 | <p>If you just want to exit without making any decisions you can also |
---|
316 | just close the window.</p> |
---|
317 | </li> |
---|
318 | |
---|
319 | <li>For further details please read the <a href= |
---|
320 | "http://furius.ca/xxdiff/doc/xxdiff-doc.html"><code>xxdiff</code> users |
---|
321 | manual</a> (available from the <kbd>Help</kbd> menu). In particular, read |
---|
322 | the section <a href= |
---|
323 | "http://furius.ca/xxdiff/doc/xxdiff-doc.html#merging-files-and-resolving-conflicts"> |
---|
324 | <em>Merging files and resolving conflicts</em></a>.</li> |
---|
325 | </ul> |
---|
326 | |
---|
327 | <p>If you have resolved all the conflicts in a file then you will be prompted |
---|
328 | on whether to run <code>svn resolved</code> on the file to signal that the |
---|
329 | file is no longer in conflict.</p> |
---|
330 | <pre> |
---|
331 | (SHELL PROMPT)$ fcm conflicts |
---|
332 | Conflicts in file: Gen_setup_local1.proc |
---|
333 | You have chosen to ACCEPT all the changes |
---|
334 | Would you like to run "svn resolved"? |
---|
335 | Enter "y" or "n" (or just press <return> for "n"): y |
---|
336 | Resolved conflicted state of 'Gen_setup_local1.proc' |
---|
337 | Conflicts in file: Gen_setup_remote2.proc |
---|
338 | Merge conflicts were not all resolved |
---|
339 | Conflicts in file: Gen_setup_remote3.proc |
---|
340 | All merge conflicts resolved |
---|
341 | Would you like to run "svn resolved"? |
---|
342 | Enter "y" or "n" (or just press <return> for "n"): y |
---|
343 | Resolved conflicted state of 'Gen_setup_remote3.proc' |
---|
344 | </pre> |
---|
345 | |
---|
346 | <p>It is important to realise that there are some types of merge that |
---|
347 | <em>xxdiff</em> will not be able to help you with.</p> |
---|
348 | |
---|
349 | <ul> |
---|
350 | <li>It you have 2 versions of a file, both with substantial changes to the |
---|
351 | same piece of code, then the <code>xxdiff</code> display will be extremely |
---|
352 | colourful and not very helpful.</li> |
---|
353 | |
---|
354 | <li>In these cases it is often easier to start with one version of the file |
---|
355 | and manually re-apply the changes from the other version. It might not be |
---|
356 | obvious how to do this and you may need to speak to the author of the other |
---|
357 | change to agree how this can be done. Fortunately this situation should be |
---|
358 | very rare.</li> |
---|
359 | |
---|
360 | <li>For a more detailed discussion please refer to <a href= |
---|
361 | "http://software.ericsink.com/scm/scm_file_merge.html">Chapter 3: File |
---|
362 | Merge</a> in the online book called <a href= |
---|
363 | "http://software.ericsink.com/scm/source_control.html">Source Control |
---|
364 | HOWTO</a>.</li> |
---|
365 | </ul> |
---|
366 | |
---|
367 | <h4 id="svn_basic_check">Adding and Removing Files</h4> |
---|
368 | |
---|
369 | <p>If your working copy contains files which are not under version control |
---|
370 | then you can use the command <code>fcm add --check</code> to add them. This |
---|
371 | will go through each of the files and prompt to see if you wish to put that |
---|
372 | file under version control using <code>svn add</code>. For each file you can |
---|
373 | enter <kbd>y</kbd> for yes, <kbd>n</kbd> for no or <kbd>a</kbd> to assume yes |
---|
374 | for all following files.</p> |
---|
375 | <pre> |
---|
376 | (SHELL PROMPT)$ fcm add -c |
---|
377 | ? xxdiff1.png |
---|
378 | ? xxdiff2.png |
---|
379 | ? xxdiff3.png |
---|
380 | ? xxdiff4.png |
---|
381 | Add file 'xxdiff1.png'? |
---|
382 | Enter "y", "n" or "a" (or just press <return> for "n"): y |
---|
383 | A xxdiff1.png |
---|
384 | Add file 'xxdiff2.png'? |
---|
385 | Enter "y", "n" or "a" (or just press <return> for "n"): n |
---|
386 | Add file 'xxdiff3.png'? |
---|
387 | Enter "y", "n" or "a" (or just press <return> for "n"): a |
---|
388 | A xxdiff3.png |
---|
389 | A xxdiff4.png |
---|
390 | </pre> |
---|
391 | |
---|
392 | <p>Similarly, if your working copy contains files which are missing (i.e. you |
---|
393 | have deleted them without using <code>svn delete</code>) then you can use the |
---|
394 | command <code>fcm delete --check</code> to delete them. This will go through |
---|
395 | each of the files and prompt to see if you wish to remove that file from |
---|
396 | version control using <code>svn delete</code>.</p> |
---|
397 | |
---|
398 | <p>As noted in the <a href= |
---|
399 | "http://subversion.tigris.org/faq.html#wc-change-detection">Subversion |
---|
400 | FAQ</a>, it can be dangerous using these commands. If you have moved or |
---|
401 | copied a file then simply adding them would cause the history to be lost. |
---|
402 | Therefore take care to only use these commands on files which really are new |
---|
403 | or deleted.</p> |
---|
404 | |
---|
405 | <h4 id="svn_basic_commit">Committing Changes</h4> |
---|
406 | |
---|
407 | <p>The command <code>fcm commit</code> should be used for committing changes |
---|
408 | back to the repository. It differs from the <code>svn commit</code> command |
---|
409 | in a number of important ways:</p> |
---|
410 | |
---|
411 | <ul> |
---|
412 | <li>Your working copy <em>must</em> be up to date. <code>fcm commit</code> |
---|
413 | will abort if it finds that any files are out of date with respect to the |
---|
414 | repository. This ensures that your working copy reflects how the repository |
---|
415 | will be after you have committed your changes. |
---|
416 | |
---|
417 | <ul> |
---|
418 | <li>This helps to ensure that any tests you have done prior to |
---|
419 | committing are valid.</li> |
---|
420 | |
---|
421 | <li><code>fcm commit</code> is not suitable if you need to commit |
---|
422 | changes from a working copy containing mixed revisions. However, you |
---|
423 | are very unlikely to need to do this.</li> |
---|
424 | |
---|
425 | <li>Actually there is a small chance that your working copy might not |
---|
426 | be up to date when you commit if someone else is committing some |
---|
427 | changes at the same time. However, this should very seldom happen and, |
---|
428 | even if it does, the commit would fail if any of the files being |
---|
429 | changed became out of date (i.e. it is not possible to lose any |
---|
430 | changes).</li> |
---|
431 | </ul> |
---|
432 | </li> |
---|
433 | |
---|
434 | <li>If it discovers a file named <samp>#commit_message#</samp> in the top |
---|
435 | level of your working copy it uses this to provide a template commit |
---|
436 | message (which you can then edit). |
---|
437 | |
---|
438 | <ul> |
---|
439 | <li>If you have performed a merge then a message describing the merge |
---|
440 | will have been added to this file. It is important that you leave this |
---|
441 | included in the commit message and do not change its format, as it is |
---|
442 | used by the <code>fcm branch</code> command.</li> |
---|
443 | |
---|
444 | <li>You can, if you wish, add entries to this file as you go along to |
---|
445 | record what changes you have prepared in your working copy. You can |
---|
446 | also use the command <code>fcm commit --dry-run</code> to allow you to |
---|
447 | edit the commit message without committing any changes.</li> |
---|
448 | |
---|
449 | <li><samp>#commit_message#</samp> is ignored by Subversion (so you |
---|
450 | won't see it show up as an unversioned files when you run <code>fcm |
---|
451 | status</code>).</li> |
---|
452 | </ul> |
---|
453 | </li> |
---|
454 | |
---|
455 | <li>It always operates from the top of your working copy. If you issue the |
---|
456 | <code>fcm commit</code> command from a sub-directory of your working copy |
---|
457 | then it will automatically work out the top directory and work from there. |
---|
458 | |
---|
459 | <ul> |
---|
460 | <li>This ensures that any template commit message gets picked up and |
---|
461 | that you do not, for example, accidently commit a partial set of |
---|
462 | changes from a merge.</li> |
---|
463 | </ul> |
---|
464 | </li> |
---|
465 | |
---|
466 | <li>It always commits <em>all</em> the changes in your working copy (it |
---|
467 | does not accept a list of files to commit). |
---|
468 | |
---|
469 | <ul> |
---|
470 | <li>Once again, this avoids any danger of accidently committing a |
---|
471 | partial set of changes.</li> |
---|
472 | |
---|
473 | <li>You should only work on one change within a working copy. If you |
---|
474 | need to prepare another, unrelated change then use a separate working |
---|
475 | copy.</li> |
---|
476 | </ul> |
---|
477 | </li> |
---|
478 | |
---|
479 | <li>It runs <code>svn update</code> after the commit to ensure that your |
---|
480 | working copy is at the latest revision and to avoid any confusion caused by |
---|
481 | your working copy containing mixed revisions.</li> |
---|
482 | </ul> |
---|
483 | <pre> |
---|
484 | (SHELL PROMPT)$ fcm commit |
---|
485 | Starting editor to create commit message ... |
---|
486 | Change summary: |
---|
487 | ------------------------------------------------------------------------ |
---|
488 | [Project: GEN] |
---|
489 | [Branch : branches/test/frsn/r123_foo_bar] |
---|
490 | [Sub-dir: <top>] |
---|
491 | |
---|
492 | M src/code/GenMod_Control/GenMod_Control.f90 |
---|
493 | M src/code/GenMod_Control/Gen_SetupControl.f90 |
---|
494 | ------------------------------------------------------------------------ |
---|
495 | Commit message is as follows: |
---|
496 | ------------------------------------------------------------------------ |
---|
497 | An example commit. |
---|
498 | ------------------------------------------------------------------------ |
---|
499 | Would you like to commit this change? |
---|
500 | Enter "y" or "n" (or just press <return> for "n"): y |
---|
501 | Sending src/code/GenMod_Control/GenMod_Control.f90 |
---|
502 | Sending src/code/GenMod_Control/Gen_SetupControl.f90 |
---|
503 | Transmitting file data .. |
---|
504 | Committed revision 170. |
---|
505 | => svn update |
---|
506 | At revision 170. |
---|
507 | </pre> |
---|
508 | |
---|
509 | <h3 id="svn_branching">Branching & Merging</h3> |
---|
510 | |
---|
511 | <p>Branching is a fundamental concept common to most version control systems. |
---|
512 | For a good introduction please read the chapter <a href= |
---|
513 | "http://svnbook.red-bean.com/en/1.4/svn.branchmerge.html">Branching and |
---|
514 | Merging</a> from the <cite>Subversion book</cite>. Even if you are already |
---|
515 | familiar with branching using other version control systems you should still |
---|
516 | read this chapter to see how branching is implemented in Subversion.</p> |
---|
517 | |
---|
518 | <p>Having read this chapter from the <cite>Subversion book</cite> you should |
---|
519 | understand:</p> |
---|
520 | |
---|
521 | <ul> |
---|
522 | <li>Why each project directory has sub-directories called <em>trunk</em>, |
---|
523 | <em>branches</em> and <em>tags</em>. This structure is assumed by |
---|
524 | <code>fcm</code> (Subversion recommends it but doesn't insist on it).</li> |
---|
525 | |
---|
526 | <li>That when you make a branch you are taking a copy of the entire project |
---|
527 | file tree. Fortunately, the design of the Subversion repository means that |
---|
528 | these copies are <q title= |
---|
529 | "http://svnbook.red-bean.com/en/1.4/svn.branchmerge.using.html#svn.branchmerge.using.create"> |
---|
530 | cheap</q> - they are quick to create and take very little space.</li> |
---|
531 | |
---|
532 | <li>That Subversion doesn't (currently) track merge information for you - |
---|
533 | this has to be done manually.</li> |
---|
534 | |
---|
535 | <li>That each revision of your repository can also be thought of as a |
---|
536 | <em>changeset</em>.</li> |
---|
537 | |
---|
538 | <li>That once a change is committed to a repository it cannot be removed |
---|
539 | (only reversed). Therefore you must take care not to committ a sensitive |
---|
540 | document or a large data file unintentionally.</li> |
---|
541 | </ul> |
---|
542 | |
---|
543 | <p>FCM provides various commands which make working with branches easier (as |
---|
544 | described in the following sections).</p> |
---|
545 | |
---|
546 | <h4 id="svn_branching_create">Creating Branches</h4> |
---|
547 | |
---|
548 | <p>The command <code>fcm branch --create</code> should be used for creating |
---|
549 | new branches. It provides a number of features:</p> |
---|
550 | |
---|
551 | <ul> |
---|
552 | <li>It applies a standard naming convention for branches. The branch name |
---|
553 | is automatically constructed for you depending on the option(s) supplied to |
---|
554 | the command. The full detail of these options are described in the <a href= |
---|
555 | "command_ref.html#fcm_svn_br">FCM Command Reference > fcm branch</a> |
---|
556 | section.</li> |
---|
557 | |
---|
558 | <li>By default, it assumes that you are branching from the last changed |
---|
559 | revision of the <em>trunk</em>. |
---|
560 | |
---|
561 | <ul> |
---|
562 | <li>You can use the <code>--branch-of-branch</code> option if you need |
---|
563 | to create a branch of a branch. A branch of a branch can be useful in |
---|
564 | many situations. For example, consider a shared branch used by several |
---|
565 | members of your team to develop, say, a new science scheme, and you |
---|
566 | have come up with some different ideas of implementing the scheme. You |
---|
567 | may want to create a branch of the shared branch to develop your idea |
---|
568 | before merging it back to the shared branch. Note that you can only |
---|
569 | merge a branch of a branch with it's parent or with another branch |
---|
570 | created from the same parent. You can't, for example, merge it with the |
---|
571 | trunk.</li> |
---|
572 | |
---|
573 | <li>You can use the <code>--revision <rev></code> option if you |
---|
574 | need to create a branch from an earlier revision of the source.</li> |
---|
575 | </ul> |
---|
576 | </li> |
---|
577 | |
---|
578 | <li>Each branch always contains a full copy of the trunk (or its parent |
---|
579 | branch) - you cannot create a branch from a sub-tree. |
---|
580 | |
---|
581 | <ul> |
---|
582 | <li>There would be no reason to only include a sub-tree in a |
---|
583 | branch.</li> |
---|
584 | </ul> |
---|
585 | </li> |
---|
586 | |
---|
587 | <li>It applies a standard commit message which defines how the branch has |
---|
588 | been created. If a Trac ticket is specified using the <code>--ticket |
---|
589 | <number></code> option, it is added to the commit log message. If you |
---|
590 | need to add anything to the commit log message, please do so |
---|
591 | <strong>above</strong> the line that says <samp>--Add your commit message |
---|
592 | ABOVE - do not alter this line or those below--</samp>.</li> |
---|
593 | </ul> |
---|
594 | |
---|
595 | <p>The following is a list of the different types of branches available:</p> |
---|
596 | |
---|
597 | <dl> |
---|
598 | <dt>User development branches</dt> |
---|
599 | |
---|
600 | <dd><samp>branches/dev/<Userid>/<Branch_Name></samp> These are |
---|
601 | for changes which are intended to be merged back to the trunk once they are |
---|
602 | complete. Most branches will belong to this type. e.g. |
---|
603 | branches/dev/frdm/vn6.1_ImprovedDeepConvection, |
---|
604 | branches/dev/frdm/r2134_NewBranchNamingConvention.</dd> |
---|
605 | |
---|
606 | <dt>Shared development branches</dt> |
---|
607 | |
---|
608 | <dd><samp>branches/dev/Share/<Branch_Name></samp></dd> |
---|
609 | |
---|
610 | <dt>User test branches</dt> |
---|
611 | |
---|
612 | <dd><samp>branches/test/<Userid>/<Branch_Name></samp> These are |
---|
613 | for changes which are <em>not</em> intended for the trunk. e.g. Proof of |
---|
614 | concept work, temporary code written for dealing with a one-off problem, |
---|
615 | etc.</dd> |
---|
616 | |
---|
617 | <dt>Shared test branches</dt> |
---|
618 | |
---|
619 | <dd><samp>branches/test/Share/<Branch_Name></samp></dd> |
---|
620 | |
---|
621 | <dt>User packages</dt> |
---|
622 | |
---|
623 | <dd><samp>branches/pkg/<Userid>/<Branch_Name></samp> These are |
---|
624 | branches which combine together a number of different development branches. |
---|
625 | Sometimes this will simply be for testing purposes (i.e. for testing a |
---|
626 | branch in combination with other branches). Other times it may be the |
---|
627 | package which eventually gets merged to the trunk (rather than the |
---|
628 | development branches). e.g. |
---|
629 | branches/pkg/frdm/vn6.1_TestImprovedDeepConvection</dd> |
---|
630 | |
---|
631 | <dt>Shared packages</dt> |
---|
632 | |
---|
633 | <dd><samp>branches/pkg/Share/<Branch_Name></samp> E.g. |
---|
634 | branches/pkg/Share/vn6.1_NewConvectionScheme.</dd> |
---|
635 | |
---|
636 | <dt>Configurations</dt> |
---|
637 | |
---|
638 | <dd><samp>branches/pkg/Config/<Branch_Name></samp> These are major |
---|
639 | packages which combine together a number of different packages and |
---|
640 | development branches. e.g. branches/pkg/Config/vn6.1_HadGEM1a.</dd> |
---|
641 | |
---|
642 | <dt>Releases</dt> |
---|
643 | |
---|
644 | <dd><samp>branches/pkg/Rel/<Branch_Name></samp> These may be bug-fix |
---|
645 | branches for system releases, if required. They can also be branches on |
---|
646 | which stable releases are prepared if you don't do this on the trunk |
---|
647 | (although you lose the ability to branch from stable releases if you work |
---|
648 | this way). e.g. branches/pkg/Rel/vn6.1_BugFixes.</dd> |
---|
649 | </dl> |
---|
650 | <pre> |
---|
651 | (SHELL PROMPT)$ fcm br -c -n my_test_branch -k 23 fcm:test |
---|
652 | Starting nedit to create commit message ... |
---|
653 | Change summary: |
---|
654 | ------------------------------------------------------------------------ |
---|
655 | A svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch |
---|
656 | ------------------------------------------------------------------------ |
---|
657 | Commit message is as follows: |
---|
658 | ------------------------------------------------------------------------ |
---|
659 | Create an example branch to demonstrate branch creation for the user guide. |
---|
660 | Created /OPS/branches/dev/frsn/r118_my_test_branch from /OPS/trunk@118. |
---|
661 | Relates to ticket #23. |
---|
662 | ------------------------------------------------------------------------ |
---|
663 | Would you like to go ahead and create this branch? |
---|
664 | Enter "y" or "n" (or just press <return> for "n"): y |
---|
665 | Creating branch svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch ... |
---|
666 | |
---|
667 | Committed revision 169. |
---|
668 | </pre> |
---|
669 | |
---|
670 | <h4 id="svn_branching_list">Listing Branches Created by You or Other |
---|
671 | Users</h4> |
---|
672 | |
---|
673 | <p>The command <code>fcm branch --list</code> can be used to list the |
---|
674 | branches you have created at the HEAD of a repository. If you specify the |
---|
675 | <code>--user <userid></code> option, the branches created by |
---|
676 | <userid> are listed instead. You can specify multiple users with |
---|
677 | multiple <code>--user <userid></code> options, or with a colon (:) |
---|
678 | separated list to a single <code>--user <userid:list></code> option. |
---|
679 | Note that you can also list shared branches by specifying <userid> as |
---|
680 | <code>Share</code>, configuration branches by specifying <userid> as |
---|
681 | <code>Config</code> and release branches by specifying <userid> as |
---|
682 | <code>Rel</code>. The command returns 0 (success) if one or more branches is |
---|
683 | found for the specified users, or 1 (failure) if no branch is found.</p> |
---|
684 | <pre> |
---|
685 | (SHELL PROMPT)$ fcm branch --list fcm:gen |
---|
686 | 1 branch found for frsn in svn://fcm1/GEN_svn/GEN |
---|
687 | fcm:GEN-br/dev/frsn/r1191_clean_up/ |
---|
688 | (SHELL PROMPT)$ echo $? |
---|
689 | 0 |
---|
690 | (SHELL PROMPT)$ fcm branch --list --user frbj --user frsn fcm:gen |
---|
691 | 2 branches found for frbj, frsn in svn://fcm1/GEN_svn/GEN |
---|
692 | fcm:GEN-br/dev/frbj/r1177_gen_ui_for_scs/ |
---|
693 | fcm:GEN-br/dev/frsn/r1191_clean_up/ |
---|
694 | (SHELL PROMPT)$ echo $? |
---|
695 | 0 |
---|
696 | (SHELL PROMPT)$ fcm branch --list --user frva fcm:gen |
---|
697 | 0 branch found for frva in svn://fcm1/GEN_svn/GEN |
---|
698 | (SHELL PROMPT)$ echo $? |
---|
699 | 1 |
---|
700 | </pre> |
---|
701 | |
---|
702 | <h4 id="svn_branching_info">Getting Information About Branches</h4> |
---|
703 | |
---|
704 | <p>The command <code>fcm branch --info</code> can be used to get various |
---|
705 | information about a branch. In particular, it summarises information about |
---|
706 | merges to and from the branch and its parent.</p> |
---|
707 | <pre> |
---|
708 | (SHELL PROMPT)$ fcm branch --info |
---|
709 | URL: svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r1346_merge |
---|
710 | Repository Root: svn://fcm1/FCM_svn |
---|
711 | Revision: 1385 |
---|
712 | Last Changed Author: frsn |
---|
713 | Last Changed Rev: 1385 |
---|
714 | Last Changed Date: 2006-04-20 11:08:45 +0100 (Thu, 20 Apr 2006) |
---|
715 | -------------------------------------------------------------------------------- |
---|
716 | Branch Create Author: frsn |
---|
717 | Branch Create Rev: 1354 |
---|
718 | Branch Create Date: 2006-04-04 14:27:47 +0100 (Tue, 04 Apr 2006) |
---|
719 | Branch Parent: svn://fcm1/FCM_svn/FCM/trunk@1346 |
---|
720 | Last Merge From Parent, Revision: 1444 |
---|
721 | Last Merge From Parent, Delta: /FCM/trunk@1439 cf. /FCM/trunk@1395 |
---|
722 | Merges Avail From Parent: 1445 |
---|
723 | Merges Avail Into Parent: 1453 1452 1449 1446 1444 1443 1441 1434 1397 1396 ... |
---|
724 | </pre> |
---|
725 | |
---|
726 | <p>If you need information on the current children of the branch, use the |
---|
727 | <code>--show-children</code> option of the <code>fcm branch --info</code> |
---|
728 | command. If you need information on recent merges to and from the branch and |
---|
729 | its siblings, use the <code>--show-siblings</code> option of the <code>fcm |
---|
730 | branch --info</code> command.</p> |
---|
731 | |
---|
732 | <p>To find out what changes have been made on a branch relative to its parent |
---|
733 | you can use the command <code>fcm diff --branch</code>.</p> |
---|
734 | |
---|
735 | <ul> |
---|
736 | <li>You can combine this with the options: |
---|
737 | |
---|
738 | <dl> |
---|
739 | <dt><code>--graphical</code></dt> |
---|
740 | |
---|
741 | <dd>to display the differences using a graphical <em>diff</em> |
---|
742 | tool</dd> |
---|
743 | |
---|
744 | <dt><code>--trac</code></dt> |
---|
745 | |
---|
746 | <dd>to display the differences using Trac</dd> |
---|
747 | |
---|
748 | <dt><code>--wiki</code></dt> |
---|
749 | |
---|
750 | <dd>to print a wiki syntax suitable for inserting into Trac</dd> |
---|
751 | </dl> |
---|
752 | </li> |
---|
753 | |
---|
754 | <li>The base of the difference is adjusted to account for any merges from |
---|
755 | the branch to its parent or vice-versa.</li> |
---|
756 | </ul> |
---|
757 | |
---|
758 | <h4 id="svn_branching_switch">Switching your working copy to point to another |
---|
759 | branch</h4> |
---|
760 | |
---|
761 | <p>The command <code>fcm switch</code> can be used to switch your working |
---|
762 | copy to point to another branch. For example, if you have a working copy at |
---|
763 | <samp>$HOME/work</samp>, currently pointing to the trunk or a branch of a |
---|
764 | project at <samp>svn://fcm1/FCM_svn/FCM/trunk</samp>, you can switch the |
---|
765 | working copy to point to another branch of same project:</p> |
---|
766 | <pre> |
---|
767 | (Shell prompt)$ cd $HOME/work |
---|
768 | (Shell prompt)$ fcm sw dev/frsn/r959_blockdata |
---|
769 | -> svn switch --revision HEAD svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r959_blockdata |
---|
770 | U doc/user_guide/getting_started.html |
---|
771 | U doc/user_guide/code_management.html |
---|
772 | U doc/user_guide/command_ref.html |
---|
773 | U src/lib/Fcm/SrcFile.pm |
---|
774 | U src/lib/Fcm/Util.pm |
---|
775 | U src/lib/Fcm/Build.pm |
---|
776 | U src/lib/Fcm/Cm.pm |
---|
777 | U src/lib/Fcm/SrcPackage.pm |
---|
778 | U src/bin/fcm_internal |
---|
779 | U src/bin/fcm_gui |
---|
780 | Updated to revision 1009. |
---|
781 | </pre> |
---|
782 | |
---|
783 | <p>Unlike <code>svn switch</code>, <code>fcm switch</code> does extra |
---|
784 | checking to ensure that your whole working copy is switched to the new branch |
---|
785 | at the correct level of sub-directory. In addition, you can specify only the |
---|
786 | <em>branch</em> part of the URL, such as <samp>trunk</samp>, |
---|
787 | <samp>branches/dev/fred/r1234_bob</samp> or even |
---|
788 | <samp>dev/fred/r1234_bob</samp> and the command will work out the full URL |
---|
789 | for you.</p> |
---|
790 | |
---|
791 | <h4 id="svn_branching_delete">Deleting Branches</h4> |
---|
792 | |
---|
793 | <p>The command <code>fcm branch --delete</code> can be used to delete |
---|
794 | branches which are no longer required. Before being asked to confirm that you |
---|
795 | want to delete the branch, you will first see the same output as from |
---|
796 | <code>fcm branch --info</code>. This allows you to check, for example, |
---|
797 | whether your branch is being used anywhere else or whether the latest changes |
---|
798 | on your branch have been merged to the trunk. You will be prompted to edit |
---|
799 | your commit log message. If you need to add anything to the commit log |
---|
800 | message, please do so <strong>above</strong> the line that says <samp>--Add |
---|
801 | your commit message ABOVE - do not alter this line or those below--</samp>. |
---|
802 | </p> |
---|
803 | |
---|
804 | <h4 id="svn_branching_merge">Merging</h4> |
---|
805 | |
---|
806 | <p>As mentioned earlier, Subversion doesn't track merge information |
---|
807 | (although, in the longer term, there are plans to add this feature). However, |
---|
808 | <code>fcm</code> <em>does</em> track a limited amount of merge information. |
---|
809 | It does this by making a number of assumptions:</p> |
---|
810 | |
---|
811 | <ul> |
---|
812 | <li>That all merges are performed using FCM and are identified using a |
---|
813 | standard template in the commit log message.</li> |
---|
814 | |
---|
815 | <li>That you only ever merge all the changes available on the source branch |
---|
816 | up to a chosen point (i.e. you can't only include a subset of the changes |
---|
817 | made to the branch).</li> |
---|
818 | |
---|
819 | <li>That the source and target are both branches (or the trunk) in the same |
---|
820 | FCM project.</li> |
---|
821 | |
---|
822 | <li>That the source and target are directly related, i.e. they must either |
---|
823 | have a parent/child relationship or they are siblings from the same parent |
---|
824 | branch.</li> |
---|
825 | </ul> |
---|
826 | |
---|
827 | <p>Note that the term <em>source branch</em> and <em>target branch</em> |
---|
828 | referred to above can also mean the trunk.</p> |
---|
829 | |
---|
830 | <p>To perform a merge, use the command <code>fcm merge <source></code>. |
---|
831 | This includes a number of important features:</p> |
---|
832 | |
---|
833 | <ul> |
---|
834 | <li>If it finds any local modifications in your working copy then it checks |
---|
835 | whether you wish to continue (in most cases you won't want to mix a merge |
---|
836 | with other changes).</li> |
---|
837 | |
---|
838 | <li>It determines the base revision and path of the <em>common |
---|
839 | ancestor</em> to be used for the merge, taking into account any merges from |
---|
840 | the <em>source</em> to the <em>target</em> or vice-versa.</li> |
---|
841 | |
---|
842 | <li>Before doing the merge, (unless you specify the |
---|
843 | <code>--non-interactive</code> option), it reports what changes will result |
---|
844 | from performing the merge and checks that you wish to continue.</li> |
---|
845 | |
---|
846 | <li>It adds details of the merge, using a standard template, into the |
---|
847 | commit message file (<samp>#commit_message#</samp>). If you need to add any |
---|
848 | extra comment, you should do so <strong>above</strong> the line that says |
---|
849 | <samp>--Add your commit message ABOVE - do not alter this line or those |
---|
850 | below--</samp>. |
---|
851 | |
---|
852 | <ul> |
---|
853 | <li>If you decide to revert the merge, you should remove the template |
---|
854 | line manually from the commit message file, making sure that you do not |
---|
855 | alter the standard template by accident.</li> |
---|
856 | </ul> |
---|
857 | </li> |
---|
858 | </ul> |
---|
859 | <pre> |
---|
860 | (SHELL PROMPT)$ fcm merge trunk # merge changes from the trunk into the branch |
---|
861 | Available Merges From /FCM/trunk: 1383 1375 |
---|
862 | Please enter the revision you wish to merge from |
---|
863 | (or just press <return> for "1383"): |
---|
864 | About to merge in changes from /FCM/trunk@1383 compared with /FCM/trunk@1371 |
---|
865 | This merge will result in the following changes: |
---|
866 | -------------------------------------------------------------------------------- |
---|
867 | A doc/standards/fortran_standard.html |
---|
868 | U src/lib/Fcm/ReposBranch.pm |
---|
869 | -------------------------------------------------------------------------------- |
---|
870 | Would you like to go ahead with the merge? |
---|
871 | Enter "y" or "n" (or just press <return> for "n"): y |
---|
872 | Performing merge ... |
---|
873 | A doc/standards/fortran_standard.html |
---|
874 | U src/lib/Fcm/ReposBranch.pm |
---|
875 | </pre> |
---|
876 | |
---|
877 | <h3 id="svn_gui">Using the GUI</h3> |
---|
878 | |
---|
879 | <p>So far, all the tools described have been command line tools. Many people |
---|
880 | will be happy with these but, for those who prefer it, there is also a simple |
---|
881 | Graphical User Interface (GUI).</p> |
---|
882 | |
---|
883 | <h4 id="svn_gui_start">Starting the GUI</h4> |
---|
884 | |
---|
885 | <p>To run the GUI simply issue the command <code>fcm gui</code> from the |
---|
886 | directory you want as your working directory. You can also start the GUI from |
---|
887 | within Konqueror (see <a href="#svn_gui_konqueror">Accessing the GUI from |
---|
888 | Konqueror</a>).</p> |
---|
889 | |
---|
890 | <p>The GUI consists of several sections:</p> |
---|
891 | |
---|
892 | <ul> |
---|
893 | <li>The top section contains a row of buttons to allow you to select which |
---|
894 | command you want to run.</li> |
---|
895 | |
---|
896 | <li>Beneath this is shown the current working directory and the top level |
---|
897 | directory of your working copy (these may be the same).</li> |
---|
898 | |
---|
899 | <li>Beneath this come various buttons and entry boxes to allow you to |
---|
900 | configure the command you have selected. These vary according to the |
---|
901 | command.</li> |
---|
902 | |
---|
903 | <li>Beneath this comes a further row of buttons |
---|
904 | |
---|
905 | <ul> |
---|
906 | <li><em>Quit</em> - this exits the GUI.</li> |
---|
907 | |
---|
908 | <li><em>Help</em> - this displays the help message for the selected |
---|
909 | command.</li> |
---|
910 | |
---|
911 | <li><em>Clear</em> - this empties the text window.</li> |
---|
912 | |
---|
913 | <li><em>Run</em> - this allows you to run your command.</li> |
---|
914 | </ul> |
---|
915 | </li> |
---|
916 | |
---|
917 | <li>Beneath this comes a scrolling text window where the output from the |
---|
918 | commands is displayed.</li> |
---|
919 | |
---|
920 | <li>The bottom section displays help information when you position the |
---|
921 | cursor over various parts of the GUI.</li> |
---|
922 | </ul> |
---|
923 | |
---|
924 | <p class="image"><img src="gui1.png" alt= |
---|
925 | "Example GUI screen with the Status commands selected" /><br /> |
---|
926 | Example GUI screen with the <kbd>Status</kbd> commands selected</p> |
---|
927 | |
---|
928 | <p>If you run a more complicated command, like <code>fcm branch</code>, which |
---|
929 | prompts for input then extra entry windows will pop up.</p> |
---|
930 | |
---|
931 | <p class="image"><img src="gui2.png" alt="Example GUI pop-up window" /><br /> |
---|
932 | Example GUI pop-up window</p> |
---|
933 | |
---|
934 | <h4 id="svn_gui_commands">GUI Commands</h4> |
---|
935 | |
---|
936 | <p>The commands available from the GUI should be self explanatory. A few |
---|
937 | points to note:</p> |
---|
938 | |
---|
939 | <ul> |
---|
940 | <li>If the current directory is not a working copy, you will only be able |
---|
941 | to Checkout a working copy or create a branch from the GUI.</li> |
---|
942 | |
---|
943 | <li>The <kbd>Checkout</kbd> command is only available if you start the GUI |
---|
944 | in a directory which is not already a working copy. After successfully |
---|
945 | running a checkout the GUI automatically sets the working directory to the |
---|
946 | top of this new working copy.</li> |
---|
947 | |
---|
948 | <li>With some commands (Status, Diff, Add, Delete, Conflicts) you can |
---|
949 | choose whether to run from the top level of your working copy or from your |
---|
950 | working directory. With the remaining commands this would not make sense |
---|
951 | and they can only be run from the top level.</li> |
---|
952 | |
---|
953 | <li>You can only issue commands from the GUI if they do not need to prompt |
---|
954 | you for authentication (i.e. the Subversion command can be run with the |
---|
955 | <code>--non-interactive</code> option). |
---|
956 | |
---|
957 | <ul> |
---|
958 | <li>If authentication is required then the command issued by the GUI |
---|
959 | will fail. For the <code>branch --create</code>, <code>branch |
---|
960 | --delete</code> and <code>commit</code> commands, which support the |
---|
961 | <code>--password</code> option, you should specify your password in |
---|
962 | <kbd>Other options</kbd> and click <kbd>Run</kbd> again. For other |
---|
963 | commands, you should run the command in interactive mode on the command |
---|
964 | line. Use the command displayed in the GUI text window but remove the |
---|
965 | <code>--non-interactive</code> option.</li> |
---|
966 | |
---|
967 | <li>Most repositories will be configured so that you only need |
---|
968 | authentication for writing (not reading). Therefore, the first command |
---|
969 | requiring authentication will probably be creating a branch or |
---|
970 | commiting to the trunk.</li> |
---|
971 | |
---|
972 | <li>You should only need to do this the first time you ever issue such |
---|
973 | a command on a each repository (unless the repository is moved to a new |
---|
974 | location) since the Subversion client caches this information for |
---|
975 | future comamnds .</li> |
---|
976 | </ul> |
---|
977 | </li> |
---|
978 | </ul> |
---|
979 | |
---|
980 | <h4 id="svn_gui_konqueror">Accessing the GUI from Konqueror</h4> |
---|
981 | |
---|
982 | <p>To enable access from Konqueror run the script |
---|
983 | <code>fcm_setup_konqueror</code>. You can then use the Konqueror file manager |
---|
984 | to select the directory which you want as your working directory. To run the |
---|
985 | GUI click the right mouse button and select <kbd>Open With => FCM |
---|
986 | GUI</kbd>.</p> |
---|
987 | |
---|
988 | <ul> |
---|
989 | <li>Make sure that your current selection is the directory and not a file |
---|
990 | within that directory.</li> |
---|
991 | </ul> |
---|
992 | |
---|
993 | <p class="image"><img src="konqueror.png" alt= |
---|
994 | "Running the GUI from within Konqueror" /><br /> |
---|
995 | Running the GUI from within Konqueror</p> |
---|
996 | |
---|
997 | <h3 id="svn_problems">Known Problems with Subversion</h3> |
---|
998 | |
---|
999 | <p>There are some limitations with Subversion v1.3 which you should be aware |
---|
1000 | of:</p> |
---|
1001 | |
---|
1002 | <ul> |
---|
1003 | <li>The <code>svn rename</code> command is not a true rename/move |
---|
1004 | operation, but is implemented as a copy and delete. As a result, if you |
---|
1005 | rename an item in a branch, and later attempt to merge it back to the |
---|
1006 | trunk, the operation may not be handled correctly by <code>svn merge</code> |
---|
1007 | (see <a href= |
---|
1008 | "http://subversion.tigris.org/issues/show_bug.cgi?id=898">subversion issue |
---|
1009 | 898</a> for further details). Support for a <q title= |
---|
1010 | "http://subversion.tigris.org/issues/show_bug.cgi?id=898">true rename</q> |
---|
1011 | will hopefully be available in Subversion in the near future. Until this is |
---|
1012 | implemented, you should avoid renaming of files or directories unless you |
---|
1013 | can ensure that no-one is working in parallel on the affected areas of the |
---|
1014 | project.</li> |
---|
1015 | </ul> |
---|
1016 | |
---|
1017 | <h2 id="trac">Using Trac</h2> |
---|
1018 | |
---|
1019 | <p><cite>Trac</cite> has a simple and intuitive web interface which is |
---|
1020 | relatively easy to pick up. It also includes a <a href= |
---|
1021 | "http://trac.edgewall.org/wiki/TracGuide">User and Administration Guide</a> |
---|
1022 | which is full of helpful information (and is referred to extensively in this |
---|
1023 | section).</p> |
---|
1024 | |
---|
1025 | <p>Trac contains a menu bar at the top of each page (which we will refer to |
---|
1026 | as the <cite>Trac menu</cite>). This provides access to all the main |
---|
1027 | features.</p> |
---|
1028 | |
---|
1029 | <h3 id="trac_login">Logging In</h3> |
---|
1030 | |
---|
1031 | <p>Although different projects may choose their own rules, we expect that |
---|
1032 | most systems will have Trac configured so that all the information is |
---|
1033 | viewable by anyone. However, in order to make any changes you will need to |
---|
1034 | login. This ensures that any changes are identified with the appropriate |
---|
1035 | userid.</p> |
---|
1036 | |
---|
1037 | <p>In the rest of this section it is assumed that you have logged in to Trac |
---|
1038 | and are therefore able to make changes.</p> |
---|
1039 | |
---|
1040 | <p>If you haven't yet got a Trac userid (which should be the same as the |
---|
1041 | userid you use for committing changes to Subversion) then please contact your |
---|
1042 | system manager.</p> |
---|
1043 | |
---|
1044 | <h3 id="trac_wiki">Using the Wiki Pages</h3> |
---|
1045 | |
---|
1046 | <p>A wiki enables documents to be written in a simple markup language using a |
---|
1047 | web browser. See the Trac Guide for information on the <a href= |
---|
1048 | "http://trac.edgewall.org/wiki/TracWiki">Trac Wiki Engine</a>. Make sure that |
---|
1049 | you read the information provided on:</p> |
---|
1050 | |
---|
1051 | <ul> |
---|
1052 | <li><a href="http://trac.edgewall.org/wiki/WikiFormatting">Wiki |
---|
1053 | Formatting</a> which explains how to format your wiki pages.</li> |
---|
1054 | |
---|
1055 | <li><a href="http://trac.edgewall.org/wiki/WikiPageNames">Wiki Page |
---|
1056 | Names</a> which explains how <em>CamelCase</em> is used to create <a href= |
---|
1057 | "http://trac.edgewall.org/wiki/WikiNewPage">New Wiki Pages</a>.</li> |
---|
1058 | |
---|
1059 | <li><a href="http://trac.edgewall.org/wiki/TracLinks">Trac Links</a> which |
---|
1060 | allow hyperlinking between Trac entities (tickets, reports, changesets, |
---|
1061 | Wiki pages, milestones and source files). This is a fundamental feature of |
---|
1062 | Trac which makes it easy, for example, to link a bug report (ticket) to the |
---|
1063 | changeset which fixed the bug (and vice-versa).</li> |
---|
1064 | </ul> |
---|
1065 | |
---|
1066 | <p>Whenever you are viewing a wiki page in Trac you should see several |
---|
1067 | buttons at the bottom of the page:</p> |
---|
1068 | |
---|
1069 | <ul> |
---|
1070 | <li><kbd>Edit This Page</kbd> - Clicking this will bring up a page where |
---|
1071 | you can edit the page contents. Before saving your changes you can preview |
---|
1072 | how the modified page will appear. You can also leave a comment explaining |
---|
1073 | what changes you made.</li> |
---|
1074 | |
---|
1075 | <li><kbd>Attach File</kbd> - Allows you to attach files to a page, e.g. an |
---|
1076 | image.</li> |
---|
1077 | |
---|
1078 | <li>If you have admin rights then you will also see |
---|
1079 | |
---|
1080 | <ul> |
---|
1081 | <li><kbd>Delete This Version</kbd> - Delete the particular version of |
---|
1082 | the page you are viewing.</li> |
---|
1083 | |
---|
1084 | <li><kbd>Delete Page</kbd> - Delete the page and all its history.</li> |
---|
1085 | </ul>Use with care - these operations are irreversible! |
---|
1086 | </li> |
---|
1087 | </ul> |
---|
1088 | |
---|
1089 | <p>At the top of each wiki page at the right hand side you can select |
---|
1090 | <kbd>Page History</kbd>. This shows you the full history of each page with |
---|
1091 | details of when each change was made, who made the change and what the |
---|
1092 | changes were.</p> |
---|
1093 | |
---|
1094 | <h3 id="trac_browser">Using the Repository Browser</h3> |
---|
1095 | |
---|
1096 | <p>The <a href="http://trac.edgewall.org/wiki/TracBrowser">Trac Browser</a> |
---|
1097 | is used to view the contents of your repository. To get to it just select |
---|
1098 | <kbd>Browse Source</kbd> from the Trac menu. You can view directories and |
---|
1099 | files at any version, see their revision histories and view <a href= |
---|
1100 | "http://trac.edgewall.org/wiki/TracChangeset">changesets</a>. Any wiki |
---|
1101 | formatting in log messages is recognised and interpreted so you can easily |
---|
1102 | link a changeset to a Trac ticket by using <a href= |
---|
1103 | "http://trac.edgewall.org/wiki/TracLinks">Trac Links</a>.</p> |
---|
1104 | |
---|
1105 | <h3 id="trac_tickets">Using the Issue Tracker</h3> |
---|
1106 | |
---|
1107 | <p>The Trac issue database provides a way of tracking issues within a project |
---|
1108 | (e.g. bug reports, feature requests, software support issues, project tasks). |
---|
1109 | Within Trac an issue is often referred to as a <em>Ticket</em>.</p> |
---|
1110 | |
---|
1111 | <p>Please refer to the Trac Guide for the following information:</p> |
---|
1112 | |
---|
1113 | <ul> |
---|
1114 | <li> |
---|
1115 | <a href="http://trac.edgewall.org/wiki/TracTickets">The Trac Ticket |
---|
1116 | System</a> - Creating and modifying tickets. |
---|
1117 | |
---|
1118 | <ul> |
---|
1119 | <li>Only Trac accounts with admin rights can modify ticket |
---|
1120 | descriptions.</li> |
---|
1121 | </ul> |
---|
1122 | </li> |
---|
1123 | |
---|
1124 | <li><a href="http://trac.edgewall.org/wiki/TracQuery">Trac Ticket |
---|
1125 | Queries</a> - List tickets matching your chosen criterion.</li> |
---|
1126 | </ul> |
---|
1127 | |
---|
1128 | <h3 id="trac_roadmap">Using the Roadmap</h3> |
---|
1129 | |
---|
1130 | <p>Each ticket can be assigned to a milestone. The Trac Roadmap can then be |
---|
1131 | used to provide a view on the ticket system. This can useful to see what |
---|
1132 | changes went into a particular system release or what changes are outstanding |
---|
1133 | before a milestone can be reached.</p> |
---|
1134 | |
---|
1135 | <p>Please refer to the Trac Guide for further information on the <a href= |
---|
1136 | "http://trac.edgewall.org/wiki/TracRoadmap">Trac Roadmap</a>.</p> |
---|
1137 | |
---|
1138 | <ul> |
---|
1139 | <li>Only Trac accounts with admin rights can add, modify and remove |
---|
1140 | milestones using the web interface.</li> |
---|
1141 | </ul> |
---|
1142 | |
---|
1143 | <h3 id="trac_timeline">Using the Timeline</h3> |
---|
1144 | |
---|
1145 | <p>The <a href="http://trac.edgewall.org/wiki/TracTimeline">Trac Timeline</a> |
---|
1146 | allows you to list all the acitivity on a project over any given period. It |
---|
1147 | can list:</p> |
---|
1148 | |
---|
1149 | <ul> |
---|
1150 | <li>Creation and changes to wiki pages.</li> |
---|
1151 | |
---|
1152 | <li>Creation, closure and changes to tickets.</li> |
---|
1153 | |
---|
1154 | <li>Commits to the Subversion repository.</li> |
---|
1155 | |
---|
1156 | <li>Milestones reached.</li> |
---|
1157 | </ul> |
---|
1158 | </body> |
---|
1159 | </html> |
---|