[[PageOutline(2-3)]]
= Git Plugin for Trac (#10594) =

This a plugin for Trac which enables 
[http://git-scm.com/ Git] 
to be used as the VersionControlSystem for Trac.

== Download and Installation ==

== Git ==

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 on the Trac side, 
there's nothing to do on the Git repository side,
except for the fact 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 Git plugin ==

The Trac Git plugin is included with Trac (since 0.13) as an optional component.
You simply have to explicitly ''enable'' the plugin in TracIni:
{{{
[components]
tracopt.versioncontrol.git.* = enabled
}}}

=== 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 `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`).

Your [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file
should have a `[trac]` section similar to the following:
{{{
[trac]
repository_type = git
repository_dir = /path/to/my/hg/repository/.git
}}}

There's also a few Git specific settings in TracIni:
{{{
[git]
## let Trac cache meta-data via CachedRepository wrapper; default: false
cached_repository = true

## disable automatic garbage collection for in-memory commit-tree cache; default: false
persistent_cache = true

## length revision sha-sums should be tried to be abbreviated to (must be >= 4 and <= 40); default: 7
shortrev_len = 6

## minimum length for which hex-strings will be interpreted as commit ids in wiki context; default: 40
wiki_shortrev_len = 7

## executable file name (in case of doubt use absolute path!) of git binary; default: 'git'
git_bin = /usr/src/git-dev/git

## define charset encoding of paths stored within git repository; default: 'utf-8'
git_fs_encoding = latin1

## enable reverse mapping of git email addresses to trac user ids; default: false
trac_user_rlookup = true

## use git-committer id instead of git-author id as changeset owner; default: true
use_committer_id = false

## use git-committer timestamp instead of git-author timestamp as changeset time; default: true
use_committer_time = false
}}}

=== Setting up post-receive hooks ===
If you want to 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 must also enable the CommitTicketUpdater functionality in your `trac.ini` by adding

{{{
tracopt.ticket.commit_updater.* = enabled
}}}

to the `[components]` section.

== 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 

== 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. 
* 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.

== Known Issues 

[[TicketQuery(component=plugin/git,status=!closed,type=defect)]]

== History

The plugin was developed by Herbert Valerio Riedel for Trac 0.10-0.13 at th:GitPlugin / [https://github.com/hvr/trac-git-plugin GitHub]. For Trac 0.13 it has now been included as a bundled optional plugin, and is maintained and developed here