Git support in Trac
Please note that we're still considering the level of performance to be sub-optimal, so it might not work for you. Small to medium sized repositories should be handled reasonably well, however.
- Browsing source code via the TracBrowser
- Viewing the change history of a file or directory using TracRevisionLog
- Performing diffs between any two files or directories
- Displaying changes in the TracTimeline
- (Optionally) caching TracChangeset information in Trac's database
- Caching Git commit relation graph in memory
- Search change descriptions via TracSearch
- Annotation support, also known as "blame" operation
- Interpretation of hex-strings in wiki content as sha1 commit checksums, with a configurable minimum character width
Download and Installation
You need to have the
git command line tools installed. You can download Git itself from
We try to maintain backward compatibility with versions of Git from 1.5.6 to the latest. It's better use a recent version, however.
The configuration has to be done mainly on the Trac side,
there's nothing required to do on the Git repository side.
Some advanced use cases necessitate however to install a
post-receive hook in the Git repository (see below).
Note that the repository should be made accessible as a local repository.
Thanks to the distributed nature of Git, that's always possible. If the
repository is not already local, simply
git clone it.
The Trac Git support is included with Trac since 1.0 as an optional component:
You simply have to explicitly enable the plugin in TracIni:
[components] tracopt.versioncontrol.git.* = enabled
The web administration interface can also be used for this, using the General / Plugins panel.
Setting up a Trac environment
You can either reuse an existing Trac environment, or create a brand new one.
For general instructions, see TracInstall.
When creating a new environment with TracAdmin
- for the repository type, specify
gitinstead of the default
- for the repository directory, specify the location of the Git repository
(for Trac < 1.0.2 the path of a non-bare repository must end in a
Your <trac_environment>/conf/trac.ini configuration file
should have a
[trac] section similar to the following (Trac < 1.1.3):
[trac] repository_type = git repository_dir = /path/to/my/git/repository/.git
[repositories] section similar to the following (Trac 1.1.3 and later).
[repositories] .type = git .dir = /path/to/my/git/repository/.git
Specify the location of the
git executable, in case it's not the default
/usr/bin/git. As an example, for Windows:
[git] git_bin = C:/Dev/msysgit/bin/git.exe
See also #settings below.
Adding a Git repository to an existing environment
If all you need is to work with a single git environment, it is enough
to modify the
[repositories] section in your trac.ini so that it
contains the appropriate values for the
.dir options, like in the above example.
However, if you need more than one git repository, or if you want to keep your old Subversion repository as the default repository in order to not break the TracLinks pointing to source files and changesets contained in that repository, you can add non-default repositories.
There are basically two ways to do that, either via the [repositories] section of the TracIni file, or via the web administration interface using the Version Control / Repositories panel. For more details, see the TracRepositoryAdmin.
git_bin setting discussed above, there are a few more Git specific settings that can be specified in TracIni [git] section.
Setting up post-receive hooks
If you want to benefit from some advanced features for your repository,
like automatically update your tickets based on the content of the commit
messages (CommitTicketUpdater) or smart caching, then you need to create
or modify the post-receive hook in the
repository so that it calls
trac-admin repository appropriately.
enable post-receive hook functionality on your repository, put a post-receive script into
TODO Include post-receive scripts attached to th:GitPlugin#post-receivehookscripts
You can then enable the CommitTicketUpdater functionality in your
trac.ini by adding:
tracopt.ticket.commit_updater.* = enabled
- Don't forget to enable the plugin:
[components] tracopt.versioncontrol.git.* = enabled
- For Trac < 1.0.2, the
repository_dirin the configuration section needs to be the
.gitrepository directory (i.e. the one containing the file
config), not the working tree directory that holds the
.gitfolder (#11297). However, a
barerepository will have these control files in the top-level directory and will not contain a
- Wrong permissions may also be the cause of the error
GitError: GIT control files not found, maybe wrong directory?. Make sure the repository path is accessible via git by the
- For Trac < 1.0.6, a repository with many branches makes Trac slow (#11971).
- If you don't see the
commitbranch, you probably have caching enabled (
cached_repository = true,
persistent_cache = true). Set those to false.
- For Trac < 1.0.2, the source browser can throw an error when trying to kill a git log process; it's not clear why it should be an error for the process to have completed. This problem manifests as a stack trace with terminate_nix at the end (#10958).
- For Trac < 1.0.5,
gitprocesses can stay open forever like this with bitten-slave (#11973).
/usr/bin/git --git-dir=/path/to/git log --pretty=format:%n%H --name-status 324a8d5... -- ...
- Setting fine grained permissions using AuthzPolicy does not work
- TypeError: Git object id must be byte or a text string, not: int
- Allow git commit hashes to be abbreviated to 7 characters
- tracopt.versioncontrol.git.tests.git_fs.GitCachedRepositoryTestCase failure on Windows
- UnicodeDecodeError: 'utf8' codec can't decode byte 0xca in position 8: invalid continuation byte
The Git support was initially developed as a plugin by Herbert Valerio Riedel for Trac 0.10-0.13. See TracHacks:GitPlugin / GitHub. Since Trac 1.0 it has now been included as an optional component (#10594), and is maintained and developed with Trac.