FCM System User Guide: FCM Command Reference
Author: FCM development team
Keywords: FCM, user guide, command reference

# FCM Command Reference

## fcm Configuration File

The FCM system uses simple line based text files to store configuration settings. All configuration files used by FCM are based on the same principles:

- All configurations are stored in plain text files.
- A line in a file may contain a configuration setting or a comment.
- Blank lines are ignored.
- A line that begins with a `#` is a comment line.
- Each configuration line has a label, a value and optionally a trailing comment. For example:

      my::label  this is the value  # some comment

- A label in a configuration line may contain any non-space character. A space character marks the end of the label.
- Words or fields in the label are normally delimited by the double colon (`::`).
- The first non-space character after the label is the beginning of the value. The value may contain space characters. The newline character or the character sequence `" # "` marks the end of the value.
- The first non-space character after the character sequence `" # "` at the end of the value is the comment. The comment is normally ignored by the parser of the configuration file.
- If the last character of the value is a backslash "\", the next non-comment line will be the continuation of the current line. Please note that trailing spaces before the continuation mark are preserved, and leading spaces are removed from the beginning of a continuation. If you want to have leading spaces in a continued line, start the line with a backslash "\" before the leading spaces. It is also worth bearing in mind that the backslash "\" character is only significant if it appears at the end of a value or the beginning of a continuation line. It is not a special character if it appears elsewhere. For example:

      foo bar\
          egg\
          ham
      # will become:
      foo bareggham

      foo bar \
          egg \
          ham
      # will become:
      foo bar egg ham

      foo bar\
          \ egg\
          \ ham
      # will become:
      foo bar egg ham

      foo bar\
          \ egg\ham
      # will become:
      foo bar egg\ham

The FCM central and user configuration files can be used to add or modify some of the default settings of FCM. When the fcm command is invoked, it normally attempts to search for a central configuration file at `$BINDIR/../etc/fcm.cfg` and then `$BINDIR/fcm.cfg`, where `$BINDIR` is the container directory of the fcm command. If a central configuration file can be located, the settings in the file will replace the pre-defined ones. After searching/reading the central configuration file, the system will attempt to search for a user configuration file located at `$HOME/.fcm` of the current user. If such a file can be found, its settings will replace the pre-defined ones as well as those defined in the central configuration file.

For information on the valid entries in the central and user configuration files, please refer to the Annex: Declarations in FCM central/user configuration file.

## fcm build

#### Usage

fcm build [OPTIONS...] [CFGFILE]

#### Description

`fcm build` invokes the FCM build system.

The path to a valid build configuration file `CFGFILE` may be provided as either a URL or a pathname. Otherwise, the build system searches the default locations for a build configuration file.

If no option is specified, the system uses the "`-s 5 -t all -j 1 -v 1`" by default.

- The "`-a [--archive]`" option can be specified to switch on the archive mode. In archive mode, sub-directories produced by the build will be archived in tar format at the end of a successful build. This option should not be used if the current build is intended to be re-used as a pre-compiled build.
- If the "`-f [--full]`" option is specified, the build system will attempt to perform a full/clean build by removing any previous build files. Otherwise, the build system will attempt to perform an incremental build where appropriate.
- When the build system is invoked, it sets a lock file in the build root directory to prevent other extracts/builds taking place in the same location. The lock file is normally removed when the build system exits. (However, a lock file may be left behind if the user interrupts the command, e.g. by typing `Ctrl-C`.) You can bypass the check for lock files by using the "`--ignore-lock`" option.
- The "`-j [--jobs] arg`" option can be used to specify the number of parallel jobs that can be handled by the make command. The argument `arg` must be a natural integer to represent the number of jobs. If not specified, the default is to perform serial make (i.e. 1 job).
- The "`-s [--stage] arg`" option can be used to limit the actions performed by the build system, up to a named stage determined by the argument `arg`. If not specified, the default is 5. The stages are:
  - "1", "s" or "setup": stage 1, read configuration and set up the build
  - "2", "pp" or "pre_process": stage 2, perform pre-processing for source files that require pre-processing
  - "3", "gd" or "generate_dependency": stage 3, scan source files for dependency information and generate make rules for them
  - "4", "gi" or "generate_interface": stage 4, generate interface files for Fortran 9X source files
  - "5", "m", "make": stage 5, invoke the make command to build the project
