git.defcon.no Git - trk/blob - concept.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   # Stop tracking
  27   trk stop
  28
  29   # Get a tracking report
  30   trk report verbose
  31
  32 Usage:
  33 ===========================
  34
  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 ..."
  38
  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)
  42
  43   Starts tracking of a project. If 'at' is given, start-time
  44   is overridden to the given time.
  45
  46   If a project was already tracking, that project will be stopped
  47   at the startingpoint of the new tracking, i.e. implicitly switching.
  48
  49 trk stop
  50 trk stop at <YYYY-MM-DD hh:mm>
  51 trk off (alias for stop)
  52
  53   Stops tracking of project, with implicit stopping of any
  54   current activity.
  55
  56 trk list [verbose]
  57 trk projects [verbose]
  58
  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.
  63
  64 trk task <task>
  65 trk task at <YYYY-MM-DD hh:mm> <task>
  66 trk activity <task>
  67 trk activity at <YYYY-MM-DD hh:mm> <task>
  68
  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
  72   and project.
  73
  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.
  77
  78 trk main
  79 trk main at <YYYY-MM-DD hh:mm>
  80
  81   Stops tracking ongoing activity, and keeps tracking project.
  82
  83 trk report
  84 trk report terse <project>
  85 trk report standard <project>
  86 trk report verbose <project>
  87 tkr report details <project>
  88
  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.
  92
  93    Terse reports include:
  94      * project name
  95      * charged customer (not implemented)
  96      * total time accumulated
  97
  98    Standard reports include:
  99      * project name
 100      * charged customer (not implemented)
 101      * session start and end datetimes and time elapsed on session
 102      * total time accumulated
 103
 104    Verbose reports include:
 105      * project name
 106      * charged customer
 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
 112
 113    Not implemented yet:
 114    Detailed reports include:
 115      * project name
 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
 123
 124 The following are not implemented, but planned (ordered by priority:
 125
 126 trk tasks
 127 trk activities
 128
 129    Lists all known task/activity names for currently active project/track
 130
 131 trk status
 132
 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.
 137
 138
 139 trk note Comment will be timestamped
 140
 141   Adds a comment/note to the tracking. The note will not
 142   affect tracked time, but will be included in detailed reports.
 143
 144 trk charge <customer>
 145
 146   Will set a customer name as meta-information. Setting the
 147   charged customer will replace any previously set value.
 148
 149 trk pause <optional description>
 150 trk back
 151
 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.
 155
 156 Storage format:
 157 ===========================
 158
 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.
 162
 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.
 168
 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).
 172
 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:
 175
 176 [YYYY-MM-DD hh:mm] to [YYYY-MM-DD hh:mm]
 177
 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.
 180
 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.
 187
 188 An example of the structure:
 189
 190         $HOME/.trk
 191         ├── 1e2ad171
 192         │   ├── info
 193         │   └── tracking
 194         ├── 373fcd96
 195         │   ├── info
 196         │   └── tracking
 197         ├── 3b5974b0
 198         │   ├── current
 199         │   ├── ef917c75
 200         │   │   ├── info
 201         │   │   └── tracking
 202         │   ├── f657d08e
 203         │   │   ├── info
 204         │   │   └── tracking
 205         │   ├── info
 206         │   ├── last
 207         │   └── tracking
 208         ├── 87670109
 209         │   ├── info
 210         │   └── tracking
 211         ├── current
 212         └── last
 213
 214 Licencing:
 215 ===========================
 216
 217 Copyright Jon Langseth
 218
 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:
 225
 226 The above copyright notice and this permission notice shall be included in all
 227 copies or substantial portions of the Software.
 228
 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
 235 SOFTWARE.