New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
command_ref.html in vendors/fcm/current/doc/user_guide – NEMO

source: vendors/fcm/current/doc/user_guide/command_ref.html @ 1980

Last change on this file since 1980 was 1980, checked in by flavoni, 14 years ago

importing fcm vendor
File size: 62.3 KB
Line 
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: FCM Command Reference</title>
10  <meta name="author" content="FCM development team" />
11  <meta name="descriptions" content="User Guide - FCM Command Reference" />
12  <meta name="keywords" content="FCM, user guide, command reference" />
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>FCM Command Reference</h1>
28
29  <div id="fcm-content"></div>
30
31  <h2 id="fcm_config">fcm Configuration File</h2>
32
33  <p>The FCM system uses simple line based text files to store configuration
34  settings. All configuration files used by FCM are based on the same
35  principles:</p>
36
37  <ul>
38    <li>All configurations are stored in plain text files.</li>
39
40    <li>A line in a file may contain a configuration setting or a comment.</li>
41
42    <li>Blank lines are ignored.</li>
43
44    <li>A line that begins with a <code>#</code> is a <dfn>comment</dfn>
45    line.</li>
46
47    <li>Each configuration line has a <dfn>label</dfn>, a <dfn>value</dfn> and
48    optionally a trailing <dfn>comment</dfn>. For example:
49      <pre>
50my::label  this is the value  # some comment
51</pre>
52    </li>
53
54    <li>A <dfn>label</dfn> in a configuration line may contain any non-space
55    character. A space character marks the end of the <dfn>label</dfn>.</li>
56
57    <li>Words or fields in the <dfn>label</dfn> are delimited by a double colon
58    <code>::</code> or slash <code>/</code>. To improve readability, the
59    convention is to only use slash as the delimiter when referring to package
60    names.</li>
61
62    <li>The first non-space character after the <dfn>label</dfn> is the
63    beginning of the <dfn>value</dfn>. The <dfn>value</dfn> may contain space
64    characters. The newline character or the character sequence <code>" #
65    "</code> marks the end of the <dfn>value</dfn>.</li>
66
67    <li>The first non-space character after the character sequence <code>" #
68    "</code> at the end of the <dfn>value</dfn> is the <dfn>comment</dfn>. The
69    <dfn>comment</dfn> is normally ignored by the parser of the configuration
70    file.</li>
71
72    <li>If it is indicated in the documentation that a declaration is expecting
73    a <code>true</code> or <code>false</code> value, the following can all be
74    used to indicate a value of <code>false</code>: an empty string, the
75    numeric <code>0</code>, the string <code>off</code> or the string
76    <code>no</code>. All other values will be considered
77    <code>true</code>.</li>
78
79    <li>If the last character of the <dfn>value</dfn> is a backslash
80    <code>\</code>, the next non-comment line will be the continuation of the
81    current line. Please note that trailing spaces before the continuation mark
82    are preserved, and leading spaces are removed from the beginning of a
83    continuation. If you want to have leading spaces in a continued line, start
84    the line with a backslash <code>\</code> before the leading spaces. It is
85    also worth bearing in mind that the backslash <code>\</code> character is
86    only significant if it appears at the end of a value or the beginning of a
87    continuation line. It is not a special character if it appears elsewhere.
88    For example:
89      <pre>
90foo bar\
91    egg\
92    ham
93# will become:
94foo bareggham
95
96foo bar \
97    egg \
98    ham
99# will become:
100foo bar egg ham
101
102foo bar\
103    \ egg\
104    \ ham
105# will become:
106foo bar egg ham
107
108foo bar\
109    \ egg\ham
110# will become:
111foo bar egg\ham
112</pre>
113    </li>
114  </ul>
115
116  <p>The FCM central and user configuration files can be used to add or modify
117  some of the default settings of FCM. When the <code>fcm</code> command is
118  invoked, it normally attempts to search for a central configuration file at
119  <samp>$BINDIR/../etc/fcm.cfg</samp> and then <samp>$BINDIR/fcm.cfg</samp>,
120  where <samp>$BINDIR</samp> is the container directory of the <code>fcm</code>
121  command. If a central configuration file can be located, the settings in the
122  file will replace the pre-defined ones. After searching/reading the central
123  configuration file, the system will attempt to search for a user
124  configuration file located at <samp>$HOME/.fcm</samp> of the current user. If
125  such a file can be found, its settings will replace the pre-defined ones as
126  well as those defined in the central configuration file.</p>
127
128  <p>For information on the valid entries in the central and user configuration
129  files, please refer to the <a href="annex_fcm_cfg.html">Annex: Declarations
130  in FCM central/user configuration file</a>.</p>
131
132  <h2 id="fcm_bld">fcm build</h2>
133
134  <dl>
135    <dt>Usage</dt>
136
137    <dd><code>fcm build [OPTIONS...] [CFGFILE]</code></dd>
138
139    <dt>Description</dt>
140
141    <dd>
142      <p><code>fcm build</code> invokes the FCM build system.</p>
143
144      <p>The path to a valid build configuration file <var>CFGFILE</var> may be
145      provided as either a URL or a pathname. Otherwise, the build system
146      searches the default locations for a build configuration file.</p>
147
148      <p>If no option is specified, the system uses the <code>-s 5 -t all -j 1
149      -v 1</code> by default.</p>
150
151      <dl>
152        <dt><code>-a [--archive]</code></dt>
153
154        <dd>This option can be specified to switch on the archive mode. In
155        archive mode, sub-directories produced by the build will be archived in
156        <code>tar</code> format at the end of a successful build. This option
157        should not be used if the current build is intended to be re-used as a
158        pre-compiled build.</dd>
159
160        <dt><code>--clean</code></dt>
161
162        <dd>If this option is specified, the build system will parse the
163        configuration file, remove contents generated by the build system in
164        the destination and exit.</dd>
165
166        <dt><code>-f [--full]</code></dt>
167
168        <dd>If this option is specified, the build system will attempt to
169        perform a full/clean build by removing any previous build files.
170        Otherwise, the build system will attempt to perform an incremental
171        build where appropriate.</dd>
172
173        <dt><code>--ignore-lock</code></dt>
174
175        <dd>When the build system is invoked, it sets a lock file in the build
176        root directory to prevent other extracts/builds taking place in the
177        same location. The lock file is normally removed when the build system
178        exits. (However, a lock file may be left behind if the user interrupts
179        the command, e.g. by typing <kbd>Ctrl-C</kbd>.) You can bypass the
180        check for lock files by using this option.</dd>
181
182        <dt><code>-j [--jobs] arg</code></dt>
183
184        <dd>This option can be used to specify the number of parallel jobs that
185        can be handled by the <code>make</code> command. The argument
186        <var>arg</var> must be a natural integer to represent the number of
187        jobs. If not specified, the default is to perform serial
188        <code>make</code> (i.e. 1 job).</dd>
189
190        <dt><code>-s [--stage] arg</code></dt>
191
192        <dd>
193          This option can be used to limit the actions performed by the build
194          system, up to a named stage determined by the argument
195          <var>arg</var>. If not specified, the default is 5. The stages are:
196
197          <ul>
198            <li><dfn>1, s or setup</dfn>: Stage 1, read configuration and set
199            up the build</li>
200
201            <li><dfn>2, pp or pre_process</dfn>: Stage 2, perform
202            pre-processing for source files that require pre-processing</li>
203
204            <li><dfn>3, gd or generate_dependency</dfn>: Stage 3, scan source
205            files for dependency information and generate <code>make</code>
206            rules for them</li>
207
208            <li><dfn>4, gi or generate_interface</dfn>: Stage 4, generate
209            interface files for Fortran 9X source files</li>
210
211            <li><dfn>5, m or make</dfn>: Stage 5, invoke the <code>make</code>
212            command to build the project</li>
213          </ul>
214        </dd>
215
216        <dt><code>-t [--targets] arg</code></dt>
217
218        <dd>This option can be used to specify the targets to be built. The
219        argument <var>arg</var> must be a colon-separated list of valid
220        targets. If not specified, the default to be built is the
221        <samp>all</samp> target.</dd>
222
223        <dt><code>-v [--verbose] arg</code></dt>
224
225        <dd>This option can be specified to alter the level of diagnostic
226        output. The argument <var>arg</var> to this option must be an integer
227        greater than or equal to 0. The verbose level increases with this
228        number. If not specified, the default verbose level is 1.</dd>
229      </dl>
230
231      <p>For further details, please refer to the chapter on <a href=
232      "build.html">The Build System</a>.</p>
233    </dd>
234
235    <dt>Alternate Names</dt>
236
237    <dd>bld</dd>
238  </dl>
239
240  <h2 id="fcm_ext">fcm extract</h2>
241
242  <dl>
243    <dt>Usage</dt>
244
245    <dd><code>fcm extract [OPTIONS...] [CFGFILE]</code></dd>
246
247    <dt>Description</dt>
248
249    <dd>
250      <p><code>fcm extract</code> invokes the FCM extract system.</p>
251
252      <p>The path to a valid extract configuration file <var>CFGFILE</var> may
253      be provided as either a URL or a pathname. Otherwise, the extract system
254      searches the default locations for an extract configuration file.</p>
255
256      <dl>
257        <dt><code>--clean</code></dt>
258
259        <dd>If this option is specified, the extract system will parse the
260        configuration file, remove contents generated by previous extract in
261        the destination and exit.</dd>
262
263        <dt><code>-f [--full]</code></dt>
264
265        <dd>If this option is specified, the extract system will attempt to
266        perform a full extract by removing any previous extracted files.
267        Otherwise, the extract system will attempt to perform an incremental
268        extract where appropriate.</dd>
269
270        <dt><code>--ignore-lock</code></dt>
271
272        <dd>When the extract system is invoked, it sets a lock file in the
273        extract destination root directory to prevent other extracts/builds
274        taking place in the same location. The lock file is normally removed
275        when the extract system exits. (However, a lock file may be left behind
276        if the user interrupts the command, e.g. by typing <kbd>Ctrl-C</kbd>.)
277        You can bypass the check for lock files by using this option.</dd>
278
279        <dt><code>-v [--verbose] arg</code></dt>
280
281        <dd>This option can be specified to alter the level of diagnostic
282        output. The argument <var>arg</var> to this option must be an integer
283        greater than or equal to 0. The verbose level increases with this
284        number. If not specified, the default verbose level is 1.</dd>
285      </dl>
286
287      <p>For further details, please refer to the chapter on <a href=
288      "extract.html">The Extract System</a>.</p>
289    </dd>
290
291    <dt>Alternate Names</dt>
292
293    <dd>ext</dd>
294  </dl>
295
296  <h2 id="fcm_cmp-ext-cfg">fcm cmp-ext-cfg</h2>
297
298  <dl>
299    <dt>Usage</dt>
300
301    <dd><code>fcm cmp-ext-cfg [--verbose (-v) arg] [--wiki (-w) arg] CFG1
302    CFG2</code></dd>
303
304    <dt>Description</dt>
305
306    <dd>
307      <p><code>fcm cmp-ext-cfg</code> compares the extract configurations of
308      two similar extract configuration files <var>CFG1</var> and
309      <var>CFG2</var>. It reports repository branches and source directories
310      that are declared in one file but not another. If a source directory is
311      declared in both files, it compares their versions. If they differ, it
312      uses <code>svn log</code> to obtain a list of revision numbers at which
313      changes are made to the source directory. It then reports, for each
314      declared repository branch, the revisions at which changes occur in their
315      declared source directories.</p>
316
317      <p>The list of revisions for each declared repository branch is normally
318      printed out as a simple list in plain text.</p>
319
320      <dl>
321        <dt><code>--verbose ARG</code></dt>
322
323        <dd>You can use this option to print the log of each revision, by
324        setting <var>ARG</var> to 2.</dd>
325
326        <dt><code>--wiki</code></dt>
327
328        <dd>Alternatively, you can use this option to change that into an
329        tabular output suitable for inserting into a Trac wiki page. This
330        option must be specified with an argument, which must be the Subversion
331        URL or FCM URL keyword of a FCM project associated with the intended
332        Trac system. The URL allows the command to work out the correct wiki
333        syntax to use.</dd>
334      </dl>
335    </dd>
336  </dl>
337
338  <h2 id="fcm_gui">fcm gui</h2>
339
340  <dl>
341    <dt>Usage</dt>
342
343    <dd><code>fcm gui [DIR]</code></dd>
344
345    <dt>Description</dt>
346
347    <dd>
348      <p><code>fcm gui</code> starts up the FCM GUI. If <var>DIR</var> is
349      specified then this is used as the working directory.</p>
350
351      <p>For further details, please refer to the section <a href=
352      "code_management.html#svn_gui">Using the GUI</a>.</p>
353    </dd>
354  </dl>
355
356  <h2 id="fcm_keyword-print">fcm keyword-print</h2>
357
358  <dl>
359    <dt>Usage</dt>
360
361    <dd><code>fcm keyword-print [TARGET]</code></dd>
362
363    <dt>Description</dt>
364
365    <dd>
366      <p>If no argument is specified, <code>fcm keyword-print</code> prints all
367      the registered FCM location keywords. Otherwise, it prints the location
368      and revision keywords according to the argument <var>TARGET</var>, which
369      must be a FCM URL keyword, a Subversion URL or a path to a Subversion
370      working copy.</p>
371    </dd>
372
373    <dt>Alternate Names</dt>
374
375    <dd>kp</dd>
376  </dl>
377
378  <h2 id="fcm_svn">FCM Code Management Commands</h2>
379
380  <p>This section describes all of the code management commands supported by
381  <code>fcm</code>.</p>
382
383  <ul>
384    <li>In some cases <code>fcm</code> simply passes the command directly on to
385    <code>svn</code> (after expanding any URL keywords). These commands are
386    listed in the <a href="#fcm_svn_other">Other Code Management Commands</a>
387    section.</li>
388
389    <li>Where <code>fcm</code> adds functionality these commands are discussed
390    individually.</li>
391
392    <li>In all cases, all the command abbreviations supported by
393    <code>svn</code> work with <code>fcm</code>.</li>
394  </ul>
395
396  <h3 id="fcm_svn_add">fcm add</h3>
397
398  <dl>
399    <dt>Usage</dt>
400
401    <dd><code>fcm add --check (-c)</code><br />
402    <code>fcm add &lt;any valid <em>svn add</em> options&gt;</code></dd>
403
404    <dt>Description</dt>
405
406    <dd>
407      <p><code>fcm add</code> supports all of the switches and arguments
408      supported by <code>svn add</code> (refer to the <a href=
409      "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.add.html">Subversion
410      book</a> for details).</p>
411
412      <p>In addition, <code>fcm add</code> supports a <code>--check</code>
413      switch (no other switches or arguments). When this is specified then
414      <code>fcm</code> checks for any files which are not currently under
415      version control (i.e. those marked with a <samp>?</samp> by <code>svn
416      status</code>) and prompts to see if you wish to schedule them for
417      addition at the next commit (using <code>svn add</code>).</p>
418
419      <p>For further details refer to the section <a href=
420      "code_management.html#svn_basic_check">Adding and Removing Files</a>.</p>
421    </dd>
422  </dl>
423
424  <h3 id="fcm_svn_br">fcm branch</h3>
425
426  <dl>
427    <dt>Usage</dt>
428
429    <dd><code>fcm branch [--info (-i)] [&lt;info-options&gt;]
430    [TARGET]</code><br />
431    <code>fcm branch --delete (-d) [&lt;info-options&gt;]
432    [&lt;commit-options&gt;] [TARGET]</code><br />
433    <code>fcm branch --create (-c) --name (-n) arg [--revision arg]
434    [&lt;create-options&gt;] [&lt;commit-options&gt;] [TARGET]</code><br />
435    <code>fcm branch --list (-l) [&lt;branch-list-options&gt;]
436    [TARGET]</code></dd>
437
438    <dt>Description</dt>
439
440    <dd>
441      <p>If <var>TARGET</var> is specified, it must either be a URL or a path
442      to a local working copy. Otherwise, the current working directory must be
443      a working copy. For <code>--info</code> and <code>--delete</code>, the
444      specified URL or that of the working copy must be a valid branch
445      (including the trunk) in a standard FCM project. For
446      <code>--create</code> and <code>--list</code>, it must be a valid URL of
447      a standard FCM project.</p>
448
449      <dl>
450        <dt><code>fcm branch --info</code></dt>
451
452        <dd>
453          <p>Displays information about a branch. This is the default if no
454          options are specified. It performs the following actions:</p>
455
456          <ul>
457            <li>It reports the basic information of the branch URL, as returned
458            by <code>svn info</code>.</li>
459
460            <li>If <code>--verbose</code> is set, it also prints the log
461            message of the last change revision.</li>
462
463            <li>If the URL is not the trunk:
464
465              <ul>
466                <li>It reports the branch creation information, including the
467                revision, author and date. It also reports the parent URL@REV
468                of the branch. If <code>--verbose</code> is set, it prints the
469                log message of the branch creation revision.</li>
470
471                <li>If the branch does not exist at the HEAD, it reports the
472                revision at which it is deleted.</li>
473
474                <li>It reports the last merges into and from the parent branch.
475                If <code>--verbose</code> is set, it also prints the log
476                message of these merges.</li>
477
478                <li>It reports the revisions available for merging into and
479                from the parent branch. If <code>--verbose</code> is set, it
480                also prints the log message of these revisions.</li>
481              </ul>
482            </li>
483
484            <li>If <code>--show-children</code> is specified, it lists the
485            current children of the branch and their create revisions. Where
486            appropriate, it reports the revision of each child, which is last
487            merged from/into the current branch. It also reports the available
488            merges from/into each child into the current branch.</li>
489
490            <li>If <code>--show-siblings</code> is specified, it reports recent
491            merges from/into sibling branches. It also reports the available
492            merges from/into sibling branches where recent merges are detected.
493            If <code>--verbose</code> is set, it also prints the log message of
494            these merges.</li>
495
496            <li>If <code>--show-other</code> is specified, it reports all
497            custom and reverse merges into the current branch.</li>
498
499            <li>You can turn on <code>--show-children</code>,
500            <code>--show-siblings</code> and <code>--show-other</code>
501            simultaneously by specifying <code>--show-all</code>.</li>
502          </ul>
503
504          <p>For further details refer to the section <a href=
505          "code_management.html#svn_branching_info">Getting Information About
506          Branches</a>.</p>
507        </dd>
508
509        <dt><code>fcm branch --delete</code></dt>
510
511        <dd>
512          <p>Deletes a branch. This command performs the following actions:</p>
513
514          <ul>
515            <li>Firstly, it provides exactly the same output as <code>fcm
516            branch --info</code>.</li>
517
518            <li>If you do not specify the <code>--non-interactive</code>
519            option, it starts an editor (using a similar convention as <a href=
520            "#fcm_svn_ci">commit</a>) to allow you to add further comment to
521            the commit log message. A standard commit log template and change
522            summary is provided for you below the line that says <samp>--Add
523            your commit message ABOVE - do not alter this line or those
524            below--</samp>. If you need to add any extra message to the log,
525            please do so <strong>above</strong> this line. When you exit the
526            editor, the command will report the commit log before prompting for
527            confirmation that you wish to proceed with deleting the branch (it
528            aborts if not).</li>
529          </ul>
530
531          <p>If you specify the <code>--non-interactive</code> option, the
532          command will not prompt you for anything. (The
533          <code>--svn-non-interactive</code> option is set automatically when
534          you specify <code>--non-interactive</code>.)</p>
535
536          <p>Subversion may prompt you for authentication if it is the first
537          time you access the repository. The command fails if the
538          authentication fails. If you specify the
539          <code>--svn-non-interactive</code> option, Subversion will not prompt
540          you for authentication. In such case, the command will simply fail if
541          authentication is required. You can use the <code>--password</code>
542          option to specify a password. Please note that the
543          <code>--svn-non-interactive</code> option is always specified if you
544          are running <code>branch --delete</code> from the FCM GUI. If
545          authentication is required, you should specify your password using
546          the <code>--password</code> option in <kbd>Other options</kbd>.</p>
547
548          <p>For further details refer to the section <a href=
549          "code_management.html#svn_branching_delete">Deleting
550          Branches</a>.</p>
551        </dd>
552
553        <dt><code>fcm branch --create</code></dt>
554
555        <dd>
556          <p>Creates a new branch.</p>
557
558          <p>You have to choose a name for your branch. This must be specified
559          as the argument of the <code>--name (-n)</code> option. The name of
560          the branch must contain only characters in the set
561          [A-Za-z0-9_-.].</p>
562
563          <p>You can specify the type of branch you are creating using the
564          <code>--type (-t)</code> option. The argument to the option must be
565          one of the following:</p>
566
567          <dl>
568            <dt><code>DEV::USER</code></dt>
569
570            <dd>A development branch for the current user (e.g.
571            <samp>branches/dev/&lt;user_id&gt;/&lt;branch_name&gt;</samp>)</dd>
572
573            <dt><code>DEV::SHARE</code></dt>
574
575            <dd>A shared development branch (e.g.
576            <samp>branches/dev/Share/&lt;branch_name&gt;</samp>)</dd>
577
578            <dt><code>DEV</code></dt>
579
580            <dd>Same as <code>DEV::USER</code></dd>
581
582            <dt><code>TEST::USER</code></dt>
583
584            <dd>A test branch for the current user (e.g.
585            <samp>branches/test/&lt;user_id&gt;/&lt;branch_name&gt;</samp>)</dd>
586
587            <dt><code>TEST::SHARE</code></dt>
588
589            <dd>A shared test branch (e.g.
590            <samp>branches/test/Share/&lt;branch_name&gt;</samp>)</dd>
591
592            <dt><code>TEST</code></dt>
593
594            <dd>Same as <code>TEST::USER</code></dd>
595
596            <dt><code>PKG::USER</code></dt>
597
598            <dd>A package branch for the current user (e.g.
599            <samp>branches/pkg/&lt;user_id&gt;/&lt;branch_name&gt;</samp>)</dd>
600
601            <dt><code>PKG::SHARE</code></dt>
602
603            <dd>A shared package branch (e.g.
604            <samp>branches/pkg/Share/&lt;branch_name&gt;</samp>)</dd>
605
606            <dt><code>PKG::CONFIG</code></dt>
607
608            <dd>A configuration branch (e.g.
609            <samp>branches/pkg/Config/&lt;branch_name&gt;</samp>)</dd>
610
611            <dt><code>PKG::REL</code></dt>
612
613            <dd>A release branch (e.g.
614            <samp>branches/pkg/Rel/&lt;branch_name&gt;</samp>)</dd>
615
616            <dt><code>PKG</code></dt>
617
618            <dd>Same as <code>PKG::USER</code></dd>
619
620            <dt><code>CONFIG</code></dt>
621
622            <dd>Same as <code>PKG::CONFIG</code></dd>
623
624            <dt><code>REL</code></dt>
625
626            <dd>Same as <code>PKG::REL</code></dd>
627
628            <dt><code>SHARE</code></dt>
629
630            <dd>Same as <code>DEV::SHARE</code></dd>
631
632            <dt><code>USER</code></dt>
633
634            <dd>Same as <code>DEV::USER</code></dd>
635          </dl>
636
637          <p>If the <code>--type</code> option is not specified, it defaults to
638          DEV::USER.</p>
639
640          <p>Your branch name will normally be prefixed by the revision number
641          from which it is branched. (E.g. if the branch name is
642          <samp>my_branch</samp> and you are branching from revision 123 of the
643          trunk, the final name will be <samp>r123_my_branch</samp>.) If this
644          revision number is associated with a revision keyword, the keyword
645          will be used in place of the revision number. (E.g. if revision 123
646          is associated with the keyword vn6.1, <samp>r123_my_branch</samp>
647          will become <samp>vn6.1_my_branch</samp>.) You can alter this
648          behaviour using the argument to the <code>--rev-flag</code> option.
649          If <code>NORMAL</code> is specified, it uses the default behaviour.
650          If <code>NUMBER</code> is specified, it will always use the revision
651          number as the prefix, regardless of whether the revision number is
652          defined as a keyword or not. If <code>NONE</code> is specified, it
653          will not add a prefix to your branch name.</p>
654
655          <p>The command will normally create your branch from the last changed
656          revision of the trunk of the specified project.</p>
657
658          <ul>
659            <li>You can use the <code>--revision</code> option to specify an
660            earlier revision of the source.</li>
661
662            <li>If the source URL is a valid URL of a branch in a standard FCM
663            project, you can use the <code>--branch-of-branch</code> option to
664            create a branch of the source branch.</li>
665          </ul>
666
667          <p>The <code>--ticket</code> option can be used to specify one or
668          more Trac ticket numbers, which the branch relates to. Multiple
669          ticket numbers can be set by specifying this option multiple times,
670          or by using a comma-separated list of ticket numbers as the argument
671          to the option. If set, the line <samp>Relates to ticket
672          #&lt;number&gt;[, #&lt;number&gt;...]</samp> will be added to the
673          template commit log.</p>
674
675          <p>If you specify the <code>--non-interactive</code> option, the
676          command will not prompt you for anything. (The
677          <code>--svn-non-interactive</code> option is set automatically when
678          you specify <code>--non-interactive</code>.)</p>
679
680          <p>Subversion may prompt you for authentication if it is the first
681          time you access the repository. The command fails if the
682          authentication fails. If you specify the
683          <code>--svn-non-interactive</code> option, Subversion will not prompt
684          you for authentication. In such case, the command will simply fail if
685          authentication is required. You can use the <code>--password</code>
686          option to specify a password. Please note that the
687          <code>--svn-non-interactive</code> option is always specified if you
688          are running <code>branch --create</code> from the FCM GUI. If
689          authentication is required, you should specify your password using
690          the <code>--password</code> option in <kbd>Other options</kbd>.</p>
691
692          <p>This command performs the following actions:</p>
693
694          <ul>
695            <li>It determines the last changed revision of the trunk/source
696            branch at the HEAD (or the specified) revision.</li>
697
698            <li>It constructs the branch name from the option you have
699            specified and reports it.</li>
700
701            <li>It checks that the chosen branch name does not currently exist.
702            If so, the command aborts with an error.</li>
703
704            <li>If you do not specify the <code>--non-interactive</code>
705            option, it starts an editor (using a similar convention as <a href=
706            "#fcm_svn_ci">commit</a>) to allow you to add further comment to
707            the commit log message. A standard commit log template and change
708            summary is provided for you below the line that says <samp>--Add
709            your commit message ABOVE - do not alter this line or those
710            below--</samp>. If you need to add any extra message to the log,
711            please do so <strong>above</strong> this line. When you exit the
712            editor, the command will report the commit log before prompting for
713            confirmation that you wish to proceed (it aborts if not).</li>
714
715            <li>It uses <code>svn mkdir</code> to create any sub-directories
716            required for the copy to succeed.</li>
717
718            <li>It uses <code>svn copy</code> to create the branch.</li>
719          </ul>
720
721          <p>For further details refer to the section <a href=
722          "code_management.html#svn_branching_create">Creating
723          Branches</a>.</p>
724        </dd>
725
726        <dt><code>fcm branch --list</code></dt>
727
728        <dd>
729          <p>Lists the branches created by you (and/or other users) at the HEAD
730          revision of a standard FCM project.</p>
731
732          <p>By default, it lists the branches created by you at the HEAD
733          revision. To display the branches at a different revision, you can
734          use the <code>--revision arg</code> option.</p>
735
736          <p>You can specify a list of users with the <code>--user arg</code>
737          option, where <var>arg</var> is a colon separated list of users.
738          (Alternatively, you can specify this option multiple times.) When
739          this option is set, the command lists the branches created by the
740          specified list of users instead. Note that you can also list shared
741          branches by specifying the user as <code>Share</code>, configuration
742          branches by specifying the user as <code>Config</code> and release
743          branches by specifying the user as <code>Rel</code>.</p>
744
745          <p>You can list all branches in the project by specifying the
746          <code>--show-all</code> option. (This option overrides the
747          <code>--user arg</code> option.)</p>
748
749          <p>By default, it lists the branches in the FCM URL keyword format.
750          If you want to print the full Subversion URL of the branches, you can
751          use the <code>--verbose</code> option.</p>
752
753          <p>The command returns 0 (success) if one or more branches is found
754          for the specified users, or 1 (failure) if no branch is found.</p>
755        </dd>
756      </dl>
757    </dd>
758
759    <dt>Alternate Names</dt>
760
761    <dd>br</dd>
762  </dl>
763
764  <h3 id="fcm_svn_ci">fcm commit</h3>
765
766  <dl>
767    <dt>Usage</dt>
768
769    <dd><code>fcm commit [--dry-run] [--svn-non-interactive] [--password arg]
770    [PATH]</code></dd>
771
772    <dt>Description</dt>
773
774    <dd>
775      <p><code>fcm commit</code> sends changes from your working copy in the
776      current working directory (or from <var>PATH</var> if it is specified) to
777      the repository.</p>
778
779      <p>This command performs the following actions:</p>
780
781      <ul>
782        <li>It checks that the current working directory (or <var>PATH</var> if
783        it is specified) is a working copy. (If not, it aborts with an
784        error).</li>
785
786        <li>It always commits from the top level of the working copy.</li>
787
788        <li>It checks that there are no files in conflict, missing or out of
789        date (it aborts if there are).</li>
790
791        <li>It checks that any files which have been added have the
792        <var>svn:executable</var> property set correctly (in case a script was
793        added before the execute bit was set correctly).</li>
794
795        <li>It reads in any existing commit message.
796
797          <ul>
798            <li>The commit message is stored in the file
799            <samp>#commit_message#</samp> in the top level of your working
800            copy.</li>
801          </ul>
802        </li>
803
804        <li>It adds the following line to the commit log message: <samp>--Add
805        your commit message ABOVE - do not alter this line or those
806        below--</samp>. This line, and anything below it, is automatically
807        ignored by <code>svn commit</code>. If you need to add any extra message
808        to the log, please do so <strong>above</strong> this line.</li>
809
810        <li>If you have run the <a href="fcm_svn_merge">merge</a> command
811        before the commit, you will get a standard commit log template below
812        a line that says <samp>--FCM message (will be inserted
813        automatically)--</samp>. Please do not try to alter this message (your
814        changes will be ignored if you do).</li>
815
816        <li>It adds current status information to the commit message showing
817        the list of modifications below a line that says <samp>--Change summary
818        (not part of commit message)--</samp>.</li>
819
820        <li>It starts an editor to allow you to edit the commit message.
821
822          <ul>
823            <li>If defined, the environment variable <var>SVN_EDITOR</var>
824            specifies the editor.</li>
825
826            <li>Otherwise the environment variable <var>VISUAL</var> specifies
827            the editor.</li>
828
829            <li>Otherwise the environment variable <var>EDITOR</var> specifies
830            the editor.</li>
831
832            <li>Otherwise the editor <code>nedit</code> is used.</li>
833          </ul>
834        </li>
835
836        <li>It reports the commit message that will be sent to Subversion and
837        then asks if you want to proceed (it aborts if not).</li>
838
839        <li>It calls <code>svn commit</code> to send the changes to the
840        repository.</li>
841
842        <li>It calls <code>svn update</code> to bring your working copy up to
843        the new revision.</li>
844      </ul>
845
846      <p>Subversion may prompt you for authentication if it is the first time
847      you access the repository. The command fails if the authentication fails.
848      If you specify the <code>--non-interactive</code> option, Subversion will
849      not prompt you for authentication. In such case, the command will simply
850      fail if authentication is required. You can use the
851      <code>--password</code> option to specify a password. Please note that
852      the <code>--svn-non-interactive</code> option is always specified if you
853      are running <code>commit</code> from the FCM GUI. If authentication is
854      required, you should specify your password using the
855      <code>--password</code> option in <kbd>Other options</kbd>.</p>
856
857      <p>The <code>--dry-run</code> switch prevents the command from committing
858      any changes. This can be used to allow you to add notes to your commit
859      message whilst you are still preparing your change.</p>
860
861      <p>For further details refer to the section <a href=
862      "code_management.html#svn_basic_commit">Committing Changes</a>.</p>
863    </dd>
864
865    <dt>Alternate Names</dt>
866
867    <dd>ci</dd>
868  </dl>
869
870  <h3 id="fcm_svn_cf">fcm conflicts</h3>
871
872  <dl>
873    <dt>Usage</dt>
874
875    <dd><code>fcm conflicts [PATH]</code></dd>
876
877    <dt>Description</dt>
878
879    <dd>
880      <p><code>fcm conflicts</code> helps you to resolve any text files in your
881      working copy which have conflicts by using the graphical merge tool
882      <code>xxdiff</code>. If <var>PATH</var> is set, it must be a working
883      copy, and the command will operate in it. If <var>PATH</var> is not set,
884      the command will operate in your current working directory.</p>
885
886      <p>This command performs the following actions:</p>
887
888      <ul>
889        <li>For each text file reported as being in conflict (i.e. marked with
890        a <samp>C</samp> by <code>svn status</code>) it calls
891        <code>xxdiff</code>.</li>
892
893        <li>If <code>xxdiff</code> reports all conflicts resolved then if asks
894        if you wish to run <code>svn resolved</code> on that file.</li>
895      </ul>
896
897      <p>For further details refer to the section <a href=
898      "code_management.html#svn_basic_conflicts">Resolving Conflicts</a>.</p>
899    </dd>
900
901    <dt>Alternate Names</dt>
902
903    <dd>cf</dd>
904  </dl>
905
906  <h3 id="fcm_svn_rm">fcm delete</h3>
907
908  <dl>
909    <dt>Usage</dt>
910
911    <dd><code>fcm delete --check (-c)</code><br />
912    <code>fcm delete &lt;any valid <em>svn delete</em> options&gt;</code></dd>
913
914    <dt>Description</dt>
915
916    <dd>
917      <p><code>fcm delete</code> supports all of the switches, arguments and
918      alternate names supported by <code>svn delete</code> (refer to the
919      <a href=
920      "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.delete.html">Subversion
921      book</a> for details).</p>
922
923      <p>In addition, <code>fcm delete</code> supports a <code>--check</code>
924      switch (no other switches or arguments). When this is specified then
925      <code>fcm</code> checks for any files which are missing (i.e. marked with
926      a <samp>!</samp> by <code>svn status</code>) and prompts to see if you
927      wish to schedule them for deletion at the next commit (using <code>svn
928      delete</code>).</p>
929
930      <p>Subversion may prompt you for authentication if it is the first time
931      you access the repository. The command fails if the authentication fails.
932      If you specify the <code>--non-interactive</code> option, Subversion will
933      not prompt you for authentication. In such case, the command will simply
934      fail if authentication is required. Please note that the
935      <code>--non-interactive</code> option is automatically specified if you
936      are running <code>delete</code> from the FCM GUI and you have not checked
937      the box <kbd>Check for files and directories...</kbd>. If authentication
938      is required, you should run <code>delete</code> in interactive mode on a
939      command line.</p>
940
941      <p>For further details refer to the section <a href=
942      "code_management.html#svn_basic_check">Adding and Removing Files</a>.</p>
943    </dd>
944  </dl>
945
946  <h3 id="fcm_svn_diff">fcm diff</h3>
947
948  <dl>
949    <dt>Usage</dt>
950
951    <dd><code>fcm diff --branch (-b) [--graphical (-g) | --summarise | --wiki |
952    --trac (-t)] [TARGET]</code><br />
953    <code>fcm diff [--graphical (-g) | --summarise | &lt;any valid <em>svn
954    diff</em> options&gt;]</code></dd>
955
956    <dt>Description</dt>
957
958    <dd>
959      <p><code>fcm diff</code> supports all of the switches, arguments and
960      alternate names supported by <code>svn diff</code> (refer to the <a href=
961      "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.diff.html">Subversion
962      book</a> for details). In addition, <code>fcm diff</code> supports the
963      following switches:</p>
964
965      <dl>
966        <dt><code>--graphical (-g)</code></dt>
967
968        <dd>If this option is specified, the command uses a graphical tool to
969        display the differences. (The default graphical diff tool is
970        <code>xxdiff</code>, but you can alter the behaviour by following the
971        instruction discussed in the sub-section on <a href=
972        "code_management.html#svn_basic_diff">Examining Changes</a>.) This
973        switch can be used in combination with all other valid switch
974        (including <code>--branch</code>) except <code>--diff-cmd</code>,
975        <code>--extensions</code>, <code>--trac</code> and
976        <code>--wiki</code>.</dd>
977
978        <dt><code>--summarise</code></dt>
979
980        <dd>This option is implemented in FCM as a wrapper to the Subversion
981        <code>--summarize</code> option. It prints only a summary of the
982        results.</dd>
983
984        <dt><code>--branch</code></dt>
985
986        <dd>
987          If this option is specified, the command displays the differences
988          between the target branch and its parent. This should show you the
989          differences which you would get if you tried to merge the changes in
990          the branch into its parent. It performs the following actions:
991
992          <ul>
993            <li>If <var>TARGET</var> is specified, it must either be a URL or a
994            path to a local working copy. Otherwise, the current working
995            directory must be a working copy. The specified URL or that of the
996            working copy must be a valid branch in a standard FCM project.</li>
997
998            <li>It determines the base of the branch relative to its parent.
999            This is adjusted to account for any merges from the branch to its
1000            parent or vice-versa.</li>
1001
1002            <li>It reports what path and revision it is comparing against.</li>
1003
1004            <li>If <code>--trac</code> is specified, it launches Trac with your
1005            default web browser to display it. Note: if <var>TARGET</var> is a
1006            working copy, local changes in it will not be displayed by
1007            Trac.</li>
1008
1009            <li>If <code>--wiki</code> is specified, it prints a Trac wiki
1010            syntax for the differences between the base and the specified
1011            branch.</li>
1012
1013            <li>Otherwise, it calls <code>svn diff</code> to report the
1014            differences between the base and the specified branch (or working
1015            copy).</li>
1016          </ul>
1017        </dd>
1018      </dl>
1019
1020      <p>For further details refer to the section <a href=
1021      "code_management.html#svn_basic_diff">Examining Changes</a>.</p>
1022    </dd>
1023  </dl>
1024
1025  <h3 id="fcm_svn_merge">fcm merge</h3>
1026
1027  <dl>
1028    <dt>Usage</dt>
1029
1030    <dd><code>fcm merge [--dry-run] [--non-interactive] [--verbose (-v)]
1031    SOURCE</code><br />
1032    <code>fcm merge --custom --revision N[:M] [--dry-run] [--non-interactive]
1033    [--verbose (-v)] SOURCE</code><br />
1034    <code>fcm merge --custom [--dry-run] [--non-interactive] [--verbose (-v)]
1035    URL1[@REV1] URL2[@REV2]</code><br />
1036    <code>fcm merge --reverse --revision [M:]N [--dry-run] [--non-interactive]
1037    [--verbose (-v)]</code></dd>
1038
1039    <dt>Description</dt>
1040
1041    <dd>
1042      <p><code>fcm merge</code> allows you to merge changes from a source into
1043      your working copy.</p>
1044
1045      <p>Before it begins, the command does the following:</p>
1046
1047      <ul>
1048        <li>If a <var>SOURCE</var> or <var>URL</var> is specified, it can be a
1049        full URL or a partial URL starting at the branches, trunk or tags
1050        level.
1051
1052          <ul>
1053            <li>If a partial URL is given, and the path name does not begin
1054            with <samp>trunk</samp>, <samp>tags</samp> or <samp>branches</samp>
1055            then <samp>branches/</samp> is automatically added to the beginning
1056            of your path.</li>
1057          </ul>
1058        </li>
1059
1060        <li>It determines the <var>TARGET</var> URL by examining your working
1061        copy.</li>
1062
1063        <li>If the current directory is not the top of your working copy, it
1064        changes the current directory to the top of your working copy.</li>
1065
1066        <li>If your working copy is not pointing to a branch of a project
1067        managed by FCM, the command aborts with an error.</li>
1068
1069        <li>If you do not specify the <code>--non-interactive</code> option, it
1070        checks for any local modifications in your working copy. If it finds
1071        any it reports them and asks you to confirm that you wish to continue
1072        (it aborts if not).</li>
1073      </ul>
1074
1075      <dl>
1076        <dt>Automatic mode (i.e. neither <code>--custom</code> nor
1077        <code>--reverse</code> is specified)</dt>
1078
1079        <dd>
1080          <p>Automatic merges are used to merge changes between two directly
1081          related branches, (i.e. the branches must either be created from the
1082          same parent or have a parent/child relationship). These merges are
1083          tracked by FCM and can be used by subsequent FCM commands. The merge
1084          delta is calculated by doing the following:</p>
1085
1086          <ul>
1087            <li>It checks that the <var>SOURCE</var> and <var>TARGET</var> are
1088            directly related.</li>
1089
1090            <li>It determines the base revision and path of the <em>common
1091            ancestor</em> of the <var>SOURCE</var> and <var>TARGET</var>.</li>
1092
1093            <li>The base revision and path are adjusted to account for any
1094            merges from the <var>SOURCE</var> to the <var>TARGET</var> or
1095            vice-versa.</li>
1096
1097            <li>It reports the revisions from <var>SOURCE</var> available for
1098            merging into <var>TARGET</var>. If the <code>--verbose</code>
1099            option is set, it prints the log for these revisions. It aborts if
1100            no revision is available for merging.</li>
1101
1102            <li>If there are 2 or more revisions available for merging and you
1103            do not specify the <code>--non-interactive</code> target, it asks
1104            you which revision of the <var>SOURCE</var> you wish to merge from.
1105            The default is the last changed revision of the <var>SOURCE</var>.
1106            The merge delta is between the base and the specified revision of
1107            the <var>SOURCE</var>.</li>
1108
1109            <li>If your working copy is a sub-tree of the <var>TARGET</var>, it
1110            ensures that the <var>SOURCE</var> contains only changes in the
1111            same sub-tree. Otherwise, the merge is unsafe, and the command will
1112            abort with an error.
1113
1114              <p>N.B.: The command looks for changes in the <var>SOURCE</var>
1115              by going through the list of changed files since the the
1116              <var>SOURCE</var> was last merged into the <var>TARGET</var>. (If
1117              there is no previous merge from SOURCE to <var>TARGET</var>, the
1118              common ancestor is used.) It is worth noting that there are
1119              situations when the command will regard your merge as
1120              <em>unsafe</em> (and so will fail incorrectly) even if the
1121              changes in the <var>SOURCE</var> outside of the current sub-tree
1122              will result in a null merge. This can happen if the changes are
1123              the results of a previous merge from the <var>TARGET</var> to the
1124              <var>SOURCE</var> or if these changes have been reversed. In such
1125              case, you will have to perform your merge in a working copy of a
1126              full tree.</p>
1127            </li>
1128          </ul>
1129        </dd>
1130
1131        <dt>Custom mode (i.e. <code>--custom</code> is specified)</dt>
1132
1133        <dd>
1134          <p>The custom mode is useful if you need to merge changes selectively
1135          from another branch. The custom mode can be used in two forms:</p>
1136
1137          <ul>
1138            <li>In the first form, you must specify a <var>SOURCE</var> as well
1139            as a revision (range) using the <code>--revision</code> option. If
1140            you specify a single revision <var>N</var>, the merge delta is
1141            between revision <var>N - 1</var> and revision <var>N</var> of the
1142            SOURCE. Otherwise, the merge delta is between revision <var>N</var>
1143            and revision <var>M</var>, where <var>N</var> &lt;
1144            <var>M</var>.</li>
1145
1146            <li>In the second form, you must specify two URLs. The merge delta
1147            is simply between the two URLs. (For each URL, if you do not
1148            specify a peg revision, the command will peg the URL with its last
1149            changed revision.)</li>
1150          </ul>
1151
1152          <p>N.B. Unlike automatic merges, custom merges are not tracked or
1153          used by subsequent FCM <code>diff</code> or <code>merge</code>
1154          commands, (although <code>branch --info</code> can be set to report
1155          them). Custom merges are always allowed, even if your working copy is
1156          pointing to a sub-tree of a branch. However, there is no checking
1157          mechanism to ensure the safety of your sub-tree custom merge so you
1158          should only do this if you are confident it is what you want.
1159          Therefore, it is recommended that you use automatic merges where
1160          possible, and use custom merges only if you know what you are
1161          doing.</p>
1162        </dd>
1163
1164        <dt>Reverse mode (i.e. <code>--reverse</code> is specified)</dt>
1165
1166        <dd>
1167          <p>The reverse mode is useful if you need to reverse a changeset (or
1168          a range of changesets) in the current branch of the working copy. In
1169          this mode, you must specify a revision (range) using the
1170          <code>--revision</code> option. If you specify a single revision
1171          <var>N</var>, the merge delta is between revision <var>N</var> and
1172          revision <var>N - 1</var> of the current branch. Otherwise, the merge
1173          delta is between revision <var>M</var> and revision <var>N</var>,
1174          where <var>M</var> &gt; <var>N</var>.</p>
1175
1176          <p>N.B. Like custom merges, reverse merges are not tracked or used by
1177          subsequent FCM <code>diff</code> or <code>merge</code> commands,
1178          (although <code>branch --info</code> can be set to report them).
1179          Likewise, reverse merges in sub-trees are always allowed, although
1180          there is no checking mechanism to ensure the safety of your sub-tree
1181          reverse merge.</p>
1182        </dd>
1183      </dl>
1184
1185      <p>Once the merge delta is determined, the command performs the
1186      following:</p>
1187
1188      <ul>
1189        <li>If you set the <code>--dry-run</code> option or if you are running
1190        in the interactive mode, it reports what changes will result from
1191        performing this merge by calling <code>svn merge --dry-run</code>.
1192
1193          <ul>
1194            <li>It prints the actual <code>svn merge --dry-run</code> command
1195            if the <code>--verbose</code> option is specified.</li>
1196
1197            <li>If you specify the <code>--dry-run</code> option, it exits
1198            after reporting what changes will result from performing the
1199            merge.</li>
1200          </ul>
1201        </li>
1202
1203        <li>If you are running in the interactive mode, it asks if you want to
1204        go ahead with the merge (it aborts if not).</li>
1205
1206        <li>It performs the merge by calling <code>svn merge</code> to apply
1207        the delta between the base and the <var>SOURCE</var> on your working
1208        copy.
1209
1210          <ul>
1211            <li>It prints the actual <code>svn merge</code> command if the
1212            <code>--verbose</code> option is specified.</li>
1213          </ul>
1214        </li>
1215
1216        <li>It adds a standard template into the commit message to provide
1217        details of the merge. The template is written below the line that says
1218        <samp>--FCM message (will be inserted automatically)--</samp>. The
1219        <a href="fcm_svn_commit">fcm commit</a> command will detect the
1220        existence of the template, so that you will not be able to alter it
1221        by accident.
1222
1223          <ul>
1224            <li>The commit message is stored in the file
1225            <samp>#commit_message#</samp> in the top level of your working
1226            copy. It is created by the merge command if it does not already
1227            exist.</li>
1228          </ul>
1229        </li>
1230      </ul>
1231
1232      <p>For further details refer to the section <a href=
1233      "code_management.html#svn_branching_merge">Merging</a>.</p>
1234    </dd>
1235  </dl>
1236
1237  <h3 id="fcm_svn_mkpatch">fcm mkpatch</h3>
1238
1239  <dl>
1240    <dt>Usage</dt>
1241
1242    <dd><code>fcm mkpatch [OPTIONS] URL [OUTDIR]</code></dd>
1243
1244    <dt>Description</dt>
1245
1246    <dd>
1247      <p><code>fcm mkpatch</code> creates patches from the specified revisions
1248      of the specified <var>URL</var>, which must be a branch URL of a valid
1249      FCM project. If the <var>URL</var> is a sub-directory of a branch, it
1250      will use the root of the branch.</p>
1251
1252      <p>If <var>OUTDIR</var> is specified, the output is sent to
1253      <var>OUTDIR</var>. Otherwise, the output will be sent to a default
1254      location in the current directory (<samp>$PWD/fcm-mkpatch-out/</samp>).
1255      The output directory will contain the patch for each revision as well as
1256      a script for importing the patch.</p>
1257
1258      <p>If a revision is specified using the <code>--revision</code> option,
1259      it will attempt to create a patch based on the changes at that revision.
1260      If a revision is not specified, it will attempt to create a patch based
1261      on the changes at the HEAD revision. If a revision range is specified, it
1262      will attempt to create a patch for each revision in that range (including
1263      the change in the lower range) where changes have taken place in the URL.
1264      No output will be written if there is no change in the given revision
1265      (range).</p>
1266
1267      <p>The <code>--exclude</code> option can be used to exclude a path in the
1268      URL. The specified path must be a relative path of the URL. Glob patterns
1269      such as <code>*</code> and <code>?</code> are acceptable. Changes in an
1270      excluded path will not be considered in the patch. A changeset containing
1271      changes only in the excluded path will not be considered at all. Multiple
1272      paths can be specified by using a colon-separated list of paths, or by
1273      specifying this option multiple times.</p>
1274
1275      <p>The <code>--organisation</code> option can be used to specify the name
1276      of your organisation. The command will attempt to parse the commit log
1277      message for each revision in the patch. It will remove all merge
1278      templates, replace Trac links with a modified string, and add information
1279      about the original changeset. If you specify the name of your
1280      organisation, it will replace Trac links such as <samp>ticket:123</samp>
1281      with <samp>$organisation_ticket:123</samp>, and report the orginal
1282      changeset with a message such as
1283      <samp>$organisation_changeset:1000</samp>. If the organisation name is
1284      not specified then it defaults to <samp>original</samp>.</p>
1285
1286      <p>Within the output directory are the <em>patches</em> and the log
1287      message file for each revision. It also contains a generated script
1288      <code>fcm-import-patch</code> for importing the patches. The user of the
1289      script can invoke the script with either a URL or a working copy
1290      argument, and the script will attempt to import the patches into the
1291      given URL or working copy.</p>
1292
1293      <p>It is worth noting that changes in Subversion properties, including
1294      changes in executable permissions, are not handled by the import
1295      script.</p>
1296    </dd>
1297  </dl>
1298
1299  <h3 id="fcm_svn_switch">fcm switch</h3>
1300
1301  <dl>
1302    <dt>Usage</dt>
1303
1304    <dd><code>fcm switch [OPTIONS] URL [PATH]</code><br />
1305    <code>fcm switch --relocate [OPTIONS] FROM TO [PATH]</code></dd>
1306
1307    <dt>Description</dt>
1308
1309    <dd>
1310      <p><code>fcm switch</code> supports the arguments and alternate names
1311      supported by <code>svn switch</code>. If <code>--relocate</code> is
1312      specified, it supports all options supported by <code>svn switch</code>.
1313      Otherwise, it supports <code>--non-interactive</code>, <code>-r
1314      [--revision]</code> and <code>-q [--quiet]</code> only. (Please refer to
1315      the <a href=
1316      "http://svnbook.red-bean.com/en/1.4/svn.branchmerge.switchwc.html">Subversion
1317      book</a> for details).</p>
1318
1319      <p>If <code>--relocate</code> is specified, FCM will pass the options and
1320      arguments directly to the corresponding Subversion command. Otherwise,
1321      FCM will ensure that your working copy switches safely through the
1322      following actions:</p>
1323
1324      <ul>
1325        <li>If <var>PATH</var> (or the current working directory if
1326        <var>PATH</var> is not specified) is not at the top of a working copy,
1327        the command will automatically search for the top of the working copy,
1328        and the switch command will always apply recursively from that
1329        level.</li>
1330
1331        <li>You can specify only the <em>branch</em> part of the URL, such as
1332        <samp>trunk</samp>, <samp>branches/dev/fred/r1234_bob</samp> or even
1333        <samp>dev/fred/r1234_bob</samp> and the command will work out the full
1334        URL for you.</li>
1335
1336        <li>If you do not specify the <code>--non-interactive</code> option, it
1337        checks for any local modifications in your working copy. If it finds
1338        any it reports them and asks you to confirm that you wish to continue
1339        (it aborts if not).</li>
1340
1341        <li>If you have some template messages in the
1342        <samp>#commit_message#</samp> file in the top level of your working
1343        copy, (e.g. after you have performed a merge), the command will report
1344        an error. You should remove the template message manually from the
1345        <samp>#commit_message#</samp> file before re-running
1346        <code>switch</code>.</li>
1347
1348        <li>The command will analyse the current working copy URL and the
1349        specified URL to ensure that they are in the same project. If your
1350        working copy is a sub-tree of a project, the command will assume that
1351        you want the same sub-tree in the new URL.</li>
1352      </ul>
1353
1354      <p>For further details refer to the section <a href=
1355      "code_management.html#svn_branching_switch">Switching your working copy
1356      to point to another branch</a>.</p>
1357    </dd>
1358  </dl>
1359
1360  <h3 id="fcm_svn_trac">fcm trac</h3>
1361
1362  <dl>
1363    <dt>Usage</dt>
1364
1365    <dd><code>fcm trac [--browser (-b) ARG] [PATH]</code></dd>
1366
1367    <dt>Description</dt>
1368
1369    <dd>
1370      <p><code>fcm trac</code> invokes the web-browser to launch the
1371      corresponding URL of the web-based repository browser (currently Trac
1372      browser) to view the Subversion repository specified by
1373      <var>PATH</var>.</p>
1374
1375      <p>If the <code>--browser</code> option is specified, <var>ARG</var> must
1376      be a valid command to a web browser. If this option is not specified, the
1377      default is to use <code>firefox</code>, or whatever setting you have
1378      declared in the user configuration file (<samp>$HOME/.fcm</samp>) using
1379      the label <code>SET::MISC::WEB_BROWSER</code>. For example:</p>
1380      <pre>
1381set::misc::web_browser  mozilla
1382</pre>
1383
1384      <p>If <var>PATH</var> is specified, it must be a path to a local working
1385      copying, a Subversion URL or a FCM URL keyword. If <var>PATH</var> is not
1386      specified, it is set to <samp>.</samp>, the current working directory. If
1387      <var>PATH</var> is a directory in the local file system, the command will
1388      determine whether it is a working copy. If so, its associated Subversion
1389      URL will be used. The command fails if the directory is not a working
1390      copy. If <var>PATH</var> is a Subversion URL or a FCM URL keyword, the
1391      URL can be <em>pegged</em> with a revision number using the
1392      <code>@</code> symbol. For example, to view the trunk of the FCM
1393      repository at revision 400, you can use <samp>fcm:fcm_tr@400</samp>. The
1394      URL declared by or associated with <var>PATH</var> must also be
1395      associated with a Trac browser URL, which is declared using the
1396      <code>SET::TRAC::&lt;pck&gt;</code> label in the FCM central/user
1397      configuration file. The command fails if an associated Trac browser URL
1398      is not found.</p>
1399    </dd>
1400
1401    <dt>Alternate Names</dt>
1402
1403    <dd>www</dd>
1404  </dl>
1405
1406  <h3 id="fcm_svn_update">fcm update</h3>
1407
1408  <dl>
1409    <dt>Usage</dt>
1410
1411    <dd><code>fcm update [OPTIONS] [PATH ...]</code></dd>
1412
1413    <dt>Description</dt>
1414
1415    <dd>
1416      <p><code>fcm update</code> supports the arguments and alternate names
1417      supported by <code>svn update</code>. It supports the options
1418      <code>--non-interactive</code>, <code>-r [--revision]</code> and
1419      <code>-q [--quiet]</code> only. (Please refer to the <a href=
1420      "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.update.html">Subversion
1421      book</a> for details).</p>
1422
1423      <p>FCM will ensure that your working copies updates safely through the
1424      following actions:</p>
1425
1426      <ul>
1427        <li>If <var>PATH</var> (or the current working directory if
1428        <var>PATH</var> is not specified) is not at the top of a working copy,
1429        the command will automatically search for the top of the working copy,
1430        and the update command will always apply recursively from that
1431        level.</li>
1432
1433        <li>If you do not specify the <code>--non-interactive</code> option, it
1434        uses <code>svn status --show-updates</code> to display what will be
1435        updated in your working copies and to check for local modifications (if
1436        you specify <code>-r [--revision]</code> then it just uses <code>svn
1437        status</code>). If it finds any it reports them and asks you to confirm
1438        that you wish to continue (it aborts if not).</li>
1439      </ul>
1440    </dd>
1441  </dl>
1442
1443  <h3 id="fcm_svn_other">Other Code Management Commands</h3>
1444
1445  <p>Other <code>svn</code> commands are supported by <code>fcm</code> without
1446  any change in functionality, with the following minor enhancements:</p>
1447
1448  <ul>
1449    <li>Where appropriate, FCM performs repository and revision keywords
1450    expansion.</li>
1451
1452    <li>The <code>fcm checkout</code> command fails if you attempt to checkout
1453    into an existing working copy.</li>
1454
1455    <li>FCM prints the corresponding <code>svn</code> command, except for
1456    <code>cat</code> and any commands with the <code>--xml</code> option
1457    specified.</li>
1458  </ul>
1459
1460  <p>The following is a list of the commands:</p>
1461
1462  <ul>
1463    <li><a href=
1464    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.blame.html">svn
1465    blame</a></li>
1466
1467    <li><a href="http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.cat.html">svn
1468    cat</a></li>
1469
1470    <li><a href=
1471    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.checkout.html">svn
1472    checkout</a></li>
1473
1474    <li><a href=
1475    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.cleanup.html">svn
1476    cleanup</a></li>
1477
1478    <li><a href=
1479    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.copy.html">svn
1480    copy</a></li>
1481
1482    <li><a href=
1483    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.export.html">svn
1484    export</a></li>
1485
1486    <li><a href=
1487    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.import.html">svn
1488    import</a></li>
1489
1490    <li><a href=
1491    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.info.html">svn
1492    info</a></li>
1493
1494    <li><a href=
1495    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.list.html">svn
1496    list</a></li>
1497
1498    <li><a href="http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.log.html">svn
1499    log</a></li>
1500
1501    <li><a href=
1502    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.lock.html">svn
1503    lock</a></li>
1504
1505    <li><a href=
1506    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.mkdir.html">svn
1507    mkdir</a></li>
1508
1509    <li><a href=
1510    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.move.html">svn
1511    move</a></li>
1512
1513    <li><a href=
1514    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.propdel.html">svn
1515    propdel</a></li>
1516
1517    <li><a href=
1518    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.propedit.html">svn
1519    propedit</a></li>
1520
1521    <li><a href=
1522    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.propget.html">svn
1523    propget</a></li>
1524
1525    <li><a href=
1526    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.proplist.html">svn
1527    proplist</a></li>
1528
1529    <li><a href=
1530    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.propset.html">svn
1531    propset</a></li>
1532
1533    <li><a href=
1534    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.resolved.html">svn
1535    resolved</a></li>
1536
1537    <li><a href=
1538    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.revert.html">svn
1539    revert</a></li>
1540
1541    <li><a href=
1542    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.status.html">svn
1543    status</a></li>
1544
1545    <li><a href=
1546    "http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.unlock.html">svn
1547    unlock</a></li>
1548  </ul>
1549
1550  <p>Please refer to the <a href=
1551  "http://svnbook.red-bean.com/en/1.4/svn.ref.html">Subversion Complete
1552  Reference</a> in the Subversion book for details of these commands.</p>
1553</body>
1554</html>
Note: See TracBrowser for help on using the repository browser.