Ticgit
Git based distributed ticketing system, including a command line client and web viewer
Install / Use
/learn @schacon/TicgitREADME
Note: the original TicGit author has pulled all the TicGit-ng changes into his repository, creating a potentially confusing situation. The schacon TicGit repo, this one, is not consistently maintained. For up to date TicGit-ng info and code, check the canonical TicGit-ng repository at
https://github.com/jeffWelling/ticgit
TicGit-ng
This project provides a ticketing system built on Git that is kept in a separate branch in your projects Git repository. Originally called TicGit, it is now known as TicGit-ng to continue development and avoid namespace clashes.
About
TicGit-ng 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-ng’) 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.
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.
There are two interfaces available, the command line ti command and the ticgitweb web interface, though ticgitweb has many more prerequisites than ti.
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-ng 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).
TicGit-ng is currently using itself to store its feature requests and bug reports.
Prerequisites
There are two sets of prerequisites, those for people who intend to just run ti, and another set for those who wish to run ticgitweb as well. ticgitweb has additional dependancies that aren't required for ti's use.
ti
Required Packages: git, ruby, rubygems
Required Ruby Gems: git
To install these packages on a Debian system, or a Debian based system like Ubuntu, do
sudo aptitude install git ruby rubygems
sudo gem install git
ticgitweb
Required Packages: git, ruby, rubygems
Required Ruby Gems: git, sinatra, haml, sass
To install these packages on a Debian system, or a Debian based system like Ubuntu, do
sudo aptitude install git ruby rubygems
sudo gem install git sinatra haml sass
A Note about rubygems
While the version of rubygems available from the repositories on Debian 5.0.5 stable will work just fine for using the command line ti program, using ticgitweb requires some extra effort.
Older versions of rubygems, 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 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 pinning before being able to properly install the git and ticgit gems.
A Note about the git gem
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
[WARNING] The git gem requires git 1.6.0.0 or later, but only found 1.5.6.5. You should probably upgrade.
Please specify at least one action to execute.
If these annoy you as they do me and you've set up apt pinning, you can do
$ sudo aptitude -t testing install git-core
And those notices should go away.
Installing
Installation on a Debian stable system. Note that the command line interface for TicGit-ng can be run from Debian stable, but some of the gems required for the web interface may require you to use apt pinning to run without errors. See below
To install TicGit-ng on your system, you can go one of two ways,
$ gem install TicGit-ng
or, you can install it from source by downloading this repository building your own gem (see below).
Usage
To get a list of all commands with short description:
> ti --help
Usage: ti COMMAND [FLAGS] [ARGS]
Options for help command:
The available TicGit-ng commands are:
recent List recent activities
checkout Checkout a ticket
tag Modify tags of a ticket
comment Comment on a ticket
milestone List and modify milestones
assign Assings a ticket to someone
points Assign points to a ticket
state Change state of a ticket
show Show a ticket
new Create a new ticket
attach Attach file to ticket
list List tickets
Common options:
-v, --version Show the version number
-h, --help Display this help
"help" is not a command
To get help about a specific command:
> ti <command> --help
## for example
> ti assign --help
Usage: ti assign [options] [ticket_id]
Options for assign command:
-c, --checkout TICKET Checkout this ticket
-u, --user USER Assign the ticket to this user
Common options:
-v, --version Show the version number
-h, --help Display this help
The available commands are:
ti list - show all tickets
ti show - show details of a specific ticket
ti new - create a new ticket
ti checkout - checkout a ticket
ti state - change a ticket state (open, resolved, invalid, hold)
ti comment - add a comment to a ticket
ti tag - add or delete a tag from a ticket
ti assign - change to whom a ticket is assigned
Usage Examples
The first time you use any command in Ticgit-ng, it will create a new branch in your repo called ‘ticgit-ng’ and setup a caching area in ~/.ticgit-ng.
If you run it without arguments, it will tell you what is available to run
$ ti
Please specify at least one action to execute.
Usage: ti COMMAND [FLAGS] [ARGS]
The available TicGit-ng commands are:
recent List recent activities
checkout Checkout a ticket
tag Modify tags of a ticket
comment Comment on a ticket
milestone List and modify milestones
assign Assings a ticket to someone
points Assign points to a ticket
state Change state of a ticket
show Show a ticket
new Create a new ticket
attach Attach file to ticket
list List tickets
Common options:
-v, --version Show the version number
-h, --help Display this help
The first time you run ti list, it will show an empty list.
$ ti list
I, [2010-09-06T15:47:52.075485 #4820] INFO -- : creating ticgit repo branch
TicId Title State Date Assgn Tags
-----------------------------------------------------------------------------------------
To add a new ticket you can use ti new -t 'Title of ticket' and give it a title in one command line.
$ ti new -t 'my new ticket'
$ ti list
TicId Title State Date Assgn Tags
-----------------------------------------------------------------------------------------
d7f2d8 my new ticket open 09/06
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:
# ---
# tags:
# # first line will be the title of the tic, the rest will be the first comment
# # if you would like to add initial tags, put them on the 'tags:' line, comma delim
#
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.
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.
#ti checkout can checkout tickets based on the TicId or based on it's place in the list
$ ti checkout 1
#checks out the first ticket, or to do the same thing by using the TicId
$ ti checkout d7f2d8
#then assign the tag
