diary-manager: simple command-line tool and Emacs package for
managing diary entries.
TL;DR
diary-manager is a way for you to maintain a collection of daily
diary entries. It comes with a command-line tool and an Emacs package;
both expose the same functionality. You can install the command-line
tool with Pip:
$ pip3 install git+https://github.com/raxod502/diary-manager.git
You can install the Emacs package with straight.el:
(straight-use-package 'diary-manager)
To get started, create a directory to hold your diary entries. You can
put it in a Git repository if you want a version-controlled diary. For
the command-line tool, export the environment variable
$DIARY_LOCATION to this directory. The Emacs package will use this
environment variable by default, but you can also set the Emacs user
option diary-manager-location.
Using the command-line tool, make a diary entry for the current day as follows:
$ diary
This will open the editor configured in the environment variable
$DIARY_EDITOR, or $EDITOR, or as a fallback vi(1). When you are
finished, save the file and exit your editor. If your
$DIARY_LOCATION is in a Git repository, a commit will automatically
be created.
Using the Emacs package, make a diary entry for the current day as follows:
M-x diary-manager-edit
When you are finished, press C-c C-c to save the entry, making a
commit if $DIARY_LOCATION is in a Git repository, and kill the
buffer.
Command-line tool
Installation
First, you will need to install Python 3 and Pip. Then, you may run the following command to install the command-line tool:
$ pip3 install git+https://github.com/raxod502/diary-manager.git
This will install a binary named diary.
Usage
The commands are mostly self-explanatory:
usage:
diary ls
diary [ edit ] [ <date> ]
diary rm [ <date> ]
diary mv [ <old-date> ] <new-date>
diary cp [ <old-date> ] <new-date>
diary run [ <shell-command> ... ]
diary git [ <git-args> ... ]
diary help
date format:
[+-]<number-of-days>
<day-of-month>
<month>-<day-of-month>
<year>-<month>-<day-of-month>
If a date is omitted, it defaults to the current date. Otherwise, you can specify an offset in days from the current date, or give a full or partial date in year-month-day format. (Partial dates are interpreted as dates in the past; if you wish to specify a future date, either give a full date or use an offset.)
diary run and diary git just change working directory to
$DIARY_LOCATION and then run the command provided.
Configuration
Before doing anything, you must set $DIARY_LOCATION to an existing
directory, which will hold your diary entries.
In this directory, the filenames of entries are determined by
concatenating the date and an extension. The date is formatted using
strftime with $DIARY_DATE_FORMAT (defaults to %Y-%m-%d-%a). The
extension is given by $DIARY_ENTRY_EXTENSION (defaults to .md).
Entries are edited in $DIARY_EDITOR, $EDITOR, or vi(1) in
decreasing order of preference.
Emacs package
Installation
diary-manager is available on MELPA. The easiest way to
install it is using straight.el:
(straight-use-package 'diary-manager)
However, you may install diary-manager using any other Emacs package
manager if you prefer.
Usage
The commands are mostly self-explanatory:
M-x diary-manager-editM-x diary-manager-find-fileM-x diary-manager-edit-modeM-x diary-manager-removeM-x diary-manager-moveM-x diary-manager-copyM-x diary-manager-browse
The equivalent to the command-line tool's diary edit is M-x diary-manager-edit. This requires $DIARY_LOCATION or
diary-manager-location to be set. However, you can also edit an
arbitrary file as a diary entry using M-x diary-manager-find-file. In fact, you can enable M-x diary-manager-edit-mode from any buffer. This is probably not very
useful in most cases, however.
M-x diary-manager-browse opens Dired on diary-manager-location.
Configuration
The same environment variables are used, but they may be overridden by setting Emacs Lisp variables:
$DIARY_LOCATIONbecomesdiary-manager-location$DIARY_DATE_FORMATbecomesdiary-manager-date-format$DIARY_ENTRY_EXTENSIONbecomesdiary-manager-entry-extension
If you don't change the extension from .md, you will probably want
to install the package markdown-mode. This can be done
with straight.el:
(straight-use-package 'markdown-mode)
Contributor guide
Please see the contributor guide for my projects.
To work on the command-line tool, start by creating a virtualenv and then run
$ pip install -e .
from inside this repository. That will install a diary binary to
your virtualenv, which automatically picks up changes to the diary
script in this repository.
To work on the Emacs package, just install it via straight.el and
hack away. Changes to diary-manager.el will take effect without
further intervention.
FAQ
How can I encrypt my diary entries?
The easiest way is to use Emacs with EasyPG Assistant. Start by
creating a GPG key. In your $DIARY_LOCATION, create a file called
.dir-locals.el with the following contents (where <your key>
matches your GPG key; to encrypt to multiple keys instead just use a
list of strings instead of a single string):
((nil . ((epa-file-encrypt-to . "<your key>"))))
Use the following configuration for diary-manager:
$ export DIARY_EDITOR='emacsclient --alternate-editor= -nw'
$ export DIARY_ENTRY_EXTENSION='.md.gpg'
How is this different from diary-lib?
diary-lib is a package which comes bundled with
Emacs. Org has integration with this package.
The word "diary" can mean either an appointment book, or a personal
journal. diary-lib provides a way to keep an appointment book, while
diary-manager provides a way to keep a personal journal.
diary-libhas all diary entries in the same file, whilediary-manageruses a separate file for each entry.diary-libhas specific support for entering and processing structured data relating to appointments and calendar events, whereasdiary-managerallows you to enter free-form text with no special features.diary-libis approximately 2,500 lines of code, anddiary-manageris approximately 600.