= Git Plugin for Trac =

== Description ==

This is yet another plugin for Trac 0.10/0.11 which enables [http://git.or.cz/ GIT] to be used instead of [http://subversion.tigris.org/ Subversion] for the trac:VersioningSystemBackend

=== Features ===

 - Browsing source code in a Git repository via the TracBrowser
 - Viewing the change history of a file or directory using TracRevisionLog
 - Performing [trac:TracDiff diffs] between any two files or two directories
 - Displaying submitted changes in the TracTimeline (0.11)
 - (Optionally) caching TracChangeset information in Trac's database (0.11)
 - Caching Git commit relation graph in memory (0.11)
 - Using the TracSearch page to search change descriptions (0.11)
 - Annotation support, also known as "blame" operation (0.11)
 - Interpretation of 40-character wide hex-strings as sha1 commit checksums
 - ...

=== Requirements ===

||        || '''0.10 Plugin''' || '''0.11 Plugin'''/'''0.11-py2.4 Plugin''' ||  '''0.12 Plugin''' ||
|| Trac   || 0.10.x      || 0.11.x || 0.12dev (trunk) ||
|| Python || 2.4+        || 2.5+/2.4+ || 2.5+ ||
|| GIT    || 1.4.4+      || 1.5.2+ (for plugin v0.11.0.1) [[BR]] 1.5.6+ (for plugin v0.11.0.2+) || 1.5.6+ ||

== Example Sites ==

 - [http://nanosleep.org/proj/trac-git-plugin/browser nanosleep.org's GitPlugin branch] (using trac 0.10)

=== Sites that were previously using GitPlugin ===

 - The GIT repositories at [https://hosted.fedoraproject.org/ Fedora Hosted]
 - [http://parted.alioth.debian.org/cgi-bin/trac.cgi/browser GNU Parted]
 - [https://reductivelabs.com/trac/puppet/browser ReductiveLabs Puppet]
 - [http://labs.ohloh.net/ Ohloh Labs] 
 - [http://www.realassignmentwriting.com assignment help]
 - [http://www.realessaywriting.com essay help]
 - [http://www.uk2.net/web-hosting/ Hosting]

== Bugs/Feature Requests == 

As this is for now just a proof of concept implementation, it has quite some deficiencies, some of which exist as tickets already:

[[TicketQuery(component=GitPlugin&status!=closed)]]

...and other potential issues/todos which aren't ticket-tracked yet:

 * ~~does not highlight sha1sums automatically~~
 * issues with filenames containing newlines (seems to be a Trac bug)
 * ...

Existing bugs and feature requests for GitPlugin are 
[report:9?COMPONENT=GitPlugin here] (all including closed ones are [report:10?COMPONENT=GitPlugin here]).

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=GitPlugin&owner=hvr new ticket].

== Download, Source ==

Download the [download:gitplugin zipped source], check out GitPlugin from [http://trac-hacks.org/svn/gitplugin Subversion], or [source:gitplugin browse the source].

(An experimental branch of this plugin with a hacky caching feature and some bug fixes is available from [http://nanosleep.org/proj/trac-git-plugin/ here].)

== Install ==

See also generic instructions at trac:TracPlugins

If you have a recent [http://pypi.python.org/pypi/setuptools setuptools] version installed, you can directly install GitPlugin from the Subversion repository.

For Trac 0.11:
{{{
#!sh
easy_install http://trac-hacks.org/svn/gitplugin/0.11
}}}
or alternatively the Python 2.4 backport:
{{{
#!sh
easy_install http://trac-hacks.org/svn/gitplugin/0.11-py2.4
}}}

For Trac 0.12
{{{
#!sh
easy_install http://trac-hacks.org/svn/gitplugin/0.12
}}}

== Configuration ==

Simply point your Trac instance to a local git repository:
{{{
[trac]
repository_dir = /var/git/Test.git
repository_type = git

## the following is only for the 0.11 branch
[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

## executable file name (optionally with path) of git binary; default: 'git'
git_bin = /usr/src/git-dev/git
}}}

'''/!\ NOTE''': the `Test.git` above 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.

'''/!\ NOTE''': 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.

If installed globally, don't forget to enable the plugin:
{{{
[components]
# for plugin version 0.10
gitplugin.* = enabled

# for plugin version 0.11.0.1+
tracext.git.* = enabled 
}}}

=== post-receive hook scripts ===

For Trac 0.11 see attachments below.

With Trac 0.12 a VC independent plugin approach to handling ticket references in commit messages has been put into place.
Thus for 0.12 in you basically need to enable the !CommitTicketUpdater component in `trac.ini` or via the webinterface under 'Admin/Plugins'. Additionally you have to call `trac-admin TRAC_ENV changeset added <commitid(s)>`, e.g. by putting a `post-receive` script into yourRepository.git/hooks/ along the lines of:
{{{
#!python
#!/usr/bin/env python

import sys
from subprocess import Popen, PIPE, call

GIT_PATH = '/usr/bin/git'
BRANCHES = ['master']
TRAC_ENV = '/srv/trac/myproj'
REPO_NAME = '(default)'

def call_git(command, args):
    return Popen([GIT_PATH, command] + args, stdout=PIPE).communicate()[0]

def handle_ref(old, new, ref):
    # If something else than the master branch (or whatever is contained by the
    # constant BRANCHES) was pushed, skip this ref.
    if not ref.startswith('refs/heads/') or ref[11:] not in BRANCHES:
        return

    # Get the list of hashs for commits in the changeset.
    args = (old == '0' * 40) and [new] or [new, '^' + old]
    pending_commits = call_git('rev-list', args).splitlines()[::-1]

    call(["trac-admin", TRAC_ENV, "changeset", "added", REPO_NAME] + pending_commits)

if __name__ == '__main__':
    for line in sys.stdin:
        handle_ref(*line.split())
}}}

== Help ==

09/06/2010
I was able to get this running with ubuntu karmic, trac 0.12rc and git version 1.7.1 (served with a gitosis install)
after encountering the issue mentioned in [http://trac-hacks.org/ticket/5480 bug #5480]
("!GitError: GIT control files not found, maybe wrong directory?") with:
{{{
  chmod o+rx /home/git/repositories/blah-blah.git
}}} 


12/13/2009
Anyone get this working in a shared hosting environment? I've tried with trac 0.11 and I get errors about it not finding the Git component (I did all the trac.ini stuff). If you have instructions please contact me, codecraig -at- gmail -dot- com ....thanks

15/04/2010
Apparently this does not work at all... At least not for me. trac 0.11. '''Please file a ticket with a decent problem report, instead of writing random notworkings on the wikipage.'''

13/07/2010
I've managed to get it to work (at least, for it not to complain about the plugin being missing) by adding:

file = /etc/trac/trac.ini

to the \[inherit\] section of the individual projects' trac.ini.   Or, of course, you could probably just configure the plugin for that particular project's trac.ini directly.

== Recent Changes ==

[[ChangeLog(gitplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:hvr Herbert Valerio Riedel] [[BR]]
'''Contributors:''' Hans Petter Jansson