TicGit-ng 1.0.0

data/LICENSE_MIT

@@ -0,0 +1,29 @@
+The MIT License
+
+Portions, Copyright (c) 2008 Scott Chacon
+Other portions, Copyright (c) 2011 Jeff Welling
+Other portions, Copyright of their respective authors.
+
+This MIT license and notice pertains ONLY to code NOT authored by Jeff Welling. 
+Contributions by Jeff Welling are licensed under GPLv3, a copy of 
+which is included with the source code.  For information on determining 
+which code was authored by whom, see 
+http://www.kernel.org/pub/software/scm/git/docs/git-blame.html
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.mkd

@@ -0,0 +1,425 @@
+## 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](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.
+
+**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](http://jaqque.sbih.org/kplug/apt-pinning.html) [pinning](http://jeffwelling.github.com//2010/09/05/Apt-Pinning.html), 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](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. 
+
+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, but the suggested method is to manually install as outlined below.
+
+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
+
+*ti*
+    sudo aptitude install rubygems
+    sudo gem install git
+
+*ticgitweb*
+
+    sudo aptitude install rubygems
+    sudo gem install ticgit sinatra haml sass
+
+
+
+
+### 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
+    $ ti tag 'bug'
+    #and view the result..
+    $ ti list
+
+       TicId  Title                                           State Date  Assgn    Tags                
+    -------------------------------------------------------------------------------------------------------
+    *  d7f2d8 my new ticket                                   open  09/06          bug               
+
+
+To assign the ticket to someone, use the `ti assign` command.  I assign the ticket to myself below.
+
+    $ ti assign -u 'jeff.welling@gmail.com'
+    $ ti list
+
+       TicId  Title                                              State Date  Assgn    Tags                
+    ----------------------------------------------------------------------------------------------------------
+    *  d7f2d8 my new ticket                                      open  09/06 jeff.we… bug  
+
+
+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.
+
+    $ ti state hold
+    $ ti list
+
+       TicId  Title                                              State Date  Assgn    Tags                
+    ----------------------------------------------------------------------------------------------------------
+
+*Dramatic Gasp!*
+Where did all of our tickets go?  Don't worry, this isn't a bug and your tickets aren't gone.  
+
+    $ ti list --states open,hold
+
+       TicId  Title                                              State Date  Assgn    Tags                
+    ----------------------------------------------------------------------------------------------------------
+    *  d7f2d8 my new ticket                                      hold  09/06 jeff.we… bug                 
+
+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`.
+
+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.
+
+    $ ti comment -m "I'm a new comment"
+    $ ti show
+    Title: my new ticket
+    TicId: d7f2d8f6d6ec3da1a1800a33fb090d590a533bac
+
+    Assigned: jeff.welling@gmail.com
+    Opened: Mon Sep 06 15:52:03 -0700 2010 (0 days)
+    State: OPEN
+    Points: no estimate
+    Tags: bug
+
+    Comments (1):
+      * Added 09/06 18:34 by jeff.welling@gmail.com
+      I'm a new comment
+
+`ti show` also has a '-f' argument to be able to see comments that are longer than 3 lines, which would normally be truncated.
+
+The `ti list` command can also be sorted and filtered.
+
+    $ ti list --help
+    Usage: ti list [options]
+     
+    Options for list command:
+        -l, --list                       Show the saved queries
+        -S, --saveas SAVENAME            Save this list as a saved name
+        -a, --assigned ASSIGNED          List only tickets assigned to someone
+        -s, --states STATE[,STATE]       List only tickets in a specific state(s)
+                                         Prefix the state with '-' to negate
+        -t, --tags TAG[,TAG]             List only tickets with specific tag(s)
+                                         Prefix the tag with '-' to negate
+        -o, --order ORDER                Field to order by - one of : assigned,state,date,title
+     
+    Common options:
+        -v, --version                    Show the version number
+        -h, --help                       Display this help
+
+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:
+
+    $ ti list -t feature -s open -a jeff.welling@gmail.com -o date.desc -S not_mine
+
+Then if you want to later list tickets with the same options as you used above, use
+
+    $ ti list not_mine
+
+## Collaboration ##
+
+If you have cloned a repository and would like to get the ticgit-ng branch for that repo (presuming they have one), do this.
+
+    $git branch ticgit-ng origin/ticgit-ng
+
+This will create a ticgit-ng branch in your local repo based on the ticgit-ng branch in origin.  Now you can run `ti list` and it will show you the ticgit-ng tickets for that repository.
+
+### Getting the TicGit-ng ticgit-ng branch ##
+
+To download your own copy of the TicGit-ng ticgit branch after cloning the repo, so that you can add or alter a bug yourself, follow these instructions.
+
+This will checkout a ticgit-ng branch and set it to track the ticgit-ng branch upstream in origin, and then checks out the master branch.  You must checkout the master branch because TicGit-ng gets confused if you are already in the ticgit-ng branch when running TicGit-ng.
+
+    $ git checkout origin/ticgit-ng
+    $ git checkout -b ticgit-ng
+    $ git checkout master
+
+This will show you all of the bugs in TicGit-ng's ticgit-ng branch.
+
+    $ ti list
+
+To submit your changes back to the upstream maintainer, push the bugs in your ticgit-ng branch to your public repo on Github
+    
+    $ git push origin ticgit-ng
+
+Then contact the upstream maintainer by sending a Pull Request or Email and ask them to review and accept your bug changes.
+
+### Sharing your tickets with others ###
+
+Sharing your ticgit tickets with other people is as easy as asking them either creating their ticgit-ng branch based on yours if they haven't already started their own ticgit-ng branch, or pulling your ticgit-ng branch into theirs.
+
+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-ng branch.
+
+For example, when I want my friend wnight to have the changes I made to my tickets in my ticgit-ng repository, I do a
+
+    $ git push origin
+
+to update all my remote branches with my current ones, and then I ask him to do a
+
+    $ git checkout ticgit-ng
+    $ git pull git@github.com:jeffWelling/ticgit.git ticgit-ng
+    $ git checkout master
+
+to pull my changes into his ticgit-ng 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.
+
+
+### Incorporating other peoples changes into your ticgit-ng branch ###
+
+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
+
+    $ git checkout ticgit-ng
+    $ git pull SOURCE_URL ticgit-ng
+    $ git checkout master
+
+Replacing SOURCE_URL with the URL you were told to pull from, now you can see the changes they made, in your ticgit-ng branch.  You can easily publish these changes with a `git push origin` so anyone following your work can also see these changes.
+
+
+### Next generation collaboration ###
+
+Changes made by [Bruno Santos](http://github.com/pheres) to add a [`ti sync`](http://github.com/jeffWelling/ticgit/commit/7388386fab4fb12c36e6eeb7d19eaa4e4b16b853) command were integrated on February 15th 2011.  You can now use the `ti sync [options]` command to sync your tickets with anyone else you've added with `git remote add`.  To use `ti sync`, all you need to do is first make sure you've already added the remote source with `git remote add`, and then do
+
+    $ ti sync --repo REMOTE_SOURCE
+
+if you want to pull their tickets into your ticgit-ng branch *and* push your tickets to their ticgit-ng branch, or
+
+    $ ti sync --repo REMOTE_SOURCE --no-push
+
+if you want to pull their tickets into your ticgit-ng branch without pushing your tickets to their branch.
+
+More information on using ti sync can be gleemed from reviewing the [merge specs](https://github.com/jeffWelling/ticgit/blob/deving/spec/merging_spec.rb)
+
+### Ticgitweb ###
+
+To run the Sinatra enabled web UI for your TicGit-ng 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.
+
+Here is what the Ticket listing looks like:
+
+<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>
+
+And here is an individual ticket:
+
+<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>
+
+
+## Development ##
+
+The original author had used rspec to write specs for ticgit-ng, 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.
+
+### Prerequisites ###
+
+To install the prerequisites on Debian stable for testing ticgit-ng, you will need [apt](http://jaqque.sbih.org/kplug/apt-pinning.html) [pinning](http://jeffwelling.github.com//2010/09/05/Apt-Pinning.html).
+
+    $ sudo aptitude -t testing install rubygems rake
+    $ sudo gem install yard bacon
+
+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.
+
+
+### How To Test ###
+
+To test your version of ticgit-ng, go to your ticgit-ng directory and run
+
+    rake bacon
+
+### How to generate a gem from your development copy of ticgit-ng ###
+
+To create a gem from your development copy of ticgit-ng, go to your ticgit-ng directory and do
+
+    rake gem
+
+This will create a pkg/ directory, which will contain a newly created ticgit-ng gem for you to install.
+
+More information on developing TicGit-ng and collaborating with other TicGit-ng developers at [here](https://github.com/jeffWelling/ticgit/wiki/Development)
+
+More information on developing TicGit-ng and collaborating with other TicGit-ng developers at [here](https://github.com/jeffWelling/ticgit/wiki/Development)
+
+### Alternatives ###
+
+ditz 
+bugs everywhere
+git-issues
+
+
+## Authors ##
+
+Original Author:
+Scott Chacon                (schacon@gmail.com)
+
+Current Active Maintainer:
+Jeff Welling                (jeff.welling@gmail.com)
+
+For a detailed list of contributors, use `git log`.

data/bin/ti

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'fileutils'
+
+# Add the library from the source tree to the front of the load path.
+# This allows ti to run without first installing a ticgit gem, which is
+# important when testing multiple branches of development.
+if File.exist? File.join('lib', 'ticgit-ng.rb')
+    $LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+end
+require 'ticgit-ng'
+
+TicGitNG::CLI.execute