Tracking your finances with Reckon and Ledger
Tracking finances and budgeting is unsexy but is the base from which flows investing, capital, and wise use of credit. It clarifies activity, priorities, obligations, and opportunities. Making money work for you is a minor superpower. It, if you can excuse the pun, pays dividends.
And it makes most sense in your hands, rather than a SaaS or bank. Many apps and online services give financial visibility but ultimately tie you to a (paid) upgrade cycle, ecosystem, or upsell where you lack control of your financial data and insights. Most make it difficult to get your data out once it’s theirs.
You have alternatives. Let’s talk about what I use and why: Ledger teamed with Reckon . As a bonus, both open source and free (See? Saving cash already 😝).
Ledger is a plain text, command line, double entry accounting program that takes a specific file format of journals and magically transforms it into accounting reports and insight. It’s been around since 2003, and battle-hardened.
Reckon is a small Bayesian ML library that works with Ledger. It takes csv files you grab (or convert) from your bank and automagically transforms them into Ledger entries for you based on estimating the probability of which account each line should go into. Together, they minimize the time I spend tracking finances, while giving me a lot of insight. I’d estimate an hour-ish every month to keep on top of my (complex) financial life.
Why Plain Text?
Flexibility, portability, and longevity end up being the short answers. Financial companies come and go, online financial SaaSes close down, and banks are allergic to innovation and/or rarely keep your full transaction history around or available to you.
Surprisingly, I’ve been increasingly moving back to plain text as a format for holding my personal data. Sure, databases are great when you need them, but with a little scripting, plain text formats are portable, version controllable, human readable, and rarely deprecate or need massive conversion. You can also manipulate them into any format you need given a little text munging know-how. Plain text emphasizes data. And data formats are effectively standards that allow you to do a lot once you understand the semantic structure of the information. Much like I loved Taskpaper (and now org-mode) for the simple hierarchical list nature of the text, you can do the exact same thing with financial information.
But why for accounting? Go back ten years and look at your financial records. Bet you can’t, right? Your bank won’t provide them that long and your accounting or money tracking software probably can’t even parse files from that far back. OK, admittedly, less of a problem than others in your life, but it’s damn interesting to see how your financial life has changed over time (As an example, how much money I pay Apple, Amazon, and Google monthly now compared to five years ago. You’ll then understand how they became FAANGBAT. Or how much you paid in cost adjusted dollars on your car loans or similar). It’s amazingly illuminating besides providing actionable insights on your financial life. If you need more convincing, there is an entire site devoted to selling you on plain text accounting
Enter Ledger
Ledger itself is a command line program for processing text files in the ledger journal double-entry accounting format. It’s been around since 2003 and is robust and reliable. It never alters your files, so maintenance of the text journal file(s) is your responsibility. There’re web interfaces like Ledger Web for it if you are not crazy about the idea of text editing and which can give you nice web-based charts (and which preserves the same underlying ledger text file format immutably.). Frankly, it’s incredible what people have done with the format even re-implement ledger in languages such as Haskell (which has both a CLI, a UI, and web-based interface as well as good docs.).
Everything in ledger runs around double entry accounting. All money flows must balance so you will learn a teensy bit about double-entry accounting (which is handy to know for work anyhow). This will often surprise you . It can be somewhat counterintuitive at first. It’s a good primer and helps you learn basics about Finance career-wise.
If you use a text editor, Ledger has a surprising amount of support as a file format. Syntax highlighting as a minimum is supported across all major editors I checked (VS Code, vim, emacs, Sublime, Atom, Textmate) though I use emacs which has an excellent ledger-mode which gives you syntax highlighting, account auto-completion, and allows you to pull up reports in-emacs and use ledger in-editor. It also autoformats everything so the file looks nice and neat.
A ledger journal entry looks somewhat like this:
2020-01-05 Amazon
; The Moon by Oliver Morton
Expenses:Books 20.50 CAD
Liabilities:RBC Visa
That’s it. A Date, a payee, a semi-colon delimited comment, and both the taking and receiving account. In sticking with double entry accounting principles there must always be two accounts.
Technically, the entry should look like this:
2020-01-05 Amazon
; Bought The Moon
Expenses:Books 20.50 CAD
Liabilities:RBC Visa -20.50 CAD
but ledger understands the short form of entering in the values once (so does the emacs ledger mode). I use the two money amounts in manual entries only for foreign currency transactions since you’ll often have to balance out separate currencies to reconcile a transaction. As an example, transferring money between two countries:
2020-01-01 Bank Transfer to Canada
; My bank has notes like this "WWW TRANSFER 12090879870313"
Assets:Canadian bank 5000.00 CAD
Assets:Singaporean bank -5250.50 SGD
I generally charge the fees both banks shaft me with separately and only track FX losses for business accounting (note: if you’re tracking FX losses or gains you add those in as a separate account as long as the overall transaction balances. Suffice it to say, banks are hosing you on international transfers so, as a tip, consider something like Transferwise ).
When I am entering entries into the ledger journal file, I often find it helpful to have the balance report open in a split window in emacs since it will generally let me know right away if I’ve messed something up by refusing to balance or numbers get out of whack. It’s handy error checking and one of the features I like about the emacs ledger-mode.
Issuing a command once you have data in ledger to get a report looks something like this:
$ ledger -f 2020_perso.ledger bal
Where I am asking for my balance report (accounting sense) from all entries in the 2020 perso file (so everything in there). It’ll return something that look somewhat like this:
xx2,376.30 CAD
x31 RSU
xxx,960.88 SGD Assets
153.00 SGD Cash
-10,500.00 SGD Loans Outstanding
xx2,376.30 CAD CDN Savings
10,500.00 SGD Receivables
3,500.00 SGD Friend1
2,000.00 SGD Friend2
5,000.00 SGD Friend3
-x,824.39 CAD Reimbursements
x31 RSU Equity RSUs
xxx,107.88 SGD SIN Savings
xx3,233.30 CAD
-xxx,200.75 SGD
-xxx,500.00 USD Equity:Opening Balances
xx,248.43 CAD
x5,451.81 SGD Expenses
183.00 CAD
90.00 SGD Bank Fees
584.56 CAD
63.13 SGD Books
x40.00 SGD Cleaner
2,480.00 SGD Computer
The Balance report (unsurprisingly) balances; Assets must balance Liabilities plus Equity. Double entry accounting is surprisingly powerful when it comes to understanding the wheres and hows of your money. For example, when I am updating the ledger text file in emacs ledger-mode, I keep the balance report open in a split window (which updates every time I save) so I can see if I’ve made any mistakes (note: in the above example, RSU refer to equity shares I have in a company not a currency. I track my portfolio in a separate ledger. It can track any sort of commodity that you can assign value to - stocks I track in USD to keep myself sane.).
The nice thing about the reports is you can instantly see how much you’ve spent and where for the year by assigning amounts to accounts (like Expenses:Computer) which let me know that I’ve bought a single laptop this year (ahem), as well as letting me know I’ve spent way more on books than I can possibly have read in three months even including textbooks (it’s a slight problem.).
Most people do not have a good grasp on their expenses, and even fewer have a budget they adhere to (#protip Pay yourself first: Move 20%-30% of your salary into savings every month and live on 80%-60% if you can.). Let’s take a look at what sort of spending we might be able to reduce with ledger, because this is where its power shines.
Wanna take a look at your food spending? Peope are often surprised by how much they spend on food versus costs like rent or transport. How much is Delivery vs Restaurants vs Groceries each month? As long as you are tracking that in your chart of accounts
(more on that setup later), you can assign expenses to Accounts like Expenses:Food:Groceries, Expenses:Food:Delivery, Expenses:Food:Restaurants to get a sobering look at how much you could be saving if you started cooking at home more often (when not forced to from lockdown).
Let’s take a look at how you’d get Ledger to tell you that:
λ ledger -f ~/Dropbox/ledger/2020_perso.ledger -M reg "^Expenses:Food"
Will yield something like this:
2020-01m-01d - 2020-01m-31d Expenses:Food:Delivery 919.86 SGD 919.86 SGD
Expenses:Food:Groceries 214.83 SGD x,134.69 SGD
Expenses:Food:Restos x,408.28 SGD x,542.97 SGD
2020-02m-01d - 2020-02m-29d Expenses:Food:Delivery 648.58 SGD x,191.55 SGD
Expenses:Food:Groceries 469.36 SGD x,660.91 SGD
Expenses:Food:Restos x,614.13 SGD x,275.04 SGD
2020-03m-01d - 2020-03m-31d Expenses:Food:Delivery 789.22 SGD x,064.26 SGD
Expenses:Food:Groceries 695.74 SGD x,760.00 SGD
Expenses:Food:Restos x,144.99 SGD x,904.99 SGD
Here’s the kicker: this is way higher than what I had budgeted for from a daily “I spend this” estimate projections I extrapolated out for a year for my budget. Here was a huge area I could start economizing (#protip, it’s not enough to budget and do projections, you also need to track.). As weird as it sounds though, I’m really enjoying cooking at home since WFH and lockdown started. Forgot how much I missed it or the fact I used to be a passable chef (though am struggling to get back to even good again.).
And strangely looking monthly expenses, it’s not books or online services or even discretionary purchases that were the real culprits (and like most people rent, food, and transport will probably be your main areas of expenses where you might have an impact if you make changes.). Though it’s important to know what your financial goals are. For me, bending towards financial independence in a few years, that means foregoing some expenses for the sake of a better future.
Reckon - Making the machine work for you
Let’s talk about the other side of the coin of using Ledger here: updating. I can hear what you’re thinking. Wow, managing a text file looks like a lot of work. Entering in every one of those ledger entries by hand? Isn’t that what we have drop down interfaces for and importing for? Does any bank offer downloads in Ledger format?
Banks are strangely behind the times on most data fronts, but the good news is, as long as you can get a csv export from your bank, you can get your machine to enter almost everything for you. Despite the financial complexity of my life: living in one country, assets in another, and company in a complete other, I spend maybe an hour a month updating everything and figuring out where the money all goes. How?
This is where Reckon comes in . Reckon is a Ruby gem which parses csv files from your bank, learns from your current (and growing) ledger data file via Bayesian statistics ML, interactively queries you about each line, and then creates the entries for you in ledger format. It massively reduced the overhead required on administering my finances. Without it I probably would’ve given up on ledger due to the entry overhead.
If you’re on any linux based system, as long as you have ruby installed (and most people should) you are all ready to go. On OSX, I personally recommend using homebrew and installing a more modern version of ruby than may be your system default (and you should be using homebrew anyway to install what you can for command line and applications) and then brew install ruby to get the latest version of ruby.
if you have a working ruby on your system, you can install reckon with a simple:
$ gem install reckon
Reckon is surprisingly robust for something someone built to scratch their own itch and cantino deserves some major credit for building something useful and great.
Reckon takes the entries for your ledger files, learns from them, and then goes line by line through a csv file you grab from your bank and figures out probabilistically what the entry is probably for (eg. Expenses:Rent, Expenses:Entertainment, Expenses:Business:Software etc etc) and creates and writes the ledger entry for you. Bliss.
This automates the onerous maintenance part. It massively reduces the PITA aspect (I could also automate the grabbing and massaging of files from my various banks, but haven’t had time to get around to it - also they all require secure logins which makes things trickier to automate. For example, one of my banks, which I should fire them for, only allows an Excel download to see your transactions. They also stupidly provide multiple rows in a cell meaning I need to export to csv and then remove all \n within a description field. Yeesh.).
Assuming you have a decent csv file in whatever format that has a date, an amount of transaction, and a description, it is a wonder to watch Reckon rip through your financial records and do the work for oyu. Let’s walk through the standard command I would issue on the command line:
$ reckon -f ./bankX_source_mar2020.csv --currency 'SGD ' -l ~/Dropbox/ledger/2020_master.ledger -o bankX_mar2020.ledger --suffixed
The csv file needs the same basics as a ledger entry, obviously: a date, a description, and an amount are the minimums though you can force Reckon to ignore columns or recognize a particular column as the important money column (important if your bank csv download also provides, say a running balance.). See reckon --help for command line options (which are very comprehensive.).
In the example above, BankX is in Singapore so I want the file to recognize that all entries are in SGD in the file so use --currency 'SGD '. I also use the --suffixed flag to make sure reckon writes ledger entries like 1000.00 SGD rather than its default $1000.00.
The -l switch for “learning” is where all the magic happens. Point this at your main ledger file and that file gets parsed and used as the basis for the bayesian predictions that reckon makes.You will be amazed how little work you need to do besides hitting return to accept Reckon’s suggestions on which account to expense debits to. As time goes on and you get more entries, the predictions become even more accurate and you do even less work (I’ve found.). It also skips lines that are too identical to entries already in the ledger file which is handy for avoiding duplicates.
Finally, the -o flag for output tells reckon where to write the collated ledger file to. I separate out my files into source files for bank and month but there is no reason you could not write directly back to your source file or a single monthly file. I generally then copy-paste the entire output into my ledger file and do a quick once over to correct for strangeness or where I got a little too hasty on hitting return with reckon.
After it asks you about which account the csv is for, it then will run through the csv file and interactively prompt you to confirm which account you want to assign an entry to. Here’s an actual example of one of mine from the evil XLS bank with some details fuzzed for obfuscation.
+------------+-------------+-------------------------------------------------------------------+
| 2020-02-29 | -30.10 SGD | Misc DR-Debit Card DELIVEROO.COM.SG SINGAPORE 28 FEB 4359 0861709 |
+------------+-------------+-------------------------------------------------------------------+
To which account did this money go? ([account]/[q]uit/[s]kip) |Expenses:Food:Delivery|
Hit return to accept the entry and have it written to your file, or type to change the account you want it to debit to. Bliss.
Once you’ve got a high degree of confidence that Reckon is going to get its prediction right almost every time you can even run the whole thing with the --unattended flag but I find having to charge to the same vendors for different reasons (Amazon, Apple etc for entertainment versus, say software or books vs online services) makes this work less well than doing overrides in interactive mode.
Setting Up
You can save yourself rework later if you choose a robust setup for Ledger. This is what I’d recommend based on what I’ve learned over time. YMMV.
Use as Few Files as possible
Ledger can include (with an include keyword) multiple files to merge all your information together. While some setups advise doing this by account, I find this ends up being counterproductive from a complexity perspective. It’s far better to keep everything in one file if your financial life will allow it.
As advice, I’d combine accounts semantically, with one file for everything that affects your personal finances, perhaps with a separate file for a budget (so you can also track how you might change that over time), a business (if you have one, or other sources of alternative income), and any investment portfolios you might have as separate files. Keep organization as simple as possible until its no longer viable (though make siure you can record changes over time - use git or dropbox to make sure your files are versioned). If you prefer to also understand your finances in a single currency, you will also need a price file for tracking foreign exchange as well stock prices if you have a portfolio (see next section).
Comment Block to organize the file
I use big commented headers to navigate what ends up being the long ledger file I have for the year.
For example, a block header by month and account makes figuring out where entries might have gone wrong easier (90% of time, mispellings on accounts or two banks recording the same entry )
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Mar 2020 - SIN Bank Account
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
...
I also do this in the budget file to denote when I’ve got a new version of a budget and then commenting out the old one with some notes to explain why. It’s ridiculously useful when you’re looking back months from then and trying to understand your thinking.
Use suffixed currencies not $ £ € ￥ prefixed
Many countries have single prefixed symbols to denote their money. While your life now may be single-currency, longer term, if you’re the type of person to read this post, your financial life gets more complex, and you will need to include other currencies. Set yourself up right. Use suffixed ISO codes for currencies like you see in airport foreign exchange counters. Cause, well… standards. It might take getting used to but it will make international entanglements in your life easier in the future.
If you prefer to see all your finances in a single currency you can do that too, but will need to start a separate “price” file to start tracking foreign exchange on currencies. Again, this is something that is easily automated. I whipped up a small ruby program called get-FX to get foreign exchange rates from an online provider which you can write directly to a price file and operate on a cron script daily or weekly. Hands off, and keeps everything tidy and updated (I’ll rewrite it in Go at some point to be faster and asynchronous.)
Opening Balances
If you’ve never done any accounting before, you need to think about setting up files by year and then “closing” accounts at year end and opening a new ledger (as accountants do). Opening the books means thinking about what your position is at the start of each year and opening balances. Surprisingly, setting this up will avoid a lot of problems for you and let you focus on recording and understanding and actioning your finances. The key problem is getting a snapshot of your financial situation at point-in-time. Traditionally, I do this on the first day of the new year (but rollover is easy if you’ve been tracking).
You open up your account with Opening Balances. Note that you will need to have entries in each currency and account if you’ve got a multi-currency life.
20xx-01-01 Opening Balance
Equity:Opening Balances -xxx,200.75 CAD
Equity:Opening Balances xxx,233.30 SGD
Equity:Opening Balances -xxx,500.00 USD
Assets:SIN Savings XXX,160.59 SGD
Assets:CDN Savings xxx,239.83 CAD
Assets:RSUs x,250 RSU @ 255.00 USD
Assets:Reimbursements x,040.16 SGD
Assets:Cash 150.00 SGD
Assets:Loans Outstanding -xx,000 SGD
Assets:Receivables:Fin1 x,000.00 SGD
Assets:Receivables:Fin2 x,500.00 SGD
Assets:Receivables:Fin3 x,500.00 SGD
Liabilities:Visa -xx,256.00 CAD
Liabilities:Credit Line -x,217.13 CAD
... etc
I’ve not bothered with Accounts like Mortgages or Home Equity for brevity. This should give you an idea of how to set up after looking at your financial accounts. As a tip, do not look at the first date after the start of month or year but at the date before that. Often, you’ll need to make sure you’ve actually accounted for the payments made before the year if they hit your accounts days later (I have this issue in Singapore all the time. Debits hit my account days after I incurred them at a vendor because of the slowness of the NETS system and Visa here.).
From there, it’s a simple matter of running your bank account exports through Reckon and tracking cash expenses by hand/note (if you need to worry about that a lot.) and by how interested in looking at what you spend, which is how we get to figuring out your Chart of Accounts.
Chart of Accounts
While a cliché, what you measure is what you manage from a financial perspective. For example, I’m terrible at tracking petty cash expenses because I am using cash in a situation where someone will not accept a card and then forget to write it down. But those are rare that and immaterial to my spending. There’s a low chance it’s indicative of a trend in my spending or finances (though probably understates my taxi, grocery, and housewares accounts slightly.). Your own Chart of Accounts will differ by your personal situation. There’re heaps of google-able articles on this by better financial whizzes than me, but this is what I find works for me. YMMV and it depends on what you care about tracking (in fact, I should probably revise some of mine since the things I thought were financial wary watches were not.).
Assets
Cash
Loans Outstanding
Country1 Savings
Receivables
Finn1
Finn2
RSUs
Country2 Savings
Equity:Opening Balances
Expenses
Bank Fees
Books
Cleaner
Computer
Education
Electronics
Entertainment
Food
Delivery
Groceries
Restaurants
Gifts
Government Fees
Gym
Health and Beauty
Housewares
Interest:Loans
Interest:Mortgage
Internet
Medical
Online Services
AWS
DNSimple
Dropbox
Github
Heroku
Phone
Rent
Software
Apple
Google
MS
Others
Taxi
Travel:Flights
Travel:Hotels
Utilities
Income
Deferred:RSUs
Deferred:Reimbursements
Interest
Rental
Salary
Liabilities
Credit Card1
Credit Card2
Credit Line
Loans
Mortgage
As I said, think about what’s important for you to track and why since the less complex you can make your life and tracking (limiting to actionable financial decisions), the easier it will be for you.
Budgeting
You need a budget. Tracking spending is about understanding where your money goes, but it’s implicitly about whether you are spending according to expectations. Those expectations are your budget.
Budgets end up being surprising. I thumbnail projections out at the start of most years in a sort of Fermi estimation type exercise and it’s shocking sometimes how far those napkin projections differ from reality in some categories (restaurant spending, for example).
Ledger supports budgets with a simple syntax related to your Accounts. You can put this at the top of your Ledger file though I generally like having it in a separate file (which I can also comment out and update a new budget as conditions evolve or financial needs change.).
So, I recommend setting up a separate budget file by year (mine is 2020_budget.ledger) and then importing that into the main ledger file you use. At the top of my master file I have the following:
include 2020_budger.ledger
which does the trick.
Budgeting entries get demarcated with a tilde ~:
~ Monthly
Expenses:Rent 2,500.00 SGD
Expenses:Food 2,500.00 SGD
Expenses:Books 200.00 SGD
Expenses:Internet 60.00 SGD
Expenses:Phone 100.00 SGD
Expenses:Transport 500.00 SGD
Expenses:Utilities 200.00 SGD
Expenses:Cleaner 120.00 SGD
Expenses:Gym 200.00 CAD
Expenses:Entertainment 500.00 CAD
Expenses:Online Services 100.00 CAD
Expenses:Software 150.00 CAD
Expenses x200.00 SGD ; all other expenses
Assets
~ Yearly
Expenses:Vacation xx,000 SGD
Expenses:Vision 1,000 SGD
Expenses:Computer 2,500 SGD
Assets
Here’s a theoretical example (with two currencies to simulate having a foreign CC or similar). I’ve also split the budget into Monthly and Yearly, though in a future post I’ll start talking about Funds (virtual) and using those to get a better idea of how you’re tracking monthly on finances. The nice thing here is you can look at top level categories like Expenses:Food rather than each individual sub-account (eg Expenses:Food:Restaurants) to get a better idea of what big areas may be looking like. Also, note that you can catch-all expenses beyond specific categories you’re interested in to get a handle on total spending versus your projections (very powerful).
The commands to handle actual to budget are pretty easy: add a –budget flag to regular ledger commands and a “grouping” time flag like your monthly reporting with a -M or -Y for monthly and yearly. Let’s take a look at Expenses:Food for example:
ledger -f ~/Dropbox/ledger/2020_master.ledger --budget -M reg "^Expenses:Food"
This takes my main ledger file (which has the budget included via the include statement above and compares the register report to budget for the Food accounts including subcategories like Groceries, Delivery, and Restaurants.). It gives you something like this:
2020-01m-01d - 2020-01m-31d Expenses:Food 1,542.97 SGD 1,542.97 SGD
2020-02m-01d - 2020-02m-29d Expenses:Food 1,732.07 SGD 3,275.04 SGD
2020-03m-01d - 2020-03m-31d Expenses:Food 629.95 SGD 3,904.99 SGD
I am significantly over-budget on food spending for the first quarter. As you can probably tell from the first report I showed you, it’s pretty clear I need to reduce restaurant spending dramatically to get myself back onto track for the year.
The key thing here is to figure out what actions you need to take from looking at the trends and other reporting you get and change your financial behaviour.
Tips, Tricks, and Gotchas
It’s a good idea to invest a tiny bit of time in reading up on double entry accounting. Some of the conventions can be (at least to me) counter-intuitive at first until you start thinking in Assets, Liabilities, Equity etc etc. Here’s some examples that affected me personally to help you avoid wasting time or frustration (note: I am not a bookkeeper or account so if any person who knows what they’re talking about or sees a logical inconsistency in what I’ve done here, please hit me up with a mention @awws on mastodon ).
Watch for double counting crediting between accounts
Succintly: have a strategy for credits/debits between your accounts to avoid double entering in double entry accounting. Credits like income and salary take care of themselves.
When your financial life becomes a bit more complex, you will do things like transfer money from one account ot another or between countries, or your bank will have a crazy way of denoting charging interest on your credit line. Reckon and Ledger write entries into your ledger file, not realizing that the transfer on your foreign bank account is actually duplicated by your domestic bank’s entry for the inbound credit. If you’re not paying attention to that and double entry accounting you will end up overcounting or have a rather large mess in accounts (yes, I got caught by this at first.).
My personal let the “pulling”/credited account be the one where the single source of truth resides as in general that feels easier to track since credits are easier to parse out than debits on most accounts. So, in the above example, if I’ve moved money from the foreign country I am working in to my home accounts to pay some bills, I let the home account have the single record for that transaction and delete the journal entry for the originating bank so I do not have a double debit and credit.
Reimbursements
Counter-intuitively, you need to think of Reimbursements as an Asset held by your company (or whoever needs to pay you back) until they pay it back. For example, my previous company made its executives use their own credit cards rather than issue corporate cards. Whenever you take on an expense the company needs to pay back, your entry should look a bit something like this:
2020-01-17 Scoot
; Flight to Jakarta return
Liabilities:CC -287.00 SGD
Assets:Reimbursements
That is, you are taking on credit card liability and you have an asset that will be repaid in the future. When you company pays you back you would see a credit in your bank account.
2020-01-17 Inward transfer from BigCo
; Expenses reimbursement
Assets:Bank Account 287.00 SGD
Assets:Reimbursements
This zeroes out your reimbursements account (if your company repaid you correctly) and helps track it to make sure you are settled especially if your company lags payments by a month as most companies do (while you’re still incurring expenses for them). You still have to pay off your credit card, but you’ve squared your reimbursements. Note: This technique also works with putting expenses on foreign credit cards but needing to track reimbursements with multiple currencies though FX then gets involved.
Loans
You can use a similar technique for Loans that are not liabilities to yourself (ie. owed to a bank etc). Think of them as an asset which is a Receivable held by someone else until it’s paid back.
2020-01-17 Loan to Finn
; WWW Transfer 459683687
Assets:Bank account -1500.00 SGD
Assets:Receivables:Finn
And handle repayments the same way you would Reimbursements above.
RSUs and Stock Options
Perhaps an edge case not so applicable for most people, but I spent a good day surveying people (even bookkeepers and accountants!) and googling to get good info on how RSUs (Reserved Stock Units) or illiquid equity grants gets handled from an accounting perspective.
If you work in tech, if you received equity, it will generally be some sort of illiquid asset which has implied value (due to valuation or paid-up investment capitalization) but is neither tradable nor convertible. Basically, it’s worth what the company or investors say it’s worth, even if you can’t use that money.
In some tax jurisdictions you might even have a tax liability because of it, so track it. Generally, RSUs or similar equity vest every month or every quarter after a one year vesting cliff (meaning: you need to spend a year at the company before getting any shares but then you get a year’s worth and rest the reamining on whatever the vesting schedule is.). Usually, the terms are you are fully vested after four years in standard “Silicon Valley” vesting schemes.
The trick here is that the value of the asset will change over time. If your company doubles in value due to injected capital (or worse, a down round), your vested shares can be at a different value than your original shares (appreciating share value) and often in a reference currency other than the one you track in (in my case, USDs) The scope of dealing with capital gains and taxation is beyond the scope of this post, but here’s how I handled this for myself in ledger.
Keep in mind, this is an esoteric area and I have to admit after speaking to two bookkeepers and a business accountant, they were themselves unable to give me a universal opinion, so not entirely sure how it gets handled canonically. IANAA (I am not an accountant - if you do know, please mention @awws on mastodon and educate me.). That said, here’s a theoretical example of a quarterly equity grant.
2020-02-02 Big Co Equity grant
; Quarterly Equity vesting
Assets:RSUs 55 RSU @ 110 USD
Income:Deferred:RSUs
You’ll notice that I use the three-letter acronym RSU to identify this as a “commodity” as far as ledger is concerned and then index that to a USD value to understand the money implications. Ledger has pretty amazing commodity value support so you do get to see the number of RSUs you actually have and can actually use the program to determine capital gains (or losses) with a little work (same as you could in the Loans section above with writing off Bad Loan Expense.).
Note: In Opening Balances, you would want to keep your RSUs (or whatever indicator you use for them consistent between years so you can see how they’re appreciating/depreciating and understand your gains or losses. Reconcile them at year end in so you can understand capital gains/losses and your financial position and then close that year’s books.).
Bonus: Emacs ledger-mode
If you are an emacs user, someone has created a fantastic major-mode for ledger you can use which makes your life even easier. It provides syntax highlighting (and aligning) of entries, auto-completion, and even allows you to run reports in a split pane on the right with a simple CTRL-C-O-R (hold down Control the entire chord) and then selecting the report you want. It also updates the report every time you save. I use this when pasting in Reckon-run ledger entries to check the balance report and make sure everything stays, well… balanced. It’s fantastic. I have not investigated this near enough but am going to look into customizing it a bit more to automate regular reports like budget and virtual Funds.
In your ~/.emacs.d/init.el use the following if you are using the fantastic use-package package manager. It will make emacs go into ledger-mode for any file with a .ledger extension.
(use-package ledger-mode
:ensure t
:defer t
:init
)
(add-to-list 'auto-mode-alist '("\\.ledger$" . ledger-mode))
You can also go full emacs on this and use babel for inserting code blocks into files and going “literate programming” on this but it’s not something I’ve had a great deal of time to loo into to see if the benefit outweighs the time cost.
As a final recommendation, I’d also recommend using ivy and swiper in emacs for ridiculously fast searching and jumping through your file when you need to find something (typos for accounts for example). Emacs makes the setup on this awesome though I do note that VS Code has a ledger mode as well though it looks more to be about syntax highlighting than having the completeness of the emacs package.
Fin
While it’s a long post, I wanted a one stop post to getting started and going with Ledger and Reckon to get people past the basic documentation you might find and get you into a routine of a financial habit that allows you minimal time to update and more time to understand your finances to control them. I hope it’s been helpful if you’re looking at doing your finances this way and I hope you’re convinced that plain text tracking of your finances is something that is robust, portable, and has longevity beyond most every other thing I’ve tried.
If this post did help you out or you have suggestion for improvements (or gasp, corrections), please ping me by mention @awws on mastodon .