&dhucpackage; &dhsection;

&dhpackage;

Control access to CVS repositories by branch

          &dhpackage;
          --config file
          --no-config
          --cvsroot path
          --help | -h

## Description

`&dhpackage;` 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. `&dhpackage;` allows the repository administrator to disallow such commits.

&dhpackage; 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, &dhpackage; is invoked if it has been configured.

## Setting Up branchctl

Setting up &dhpackage; is not difficult, but there are usually several steps:

1. Install &dhpackage;. 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 &dhpackage;. This is a matter of adding and/or changing some of the configuration files in the CVSROOT module in the repository.

### Install &dhpackage;

&dhpackage; 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 &dhpackage; by checking it into the repository itself, check out a working copy of the CVSROOT module. Add the name `&dhpackage;` to the file `checkoutlist` in that directory as well, and commit that change. This will cause a copy of &dhpackage; to be checked out into the repository itself. Copy te &dhpackage; script into the directory, make sure that it is executable by everyone (you should use `chmod a+x &dhpackage;` 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 &dhpackage; script should be located in the repository in the `CVSROOT` directory in the repository. This is the usual way of integrating &dhpackage; into a CVS repository.

To install &dhpackage; 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 &dhpackage;` 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 &dhpackage; (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 &dhpackage;

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

The `commitinfo` file in the `CVSROOT` module needs to be modified to invoke &dhpackage; 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, `&dhpackage;.conf`, to be used everywhere that doesn't use an alternate invocation of &dhpackage;.

The second line tells CVS to use &dhpackage;'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 &dhpackage; 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 &dhpackage;.

## Options

When an option includes an argument, you may specify the argument either separate ("-d output") or mashed ("-doutput"). &dhpackage; 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 &dhpackage;. By default, a file named `&dhpackage;.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 &dhpackage;. 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.

## See Also

The &dhpackage; page on &sourceforge;.

The CVS home page.

## Author

&dhpackage; was originally written by Fred Drake.

This manual page was written by &dhusername; &dhemail;.