ja-he / dayplan

A utility to plan and track your time.

Dayplan

A utility to plan and track your time.

Warning/Disclaimer

• 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. :)

Installation

Arch Linux

For Arch Linux and its derivatives there is an AUR package available.

Manually

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).

Usage

• 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

Regular TUI Usage (tui)

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.

Keyboard-driven

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)

Mouse-driven

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

Getting Summaries (summarize)

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-readable

Getting a Timesheet (timesheet)

This 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.

Adding events via CLI (add)

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.

Configuration and Defaults

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>

File Content Formatting

Days

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

Configuration

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 short¹ 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'
  # ...

Note: Terminal Color Support

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

1. 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. ↩