git.defcon.no Git - trk/blob - README.txt

   1 General:
   2 ===========================
   3
   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.
   7
   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/)
  13
  14 Example session:
  15 ===========================
  16
  17   # Start tracking time usage:
  18   trk start Big coding-project
  19
  20   # Track a sub-task, e.g. separate tracking for fixes:
  21   trk task Bugfix BUG#3247
  22
  23   # Return from sub-task, keep tracking the main project/activity:
  24   trk main
  25
  26   # Check what is currently going on
  27   trk status
  28
  29   # Stop tracking
  30   trk stop
  31
  32   # Get a tracking report
  33   trk report verbose
  34
  35 Usage:
  36 ===========================
  37
  38 With default execution of trk, data will be stored in, and read from
  39 the directory $HOME/.trk This path may be overridden by setting the
  40 environment variable TRK_DIR, e.g. "env TRK_DIR=/foo/bar trk ..."
  41
  42 trk start <project> (if tracking project: stop-and-start, aka switch)
  43 trk start at <YYYY-MM-DD hh:mm> <project>
  44 trk on <project> (alias for start)
  45
  46   Starts tracking of a project. If 'at' is given, start-time
  47   is overridden to the given time.
  48
  49   If a project was already tracking, that project will be stopped
  50   at the startingpoint of the new tracking, i.e. implicitly switching.
  51
  52 trk stop
  53 trk stop at <YYYY-MM-DD hh:mm>
  54 trk off (alias for stop)
  55
  56   Stops tracking of project, with implicit stopping of any
  57   current activity.
  58
  59 trk list [verbose]
  60 trk projects [verbose]
  61
  62    Lists all known project names. If a project/track is currently
  63    active, thata project will be indicated with a chevron (>).
  64    Adding verbose to the command will display ID hashes along
  65    with the project/track names.
  66
  67 trk task <task>
  68 trk task at <YYYY-MM-DD hh:mm> <task>
  69 trk activity <task>
  70 trk activity at <YYYY-MM-DD hh:mm> <task>
  71
  72   Starts tracking of an activity within the project; think task
  73   or sub-projects. Activities will be tallied within the project
  74   like the "main project", while time counts to both activity
  75   and project.
  76
  77   Only one activity can be ongoing at the same time,
  78   so starting a new activity while one is ongoing stops the current
  79   and starts the new one.
  80
  81 trk main
  82 trk main at <YYYY-MM-DD hh:mm>
  83
  84   Stops tracking ongoing activity, and keeps tracking project.
  85
  86 trk status
  87
  88   Displays current project, charged customer (if any),
  89   start time for this session, time spent on this session,
  90   time spent on project total,
  91   current activity with start time and time spent this session.
  92
  93 trk report
  94 trk report terse <project>
  95 trk report standard <project>
  96 trk report verbose <project>
  97 tkr report details <project>
  98
  99    Gives a tracking report for the given project.
 100    Using "report" with no options provide a standard report for
 101    the last (or current) project tracked as a shortcut.
 102    Note: reports include currently active session. There is currently
 103    no plan to add complexity by adding an option to filter that out..
 104
 105    Terse reports include:
 106      * project name
 107      * charged customer (not implemented)
 108      * total time accumulated
 109
 110    Standard reports include:
 111      * project name
 112      * charged customer (not implemented)
 113      * session start and end datetimes and time elapsed on session
 114      * total time accumulated
 115
 116    Verbose reports include:
 117      * project name
 118      * charged customer
 119      * session start and end datetimes and time elapsed on session
 120      * activity start and end datetimes and time elapesd on activity
 121      * time accumulated per named task
 122      * note texts w/datetime (not implemented)
 123      * total time accumulated
 124
 125    Not implemented yet:
 126    Detailed reports include:
 127      * project name
 128      * charged customer (not implemented)
 129      * session start and end datetimes and time elapsed on session
 130      * activity start and end datetimes and time elapesd on activity
 131      * pauses with start, end, comment and elapsed time (not implemented)
 132      * note texts w/datetime (not implemented)
 133      * time accumulated per named task
 134      * total time accumulated
 135
 136 The following are not implemented, but planned (ordered by priority:
 137
 138 trk tasks
 139 trk activities
 140
 141    Lists all known task/activity names for currently active project/track
 142
 143 trk note Comment will be timestamped
 144
 145   Adds a comment/note to the tracking. The note will not
 146   affect tracked time, but will be included in detailed reports.
 147
 148 trk charge <customer>
 149
 150   Will set a customer name as meta-information. Setting the
 151   charged customer will replace any previously set value.
 152
 153 trk pause <optional description>
 154 trk back
 155
 156   Adds an activity to the project that is not counted on
 157   the project. Pauses will be listed on detailed reports,
 158   but not on terse, standard and verbose reports.
 159
 160 Storage format:
 161 ===========================
 162
 163 The directory used for storing tracking data will be $HOME/.trk unless
 164 overridden with the environment variable TRK_DIR. In this description,
 165 $TRK_DIR will represent the active tracking directory.
 166
 167 Inside $TRK_DIR each track/project will be stored in separate
 168 sub-directories, with a random generated ID as directory name.
 169 The ID of the currently active project/track is stored (single-line)
 170 in the file $TRK_DIR/current, and the last activated track (current,
 171 if one is tracking) is stored in $TRK_DIR/last.
 172
 173 Meta-information, e.g. Title of the current track is stored in the
 174 file $TRK_DIR/<id-hash>/info as a colon-separated key-value list
 175 (currently only title is used).
 176
 177 Time-tracking data is stored as $TRK_DIR/<id-hash>/tracking, as a
 178 very simple format, with start-and-stop times line-by-line:
 179
 180 [YYYY-MM-DD hh:mm] to [YYYY-MM-DD hh:mm]
 181
 182 If a task is currently tracking, the line will be non-ended (i.e. no newline)
 183 with only the start-time in brackets.
 184
 185 Sub-tasks are stored using the same princible as above, with the only
 186 difference that they are contained within the given track's directory.
 187 So, the ID of the last and current tasks will be stored in
 188 $TRK_DIR/<id-hash>/current and $TRK_DIR/<id-hash>/last, the activity
 189 it self in $TRK_DIR/<id-hash>/<id-hash>, with meta-info and tracking in
 190 $TRK_DIR/<id-hash>/<id-hash>/info and $TRK_DIR/<id-hash>/<id-hash>/tracking.
 191
 192 An example of the structure:
 193
 194         $HOME/.trk
 195         ├── 1e2ad171
 196         │   ├── info
 197         │   └── tracking
 198         ├── 373fcd96
 199         │   ├── info
 200         │   └── tracking
 201         ├── 3b5974b0
 202         │   ├── current
 203         │   ├── ef917c75
 204         │   │   ├── info
 205         │   │   └── tracking
 206         │   ├── f657d08e
 207         │   │   ├── info
 208         │   │   └── tracking
 209         │   ├── info
 210         │   ├── last
 211         │   └── tracking
 212         ├── 87670109
 213         │   ├── info
 214         │   └── tracking
 215         ├── current
 216         └── last
 217
 218 Licencing:
 219 ===========================
 220
 221 Copyright Jon Langseth
 222
 223 Permission is hereby granted, free of charge, to any person obtaining a copy of
 224 this software and associated documentation files (the "Software"), to deal in
 225 the Software without restriction, including without limitation the rights to
 226 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 227 of the Software, and to permit persons to whom the Software is furnished to do
 228 so, subject to the following conditions:
 229
 230 The above copyright notice and this permission notice shall be included in all
 231 copies or substantial portions of the Software.
 232
 233 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 234 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 235 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 236 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 237 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 238 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 239 SOFTWARE.