Updated: 21 July 2003Index
branchctl - Control access to CVS repositories by branch
branchctl [ --config file ] [ --no-config ] [ --cvsroot path ] [ --help | -h ]
branchctl takes care of disallowingcheckins for branches that have been marked "off-limits".
In any large project using CVS branches, some branches will beactive, some will have been merged into other branches or thetrunk, and others will have been bypassed. CVS really does notprovide tools to make easy to determine which branches are stillbeing used, and it's easy for someone new to a project to findan interesting tangent in a branch and start working on it, eventhough the branch has been abandoned or has already been mergedinto another branch where the features of the original branchare to be maintained.
CVS also allows a single commit to affect files on more than onebranch; this is possible by committing two files in one workingdirectory after using cvs up -r to move oneof them to a different branch. branchctlallows the repository administrator to disallow such commits.
branchctl works by integrating with CVS in the repositoryusing the configuration files in the repository's CVSROOTmodule. When CVS executes commands from thecommitinfo file, branchctl is invoked ifit has been configured.
SETTING UP BRANCHCTL
Setting up branchctl is not difficult, but there are usuallyseveral steps:
- Install branchctl. This is usually done by adding it toyour CVS repository, but it may be located in a directory onthe default PATH, or just about anywhere else.
- Configure CVS to invoke branchctl. This is a matter ofadding and/or changing some of the configuration files inthe CVSROOT module in the repository.
branchctl consists of a single Python script; it does notneed any supplemental data files. There are two approaches toinstalling the script:check it into the repository, or place it in a shared location on the CVSserver.
To install branchctl by checking it into the repositoryitself, check out a working copy of the CVSROOT module. Addthe name branchctl to the filecheckoutlist in that directory as well,and commit that change. This will cause a copy of branchctlto be checked out into the repository itself. Copy tebranchctl script into the directory, make sure that it isexecutable by everyone (you should use chmod a+xbranchctl for this), and use the cvsadd and cvs commit commands toadd it to the repository. Once the commit is complete, achecked-out copy of the branchctl script should be locatedin the repository in the CVSROOT directory in therepository. This is the usual way of integrating branchctlinto a CVS repository.
To install branchctl outside of the repository, find alocation for the script. This can be in a "bin" directorysuch as /usr/local/bin/, or can be insome other location. The only requirement is that all usersof the repository be able to execute the script (you shoulduse chmod a+x branchctl for this). Thisapproach requires direct access to the CVS server machine, andis most useful if several repositories are going to share asingle copy of branchctl (maybe to ensure the same versionis used for each; it's not large enough for disk space to bean issue).
CONFIGURE CVS TO USE BRANCHCTL
Getting the CVS server to invoke branchctl requires editingone 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 bemodified to invoke branchctl when appropriate. Just when isappropriate depends entirely on your project. If yourcommitinfo file still contains thecomments that cvs init copies in, this is agood time to read them if you haven't. If the file does notalready contain any configuration lines, you can simply add tothe end of the file.
Here are some example lines to get you started:
DEFAULT $CVSROOT/CVSROOT/branchctlProjectOne $CVSROOT/CVSROOT/branchctl --no-configProjectTwo $CVSROOT/CVSROOT/branchctl --config project-two.conf
The first line causes the default configuration file,branchctl.conf, to be used everywherethat doesn't use an alternate invocation of branchctl.
The second line tells CVS to use branchctl's internalconfiguration defaults instead of reading a configurationfile, but to only do so in the the ProjectOne directory of therepository.
The third line tells CVS to run branchctl using a separateconfiguration file for the ProjectTwo directory in therepository.
To finish the repository configuration, commit the changesyou've made. Once the CVS server has reported that it is"Rebuilding administrative file database", your repository isconfigured to use branchctl.
When an option includes an argument, you may specify theargument either separate ("-d output") or mashed ("-doutput").branchctl supports both. For long options which include anargument, the argument may be separated from the option("--fromhost example.com") or mashed, but with an equals signbetween the option and the argument ("--fromhost=example.com").
- --config file
- Use file as the configurationfile for branchctl. By default, a file namedbranchctl.conf is used if it exists.If the name of the configuration file is relative, it isinterpreted as relative to the CVSROOT administrativedirectory of the repository. --config isincompatible with --no-config.
- Do not use a configuration file for branchctl. This canbe used to disable the use of the default configurationfile. --no-config is incompatible with--config. Note that it's not normallyuseful to specify this option, but it may be useful whenyou want to allow changes to any branch within a singleCVS module, but use a more sophisticated configuration forthe rest of the repository.
- --cvsroot path
- Use path as the value for theCVSROOT environment variable. This isusually not needed.
- Print a summary of the command line options to standardoutput.
There are probably some bugs. If you find them, pleasereport them to the maintainers using the bugtracker <URL:http://sourceforge.net/projects/cvs-syncmail/>.
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/>.
branchctl was originally written by Fred Drake.
This manual page was written by Fred L. Drake, Jr. <fdrakeAATTacm.org>.
- SETTING UP BRANCHCTL
- INSTALL BRANCHCTL
- CONFIGURE CVS TO USE BRANCHCTL
- SEE ALSO
This document was created byman2html,using the manual pages.