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 delimited by a double colon :: or slash /. To improve readability, the convention is to only use slash as the delimiter when referring to package names.
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 it is indicated in the documentation that a declaration is expecting a true or false value, the following can all be used to indicate a value of false: an empty string, the numeric 0, the string off or the string no. All other values will be considered true.
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.

-a [--archive]

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.

-f [--full]

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.

-j [--jobs] arg

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

-s [--stage] arg

This 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 or make: Stage 5, invoke the make command to build the project

-t [--targets] arg

This option 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 to be built is the all target.

-v [--verbose] arg

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

--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.
-f [--full]: 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.
-v [--verbose] arg: This 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) arg] [--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.

--verbose ARG: You can use this option to print the log of each revision, by setting ARG to 2.
--wiki: 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 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 keyword-print

Usage: fcm keyword-print [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 a FCM URL keyword, a Subversion URL or a path to a Subversion working copy.
Alternate Names: kp

FCM Code Management Commands

This section describes all of the code management 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 Code Management 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)] [<info-options>]
    [TARGET]

fcm branch --delete (-d) [<info-options>]
    [<commit-options>] [TARGET]

fcm branch --create (-c) --name (-n) arg [--revision arg]
    [<create-options>] [<commit-options>] [TARGET]

fcm branch --list (-l) [<branch-list-options>]
    [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. 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.
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 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).

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 characters in the set [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 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 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. Note that 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.

You can list all branches in the project by specifying the --show-all option. (This option overrides the --user arg option.)

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

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

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

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

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) | --summarise | --wiki |
    --trac (-t)] [TARGET]

fcm diff [--graphical (-g) | --summarise | <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:

--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 switch can be used in combination with all other valid switch (including --branch) except --diff-cmd, --extensions, --trac and --wiki.

--summarise

This option is implemented in FCM as a wrapper to the Subversion --summarize option. It prints only a summary of the results.

--branch

If this option 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 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 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 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 --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.

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. Multiple paths can be specified by using a colon-separated list of paths, or by specifying this option multiple times.

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

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

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, -r [--revision] and -q [--quiet] 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 -r [--revision] 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).

Other Code Management 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:

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