Author: FCM team

# FCM: User Guide: FCM Command Reference

## Introduction

This chapter describes all commands supported by `fcm`. `fcm` has its own set of functionalities, but it also wraps all `svn` commands.

In most wrappers to `svn`, `fcm` simply passes the command directly on to `svn` (after expanding any keywords). These commands are listed in the Other Subversion Commands section.

Where `fcm` adds more functionality to an `svn` command, the command is discussed individually.

All command abbreviations supported by `svn` work with `fcm`.

Subversion may prompt you for authentication if it is the first time you write to a repository. The command fails if the authentication fails. A command may support the `--non-interactive` or `--svn-non-interactive` option. If such an option is specified, Subversion will not prompt you for authentication, and the command will simply fail if authentication is required. Please note that the option is normally specified if you are running a command from the FCM GUI. If authentication is required, you should run the command in interactive mode on a command line, or by using the `--password=PASSWORD` option in the `Other options`.

## Environment Variables

The following environment variables are used by the `fcm` command.

FCM_CONF_PATH='/path/to/conf1 /path/to/conf2'
  This variable is mainly used to test FCM. If specified, override the paths for site and user configuration files. The value should be a space delimited list of paths where FCM site and user configuration files can be found. The value can also be set to a null string to allow FCM to run with no site or user configuration. If not defined, the default to look for site and user configuration files from `$FCM_HOME/etc/fcm/` and `~/.metomi/fcm/` (where $FCM_HOME/bin/fcm is where the `fcm` command is invoked.
FCM_DEBUG=true
  If specified, raises the verbosity to the debug level. This is useful in debugging especially if a command does not accept a `-v` option.
FCM_GRAPHIC_DIFF=`command`
  (Deprecated) Specifies an alternate command for doing graphical diff tool. The external configuration file should be used instead of this environment variable.
FCM_GRAPHIC_MERGE=`command`
  (Deprecated) Specifies an alternate command for doing graphical merge tool. The external configuration file should be used instead of this environment variable.
FCM_VERBOSE=`N`
  (Deprecated) An alternate way to specify the verbosity for FCM 1 extract and build systems.

## fcm add

Usage
  `fcm add --check (-c) [PATH]`
  `fcm add <any valid svn add options>`
Description

  In the 1st form (i.e. `fcm add --check`), the system checks for any files which are not currently under version control (i.e. those marked with a `?` by `svn status`) and prompts the user to make a decision on whether to schedule them for addition at the next commit (using `svn add`).

  In the 2nd form (i.e. without the `--check` option), `fcm add` simply pass control to `svn add`. (For detail of usage, please refer to the Subversion book.)

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

## fcm branch

Description

  Deprecated. The 4 usages of this command have been replaced by the following commands:

  `fcm branch --create --name NAME`
    fcm branch-create
  `fcm branch --delete`
    fcm branch-delete
  `fcm branch [--info]`
    fcm branch-info
  `fcm branch --list`
    fcm branch-list
Alternate Names
  br

## fcm branch-create

Usage
  `fcm branch-create [OPTIONS] NAME [SOURCE]`
Description

  Creates a new branch.

  The 1st argument NAME must be the short name for your branch. The name of the branch must contain only characters in the set `[A-Za-z0-9_-.]`. If the `--ticket=N` option is not specified and NAME contains only a list of positive integers separated by `[_-]` (an underscore or a hyphen), the command will assume that NAME also specifies the related ticket numbers.

  If the 2nd argument SOURCE is specified, it must either be a URL or a path to a working copy of a standard FCM project. Otherwise, the current working directory must be a working copy of a standard FCM project.

  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 and change summary is provided for you below the line that says `--Add your commit message ABOVE - do not alter this line or those below--`. 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 copy` to create the branch.

  For further details refer to the section Creating Branches.

Options
  `--branch-of-branch`, `--bob`
    If the source URL is a valid URL of a branch in a standard FCM project, this option tells the system to create a branch of the source branch. Otherwise, it will normally create a branch from the trunk.
  `--non-interactive`
    Tells the system not to prompt for anything. (The `--svn-non-interactive` option is set automatically when you specify `--non-interactive`.)
  `--password=PASSWORD`
    Specifies the password for authentication.
  `--rev-flag=NONE|NORMAL|NUMBER`
    Alters the branch name prefix behaviour. 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`.) 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.
  `--svn-non-interactive`
    Tells the system to run `svn` in non-interactive mode.
  `--switch`, `-s`
    `fcm switch` the current working directory (if it contains a relevant working copy) to point to the newly created branch after the branch is created.
  `--ticket=N`, `-k N`
    Specifies 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 ticket numbers will be included in the commit log message.
  `--type=TYPE`, `-t TYPE`
    Specifies the type of branch to create. The argument to the option must be one of the following:
    `DEV::USER`, `DEV`, `USER` (default)
      A development branch for the current user (e.g. `branches/dev/<user_id>/<branch_name>`)
    `DEV::SHARE`, `SHARE`
      A shared development branch (e.g. `branches/dev/Share/<branch_name>`)
    `TEST::USER`, `TEST`
      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>`)
    `PKG::USER`, `PKG`
      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`, `CONFIG`
      A configuration branch (e.g. `branches/pkg/Config/<branch_name>`)
    `PKG::REL`, `REL`
      A release branch (e.g. `branches/pkg/Rel/<branch_name>`)
