<!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 15, 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>fdrake@acm.org</email>">
  <!ENTITY dhusername  "Fred L. Drake, Jr.">
  <!ENTITY dhucpackage "<refentrytitle>syncmail</refentrytitle>">
  <!ENTITY dhpackage   "syncmail">

  <!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>2002</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>
    <refpurpose>Send email notifications of CVS activity</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg>--cvsroot <replaceable>path</replaceable></arg>
      <arg><group><arg>--context</arg><arg>-C</arg></group>
           <replaceable>lines</replaceable></arg>
      <arg>-c</arg>
      <arg>-u</arg>
      <arg><option>--quiet</option> | <option>-q</option></arg>
      <arg>--fromhost <replaceable>hostname</replaceable></arg>
      <arg>-f <replaceable>hostname</replaceable></arg>
      <arg>--mailhost <replaceable>hostname</replaceable></arg>
      <arg>-m <replaceable>hostname</replaceable></arg>
      <arg>--reply-to <replaceable>email-address</replaceable></arg>
      <arg>-R <replaceable>email-address</replaceable></arg>
      <arg>--subject-prefix <replaceable>string</replaceable></arg>
      <arg>-S <replaceable>string</replaceable></arg>
      <arg><option>--help</option> | <option>-h</option></arg>
      <arg choice="req">%{sSv}</arg>
      <arg choice="req" rep="repeat">email</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>&dhpackage;</command> sends out notifications of CVS
      commits via email, including the patch that was applied for
      changed files, the content of new files, or notes about files
      that were removed.
    </para>
    <para>
      In any large project, keeping track of changes is difficult.
      CVS does a reasonable job of allowing source changes to be
      controlled and managed, but does not provide tools to make it
      easier to work with a changing code base.  The hardest part of
      working on a dynamic project with many changing modules is
      knowing when changes occur, and what those changes are.
    </para>
    <para>
      Software developers often are heavy email users, spending huge
      amounts of time working with their email software.  Open source
      developers are among the most serious email addicts out there,
      sorting through hundreds of emails a day, since this is often
      the only way to stay in touch with users and fellow developers.
    </para>
    <para>
      <emphasis>Clearly, we need more email.</emphasis>
    </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>loginfo</filename> file, &dhpackage; is invoked if its
      been configured, and it sends email to one or more email
      addresses specified on the command line.
    </para>
  </refsect1>

  <refsect1>
    <title>Setting Up syncmail</title>
    <para>
      Setting up &dhpackage; is not difficult, but there are usually
      several steps:
    </para>
    <orderedlist numeration="arabic">
      <listitem>
        <para>
          Set up a mailing list.  Strictly speaking, this is optional,
          but with most good mailing list managers, it's easier to
          maintain a mailing list than it is to continually update a
          list of individual email addresses on the &dhpackage;
          command line.  How this is done depends on many things, but
          not &dhpackage;, so will not be further covered here.
        </para>
      </listitem>
      <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>syncmail</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
        syncmail</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 syncmail</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 CVSROOT module of the repository.  Even
        if you're using a single installation of &dhpackage;, this
        configuration needs to be performed for each repository.
      </para>
      <para>
        The <filename>loginfo</filename> 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 <filename>loginfo</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 two example lines to get you started:
<literallayout>
CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} you@example.com

DEFAULT $CVSROOT/CVSROOT/syncmail %{sVv} myproject-checkins@example.com
</literallayout>
      </para>
      <para>
        This will cause email to be sent to two different places, with
        which depending on what files in the repository are affected.
        For administrative files in the CVSROOT module, email will be
        sent to <email>you@example.com</email>; you should probably
        list all your project administrators here.  For all other
        files, email will be sent to the addresses you specify.
      </para>
      <para>
        If you have several sub-products for which you want different
        checkin lists, you can change the "DEFAULT" label to match the
        subtree that you want to go to each list, with a separate line
        for each distinct prefix.  For example, if your repository
        includes the modules "one" and "two", you could use the
        following:
<literallayout>
CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} you@example.com

