2 ===========================
4 trk is a simple time tracker with support for sub-tasks/activities.
5 It is implemented using perl, and should work with no additional
6 modules using perl >= 5.8 on a Unix/Linux based system.
8 trk was inspired by several similar simple console based trackers, like:
9 * ti (http://ti.sharats.me/)
10 * timed (http://adeel.github.io/timed/),
11 * timetrap (https://github.com/samg/timetrap)
12 * wtime (http://wtime.sourceforge.net/)
15 ===========================
17 # Start tracking time usage:
18 trk start Big coding-project
20 # Track a sub-task, e.g. separate tracking for fixes:
21 trk task Bugfix BUG#3247
23 # Return from sub-task, keep tracking the main project/activity:
29 # Get a tracking report
33 ===========================
35 With default execution of trk, data will be stored in, and read from
36 the directory $HOME/.trk This path may be overridden by setting the
37 environment variable TRK_DIR, e.g. "env TRK_DIR=/foo/bar trk ..."
39 trk start <project> (if tracking project: stop-and-start, aka switch)
40 trk start at <YYYY-MM-DD hh:mm> <project>
41 trk on <project> (alias for start)
43 Starts tracking of a project. If 'at' is given, start-time
44 is overridden to the given time.
46 If a project was already tracking, that project will be stopped
47 at the startingpoint of the new tracking, i.e. implicitly switching.
50 trk stop at <YYYY-MM-DD hh:mm>
51 trk off (alias for stop)
53 Stops tracking of project, with implicit stopping of any
57 trk projects [verbose]
59 Lists all known project names. If a project/track is currently
60 active, thata project will be indicated with a chevron (>).
61 Adding verbose to the command will display ID hashes along
62 with the project/track names.
65 trk task at <YYYY-MM-DD hh:mm> <task>
67 trk activity at <YYYY-MM-DD hh:mm> <task>
69 Starts tracking of an activity within the project; think task
70 or sub-projects. Activities will be tallied within the project
71 like the "main project", while time counts to both activity
74 Only one activity can be ongoing at the same time,
75 so starting a new activity while one is ongoing stops the current
76 and starts the new one.
79 trk main at <YYYY-MM-DD hh:mm>
81 Stops tracking ongoing activity, and keeps tracking project.
84 trk report terse <project>
85 trk report standard <project>
86 trk report verbose <project>
87 tkr report details <project>
89 Gives a tracking report for the given project.
90 Using "report" with no options provide a standard report for
91 the last (or current) project tracked as a shortcut.
93 Terse reports include:
95 * charged customer (not implemented)
96 * total time accumulated
98 Standard reports include:
100 * charged customer (not implemented)
101 * session start and end datetimes and time elapsed on session
102 * total time accumulated
104 Verbose reports include:
107 * session start and end datetimes and time elapsed on session
108 * activity start and end datetimes and time elapesd on activity
109 * time accumulated per named task
110 * note texts w/datetime (not implemented)
111 * total time accumulated
114 Detailed reports include:
116 * charged customer (not implemented)
117 * session start and end datetimes and time elapsed on session
118 * activity start and end datetimes and time elapesd on activity
119 * pauses with start, end, comment and elapsed time (not implemented)
120 * note texts w/datetime (not implemented)
121 * time accumulated per named task
122 * total time accumulated
124 The following are not implemented, but planned (ordered by priority:
129 Lists all known task/activity names for currently active project/track
133 Displays current project, charged customer (if any),
134 start time for this session, time spent on this session,
135 time spent on project total,
136 current activity with start time and time spent this session.
139 trk note Comment will be timestamped
141 Adds a comment/note to the tracking. The note will not
142 affect tracked time, but will be included in detailed reports.
144 trk charge <customer>
146 Will set a customer name as meta-information. Setting the
147 charged customer will replace any previously set value.
149 trk pause <optional description>
152 Adds an activity to the project that is not counted on
153 the project. Pauses will be listed on detailed reports,
154 but not on terse, standard and verbose reports.
157 ===========================
159 The directory used for storing tracking data will be $HOME/.trk unless
160 overridden with the environment variable TRK_DIR. In this description,
161 $TRK_DIR will represent the active tracking directory.
163 Inside $TRK_DIR each track/project will be stored in separate
164 sub-directories, with a random generated ID as directory name.
165 The ID of the currently active project/track is stored (single-line)
166 in the file $TRK_DIR/current, and the last activated track (current,
167 if one is tracking) is stored in $TRK_DIR/last.
169 Meta-information, e.g. Title of the current track is stored in the
170 file $TRK_DIR/<id-hash>/info as a colon-separated key-value list
171 (currently only title is used).
173 Time-tracking data is stored as $TRK_DIR/<id-hash>/tracking, as a
174 very simple format, with start-and-stop times line-by-line:
176 [YYYY-MM-DD hh:mm] to [YYYY-MM-DD hh:mm]
178 If a task is currently tracking, the line will be non-ended (i.e. no newline)
179 with only the start-time in brackets.
181 Sub-tasks are stored using the same princible as above, with the only
182 difference that they are contained within the given track's directory.
183 So, the ID of the last and current tasks will be stored in
184 $TRK_DIR/<id-hash>/current and $TRK_DIR/<id-hash>/last, the activity
185 it self in $TRK_DIR/<id-hash>/<id-hash>, with meta-info and tracking in
186 $TRK_DIR/<id-hash>/<id-hash>/info and $TRK_DIR/<id-hash>/<id-hash>/tracking.
188 An example of the structure:
215 ===========================
217 Copyright Jon Langseth
219 Permission is hereby granted, free of charge, to any person obtaining a copy of
220 this software and associated documentation files (the "Software"), to deal in
221 the Software without restriction, including without limitation the rights to
222 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
223 of the Software, and to permit persons to whom the Software is furnished to do
224 so, subject to the following conditions:
226 The above copyright notice and this permission notice shall be included in all
227 copies or substantial portions of the Software.
229 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
230 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
231 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
232 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
233 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
234 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE