Package: nttl
NTTLNoTimeToLose, a tiny command line (work) time tracker
with basic report capabilities and a plain text data storage format.Tracking TimeTo start tracking the time you spend on a task, simply runnttlstartTo see what you’re currently tracking, runnttlstatusOnce you’re done, runnttlstopTo list the measured time spans, runnttllistnttlmight then output something like this, indicating a time period of
work between 07:32 and 08:57 on 2024-01-28.2024-01-28 07:32:10 (start)  []
    2024-01-28 08:57:41 (stop)  []If you switch to a new activity, it would be very annoying to have to runnttl stopandnttl start. Instead you can usenttlswitchThere’s also theeventcommand, but that only makes sense when you use
labels and descriptions:Labels and DescriptionsForstart,stop,switch, andeventyou can providelabelsand adescriptionto specify what exactly you’re working on, like this:nttlstart-lwork-lprogramming-d"Adding a new feature to Blarp"This will add the labelsworkandprogrammingto the time span that
you’re tracking. This is very useful once you’re getting to the reporting
side of things:Time Reportsnttlcan report the time spent in the three human-readable formats and
one for integration with other programs:Gantt chart, a textual Gantt chart of time spent grouped by labelsBar chart, a textual bar chart of time spent grouped by labelsText report, just a listing grouped by time or labelsCSVfile formatYou can tellnttlto only include activities with certain labels in the
report with--label(or-l), or exclude activities that have certain
labels with--exclude-label(or-x). Both parameters,-land-x,
may be provided multiple times.To select the time window for which to create a report, see Time range
selection:Time range selectionThe--startand--endparameters can be used to select the time range
for which areport(orlist) should be created. Their default values
will create a time report for the last seven days.Both--startand--endhave a short form:-sand-erespectively.You can express times in two different ways: absolute and relative.Absolute time selectionAbsolute uses the ISO date format and looks like this:nttlreport--start"2023-11-28 12:00"--end"2023-12-31 23:59"This would create a report for the time between 2023-11-28 and the end of
the year 2023.If you only provide a time (e.g.07:23),nttlassumes you meant "today" at
that time.If you only provide a date (e.g.2023-11-29),nttlassumes you meant00:00(midnight) of that date.Relative time selectionYou can specify points in time relative to "now" by prefixing the-sor-eparameter withTfollowed by, for example:+20s, 20 seconds later+5m, 5 minutes later-2h, 2 hours earlier-1d, 1 day earlier+2w, 2 weeks laterThese can be combined to express, for example, "two weeks and two hours ago":-2w2h.Example, request the report for the last 7 days, excluding today:nttlreport--start"T-7d"--end"T-1d"Day of weekFor the--startand--endparameters you may also provide the name of a
day of the week in your locale. For example, if your computer is set to
Dutch and you want to show everything since the last Friday, you could runnttlreport--startVrijdagThe short version of the day of the week is also understood (e.g.vr.in
this example).No matter what your locale is set to, English weekdays are always
understood.TodayYou can use the phrasetodayin both--startand--end. But it's
usually faster to write the equivalentT0.Textual reportThe textual report is the default, but you can request it explicitly withnttlreport-ftextThe output might look like this:2024-01-03
      07:30 - 08:15    emails, work    
      08:15 - 08:30    meeting, work    weekly team meeting
      08:30 - 08:43    break    
      08:43 - 10:00    bigProject1, programming, work    
      10:00 - 10:35    bigProject1, meeting, work    project meeting
      10:35 - 12:00    bigProject1, programming, work    
      12:00 - 12:35    break, lunch    
      12:35 - 14:30    otherProject, programming, work    going home earlierYou can see the time spans sorted by day and time followed by labels
and description.Gantt chart reportThis report will produce a textual Gantt chart of time spent on activities
grouped by labels. With the previous textual report in mind, a Gantt chart
report would look like this:bigProject1  │               ████████████████████████████████████████                             
     break        │            ████                                      ████████                      
     emails       │██████████                                                                          
     lunch        │                                                      ████████                      
     meeting      │         ████                 ████████                                              
     otherProject │                                                             ███████████████████████
     programming  │               ████████████████      ██████████████████      ███████████████████████
     work         │█████████████  ████████████████████████████████████████      ███████████████████████
    ──────────────┼─────────────────────────────────────────────────────────────────────────────────────
                  │└ 07:30 └ 08:10 └ 08:50 └ 09:30 └ 10:10 └ 10:50 └ 11:30 └ 12:10 └ 12:50 └ 13:30 └ 14:10 
                  │By default the X-axis will be 1 hour per character, but you can provide a--resolutionparameter to change it. The Gantt chart above was created
