| 1 | [[PageOutline(2-3)]] |
| 2 | = Git Plugin for Trac (#10594) = |
| 3 | |
| 4 | This a plugin for Trac which enables |
| 5 | [http://git-scm.com/ Git] |
| 6 | to be used as the VersionControlSystem for Trac. |
| 7 | |
| 8 | == Download and Installation == |
| 9 | |
| 10 | == Git == |
| 11 | |
| 12 | You can download Git itself from |
| 13 | [http://git-scm.com/download Git:Download]. |
| 14 | |
| 15 | We try to maintain backward compatibility with versions of Git as old as 1.5.6, |
| 16 | up to the latest. Better use a recent version however. |
| 17 | |
| 18 | === Configuration === |
| 19 | |
| 20 | The configuration has to be done on the Trac side, |
| 21 | there's nothing to do on the Git repository side, |
| 22 | except for the fact that the repository should be made |
| 23 | accessible as a local repository. |
| 24 | Thanks to the distributed nature of Git, that's |
| 25 | always possible (if the repository is not already local, |
| 26 | simply `git clone` it). |
| 27 | |
| 28 | == Trac Git plugin == |
| 29 | |
| 30 | The Trac Git plugin is included with Trac (since 0.13) as an optional component. |
| 31 | You simply have to explicitly ''enable'' the plugin in TracIni: |
| 32 | {{{ |
| 33 | [components] |
| 34 | tracopt.versioncontrol.git.* = enabled |
| 35 | }}} |
| 36 | |
| 37 | === Setting up a Trac environment === |
| 38 | |
| 39 | You can either reuse an existing Trac environment, |
| 40 | or create a brand new one. |
| 41 | |
| 42 | For general instructions, see TracInstall. |
| 43 | |
| 44 | When creating a new environment with TracAdmin `initenv` command, |
| 45 | - for the ''repository type'', specify `git` instead of the default `svn`. |
| 46 | - for the ''repository directory'', specify the location of the Git repository |
| 47 | (including the ending `.git`). |
| 48 | |
| 49 | Your [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file |
| 50 | should have a `[trac]` section similar to the following: |
| 51 | {{{ |
| 52 | [trac] |
| 53 | repository_type = git |
| 54 | repository_dir = /path/to/my/hg/repository.git |
| 55 | }}} |
| 56 | |
| 57 | There's also a few Git specific settings in TracIni: |
| 58 | {{{ |
| 59 | [git] |
| 60 | ## let Trac cache meta-data via CachedRepository wrapper; default: false |
| 61 | cached_repository = true |
| 62 | |
| 63 | ## disable automatic garbage collection for in-memory commit-tree cache; default: false |
| 64 | persistent_cache = true |
| 65 | |
| 66 | ## length revision sha-sums should be tried to be abbreviated to (must be >= 4 and <= 40); default: 7 |
| 67 | shortrev_len = 6 |
| 68 | |
| 69 | ## minimum length for which hex-strings will be interpreted as commit ids in wiki context; default: 40 |
| 70 | wiki_shortrev_len = 7 |
| 71 | |
| 72 | ## executable file name (in case of doubt use absolute path!) of git binary; default: 'git' |
| 73 | git_bin = /usr/src/git-dev/git |
| 74 | |
| 75 | ## define charset encoding of paths stored within git repository; default: 'utf-8' |
| 76 | git_fs_encoding = latin1 |
| 77 | |
| 78 | ## enable reverse mapping of git email addresses to trac user ids; default: false |
| 79 | trac_user_rlookup = true |
| 80 | |
| 81 | ## use git-committer id instead of git-author id as changeset owner; default: true |
| 82 | use_committer_id = false |
| 83 | |
| 84 | ## use git-committer timestamp instead of git-author timestamp as changeset time; default: true |
| 85 | use_committer_time = false |
| 86 | }}} |
| 87 | |
| 88 | === Setting up post-receive hooks === |
| 89 | If you want to enable post-receive hook functionality on your repository, put a post-receive script into `your_repository.git/hooks/`. |
| 90 | |
| 91 | TODO: Include post-receive scripts attached to http://trac-hacks.org/wiki/GitPlugin#post-receivehookscripts |
| 92 | |
| 93 | You must also enable the CommitTicketUpdater functionality in your `trac.ini` by adding |
| 94 | |
| 95 | {{{ |
| 96 | tracopt.ticket.commit_updater.* = enabled |
| 97 | }}} |
| 98 | |
| 99 | to the `[components]` section. |
| 100 | |
| 101 | == Features == |
| 102 | |
| 103 | * Browsing source code in a Git repository via the TracBrowser |
| 104 | * Viewing the change history of a file or directory using TracRevisionLog |
| 105 | * Performing diffs between any two files or two directories |
| 106 | * Displaying submitted changes in the TracTimeline |
| 107 | * (Optionally) caching TracChangeset information in Trac's database |
| 108 | * Caching Git commit relation graph in memory |
| 109 | * Using the TracSearch page to search change descriptions |
| 110 | * Annotation support, also known as "blame" operation |
| 111 | * Interpretation of 40-character wide hex-strings as sha1 commit checksums |
| 112 | |
| 113 | == Troubleshooting |
| 114 | |
| 115 | * `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. |
| 116 | * 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. |
| 117 | * 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. |
| 118 | * Don't forget to enable the plugin: |
| 119 | {{{ |
| 120 | [components] |
| 121 | tracopt.versioncontrol.git.* = enabled |
| 122 | }}} |
| 123 | * 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. |
| 124 | |
| 125 | == Known Issues |
| 126 | |
| 127 | [[TicketQuery(component=plugin/git,milestone=plugin - git,status=!closed,type=defect)]] |
| 128 | |
| 129 | == History |
| 130 | |
| 131 | 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 |