- The "`-t [--targets] arg`" can be used to specify the targets to be built. The argument `arg` must be a colon-separated list of valid targets. If not specified, the default target to be built is the "all" target.
- The "`-v [--verbose] arg`" option can be specified to alter the level of diagnostic output. The argument `arg` to this option must be an integer greater than or equal to 0. The verbose level increases with this number. If not specified, the default verbose level is 1.

For further details, please refer to the chapter on The Build System.

#### Alternate Names

bld

## fcm extract

#### Usage

fcm extract [OPTIONS...] [CFGFILE]

#### Description

`fcm extract` invokes the FCM extract system.

The path to a valid extract configuration file `CFGFILE` may be provided as either a URL or a pathname. Otherwise, the extract system searches the default locations for an extract configuration file.

- If the "`-f [--full]`" option is specified, the extract system will attempt to perform a full/clean extraction by removing any previous extracted files. Otherwise, the extract system will attempt to perform an incremental extraction where appropriate.
- When the extract system is invoked, it sets a lock file in the extract destination root directory to prevent other extracts/builds taking place in the same location. The lock file is normally removed when the extract system exits. (However, a lock file may be left behind if the user interrupts the command, e.g. by typing `Ctrl-C`.) You can bypass the check for lock files by using the "`--ignore-lock`" option.
- The "`-v [--verbose] arg`" option can be specified to alter the level of diagnostic output. The argument `arg` to this option must be an integer greater than or equal to 0. The verbose level increases with this number. If not specified, the default verbose level is 1.

For further details, please refer to the chapter on The Extract System.

#### Alternate Names

ext

## fcm cmp-ext-cfg

#### Usage

fcm cmp-ext-cfg [--verbose (-v)] [--wiki (-w) arg] CFG1 CFG2

#### Description

`fcm cmp-ext-cfg` compares the extract configurations of two similar extract configuration files CFG1 and CFG2. It reports repository branches and source directories that are declared in one file but not another. If a source directory is declared in both files, it compares their versions. If they differ, it uses `svn log` to obtain a list of revision numbers at which changes are made to the source directory. It then reports, for each declared repository branch, the revisions at which changes occur in their declared source directories.

The list of revisions for each declared repository branch is normally printed out as a simple list in plain text.

- You can use the `--verbose` option to print also the log of each revision.
- Alternatively, you can use the `--wiki` option to change that into an tabular output suitable for inserting into a Trac wiki page. The `--wiki` option must be specified with an argument, which must be the Subversion URL or FCM URL keyword of a FCM project associated with the intended Trac system. The URL allows the command to work out the correct wiki syntax to use.

## fcm gui

#### Usage

fcm gui [DIR]

#### Description

`fcm gui` starts up the FCM GUI. If DIR is specified then this is used as the working directory.

For further details, please refer to the section Using the GUI.

## fcm Subversion Subcommands

This section describes all of the Subversion related commands supported by `fcm`.

- In some cases `fcm` simply passes the command directly on to `svn` (after expanding any URL keywords). These commands are listed in the Other Subversion Commands section.
- Where `fcm` adds functionality these commands are discussed individually.
- In all cases, all the command abbreviations supported by `svn` work with `fcm`.

### fcm add

#### Usage

fcm add --check (-c)

fcm add <any valid svn add options>

#### Description

`fcm add` supports all of the switches and arguments supported by `svn add` (refer to the Subversion book for details).

In addition, `fcm add` supports a `--check` switch (no other switches or arguments). When this is specified then `fcm` checks for any files which are not currently under version control (i.e. those marked with a "?" by `svn status`) and prompts to see if you wish to schedule them for addition at the next commit (using `svn add`).

For further details refer to the section Adding and Removing Files.

### fcm branch

#### Usage

fcm branch [--info (-i)] [--verbose (-v)] [--show-children] [--show-siblings] [--show-other] [--show-all (-a)] [TARGET]

