[1977] | 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> |
---|