timeless

#+TITLE: Timeless README #+AUTHOR: Adolfo Villafiorita #+STARTUP: showall

Timeless is a simple command line time tracker which supports stopwatches, pomodoro timers, and key-value pair in notes.

Some non nominal conditions are also handled (e.g., starting a clock twice, trying to stop when no clock was started).

• Installation :PROPERTIES: :CUSTOM_ID: installation :END:

Install the gem:

#+BEGIN_EXAMPLE $ gem install timeless #+END_EXAMPLE

• Usage :PROPERTIES: :CUSTOM_ID: usage :END:

Run a pomodoro timer:

#+BEGIN_EXAMPLE timeless pom p:project meeting with c:john timeless pom --duration 60 p:prj2 timeless pom --long # default to 50 minutes #+END_EXAMPLE

Start clocking using a stopwatch:

#+BEGIN_EXAMPLE timeless start requirements doc timeless start --at 'thirty minutes ago' fixing bug 182 for c:tim timeless start --force --at 'five minutes ago' requirements document for p:prj1 #+END_EXAMPLE

Stop clocking:

#+BEGIN_EXAMPLE timeless stop timeless stop forgot notes on start timeless stop --last # reuse the notes of previous entry timeless stop --at 'five minutes ago' timeless stop --start '1 hour ago' --at 'now' clocked a full entry #+END_EXAMPLE

Enter a full entry:

#+BEGIN_EXAMPLE timeless clock activity on p:project # from end of last entry to now timeless clock --start 'three hours ago' --stop 'five minutes ago' #+END_EXAMPLE

What was i doing?

#+BEGIN_EXAMPLE timeless current # print current entry timeless forget # forget pending clock #+END_EXAMPLE

What did I do?

#+BEGIN_EXAMPLE timeless last # print last entry #+END_EXAMPLE

Reporting and exporting

#+BEGIN_EXAMPLE timeless statement timeless balance --from yesterday --filter p:project timeless export #+END_EXAMPLE

Notice that even though =timeless= uses CSV as its native format, the export command generates a CSV file which is more easily parsed by a spreadsheet application such as LibreOffice.

If you do not want to type =timeless= every time, you can invoke a console:

#+BEGIN_EXAMPLE timeless console timeless:000> start timeless:001> stop timeless:002> #+END_EXAMPLE

More information with:

#+BEGIN_EXAMPLE timeless help # get list of available commands timeless help command # help about command timeless man # output this README file #+END_EXAMPLE

• Key-Value pairs :PROPERTIES: :CUSTOM_ID: key-value-pairs :END:

Timeless has some basic support for key-pair values in the notes field.

A key-pair value is entered as:

#+BEGIN_EXAMPLE key:value #+END_EXAMPLE

where =key= is any string starting with a letter and containing letters, numbers, and underscores; and =value= is anything but a space.

For instance a note field could look like:

#+BEGIN_EXAMPLE working for c:john_smith on a:writing_documentation #+END_EXAMPLE

Key value pairs can be used to assign a special meaning to some strings and improve filtering and exporting.

Three special keys are =p= for projects, =c= for clients, and =a= for activity. These keys get dedicated columns in the csv file when using the =export= command.

• If something goes wrong :PROPERTIES: :CUSTOM_ID: if-something-goes-wrong :END:

Timeless writes entries on =~/.timeless.csv=, storing the following information:

• start date and time
• end date and time
• notes

You can edit the file to manually fix entries if you make some mistake.

The =~/timeless.csv= file should contain only correct entries, that is, entries with start, stop, and (possibly empty) notes.

When using a stopwatch, a temporary file =~/.timeless-tmp.csv= is used to store the timestamp of the start command.

• Version History :PROPERTIES: :CUSTOM_ID: version-history :END:

*** 0.6.0

• support for generic keys in notes. Possibility of specifying the same key multiple times in a single note field
• balance now produces distinct reports for each key (on top of the three already generated for projects, activities, and clients)
• management of empty lines in ~/timeless.csv

*** 0.5.0

• updated origin in Gem specification

*** 0.4.0

• second public release
• new =balance= command
• the =report= command has been renamed =statement=
• interactive =console=
• more detailed help for commands
• fixed a bug in the last command: now it returns the last activity in chronological order (rather than the last activity which has been clocked)

*** 0.2.0

• initial public release

** License :PROPERTIES: :CUSTOM_ID: license :END:

Licensed under the terms of the MIT License.

** Contributing :PROPERTIES: :CUSTOM_ID: contributing :END:

• Fork it ( https://github.com/[my-github-username]/timeless/fork )
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create a new Pull Request