workedon

Work tracking from your shell.

Why build this

I believe tracking your work is an important way of measuring productivity and is a habit that is very helpful to develop. But the thing about habits is - if they aren’t easy and accessible, you will eventually stop doing them - just like going to a gym that is 40 minutes away :) I tried different methods to log my work and failed. Google Docs, iCloud Notes, Notepad++, Sticky Notes, etc. I really wanted a way of tracking with very little effort so I could make this a habit. It's pretty obvious that we all spend most of our day on the terminal. Wouldn’t it be nice if I wrote a feature, committed it and then logged what I did right then and there without a second thought? What if I could also search this based on date so I could look at, for example, how productive I was in the past week?

workedon is another attempt of mine to make work logging a habit and improve my productivity.

How it works

This tool is useful in two ways - for logging work and fetching logged work. The implementation is very simple. Work is logged in the form of workedon <text> @ <date>or just workedon <text> (which uses the current date/time). There is a custom parser that reads the content, splits it at the @ to a work and a date component and then uses the awesome dateparser library to parse human-readable dates into datetime objects. This is then saved in a SQLite database (File location varies based on OS). Logged work can be fetched using multiple options that accept similar human-readable date/times. The same parser is used again to parse into datetime objects which are used to query the database. The output uses the current shell's pager to display a paged list similar to git log (your output may slightly vary based on your shell).

Installation

pip install workedon

Requirements

• Python 3.7+

Features

• Log work from your shell in plain text with human-readable dates/times.
  • The date/time is optional. The default is the current date/time.
  • The @ character is used to separate the text from the date/time.
• Fetch logged work with human-readable dates/times.
• Familiar Git-like interface.
• Filter, sort, delete, format and display logged work on your shell.
• Set date/time format of the output through settings.

Settings

Whenever workedon is run for the first time, a settings file named wonfile.py is generated at the user's configuration directory, which varies based on OS. To find out, run:

workedon --print-settings-path

Settings are strings used to configure the behavior of workedon. The currently available settings are:

• DATE_FORMAT : Sets the date format of the output.
  • Must be a valid Python strftime string.
  • Option: --date-format <value>
  • Environment variable: WORKEDON_DATE_FORMAT
• TIME_FORMAT : Sets the time format of the output.
  • Must be a valid Python strftime string.
  • Option: --time-format <value>
  • Environment variable: WORKEDON_TIME_FORMAT
• DATETIME_FORMAT : Sets the date and time format of the output.
  • Must be a valid Python strftime string.
  • Setting this overrides DATE_FORMAT and TIME_FORMAT.
  • Option: --datetime-format <value>
  • Environment variable: WORKEDON_DATETIME_FORMAT
• TIME_ZONE : Sets the time zone of the output.
  • Must be a valid timezone string.
  • Default is the auto-detected timezone using the tzlocal library.
  • Option: --time-zone <value>
  • Environment variable: WORKEDON_TIME_ZONE

Order of priority is Option > Environment variable > Setting.

To find your current settings, run:

workedon --print-settings

Check the default settings here.

Usage

$ workedon --help
Usage: workedon [OPTIONS] COMMAND [ARGS]...

  Work tracking from your shell.

  Example usages:
  1. Logging work:
  workedon painting the garage
  workedon studying for the SAT @ June 23 2010
  workedon pissing my wife off @ 2pm yesterday

  2. Fetching work:
  workedon what
  workedon what --from "2pm yesterday" --to "9am today"
  workedon what --today
  workedon what --past-month

Options:
  -v, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  workedon*  Specify what you worked on, with optional date/time.
  what       Fetch and display logged work.

$ workedon what --help
Usage: what [OPTIONS]

  Fetch and display logged work.

  If no options are provided, work
  from the past week is returned.

Options:
  -r, --reverse           Reverse order while sorting.
  -n, --count INTEGER     Number of entries to return.
  -s, --last              Fetch the last thing you worked on
  -i, --id TEXT           id to fetch with.
  -f, --from TEXT         Start date-time to filter with.
  -t, --to TEXT           End date-time to filter with.
  --since TEXT            Fetch work done since a specified date-time in the
                          past.
  -d, --past-day          Fetch work done in the past 24 hours.
  -w, --past-week         Fetch work done in the past week.
  -m, --past-month        Fetch work done in the past month.
  -y, --past-year         Fetch work done in the past year.
  -e, --yesterday         Fetch work done yesterday.
  -o, --today             Fetch work done today.
  --on TEXT               Fetch work done on a particular date/day.
  --at TEXT               Fetch work done at a particular time on a particular
                          date/day.
  --delete                Delete fetched work.
  -g, --no-page           Don't page the output.
  -l, --text-only         Output the work log text only.
  --date-format TEXT      Sets the date format of the output. Must be a valid
                          Python strftime string.
  --time-format TEXT      Sets the time format of the output. Must be a valid
                          Python strftime string.
  --datetime-format TEXT  Sets the datetime format of the output. Must be a
                          valid Python strftime string.
  --time-zone TEXT        Sets the timezone of the output. Must be a valid
                          timezone string.
  --help                  Show this message and exit.

