***External Tools Cookbook***

Just some notes on where I'm going with #183 (in the =external-tools-branch=
CVS branch). Many trivial things can just be
done with a command-line. Custom processor scripts make things way more
powerful. And scripts have access to QUERY_STRING, so being able to build
CGI-type forms is easy. However, you'll need to ensure you use the _GET_ query
method in forms rather than _POST_.

**Files**

*Blame*

permissions *asio*, command line:

  /usr/bin/cvs -n -d '%RP' rannotate -r `expr '%V1' \| HEAD` '%F' 2>&1

*Graph*

permissions asio, command line (see attached script):

  /home/cpb/src/scripts/cvstrac_graphvers.pl --filename='%F'
                   --database='%RP/%P.db' --baseurl='%B/'

**Directories**

*ChangeLog*

permissions *asoi*, command line:

  /usr/bin/cvs -d '%RP' rlog '%F' 2>/dev/null |
          /usr/bin/cvs2cl --stdin  --stdout --rcs '%RP' 2>&1

Note that cvs2cl only handles the --rcs style when there's no trailing '/' in
the repository path. It's also possible to do this for individual files (I call
it the "FileLog" tool).

**Tickets**

*Close Ticket*

permissions *asw*, command line:

  /usr/bin/sqlite3 '%RP/%P.db'
         "UPDATE ticket SET status='closed' WHERE tn='%TN';"

The user gets redirected back to /tktview since there's no output. Unless
there's a failure.

*Dupe*

A frequent activity for a project manager is handling duplicate entries. This
tool creates a [Dupe] link and prompts for a ticket number. The rest is magic.
Permissions *asw*, command-line:

  /home/cpb/src/scripts/cvstrac_tktdupe.pl --database='%RP/%P.db'
           --toolurl='%B/tkttool' --toolname='%T' --tn='%TN'
           --user='%U' 2>&1

**Check-ins**

*Pass/Fail*

permissions *asi*, command-line:

  /usr/bin/sqlite3 '%RP/%P.db'
   "INSERT INTO inspect(cn,inspecttime,inspector,result)
   VALUES('%CN','%N','%U','failed|passed')"

The user gets redirected back to /chngview since there's no output. Unless
there's a failure.

*Message Sync*

A frequent complaint is that when a check-in message is editted within CVSTrac,
there's no way to sync that message back to the CVS repository itself. This
uses the =rcs -m= option to push the message back for all files in the
check-in.

permissions *asi*, command-line:

  /home/cpb/src/scripts/cvstrac_chngsync.pl --database='%RP/%P.db'
             --cvsroot='%RP' --cn='%CN'

**Wiki**

*Formatting*

permissions *asj*. Different from /wiki.txt in that the output is inlined into
the CVSTrac page, not just as straight =text/plain=.

  echo '<pre>' && cat '%C' && echo '</pre>'

*Comment*

permissions *ask*. This generates an interactive HTML form.

  /home/cpb/src/scripts/cvstrac_wikicomment.pl --database='%RP/%P.db'
       --toolurl='%B/wikitool' --toolname='%T'
       --page='%W' --user='%U' 2>&1

*Spam*

permissions *askd*.

  /home/cpb/src/scripts/cvstrac_wikispam.pl --database='%RP/%P.db'
      --toolurl='%B/wikitool' --toolname='%T'
      --page='%W' --time='%T1' 2>&1

Before using it, run

  cvstrac_wikispam.pl --database='/path/to/db' --init

And, of course, you'll probably want to set up some kind of report...