fcm branch --delete (-d) [--verbose (-v)] [--show-children] [--show-siblings] [--show-other] [--show-all (-a)] [--svn-non-interactive] [--non-interactive] [--password arg] [TARGET]

fcm branch --create (-c) --name (-n) arg [--type (-t) arg] [--rev-flag arg] [--ticket (-k) arg] [--branch-of-branch] [--svn-non-interactive] [--non-interactive] [--password arg] [--revision arg] [TARGET]

fcm branch --list (-l) [--user (-u) arg] [--verbose (-v)] [--revision arg] [TARGET]

#### Description

If TARGET is specified, it must either be a URL or a path to a local working copy. Otherwise, the current working directory must be a working copy. For `--info` and `--delete`, the specified URL or that of the working copy must be a valid branch (including the trunk) in a standard FCM project. For `--create` and `--list`, it must be a valid URL of a standard FCM project.

`fcm branch --info` displays information about a branch.

- This is the default if no options are specified (e.g. if you just issue the command `fcm br`).
- This command performs the following actions:
  - It reports the basic information of the branch URL, as returned by "svn info".
  - If `--verbose` is set, it also prints the log message of the last change revision.
  - If the URL is not the trunk:
    - It reports the branch creation information, including the revision, author and date. It also reports the parent URL@REV of the branch. If `--verbose` is set, it prints the log message of the branch creation revision.
    - If the branch does not exist at the HEAD, it reports the revision at which it is deleted.
    - It reports the last merges into and from the parent branch. If `--verbose` is set, it also prints the log message of these merges.
    - It reports the revisions available for merging into and from the parent branch. If `--verbose` is set, it also prints the log message of these revisions.
  - If `--show-children` is specified, it lists the current children of the branch and their create revisions. Where appropriate, it reports the revision of each child, which is last merged from/into the current branch. It also reports the available merges from/into each child into the current branch.
  - If `--show-siblings` is specified, it reports recent merges from/into sibling branches. It also reports the available merges from/into sibling branches where recent merges are detected. If `--verbose` is set, it also prints the log message of these merges.
  - If `--show-other` is specified, it reports all custom and reverse merges into the current branch.
  - You can turn on `--show-children`, `--show-siblings` and `--show-other` simultaneously by specifying `--show-all`.
- For further details refer to the section Getting Information About Branches.

`fcm branch --delete` deletes a branch.

- This command performs the following actions:
  - Firstly, it provides exactly the same output as `fcm branch --info`.
  - If you do not specify the `--non-interactive` option, it starts an editor (using a similar convention as commit) to allow you to add further comment to the commit log message. A standard commit log template is provided for you below the line that says "--This line will be ignored and those below will be inserted automatically--". If you need to add any extra message to the log, please do so above this line. When you exit the editor, the command will report the commit log before prompting for confirmation that you wish to proceed with deleting the branch (it aborts if not).
- If you specify the `--non-interactive` option, the command will not prompt you for anything. (The `--svn-non-interactive` option is set automatically when you specify `--non-interactive`.)
- Subversion may prompt you for authentication if it is the first time you access the repository. The command fails if the authentication fails. If you specify the `--svn-non-interactive` option, Subversion will not prompt you for authentication. In such case, the command will simply fail if authentication is required. You can use the `--password` option to specify a password. Please note that the `--svn-non-interactive` option is always specified if you are running `branch --delete` from the FCM GUI. If authentication is required, you should specify your password using the `--password` option in "Other options".
- For further details refer to the section Deleting Branches.

`fcm branch --create` creates a new branch.

