From: Jon Langseth Date: Mon, 13 May 2013 10:36:37 +0000 (+0200) Subject: Fleshing out the readme X-Git-Url: https://git.defcon.no/?p=trk;a=commitdiff_plain;h=b1b238b174926ef01f2e977b8136208121c76817 Fleshing out the readme --- diff --git a/concept.txt b/concept.txt index 111f65e..c9ef067 100644 --- a/concept.txt +++ b/concept.txt @@ -1,3 +1,41 @@ +General: +=========================== + +trk is a simple time tracker with support for sub-tasks/activities. +It is implemented using perl, and should work with no additional +modules using perl >= 5.8 on a Unix/Linux based system. + +trk was inspired by several similar simple console based trackers, like: + * ti (http://ti.sharats.me/) + * timed (http://adeel.github.io/timed/), + * timetrap (https://github.com/samg/timetrap) + * wtime (http://wtime.sourceforge.net/) + +Example session: +=========================== + + # Start tracking time usage: + trk start Big coding-project + + # Track a sub-task, e.g. separate tracking for fixes: + trk task Bugfix BUG#3247 + + # Return from sub-task, keep tracking the main project/activity: + trk main + + # Stop tracking + trk stop + + # Get a tracking report + trk report verbose + +Usage: +=========================== + +With default execution of trk, data will be stored in, and read from +the directory $HOME/.trk This path may be overridden by setting the +environment variable TRK_DIR, e.g. "env TRK_DIR=/foo/bar trk ..." + trk start (if tracking project: stop-and-start, aka switch) trk start at trk on (alias for start) @@ -5,15 +43,26 @@ trk on (alias for start) Starts tracking of a project. If 'at' is given, start-time is overridden to the given time. - Future expansion: If a project was already tracking, that project will be stopped at the startingpoint of the new tracking, i.e. implicitly switching. -trk note Comment will be timestamped +trk stop +trk stop at +trk off (alias for stop) - Adds a comment/note to the tracking. The note will not - affect tracked time, but will be included in detailed reports. + Stops tracking of project, with implicit stopping of any + current activity. +trk list [verbose] +trk projects [verbose] + + Lists all known project names. If a project/track is currently + active, thata project will be indicated with a chevron (>). + Adding verbose to the command will display ID hashes along + with the project/track names. + +trk task +trk task at trk activity trk activity at @@ -22,7 +71,6 @@ trk activity at like the "main project", while time counts to both activity and project. - Future: Only one activity can be ongoing at the same time, so starting a new activity while one is ongoing stops the current and starts the new one. @@ -32,47 +80,24 @@ trk main at Stops tracking ongoing activity, and keeps tracking project. -trk pause -trk back - - Adds an activity to the project that is not counted on - the project. Pauses will be listed on detailed reports, - but not on terse, standard and verbose reports. - -trk charge - - Will set a customer name as meta-information. Setting the - charged customer will replace any previously set value. - -trk status - - Displays current project, charged customer (if any), - start time for this session, time spent on this session, - time spent on project total, - current activity with start time and time spent this session. - -trk stop -trk stop at -trk off (alias for stop) - - Stops tracking of project, with implicit stopping of any - current activity. - +trk report trk report terse -trk report +trk report standard trk report verbose tkr report details Gives a tracking report for the given project. + Using "report" with no options provide a standard report for + the last (or current) project tracked as a shortcut. Terse reports include: * project name - * charged customer + * charged customer (not implemented) * total time accumulated Standard reports include: * project name - * charged customer + * charged customer (not implemented) * session start and end datetimes and time elapsed on session * total time accumulated @@ -81,22 +106,130 @@ tkr report details * charged customer * session start and end datetimes and time elapsed on session * activity start and end datetimes and time elapesd on activity - * note texts w/datetime * time accumulated per named task + * note texts w/datetime (not implemented) * total time accumulated + Not implemented yet: Detailed reports include: * project name - * charged customer + * charged customer (not implemented) * session start and end datetimes and time elapsed on session * activity start and end datetimes and time elapesd on activity - * pauses with start, end, comment and elapsed time - * note texts w/datetime + * pauses with start, end, comment and elapsed time (not implemented) + * note texts w/datetime (not implemented) * time accumulated per named task * total time accumulated -trk projects +The following are not implemented, but planned (ordered by priority: + +trk tasks +trk activities - Lists all known project names + Lists all known task/activity names for currently active project/track + +trk status + Displays current project, charged customer (if any), + start time for this session, time spent on this session, + time spent on project total, + current activity with start time and time spent this session. + + +trk note Comment will be timestamped + + Adds a comment/note to the tracking. The note will not + affect tracked time, but will be included in detailed reports. + +trk charge + + Will set a customer name as meta-information. Setting the + charged customer will replace any previously set value. + +trk pause +trk back + + Adds an activity to the project that is not counted on + the project. Pauses will be listed on detailed reports, + but not on terse, standard and verbose reports. +Storage format: +=========================== + +The directory used for storing tracking data will be $HOME/.trk unless +overridden with the environment variable TRK_DIR. In this description, +$TRK_DIR will represent the active tracking directory. + +Inside $TRK_DIR each track/project will be stored in separate +sub-directories, with a random generated ID as directory name. +The ID of the currently active project/track is stored (single-line) +in the file $TRK_DIR/current, and the last activated track (current, +if one is tracking) is stored in $TRK_DIR/last. + +Meta-information, e.g. Title of the current track is stored in the +file $TRK_DIR//info as a colon-separated key-value list +(currently only title is used). + +Time-tracking data is stored as $TRK_DIR//tracking, as a +very simple format, with start-and-stop times line-by-line: + +[YYYY-MM-DD hh:mm] to [YYYY-MM-DD hh:mm] + +If a task is currently tracking, the line will be non-ended (i.e. no newline) +with only the start-time in brackets. + +Sub-tasks are stored using the same princible as above, with the only +difference that they are contained within the given track's directory. +So, the ID of the last and current tasks will be stored in +$TRK_DIR//current and $TRK_DIR//last, the activity +it self in $TRK_DIR//, with meta-info and tracking in +$TRK_DIR///info and $TRK_DIR///tracking. + +An example of the structure: + + $HOME/.trk + ├── 1e2ad171 + │   ├── info + │   └── tracking + ├── 373fcd96 + │   ├── info + │   └── tracking + ├── 3b5974b0 + │   ├── current + │   ├── ef917c75 + │   │   ├── info + │   │   └── tracking + │   ├── f657d08e + │   │   ├── info + │   │   └── tracking + │   ├── info + │   ├── last + │   └── tracking + ├── 87670109 + │   ├── info + │   └── tracking + ├── current + └── last + +Licencing: +=========================== + +Copyright Jon Langseth + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/ideas b/ideas deleted file mode 100644 index 1430e66..0000000 --- a/ideas +++ /dev/null @@ -1,19 +0,0 @@ -Handle Activities within a project like projects are handled from "root": - Separate hash-ID directory for each activity - Separate info-file with optional meta-data per activiy - Separate tracking-file per activity. - Activities stored as sub-directories of related project - Keep track of current and last activity - -Change functions/subs that handle projects currently to be -generic, and take PROJECT id as optional argument, following -the logic: if an argument is passed, the function should -operate on an activity, if no argument is passed, on project. - -Fix code so start = stop->start can work -Make sure stop stops current activity, if any -Allow activities to toggle (activity = main->activity) - -Be naive: assume that tracking files are consistent :) -Maybe: get inspiration from ti: read until last line, and regex new info onto it :) -