Alternate Names
  bcreate, bc

## fcm branch-delete

Usage
  `fcm branch-delete [OPTIONS] [TARGET]`
Description

  Deletes a branch.

  If TARGET is specified, it must either be a URL or a path to a local working copy of a valid branch of a standard FCM project. Otherwise, the current working directory must be a working copy of a valid branch of a standard FCM project.

  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 and change summary is provided for you below the line that says `--Add your commit message ABOVE - do not alter this line or those below--`. 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).

  For further details refer to the section Deleting Branches.

Options

  The command supports all options of fcm branch-info as well as the following:

  `--non-interactive`
    Tells the system not to prompt for anything. (The `--svn-non-interactive` option is set automatically when you specify `--non-interactive`.)
  `--password=PASSWORD`
    Specifies the password for authentication.
  `--svn-non-interactive`
    Tells the system to run `svn` in non-interactive mode.
  `--switch`, `-s`
    If SOURCE not specified in the argument list, `fcm switch` the current working copy to point to the trunk after the branch deletion.
Alternate Names
  bdelete, bdel, brm

## fcm branch-diff

Usage
  `fcm branch-diff [OPTIONS] [TARGET]`
Description

  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.

  If an argument 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.

  The command 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 then reports what path and revision it is comparing against using `svn diff` or otherwise.

  For further details refer to the section Examining Changes.

Options
  `--diff-cmd=COMMAND`
    Option passed to `svn diff`.
  `--extensions=EXT`, `-x EXT`
    Option passed to `svn diff`.
  `--graphical`, `-g`
    Tells the `svn diff` to use 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 should not be used with `--diff-cmd`, `--extensions`, `--trac` and `--wiki`.
  `--summarize`, `--summarise`
    Reports using `svn diff --summarize`.
  `--xml`
    Used with --summarise to change output format to XML.
  `--trac`, `-t`
    Launches Trac with your default web browser to report the diff. Note: if TARGET is a working copy, local changes in it will not be displayed.
  `--wiki`, `-w`
    Prints a Trac wiki syntax to represent the diff.
Alternate Names
  bdiff, bdi

## fcm branch-info

Usage
  `fcm branch-info [OPTIONS] [TARGET]`
Description

  Displays information about a branch.

  If the argument TARGET is specified, it must either be a URL or a path to a local working copy of a valid branch of a standard FCM project. Otherwise, the current working directory must be a working copy of a valid branch of a standard FCM project.

  It 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.
  - It reports relationship with other branches, depending on options.

  For further details refer to the section Getting Information About Branches.