- You have to choose a name for your branch. This must be specified as the argument of the `--name (-n)` option. The name of the branch must contain only word characters, i.e. [A-Za-z0-9_].
- You can specify the type of branch you are creating using the `--type (-t)` option. The argument to the option must be one of the following:
  - DEV::USER - a development branch for the current user (e.g. branches/dev/<user_id>/<branch_name>)
  - DEV::SHARE - a shared development branch (e.g. branches/dev/Share/<branch_name>)
  - DEV - same as DEV::USER
  - TEST::USER - a test branch for the current user (e.g. branches/test/<user_id>/<branch_name>)
  - TEST::SHARE - a shared test branch (e.g. branches/test/Share/<branch_name>)
  - TEST - same as TEST::USER
  - PKG::USER - a package branch for the current user (e.g. branches/pkg/<user_id>/<branch_name>)
  - PKG::SHARE - a shared package branch (e.g. branches/pkg/Share/<branch_name>)
  - PKG::CONFIG - a configuration branch (e.g. branches/pkg/Config/<branch_name>)
  - PKG::REL - a release branch (e.g. branches/pkg/Rel/<branch_name>)
  - PKG - same as PKG::USER
  - CONFIG - same as PKG::CONFIG
  - REL - same as PKG::REL
  - SHARE - same as DEV::SHARE
  - USER - same as DEV::USER

  If the `--type` option is not specified, it defaults to DEV::USER.

- Your branch name will normally be prefixed by the revision number from which it is branched. (E.g. if the branch name is "my_branch" and you are branching from revision 123 of the trunk, the final name will be "r123_my_branch".) If this revision number is associated with a revision keyword, the keyword will be used in place of the revision number. (E.g. if revision 123 is associated with the keyword vn6.1, "r123_my_branch" will become "vn6.1_my_branch".) You can alter this behaviour using the argument to the `--rev-flag` option. If NORMAL is specified, it uses the default behaviour. If NUMBER is specified, it will always use the revision number as the prefix, regardless of whether the revision number is defined as a keyword or not. If NONE is specified, it will not add a prefix to your branch name.
- The command will normally create your branch from the last changed revision of the trunk of the specified project.
  - You can use the `--revision` option to specify an earlier revision of the source.
  - If the source URL is a valid URL of a branch in a standard FCM project, you can use the `--branch-of-branch` option to create a branch of the source branch.
- The `--ticket` option can be used to specify one or more Trac ticket numbers, which the branch relates to. Multiple ticket numbers can be set by specifying this option multiple times, or by using a comma-separated list of ticket numbers as the argument to the option. If set, the line "Relates to ticket #<number>[, #<number>...]" will be added to the template commit log.
- If you specify the `--non-interactive` option, the command will not prompt you for anything. (The `--svn-non-interactive` option is set automatically when you specify `--non-interactive`.)
- Subversion may prompt you for authentication if it is the first time you access the repository. The command fails if the authentication fails. If you specify the `--svn-non-interactive` option, Subversion will not prompt you for authentication. In such case, the command will simply fail if authentication is required. You can use the `--password` option to specify a password. Please note that the `--svn-non-interactive` option is always specified if you are running `branch --create` from the FCM GUI. If authentication is required, you should specify your password using the `--password` option in "Other options".
- This command performs the following actions:
  - It determines the last changed revision of the trunk/source branch at the HEAD (or the specified) revision.
  - It constructs the branch name from the option you have specified and reports it.
  - It checks that the chosen branch name does not currently exist. If so, the command aborts with an error.
  - If you do not specify the `--non-interactive` option, it starts an editor (using a similar convention as commit) to allow you to add further comment to the commit log message. A standard commit log template is provided for you below the line that says "--This line will be ignored and those below will be inserted automatically--". If you need to add any extra message to the log, please do so above this line. When you exit the editor, the command will report the commit log before prompting for confirmation that you wish to proceed (it aborts if not).
  - It uses `svn mkdir` to create any sub-directories required for the copy to succeed.
  - It uses `svn copy` to create the branch.
- For further details refer to the section Creating Branches.

`fcm branch --list` lists the branches created by you (and/or other users) at the HEAD revision of a standard FCM project.

- By default, it lists the branches created by you at the HEAD revision. To display the branches at a different revision, you can use the `--revision arg` option.
- You can specify a list of users with the `--user arg` option, where "arg" is a colon separated list of users. (Alternatively, you can specify this option multiple times.) When this option is set, the command lists the branches created by the specified list of users instead.
- By default, it lists the branches in the FCM URL keyword format. If you want to print the full Subversion URL of the branches, you can use the `--verbose` option.
- The command returns 0 (success) if one or more branches is found for the specified users, or 1 (failure) if no branch is found.

#### Alternate Names

br

### fcm commit

#### Usage

