Accounting or bookkeeping may look like black magic to nonprofessionals, but its most basic forms are less obscure than you might think. A good accounting system can save money, trouble, and time – even if you are just trying to get your personal finances under control. In this tutorial, I will explain a simple accounting technique, plain text accounting (PTA), and introduce you to hledger, one of the most popular open source PTA tools.

What Is PTA?

In double-entry accounting, every change in the state of the system is a dated movement of money (or whatever else is being accounted for) between at least one source and one destination, and the sum of all those movements equals zero. Double-entry accounting has been around for centuries because its "balanced" transactions are a great, self-enforcing, easy-to-code way to guarantee that no money ever enters or leaves the system unexplained. In double-entry accounting, money is usually inside three main types of accounts: assets (what you own), liabilities (what you owe), and equity, plus two other categories devoted to revenues and expenses. Each account can be subdivided in multiple levels of sub-accounts according to your needs.

In business, equity, more or less, is defined as every stakeholder's initial contributions to the company, from money to office space to machinery, and what the stakeholder could potentially get back upon leaving the company or the company shutting down. In personal accounting, equity represents whatever "wealth" you have when you start accounting that doesn't belong in the other four top-level categories (assets, liabilities, revenues, and expenses). In practice, as far as personal accounting for most people is concerned, equity could be little more than an initial configuration parameter that must be defined somehow, but has little or no impact on what happens next.

PTA, a form of double-entry accounting, stores all data in a human-readable format inside plain text files that you can edit with normal text editors or simple shell scripts. Plain text and scripts might seem old-fashioned, but, according to PTA proponents, that is part of the point. Today's spreadsheets and other financial tools store data in arcane formats that are often proprietary. Even if the data is theoretically in an open format, you'll need sophisticated software to read and modify it.

On the other hand, if your private financial data is in plain text that you can manage entirely on your computer, it is much easier to protect the data from vendor lock-in and other external treats. Plain text, human-readable files are easy to convert and reuse based on your needs. They are also much easier to protect and recover from user errors, even with multiple people working on the same data, because you can store the files in any revision-control system: No matter how many mistakes you or your partners make, you can always recover the original data – you'll even know who made the changes and when.

Finally, plain text is much easier to import or export to any format, often automatically. You'll also find it easier to automate or integrate PTA with other systems. Indeed, in some cases, PTA command-line tools might be the only feasible way to clean up and convert old accounting files to a format usable by your preferred accounting software. The same flexibility is also useful in educational settings to generate reports for class tests or demos.

The PTA Ecosystem

At time of writing, the PTA portal [1] lists scores of PTA tools. The most popular open source PTA tools are Ledger, Beancount, and hledger. Ledger is the original PTA tool, while Beancount, which is customizable with Python, is the best suited for investing and trading. In this article, I will cover the third option, hledger [2], because it is very flexible and fast, making it a good choice for PTA beginners.

The multiplatform hledger can be used from a phone, and it supports multiple currencies and direct download and conversion of some bank statements. It handles multiple accounts with multiple currencies; can generate multi-period balance sheets, income statements, and cashflow reports; and can convert data to HTML, CSV, JSON, or SQL formats. There is also a Haskell-based software library to extend or integrate hledger with scripts and third-party applications.

Like most other PTA tools, hledger reads and writes data to and from one or more accounting journals and generates reports according to the user's requests. An accounting journal (journal for short) is simply a plain text file that contains the initial conditions of each account and all its transactions, as well as other configuration parameters.

When starting out with PTA, a single journal, with transactions strictly ordered by date, should be enough. Eventually, however, storing everything in one file will slow down hledger enough to be noticeable, and you will discover that reports are less readable. In most cases, you don't need to load five years worth of transactions every time you just want to see (or edit) how much you spent on groceries last week. With hledger's ability to support multiple journals, you have the option of keeping one journal for work and one for personal expenses. Other options include one journal per year or one for every currency you need to manage.

Inside a journal, data can be in several formats, but the default format is very simple. As I'll demonstrate later, the default format might be the only one you ever need. Every hledger journal must have a header that defines when accounting begins and each account's name and initial balance. As an example, Listing 1 shows the header of the journal file I created specifically for this tutorial.

2020-01-01 opening balances as of this date
  assets:bank             E-2543.33
  assets:cash             E100
  liabilities:creditcard  E0; Hi, I am a comment
  equity:opening/closing balances

I modeled Listing 1 after the sample template in hledger's official documentation, changing just the initial start date and the names of all the assets I wanted to monitor (which I assume are the same for most people): assets:bank for my bank balance and expenses paid with the related debit card or wire transfer, assets:cash for cash expenses, and liabilities:creditcard for expenses paid by credit card.

In this tutorial, while the account and sub-account names are taken from my actual journals, all the transaction amounts were deliberately replaced with random values to introduce errors. In Listing 1, you should note that money amounts must have a currency prefix (E for euro), there must be at least two spaces before each amount, and everything after a semicolon is a comment. Following the header in Listing 1, a single transaction might look like this:

2015/10/16 bought food
  expenses:food.  E100
  assets:cash

The resulting transaction has just a date, a description, and a declaration of the corresponding money movements, in double-entry format: In this example, EUR100 went into the sub-account expenses:food, coming from assets:cash. You do not need to write -100 after assets:cash, because hledger will automatically assume that. If instead I had paid EUR20 cash and put the remainder on my credit card, the transaction would have three movement lines, not two, to make hledger accept the transaction:

expenses:groceries  E100
assets:cash  E-20
liabilities:creditcard  E-80

Apart from this, you just need to set a time interval for hledger to analyze using "period expressions." How you pass a period expression to hledger depends on how you use it. Listing 2 shows several period expression formats. If the beginning and ending dates are in the current year, you can omit the year. Periods from the beginning of one month to the end of another can be written as simply as "march-november". You can also specify just the beginning or end of a period, as in "from 2021/01/01" or "to 2023". Dates aside, a period expression can also begin with a report interval (e.g., "weekly from 2023/03/01 to 2023/05/15" or "monthly in 2008").

"from 2023/03/01 to 2023/05/15"
"2023/03/01 2023/05/15"
2023/03/01to2023/05/15
2023/03/01..2023/05/15
2023/03/01-2023/05/15

Installing and Using hledger

On Linux, hledger is available as a binary package for all the most common distributions, but to run the latest stable version (version 1.33.1 at time of writing) you must download the corresponding ZIP archive from the website, unpack it, and then move the unzipped files to a folder in your $PATH (e.g. /usr/local/bin):

> unzip hledger-linux-x64.zip
> tar tf hledger-linux-x64.tar
> mv hledger hledger-ui hledger-web /usr/local/bin

The three statically linked executable files in the last command above are hledger's main advantage: You get three different interfaces. I will describe each interface, before showing how to import data into hledger and discussing some general issues.