Options
  `--show-all`, `-a`
    Turns on `--show-children`, `--show-other` and `--show-siblings`.
  `--show-children`
    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.
  `--show-other`
    Reports all custom and reverse merges into the current branch.
  `--show-siblings`
    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.
  `--verbose`, `-v`
    Increases the verbosity.
Alternate Names
  binfo

## fcm branch-list

Usage
  `fcm branch-list [OPTIONS] [TARGET ...]`
Description

  Searches and lists branches in projects. By default, it lists only branches created by the current user.

  If no TARGET is specified, the current working directory is assumed to be the target. Each target must either be a URL[@REV] or a PATH[@REV] to a working copy of a standard FCM project.

Options
  `--only=DEPTH:PATTERN`
    Specify a regular expression to match at various depth. E.g. with the normal FCM branch naming convention, `--only=1:dev --only=2:fred` will display only the development branches owned by user ID `fred`. (This option is cumalative, and overrides the `--show-all` and `--user=PATTERN` options.)
  `--quiet`, `-q`
    Decreases verbosity. Only prints branches matching the search criteria.
  `--show-all`, `-a`
    Prints branches of all users. (This option overrides the `--user=USER` option.)
  `--url`
    Displays Subversion URL instead of FCM location keywords.
  `--user=PATTERN`, `-u PATTERN`
    Equivalent to `--only=2:^PATTERN$` for projects with the normal FCM branch naming convention. Lists branches created by the specified list of users instead of the current user. With the normal FCM branch naming convention, you can also list shared branches by specifying the user as `Share`, configuration branches by specifying the user as `Config` and release branches by specifying the user as `Rel`. (This option is cumalative.)
Alternate Names
  blist, bls

## fcm browse

Usage
  `fcm browse [OPTIONS] [TARGET ...]`
Description

  `fcm browse` 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 TARGET.

  If TARGET is specified, it must be a path to a local working copying, a Subversion URL or an FCM URL keyword. Otherwise, it is set to `.`, the current working directory. If TARGET 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. The Subversion URL must be associated with an FCM location keyword, so that the system knows how to map the Subversion URL to the web browser URL.

Options
  `--browser=COMMAND`, `-b COMMAND`
    If this option is specified, its argument COMMAND must be a valid command to a web browser. If this option is not specified, the default is to use `firefox`, or the browser setting in the external configuration files (i.e. `$FCM/etc/fcm/external.cfg` and `$HOME/.metomi/fcm/external.cfg`). For example:

        browser = konqueror

Alternate Names
  trac, www

## fcm build

Usage
  `fcm build [OPTIONS...] [CFGFILE]`
Description

  `fcm build` invokes the deprecated FCM 1 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.

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

Option

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

  `--archive`, `-a`
    This 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.
  `--clean`
    If this option is specified, the build system will parse the configuration file, remove contents generated by the build system in the destination and exit.
  `--full`, `-f`
    If this 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.
  `--ignore-lock`
    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 this option.
  `--jobs=N`, `-j N`
    This option can be used to specify the number of parallel jobs that can be handled by the `make` command. The argument N 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).
  `--stage=STAGE`, `-s STAGE`
    This option can be used to limit the actions performed by the build system, up to a named stage determined by the argument STAGE. 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 or make: Stage 5, invoke the `make` command to build the project
  `--targets=TARGETS`, `-t TARGETS`
    This option can be used to specify the targets to be built. The argument TARGETS must be a colon-separated list of valid targets. If not specified, the default to be built is the `all` target.
  `--verbose=N`, `-v N`
    This option can be specified to alter the level of diagnostic output. The argument N 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.
Alternate Names
  bld

## fcm cfg-print

Usage
  `fcm cfg-print [OPTIONS] [TARGET ...]`
Description

  Parses each FCM configuration file specified in the argument list, and prints the result to STDOUT.

Options
  `--fcm1`, `-f`
    If specified, targets should be in FCM 1 format. Otherwise, they should be in FCM 2 format.
Alternate Names
  cfg

## fcm cmp-ext-cfg

Usage
  `fcm cmp-ext-cfg [OPTIONS] CFG1 CFG2`
