This episode is freely available thanks to the support of our subscribers

Subscribers get exclusive access to new and all previous subscriber-only episodes, video downloads, and 30% discount for team members. Become a Subscriber

We give a quick introduction to Ledger itself and to the Mac app we're going to build.

0:13 This episode is a slight divergence from the regular episodes because we're introducing a new project. This is to provide some context. Afterward, we'll continue with the regular episodes including live coding.

Showing Ledger

0:25 We made a clone of Ledger in Swift. Ledger is an app we use for all our bookkeeping. Our clone is a Mac GUI app, whereas the original app is on the command line. The cool thing about Ledger is that it operates on a simple text file, which suits our workflow perfectly. It's like Markdown for bookkeeping. We have the file under version control, which is easy for collaborating, and this also makes it possible to see the history of our bookkeeping.

1:08 We wanted to write a GUI app that has more visual features than those the command line app allows. This is because things like searching and highlighting sometimes work better in a GUI.

1:17 Let's show how the basic principles work. A Ledger file is a simple text file. If we want to add a new entry, we begin by writing down the date and the title. Then we can add two postings. For the first posting, we write down the account name and the amount. Next, we have to write down where the money came from, i.e. which account it was paid from. We add another posting on a separate line and specify Assets:Checking as the account and -50 USD as the amount.

2:08 This is one of the most essential things about Ledger: it uses double-entry bookkeeping, so all the postings in a transaction have to add up to zero. This is also something we really like: there's a check built in. We learned that double-entry bookkeeping isn't complicated, and as a bonus, it's very useful; it's like having a type system for your bookkeeping.

A Command Line App

2:39 Once we have a file with a single transaction, we can switch to the Terminal, run ledger on this file, and display the balance. Here we get the overview of all our accounts (in this case, we only have two), and all the amounts are summed up.

3:06 The balance view is more interesting once we have multiple transactions. To demonstrate this, let's add a second transaction that records a payment for a contracting gig. The income is 1000 USD, and it flows into the checking account. If we save this file and rerun our balance command, we can see that the amounts for each account have been summed up into a total. The checking account now contains 950 USD (the sum of -50 USD and 1000 USD). This should correspond with the actual checking account balance.

3:58 We've now shown the basic principle of Ledger. However, there are also some convenience features. For example, we don't have to keep repeating ourselves: we can leave off one of the amounts and Ledger will infer what the other amount is. In doing so, we can see we still have the same balance. We can also look at a second report that Ledger can generate: the register. Here are all individual transactions and a running total, and we can see that Ledger filled in the missing amounts.

Auto-Balancing

4:40 Another interesting thing is to show that a transaction doesn't need to have just two postings; there can be more. For example, we could add a second posting to our contracting transaction for the VAT. This helped us manage the VAT we have in Europe. The issue with VAT is that you always have a certain amount of money in your account, and you never know how much of it's the VAT amount that you have to send to the authorities at some point. To deal with this, we create another account, Liabilities:VAT, and specify 190 USD as the amount. We can now run the balance command again and immediately see how much VAT we still have lying around.

5:37 Having such a good overview is what made us really happy with Ledger. Instead of looking at one big number on the account, we can see where the money needs to go, who we still need to pay, and what all the numbers mean.

The GUI App

5:56 So let's look at our GUI app now, which is similar to the command-line version. On the left-hand side, we show the account tree with the totals for each account. On the right-hand side, we show a register in reverse order. The app allows us to do a few cool things. For example, we can select an account and filter out all the transactions for that account. Likewise, we can filter by using the search bar.

6:42 We designed the app in an extensible way, and as such, there are some features we haven't shown yet. It's very much a work in progress and not a finished app. We're working on it, and there are a lot of interesting topics within this project. For example: first we had to parse a Ledger file into something more structural. Then we needed to evaluate all the postings and transactions in that structure. Finally, we needed to present this in a GUI. To do that, we had to build the tree structure on the left, and we had to connect all the view controllers. We'll cover all these topics and more in upcoming episodes.