[Cvs-syncmail] syncmail/doc branchctl.1,NONE,1.1 branchctl.sgml,NONE,1.1

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/cvs-syncmail/syncmail/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv2203

Added Files:
	branchctl.1 branchctl.sgml 
Log Message:
Manual page for branchctl.

--- NEW FILE: branchctl.1 ---
.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <st...@gg...>.
.TH "BRANCHCTL" "1" "21 July 2003" "" ""

.SH NAME
branchctl \- Control access to CVS repositories by branch
.SH SYNOPSIS

\fBbranchctl\fR [ \fB--config \fIfile\fB\fR ] [ \fB--no-config\fR ] [ \fB--cvsroot \fIpath\fB\fR ] [ \fB--help | -h\fR ]

.SH "DESCRIPTION"
.PP
\fBbranchctl\fR takes care of disallowing
checkins for branches that have been marked "off-limits".
.PP
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.
.PP
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 \fBcvs up -r\fR to move one
of them to a different branch.  \fBbranchctl\fR
allows the repository administrator to disallow such commits.
.PP
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
\fIcommitinfo\fR file, branchctl is invoked if
it has been configured.
.SH "SETTING UP BRANCHCTL"
.PP
Setting up branchctl is not difficult, but there are usually
several steps:
.TP 3
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 \fBPATH\fR, or just about anywhere else.
.TP 3
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.
.SS "INSTALL BRANCHCTL"
.PP
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.
.PP
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
\fIcheckoutlist\fR 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 \fBchmod a+x
branchctl\fR for this), and use the \fBcvs
add\fR and \fBcvs commit\fR 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 \fICVSROOT\fR directory in the
repository.  This is the usual way of integrating branchctl
into a CVS repository.
.PP
To install branchctl outside of the repository, find a
location for the script.  This can be in a "bin" directory
such as \fI/usr/local/bin/\fR, 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 \fBchmod a+x branchctl\fR 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).
.SS "CONFIGURE CVS TO USE BRANCHCTL"
.PP
Getting the CVS server to invoke branchctl requires editing
one more file in the \fICVSROOT\fR module of the repository.
Even if you're using a shared installation of branchctl,
this configuration needs to be performed for each repository.
.PP
The \fIcommitinfo\fR file in the \fICVSROOT\fR module needs to be
modified to invoke branchctl when appropriate.  Just when is
appropriate depends entirely on your project.  If your
\fIcommitinfo\fR file still contains the
comments that \fBcvs init\fR 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.
.PP
Here are some example lines to get you started:

.nf
DEFAULT $CVSROOT/CVSROOT/branchctl

ProjectOne $CVSROOT/CVSROOT/branchctl --no-config

ProjectTwo $CVSROOT/CVSROOT/branchctl --config project-two.conf
.fi
.PP
The first line causes the default configuration file,
\fIbranchctl.conf\fR, to be used everywhere
that doesn't use an alternate invocation of branchctl.
.PP
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 \fIProjectOne\fR directory of the
repository.
.PP
The third line tells CVS to run branchctl using a separate
configuration file for the \fIProjectTwo\fR directory in the
repository.
.PP
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.
.SH "OPTIONS"
.PP
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").
.TP
\fB--config \fIfile\fB\fR
Use \fIfile\fR as the configuration
file for branchctl.  By default, a file named
\fIbranchctl.conf\fR is used if it exists.
If the name of the configuration file is relative, it is
interpreted as relative to the \fICVSROOT\fR administrative
directory of the repository.  \fB--config\fR is
incompatible with \fB--no-config\fR.
.TP
\fB--no-config\fR
Do not use a configuration file for branchctl.  This can
be used to disable the use of the default configuration
file.  \fB--no-config\fR is incompatible with
\fB--config\fR.  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.
.TP
\fB--cvsroot \fIpath\fB\fR
Use \fIpath\fR as the value for the
\fBCVSROOT\fR environment variable.  This is
usually not needed.
.TP
\fB--help\fR
.TP
\fB-h\fR
Print a summary of the command line options to standard
output.
.SH "BUGS"
.PP
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/>.
.SH "SEE ALSO"
.PP
The branchctl page <URL:http://sourceforge.net/projects/cvs-syncmail/> on SourceForge <URL:http://sourceforge.net/>.
.PP
The CVS home page <URL:http://www.cvshome.org/>.
.SH "AUTHOR"
.PP
branchctl was originally written by Fred Drake.
.PP
This manual page was written by Fred L. Drake, Jr. <fd...@ac...>.

