Get bug tracker for your gitorious repository
First blog in quite a while this. I have recently been playing around with new tools, namely Apache, MySQL, Gitorious and lately Trac. Getting the http server running on my desktop was much easier than I first expected, and there are too many fun tools out there to try out once you have that going. Today I would like to write a tutorial on how you get Trac to work with your gitorious repository. This tutorial will include a setup that makes it possible to write commit messages that are automatically appended to a given bug/feature request, and even make it possible to close the ticket. I assume that you already have a git repository in a folder /path/to/your/git/repo. If it is not a bare repository, the path is
/path/to/your/git/repo/.git/. I also assume you have a python 2 install on your machine.
First, you need to install Trac. On Arch Linux this is readily available in the package manager, and I suppose that is the case for most other distributions as well (correct, this tutorial is not for the Windows users of you). Further you need to install the GitPlugin from http://trac-hacks.org/wiki/GitPlugin. This can be done with the command
This assumes you are using Trac 0.12. Have a look at the link for further information. Now it is time to set up a trac project. The trac project is a folder which will contain the configuration and information for that bug tracker. This folder can be moved around as you feel like (so backup is easy). Set up the environment with
trac-admin /path/to/folder/wher/you/want/trac/project initenv
This will ask you for the project title and what kind of database you want. SQLite is the default option, and a good one in my opinion since you then have all information contained in this folder. Now you open the folder /path/to/folder/wher/you/want/trac/project/conf/trac.ini where you need to add some options under new categories, namely
tracext.git.* = enabled
tracopt.ticket.commit_updater.committicketreferencemacro = enabled
tracopt.ticket.commit_updater.committicketupdater = enabled
cached_repository = false
persistent_cache = false
The git category is some specific options for the plugin. The components-category contains the plugins you want activated. This includes the CommitTicketUpdater plugin that is included in the default Trac installation. In the trac category you need to change the following options for the git plugin:
repository_dir = /path/to/your/git/repo
repository_type = git
Remember that the path to your repository should include the .git folder if it is a normal repository. Finally, for the CommitTicketUpdater plugin you need to add some parameters in the ticket category. This is further explained in the link above.
commit_ticket_update_commands.close = fixes
commit_ticket_update_commands.refs = <ALL>
commit_ticket_update_check_perms = false
commit_ticket_update_notify = false
This finalizes the configuration of Trac. Lastly you probably want a way for people to log in. What I chose (and it is probably a weak solution but it works), was to use
htpasswd for this purpose. This is explained in the installation wiki for Trac. To add the first user I used
htpasswd -c /path/to/folder/wher/you/want/trac/.htpasswd <user>
and then for successive user accounts I dropped the "-c". You can then start your server with the command
tracd -p 8000 \
--basic-auth="*,/path/to/folder/wher/you/want/trac/.htpasswd,Some Credential" \
and open it up the link http://localhost:8000 in your browser. Note that you can have many Trac projects, just add the path to each project separated by space in this command. You probably want to create a small script that contains this command and call it something like "start" so that you do not have to manually write this command every time… Put it in /path/to/folder/wher/you/want/trac/.
Adding a hook to the git repository
Now, in order to get your commits to automatically append to tickets, you need to add what is called a hook to the git repository. This is essentially a program that is ran at a certain point during your interaction with git, for example every time you make a commit (pre-commit or post-commit). For a bare repository you find them in /path/to/git/repo/hooks, and for a normal repository you find them in /path/to/git/repo/.git/hooks/. What you need to do is to get your git repository to execute a command in trac-admin which updates the tickets with the new commit(-s), namely the command
trac-admin /path/to/folder/wher/you/want/trac/project changeset added <repository-name> <commit-hash>
If you just want this to work for yourself locally, it is quite easy. The script named "post-commit" is executed after every commit, and since you can only commit one commit at the time (right?), you can then just get the commit hash from your log. Add this to post-commit:
commit_hash=$(git log --all -1 --pretty="%H")
trac-admin /path/to/folder/wher/you/want/trac/project changeset added changeset added '(default)' $commit_hash
The repository name is ‘(default)’ by default. This is there to support multiple repository functionality (I haven’t gotten that far yet).
For a more practical case you might want a bare repository that several people have push access to, so that every time someone pushes changes to this repository the tracker gets updated. This complicates things, because there are no hooks that are ran once per commit (to my knowlegde), so the script above would only add the last commit sent in a commit stack. Luckily there is help, and the GitPlugin guys wrote two scripts for the purpose which you can find here. There is one script for pushing changes from all branches, and one script for only letting changes to the master branch be appended to the tickets. Add the one you want into post-receive, which is a hook that is ran after each commit stack has been pushed to the repository.
Now you are all set (if I have remembered all the stages). Try to log into your tracker, create a new ticket, and then try to commit (and push if you chose the second option) and see if your changes appear. You can refer to a given ticket in your commit message with #1, like "This is related to bug #1". In the configuration above we set commit_ticket_update_commands.close to "fixes", which means that if we write "This fixes #1" in our commit message, then ticket #1 will be closed automatically. Obligatory screenshot below.
If you find some missing information then please let me know and I’ll try to update the walkthrough.