There are two aspects to setting up Manuscript-Subversion integration:

  1. Getting Subversion to transmit changes to Manuscript
  2. Getting Manuscript to provide links to WebSVN, the web-based Subversion repository browser

Setting up the repository in Manuscript

The starting point for setting up source control integration is to create the repository in Manuscript. To do so, log into Manuscript as an administrator and go to Avatar Menu > Source Control. Click Create New Repository. In the resulting dialog, select Subversion as the type and give the repository a display name. Click Next.

alt text

The resulting dialog contains scripts and instructions for getting Subversion to transmit changes to Manuscript. Those instructions are provided in more detail below. Select the appropriate tab for the server Subversion runs on and download the scripts. Before you close the dialog, choose whether you want Manuscript to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Avatar Menu > Source Control page.

Diff and log links

In order to have Manuscript link to checked-in files directly from cases, you need something that allows you to view file diffs and history logs from a web browser. We recommend WebSVN. You can also setup Manuscript to link to logs and diffs in Trac. Once you have WebSVN or Trac installed and working with your Subversion repository, set the path to it in the New Repository dialog and click OK to complete the setup.

Getting Subversion to transmit changes to Manuscript

If your Subversion server is Linux or Unix, make sure that Perl is installed. If your Subversion server is Windows, make sure it has Windows Scripting version 5.6 or later installed.

Put the logBugDataSVN and post-commit scripts you downloaded above into Hooks directory in your Subversion repository. If your SVN repository is on Unix, grant execute permissions on both files (chmod +x filename). If you already have a post-commit script, you will need to merge it with this one.

Entering Case Numbers in Subversion Commits

When you commit a change using Subversion, include a single line of the form BugzID: case number in the log after the other comments, for example:

alt text

You can also reference multiple case numbers by separating them with commas: BugzID: 49, 50

Setting up Integration with TortoiseSVN

If anyone on your team uses TortoiseSVN, a Subversion client for Windows, follow the steps below to configure it to prompt for case numbers when you enter log messages:

Check out your repository
cd to the root directory of your checkout
Run the following commands from the command line. Notice the dots which are important.

svn propset bugtraq:label "BugzID:" .
svn propset bugtraq:url "http://Your Manuscript URL/default.asp?%BUGID%" .
svn propset bugtraq:message "BugzID: %BUGID%" .
svn propset bugtraq:number "true" .
svn propset bugtraq:warnifnoissue "false" .
svn commit -q -m "Added BugzID properties to the repository"

Note that if you would prefer to run these commands from a batch file, you need to escape the % signs by doubling them to prevent the batch file from replacing them with nothing. (e.g. %%BUGID%%).

Tortoise will search up your folder path on a checkout looking for this property, so if you checkout from other folders in your tree, be sure to do the same procedure for those folders also. We used to ask people to execute the above commands with the -R flag to do this recursively, but it has been reported that this can slow down Subversion. More details are available in this guide about Integrating Issue Trackers with TortoiseSVN.

Entering Case Numbers in TortoiseSVN Commits

When you commit a change to a Subversion repository using Tortoise-SVN, enter the case number in the BugzID edit box at the top right corner of the Enter Log Message dialog:

alt text


Troubleshooting SVN Integration

If you check in a file and don’t see any corresponding info appear in the Manuscript case:

  • Make sure you are using the correct syntax when referring to the case. Try BugzID:1 (if you have a case number 1)
  • See if the trigger is running.
    1. The post-commit script for Subversion has a line at the end that says
      rm /var/tmp/$LOGSVNCHANGEFILE (unix)
      del %temp%%logsvnfile% (windows)
    2. Add a # character to the beggining of this line so after the commit runs it does NOT delete the file in /var/tmp (or c:temp, c:windowstemp)
    3. Run a commit again and validate the file is there
    4. If the file is not there, try running the post-commit script directly (to make sure the problem is not svn failing to run it):
      1. Go to your svn hooks directory
      2. Run post-commit /path/to/svn/root/directory 1234 where the first argument is the root directory of your svn directory and “1234” is a revision number containing a Manuscript case id. If anythings goes wrong, you will see it on your console output.
  • See if the logBugDataSVN file is working. The easiest way to do this is to call it from the command line. (In the commands below, replace $REV with a valid revision number and $REPOS with the path to your repository.)
  • Unix:  svnlook changed -r $REV $REPOS > /var/tmp/svnfilesvnlook log -r $REV $REPOS | perl /path/to/ $REV /var/tmp/svnfile $REPOS
  • Windows:  svnlook changed -r $REV $REPOS > /var/tmp/svnfilesvnlook log -r $REV $REPOS | cscript /path/to/logBugDataSVN.vbs $REV /var/tmp/svnfile $REPOS
    1. If the above lines DID make an entry on your case, focus on the post-commit script. It’s likely that svnlook is not in the scripts path and you need to rewrite those lines in the script to use the full path to svnlook. Or the user that subversion runs as may not have permission to run cscript.exe (on windows).
    2. If the above lines DID NOT make an entry on your case, logBugDataSVN is failing. If you are using On Demand, or have a SSL Manuscript install, one of the most common reasons for failing is the script cannot find wget. At the top of the script it may say $wget_path = `which wget`; and you should change this to $wget_path = "/actual/path/to/wget";Also at the bottom of the script you should change the line that calls system to be system("$wget_path --no-check-certificate '$url' -q -O /dev/null");

If the info is actually getting into Manuscript but the link back to WebSVN is not working:

  • Outside of Manuscript navigate to your site and make sure WebSVN is working on its own. Note the URLs that it is using and make sure you have set the appropriate pointers for your server. You can edit the URLs by editing your repo settings in Avatar Menu > Source Control
  • If you are using an older version of Manuscript and you see %2F in the URLs where you should see “/”, change your Apache AllowEncodedSlashes configuration.

If none of that works…

These steps work for most people, but not all.

If you’re still having trouble, go to and contact us. Friendly people are standing by to help!