fcm commit [--dry-run] [--svn-non-interactive] [--password arg] [PATH]

#### Description

`fcm commit` sends changes from your working copy in the current working directory (or from PATH if it is specified) to the repository.

- This command performs the following actions:
  - It checks that the current working directory (or PATH if it is specified) is a working copy. (If not, it aborts with an error).
  - It always commits from the top level of the working copy.
  - It checks that there are no files in conflict, missing or out of date (it aborts if there are).
  - It checks that any files which have been added have the svn:executable property set correctly (in case a script was added before the execute bit was set correctly).
  - It reads in any existing commit message and strips out any previous status info (it starts with an empty file if there is none).
    - The commit message is stored in the file `#commit_message#` in the top level of your working copy.
  - If you have run the merge command before the commit, you will get a standard commit log template below the line that says "--This line will be ignored and those below will be inserted automatically--". If you need to add any extra message to the log, please do so above this line.
  - It adds the following line to the commit message:
    `--This line, and those below, will be ignored--`
    This line, and anything below it, is automatically ignored by `svn commit`.
  - It adds current status information to the commit message showing the list of modifications.
  - It starts an editor to allow you to edit the commit message.
    - If defined, the environment variable SVN_EDITOR specifies the editor.
    - Otherwise the environment variable VISUAL specifies the editor.
    - Otherwise the environment variable EDITOR specifies the editor.
    - Otherwise the editor nedit is used.
  - It reports the commit message and then asks if you want to proceed (it aborts if not).
  - It calls `svn commit` to send the changes to the repository.
  - It calls `svn update` to bring your working copy up to the new revision.
- Subversion may prompt you for authentication if it is the first time you access the repository. The command fails if the authentication fails. If you specify the `--non-interactive` option, Subversion will not prompt you for authentication. In such case, the command will simply fail if authentication is required. You can use the `--password` option to specify a password. Please note that the `--svn-non-interactive` option is always specified if you are running "commit" from the FCM GUI. If authentication is required, you should specify your password using the `--password` option in "Other options".
- The `--dry-run` switch prevents the command from committing any changes. This can be used to allow you to add notes to your commit message whilst you are still preparing your change.

For further details refer to the section Committing Changes.

#### Alternate Names

ci

### fcm conflicts

#### Usage

fcm conflicts [PATH]

#### Description

`fcm conflicts` helps you to resolve any text files in your working copy which have conflicts by using the graphical merge tool xxdiff. If PATH is set, it must be a working copy, and the command will operate in it. If PATH is not set, the command will operate in your current working directory.

- This command performs the following actions:
  - For each text file reported as being in conflict (i.e. marked with a "C" by `svn status`) it calls `xxdiff`.
  - If `xxdiff` reports all conflicts resolved then if asks if you wish to run `svn resolved` on that file.

For further details refer to the section Resolving Conflicts.

#### Alternate Names

cf

### fcm delete

#### Usage

fcm delete --check (-c)

fcm delete <any valid svn delete options>

#### Description

`fcm delete` supports all of the switches, arguments and alternate names supported by `svn delete` (refer to the Subversion book for details).

- In addition, `fcm delete` supports a `--check` switch (no other switches or arguments). When this is specified then `fcm` checks for any files which are missing (i.e. marked with a "!" by `svn status`) and prompts to see if you wish to schedule them for deletion at the next commit (using `svn delete`).
- Subversion may prompt you for authentication if it is the first time you access the repository. The command fails if the authentication fails. If you specify the `--non-interactive` option, Subversion will not prompt you for authentication. In such case, the command will simply fail if authentication is required. Please note that the `--non-interactive` option is automatically specified if you are running "delete" from the FCM GUI and you have not checked the box "Check for files and directories...". If authentication is required, you should run "delete" in interactive mode on a command line.

For further details refer to the section Adding and Removing Files.

### fcm diff

#### Usage

fcm diff --branch (-b) [--graphical (-g) | --diff-cmd arg [--extensions (-x) arg] | --wiki | --trac (-t)] [TARGET]

fcm diff [--graphical (-g) | --diff-cmd arg [--extensions (-x) arg]] <any valid svn diff options>

#### Description