Description

  `fcm cmp-ext-cfg` compares the deprecated FCM 1 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.

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

## fcm commit

Usage
  `fcm commit [OPTIONS] [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.
    - The commit message is stored in the file `#commit_message#` in the top level of your working copy.
  - It adds the following line to the commit log message: `--Add your commit message ABOVE - do not alter this line or those below--`. This line, and anything below it, is automatically ignored by `svn commit`. If you need to add any extra message to the log, please do so above this line.
  - If you have run the merge command before the commit, you will get a standard commit log template below a line that says `--FCM message (will be inserted automatically)--`. Please do not try to alter this message (your changes will be ignored if you do).
  - It adds current status information to the commit message showing the list of modifications below a line that says `--Change summary (not part of commit message)--`.
  - 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 that will be sent to Subversion 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.

  For further details refer to the section Committing Changes.

Options
  `--dry-run`
    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.
  `--password=PASSWORD`
    Specifies the password for authentication.
  `--svn-non-interactive`
    Tells the system to run `svn` in non-interactive mode.
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

  In the 1st form (i.e. `fcm delete --check`), the system checks for any files which are missing (i.e. those marked with a `!` by `svn status`) and prompts the user to make a decision on whether to schedule them for deletion at the next commit (using `svn delete`).

  In the 2nd form (i.e. without the `--check` option), `fcm delete` simply pass control to `svn delete`. (For detail of usage, please refer to the Subversion book.)

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

## fcm diff

Usage
  `fcm diff [OPTIONS] [TARGET ...]`
Description

  Display the differences between two revisions or paths. `fcm diff` supports all of the arguments and alternate names supported by `svn diff` (refer to the Subversion book for details).

  For further details refer to the section Examining Changes.

Options

  `fcm diff` supports the following options in addition to the options of `svn diff` (refer to the Subversion book for details):

  `--graphical`, `-g`
    If this option 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 option can be used in combination with all other valid options except `--diff-cmd` and `--extensions`.
  `--summarise`
    This option is implemented in FCM as a wrapper to the Subversion `--summarize` option. It prints only a summary of the results.
  `--branch`, `-b`
    This usage is deprecated. It is replaced by the fcm branch-diff command.

## fcm export-items

Usage
  `fcm export-items [OPTIONS...] SOURCE`
Description

  `fcm export-items` exports directories in SOURCE as a list of versioned items. The SOURCE should be the URL of a branch in a Subversion repository with the standard FCM layout.

  This command is used to support a legacy working practice, in which directories in a source tree are regarded as individual versioned items.

  The configuration file should be in the deprecated FCM 1 configuration format. The label in each entry should be a path relative to the source URL. If the path ends in `*` then the path is expanded recursively and any sub-directories containing regular files are added to the list of relative paths to export. The value may be empty, or it may be a list of space separated conditions. Each condition is a conditional operator (`>`, `>=`, `<`, `<=`, `==` or `!=`) followed by a revision number. The command uses the revision log to determine the revisions at which the relative path has been updated in the source URL. If these revisions also satisfy the conditions set by the user, they will be considered in the export.

  For further details, please refer to System Administration > Maintaining alternate versions of namelists and data files.

Options
  `--config-file=PATH`, `--file=PATH`, `-f PATH`
    Specifies the path to the configuration file. (default=`$PWD/fcm-export-items.cfg`)
  `--directory=PATH`, `-C PATH`
    Specifies the path to the destination. (default=`$PWD`)
  `--new`, `-N`
    Specifies the new mode. In this mode, everything is re-exported. Otherwise, the system runs in incremental mode, in which the version directories are only updated if they do not already exist.

## fcm extract

Usage
  `fcm extract [OPTIONS...] [CFGFILE]`
Description

  `fcm extract` invokes the deprecated FCM 1 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.

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

