DIARY(1) General Commands Manual DIARY(1)

diary - text-based journaling program

diary [OPTION]... [DIARY_DIR]...

Open the diary journal for entries stored in DIARY_DIR.

DIARY_DIR is required, if not set as environment variable or defined in the CONFIGURATION FILE.

-v, --version

Print diary version

-h, --help

Show diary help text

-d, --dir=DIARY_DIR

Directory with the journal text files

-e, --editor=EDITOR

Text editor used for opening the journal files

-f, --fmt=FMT

FMT is a custom date and file format. Change with care, because the diary reads and writes to files with file name FMT. The new FMT is only applied to newly saved entries. Existing entries with the old FMT are not automatically migrated to the new FMT and do not show up with a new FMT specifier. Consequently, a change in FMT shows an empty diary at first. Rename all files in the DIARY_DIR to migrate to a new FMT.

-F, --fmt-cmd=FMT_CMD

Journal entries are formatted with this command. If not set (default), the characters are printed to the preview screen character by character (without word wrap). For example, to enable word wrap after 75 characters, use "fmt -s" as FMT_CMD. To format markdown, use "mdcat -c" or similar, see CUSTOM FORMATTING.

-p, --no-pty

No pseudo terminal (pty) for entry preview. Only effective in combination with --fmt-cmd. If set, the output of --fmt-cmd is displayed with Ncurses. If not set (default), the result of --fmt-cmd (journal entry preview) is printed on a pseudo-terminal (pty) and not processed with Ncurses. The pty supports the ANSI escape sequences (e.g. colors, font types, etc.) of the native terminal.

-m, --no-mouse

Disable mouse, don't listen for mouse events. Mouse events are enabled by default. Without --no-mouse flag (default), native text selection and right-click in the preview window requires holding down the SHIFT key, see MOUSE EVENTS.

-r, --range=RANGE

The number of years to show before/after today. Defaults to 1 year.

-w, --weekday=DAY

First day of the week. DAY is an integer in range (0..6), interpreted as 0 or 7 = Sun, 1 = Mon, ..., 6 = Sat. If glibc is installed, the first day of the week is derived from the current locale setting ($LANG, see man locale). Without glibc, the first weekday defaults to 1 (Monday), unless specified otherwise with this option.

Navigation is done using the following vim-inspired keyboard shortcuts:

Key(s) Action
e, Enter edit current entry
d, x delete current entry
t jump to today
f jump to or find specific day
j, down go forward by 1 week
k, up go backward by 1 week
h, left go left by 1 day
l, right go right by 1 day
J go forward by 1 month
K go backward by 1 month
N go to the previous journal entry
n go to the next journal entry
g go to start of journal
G go to end of journal
s, S sync selected day/Month with CalDAV server
i import entries from .ics file
E export entries to .ics file
q quit the program

DIARY_DIR

If this variable is set to a directory that can be opened, diary will use it to store diary files. Diary files are simple text files named after their date, formatted according to FMT (see --fmt option). The format defaults to "%Y-%m-%d", which is "YYYY-MM-DD" (see man strftime). All other files different from FMT are ignored.

EDITOR

The program used to edit journal entries inside DIARY_DIR.

LANG

The default locale used to display the first day of the week, see --weekday option.

If the argument DIARY_DIR is given, diary files are read from and stored to that directory, ignoring the $DIARY_DIR environment variable, any --dir option or the dir value set in the CONFIGURATION FILE.

${PREFIX:-/usr/local/bin}/diary

The diary binary