`fcm diff` supports all of the switches, arguments and alternate names supported by `svn diff` (refer to the Subversion book for details). In addition, `fcm diff` supports the following switches:

- If `--graphical` is specified, the command uses a graphical tool to display the differences. (The default graphical diff tool is xxdiff, but you can alter the behaviour by following the instruction discussed in the sub-section on Examining Changes.) This switch can be used in combination with all other valid switch (including `--branch`) except `--diff-cmd`, `--extensions`, `--trac` and `--wiki`.
- If `--branch` is specified, the command displays the differences between the target branch and its parent. This should show you the differences which you would get if you tried to merge the changes in the branch into its parent. It performs the following actions:
  - If TARGET is specified, it must either be a URL or a path to a local working copy. Otherwise, the current working directory must be a working copy. The specified URL or that of the working copy must be a valid branch in a standard FCM project.
  - It determines the base of the branch relative to its parent. This is adjusted to account for any merges from the branch to its parent or vice-versa.
  - It reports what path and revision it is comparing against.
  - If `--trac` is specified, it launches Trac with your default web browser to display it. Note: if TARGET is a working copy, local changes in it will not be displayed by Trac.
  - If `--wiki` is specified, it prints a Trac wiki syntax for the differences between the base and the specified branch.
  - Otherwise, it calls `svn diff` to report the differences between the base and the specified branch (or working copy).

For further details refer to the section Examining Changes.

### fcm merge

#### Usage

fcm merge [--dry-run] [--non-interactive] [--verbose (-v)] SOURCE

fcm merge --custom --revision N[:M] [--dry-run] [--non-interactive] [--verbose (-v)] SOURCE

fcm merge --custom [--dry-run] [--non-interactive] [--verbose (-v)] URL1[@REV1] URL2[@REV2]

fcm merge --reverse --revision [M:]N [--dry-run] [--non-interactive] [--verbose (-v)]

#### Description

`fcm merge` allows you to merge changes from a source into your working copy.

Before it begins, the command does the following:

- If a SOURCE/URL is specified, it can be a full URL or a partial URL starting at the branches, trunk or tags level.
  - If a partial URL is given, and the path name does not begin with "trunk", "tags" or "branches" then "branches/" is automatically added to the beginning of your path.
- It determines the TARGET URL by examining your working copy.
- If the current directory is not the top of your working copy, it changes the current directory to the top of your working copy.
- If your working copy is not pointing to a branch of a project managed by FCM, the command aborts with an error.
- If you do not specify the `--non-interactive` option, it checks for any local modifications in your working copy. If it finds any it reports them and asks you to confirm that you wish to continue (it aborts if not).

If neither `--custom` nor `--reverse` is specified, the command defaults to the automatic mode. Automatic merges are used to merge changes between two directly related branches, (i.e. the branches must either be created from the same parent or have a parent/child relationship). These merges are tracked by FCM and can be used by subsequent FCM commands. The merge delta is calculated by doing the following:

- It checks that the SOURCE and TARGET are directly related.
- It determines the base revision and path of the common ancestor of the SOURCE and TARGET.
- The base revision and path are adjusted to account for any merges from the SOURCE to the TARGET or vice-versa.
- It reports the revisions from SOURCE available for merging into TARGET. If the `--verbose` option is set, it prints the log for these revisions. It aborts if no revision is available for merging.
- If there are 2 or more revisions available for merging and you do not specify the `--non-interactive` target, it asks you which revision of the SOURCE you wish to merge from. The default is the last changed revision of the SOURCE. The merge delta is between the base and the specified revision of the SOURCE.
- If your working copy is a sub-tree of the TARGET, it ensures that the SOURCE contains only changes in the same sub-tree. Otherwise, the merge is unsafe, and the command will abort with an error.

  N.B.: The command looks for changes in the SOURCE by going through the list of changed files since the the SOURCE was last merged into the TARGET. (If there is no previous merge from SOURCE to TARGET, the common ancestor is used.) It is worth noting that there are situations when the command will regard your merge as "unsafe" (and so will fail incorrectly) even if the changes in the SOURCE outside of the current sub-tree will result in a null merge. This can happen if the changes are the results of a previous merge from the TARGET to the SOURCE or if these changes have been reversed. In such case, you will have to perform your merge in a working copy of a full tree.

