Keeping your finances at check with Ledger

matousdzivjak@gmail.com (Matouš Dzivjak) — Wed, 19 Feb 2020 00:00:00 +0000

For the last ~~three months~~ year, I have been keeping track of all my expenses and income using Ledger, and it slowly turned into a little obsession of mine. Here’s my take on what ledger is, how to keep one, and why you need one.

What is Ledger

Ledger is a double entry accounting system that is accessed from a command line and kept in simple text files. This is a lot of words for introduction, but all the terms will be explained in the following paragraphs. For now, all you need to know is that this is one of many ways of bookkeeping - recording of financial transactions. And that thanks to ledger, you will be able to know how much you are spending, on what, and where your money lies.

Double Entry accounting

In accounting, everything is based on accounts. An account is every type of expense, income, or a place that holds any monetary value. In double entry accounting each transaction is recorded as a flow between at least two accounts and it is required for the total amount removed from accounts to equal to the total amount added. This is a partial check that every transaction was correctly recorded, and no money was lost in the process. In practice, it means that adding 1000$ in one place (account) requires you to remove 1000$ from another place. The consequence of this is that the balance of all accounts is always zero.

For example, buying groceries for 42$ will be recorded as moving 42$ from Credit Card to Groceries account. In the same way, receiving 2000$ salary means a flow of 2000$ from account Salary to account Bank. While the names of the accounts are entirely up to you there are certain naming conventions. In general, you would have the following main accounts:

Expenses - where the money goes
Income - where the money comes from
Assets - where money sits
Liabilities - money you owe
Equity - the real value of your property

You can add further levels to the accounts as detailed as you need, for example, Expenses -> Fun -> Tickets -> Concerts.

Ledger

Ledger is a command line tool for double-entry accounting. It is an extremely versatile tool that takes some time to master but once learned it can be used seamlessly for both personal and professional accounting.

Documentation for ledger can be found at https://www.ledger-cli.org/ in pdf or html format. There’s also awesome Getting Started With Ledger tutorial by Rolf Schröder & Contributors where I took a lot of inspiration from, and that might help you get started. Finally, if you want just a brief introduction and want to learn the rest as you go, you can quickly scrim through Ledger CLI cheatsheet.

Working with Ledger

Working with Ledger consists of two distinct actions: updating the list of transactions in your journal file and using the ledger tool to view and interpret the recorded transactions. Ledger provides you with a set of tools to analyze and filter out the transactions recorded in your ledger files.

Following the groceries example from an introduction to the double entry accounting the transaction recorded in your journal file would look like this:

2020/04/14 Groceries
  Expenses:Groceries  $42
  Assets:Checking  $-42

Each transaction starts with a date and title of the transaction. The heading is followed by two or more lines of accounts involved in the transaction with the amount of money moved from or into the account. Lines with accounts (postings) start with whitespace, and the amount is separated by at least two whitespaces from the account. Two spaces are required because the account name itself can contain a space, for example, Expenses:Car Insurance or Expenses:Food and Drinks. The amount must sum up to zero (otherwise, it wouldn’t be a valid double entry accounting transaction). Ledger can calculate the appropriate amount for the last account for you so it would be valid and more comfortable to write:

2020/04/14 Groceries
  Expenses:Groceries  $42
  Assets:Checking

The journal file consists of transactions such as the previous one and some optional metadata. Following are some more illustrative examples to help get you started:

; Set up your initial state using opening balances
; This will be your first transaction
; (assuming you are not starting with zero money).
; '*' means that the transaction is cleared
; e.g., the money was moved from one account to the other.
2020/04/14 * Opening Balance
  Assets:Checking  $1490
  Assets:Savings  $3220
  Liabilities:Loan  $200
  Equity:Opening Balances

; Salary comes from your employer to your checking account.
2020/04/15 * Salary
  Assets:Checking  $1330
  Income:Salary

; Withdrawal means moving money from your checking account to cash.
2020/04/16 * ATM withdrawal
  Assets:Cash  $40
  Assets:Checking

; Payig for beer by cash.
2020/04/16 * The Pub
  Expenses:Fun:Beers  $12
  Assets:Cash

; Paying for your friend's beer because he doesn't have money.
2020/04/17 * The Pub
  Assets:Reimbursements  $8 ; Payee: Friends Name
  Assets:Cash

...