Options
  `--clean`
    If this option is specified, the extract system will parse the configuration file, remove contents generated by previous extract in the destination and exit.
  `--full`, `-f`
    If this option is specified, the extract system will attempt to perform a full extract by removing any previous extracted files. Otherwise, the extract system will attempt to perform an incremental extract where appropriate.
  `--ignore-lock`
    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 this option.
  `--verbose=N`, `-v N`
    This option can be specified to alter the level of diagnostic output. The argument N 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.
Alternate Names
  ext

## 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 keyword-print

Usage
  `fcm keyword-print [OPTIONS] [TARGET ...]`
Description

  If no argument is specified, `fcm keyword-print` prints all the registered FCM location keywords. Otherwise, it prints the location and revision keywords according to the argument TARGET, which must be an FCM URL keyword, a Subversion URL or a path to a Subversion working copy.

Options
  `--verbose`, `-v`
    Prints implied location keywords as well.
Alternate Names
  kp

## fcm loc-layout

Usage
  `fcm loc-layout [OPTIONS] [TARGET ...]`
Description

  Parse the URL of a FCM/Subversion TARGET, and print its FCM layout information.

  If no argument is specified, TARGET is the current working directory.

  See also System Administration > Subversion > Repository Layout.

Options
  `--verbose`, `-v`
    Increase verbosity.

## fcm make

Usage
  `fcm make [OPTIONS] [DECLARATION ...]`
Description

  `fcm make` invokes the FCM make system, which is used to run the extract and build systems and other utilities.

  For further details, please refer to the chapter on FCM Make.

Arguments

  Each argument is considered to be a declaration line to append to the configuration file.

Options
  `--archive, -a`
    Switch on archive mode. In archive mode, intermediate files will be put into TAR-GZIP archives on completion, e.g. extract system: `.fcm-make/cache/extract/`, and build system: `build/include/` and `build/o/`.

    The archive mode is not suitable for a make that will be inherited or used by other makes.

  `--config-file-path=PATH, -F PATH`
    Specifies paths for searching configuration files specified in relative paths.
  `--config-file=PATH, --file=PATH, -f PATH`
    Specifies paths to the configuration files either as a URL or a pathname. (default=`fcm-make.cfg` in the current working directory)
  `--directory=PATH, -C PATH`
    Change directory to PATH before doing anything. (default=$PWD)
  `--ignore-lock`
    Ignores lock file. When the system is invoked, it sets up a lock file in the destination. The lock is normally removed when the system completes the make. While the lock file is in place, another make invoked in the same destination will fail. This option can be used to bypass this check.
  `--jobs=N, -j N`
    Specifies the number of (child) processes that can be run simultaneously.
  `--name=NAME`, `-n NAME`
    Specify a name for the make, so that the command will search for fcm-makeNAME.cfg instead of fcm-make.cfg, and will write context files in .fcm-makeNAME/ and log files as fcm-makeNAME.log, etc.
  `--new`, `-N`
    Removes items in the destination created by the previous make, and starts a new make.
  `--quiet, -q`
    Decreases the verbosity level.
  `--verbose, -v`
    Increases the verbosity level.

## fcm merge