The `--custom` mode is useful if you need to merge changes selectively from another branch. The custom mode can be used in two forms:

- In the first form, you must specify a SOURCE as well as a revision (range) using the `--revision` option. If you specify a single revision N, the merge delta is between revision N - 1 and revision N of the SOURCE. Otherwise, the merge delta is between revision N and revision M, where N < M.
- In the second form, you must specify two URLs. The merge delta is simply between the two URLs. (For each URL, if you do not specify a peg revision, the command will peg the URL with its last changed revision.)

N.B. Unlike automatic merges, custom merges are not tracked or used by subsequent FCM `diff` or `merge` commands, (although `branch --info` can be set to report them). Custom merges are always allowed, even if your working copy is pointing to a sub-tree of a branch. However, there is no checking mechanism to ensure the safety of your sub-tree custom merge so you should only do this if you are confident it is what you want. Therefore, it is recommended that you use automatic merges where possible, and use custom merges only if you know what you are doing.

The `--reverse` mode is useful if you need to reverse a changeset (or a range of changesets) in the current branch of the working copy. In this mode, you must specify a revision (range) using the `--revision` option. If you specify a single revision N, the merge delta is between revision N and revision N - 1 of the current branch. Otherwise, the merge delta is between revision M and revision N, where M > N.

N.B. Like custom merges, reverse merges are not tracked or used by subsequent FCM `diff` or `merge` commands, (although `branch --info` can be set to report them). Likewise, reverse merges in sub-trees are always allowed, although there is no checking mechanism to ensure the safety of your sub-tree reverse merge.

Once the merge delta is determined, the command performs the following:

- If you set the `--dry-run` option or if you are running in the interactive mode, it reports what changes will result from performing this merge by calling `svn merge --dry-run`.
  - It prints the actual `svn merge --dry-run` command if the `--verbose` option is specified.
  - If you specify the `--dry-run` option, it exits after reporting what changes will result from performing the merge.
- If you are running in the interactive mode, it asks if you want to go ahead with the merge (it aborts if not).
- It performs the merge by calling `svn merge` to apply the delta between the base and the SOURCE on your working copy.
  - It prints the actual `svn merge` command if the `--verbose` option is specified.
- It adds a standard template into the commit message to provide details of the merge. The template is written below the line that says "--This line will be ignored and those below will be inserted automatically--". The fcm commit command will detect the existence of the template, so that you will not be able to alter it by accident.
  - The commit message is stored in the file `#commit_message#` in the top level of your working copy. It is created by the merge command if it does not already exist.

For further details refer to the section Merging.

### fcm mkpatch

#### Usage

fcm mkpatch [OPTIONS] URL [OUTDIR]

#### Description

`fcm mkpatch` creates patches from the specified revisions of the specified URL, which must be a branch URL of a valid FCM project. If the URL is a sub-directory of a branch, it will use the root of the branch.

If OUTDIR is specified, the output is sent to OUTDIR. Otherwise, the output will be sent to a default location in the current directory (`$PWD/fcm-mkpatch-out/`). The output directory will contain the patch for each revision as well as a script for importing the patch.

If a revision is specified using the `--revision` option, it will attempt to create a patch based on the changes at that revision. If a revision is not specified, it will attempt to create a patch based on the changes at the HEAD revision. If a revision range is specified, it will attempt to create a patch for each revision in that range (including the change in the lower range) where changes have taken place in the URL. No output will be written if there is no change in the given revision (range).

The `--exclude` option can be used to exclude a path in the URL. The specified path must be a relative path of the URL. Glob patterns such as `*` and `?` are acceptable. Changes in an excluded path will not be considered in the patch. A changeset containing changes only in the excluded path will not be considered at all.

The `--organisation` option can be used to specify the name of your organisation. The command will attempt to parse the commit log message for each revision in the patch. It will remove all merge templates, replace links to Trac tickets with a simple string, and add information about the original changeset. If you specify the name of your organisation, it will replace Trac ticket links such as `"ticket:123"` to `"$organisation ticket 123"`, and report the orginal changeset with a message such as `"$organisation changeset 1000"`. Otherwise, it will report without the organisation name, e.g. `"Original ticket 123"` and `"Original changeset 1000"`.