We will explain all the concepts more in-depth later on. Now let’s get started with ledger to make some sense of our transactions.

Installing Ledger

To get started with Ledger, first install it on your device. You can find everything on Ledgers download page.

MacOS

To install ledger or MacOS simply run

brew install ledger

Linux & BSD

Go to Ledger Cli Download Page and download the latest version of binary for your distribution.

Windows

It’s a little bit harder to get Ledger running on windows, but the simplest way to do so is to go to Ledger Binaries Download Page and download the binary for the Windows system.

Reports

Journal is an excellent way to keep track of transactions but doesn’t give as much information about our current financial situation and insight into our spending and income. This is where the Ledger tool comes in. Ledger tool provides you with a set of commands and tools to make sense of your journal. The most used commands for reporting are balance (bal) and register (reg).

Balance

The balance report creates total balance for all transactions. The most basic usage looks like this:

$ ledger -f ledger.txt bal[ance]

        $1720.00  Assets:Checking
       $-1200.00  Equity:OpeningBalances
         $220.00  Expenses
         $133.00    Food:Groceries
         $127.00    Unknown
       $-1000.00  Income:Salary
 ---------------
               0

Ledger, of course, allows you to do plenty of things with the balance. Including but not limited to:

# Restrict by date. Use -p or --period.
$ ledger -p "last 3 months" bal
$ ledger -p "this month" bal
$ ledger -p "2020" bal

# Balance by account name
$ ledger bal Expenses
$ ledger bal Assets and Liabilities

# Show subaccounts only until certain depth
$ ledger --depth 2 bal

Register

$ ledger -f ledger.txt reg[istry]

...
2020/04/15 Some Restaurant         Expenses:Food:Lunches             $7.00         $47.20
                                   Assets:Checking                  $-7.00         $40.20
2020/04/15 Some Coffee Shop        Expenses:Food:Coffee              $6.00         $46.90
                                   Assets:Checking                  $-6.00         $40.20
2020/04/15 Groceries Shop          Expenses:Food:Groceries          $10.00         $50.00
                                   Assets:Checking                 $-10.00         $40.20
2020/04/15 My Company              Assets:Checking               $1,500.00      $1,500.00
                                   Income:Salary:Company        $-1,500.00         $40.00
2020/04/15 Rent                    Expenses:Living:Rent            $200.00        $200.00
                                   Assets:Checking:Airbank        $-200.00         $40.20

Again, ledger allows you to do much more, often in the same way as with balance command:

# Restrict by period.
$ ledger -p "feb 2020" reg

# Group by week
$ ledger reg -W

# Show weekly expenses
$ ledger reg -W -n Expenses

# Show weekly expenses as total amount
$ ledger reg -W -n Expenses

There’s much more you can do. To see the full list of flags and commands, you can use, visit the official documentation.

Keeping a Journal

The essential part of Ledger and accounting, in general, is keeping a good journal. Ledger has been designed to make that as easy as possible with its simple format and by automatically determining us much information as possible. For example, if Ledger encounters posting with an unknown account, it will create it. Or if you use commodity, that the Ledger hasn’t seen before, it will create that commodity and automatically determine how to display it (placement of currency, display precision, thousands separator, etc.) based on how you used the commodity in the journal.

While the format as simple as possible, there are still two rules that need to be followed. First is that the start of the transaction is at the first line followed by accounts indented by at least one space. Secondly, there must be at least two spaces between the account and the amount. If you don’t follow these rules Ledger will report an error and exit.

Sometimes the flexibility isn’t desired and might lead to difficulties. In order to combat inconsistency, you can define accounts and payees beforehand and ledger will print error and exit if it encounters an unknown account or payee.

; Define your accounts
account Assets
account Assets:Cash
account Expenses
account Expenses:Utilities

Use --strict flag to enable the strict mode. Strict mode will print warnings but still calculate the results, if you want to force the consistency you can use --pedantic that will cause the Ledger to exit with error on undefined accounts and commodities.

$ ledger bal --strict
Warning: "journal.dat", line 6: Unknown account ’Asets:Checking’

If you already started a journal and would like to enable the strict mode, you can find out all the accounts that you use by running $ ledger accounts. To put them into your journal, you need to prepend them with account; this can be simplified by running $ ledger accounts | awk '{print "account " $0}'.

Advanced usage

You have seen some basic usage in previous sections, here are some more advanced concepts you will encounter with Ledger accounting.