${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg

An optional diary CONFIGURATION FILE

The diary.cfg configuration file can optionally be used to persist diary configuration. Use the "#" or ";" characters to comment lines.

Create default configuration location:

mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary

Install an example configuration file with defaults:

tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
# https://code.in0rdr.ch/diary/file/config/diary.cfg.html
# Path that holds the journal text files
#dir = ~/diary
# Number of years to show before/after todays date
range = 1
# 0 = Sunday, 1 = Monday, ..., 6 = Saturday
weekday = 1
# Date and file format, change with care
fmt = %Y-%m-%d
# Text format command for entry preview
fmt_cmd =
# Use pseudo terminal (pty) to view result of fmt_cmd
#no_pty = false
# Listen for mouse events
#no_mouse = false
# Editor to open journal files with
editor =
# CalDAV server URI
#caldav_server =
# Calendar name for CalDAV sync
#caldav_calendar =
# CalDAV server username
#caldav_username =
# CalDAV server password
#caldav_password =
# OAuth command to fetch access token. For example, "oama access"
#oauth_eval_cmd =
EOF

To copy the sample file from the source repository:

cp config/diary.cfg ${XDG_CONFIG_HOME:-~/.config}/diary/

The file "${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg" should adhere to a basic "key = value" format. The value is read until the end of the line '\n'. Lines can be commented with the special characters "#"or ";".

The following configuration keys are currently supported:

Command Line Option Config Key Example Config Value Default Config Value Description
"--dir", "-d", or first non-option argument dir ~/diary n/a Diary directory. Path that holds the journal text files. If unset, defaults to environment variable "$DIARY_DIR".
"--editor" or "-e" editor vim (empty) Editor to open journal files with. If unset, defaults to environment variable "$EDITOR". If no editor is provided, the diary is opened read-only.
"--fmt" or "-f" fmt %d_%b_%y %Y-%m-%d Date format and file name for the files inside the "dir". For the format specifiers, see "man strftime". Be careful: If you change this, you might no longer find your existing diary entries, because the diary assumes to find the journal files under another file name. Hence, a change in FMT shows an empty diary, at first. Rename all files in the DIARY_DIR to migrate to a new FMT.
"--fmt-cmd" or "-F" fmt_cmd "fmt -w75 -s", "mdcat -c" or "mdcat" (empty) Journal entries are formatted with this command. If not set (default), the characters are printed to the preview screen character by character (without word wrap). For example, to enable word wrap after 75 characters, use "fmt -s" as FMT_CMD. See also [Custom Formatting](#Custom-Formatting).
"--no-pty" or "-p" no_pty "true" false (or 0) No pseudo terminal (pty) for entry preview. Only effective in combination with "--fmt-cmd". If set to true (or 1), the output of "--fmt-cmd" is displayed with Ncurses. If set to false (or 0), the result of "--fmt-cmd" (journal entry preview) is printed on a pseudo-terminal (pty) and not processed with Ncurses. The pty supports the ANSI escape sequences (e.g. colors, font types, etc.) of the native terminal.
"--no-mouse" or "-m" no_mouse "true" false (or 0) Don't listen for MOUSE EVENTS. With no_mouse=0 (default), native text selection and right-click in the preview window requires holding down the "SHIFT" key.
"--range" or "-r" range 10 1 Number of years to show before/after todays date
"--weekday" or "-w" weekday 0 1 First weekday, "7" = Sunday, "1" = Monday, ..., "6" = Saturday. Use "7" (or "0") to display week beginning at Sunday ("S-M-T-W-T-F-S"), or "1" for "M-T-W-T-F-S-S". If "glibc" is installed, the first day of the week is derived from the current locale setting ("$LANG", see "man locale"). Without "glibc", the first weekday defaults to 1 (Monday), unless specified otherwise with this option.
n/a caldav_server Google calendar "https://apidata.googleusercontent.com/caldav/v2", Yahoo calendar "https://caldav.calendar.yahoo.com", GMX "https://caldav.gmx.net" or other CalDAV compatible provider. (empty) CalDAV server for CALDAV SYNC (required).
n/a caldav_calendar diary (empty) Calendar name for CALDAV SYNC (required).
n/a caldav_username (empty) CalDAV server username for CALDAV SYNC (optional).
n/a caldav_password (empty) CalDAV server password for CALDAV SYNC (optional).
n/a oauth_eval_cmd "oama access <email>" or "pass" (empty) OAuth command to fetch access token for CALDAV SYNC (optional).

The preview of the journal entries can be processed with a custom --fmt-cmd. The result of this formatting command is printed to a pseudo-terminal (pty) by default. This behavior can be changed with the --no-pty flag. The output processed on the pty (without Ncurses) includes all ANSI escape characters supported by the terminal (colors, font types, etc.). Thus, formatters like "fmt", or any "cat like program" ("mdcat" to process Markdown) can be plugged in for --fmt-cmd.

Mouse events are listened for by default (no_mouse=false configuration). This behavior can be disabled with the --no-mouse flag or in the CONFIGURATION FILE (no_mouse=true). With no_mouse=false (default), use the SHIFT key for native text selection and right-click in the preview window.

The import functionality can be triggered by pressing i and expects a path to an ics file. Files in the DIARY_DIR are overwritten with the entries from the imported ics file.

The export functionality can be triggered by pressing E and asks for a file path to an ics file for storing the journal entries. The ics file will be created if it does not exist. Existing ics files are overwritten.

The journal files can be synced via CalDAV by pressing s. Pressing S syncs all journal entries of the active month.

The most recently modified entry is considered up to date and is automatically replaced on the remote side. If the remote file is more recent, the local file can be replaced with the remote content after confirmation.

No sync is performed, when both files (local/remote) have the same modification timestamp or no files exists on the server and on disk at all (i.e., no entry for that date).

The diary creates a full-day calendar entry. It's advised to use a separate calendar for syncing purposes and not to have multiple events for a day on the remote calendar. The diary only considers the first event of a given day.

The calender for synchronization can be defined with the configuration key "caldav_calendar". This key is empty by default. It is required to configure at least following parameters in the CONFIGURATION FILE:

In addition, it is required to specifiy either "caldav_username" and "caldav_password" for basicauth (takes precedence) OR the "oauth_eval_cmd" to retreive an OAuth access token from a password manager or tool that prints the token to stdout. Leave username/password empty if you intend to use OAuth ("oauth_eval_cmd").

Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server. Other CalDAV servers and APIs that are secured with OAuth2 might work as well (untested).

Use the EXPORT/IMPORT functionality for more batch oriented processing. Making a network request and deciding the most recently modified entry (local/remote) takes quite some time for large batches.

To synchronize with the Google calendar, it is required to setup a project in the cloud console and enable the CalDAV API (not the Google Calendar API):

https://console.cloud.google.com/apis/api/caldav.googleapis.com

The Google Calendar CalDAV API is protected with OAuth2:

https://developers.google.com/identity/protocols/oauth2

The "application", the "consent screen" and the "credentials" (client id and secret) need to be defined in the Google cloud console. Client id and secret should be stored in an utility application that can fetch and refresh the OAuth access token (e.g., "oama"). The command to access the access token ("oauth_eval_cmd") should be configured in the CONFIGURATION FILE.

The application requires two OAuth2 scopes (https://developers.google.com/calendar/api/auth) for CalDAV requests:

The user is asked for consent during the first CALDAV SYNC.

The default variables, for instance, for the configuration variables "editor", "dir" and "weekday", are populated with values in the following order, where earlier entries are overwritten by subsequent ones if they exist:

Description
1 No default for DIARY_DIR. Defaults for "range", "weekday", "fmt" and "editor" are provided in "diary.h". If EDITOR is unset and no editor is provided in the CONFIGURATION FILE or --editor option, the diary works read-only. Journal files cannot be opened. If DIARY_DIR is not provided, the diary won't open.
2 CONFIGURATION FILE (empty default for "editor", no default for "dir")
3 Environment variables $DIARY_DIR, $EDITOR and $LANG for locale ("weekday")
4 Option arguments, see section OPTIONS
5 First non-option argument is interpreted as DIARY_DIR

If glibc is installed, the first weekday defaults to the locale defined in the current shell environment ($LANG, see man locale), unless specified otherwise with the --weekday option.

Start with weekday=3(Wed), overrule any other configuration value:

diary -w3

Start with glibc derived weekday=1, regardless of weekday in config file:

LANG=de_CH diary

If glibc is installed, start with glibc derived base date (weekday=0):

LANG= diary

Disable environment variable, default to value from config file:

unset LANG

Start with weekday default from config file, if available:

diary

Remove config file:

rm ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg

Start with weekday default value from source code (1=Mon):

diary

Contributions are always welcome! All source code is available at https://code.in0rdr.ch/diary.

For question and support visit https://web.libera.chat/gamja/#p0c.

MIT License, https://code.in0rdr.ch/diary/file/LICENSE.html

2024-09-14