------------------------------------------------------------
vcs-commithooks
------------------------------------------------------------

Homepage: http://software.complete.org/vcs-commithooks
Author: John Goerzen <jgoerzen@complete.org>


This is a collection of scripts to process commit actions from
different version control systems (VCS) and inject the results into
different bug-tracking systems (BTS).

Currently supported VCS:
 * Darcs
 * Mercurial
 * Git

Currently supported BTS:
 * Trac
 * Debbugs (Debian BTS)

------------------------------------------------------------
OVERVIEW
------------------------------------------------------------

The package consists of two parts: frontends and backends.

The backends correspond to a specific BTS and are responsible for
injecting data into the BTS.  They receive information on the command
line that tell them what to inject.

The frontends are called by the VCS directly.  They query the VCS for
the information that is needed, then invoke the backends to inject it.

The backends may be called directly by your own scripts, too, or
called by new frontend scripts.

You do not need to "install" this package; you can simply run the
scripts directly from where you unpacked it.

------------------------------------------------------------
BACKENDS
------------------------------------------------------------

There are two backends:

  deb-post-commit-hook injects data via email into debbugs

  trac-post-commit-hook uses the Trac libraries directly to inject
  into Trac.

You may run either program with --help to get a usage summary.  Not
all options are required.

trac-post-commit-hook will not run at all without the Trac libraries
present.

If you are using one of the supported VCS, you will likely not invoke
the backends directly, but rather call a frontend which will take care
of invoking the backend.

=== Operation of the backends

The backends scan your commit logs for certain text that references
bug/ticket numbers.  If a reference is found, a copy of the commit
message and a link to the changeset will be sent to the relevant BTS.
If you write the text in a certain way, the bug in the relevant BTS
will also be marked fixed (Trac) or pending (debbugs).

Here are the phrases that are supported.  Matches are
case-insensitive. Numeric values here are examples; of course you
would use your real numbers here:

Trac                 Debian                     Action
-------------------- -------------------------- -----------------
close #12345         close deb#12345            Notify & close
closed #12345        closed deb#12345           Notify & close
closes #12345        closes deb#12345           Notify & close
fix #12345           fix deb#12345              Notify & close
fixed #12345         fixed deb#12345            Notify & close
fixes #12345         fixes deb#12345            Notify & close
                     Closes: #12345             Notify & close
addresses #12345     addresses deb#12345        Notify
re #12345            re deb#12345               Notify
references #12345    references deb#12345       Notify
refs #12345          refs deb#12345             Notify
see #12345           see deb#12345              Notify
                     Refs: #12345               Notify

You can use any command with a colon after it, and then omit the "deb"
prefix, for Debian bugs.  Two examples of that are shown above.

Multiple bugs may be combined with "and", ",", or "&".

Example:

    Changed blah and foo to do this or that. Fixes #10 and #12, and
    refs #1530.

This will close #10 and #12 in trac, and add a note to #1530 in
Debian.

=== Examples

You can see an example of the actions of the Debian commit hook at:

  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=468076#10

------------------------------------------------------------
FRONTENDS
------------------------------------------------------------

The frontends are:

darcs-both-commit: Commit darcs messages to debbugs and Trac
git-both-commit: Commit git messages to debbugs and Trac
git-deb-commit: Commit git messages to debbugs
git-trac-commit: Commit git messages to Trac
git-find-revs: Used by git scripts to get the specific rev numbers
               that are new
hg-both-commit: Commit Mercurial messages to debbugs and Trac
hg-deb-commit: Commit Mercurial messages to debbugs
hg-trac-commit: Commit Mercurial messages to Trac

------------------------------------------------------------
DARCS FRONTEND
------------------------------------------------------------

=== darcs-both-commit

To configure, edit _darcs/prefs/defaults in the Darcs repo on your
server.  Add lines like this:

  apply posthook /usr/bin/darcs-both-commit user@example.com
     http://trac.example.com/project /opt/trac/instances/project

  pull posthook /usr/bin/darcs-both-commit user@example.com
     http://trac.example.com/project /opt/trac/instances/project

Note that each of those entries should be contained entirely on one
line; they are just wrapped here for readability.

The parameters are:

 $1 - the "From" address for submissions to Debian BTS
 $2 - the URL for the trac instance
 $3 - the path to the trac instance

------------------------------------------------------------
GIT FRONTENDS
------------------------------------------------------------

I recommend that you configure the Git frontends in your Git server
repo only.  To do so, you will want to edit .git/hooks/post-receive
and insert, at the end, a call to the Git frontend as shown below.
After doing so, make sure you use chmod to mark the post-receive hook
executable.  Do not "source" with "." the frontend as the post-receive
example shows.

=== git-deb-commit

Sample addition to post-receive:

  /usr/bin/git-deb-commit 'http://repo.or.cz/w/git.git?' \
    user@example.com

The args are:

 $1 - Path to gitweb web server for this repo
      
      Should end with '?' if pathinfo is used or ';' otherwise
 
      Examples:
      
      'http://git.kernel.org/gitweb.cgi?p=boot/syslinux/syslinux-gpxe.git;'
      'http://repo.or.cz/w/git.git?'
 
      You probably want to surround this with quotes as shown above!
 
      After this, the script can append things like "a=shortlog"

 $2 - "From" address for mails to the Debian BTS

=== git-trac-commit

Designed to work with GitPlugin at http://trac-hacks.org/wiki/GitPlugin

Sample addition to post-receive hook:

  /usr/bin/git-trac-commit http://trac.example.com/project \
      /opt/trac/instances/project

The args are:

 $1 - URL of this trac instance
 $2 - Filesystem path to the trac instance

=== git-both-commit

Scans for Trac and debbugs.

Sample addition to post-receive:

  /usr/bin/git-both-commit http://trac.example.com/project \
      /opt/trac/instances/project \
      'http://repo.or.cz/w/git.git?' \
      user@example.com

The args are:

 $1 - URL for this trac instance
 $2 - Path to Trac installation
 $3 - URL for gitweb server (see notes above)
 $4 - From address for debbugs BTS

------------------------------------------------------------
MERCURIAL FRONTENDS
------------------------------------------------------------

I recommend configuring these in the Mercurial repo on your server.
Edit .hg/hgrc and add sections as listed below.

=== hg-deb-commit

Sample .hg/hgrc section:

  [hooks]
  incoming = /usr/bin/hg-deb-commit http://hg.example.com/project
           user@example.com

That "incoming" stuff should all be on one line.

The args are:

 $1 - Path to hgweb/hgwebdir for this repo
 $2 - "From" address for mails to Debian BTS

=== hg-trac-commit

Sample .hg/hgrc section:
  
   [hooks]
   incoming = /usr/bin/hg-trac-commit http://trac.example.com/project
       /opt/trac/instances/project

That "incoming" stuff should all be on one line.

The args are:

 $1 - URL of this trac instance
 $2 - Filesystem path to the trac instance

=== hg-both-commit

Sample .hg/hgrc section:

   [hooks]
   incoming = /usr/bin/hg-both-commit http://trac.example.com/project
      /opt/trac/instances/project http://hg.example.com/project
      user@example.com

As before, those three incoming lines are wrapped here for readibility
but should be all one line in Mercurial.

The args are:

 $1 - URL of this trac instance
 $2 - Filesystem path to the trac instance
 $3 - Path to hgweb/hgwebdir for this repo
 $4 - "From" address for mails to Debian BTS