Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 374 lines (263 sloc) 12.497 kB
fcffc4e @samg added README and format stub
authored
1 Timetrap
2 ========
3
adb73ea @samg Update README
authored
4 Timetrap is a simple command line time tracker written in ruby. It provides an
5 easy to use command line interface for tracking what you spend your time on.
89770cc @samg Updated README
authored
6
080a1f7 @samg Restructured README
authored
7 Getting Started
8 ---------------
ce47269 @samg update install instruction to use GemCutter
authored
9
6eccaf7 @samg added gemspec and bin/t
authored
10 To install:
45876a4 @samg markdown'd readme
authored
11
ce47269 @samg update install instruction to use GemCutter
authored
12 $ gem install timetrap
fcffc4e @samg added README and format stub
authored
13
6eccaf7 @samg added gemspec and bin/t
authored
14 This will place a ``t`` executable in your path.
fcffc4e @samg added README and format stub
authored
15
080a1f7 @samg Restructured README
authored
16 ### Basic Usage
fcffc4e @samg added README and format stub
authored
17
080a1f7 @samg Restructured README
authored
18 $ # get help
19 $ t --help
fcffc4e @samg added README and format stub
authored
20
080a1f7 @samg Restructured README
authored
21 Timetrap maintains a list of *timesheets*.
fcffc4e @samg added README and format stub
authored
22
080a1f7 @samg Restructured README
authored
23 $ # create the "coding" timesheet
3399bde @samg Rename switch command to sheet.
authored
24 $ t sheet coding
080a1f7 @samg Restructured README
authored
25 Switching to sheet coding
26
27 All commands can be abbreviated.
28
3399bde @samg Rename switch command to sheet.
authored
29 $ # same as "t sheet coding"
080a1f7 @samg Restructured README
authored
30 $ t s coding
31 Switching to sheet coding
32
33 Each timesheet contains *entries*. Each entry has a start and end time, and a
34 note associated with it. An entry without an end time set is considered to be
eb46080 @samg words
authored
35 running.
080a1f7 @samg Restructured README
authored
36
37 You check in to the current sheet with the `in` command.
38
39 $ # check in with "document timetrap" note
40 $ t in document timetrap
41 Checked into sheet "coding".
42
43 Commands like `display` and `now` will show you the running entry.
fcffc4e @samg added README and format stub
authored
44
4423283 @samg Improved documentation for noobs
authored
45 $ t display
080a1f7 @samg Restructured README
authored
46 Timesheet: coding
47 Day Start End Duration Notes
48 Sun Nov 28, 2010 12:26:10 - 0:00:03 document timetrap
49 0:00:03
50 ---------------------------------------------------------
51 Total 0:00:03
4423283 @samg Improved documentation for noobs
authored
52
080a1f7 @samg Restructured README
authored
53 $ t now
54 *coding: 0:01:02 (document timetrap)
fcffc4e @samg added README and format stub
authored
55
080a1f7 @samg Restructured README
authored
56 If you make a mistake use the `edit` command.
57
58 $ # edit the running entry's note
59 $ t edit writing readme
60 editing entry #42
61
62 You check out with the `out` command.
63
64 $ t out
65 Checked out of sheet "coding"
66
889b8ce @samg More words
authored
67 You can edit entries that aren't running using `edit`'s `--id` or `-i` flag.
91a37c8 @samg Fixed error in readme
authored
68 `t display --ids` (or `t display -v`) will tell you the ids.
889b8ce @samg More words
authored
69
70 $ # note id column in output
71 $ t d -v
72 Timesheet: coding
73 Id Day Start End Duration Notes
74 43 Sun Nov 28, 2010 12:26:10 - 13:41:03 1:14:53 writing readme
75 1:14:53
76 ---------------------------------------------------------
77 Total 1:14:53
78
118defc @samg Readme tweaks
authored
79 $ # -i43 to edit entry 43
889b8ce @samg More words
authored
80 $ t e -i43 --end "2010-11-28 13:45"
81 editing entry #43
82
83 $ t d
84 Timesheet: coding
85 Day Start End Duration Notes
118defc @samg Readme tweaks
authored
86 Sun Nov 28, 2010 12:26:10 - 13:45:00 1:18:50 writing readme
889b8ce @samg More words
authored
87 1:18:50
88 ---------------------------------------------------------
89 Total 1:18:50
90
91
080a1f7 @samg Restructured README
authored
92 ### Natural Language Times
93
94 Commands such as `in`, `out`, `edit`, and `display` have flags that accept
95 times as arguments. Any time you pass Timetrap a time it will try to parse it
96 as a natural language time.
97
98 This is very handy if you start working and forget to start Timetrap. You can
99 check in 5 minutes ago using `in`'s `--at` flag.
100
101 $ t in --at "5 minutes ago"
102
103 Command line flags also have short versions.
104
105 $ # equivilent to the command above
106 $ t i -a "5 minutes ago"
107
108 You can consult the Chronic gem (http://chronic.rubyforge.org/) for a full
109 list of parsable time formats, but all of these should work.
110
111 $ t out --at "in 30 minutes"
112 $ t edit --start "last monday at 10:30am"
113 $ t edit --end "tomorrow at noon"
114 $ t display --start "10am" --end "2pm"
115 $ t i -a "2010-11-29 12:30:00"
116
117 ### Output Formats
118
06df6f4 @samg Update documentation for next release
authored
119 #### Built-in Formatters
120
a0b505e @samg Basic documentation of factor formatter
authored
121 Timetrap has built-in support for 6 output formats.
06df6f4 @samg Update documentation for next release
authored
122
b71a9a3 Update README
Sam Goldstein authored
123 These are **text**, **csv**, **ical**, **json**, and **ids**
06df6f4 @samg Update documentation for next release
authored
124
f3faead @samg Less wordy readme
authored
125 The default is a plain **text** format. (You can change the default format using
06df6f4 @samg Update documentation for next release
authored
126 `t configure`).
fcffc4e @samg added README and format stub
authored
127
a66d614 @samg md formatting
authored
128 $ t display
080a1f7 @samg Restructured README
authored
129 Timesheet: coding
54e4e33 @samg updated README
authored
130 Day Start End Duration Notes
131 Mon Apr 13, 2009 15:46:51 - 17:03:50 1:16:59 improved display functionality
132 17:25:59 - 17:26:02 0:00:03
133 18:38:07 - 18:38:52 0:00:45 working on list
134 22:37:38 - 23:38:43 1:01:05 work on kill
135 2:18:52
136 Tue Apr 14, 2009 00:41:16 - 01:40:19 0:59:03 gem packaging
080a1f7 @samg Restructured README
authored
137 10:20:00 - 10:48:10 0:28:10 working on readme
54e4e33 @samg updated README
authored
138 1:27:13
139 ---------------------------------------------------------
140 Total 3:46:05
fcffc4e @samg added README and format stub
authored
141
f3faead @samg Less wordy readme
authored
142 The **CSV** formatters is easy to import into a spreadsheet.
080a1f7 @samg Restructured README
authored
143
144 $ t display --format csv
145 start,end,note,sheet
146 "2010-08-21 11:19:05","2010-08-21 12:12:04","migrated site","coding"
147 "2010-08-21 12:44:09","2010-08-21 12:48:46","DNS emails and install email packages","coding"
148 "2010-08-21 12:49:57","2010-08-21 13:10:12","A records","coding"
149 "2010-08-21 15:09:37","2010-08-21 16:32:26","setup for wiki","coding"
150 "2010-08-25 20:42:55","2010-08-25 21:41:49","rewrote index","coding"
151 "2010-08-29 15:44:39","2010-08-29 16:21:53","recaptcha","coding"
152 "2010-08-29 21:15:58","2010-08-29 21:30:31","backups","coding"
153 "2010-08-29 21:40:56","2010-08-29 22:32:26","backups","coding"
154
f3faead @samg Less wordy readme
authored
155 **iCal** format lets you get your time into your favorite calendar program
06df6f4 @samg Update documentation for next release
authored
156 (remember commands can be abbreviated).
080a1f7 @samg Restructured README
authored
157
158 $ t d -f ical > MyTimeSheet.ics
fcffc4e @samg added README and format stub
authored
159
f3faead @samg Less wordy readme
authored
160 The **ids** formatter is provided to facilitate scripting within timetrap. It only
161 outputs numeric id for the entries. This is handy if you want to move all entries
06df6f4 @samg Update documentation for next release
authored
162 from one sheet to another sheet. You could do something like this:
163
164 $ for id in `t display sheet1 -f ids`; do t edit --id $id --move sheet2; done
165 editing entry #36
166 editing entry #37
167 editing entry #44
168 editing entry #46
169
a0b505e @samg Basic documentation of factor formatter
authored
170 A *json* formatter is provided because hackers love json.
06df6f4 @samg Update documentation for next release
authored
171
172 $ t d -fjson
173
174 #### Custom Formatters
175
f3faead @samg Less wordy readme
authored
176 Timetrap tries to make it easy to define custom output formats.
177
178 You're encouraged to submit these back to timetrap for inclusion in a future
179 version.
06df6f4 @samg Update documentation for next release
authored
180
f3faead @samg Less wordy readme
authored
181 To create a custom formatter you create a ruby class and implement two methods
182 on it.
06df6f4 @samg Update documentation for next release
authored
183
f3faead @samg Less wordy readme
authored
184 As an example we'll create a formatter that only outputs the notes from
06df6f4 @samg Update documentation for next release
authored
185 entries.
186
187 To ensure that timetrap can find your formatter put it in
188 `~/.timetrap/formatters/notes.rb`. The filename should be the same as the
189 string you will pass to `t d --format` to invoke it. If you want to put your
190 formatter in a different place you can run `t configure` and edit the
191 `formatter_search_paths` option.
192
f3faead @samg Less wordy readme
authored
193 All timetrap formatters live under the namespace `Timetrap::Formatters` so
194 define your class like this:
06df6f4 @samg Update documentation for next release
authored
195
196 class Timetrap::Formatters::Notes
197 end
198
f3faead @samg Less wordy readme
authored
199 When `t display` is invoked, timetrap initializes a new instance of the
06df6f4 @samg Update documentation for next release
authored
200 formatter passing it an Array of entries. It then calls `#output` which should
201 return a string to be printed to the screen.
202
203 This means we need to implement an `#initialize` method and an `#output`
f3faead @samg Less wordy readme
authored
204 method for the class. Something like this:
06df6f4 @samg Update documentation for next release
authored
205
206 class Timetrap::Formatters::Notes
207 def initialize(entries)
208 @entries = entries
209 end
210
211 def output
212 @entries.map{|entry| entry[:note]}.join("\n")
213 end
214 end
215
216 Now when I invoke it:
217
218 $ t d -f notes
219 working on issue #123
220 working on issue #234
221
b71a9a3 Update README
Sam Goldstein authored
222 Timetrap Formatters Repository
223 ------------------------------
224
225 A community focused repository of custom formatters is available at
042dfc7 Fix typo
Sam Goldstein authored
226 https://github.com/samg/timetrap_formatters.
b71a9a3 Update README
Sam Goldstein authored
227
fcffc4e @samg added README and format stub
authored
228 Commands
a66d614 @samg md formatting
authored
229 --------
080a1f7 @samg Restructured README
authored
230 **archive**
a35f5f9 @samg added support for csv export
authored
231 Archives the selected entries (by moving them to a sheet called ``_[SHEET]``)
47d5c37 @samg Updated README
authored
232 These entries can be seen by running ``t display _[SHEET]``.
2786b23 @samg implement archive
authored
233 usage: ``t archive [--start DATE] [--end DATE] [SHEET]``
fcffc4e @samg added README and format stub
authored
234
235 **backend**
236 Run an interactive database session on the timetrap database. Requires the
237 sqlite3 command.
238
239 usage: ``t backend``
240
5bf848a @samg Added configuration via config path
authored
241 **configure**
21b3e5d @samg readme formatting
authored
242 Creates a config file at ``~/.timetrap.yml`` or ``ENV['TIMETRAP_CONFIG_FILE']`` if
06df6f4 @samg Update documentation for next release
authored
243 one doesn't exist. If one does exist it will update it with new
244 configuration options preserving any user overrides. Prints path to config
79ec80d @samg Added docs about erb interpolation of .timetrap.yml
authored
245 file. This file may contain ERB.
5bf848a @samg Added configuration via config path
authored
246
247 usage: ``t configure``
248
fcffc4e @samg added README and format stub
authored
249 **display**
250 Display a given timesheet. If no timesheet is specified, show the current
0608df5 Added docs for `display full` keywords
Sam Goldstein authored
251 timesheet. If ``all`` is passed as SHEET display all timesheets. If ``full``
252 is passed as SHEET archived timesheets are displayed as well. Accepts an
253 optional ``--ids`` flag which will include the entries' ids in the output.
2786b23 @samg implement archive
authored
254 This is useful when editing an non running entry with ``edit``.
fcffc4e @samg added README and format stub
authored
255
e949914 @samg version 1.0
authored
256 Display is designed to support a variety of export formats that can be
257 specified by passing the ``--format`` flag. This currently defaults to
06df6f4 @samg Update documentation for next release
authored
258 text. iCal, csv, json, and numeric id output are also supported.
fcffc4e @samg added README and format stub
authored
259
221c6fa @samg updated README
authored
260 Display also allows the use of a ``--round`` or ``-r`` flag which will round
89770cc @samg Updated README
authored
261 all times in the output. See global options below.
221c6fa @samg updated README
authored
262
0608df5 Added docs for `display full` keywords
Sam Goldstein authored
263 usage: ``t display [--ids] [--round] [--start DATE] [--end DATE] [--format FMT] [SHEET | all | full]``
fcffc4e @samg added README and format stub
authored
264
2786b23 @samg implement archive
authored
265 **edit**
266 Inserts a note associated with the an entry in the timesheet, or edits the
267 start or end times. Defaults to the current time although an ``--id`` flag can
268 be passed with the entry's id (see display.)
269
293582e @samg Added --append option to edit
authored
270 usage: ``t edit [--id ID] [--start TIME] [--end TIME] [--append] [NOTES]``
2786b23 @samg implement archive
authored
271
fcffc4e @samg added README and format stub
authored
272 **in**
273 Start the timer for the current timesheet. Must be called before out. Notes
274 may be specified for this period. This is exactly equivalent to
2786b23 @samg implement archive
authored
275 ``t in; t edit NOTES``. Accepts an optional --at flag.
fcffc4e @samg added README and format stub
authored
276
8610467 @samg kill an entry or a sheet
authored
277 usage: ``t in [--at TIME] [NOTES]``
fcffc4e @samg added README and format stub
authored
278
279 **kill**
8610467 @samg kill an entry or a sheet
authored
280 Delete a timesheet or an entry. Entry's are referenced using an ``--id``
281 flag (see display). Sheets are referenced by name.
fcffc4e @samg added README and format stub
authored
282
8610467 @samg kill an entry or a sheet
authored
283 usage: ``t kill [--id ID] [TIMESHEET]``
fcffc4e @samg added README and format stub
authored
284
285 **list**
286 List the available timesheets.
287
288 usage: ``t list``
289
290 **now**
f0664ba @samg Updated docs for `out`, `now`, and `running`.
authored
291 Print a description of all running entries.
fcffc4e @samg added README and format stub
authored
292
293 usage: ``t now``
294
295 **out**
54e4e33 @samg updated README
authored
296 Stop the timer for the current timesheet. Must be called after in. Accepts an
f0664ba @samg Updated docs for `out`, `now`, and `running`.
authored
297 optional --at flag. Accepts an optional TIMESHEET name to check out of a
298 running, non-current sheet.
fcffc4e @samg added README and format stub
authored
299
f0664ba @samg Updated docs for `out`, `now`, and `running`.
authored
300 usage: ``t out [--at TIME] [TIMESHEET]``
fde33b6 @samg Trimmed whitespace
authored
301
c4c79cf @walski Fixed spec labels according to the continue/resume change.
walski authored
302 **resume**
303 Start the timer for the current timesheet with the same notes as the last entry.
fde33b6 @samg Trimmed whitespace
authored
304 If there is no last entry the new one has blank notes ore uses the optional
c4c79cf @walski Fixed spec labels according to the continue/resume change.
walski authored
305 NOTES parameter.
306
307 usage: ``t resume [--at TIME] [NOTES]``
308
3399bde @samg Rename switch command to sheet.
authored
309 **sheet**
310 Switch to a timesheet creating it if necessary. The default timesheet is
de37f30 @samg `sheet` is equivilent to `list` when invoked without arguments
authored
311 called "default". When no sheet is specified list all existing sheets.
9a018fd @samg Document `t s -`
authored
312 The special timesheet name '-' will switch to the last active sheet.
fcffc4e @samg added README and format stub
authored
313
de37f30 @samg `sheet` is equivilent to `list` when invoked without arguments
authored
314 usage: ``t sheet [TIMESHEET]``
fcffc4e @samg added README and format stub
authored
315
93dfff7 @samg added week command
authored
316 **week**
317 Shortcut for display with start date set to monday of this week
318
f0664ba @samg Updated docs for `out`, `now`, and `running`.
authored
319 usage: ``t week [--ids] [--end DATE] [--format FMT] [TIMESHEET | all]``
93dfff7 @samg added week command
authored
320
5db8b8a @rfunduk add month cli option
rfunduk authored
321 **month**
322 Shortcut for display with start date set to the beginning of this month
323 (or a specified month) and end date set to the end of the month.
324
325 usage: ``t month [--ids] [--start MONTH] [--format FMT] [TIMESHEET | all]``
326
327
221c6fa @samg updated README
authored
328 Global Options
329 --------
330
331 **rounding**
332 passing a ``--round`` or ``-r`` flag to any command will round entry start
333 and end times to the closest 15 minute increment. This flag only affects the
334 display commands (e.g. display, list, week, etc.) and is non-destructive.
335 The actual start and end time stored by Timetrap are unaffected.
b50d979 @samg Added url for bug reporting
authored
336
89770cc @samg Updated README
authored
337 See `configure` command to change rounding increment from 15 minutes.
338
43a1011 @samg Added --yes documentation to README
authored
339 **non-interactive**
340 passing a ``--yes`` or ``-y`` flag will cause any command that requires
341 confirmation (such as ``kill``) to assume an affirmative response to any
342 prompt. This is useful when timetrap is used in a scripted environment.
343
9631769 @samg updated documentation, bumped gem version
authored
344 Configuration
345 --------
346
79ec80d @samg Added docs about erb interpolation of .timetrap.yml
authored
347 Configuration of TimeTrap's behavior can be done through an ERB interpolated
348 YAML config file.
349
9631769 @samg updated documentation, bumped gem version
authored
350 See ``t configure`` for details. Currently supported options are:
351
c7f86a2 @samg minor formatting
authored
352 **round_in_seconds**: The duration of time to use for rounding with the -r flag
06df6f4 @samg Update documentation for next release
authored
353
c7f86a2 @samg minor formatting
authored
354 **database_file**: The file path of the sqlite database
06df6f4 @samg Update documentation for next release
authored
355
c7f86a2 @samg minor formatting
authored
356 **append_notes_delimiter**: delimiter used when appending notes via `t edit --append`
080a1f7 @samg Restructured README
authored
357
c7f86a2 @samg minor formatting
authored
358 **formatter_search_paths**: an array of directories to search for user defined fomatter classes
408e1a5 @samg fixed formatting issue in README
authored
359
c7f86a2 @samg minor formatting
authored
360 **default_formatter**: The format to use when display is invoked without a `--format` option
9631769 @samg updated documentation, bumped gem version
authored
361
080a1f7 @samg Restructured README
authored
362 Special Thanks
363 --------------
364
365 The initial version of Timetrap was heavily inspired by Trevor Caira's
366 Timebook, a small python utility.
367
368 Original Timebook available at:
369 http://bitbucket.org/trevor/timebook/src/
090e0a9 @samg Updated readme with new config option
authored
370
b50d979 @samg Added url for bug reporting
authored
371 Bugs and Feature Requests
372 --------
373 Submit to http://github.com/samg/timetrap/issues
Something went wrong with that request. Please try again.