Trac + darcs = I'm in heaven
In the last couple of months, I've stumbled across Trac for several times. It seemed very nice, extremely well integrated, but it would only support Subversion as his SCM system, and as you may have read, I'm more a darcs kind-of-a-guy.
So I never payed much attention to it.
I did jump when Justus Pendleton announced a patch to add support for darcs some months back, but I've read somewhere (can't seem to find the post now) that this patch only supported a older version of Trac. There is some talk about support darcs and other SCMs natively sometime in the 2.0 milestone, but that seems way of. The ideas regarding expanding Trac to other SCMs are also mentioned in this thread.
Last thursday though, I had lunch with João Gomes (who seems to have misplaced his blog/homepage), who is working in his course final project, and he is using Trac to manage his work between him and his partner. He gave me the tour, and frankly, I was totally sold. I had to find a way to make it work with darcs, and also, try to make it work at work, where we use CVS.
After some hours thinking, searching and browsing, I had a plan: use darcs to manage your code, just export your changes to a SVN repository on a regular basis to make Trac work. This idea should also be applicable to other SCMs like cvs, monotone, git and the arch family.
So now I had this tasks:
- install Trac and all it's dependencies;
- install and learn how to use svn;
- learn how to configure it and make all the features work;
- export a darcs repository to a svn repository, with regular updates.
The server had a Fedora Core 3 setup, so I figure it should be easy. Rui spend most of the day telling me that it would be a nightmare, because the last time he tried to install this, it was a mess with dependencies. I have to admit, I was bit scared.
Also, I had to download a Trac post-commit hook for Subversion from the Trac project site. Use the original raw format download link at the bottom, but be careful: in my case, it added some HTML to the end of the script. You should only copy-and-paste the script up to the HTML Doctype declaration. Instruction on how to use this post-commit are at the top of the script.
Installing svn and learning how-to use it
The Trac how-to on Fedora Core3 included the Subversion installation instructions. They worked without any problems.
As I don't need or want a Subversion server, there is no setup of those components, just the creation of Subversion repositories with the
Learning to use it was also easy. The Subversion book is excellent. The command line interface of
svn is essentially the same as CVS, which I use for quite some time. No problems there. The administrative side of Subversion, creating repositories, choosing data stores, and configuring post-commit hooks was also simple.
All in all, I browsed the first 4 chapter of the SVN book, and read chapter 5 with some care. It took me less than an hour.
My advise: start simple. You can read the Trac Guide in less than an hour, but don't change everything at once.
The thinks I changed where:
- Set up the post-commit hook: allows you to comment and close tickets directly from commit messages;
- Setup permissions with the
trac-admincommand to your self: I gave me TRAC_ADMIN privileges for now.
The Apache configuration was simply copy and pasting from other places. Eventually I arrived at this one
<VirtualHost *:80> ServerName mytrac DocumentRoot "/servers/sites/mytrac/docs" ErrorLog "/servers/logs/httpd/sites/mytrac_error_log" RewriteEngine On RewriteRule ^/$ /cgi-bin/trac.cgi [R] ScriptAlias "/cgi-bin/" "/servers/sites/mytrac/cgi/" <Directory "/servers/sites/mytrac/cgi-bin"> AllowOverride None Options None Order allow,deny Allow from all </Directory> <Location "/cgi-bin/trac.cgi/login"> AuthType Basic AuthName "trac" AuthUserFile /servers/sites/mytrac/etc/trac.htpasswd Require valid-user </Location> <Location "/cgi-bin/trac.cgi"> SetEnv TRAC_ENV "/home/melo/sites/trac_instances/test2" </Location> Alias /trac /usr/share/trac/htdocs/ <Directory "/usr/share/trac/htdocs"> Options Indexes MultiViews AllowOverride None Order allow,deny Allow from all </Directory> </VirtualHost>
I had to copy
trac.cgi to my local cgi directory making sure it was executable, and also I changed the ownership on the Trac environment to the user that Apache runs on.
Although the instructions say that you should also change the ownership of your subversion repository, I think that this is only required if you use the Berkley DB data store, which requires a writable repository even for read-only operations. I'm using the FSFS data store that does not have this restriction. I didn't change the ownership of my repository, and so far it seems to work ok.
After getting this to run, I also make the setup of the
tracd standalone Trac server. You just need to create a htdigest password file with the
command of Apache, making sure that you use the
I think I'm going to use the
tracd live instead of Apache, at least until I try the FastCGI stuff. I like the support of multiple projects that
tracd has, it seems better than the Apache setup.
You can also mess around with the
config.ini file of your Trac environment. I did it just to change the
default_charset to UTF-8, and enable logging.
After this, I was up and running and I had a working Trac installation.
Exporting a darcs repo to a svn repo
Now the fun part: how to keep using your favorite SCM and use all the Trac goodness.
Enter the Tailor script: a almost universal bi-directional SCM converter.
I'm using the old version for now, only because I found some other people using the same setup, but my final setup is going to use the currently in beta tailor, that gives a lot more flexibility (my favorite feature of the new version is the ability to preserve the author and the date of the change-set when you sync from darcs to svn).
After a quick download with
darcs get --partial http://nautilus.homeip.net/~lele/projects/cvsync/, and a quick read over the
README, you let it run:
- check out your target svn repository;
- bootstrap your svn repo with the contents of the darcs repo;
- update the sync after each change-set.
I created a directory on my home directory,
darcs2svn, to keep all the stuff to do this migrations.
mkdir darcs2svn cd darcs2svn svn co file:///home/melo/sites/svn_repos/test2/trunk test2 Checked out revision 4. ~/src/cvsync/tailor.py \ --bootstrap \ --source-kind=darcs \ --repository=/home/melo/sites/darcs.simplicidade.org/docs/repos/darcs2rss \ --target-kind=svn \ ~/darcs2svn/test2
After this we have a single change-set in the svn repository and I'm able to see it from Trac.
This is not that good. The history is lost. I found two workarounds to this.
The first one is to use the
--revision parameter of
tailor.py. It allows you to specify a tag on the darcs repository. It will then import all the change-sets up to that tag as a single one into svn. Then, further updates will be imported one by one. It's not perfect, because if you don't have a tag early on in your darcs repository, you might lose a lot of change-sets.
A better way is to use a temporary darcs repo and then hack a bit the tailor status file. First you create a new empty darcs repo.
mkdir x; cd x; darcs init. Then to prevent tailor from failing, you create an empty change-set. The best way to do it is to tag your empty repository with the
darcs tag command.
Now you can run the tailor bootstrap command changing the
--repository to point to the temporary darcs repository. It will create the initial bootstrap and state information.
Now you need to change the
tailor.info inside your svn repository. You'll see that the 4th line is your source darcs repository (notice that I'm not using the latest betas of tailor, the format of the tailor.info might have changed in later versions). Just change it to your real darcs repository.
Whenever I do a new change-set in darcs, you just need to run
~/src/cvsync/tailor.py ~/darcs2svn/test2. All the change-sets that are missing from the svn repository will be imported, one by one.
To make sure that Trac is in sync with all this changes, run the following command:
trac-admin environment_path resync.
That's all there is to it.
One small warning: after the import, you might notice that the number of change-sets in darcs is bigger than the revisions in svn. The
tailor script tries to import darcs change-sets that the
darcs tag command creates, but those change-sets don't change any files, so no revision is created for them. This means that the subversion repository will not have your darcs tags, but it explains the difference between the number of change-sets.
Things to improve
This setup works but it's still not perfect. I haven't figure it out how-to bootstrap the svn repository with all the change-sets from the darcs repository. Right now, he bundles all the darcs change-sets in a single one. I assuming that this is a limitation on my part. We'll see.
Update: You can use an empty temporary repository and some small hack to work around this and import all the change-sets. See above for detailed information.
Also, the author and date of the change-set is not kept between repositories. This limitation seems to be solved in the new version of tailor. I'll have to try it
Until Trac gets darcs support, this setup works very well for me. I'll be moving my projects to Trac in the next weeks. I'll probably wait a bit to use the new tailor script.
By the way, it took me more time to write this how-to than to setup up the entire system...
After I wrote all of this, I found this message in the Darcs users mailing list. Well, I never said I was the first one to think about this stuff, but I hope this helps others to use Trac with darcs or other SCM supported by the tailor script.
I'll keep this post updated as I refine my solution.
- 20050819: initial version
- 20050820: workaround to import all the darcs change-sets
- 20050820: spelling, some clarifications about number of change-sets