[[PageOutline(2-3)]] = Git support in Trac (#10594) = Starting with version [milestone:1.0], Trac features built-in support for [http://git-scm.com/ Git] so that it can be used as one of the VersionControlSystem for 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. == Features == * Browsing source code in a Git repository via the TracBrowser * Viewing the change history of a file or directory using TracRevisionLog * Performing diffs between any two files or two directories * Displaying submitted changes in the TracTimeline * (Optionally) caching TracChangeset information in Trac's database * Caching Git commit relation graph in memory * Using the TracSearch page to search change descriptions * Annotation support, also known as "blame" operation * Interpretation of 40-character wide hex-strings as sha1 commit checksums == Git == === Download and Installation === You need to have the `git` command line tools installed. You can download Git itself from [http://git-scm.com/download Git:Download]. We try to maintain backward compatibility with versions of Git as old as 1.5.6, up to the latest. Better use a recent version however. === Configuration === 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 [#hooks 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). == Trac == The Trac Git support is included with Trac since 1.0 as an optional component: `tracopt.versioncontrol.git`. 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. ==== New environment For general instructions, see TracInstall. When creating a new environment with TracAdmin `initenv` command, - for the ''repository type'', specify `git` instead of the default `svn`. - for the ''repository directory'', specify the location of the Git repository (including the ending `.git` directory). Your [wiki:TracIni /conf/trac.ini] configuration file should have a `[trac]` section similar to the following: {{{ [trac] repository_type = git repository_dir = /path/to/my/git/repository/.git }}} Also in there, make sure you 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 `[trac]` section in your [TracIni trac.ini] so that it contains the appropriate values for the `repository_type` and `repository_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 is basically two ways to do it, either via the [TracIni#repositories-section "[repositories]"] section of the TracIni file, or via the web administration interface using the //Version Control / Repositories// panel. For more details, see the TracRepositoryAdmin. ==== Fine tune `trac.ini` settings #settings Besides the `git_bin` setting discussed above, there are a few more Git specific settings that can be specified in [TracIni#git-section "TracIni [git]"] section. === Setting up post-receive hooks === #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 [http://git-scm.com/book/en/Customizing-Git-Git-Hooks#Server-Side-Hooks post-receive] hook in the `.git/hooks` repository so that it calls `trac-admin repository` appropriately. enable post-receive hook functionality on your repository, put a post-receive script into `your_repository/.git/hooks/`. TODO: Include post-receive scripts attached to http://trac-hacks.org/wiki/GitPlugin#post-receivehookscripts You can then enable the CommitTicketUpdater functionality in your `trac.ini` by adding: {{{ tracopt.ticket.commit_updater.* = enabled }}} to the `[components]` section. == Troubleshooting * `repository_dir` in the configuration section needs to be the `.git` repository directory (i.e. the one containing the file `HEAD` and `config`), not the working tree directory that holds the `.git/` folder (#11297). * Wrong permissions may also be the cause of the error `GitError: GIT control files not found, maybe wrong directory?`. Make sure the `repository_dir` argument is accessible via git by the `tracd` process. * If you are noticing a slow down in trac with a repository above 500 commits, try disabling the caching. It seems to bog things down as a repo grows(!) * Don't forget to enable the plugin: {{{ [components] tracopt.versioncontrol.git.* = enabled }}} * If you don't see the `shortrev` and `commit` branch, you probably have caching enabled (`cached_repository = true, persistent_cache = true`). Set those to false. * 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). == Known Issues [[TicketQuery(component=plugin/git,status=!closed,type=defect)]] == History The Git support was initially developed as a plugin by Herbert Valerio Riedel for Trac 0.10-0.13. See TracHacks:GitPlugin / [https://github.com/hvr/trac-git-plugin GitHub]. For Trac 1.0, it has now been included as an optional component, and is maintained and developed here.