Limitations

• Your input is limited by your shell. Certain characters like the single quote ' behave differently. Put your content within double quotes to get around special characters.

  For example:

  workedon "repairing my wife's phone"
  

• The date parser which is used may misinterpret some irregular phrases of date/time, but mostly does great.

• There are some reserved keywords that are used as subcommands and cannot be used as the first word of your log's content:

  • workedon
  • what

  You can use double quotes here as well to get around this.

  For example, this will not work:

  workedon what my wife asked me to do @ 3pm 3 days ago
  

  This is fine:

  workedon "what my wife asked me to do" @ 3pm 3 days ago
  

Credits

• dateparser, for an amazing date parser. This project would not be possible without it.
• peewee, for a nice and tiny ORM to interact with SQLite.
• Click, for making writing CLI tools a complete pleasure.
• jrnl, fck and Simon Willison for some inspiration.

History

0.7.0 (2023-04-07)

• add option and environment variable alternatives for all settings
• add setting to specify timezone for display
  • setting : TIME_ZONE
  • option: --time-zone <value>
  • environment variable: WORKEDON_TIME_ZONE
• fix usage of date/time formatting settings
• BREAKING (for advanced users only): removed the db and conf subcommands and moved their options under the main workedon command to free up reserved keywords db and conf.
  • workedon db --print-path is now workedon --print-db-path
  • workedon db --vacuum is now workedon --vacuum-db
  • workedon db --truncate is now workedon --truncate-db
  • workedon db --version is now workedon --db-version
  • workedon conf --print-path is now workedon --print-settings-path
  • workedon conf --print is now workedon --print-settings
  • all above options are now hidden from the user

0.6.3 (2023-04-02)

• enable the settings file wonfile.py
• allow settings DATE_FORMAT, TIME_FORMAT, DATETIME_FORMAT
• add a conf command to view the settings
• fix load_module deprecation
• change default date/time format

0.6.2 (2023-03-21)

• more database optimizations
• add --version for the db subcommand to print current SQLite version

0.6.1 (2023-03-20)

• add some database optimizations
• add a new "db" subcommand for database maintenance (advanced users only)
• add --print-path to print database file path
• add --vacuum to run VACUUM on the database
• add --truncate to delete all saved work
• Remove usage of reserved keyword "work" and make it available

0.6.0 (2023-02-05)

• add fetching by id using --id/-i

0.5.9 (2023-02-05)

• make --count work with all other options

0.5.8 (2023-01-27)

• fix hash generation

0.5.7 (2023-01-26)

• fix deletion

0.5.6 (2023-01-25)

• add --since as alternative for --from
• fix formatting in shell

0.5.5 (2023-01-23)

• add -l/--text-only for text-only output
• remove -d used as alternative for --delete

0.5.4 (2023-01-22)

• add -g as alternative for no-page
• fix help text
• update README
• hashlib: set usedforsecurity

0.5.3 (2023-01-18)

• allow reverse sorting using -r/--reverse

0.5.2 (2023-01-18)

• remove recording seconds for simple querying
• add --no-page to avoid paging
• improve deleting

0.5.1 (2023-01-18)

• fix start > end check
• add --at to fetch work done at a particular time on a particular date/day

0.5.0 (2023-01-14)

• Breaking: rename database to won.db (A new database will be created and the old one will no longer be used.)

0.4.5 (2023-01-13)

• fix error message

0.4.4 (2023-01-13)

• raise if start date is greater than end date

0.4.3 (2023-01-12)

• don't force color when paging

0.4.2 (2023-01-12)

• Python 3.11 support

0.4.1 (2023-01-12)

• ask for deletion only if there's something
• use tz aware now() for comparison

0.4.0 (2023-01-11)

• Breaking: rename database to wondb.sqlite3
• force colored output on windows
• use tz aware RELATIVE_BASE

0.3.3 (2023-01-09)

• add --delete/-d for deletion
• add --on to fetch work done on a particular date/day
• add --last/-s to fetch the last entered work log

0.3.2 (2023-01-08)

• make dependency versions flexible

0.3.1 (2023-01-08)

• Fixed README

0.3.0 (2023-01-08)

• First release on PyPI.