Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 356 lines (225 sloc) 18.283 kb
d85010c7 » jeff
2010-09-06 Added About section from schacons wiki to README
1 ## TicGit ##
a132ae49 » jeff
2010-09-06 Improved documentation
2
3 This project provides a ticketing system built on Git that is kept in a
4 separate branch in your projects Git repository.
5
d85010c7 » jeff
2010-09-06 Added About section from schacons wiki to README
6 ### About ###
7
8 TicGit is a simple ticketing system, roughly similar to the Lighthouse model, that is based in git. It provides a command line client that uses the ‘git’ gem to keep its ticketing information in a separate branch (called ‘ticgit’) within your existing git repository. All the data is file based and rarely changing, decreasing the likelihood of a merge issue. Right now, ticket branch merges need to be done manually and separately, but work is being done on a `ti sync` command to make this easier and more intuitive.
9
10 The idea is that it keeps your tickets in the same repository, but without mucking up your working tree. By using its own seperate branch to store its information it keeps the working trees in all your other branches untouched.
11
12 There are two interfaces available, the command line `ti` command and the `ticgitweb` web interface, though `ticgitweb` has many more prerequisites than `ti`.
13
14 It will automatically create the new branch the first time you use it, and it caches all the data (another working directory and index file) in your ~/.ticgit directory by default. If you delete that directory, it will just create it again the next time, you will lose no data (except some of your saved preferences).
15
16 TicGit is currently using itself to store its feature requests and bug reports.
a132ae49 » jeff
2010-09-06 Improved documentation
17
2e3215af » jeff
2010-09-06 Added prerequisites section again - got overwritten when moving READM…
18 ### Prerequisites ###
19
20 It is assumed that you already have a recent version of the Git revision control system installed. If it is not available through your package manager, you can download the latest Git source code from http://git-scm.com/ instead.
21
aa64e52f » jeff
2010-09-06 Removed superfluous line
22 It is also assumed that you have a recent version of rubygems installed. Older versions, such as the one available on Debian 5.0.5, will not work out of the box with the new gem repositories because the .deb in stable relies on rubyforge rather than rubygems for its operations. See [this bug](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=558251) for an example. If you are running an older version of rubygems, you may need to get the latest rubygems package from http://rubygems.org/ or [apt](http://jaqque.sbih.org/kplug/apt-pinning.html) [pinning](http://jeffwelling.github.com//2010/09/05/Apt-Pinning.html) before being able to properly install the git and ticgit gems.
2e3215af » jeff
2010-09-06 Added prerequisites section again - got overwritten when moving READM…
23
b9f53019 » jeffWelling
2010-09-06 Added note about the git version that the git gem needs and the notic…
24 The git gem requires a git version of 1.6.0.0 or later, but on Debian stable, git-core is currently (Sept 6th 2010) at 1.5.6.5. This isn't a fatal problem and we can continue using version 1.5.6.5 with the git gem, but you will see notices like this if you do
25
26 [WARNING] The git gem requires git 1.6.0.0 or later, but only found 1.5.6.5. You should probably upgrade.
27 Please specify at least one action to execute.
28
29 If these annoy you as they do me, you can do
30
31 $ sudo aptitude -t testing install git-core
32
33 And those notices should go away.
2e3215af » jeff
2010-09-06 Added prerequisites section again - got overwritten when moving READM…
34
a132ae49 » jeff
2010-09-06 Improved documentation
35 ### Installing ###
2e3215af » jeff
2010-09-06 Added prerequisites section again - got overwritten when moving READM…
36 Installation on a Debian stable system. Note that the command line interface for ticgit can be run from Debian stable, but some of the gems required for the web interface may require you to use [apt](http://jaqque.sbih.org/kplug/apt-pinning.html) [pinning](http://jeffwelling.github.com//2010/09/05/Apt-Pinning.html) to run without errors. See below.
a132ae49 » jeff
2010-09-06 Improved documentation
37
b9b68423 » jeffWelling
2010-09-06 Improved the Install section
38 If you know what rake is and know you already have it installed, you can use the command `rake setup` to automatically install all dependencies.
a132ae49 » jeff
2010-09-06 Improved documentation
39
b9b68423 » jeffWelling
2010-09-06 Improved the Install section
40 There are two parts to ticgit, the command line interface `ti` and the optional web based interface `ticgitweb`. To install the dependencies for either one, do
41
42 *ti*
d85010c7 » jeff
2010-09-06 Added About section from schacons wiki to README
43 sudo aptitude install rubygems
b9b68423 » jeffWelling
2010-09-06 Improved the Install section
44 sudo gem install git
45
46 *ticgitweb*
47
d85010c7 » jeff
2010-09-06 Added About section from schacons wiki to README
48 sudo aptitude install rubygems
b9b68423 » jeffWelling
2010-09-06 Improved the Install section
49 sudo gem install ticgit sinatra haml sass
a132ae49 » jeff
2010-09-06 Improved documentation
50
51
52 ### Usage ###
53
54 To get a list of all commands with short description:
55
56 > ti --help
57 Usage: ti COMMAND [FLAGS] [ARGS]
58
59 Options for help command:
60
61 The available ticgit commands are:
62 recent List recent activities
63 checkout Checkout a ticket
64 tag Modify tags of a ticket
65 comment Comment on a ticket
66 milestone List and modify milestones
67 assign Assings a ticket to someone
68 points Assign points to a ticket
69 state Change state of a ticket
70 show Show a ticket
71 new Create a new ticket
72 attach Attach file to ticket
73 list List tickets
74
75 Common options:
76 -v, --version Show the version number
77 -h, --help Display this help
78 "help" is not a command
79
80
81 To get help about a specific command:
82
83 > ti <command> --help
84 ## for example
85 > ti assign --help
86 Usage: ti assign [options] [ticket_id]
87
88 Options for assign command:
89 -c, --checkout TICKET Checkout this ticket
90 -u, --user USER Assign the ticket to this user
91
92 Common options:
93 -v, --version Show the version number
94 -h, --help Display this help
95
96
0aba4ff7 » jeffWelling
2010-09-06 Fixed bit at the bottom about the available commands
97 The available commands are:
98
99 ti list - show all tickets
100 ti show - show details of a specific ticket
101 ti new - create a new ticket
102 ti checkout - checkout a ticket
103 ti state - change a ticket state (open, resolved, invalid, hold)
104 ti comment - add a comment to a ticket
105 ti tag - add or delete a tag from a ticket
106 ti assign - change to whom a ticket is assigned
a132ae49 » jeff
2010-09-06 Improved documentation
107
108
af0b4baf » jeff
2010-09-06 Updated Authors header, and added Usage Examples section
109 ### Usage Examples ###
110
111 The first time you use any command in ticgit, it will create a new branch in your repo called ‘ticgit’ and setup a caching area in ~/.ticgit.
112
113 If you run it without arguments, it will tell you what is available to run
114
115 $ ti
116 Please specify at least one action to execute.
117
118 Usage: ti COMMAND [FLAGS] [ARGS]
119
120 The available ticgit commands are:
121 recent List recent activities
122 checkout Checkout a ticket
123 tag Modify tags of a ticket
124 comment Comment on a ticket
125 milestone List and modify milestones
126 assign Assings a ticket to someone
127 points Assign points to a ticket
128 state Change state of a ticket
129 show Show a ticket
130 new Create a new ticket
131 attach Attach file to ticket
132 list List tickets
133
134 Common options:
135 -v, --version Show the version number
136 -h, --help Display this help
137
138 The first time you run `ti list`, it will show an empty list.
139
140 $ ti list
141 I, [2010-09-06T15:47:52.075485 #4820] INFO -- : creating ticgit repo branch
142
143 TicId Title State Date Assgn Tags
144 -----------------------------------------------------------------------------------------
145
1e555e52 » jeffWelling
2010-09-06 Broke out mention of how not using -m brings up an editor into a full…
146 To add a new ticket you can use `ti new -t 'Title of ticket'` and give it a title in one command line.
af0b4baf » jeff
2010-09-06 Updated Authors header, and added Usage Examples section
147
148 $ ti new -t 'my new ticket'
149 $ ti list
150
151 TicId Title State Date Assgn Tags
152 -----------------------------------------------------------------------------------------
153 d7f2d8 my new ticket open 09/06
154
1e555e52 » jeffWelling
2010-09-06 Broke out mention of how not using -m brings up an editor into a full…
155 For the ‘comment’ and ‘new’ commands, if you don’t specify a ‘-m’ for the message, it puts you into $EDITOR to write it. The ‘new’ action is especially useful with this, because you can also tag it and give it an initial comment when you create it this way:
156
157
158 # ---
159 # tags:
160 # # first line will be the title of the tic, the rest will be the first comment
161 # # if you would like to add initial tags, put them on the 'tags:' line, comma delim
162 #
af0b4baf » jeff
2010-09-06 Updated Authors header, and added Usage Examples section
163
78206b7b » jeffWelling
2010-09-06 Added note about best practice being checkout the ticket your working…
164 To edit a ticket, such as assigning a tag to the new ticket we created, we first checkout the ticket and then use `ti tag`.
165 Always checkout the ticket you intend to edit. Some commands allow you to include a tic_id argument but that can get confusing to keep track of and most of the time several edits will be done to the same ticket anyway, so it is suggested you use `ti checkout` for convenience if nothing else.
573fba33 » jeffWelling
2010-09-06 Added example usage or assigning a tag
166
167 #ti checkout can checkout tickets based on the TicId or based on it's place in the list
168 $ ti checkout 1
169 #checks out the first ticket, or to do the same thing by using the TicId
170 $ ti checkout d7f2d8
171 #then assign the tag
172 $ ti tag 'bug'
173 #and view the result..
174 $ ti list
175
176 TicId Title State Date Assgn Tags
177 -------------------------------------------------------------------------------------------------------
178 * d7f2d8 my new ticket open 09/06 bug
179
180
520c7827 » jeffWelling
2010-09-06 Filled in more usage examples, added mention of 'ti sync' command tha…
181 To assign the ticket to someone, use the `ti assign` command. I assign the ticket to myself below.
182
183 $ ti assign -u 'jeff.welling@gmail.com'
184 $ ti list
185
186 TicId Title State Date Assgn Tags
187 ----------------------------------------------------------------------------------------------------------
188 * d7f2d8 my new ticket open 09/06 jeff.we… bug
189
190
191 To change the state of a ticket, such as to change it from 'open' to 'hold' or 'resolved', use `ti state`. There are 4 valid states: hold, invalid, open, and resolved.
192
193 $ ti state hold
194 $ ti list
195
196 TicId Title State Date Assgn Tags
197 ----------------------------------------------------------------------------------------------------------
198
199 *Dramatic Gasp!*
200 Where did all of our tickets go? Don't worry, this isn't a bug and your tickets aren't gone.
201
202 $ ti list --states open,hold
203
204 TicId Title State Date Assgn Tags
205 ----------------------------------------------------------------------------------------------------------
206 * d7f2d8 my new ticket hold 09/06 jeff.we… bug
207
208 By default `ti list` doesn't show tickets with a state of 'hold', so we have to specify that we want to see those tickets with an argument. Now you can see, out `ti state hold` command changed the state of that ticket to on hold. This can also be done without checking out the ticket by using `ti state 1 hold`.
209
210 Where ticgit expects a ticket id, it will take either the number of the ticket on the last ‘list’ you did, or it will take the partial sha each ticket is assigned when it is created – that number never changes for the life of the ticket, even across repositories, so you can email that number to someone else working on the project so they can identify it. If nothing is specified, it will use the currently checked out ticket.
211
212 $ ti comment -m "I'm a new comment"
213 $ ti show
214 Title: my new ticket
215 TicId: d7f2d8f6d6ec3da1a1800a33fb090d590a533bac
216
217 Assigned: jeff.welling@gmail.com
218 Opened: Mon Sep 06 15:52:03 -0700 2010 (0 days)
219 State: OPEN
220 Points: no estimate
221 Tags: bug
222
223 Comments (1):
224 * Added 09/06 18:34 by jeff.welling@gmail.com
225 I'm a new comment
226
227 `ti show` also has a '-f' argument to be able to see comments that are longer than 3 lines, which would normally be truncated.
228
229 The `ti list` command can also be sorted and filtered.
230
231 $ ti list --help
232 Usage: ti list [options]
233
234 Options for list command:
235 -l, --list Show the saved queries
236 -S, --saveas SAVENAME Save this list as a saved name
237 -a, --assigned ASSIGNED List only tickets assigned to someone
238 -s, --states STATE[,STATE] List only tickets in a specific state(s)
239 Prefix the state with '-' to negate
240 -t, --tags TAG[,TAG] List only tickets with specific tag(s)
241 Prefix the tag with '-' to negate
242 -o, --order ORDER Field to order by - one of : assigned,state,date,title
243
244 Common options:
245 -v, --version Show the version number
246 -h, --help Display this help
247
248 So if you wanted to see a list of all your tickets that have the ‘feature’ tag, assigned to ‘jeff.welling@gmail.com’ and are ‘open’, ordered by date opened descending, and save that view as ‘not_mine’, you can run this:
249
250 $ ti list -t feature -s open -a jeff.welling@gmail.com -o date.desc -S not_mine
251
252 Then if you want to later list tickets with the same options as you used above, use
253
254 $ ti list not_mine
255
256 ## Collaboration ##
257
258 If you have cloned a repository and would like to get the ticgit branch for that repo (presuming they have one), do this.
259
260 $git branch ticgit origin/ticgit
261
262 This will create a ticgit branch in your local repo based on the ticgit branch in origin. Now you can run `ti list` and it will show you the ticgit tickets for that repository.
263
264
265 ### Sharing your tickets with others ###
266
37333029 » jeffWelling
2010-09-06 Added a Development section to the README
267 Sharing your ticgit tickets with other people is as easy as asking them either creating their ticgit branch based on yours if they haven't already started their own ticgit branch, or pulling your ticgit branch into theirs.
520c7827 » jeffWelling
2010-09-06 Filled in more usage examples, added mention of 'ti sync' command tha…
268
269 If you host your repositories on [Github](http://www.github.com) as I do then this process is simplified some because you don't have to worry about hosting your repository somewhere where other people can access it to pull your ticgit branch.
270
271 For example, when I want my friend wnight to have the changes I made to my tickets in my ticgit repository, I do a
272
273 $ git push origin
274
275 to update all my remote branches with my current ones, and then I ask him to do a
276
277 $ git checkout ticgit
278 $ git pull git@github.com:jeffWelling/ticgit.git ticgit
279 $ git checkout master
280
281 to pull my changes into his ticgit branch and then switch back to his master branch. Now when he does `ti list` it will show the changes I made to the tickets on my system.
282
283
284 ### Incorporating other peoples changes into your ticgit branch ###
285
286 The process is much the same as above, except the rolls are reversed. Once you know they have published their changes and you have a URL to do a git pull from, you simply do
287
288 $ git checkout ticgit
289 $ git pull SOURCE_URL ticgit
290 $ git checkout master
291
292 Replacing SOURCE_URL with the URL you were told to pull from, now you can see the changes they made, in your ticgit branch. You can easily publish these changes with a `git push origin` so anyone following your work can also see these changes.
293
294
295 ### Next generation collaboration ###
296
297 Changes made by [Bruno Santos](http://github.com/pheres) to add a [`ti sync`](http://github.com/jeffWelling/ticgit/commit/7388386fab4fb12c36e6eeb7d19eaa4e4b16b853) command are currently in the process of being integrated into the master branch. Once this is done, syncing with other people should be as easy as `ti sync REMOTE_REPO` where REMOTE_REPO is a repo URL.
573fba33 » jeffWelling
2010-09-06 Added example usage or assigning a tag
298
af0b4baf » jeff
2010-09-06 Updated Authors header, and added Usage Examples section
299
dba3fb19 » jeffWelling
2010-09-06 Added a section about TicGitWeb - shamelessly copied from schacon's wiki
300 ### Ticgitweb ###
301
302 To run the Sinatra enabled web UI for your TicGit repo, simply cd to your repository and run 'ticgitweb', or 'ticgitweb -p 3456' to change the port to something other than '4567', which is the Sinatra default.
303
304 Here is what the Ticket listing looks like:
305
306 <a href="http://www.flickr.com/photos/chacon/2359042481/" title="TicGitWeb Ticket List by schacon, on Flickr"><img src="http://farm4.static.flickr.com/3289/2359042481_065867a92e.jpg" width="500" height="258" alt="TicGitWeb Ticket List" /></a>
307
308 And here is an individual ticket:
309
310 <a href="http://www.flickr.com/photos/chacon/2359042513/" title="TicGitWeb Ticket by schacon, on Flickr"><img src="http://farm4.static.flickr.com/3240/2359042513_6d4bd069d0.jpg" width="500" height="275" alt="TicGitWeb Ticket" /></a>
311
312
37333029 » jeffWelling
2010-09-06 Added a Development section to the README
313 ## Development ##
314
05e38694 » jeffWelling
2010-09-06 Updated references to bacon links
315 The original author had used rspec to write specs for ticgit, but one of the maintainers since then switched it over to bacon[[1](http://www.ruby-forum.com/topic/137928)][[2](http://www.ruby-forum.com/topic/172139)][[3](http://testanything.org/wiki/index.php/Testing_with_Ruby)] and I haven't been too inclined to switch it back.
37333029 » jeffWelling
2010-09-06 Added a Development section to the README
316
317 ### Prerequisites ###
318
319 To install the prerequisites on Debian stable for testing ticgit, you will need [apt](http://jaqque.sbih.org/kplug/apt-pinning.html) [pinning](http://jeffwelling.github.com//2010/09/05/Apt-Pinning.html).
320
d3e97b2d » jeffWelling
2010-09-06 Filled in prerequisites for testing on Debian stable
321 $ sudo aptitude -t testing install rubygems rake
322 $ sudo gem install yard bacon
323
324 I pull rubygems from testing to avoid a problem with gherkin creating a syntactically incorrect gemspec which makes a lot of noise whenever `gem` is called. I ran into a problem when gem was installing yard, it had a problem with the documentation but thankfully the error wasn't fatal and was only about not being able to compile the documentation which I don't use, so it continued without trouble.
37333029 » jeffWelling
2010-09-06 Added a Development section to the README
325
326
327 ### How To Test ###
328
329 To test your version of ticgit, go to your ticgit directory and run
330
331 rake bacon
332
333 ### How to generate a gem from your development copy of ticgit ###
334
335 To create a gem from your development copy of ticgit, go to your ticgit directory and do
336
337 rake gem
338
339 This will create a pkg/ directory, which will contain a newly created ticgit gem for you to install.
8dafd145 » jeffWelling
2010-09-07 Added Alternatives to README
340
341 ### Alternatives ###
342
343 ditz
344 bugs everywhere
345 git-issues
346
37333029 » jeffWelling
2010-09-06 Added a Development section to the README
347
af0b4baf » jeff
2010-09-06 Updated Authors header, and added Usage Examples section
348 ## Authors ##
349
a132ae49 » jeff
2010-09-06 Improved documentation
350 Original Author:
351 Scott Chacon (schacon@gmail.com)
352
353 Current Active Maintainer:
354 Jeff Welling (jeff.welling@gmail.com)
61fc637a » jeff
2010-09-06 Readded note at the bottom about the AUTHORS file
355
356 For a detailed list of all contributors and the number of submitted patches for each, see the AUTHORS file.
Something went wrong with that request. Please try again.