README.md
1## Welcome to Pit ##
2Pit is a command-line project manager that integrates with Git. I wrote it
3because I needed a command-line tool for tracking tasks. Besides, after
4years of Ruby and JavaScript programming I missed plain C.
5
6### Installing Pit ###
7Pit is implemented in C and compiles down to a single executable file. It
8has been tested to compile on Mac OS Leopard, Ubuntu, and RedHat Linux.
9
10 $ git clone git://github.com/michaeldv/pit.git
11 $ cd pit
12 $ make
13 $ make test # <-- Optional, requires Ruby
14 $ sudo make install
15 $ which pit
16 /usr/local/bin/pit
17 $ pit version
18 0.1.0
19
20### Basic Concepts ###
21Basic Pit entities are projects, tasks, and notes. One project can have
22multiple tasks, and a task can have multiple notes. Each entity has a number
23of attributes. For example, project has name and status, task has name,
24status, priority, date, and time, and within note there is message body.
25All attributes except name and message body are optional and can be omitted.
26
27The attributes have no semantic meaning, and do not have a pre-defined set
28of values. For example, depending on the particular need, the time attribute
29could be used as projected time in weeks, hours spent on the task, or days
30left to finish the task.
31
32Pit tries to maintain a notion of "current" project, task, or note. When you
33create new project, it automatically becomes current. If you do not specify
34project number when creating a task, the new task will be associated with
35the current project.
36
37### Pit Commands ###
38Pit commands are as follows:
39
40 init Create an empty Pit database or re-initialize an existing one
41 project Create, search, and manage Pit projects
42 task Create, search, and manage Pit tasks
43 note Create, search, and manage Pit notes
44 log Show chronological Pit activity log
45 info Show summary information about your Pit database
46 help Show help information about Pit
47 version Show Pit version number
48
49All commands may be shortened, as long as they remain unambiguous. For more
50information on a specific command run:
51
52 $ pit help <command>
53
54### Git Integration ###
55Pit distribution comes with tools/commit-msg file. Copy this file to
56.git/hooks/commit-msg and make it executable:
57
58 $ cp ~/pit/tools/commit-msg .git/hooks
59 $ chmod +x .git/hooks/commit-msg
60
61Create git branch using task number as a branch name. Now on every commit to
62the branch the hook will prompt you to update task status. The hook appends
63Pit task number to the commit message, updates Pit task status, and creates
64task note with the commit massage. For example:
65
66 $ git checkout -b 2
67 Switched to a new branch '2'
68
69 $ touch README
70 $ git add .
71 $ git commit -am "Added README file"
72 What is the status of task 2?
73 (I)n progress
74 (P)ostponed
75 (O)pen
76 (D)one
77 Enter the status for task 2 [D]:
78 i
79 updated task 2: My second task (status: in progress)
80 created note 2: Added README file [task 2, status:in progress] (task 2)
81 [2 0d930fb] Added README file [task 2, status:in progress]
82 0 files changed, 0 insertions(+), 0 deletions(-)
83 create mode 100644 README
84
85### Tips ###
86A few tips to get you going:
87
88 # Changing default Pit file name: define PITFILE environment variable.
89 $ pit init
90 Created empty /Users/mike/.pit
91
92 $ export PITFILE="~/pit.db"
93 $ pit init
94 Created empty /Users/mike/pit.db
95
96 # Displaying last 10 lines of pit log in reverse order:
97 $ pit log|tail -10|sed -n '1!G;h;$p'
98
99 # Displaying tasks within certain date range:
100 $ pit task -q -d "Jan 1" -D "Sep 1"
101
102 # Displaying tasks with certain time range:
103 $ pit task -q -t 0:30 -T 8:00
104
105### Sample Pit session ###
106
107 $ pit init
108 Created empty /Users/mike/.pit
109
110 $ pit project -c "My very first project"
111 created project 1: My very first project (status: active)
112
113 $ pit project -c "My second project" -s backlog
114 created project 2: My second project (status: backlog)
115
116 $ pit project
117 1: (mike) |active | My very first project (0 tasks)
118 * 2: (mike) |backlog| My second project (0 tasks)
119
120 $ pit project -e 1 -s current
121 updated project 1: My very first project (status: current)
122
123 $ pit project
124 * 1: (mike) |current| My very first project (0 tasks)
125 2: (mike) |backlog| My second project (0 tasks)
126
127 $ pit task -c "My very first task"
128 created task 1: My very first task (status: open, priority: normal, project: 1)
129
130 $ pit task -c "My second task" -s new -p high
131 created task 2: My second task (status: new, priority: high, project: 1)
132
133 $ pit task -c "My third task" -p low -t 4:00
134 created task 3: My third task (status: open, priority: low, time: 4:00, project: 1)
135
136 $ pit p
137 * 1: (mike) |current| My very first project (3 tasks)
138 2: (mike) |backlog| My second project (0 tasks)
139
140 $ pit t
141 1: (mike) |open| |normal| My very first task (0 notes)
142 2: (mike) |new | |high | My second task (0 notes)
143 * 3: (mike) |open| |low | 4:00 My third task (0 notes)
144
145 $ pit task -e -s new
146 updated task 3: My third task (status: new)
147
148 $ pit task -e 1 -d 10/10
149 updated task 1: My very first task (date: Oct 10, 2010)
150 * 1: (mike) |open| |normal| Oct 10, 2010 My very first task (0 notes)
151 2: (mike) |new | |high | My second task (0 notes)
152 3: (mike) |new | |low | 4:00 My third task (0 notes)
153
154 $ pit note -c "Sample note for task #1"
155 created note 1: Sample note for task #1 (task 1)
156
157 $ pit task -q -s new
158 2: (mike) |new| |high| My second task (0 notes)
159 3: (mike) |new| |low | 4:00 My third task (0 notes)
160
161 $ pit task -m -p 2
162 moved task 1: from project 1 to project 2
163
164 $ pit project 2
165 1: (mike) |current| My very first project (2 tasks)
166 * 2: (mike) |backlog| My second project (1 task)
167
168 $ pit project -d
169 deleted note 1: Sample note for task #1 (task 1)
170 deleted task 1: My very first task with 1 note (project: 2)
171 deleted project 2: My second project with 1 task
172
173 $ pit log
174 Aug 22, 2010 14:30 (mike): Initialized pit
175 Aug 22, 2010 14:31 (mike): created project 1: My very first project (status: active)
176 Aug 22, 2010 14:31 (mike): created project 2: My second project (status: backlog)
177 Aug 22, 2010 14:31 (mike): updated project 1: My very first project (status: current)
178 Aug 22, 2010 14:31 (mike): created task 1: My very first task (status: open, priority: normal, project: 1)
179 Aug 22, 2010 14:31 (mike): created task 2: My second task (status: new, priority: high, project: 1)
180 Aug 22, 2010 14:31 (mike): created task 3: My third task (status: open, priority: low, time: 4:00, project: 1)
181 Aug 22, 2010 14:32 (mike): updated task 3: My third task (status: new)
182 Aug 22, 2010 14:32 (mike): updated task 1: My very first task (date: Oct 10, 2010)
183 Aug 22, 2010 14:32 (mike): created note 1: Sample note for task #1 (task 1)
184 Aug 22, 2010 14:33 (mike): moved task 1: from project 1 to project 2
185 Aug 22, 2010 14:33 (mike): deleted note 1: Sample note for task #1 (task 1)
186 Aug 22, 2010 14:33 (mike): deleted task 1: My very first task with 1 note (project: 2)
187 Aug 22, 2010 14:33 (mike): deleted project 2: My second project with 1 task
188
189### License ###
190Copyright (c) 2010 Michael Dvorkin
191
192mike[at]dvorkin.net aka mike[at]fatfreecrm.com
193
194THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS
195OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
196WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
197ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
198LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
199OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
200OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
201BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
202WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
203OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
204EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
205
206Released under the Simplified BSD license. See LICENSE file for details.
207