A utility to plan and track your time.
- format-wise, nothing is set in stone right now
I would like to keep things simple, but I've already thought about going to a Markdown-ish format (like taskell uses) and I'll assume that any format changes that I can accommodate for myself with sed are fair game - it's unpolished
there's definitely rough edges that I just ignore for now to tackle more relevant work - the code might suck?
I wrote this to familiarize myself with Go; who knows if it worked? (the goreportcard rating up top is definitely way too lenient)
but also
- is it any good?
sure. I've been happily using it for months. :)
For Arch Linux and its derivatives there is an AUR package available.
All that's really needed is a go install github.com/ja-he/dayplan@latest.
However there is a small build script .scripts/build.sh available that takes
care of inserting version and commit information.
Therefore the recommended steps are:
git clone https://github.com/ja-he/dayplan
cd dayplan
./.scripts/build.sh install
As it still uses go install under the hood, the binary should be in your
$GOPATH (or if empty in $HOME/go/bin).
- Help messages are available e.g. via
-h - in TUI mode the key ? toggles a help popup panel showing the controls based on the current context (this is generated; while being maybe not structured as nicely, it should generally provide the most complete and up-to-date information
Dayplan mainly works as a terminal UI (TUI) program invoked simply by calling
the program with the tui subcommand:
$ dayplan tui
In this mode it allows you sketch out the events of a day, similar to how a graphical calendar application might work.
These events can then be shuffled around, resized, renamed, etc. as the day goes on and it turns out that one task actually took a lot longer or that phone call fell through. Thus you end up with a list of the (important) events of the day.
Dayplan can be controlled via both mouse and keyboard. Key mappings are "vim-ish" and not currently configurable.
| key input | does... |
|---|---|
| ? | open help (context-based) |
| h / l | switch the current day |
| i / ESC | switch between day, week, and month view |
| + / - | zoom in or out |
| j / k | select next or previous event |
| d | delete the current event |
| CTRL-wh / CTRL-wl | switch to left / right ui pane |
| S | toggle a summary view (for day/week/...) |
| W | load the weather (see the config section) |
| w | write the current day to file |
| q | quit |
| m | enter event move mode, in which... |
| j / k | ...move event up or down |
| m / ESC | ...exit mode |
| r | enter event resize mode, in which... |
| j / k | ...lengthen or shorten event |
| r / ESC | ...exit mode |
| (see help... | ...for more) |
To roughly emulate the expected behavior of a familiar calendar application, the mouse can also be used for editing (in truth, this was the initial method implemented, as it's pretty straightforward to define what the basic operations should be and how they should behave):
- move: left click inside of an event and drag it
- resize: left click on the end (timestamp) of an event and drag it
- edit name: left click on the events name (or anywhere at the top of the event)
- delete: middle click on the event
- split: right click on the event at the time at which to split it
To then get summary information about the information generated in this way,
dayplan has the subcommand summarize. It requires you to specify a --from
and a --til date and summarizes the duration of events in this range by their
categories.
You could for example use dayplan as above to track your working hours and then
see how much you've worked in November 2021 using the following command:
$ dayplan summarize --from 2021-11-01 --til 2021-11-30 \
--category-filter work \
--human-readableThis is similar but distinct from summaries. You might have to fill out a timesheet at some point, of a format like the following, but probably in a spreadsheet:
| Date | Start | Break Duration | End |
|---|---|---|---|
| 2022-12-01 | 08:45 | 45min | 16:30 |
| 2022-12-02 | 08:52 | 1h | 16:20 |
| ... | ... | ... | ... |
You can generate the data for this with dayplan using the (timesheet) subcommand:
$ dayplan timesheet --from "2022-12-01" \
--til "2022-12-31" \
--category "my-project" \
--include-empty
This would give you roughly the output
2022-12-01,08:45,45min,16:30
2022-12-02,08:52,1h,16:20
...
which should already be sufficient for opening as / copy-pasting into a spreadsheet.
Be sure to check out dayplan timesheet --help as well.
Besides being able to add events in the TUI mode, events can also be added via
the add subcommand.
This is especially useful for adding repeat events, in which case a start date,
an end date, and the period of repetition need to be specified.
For more see dayplan add -h.
By default dayplan uses the directory ${HOME}/.config/dayplan for
configuration and data storage. This directory can be set with the
DAYPLAN_HOME environment variable.
In the subdirectory days then days are stored as files named by
YYYY-MM-DD format.
Optionally, category styles can be defined in the file config.yaml; also see
the Configuration section.
To get weather and sunrise/-set information you'll need to define latitude and
longitude as environment variables (e.g. in the .bashrc):
export LATITUDE=12.3456
export LONGITUDE=11.1111
For getting the weather information from OWM you'll also need to have
OWM_API_KEY defined in the same way, e.g.
export OWM_API_KEY=<key>
A day, usually at ${DAYPLAN_HOME}/days/<YYYY-MM-DD>, is a list of events
formatted as
<start>|<end>|<category>|<title>
so for example a day with three events might be
08:00|08:30|eat|Breakfast
08:30|10:00|fitness|Work Out
10:00|18:00|misc|Do Absolutely Nothing
Dayplan can be optionally configured in ${DAYPLAN_HOME}/config.yaml.
Configuration currently entails theming and categories.
- The general UI colors are defined under
stylesheet. - The categories are listed under
categories
Here a very short1 example of the file format:
stylesheet:
normal: { fg: '#000000', bg: '#ffffff' }
timeline-day: { fg: '#c0c0c0', bg: '#ffffff' }
timeline-night: { fg: '#f0f0f0', bg: '#000000' }
timeline-now: { fg: '#ffffff', bg: '#ff0000' }
summary-default: { fg: '#000000', bg: '#ffffff' }
summary-title-box: { fg: '#000000', bg: '#f0f0f0', style: { italic: true } }
categories:
- name: uni
color: '#ffdccc'
- name: work
color: '#ffcccc'
goal: # this helps track overtime
workweek:
monday: 5h
tuesday: 5h
wednesday: 5h
thursday: 5h
friday: 0h
saturday: 0h
sunday: 0h
- name: cooking
color: '#ccffe6'
# ...Currently, a true color terminal is required; use of other color codes is not supported.
However, this is not inherent to dayplan; see #24.
Footnotes
-
As these identifiers are very much subject to change pre-v1.0.0, I'm refraining from providing a default 'config.yaml' file in the repo. Please just look through the sources in 'src/config/config.go' to see the yaml-identifiers that are available for stylings. ↩