Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100755 297 lines (211 sloc) 10.106 kb
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
1 =======================================================================
2 Copyright 2009 Broadcom Corporation
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 ========================================================================
16
17
18 git-jira-hook README
19 ********************
20
21 Author: Joyjit Nath
22 *******************
23
24
25 Table of Contents
26 =================
27 1. Introduction
28 2. System Requirements
29 3. Installation
30 4. Using git-jira-hook
31 5. Known limitations
32 6. Frequently Asked Questions (FAQ)
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
33 7. Credits
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
34
35
36 1. Introduction
37 ===============
38
39 1.1 Get git and Jira to work in Harmony
40 ---------------------------------------
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
41 If you are using git [1] for source control and Jira [2] for bug
42 tracking, then the git-jira-hook script might be useful to you.
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
43
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
44 Once you have the script setup in your environment, every time you
45 make a git commit, a comment is automatically posted to an open
46 issue in Jira.
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
47
48 This script will also "enforce" that for every git commit, you have at
49 least one Jira issue that you are referencing.
50
51 This way you have a paper trail of the history behind each and every
52 git commit.
53
54 This is particularly useful for corporate git repositories.
55
56
57 1.2 Example use
58 ---------------
59 In order to specify which issue (or issues) you want the commit message
60 to get tracked to in Jira, you place magic text markers such as:
61
62 "refs #NNN" or "fixes #NNN"
63
64 anywhere in your commit message, where "NNN" is the name of an open
65 Jira issue.
66
67 For example, say you have typed in the following commit message in
68 your git repository.
69
70 Hey look! This is my very first git-commit
71
72 Using the new and fresh git-jira-hook
73
74 refs #SW-189, refs #HW-278 fixes #FW-702
75
76
77 The following things will happen:
78
79 In your Jira bug database, for projects named "TST", "HW" and "FW"
80 in Jira, for issue numbers "SW-189", "HW-278", and "FW-702", the
81 following comments will be added:
82
83 commit 424daa955f5c8a17aab9d524071f65f1999769a9
84 Author: Joyjit Nath <joyjit@mycompany.com>
85 Date: Tue Aug 25 15:12:39 2009 -0700
86
87 Hey look! This is my very first git-commit
88
89 Using the new and fresh git-jira-hook
90
91 refs #SW-189, refs #HW-278 fixes #FW-702
92
93 In addition,
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
94 * the issue "FW=702" will be marked as resolved. (NOTE:
95 this "resolved" part does not work yet. See "Known
96 Limitations" section.)
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
97
98 1.3 Wait! there's more
99 -----------------------
100
101 If your git repository is exposed using gitweb [3], an hyperlink
102 linking to the exact commit will also be embedded in the Jira issue
103 comment that was added. This enables anyone to examine your git
104 commit simply by clicking on the hyperlink.
105
106 2. System Requirements
107 ======================
108 - Python 2.x and python modules: SOAPpy, ConfigParser.
109 I have tested with Python 2.5.2.
110
111 - A Jira installation with Remote APIs enabled.
112
113 - git version 1.6.x.y (I have tested with 1.6.0.4).
114
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
115 - Linux or some other similar Unix flavor (I have tested with
116 CentOS 5.x).
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
117
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
118 - OPTIONAL, but Highly recommended: gitweb [4] which has been
119 setup with "upstream" git repositories.
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
120
121
122
123 3. Installation
124 ===============
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
125 Here is a typical example of how this hook may be used.
126
127 In a corporate setting where git is used, there is typically an
128 "upstream" or "public" repository. And then developers have their
129 "private" repositories. For their day-to-day work, the developers
130 use their private repositories. Periodically, they (either
131 directly, or via gatekeepers) push changes from their private
132 repository to the "upstream" one. Also, the "upstream" repository
133 is typically a bare repository, and no actual commits are done
134 here.
135
136 In the private repository, the hook should be installed, but only
137 *partically*. Every time a commit is made, the hook only checks to
138 make sure that the commit text conforms to correct formatting (i.e.
139 the magic references to Jira issues are present). No Jira issues
140 are updated.
141
142 The hook is completely installed in the "upstream" repository.
143
144 Whenever a commit is made in the upstream repository or a "git push"
145 is done to it, the installed hook will kick in and validate the
146 commit message, followed by update of the Jira issue.
147
148
149 3.1 Installtion for "private" repository
150 ----------------------------------------
151 (i) Copy this script to <your-git-repo-GIT-dir>/hooks/commit-msg
152 and mark it executable
153 Example:
154 cp git-jira-hook joyjit-project/.git/hooks/commit-msg
155 chmod +x joyjit-project/.git/hooks/commit-msg
156
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
157
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
158 (iii) Set the following git config value
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
159 Example:
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
160 cd joyjit-repo
161 git config jira.url "http://jira.mycompany.com"
162
cc08e025 » Joyjit Nath
2009-08-20 Added branch support for local repositories
163 (iv) [Optional] If you wish jira integration to be triggered only
d942c34e » Joyjit Nath
2009-08-21 Added branch support for remote repositories
164 on certain branches, add a comma-separated list of
cc08e025 » Joyjit Nath
2009-08-20 Added branch support for local repositories
165 branch names to git config "git-jira-hook.branches"
166 For example:
167
168 cd joyjit-repo
169 git config git-jira-hook.branches "jira1,jira2"
170
171 This will cause the integration to be triggered only on
172 git branches jira1 and jira2. For instance, if you make a commit
173 to branch "master", the hook will simply stay disabled.
174
175 By default, if you do not set this config, all branches are
176 checked.
177
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
178 See the "Frequently Asked Questions" section to figure out what
179 values to use for your "jira.url".
180
181 3.2 Installation for "upstream" repository
182 ------------------------------------------
183 (i) Copy this script to
184 <upstream-repo-GIT-dir>/hooks/{commit-msg|post-commit|update|post-receive}
185 and mark it executable
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
186
187 Example:
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
188 cp git-jira-hook upstream-project.git/hooks/commit-msg
189 cp git-jira-hook upstream-project.git/hooks/post-commit
190 cp git-jira-hook upstream-project.git/hooks/update
191 cp git-jira-hook upstream-project.git/hooks/post-receive
192 chmod +x upstream-project.git/hooks/commit-msg
193 chmod +x upstream-project.git/hooks/post-commit
194 chmod +x upstream-project.git/hooks/update
195 chmod +x upstream-project.git/hooks/post-receive
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
196
197 (iii) Set the following git config values (Note: gitweb.url config is
198 recommended, but Optional): "jira.url" "gitweb.url"
199 Example:
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
200 cd upstream.git
201 git config jira.url "http://jira.mycompany.com"
202 git config gitweb.url "http://git.mycompany.com/gitweb.cgi/p=upstream-project.git;a=commit;h="
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
203
d942c34e » Joyjit Nath
2009-08-21 Added branch support for remote repositories
204 (iv) [Optional] If you wish jira integration to be triggered only
205 on certain branches, add a comma-separated list of
206 branch names to git config "git-jira-hook.branches"
207 For example:
208
209 cd joyjit-repo
210 git config git-jira-hook.branches "jira1,jira2"
211
212 This will cause the integration to be triggered only on
213 git branches jira1 and jira2. For instance, if you make a commit
214 to branch "master", the hook will simply stay disabled.
215
216 By default, if you do not set this config, all branches are
217 checked.
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
218 See the "Frequently Asked Questions" section to figure out what values
219 to use for your "jira.url" and "gitweb.url"
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
220
221
222 4. Using git-jira-hook
223 ======================
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
224 When you are read to make a git commit, make sure that you have an
225 appropriate open jira issue. There can be more than one open issues.
226 Lets say this commit deals with Jira issues FOO-23 and BAR-42 and
227 also marks FOO-56 as resolved.
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
228
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
229 Anywhere in your commit message, you must put the following strings
230 (without the quotes):
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
231 "refs #FOO-23"
232 "refs #BAR-42"
233 "fixes #FOO-56"
234
235
236
fb71a181 » Joyjit Nath
2009-08-17 Support for git push (bare repository)
237 And then you do a "git commit" the normal way. At this time, assuming
238 the "private" repository, the commit message will be checked for
239 references to Jira issues and the commit will succeed only if these
240 issues exist.
241
242 And then, at a later time, when you do "git push" to push your changes
243 upstream, the final validation and Jira issue update will be done.
244
245 NOTE: The "fixes" feature does not work yet :<
246
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
247
248 5. Known Limitations
249 ====================
250
d9ffffc8 » Joyjit Nath
2009-08-17 README file minor change
251 I am working to fix all of these issues:
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
252 * The "fixes" text does not yet mark the Jira issue as resolved.
253
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
254 * The error messages are a bit confusing (cluttered with too much detail).
255
d9ffffc8 » Joyjit Nath
2009-08-17 README file minor change
256 DISCLAIMER: This is my very first attempt at writing python code, so it is not
257 very well written.
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
258
259
260 6. Frequently asked Questions
261 =============================
262
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
263 Q 6.1 What value should I use for "jira.url" git config?
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
264 A. It depends on your Jira server setup. When you log-in to the Jira
265 server using a browser, the URL to the login page typically looks like:
266 http://jira.mycompany.com/secure/Dashboard.jspa
267 In which case, your "jira.url" should be "http://jira.mycompany.com"
268
269
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
270 Q 6.2 What value should I use for "gitweb.url" git config?
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
271 A. Assuming you have gitweb enabled for your repository, this is the URL which you
272 use to access gitweb.
273 for instance, in order to view commit "424daa955f5c8a17aab9d524071f65f1999769a9"
274 in gitweb, if you use:
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
275 http://git.mycompany.com/gitweb.cgi?p=joyjit-repo/.git;a=commit;h=424daa955f5c8a17aab9d524071f65f1999769a9
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
276
277 Then the "gitweb.url" to use is:
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
278 "http://git.mycompany.com/gitweb.cgi?p=joyjit-repo/.git;a=commit;h="
279
280
281 7. Credits
282 ==========
283 This script was inspired by the following:
284 http://github.com/dreiss/git-jira-attacher/tree/master
285 http://confluence.atlassian.com/display/JIRAEXT/Jira+CLI
286
287
288 8. References
289 =============
290 [1] Git, an source configuratiin management ("SCM") tool
291 http://git-scm.com/
292
293 [2] Jira, a bug tracking system
294 http://www.atlassian.com/software/jira
e30e405b » Joyjit Nath
2009-08-12 Initial commit for git-jira-hook
295
92c88296 » Joyjit Nath
2009-08-12 Fixed minor typo in README
296 [3] Gitweb, a web based browser for git
297 http://git.or.cz/gitwiki/Gitweb
Something went wrong with that request. Please try again.