Usage
  `fcm merge [OPTIONS] SOURCE`
  `fcm merge --custom --revision N[:M] [OPTIONS] SOURCE`
  `fcm merge --custom [OPTIONS] URL1[@REV1] URL2[@REV2]`
  `fcm merge --reverse [--revision [M:]N] [OPTIONS]`
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 or 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).
  Automatic mode (i.e. neither `--custom` nor `--reverse` is specified)

    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 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.

  Custom mode (i.e. `--custom` is specified)

    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.

  Reverse mode (i.e. `--reverse` is specified)

    The reverse mode is useful if you need to reverse a changeset (or a range of changesets) in the current source of the working copy. If a revision is not specified with `--revision=M:N`, it attempts to merge the delta COMMITTED:(COMMITTED - 1). If a single revision N is specified, the merge delta is N:(N - 1). Otherwise, the merge delta is between revision M: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 `--FCM message (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.
    - If the `--auto-log` option is specified in the automatic mode, it adds the log messages of the merged revisions as well as the standard template.

  For further details refer to the section Merging.

Options
  `--auto-log`
    In automatic mode, adds the log messages of the merged revisions in the commit log. Has no effect in other merge modes.
  `--dry-run`
    Tries operation but make no changes.
  `--non-interactive`
    Tells the system not to prompt for anything.
  `--revision=REV`, `-r REV`
    Specifies a revision or a revision range.
  `--verbose`, `-v`
    Prints extra information.

## 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.

  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.

Options
  `--exclude=PATH`
    Excludes 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. Multiple paths can be specified by using a colon-separated list of paths, or by specifying this option multiple times.
  `--organisation=NAME`
    Specifies 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 Trac links with a modified string, and add information about the original changeset. If you specify the name of your organisation, it will replace Trac links such as `ticket:123` with `$organisation_ticket:123`, and report the orginal changeset with a message such as `$organisation_changeset:1000`. If the organisation name is not specified then it defaults to `original`.
  `--revision=REV`, `-r REV`
    Specifies a revision or a revision range, at which the patch will be based on. 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).

## fcm project-create

Usage
  `fcm project-create [OPTIONS] PROJECT-NAME REPOS-ROOT-URL`
Description

  Create a new project and its trunk directory in a repository.

  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 and change summary is provided for you below the line that says `--Add your commit message ABOVE - do not alter this line or those below--`. 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).

Options
  `--non-interactive`
    Tells the system not to prompt for anything. (The `--svn-non-interactive` option is set automatically when you specify `--non-interactive`.)
  `--password=PASSWORD`
    Specifies the password for authentication.
  `--svn-non-interactive`
    Tells the system to run `svn` in non-interactive mode.

## fcm switch

Usage
  `fcm switch [OPTIONS] URL[@REV1] [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`, `--revision=REV` (`-r REV`) and `--quiet` (`-q` 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 test-battery

Usage
  `fcm test-battery [...]`
Description

  Run FCM self tests.

  Change directory to the FCM source tree, and runs this shell commmand:

      exec prove -j "${NPROC:-9}" -s -r "${@:-t}"

  where NPROC is the number of processors on your computer. You can override the prove command line by specifying extra arguments. E.g. If you do not want to run the full test suite, you can specify the names of individual test files or their containing directories as extra arguments. For example:

  Run the full test suite with the default options.

      fcm test-battery

  Run the full test suite with 12 processes.

      fcm test-battery -j 12

  Run only tests under `t/fcm-make/` with 12 processes.

      fcm test-battery -j 12 t/fcm-make

  Run only `t/fcm-make/10-log.t` in verbose mode.

      fcm test-battery -v t/fcm-make/10-log.t

Environment Variables
TEST_PROJECT
  If this is set, run CM tests using a project sub-hierarchy in the test repositories.
TEST_REMOTE_HOST
  If this is set, run CM tests using an auto-generated Subversion server on the host specified.

## fcm update

Usage
  `fcm update [OPTIONS] [PATH ...]`
Description

  `fcm update` supports the arguments and alternate names supported by `svn update`. It supports the options `--non-interactive`, `--revision=REV` (`-r REV`) and `--quiet` (`-q`) only. (Please refer to the Subversion book for details).

  FCM will ensure that your working copies updates 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 update command will always apply recursively from that level.
  - If you do not specify the `--non-interactive` option, it uses `svn status --show-updates` to display what will be updated in your working copies and to check for local modifications (if you specify `--revision=REV` (`-r REV` then it just uses `svn status`). If it finds any it reports them and asks you to confirm that you wish to continue (it aborts if not).

## fcm version

Usage
  `fcm version`
Description

  Print FCM version string.

Alternate Names
  --version, -V

## Other Subversion Commands

Other `svn` commands are supported by `fcm` 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.

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 lock
- svn log
- svn mergeinfo
- svn mkdir
- svn move
- svn patch
- svn propdel
- svn propedit
- svn propget
- svn proplist
- svn propset
- svn relocate
- svn resolve
- svn resolved
- svn revert
- svn status
- svn unlock
- svn upgrade

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