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.

-f, --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
# 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 =
# Google calendar name for CalDAV sync
#google_calendar =
# Google OAuth2 clientid and secretid
#google_clientid =
#google_secretid =
# Google OAuth2 tokenfile
#google_tokenfile = ~/.diary-token
EOF

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

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.

Currently, only the Google Calendar is supported as remote provider. Please open an [issue](https://codeberg.org/in0rdr/diary/issues) to implement support for additional remote calendar servers.

The calender for synchronization can be defined with the configuration key "google_calendar", see CONFIGURATION FILE. This key is empty by default.

Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server.

The Google Calendar CalDAV API is protected with OAuth2:

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

The credentials and the consent screen can be redefined at compile time (export "GOOGLE_OAUTH_CLIENT_ID"/"GOOGLE_OAUTH_CLIENT_SECRET" to environment) or during runtime with the keys "google_clientid"/"google_secretid" in the CONFIGURATION FILE. The token used to authenticate with the Google API is stored in the file specified by "google_tokenfile" and renewed automatically.

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

1."https://www.googleapis.com/auth/calendar": read/write access to Calendars - required to discover the unique hyperlink/URI for the calendar specified by config key "google_calendar"
2."https://www.googleapis.com/auth/calendar.events.owned": read/write access to Events owned by the user - allows diary to create/read/update/delete events in "google_calendar"

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://codeberg.org/in0rdr/diary.

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

•Andreas Gruhler
•Matthias Beyer
•Johnathan Jenkins
•Yu-Jie Lin
•Balduin Dettling
•Avindra Goolcharan
•Oliver Blanthorn
•Jonny Burger

MIT License, https://codeberg.org/in0rdr/diary/raw/branch/master/LICENSE

2022-01-17