So what exactly is hledger? Basically, it’s a program that parses a plain-text journal file and uses it to generate financial reports. The journal itself is formatted for double-entry accounting, i.e. every credit must have a corresponding debit. The core hledger program operates exclusively from a terminal command line, although there are other interfaces available.
You can use any text editor to create or modify the journal. (I use nano or gedit personally.) There is also a built-in command called
hledger add that lets you create a new journal or add entries to an existing file. This command, however, cannot be used to edit or modify journal entries; that can only be done with a text editor.
By default, hledger looks for the journal in your home directory at
~/.hledger.journal. But you can use any file as the journal by adding the
-f flag. Say you have a journal file located at
~/Documents/sample.journal. To have hledger print out all of the entries in this journal you would enter:
$ hledger print -f ~/Documents/sample.journal
You’ll note that
hledger must be followed by a command. If you enter
hledger alone, you will get a help message with a list of available commands. In addition to
$ hledger accounts # prints a list of accounts $ hledger balancesheet # prints a list of accounts and balances $ hledger register # prints a list of transactions and running balances
Most of these commands also have abbreviations, such as
hledger bal for
hledger balance and
hledger bs for
In working with the journal itself, there are a few basic formatting rules that must be followed:
- Each entry begins with a non-indented date starting with the four-digit year (i.e., 2017/07/30);
- After the date, and staying on the same line, is a space followed by a description of the journal entry;
- There are at least two additional lines that are indented, each containing an account name and a transaction amount; and
- There must be at least two spaces between the account name and transaction amount.
This last rule is critical. Here is an example of a correctly formatted journal entry:
2017/07/30 Sample entry assets 100 equity -100
Here is an incorrect example:
2017/07/30 Incorrect entry assets 100 equity -100
With the second example, hledger will read the entry as an account called
assets 100 rather than an
assets account with a $100 debit.
Hledger is written in the Haskell programming language. The best way I’ve found to install the program is through Haskell Stack, which is the official builder for multi-package Haskell projects. You can learn more about Stack and other installation options through the hledger download page.
Some Linux distributions also maintain a pre-compiled hledger package. These packages are often several versions behind the current release. Debian, for instance, currently has hledger 1.0.1 in its stable repository, while the most recent upstream release, as of this writing, is hledger 1.3.
For purposes of this blog, I try to stay on the most current release. I have hledger 1.3 installed (via Haskell Stack) on a ThinkPad T420 running Solus, an independent Linux-based operating system.
Simon Michael originally developed hledger as a Haskell-based reimplementation of Ledger, a plain-text accounting tool first released by John Wiegley in 2003. The hledger documentation offers a detailed explanation of the differences between the two programs.
While this blog will focus on hledger, its journal files should also work in Ledger. (Ledger does not have an
add command, however, so you need to create journals exclusively with a text editor.) Since Ledger is more widely available through Linux and BSD package managers, you may want to use it if for some reason you are unable to install hledger.