with--resolution 5mto have 5 minutes per character.Bar chart reportThis report will produce a textual bar chart of time spent on activities
grouped by labels. With the previous Gantt chart and textual report in
mind, the bar chart would look like this:7  │                                                                              
       6  │                                                                              
       5  │                                                                         ████ 
       4  │                                                               ▄▄▄▄      ████ 
       3  │     ▂▂▂▂                                                      ████      ████ 
       2  │     ████                                                      ████      ████ 
       1  │     ████                                         ▆▆▆▆         ████      ████ 
       0  │     ████      ▆▆▆▆    ▄▄▄▄   ▄▄▄▄    ▆▆▆▆        ████         ████      ████ 
    ──────┼──────────────────────────────────────────────────────────────────────────────
          │  bigProject1  break  emails  lunch  meeting  otherProject  programming  workThe Y-axis is 1 hour per line. This can not be changed at the moment.Advanced UsageModified 'Now'Sometimes you will only be able tostart,stop, orswitchafter the
fact or even before the fact (e.g. when you know you will be in a meeting
in 5 minutes).To express that, you can use the--when(or short-w) parameter to
modify the time when that action (start,stop,switch) should be
registered.--whenaccepts both absolute and relative time.For example, if you have been interrupted in your work by an impromptu
meeting, you could run this after the 15 minutes meeting:nttlswitch-lmeeting-lwork-w"T-15m"nttlswitch-lwork-lprogrammingMultiple tasksnttlcan track multiple tasks at the same time. For example, you could
runnttlstart-lworknttlstart-lmeetingAt which pointnttl statuswould show two active tasks:Active tasks:
    (1) 2024-01-05 08:12:13  ['work']
    (2) 2024-01-05 08:12:14  ['meeting']Just runningnttl stopornttl switchwould stop the tracking of all
active tasks.To only stop one of the running tasks, use the--task(or short-t)
parameter.For example, to stop tracking of the meeting, runnttlstop-t2The first task, labelledwork, would remain active.At the moment-tdoes not work forswitch.Eventsnttlsupports an additional action tostart,stop, andswitch:event. This can be useful when integratingnttlwith your desktop
environment.For example, when you lock your screen the desktop environment
could callnttl event -d "Lock screen".Or you could have a git hook set up to callnttl event -d "git push".Events can be useful if you want to have checkpoints in your daily
activities to be able to reconstruct the exact time of when you left your
desk or when you completed a task without having to callnttlwithswitchorstart/stopall the time.Status Display in Desktop EnvironmentYou can utilisenttl statuswith its formats (json,csv,customtext) to integrate the current status of tracked tasks into your desktop
environment.For example, an integration intoswaywithwaybarcould work by adding
this to yourwaybarconfiguration file:"custom/nttl":{"format":" {} ","interval":1,"exec-if":"test $(nttl status -f csv 2> /dev/null | wc -l) -gt 0","exec":"nttl status -f custom -c '{description}, {labels}' | head -n 1"}It would verify that at least one task is being tracked, by counting the
lines of thenttl statusexport ascsv, and if there is a task running,
the custom format is used as the label in the task bar.Data StorageThe data file is stored in your home directory at.local/share/nttl/times.tomland uses theTOMLfile
format.nttlonly accesses the data file while running, so you can manually edit
that file in any text editor at any other point in time without affectingnttl.InstallationTo installnttl, it’s probably best to use pip:pipinstallnttlAlternatively you can clone the git repository and installnttllike
this:gitclonehttps://codeberg.org/vonshednob/nttlcdnttlpythonsetup.pyinstallLicenseCopyright (C) 2024 Robert Labuddamailto:contact+nttl@vonshednob.cc.This program is free software: you can redistribute it and/or modify
it under the terms of theGNU General Public Licenseas published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See theGNU General Public Licensefor more details.You should have received a copy of theGNU General Public Licensealong with this program.  If not, seehttps://www.gnu.org/licenses/.