BRANCHCTL(1)

NAME
branchctl - Control access to CVS repositories by branch

SYNOPSIS
branchctl [ --config file ] [ --no-config ] [ --cvsroot path ] [ --help | -h ]

DESCRIPTION

branchctl takes care of disallowing checkins for branches that have been marked "off-limits".

In any large project using CVS branches, some branches will be active, some will have been merged into other branches or the trunk, and others will have been bypassed. CVS really does not provide tools to make easy to determine which branches are still being used, and it's easy for someone new to a project to find an interesting tangent in a branch and start working on it, even though the branch has been abandoned or has already been merged into another branch where the features of the original branch are to be maintained.

CVS also allows a single commit to affect files on more than one branch; this is possible by committing two files in one working directory after using cvs up -r to move one of them to a different branch. branchctl allows the repository administrator to disallow such commits.

branchctl works by integrating with CVS in the repository using the configuration files in the repository's CVSROOT module. When CVS executes commands from the commitinfo file, branchctl is invoked if it has been configured.

SETTING UP BRANCHCTL

Setting up branchctl is not difficult, but there are usually several steps:

1.  Install branchctl. This is usually done by adding it to your CVS repository, but it may be located in a directory on the default PATH, or just about anywhere else.

2.  Configure CVS to invoke branchctl. This is a matter of adding and/or changing some of the configuration files in the CVSROOT module in the repository.

  INSTALL BRANCHCTL

branchctl consists of a single Python script; it does not need any supplemental data files. There are two approaches to installing the script: check it into the repository, or place it in a shared location on the CVS server.

To install branchctl by checking it into the repository itself, check out a working copy of the CVSROOT module. Add the name branchctl to the file checkoutlist in that directory as well, and commit that change. This will cause a copy of branchctl to be checked out into the repository itself. Copy te branchctl script into the directory, make sure that it is executable by everyone (you should use chmod a+x branchctl for this), and use the cvs add and cvs commit commands to add it to the repository. Once the commit is complete, a checked-out copy of the branchctl script should be located in the repository in the CVSROOT directory in the repository. This is the usual way of integrating branchctl into a CVS repository.

To install branchctl outside of the repository, find a location for the script. This can be in a "bin" directory such as /usr/local/bin/, or can be in some other location. The only requirement is that all users of the repository be able to execute the script (you should use chmod a+x branchctl for this). This approach requires direct access to the CVS server machine, and is most useful if several repositories are going to share a single copy of branchctl (maybe to ensure the same version is used for each; it's not large enough for disk space to be an issue).

  CONFIGURE CVS TO USE BRANCHCTL

Getting the CVS server to invoke branchctl requires editing one more file in the CVSROOT module of the repository. Even if you're using a shared installation of branchctl, this configuration needs to be performed for each repository.

The commitinfo file in the CVSROOT module needs to be modified to invoke branchctl when appropriate. Just when is appropriate depends entirely on your project. If your commitinfo file still contains the comments that cvs init copies in, this is a good time to read them if you haven't. If the file does not already contain any configuration lines, you can simply add to the end of the file.

Here are some example lines to get you started:
DEFAULT $CVSROOT/CVSROOT/branchctl
ProjectOne $CVSROOT/CVSROOT/branchctl --no-config
ProjectTwo $CVSROOT/CVSROOT/branchctl --config project-two.conf

The first line causes the default configuration file, branchctl.conf, to be used everywhere that doesn't use an alternate invocation of branchctl.

The second line tells CVS to use branchctl's internal configuration defaults instead of reading a configuration file, but to only do so in the the ProjectOne directory of the repository.

The third line tells CVS to run branchctl using a separate configuration file for the ProjectTwo directory in the repository.

To finish the repository configuration, commit the changes you've made. Once the CVS server has reported that it is "Rebuilding administrative file database", your repository is configured to use branchctl.

OPTIONS

When an option includes an argument, you may specify the argument either separate ("-d output") or mashed ("-doutput"). branchctl supports both. For long options which include an argument, the argument may be separated from the option ("--fromhost example.com") or mashed, but with an equals sign between the option and the argument ("--fromhost=example.com").

--config file
    Use file as the configuration file for branchctl. By default, a file named branchctl.conf is used if it exists. If the name of the configuration file is relative, it is interpreted as relative to the CVSROOT administrative directory of the repository. --config is incompatible with --no-config.

--no-config
    Do not use a configuration file for branchctl. This can be used to disable the use of the default configuration file. --no-config is incompatible with --config. Note that it's not normally useful to specify this option, but it may be useful when you want to allow changes to any branch within a single CVS module, but use a more sophisticated configuration for the rest of the repository.

--cvsroot path
    Use path as the value for the CVSROOT environment variable. This is usually not needed.

--help

-h  Print a summary of the command line options to standard output.

BUGS

There are probably some bugs. If you find them, please report them to the maintainers using the bug tracker <URL:http://sourceforge.net/projects/cvs-syncmail/>.

SEE ALSO

The branchctl page <URL:http://sourceforge.net/projects/cvs-syncmail/> on SourceForge <URL:http://sourceforge.net/>.

The CVS home page <URL:http://www.cvshome.org/>.

AUTHOR

branchctl was originally written by Fred Drake.

This manual page was written by Fred L. Drake, Jr. <fdrake@acm.org>.