Home

Welcome to the hledger-mode wiki!

Introduction

Hledger mode is an emacs major mode that interacts with the plain-text accounting program hledger.

Wiki

I intend to use this space for everything related to the usage, design and implementation of ideas that I or other users find interesting.

Using Multiple Hledger Directories

If you manage various hledger directories, you can leverage dir-locals to dynamically set the hledger-jfile.

Insert the following into a .dir-locals.el file and place it within each of your hledger directories:

((nil .
      (
       (eval . (setq-local
		current-directory (expand-file-name (locate-dominating-file
						     default-directory ".dir-locals.el"))))
       (eval . (setq-local hledger-jfile (expand-file-name "main.journal"
							   current-directory)))
       )))

Additionally, to refresh the account cache, configure the following variable:

(setq hledger-invalidate-completions '(on-edit on-save on-idle))

This ensures the cache updates upon file edits, saves, or when Emacs remains idle for a period.

Design Notes

Writing a simple specification format for reports. All functions should care about manipulating these specifications and generating more complex specifications of reports. In the end, these specifications should be converted into report content in a buffer by running hledger or any other means [in case we start writing a clone in Emacs Lisp in the future, who know?].

Why is this important?

I think reports are very messy if we directly deal with the report content in a buffer. It is difficult to generate a slightly different report from an existing report if all you have is the report content and not the specification, e.g. re-generating the report with flat format accounts rather than tree-like account names.

Vanilla Emacs install with MELPA

M-x package-install hledger-mode

Spacemacs install

instructions

OSX gotchas

When installing via brew install hledger, the binaries are placed in /usr/local/bin, but when using the GUI version of Emacs that path isn't necessarily passed in at start-up. This is apparently a common issue on OSX, so a nice package called exec-path-from-shell exists to ensure the $PATH you see in, say, bash, is available to emacs.

This resolved a really frustrating issue whereby company-completion wasn't working because the shell-command-to-string function couldn't find hledger due to it being at /usr/local/bin. This resulted in the hledger-accounts-cache always being nil, and thus company had no completions to offer. Also, hledger-run-command always failed as well.