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, that 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 tasks [verbose]
  87 trk activities [verbose]
  88
  89    Lists all known task/activity names for current project/track.
  90    If a given sub-task/activity is currently active, that project
  91    will be indicated with a chevron (>).
  92    Adding verbose to the command will display ID hashes along
  93    with the activity/task names.
  94
  95 trk status
  96
  97   Displays current project, charged customer (if any),
  98   start time for this session, time spent on this session,
  99   time spent on project total,
 100   current activity with start time and time spent this session.
 101
 102 trk report
 103 trk report terse <project>
 104 trk report standard <project>
 105 trk report verbose <project>
 106 tkr report details <project>
 107
 108    Gives a tracking report for the given project.
 109    Using "report" with no options provide a standard report for
 110    the last (or current) project tracked as a shortcut.
 111    Note: reports include currently active session. There is currently
 112    no plan to add complexity by adding an option to filter that out..
 113
 114    Terse reports include:
 115      * project name
 116      * charged customer (not implemented)
 117      * total time accumulated
 118
 119    Standard reports include:
 120      * project name
 121      * charged customer (not implemented)
 122      * session start and end datetimes and time elapsed on session
 123      * total time accumulated
 124
 125    Verbose reports include:
 126      * project name
 127      * charged customer
 128      * session start and end datetimes and time elapsed on session
 129      * activity start and end datetimes and time elapesd on activity
 130      * time accumulated per named task
 131      * note texts w/datetime (not implemented)
 132      * total time accumulated
 133
 134    Not implemented yet:
 135    Detailed reports include:
 136      * project name
 137      * charged customer (not implemented)
 138      * session start and end datetimes and time elapsed on session
 139      * activity start and end datetimes and time elapesd on activity
 140      * pauses with start, end, comment and elapsed time (not implemented)
 141      * note texts w/datetime (not implemented)
 142      * time accumulated per named task
 143      * total time accumulated
 144
 145 The following are not implemented, but planned (ordered by priority:
 146
 147 trk tasks
 148 trk activities
 149
 150    Lists all known task/activity names for currently active project/track
 151
 152 trk note Comment will be timestamped
 153
 154   Adds a comment/note to the tracking. The note will not
 155   affect tracked time, but will be included in detailed reports.
 156
 157 trk charge <customer>
 158
 159   Will set a customer name as meta-information. Setting the
 160   charged customer will replace any previously set value.
 161
 162 trk pause <optional description>
 163 trk back
 164
 165   Adds an activity to the project that is not counted on
 166   the project. Pauses will be listed on detailed reports,
 167   but not on terse, standard and verbose reports.
 168
 169 Storage format:
 170 ===========================
 171
 172 The directory used for storing tracking data will be $HOME/.trk unless
 173 overridden with the environment variable TRK_DIR. In this description,
 174 $TRK_DIR will represent the active tracking directory.
 175
 176 Inside $TRK_DIR each track/project will be stored in separate
 177 sub-directories, with a random generated ID as directory name.
 178 The ID of the currently active project/track is stored (single-line)
 179 in the file $TRK_DIR/current, and the last activated track (current,
 180 if one is tracking) is stored in $TRK_DIR/last.
 181
 182 Meta-information, e.g. Title of the current track is stored in the
 183 file $TRK_DIR/<id-hash>/info as a colon-separated key-value list
 184 (currently only title is used).
 185
 186 Time-tracking data is stored as $TRK_DIR/<id-hash>/tracking, as a
 187 very simple format, with start-and-stop times line-by-line:
 188
 189 [YYYY-MM-DD hh:mm] to [YYYY-MM-DD hh:mm]
 190
 191 If a task is currently tracking, the line will be non-ended (i.e. no newline)
 192 with only the start-time in brackets.
 193
 194 Sub-tasks are stored using the same princible as above, with the only
 195 difference that they are contained within the given track's directory.
 196 So, the ID of the last and current tasks will be stored in
 197 $TRK_DIR/<id-hash>/current and $TRK_DIR/<id-hash>/last, the activity
 198 it self in $TRK_DIR/<id-hash>/<id-hash>, with meta-info and tracking in
 199 $TRK_DIR/<id-hash>/<id-hash>/info and $TRK_DIR/<id-hash>/<id-hash>/tracking.
 200
 201 An example of the structure:
 202
 203         $HOME/.trk
 204         ├── 1e2ad171
 205         │   ├── info
 206         │   └── tracking
 207         ├── 373fcd96
 208         │   ├── info
 209         │   └── tracking
 210         ├── 3b5974b0
 211         │   ├── current
 212         │   ├── ef917c75
 213         │   │   ├── info
 214         │   │   └── tracking
 215         │   ├── f657d08e
 216         │   │   ├── info
 217         │   │   └── tracking
 218         │   ├── info
 219         │   ├── last
 220         │   └── tracking
 221         ├── 87670109
 222         │   ├── info
 223         │   └── tracking
 224         ├── current
 225         └── last
 226
 227 Licencing:
 228 ===========================
 229
 230 Copyright Jon Langseth
 231
 232 Permission is hereby granted, free of charge, to any person obtaining a copy of
 233 this software and associated documentation files (the "Software"), to deal in
 234 the Software without restriction, including without limitation the rights to
 235 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 236 of the Software, and to permit persons to whom the Software is furnished to do
 237 so, subject to the following conditions:
 238
 239 The above copyright notice and this permission notice shall be included in all
 240 copies or substantial portions of the Software.
 241
 242 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 243 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 244 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 245 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 246 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 247 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 248 SOFTWARE.