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

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

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

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

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.

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:

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