--- NEW FILE: branchctl.sgml ---
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@
  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Fred</firstname>">
  <!ENTITY dhsurname   "<surname>Drake</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>July 14, 2003</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>fd...@ac...</email>">
  <!ENTITY dhusername  "Fred L. Drake, Jr.">
  <!ENTITY dhucpackage "<refentrytitle>branchctl</refentrytitle>">
  <!ENTITY dhpackage   "branchctl">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY sourceforge "<ulink url='http://sourceforge.net/'>SourceForge</ulink>">
]>
<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2003</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>
    <refpurpose>Control access to CVS repositories by branch</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg>--config <replaceable>file</replaceable></arg>
      <arg>--no-config</arg>
      <arg>--cvsroot <replaceable>path</replaceable></arg>
      <arg><option>--help</option> | <option>-h</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>&dhpackage;</command> takes care of disallowing
      checkins for branches that have been marked "off-limits".
    </para>
    <para>
      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.
    </para>
    <para>
      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 <command>cvs up -r</command> to move one
      of them to a different branch.  <command>&dhpackage;</command>
      allows the repository administrator to disallow such commits.
    </para>
    <para>
      &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
      <filename>commitinfo</filename> file, &dhpackage; is invoked if
      it has been configured.
    </para>
  </refsect1>

  <refsect1>
    <title>Setting Up branchctl</title>
    <para>
      Setting up &dhpackage; is not difficult, but there are usually
      several steps:
    </para>
    <orderedlist numeration="arabic">
      <listitem>
        <para>
          Install &dhpackage;.  This is usually done by adding it to
          your CVS repository, but it may be located in a directory on
          the default <envar>PATH</envar>, or just about anywhere else.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
    </orderedlist>

    <refsect2>
      <title>Install &dhpackage;</title>
      <para>
        &dhpackage; consists of a single Python script; it does not
        need any supplemental data files.  There are two approaches to
        installing the script:
        <simplelist type="inline">
          <member>check it into the repository</member>
          <member>or place it in a shared location on the CVS
          server</member>
        </simplelist>.
      </para>
      <para>
        To install &dhpackage; by checking it into the repository
        itself, check out a working copy of the CVSROOT module.  Add
        the name <literal>&dhpackage;</literal> to the file
        <filename>checkoutlist</filename> 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 <command>chmod a+x
        &dhpackage;</command> for this), and use the <command>cvs
        add</command> and <command>cvs commit</command> 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 <filename
        class="directory">CVSROOT</filename> directory in the
        repository.  This is the usual way of integrating &dhpackage;
        into a CVS repository.
      </para>
      <para>
        To install &dhpackage; outside of the repository, find a
        location for the script.  This can be in a "bin" directory
        such as <filename
        class="directory">/usr/local/bin/</filename>, 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 <command>chmod a+x &dhpackage;</command> 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).
      </para>
    </refsect2>

    <refsect2>
      <title>Configure CVS to use &dhpackage;</title>
      <para>
        Getting the CVS server to invoke &dhpackage; requires editing
        one more file in the <filename
        class="directory">CVSROOT</filename> module of the repository.
        Even if you're using a shared installation of &dhpackage;,
        this configuration needs to be performed for each repository.
      </para>
      <para>
        The <filename>commitinfo</filename> file in the <filename
        class="directory">CVSROOT</filename> module needs to be
        modified to invoke &dhpackage; when appropriate.  Just when is
        appropriate depends entirely on your project.  If your
        <filename>commitinfo</filename> file still contains the
        comments that <command>cvs init</command> 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.
      </para>
      <para>
        Here are some example lines to get you started:
<literallayout>
DEFAULT $CVSROOT/CVSROOT/branchctl

ProjectOne $CVSROOT/CVSROOT/branchctl --no-config

ProjectTwo $CVSROOT/CVSROOT/branchctl --config project-two.conf
</literallayout>
      </para>
      <para>
        The first line causes the default configuration file,
        <filename>&dhpackage;.conf</filename>, to be used everywhere
        that doesn't use an alternate invocation of &dhpackage;.
      </para>
      <para>
        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 <filename
        class="directory">ProjectOne</filename> directory of the
        repository.
      </para>
      <para>
        The third line tells CVS to run &dhpackage; using a separate
        configuration file for the <filename
        class="directory">ProjectTwo</filename> directory in the
        repository.
      </para>
      <para>
        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;.
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Options</title>
    <para>
      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").
    </para>

    <variablelist>
      <varlistentry>
        <term><option>--config <replaceable>file</replaceable></option></term>
        <listitem>
          <para>
            Use <replaceable>file</replaceable> as the configuration
            file for &dhpackage;.  By default, a file named
            <filename>&dhpackage;.conf</filename> is used if it exists.
            If the name of the configuration file is relative, it is
            interpreted as relative to the <filename
            class="directory">CVSROOT</filename> administrative
            directory of the repository.  <option>--config</option> is
            incompatible with <option>--no-config</option>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--no-config</option></term>
        <listitem>
          <para>
            Do not use a configuration file for &dhpackage;.  This can
            be used to disable the use of the default configuration
            file.  <option>--no-config</option> is incompatible with
            <option>--config</option>.  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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--cvsroot <replaceable>path</replaceable></option></term>
        <listitem>
          <para>
            Use <replaceable>path</replaceable> as the value for the
            <envar>CVSROOT</envar> environment variable.  This is
            usually not needed.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--help</option></term>
        <term><option>-h</option></term>
        <listitem>
          <para>
            Print a summary of the command line options to standard
            output.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
      There are probably some bugs.  If you find them, please
      report them to the maintainers using the <ulink
      url="http://sourceforge.net/projects/cvs-syncmail/">bug
      tracker</ulink>.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      The <ulink url="http://sourceforge.net/projects/cvs-syncmail/"
      >&dhpackage; page</ulink> on &sourceforge;.
    </para>

    <para>
      The <ulink url="http://www.cvshome.org/">CVS home page</ulink>.
    </para>
  </refsect1>

  <refsect1>
    <title>Author</title>
    <para>
      &dhpackage; was originally written by Fred Drake.
    </para>
    <para>
      This manual page was written by &dhusername; &dhemail;.
    </para>
  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->