Within the output directory are the "patches" and the log message file for each revision. It also contains a generated script `fcm-import-patch` for importing the patches. The user of the script can invoke the script with either a URL or a working copy argument, and the script will attempt to import the patches into the given URL or working copy.

It is worth noting that changes in Subversion properties, including changes in executable permissions, are not handled by the import script.

### fcm switch

#### Usage

fcm switch [OPTIONS] URL [PATH]

fcm switch --relocate [OPTIONS] FROM TO [PATH]

#### Description

`fcm switch` supports the arguments and alternate names supported by `svn switch`. If `--relocate` is specified, it supports all options supported by `svn switch`. Otherwise, it supports `--non-interactive`, `-r [--revision]` and `-q [--quiet]` only. (Please refer to the Subversion book for details).

If `--relocate` is specified, FCM will pass the options and arguments directly to the corresponding Subversion command. Otherwise, FCM will ensure that your working copy switches safely through the following actions:

- If PATH (or the current working directory if PATH is not specified) is not at the top of a working copy, the command will automatically search for the top of the working copy, and the switch command will always apply recursively from that level.
- You can specify only the "branch" part of the URL, such as "trunk", "branches/dev/fred/r1234_bob" or even "dev/fred/r1234_bob" and the command will work out the full URL for you.
- If you do not specify the `--non-interactive` option, it checks for any local modifications in your working copy. If it finds any it reports them and asks you to confirm that you wish to continue (it aborts if not).
- If you have some template messages in the `#commit_message#` file in the top level of your working copy, (e.g. after you have performed a merge), the command will report an error. You should remove the template message manually from the `#commit_message#` file before re-running `switch`.
- The command will analyse the current working copy URL and the specified URL to ensure that they are in the same project. If your working copy is a sub-tree of a project, the command will assume that you want the same sub-tree in the new URL.

For further details refer to the section Switching your working copy to point to another branch.

### fcm trac

#### Usage

fcm trac [--browser (-b) ARG] [PATH]

#### Description

`fcm trac` invokes the web-browser to launch the corresponding URL of the web-based repository browser (currently Trac browser) to view the Subversion repository specified by PATH.

- If the `--browser` option is specified, ARG must be a valid command to a web browser. If this option is not specified, the default is to use "firefox", or whatever setting you have declared in the user configuration file (`$HOME/.fcm`) using the label "SET::MISC::WEB_BROWSER". For example:

      set::misc::web_browser  mozilla

- If PATH is specified, it must be a path to a local working copying, a Subversion URL or a FCM URL keyword. If PATH is not specified, it is set to ".", the current working directory. If PATH is a directory in the local file system, the command will determine whether it is a working copy. If so, its associated Subversion URL will be used. The command fails if the directory is not a working copy. If PATH is a Subversion URL or a FCM URL keyword, the URL can be "pegged" with a revision number using the "@" symbol. For example, to view the trunk of the FCM repository at revision 400, you can use "fcm:fcm_tr@400". The URL declared by or associated with PATH must also be associated with a Trac browser URL, which is declared using the "SET::TRAC::<pck>" label in the FCM central/user configuration file. The command fails if an associated Trac browser URL is not found.

#### Alternate Names

www

### Other Subversion Commands

Other `svn` commands are supported by `fcm` without any change in functionality, with the following minor enhancements:

- Where appropriate, FCM performs repository and revision keywords expansion.
- The `fcm checkout` command fails if you attempt to checkout into an existing working copy.
- FCM prints the corresponding `svn` command, except for `cat` and any commands with the `--xml` option specified.

The following is a list of the commands:

- svn blame
- svn cat
- svn checkout
- svn cleanup
- svn copy
- svn export
- svn import
- svn info
- svn list
- svn log
- svn lock
- svn mkdir
- svn move
- svn propdel
- svn propedit
- svn propget
- svn proplist
- svn propset
- svn resolved
- svn revert
- svn status
- svn unlock
- svn update

Please refer to the Subversion book for details of these commands.