Ledger is a double-entry accounting application. It defines a simple
plain text file format for writing out your accounts, and the ledger command
parses the file and produces reports. An entry looks something like this:
2018-07-04 Critical Mass
expenses:games £50.00
assets:main
This entry describes me spending £50.00 in a shop called Critical Mass. If an entry contains a single line with no amount listed, then ledger will calculate it to be the remaining balance. All entries in ledger must balance to zero, and so this one is £-50.00.
If I save this into a file I can then use the balance subcommand to check that I’ve entered everything correctly and tell me how much I have in my accounts:
$ ledger --file ~/accounts balance
£-50.00 assets:savings
£50.00 expenses:games
--------------------
0
If any entry doesn’t balance, then ledger will refuse to produce a report:
$ ledger --file ~/accounts balance
While parsing file "/home/dan/accounts", line 3:
While balancing transaction from "/home/dan/accounts", lines 1-3:
> 2018-07-04 Game Shop
> expenses:games £50.00
> assets:main £-45.00
Unbalanced remainder is:
£5.00
Amount to balance against:
£50.00
Error: Transaction does not balance
You can also make typing this a little quicker with the ~/.ledgerrc
configuration file, and the shorthand subcommand syntax:
$ cat ~/.ledgerrc
--file ~/accounts
$ ledger b
£-50.00 assets:main
£50.00 expenses:games
--------------------
0
Since the accounts have no starting balances though this transaction makes it
look like I’m now in debt. I use an account called equity:opening balance to
magically produce the money from nothing:
2018-07-04 Opening Balance
assets:main £1000.00
assets:savings £1000.00
equity:opening balance
Now when I run the balance command again ledger tells me how much I have left in my main account, and how much I’ve spent so far:
$ ledger b
£1950.00 assets
£950.00 main
£1000.00 savings
£-2000.00 equity:opening balance
£50.00 expenses:games
--------------------
0
When I get paid, I use an income account to enter it into ledger. This account somewhat confusingly shows a negative value in all my reports. This is because I’m in effect taking money from an income and turning it into an asset. I also divide up my main account into pots, which allows me to budget for the rest of the month:
2018-07-04 Work
assets:main:electricity £100.00
assets:main:fuel £150.00
assets:main:groceries £400.00
assets:main:spending £100.00
assets:main:water £50.00
income:salary £-800.00
This means when I buy groceries, I take the money from the
assets:main:groceries account. Since the accounts are in a hierarchy, the
assets:main account will then reflect the new total balance of it’s
sub-accounts. This allows me to check that the balance in ledger matches my bank
accounts, but also allows me to keep track of a monthly budget.
Clearing entries
All the entries so far have been uncleared as far as ledger is concerned. To clear an entry, you enter an asterisk between the date and payee, like this:
2018-07-04 * Work
There are both --cleared and --uncleared options for the ledger command,
these filter the entries that are considered when producing reports. Using these
allows me to add entries for cheques, or the receipts I accumulate through the
day without them getting in the way of balancing ledger with my bank accounts.
When balancing my accounts I use the --cleared option, and to check how much
money I really have I use the --uncleared one.
Validation
There are several options to the ledger command that validate you have entered things correctly, two of them I find particularly useful:
--pedantic
Accounts, tags or commodities not previously declared
will cause errors.
--check-payees
Enable strict and pedantic checking for payees as
well as accounts, commodities and tags.
You declare payees and accounts at the start of the file like this:
payee Critical Mass
account assets:main