commandline examples

neels@box:~$ ptimer -h
Usage: ptimer [<name> | stop | ...]
Examples:
  ptimer foo   -- starts the clock on project "foo" (stops others)
  ptimer       -- prints the current project and running time
  ptimer stop  -- stops the current clock
  ptimer log   -- shows all recorded project times (except running).
                  Also corrects the grand total if necessary.
  ptimer + 1:23     -- adds some time to the running timer
  ptimer + -1:23    -- subtracts from the running timer
  ptimer -t 76:54   -- adds to the grand total
  ptimer -t -76:54  -- subtracts from the grand total
  ptimer rotate     -- start a new log file

Get the complete help with the -h option.

neels@box:~$ ptimer
(0)

Just call ptimer to get a status message. First invocation shows a grand total of zero hours.

neels@box:~$ ptimer project_A
started project_A.
neels@box:~$ ptimer
project_A=0 (0)
neels@box:~$ ptimer
project_A=0:01 (0:01)
neels@box:~$ ptimer stop
stopped project_A (0:02).
neels@box:~$ ptimer
(0:02)

Start a project timer by giving any name as argument to ptimer. The first query shows zero hours, which becomes "0:01" after one minute, for both "project_A" and the grand total.

Stop the currently running project by passing "stop" to ptimer. The final total is 2 minutes.

neels@box:~$ ptimer foo
started foo.
neels@box:~$ ptimer bar
stopped foo (0:02).
started bar.

You can also switch directly to another project, without stopping explicitly.

neels@box:~$ ptimer log
2009-10-15  (0:01)   foo=0:01
2009-10-16  (0:04)   foo=0:02 project_A=0:02
2009-10     (0:05)   foo=0:03 project_A=0:02

Running Total: 0:05

Calling ptimer log prints a log of each day and each month of project hours.

Here, project "bar" is not included yet, since it is still running.

Note that ptimer log also fixes the grand total if the log's total differs. So you can edit the log file at ~/.project-timer/log and then call ptimer log to calculate the new total.

neels@box:~$ ptimer stop
stopped bar (0:01).
neels@box:~$ ptimer log
2009-10-15  (0:01)   foo=0:01
2009-10-16  (0:05)   foo=0:02 bar=0:01 project_A=0:02
2009-10     (0:06)   foo=0:03 bar=0:01 project_A=0:02

Running Total: 0:06
neels@box:~$

Project bar shows up in the log once its timer is stopped.

neels@box:~$ ptimer foo
started foo.
neels@box:~$ ptimer + 1:23
foo=1:23 (1:29)
neels@box:~$ ptimer stop
stopped foo (1:23).
neels@box:~$ ptimer log
2009-10-15  (0:01)   foo=0:01
2009-10-16  (1:28)   foo=1:25 bar=0:01 project_A=0:02
2009-10     (1:29)   foo=1:26 bar=0:01 project_A=0:02

Running Total: 1:29

This manually adds some hours to the running timer, here one hour and 23 minutes.

Note: This is implemented by shifting the recorded starting time for this timer backwards by 1:23 hours. If you add many hours, the starting time may shift to the previous day.

You can't add or remove time from stopped timers (short of editing the log file). Instead: start, then add, and stop again.

neels@box:~$ ptimer -t -1:00
adjust total: -1 (0:29) 2009-10-16_17-21

This adjusts the grand total. Say you have submitted one working hour to your employer/client to appear on your paycheck. You can then adjust your running total like this. (This is an overall counter across all projects. It makes most sense when there is a single employer for all projects.)

neels@box:~$ export PS1="\`cat ~/.project-timer/human-readable-state\` $PS1"
foo=0:14 (0:52) neels@box:~$ ptimer stop
stopped foo (0:14).
(0:52) neels@box:~$

Gimmick: include the timing status in your command prompt.