one/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject-one-cvs@example.com
two/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject-two-cvs@exmaple.com
</literallayout>
      </para>
      <para>
        Note that <literal>%{sSv}</literal> is magic that CVS
        understands and replaces with information about the files that
        are affected; be sure to enter that exactly as shown, just
        before the email addresses.  Command line options for
        &dhpackage; should be placed between the name of the
        &dhpackage; command and the <literal>%{sSv}</literal>.
      </para>
      <para>
        You can still have a "DEFAULT" line that gets used for any
        additional subprojects.
      </para>
      <para>
        If you do <emphasis>not</emphasis> have a stock
        <filename>loginfo</filename> file, then you can probably
        figure out what you need to do to combine the information
        above with your existing changes.  If the command lines in the
        file become too long for comfort, some helper scripts can be
        added to the CVSROOT module (remember to add their names to
        the <filename>checkoutlist</filename> as well!).
      </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>--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>--context <replaceable>lines</replaceable></option></term>
        <term><option>-C <replaceable>lines</replaceable></option></term>
        <listitem>
          <para>
            Generate context diffs with
            <replaceable>lines</replaceable> lines of context
            displayed on either side of the changed portion.
	  </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-c</option></term>
        <listitem>
          <para>
            Generate context diffs with two lines of context shown on
            either side of the changed portion.  This is the default.
	   </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-u</option></term>
        <listitem>
          <para>
            Generate unified diffs instead of context diffs.  Unified
            diffs are typically shorted than context diffs, but many
            users find it easier to read context diffs.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--quiet</option></term>
        <term><option>-q</option></term>
        <listitem>
          <para>
            Do not display progress information to the user.  By
            default, &dhpackage; will display the email addresses it
            is sending mail to and note when it starts generating the
            notification email and when it is done sending the email.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--fromhost <replaceable>hostname</replaceable></option></term>
        <term><option>-f <replaceable>hostname</replaceable></option></term>
        <listitem>
          <para>
            Specify the host name that email should appear to come
            from.  By default, &dhpackage; uses the fully qualified
            name for the host it's running on, and lets the local MTA
            take care of host name translation.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--mailhost <replaceable>hostname</replaceable></option></term>
        <term><option>-m <replaceable>hostname</replaceable></option></term>
        <listitem>
          <para>
            Specify the host name that should be used to submit mail
            via SMTP.  By default, &dhpackage; uses
            <systemitem class="systemname">localhost</systemitem>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--reply-to <replaceable>email-address</replaceable></option></term>
        <term><option>-R <replaceable>email-address</replaceable></option></term>
        <listitem>
          <para>
            Specify an email address that should be used for the
            Reply-To header in email.  This header is not normally
            used.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--subject-prefix <replaceable>string</replaceable></option></term>
        <term><option>-S <replaceable>string</replaceable></option></term>
        <listitem>
          <para>
            Provide a string that is pre-pended to the subject of
            generated email.  This prefix is often of the form
            '[Checkins]', allowing mail filters to easily identify
            mail from syncmail for a specific CVS repository or
            project.
          </para>
          <para>
            This is often not needed if mail is being sent to a
            mailing list manager that adds a prefix of it's own.
          </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>Alternatives</title>
    <para>
      Other people have written tools that serve similar purposes, but
      not all of these are meant to support CVS repositories accessed
      from remote locations (anything other than direct filesystem
      access).
    </para>

    <para>
      A mostly-equivalent package, written in Perl, is available as
      <ulink url='http://cvs-syncmail-pl.sourceforge.net/'
      >cvs-syncmail (Perl version)</ulink>.
    </para>

    <para>
      <command>log_accum</command> is another Perl implementation, but
      there appears to be no authoritative source of information for
      this package.
    </para>

    <para>
      Please inform the &dhpackage; maintainers if you can provide
      current references to these efforts.
    </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 Barry Warsaw to send mail
      based on checkins to the Python project.  Barry continues to
      maintain &dhpackage; with help from &dhusername; and others.
    </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:
-->