Introduction to Ledger

Sep 12, 2018

Getting Started with Ledger

Since changing jobs, moving states, renting an apartment, and cohabiting for the first time all in the same month, I’ve been interested in understanding how my money tends to come in and go out. There are many tools available for this, all of them with different focuses and purposes. Some are great at ‘envelope budgeting’ — putting away a fraction of each paycheck into holiday, car, and bill funds — while others try to work well with your existing bank account, or your tax agent. I’d looked at these options in the past, but their slick interfaces felt too coddling, hiding details and thereby losing the value of tracking finances in the first place.

Being comfortable with the command line, I was naturally drawn to the notion of Plain Text Accounting. This is where you create a ‘journal’ of expenses, using a form of double-entry accounting, and define cost centres where you money goes. This to me had the advantages of:

Ability to version control: I can keep this in Git so I can’t muck it up too badly;

Transferrable format: I can use more than one application to read these files, if my current one stops being maintained;

Accessible format: I can write my own tools if I want to do something unavailable today;

I spent a week playing around with the different offerings, and ultimately settled on hledger. What follows is a guide geared to using hledger, but widely applicable to other plain text accounting programmes, as the syntax is broadly similar.

Starting Out: Your First Transaction

One of the most confusing aspects of using hledger was just starting out — I had no idea how to notate existing wealth using its double-entry system. It turns out, this is straightforward. You take your equity and transfer it to your assets. If this is confusing, just do it once, consider it a magical incantation, and forget about it. You never have to think about this again.

All regular transactions have a negative and a positive line: in this instance, we ‘took’ from our equity, and we ‘gave’ to our checking and savings accounts. Similarly, when you go to the supermarket, you will ‘take’ from your wallet, and ‘give’ to your supermarket expenses account.

Journalling Your Everyday Transactions

A Single Transaction

To model a single transaction as in the supermarket, we write something similar to the following:

Transaction Notation

You may find it useful when entering transactions to store the payee’s name. This is the information before the pipe (|) in the supermarket example above. If you’d simply like a description of the transaction, omit the pipe character and simply write a description after the date.

You may also find it useful to have a distinction between ‘confirmed’ and ‘pending’ transactions. I use this for credit card authorisations, pending transactions that are yet to clear. Pending transactions are marked with an exclamation mark; confirmed transactions are marked with an asterisk.

Buying a Few Rounds (Multiple expenses at the same location on the same day)

Shares/Non-Cash assets

Structure

To keep things simple, let’s store your shares in an account just called shares. We’ll assume that there is some nominal brokerage fee, and that your keep the money to buy your shares in a separate brokerage account called cmc (after the share brokers).

Now when we run out balance statement query, we’re shown that we have $96,514.00 in assets, as well as 60 VAS shares. This is informative, but not very useful for knowing our assets on a day-to-day basis. For that, we need to know the prices of all of our shares.

Note also that I’ve added a comment — text after a semi-colon in the transaction description — that will come in handy later on.

We can introduce a lookup file which tells us the value of one VAS share at a point in time. This can be done in the one ledger file, but it can be more useful to create a new file called something like prices.ledger, and make reference to this in the original ledger file. For example, I do the following:

include ~/.prices.hledger

In the prices file, we simply assert the date the price was looked up, and how much the share is worth with:

P 2018/03/05 VAS $60.00

Useful tools

I like to retrieve end-of-day pricing for my stocks. So, I download prices at 5pm each weekday.

My crontab has the following line:

~0 17 * * 1-5 ~/bin/stocks.sh >> ~/.prices.hledger

Let’s say I have positions in the ASX’s NDQ and VAS indexes. Then my ~/bin/stocks.sh would be:

ticker.sh has been modified only slightly to retrieve prices from the Australia Yahoo! API (i.e., by setting API_ENDPOINT="https://query1.finance.yahoo.com/v7/finance/quote?lang=en-US&region=AU&corsDomain=au.finance.yahoo.com" in the script).

Useful hledger Commands

Having my end-of-day figures, I can easily run the following commands to

Estimate total share valuehledger reg tag:"shares" assets:shares -V

2018/03/05 60 Vanguard.. assets:shares $3,600.00 $3,600.00

Estimate total share value increasehledger reg tag:"shares" -V not:expenses
The total value will be the output of the last line. For example, let us assume after some time has passed, the following entry is made in the ledger:

P 2018/05/05 VAS $70.00

That is, the price of the stock VAS was $70.00 on 2018/05/05. We then run the command: hledger reg tag:"shares" -V not:expenses:

This tells us that, after costs, we have made an (unrealised and untaxed) profit of $589.00

Conclusion

Plain text accounting is a great way to simply keep track all of your expenses, but can also be used for more complicated assets, such as equities. hledger is a straightforward way to get powerful summary information once you’ve assiduously kept track of only a few transactions.

The project is still very much underway, with downloads available here, and discussion taking place here.