Resetting a Balance

Sometimes your ledger account balance and real account balance values diverge. This might happen, for example, if you lose track of your cash spending. To bring the ledger back to order you can simply reset the balance to its current value using the = operator and Adjustents account.

2020/04/20 Adjusting Cash
   Assets:Checking  = $20
   Equity:Adjustments

Commodities

Ledger allows you to keep track of investments and multiple currencies. Investment is anything that is not in dollars (or whatever your default currency is). In the sense of Ledger, there’s no difference between stocks and currencies; both are handled the same way. It is only recommended to put currency symbols before the value and commodity symbols after it. To allow ledger to handle multiple commodities (we will use currencies and commodities interchangeably) it must know how to convert them. This is done by defining the commodity’s value in terms of another commodity. Most often, you would specify the purchase price of the commodity at the time of transaction.

2020/04/21 Stock purchase
  Assets:Broker  10 TSLA @ $420.00
  Assets:Broker

Now at the time of sale:

2020/04/22 Stock sale
  Assets:Broker                    -10 TSLA {$420.00} @ $500.00
  Income:Capital Gains             $-800.00
  Assets:Broker                   $5,000.00 ; you can ommit this value

The {$420.00} behind TSLA stock is a lot price. Lot price means that the price of the given commodity can differ for each lot. This allows you to track multiple investments in the same currency bought and different initial prices.

Sometimes the commodities are consumed and are not meant to be sold later. In that case, you want to fix the lot price, so it stays at the same as at the purchase time.

2020/04/23 Shell
  Expenses:Gasoline  40 L {=$1.5}
  Assets:Checking

On the background, this introduces a new commodity with fixed value L {=$1.5}.

Sometimes you also want to see the values in terms of a particular commodity. For example, you might have a lot of investments going on and would like to know your current total equity in terms of dollars. This can be done using the -X (--exchange) COMMODITY flag. The Ledger will convert all the commodity values based on the latest available price it can find.

Budgeting

Budgeting is another feature of Ledger. Budgeting allows you to control your income and expenses, by reporting on how far or close your actual financial activity matches your expectations.

To get started with budgeting, you define periodic transactions at the top of your ledger file. These transactions are almost identical to any other transactions you would record except that they start by tilde (~) and have period expression instead of the payee in the title.

~ Monthly
  Expenses:Rent  $500.00
  Expenses:Food  $450.00
  Expenses:Insurance  $150.00
  Expenses:Party  $50.00
  ; other expenses
  Expenses  $200.00
  Assets:Checking

~ Yearly
  Expenses:Car:Repair  $500.00
  Assets

If you don’t know what your monthly expenses are for individual categories following command that will report your monthly average might help you:

ledger bal --monthly --average expenses

Keep in mind though that in order to get accurate estimates you need to be keeping ledger for some time.

After you define your periodic transactions in the ledger file, you create budget report by adding --budget to the command you would otherwise normally use. E.g., to check your monthly expenses compared to the budget, you would use:

ledger reg --budget --monthly ^expenses

Here’s a more restricted output of

$ ledger --budget --monthly -p "this year" reg rent
01/01/2020 - 31/01/2020            Expenses:Living:Rent         $-10.00     $-10.00
01/02/2020 - 29/02/2020            Expenses:Living:Rent          $14.00      $-4.00
01/03/2020 - 31/03/2020            Expenses:Living:Rent          $14.00      $-4.00

The first column with values tells you the difference between the budget and the actual amount spent. The second column is the final running balance and doesn’t provide much information when reporting on averages or against budget.

Examples

; Exchanging currencies in a single account
2020/04/24 * Exchange
  Revolut  €400.50 @ $0.92
  Revolut

; Paying lunch for your friend
2020/04/24 * Restaurant
  Expenses:Food:Lunches  $10
  Assets:Reimbursements  $9.50 ; Payee: My Friend
  Assets:Cash

; Getting paid back for the lunch
11/02/2020 * My Friend
  Assets:Checking  $9.50
  Assets:Reimbursements  ; Payee: My Friend

Summary

It might feel demanding and time-consuming to keep a financial journal, but the benefits overweight all the negatives. Keeping a journal provides you with enormous insight into your financial state and helps you optimize. If you want to keep your finances at check or if you are just interested in what you spend the most on, Ledger is the right tool for you.

Finance - dzx.cz