Reconciling Ledger

For me, one of the primary appeals of using Ledger – or really any accounting system – is that it let’s me know how much money I have (or don’t have) right now. Other people’s records lag behind reality.

If I submit an order for a $50 widget on a website today, I consider that $50 gone, even though the vendor likely didn’t collect the money immediately. They probably placed a hold on the funds, but will not actually capture the money until they ship the order, which may take a couple days. When they do capture the funds, it may still be another day or two until that action posts to my online bank statement. Were I dependent on the bank, I could go a week thinking that I have $50 more than I actually have.

It is important to me that I log transactions without waiting for them to appear elsewhere, but at some point I do want to reconcile my records against what my bank believes. I accomplish this with auxiliary dates.

Were I to submit that order for a $50 widget today, I would create the entry using today’s date. Even if it takes me a few days to actually record the entry, I will still use the date the order was submitted.

2020-08-06 Acme, Inc
    Expenses:Misc                             $50.00

Periodically, I will manually reconcile every transaction in my journal against my bank’s online statements. Usually this happens every other week or so. Many people will simply dump a CSV from their bank and use a script to parse and import the results into their journal. I prefer to do it manually. This rarely takes more than 30 minutes, and for me it is one of the other primary appeals of using Ledger: it forces me to be intimately aware of how money is flowing in my life, and makes it extremely easy to spot problems or errors. It is difficult to accomplish that reliably without manually touching every transaction.

So a week or two later I’ll login to the bank and make sure there is a $50 payment to Acme, Inc. If the date listed by the bank for that transaction is different from what I recorded – which for online transactions is almost always the case – I’ll prepend that date to my entry.

2020-08-10=2020-08-06 Acme, Inc
    Expenses:Misc                             $50.00

When there are two dates, Ledger considers the date to the left of the = to be the primary date. The other date is the auxiliary date. Previously, when only one date was listed, it was the equivalent to 2020-08-06=2020-08-06. By using the bank’s date as the primary date, I know that the default output from a report like ledger register assets:bank:checking will match the bank’s statements. If I want to report on what I consider to be the real dates of the transactions, I can pass the --aux-date flag.

The journal files themselves I edit manually in vim, with a little help from vim-ledger. I have <leader>t mapped to set today’s date as the primary date of the current transaction. Because I usually only reconcile two or three times a month, today’s date is often not the date I actually want, but this shortcut allows me to immediately insert a new date in the correct format. I can then quickly change the day number to whatever it should actually be.

I consider the transaction to be cleared once the bank statement and the Ledger journal file agree on the date, payee, and dollar amount. In Ledger, transactions are marked as cleared by inserting an * between the date and the payee. In vim I map this to <leader>c. A complete transaction thus looks like this:

2020-08-10=2020-08-06 * Acme, Inc
    Expenses:Misc                             $50.00

Ledger defaults to including all transactions in its reporting and calculations. By passing the --cleared flag it will only include transactions that have been marked as cleared. So after I think I’m done reconciling all transactions against my bank statement, I will run ledger balance assets:bank:checking --cleared and verify that the resulting balance matches what the bank shows. If I want to know how much money I actually have in that account, I will run ledger balance assets:bank:checking. The output of this will likely include transactions that the bank hasn’t caught on to yet.

If for some reason Ledger’s output of the cleared balance does not agree with the bank, my first step will be to make sure that all transactions are sorted by their primary date. If I already have the file open in vim, I have a shortcut for that. Otherwise I keep a one-liner script called ledger-sort that takes the name of a ledger file as input, sorts it, and shows me the diff.


ledger -f $1 print --sort d > $1.sort && mv $1{.sort,} && git diff

Checking the diff of the sorted output before continuing is important. Sometimes I’ll make a silly mistake like typing the wrong year when entering the transaction. This sort of mistake is obvious when looking at the diff.

Once the file is sorted, I’ll run ledger register assets:bank:checking --cleared. The final column in this output is a running total of the account balance. The only difference between the output and my bank statement should be the ordering of transactions within a day, which I do not care about.

I’ll know that I last cleared my journal around a certain date, and that the account balance was accurate as of that date.1 If I was doing this on 2020-08-06, I might say to myself “I know I cleared Ledger sometime in mid-July, so let’s look at my account balance at end of day on 2020-07-15”. If the bank and Ledger both agree on the balance at the end of day on that date (regardless of the ordering of the multiple transactions that may have occurred on the day), I’ll know that the error is somewhere between 2020-07-16 and 2020-08-06. Next I’ll jump to another random day in that period – maybe 2020-07-22 – and perform the same exercise. This is repeated until I find the first day where the two systems disagree on the ending balance. Then I look at every transaction on that day and find the error. Usually it will be a simple data entry error, such as me typing $12.10 instead of $12.01. Having my receipts stored allows me to verify that I did indeed agree to pay $12.10 and that the error is mine rather than the payee’s. This whole process of finding errors rarely requires more than two minutes, and occurs maybe once every three months.

Though I don’t use CSV exports from my banks for anything, I do like to periodically download and archive them. When I generate the exports I ask for one file per month. I refer to these as “bank dumps” and store them in directory named dump. Each file is named for the account and month it represents. For example, an account named Assets:Bank:Savings will have last month’s dump stored at dump/assets-bank-savings-202007.csv. I pretty much never open these files, but I like having them archived. They allow me to see how much money a bank thought I had at any point in time, even if the account is no longer open, and provide assurance that I can always true my records if I somehow mess them up.


  1. Ledger has the ability to record assertions. I have never used this feature, but I probably should.

Receipts and Ledger

As previously mentioned, I store receipts in the same repository as my Ledger data files.

Purchasing something online automatically generates a receipt; it’s just a simple matter of saving the confirmation web page or email as a PDF and moving it into the proper directory with the proper filename. That’s a low enough bar that I cannot justify not storing them. I have a receipt for every digital transaction I have made since I began using Ledger in 2012.

I’m less strict about storing receipts for transactions that occur in meatspace. These transactions usually result in a paper receipt (which may not be initially even be offered), which then requires scanning or photographing. That is just enough effort that I don’t always want to do it. I’ll store the receipt for a meatspace transaction if the amount is greater than $100, or if I think it might be tax deductible, or if I think I might make a warranty claim. But if the transaction is a $10 sandwich for lunch, I probably won’t bother storing the receipt.

My naming scheme for the receipt files consists of the date of the transaction, the amount, and the payee. This is enough information to go from a Ledger journal entry to a receipt, or from a receipt to a Ledger journal entry. For example, consider a transaction with a journal entry like this:

2020-07-14 Acme Widgets
    Expenses:Bicycle:Parts                    $23.72

The receipt for that transaction will be at receipts/20200714_23.72-acme_widgets.pdf.

When I first began using Ledger and came up with this file naming scheme, I figured I would write some sort of script that would parse the components of a journal entry and generate the expected receipt filename so that I could quickly jump from one to the other. What I found is that the scheme is simple enough to make such a script unnecessary. When I look at a journal entry I intuitively know what the receipt filename is, and when I look at a receipt filename I intuitively know what the journal entry is. Writing a simple script to generate one from the other would take more energy than I have collectively spent over the past eight years solving the problem manually. So I never wrote it.

I also store invoices in the same repository, in a directory creatively named invoices. These are invoices that vendors send me – primarily things like rent statements and utility bills – not invoices that I send to people. The naming scheme is the same as what I use for receipts, except in this case the date in the filename is the date the vendor included on the invoice rather than the date I received it or paid it. I chose this because if I ever need to dispute a charge or a payment, this date is an easy way for both the vendor and I to quickly verify that we are discussing the same thing. Each invoice will of course have an associated receipt in the receipts directory after I pay it, and the date on this file will be the date on which I submitted the payment.

Every now and then I need to write someone an old-fashioned paper check. These get scanned and stored in a checks directory. The file naming scheme for these is similar to that of receipts, except that in addition to the date, amount and payee, I also include the check number. Ledger supports including the check number in the journal entry, so including it in the filename provides another way to link the two things. For example, back in 2015 I renewed my passport book and bought a passport card:

2015-11-09=2015-10-31 * (#1047) US Department of State
    ; Passport Book Renewal
    ; Passport Card Purchase
    Expenses:Travel:Documentation            $140.00

The scan of the check from that transaction lives at checks/20151031_140.00-1047-us_department_of_state.pdf.

Tracking Cash with Ledger

In a double-entry accounting system like Ledger, money always moves from one account to another. Money cannot be magicked in or out of existence.

Previously I mentioned that I sometimes do not track cash transactions. If the transaction is less than $20 and is not related to a category of expense I care about, I may not bother with it. At first glance, this may seem like it conflicts with the inability to magically disappear money. If I take cash out of my checking account, I have to represent that withdrawal or else the balance of the account will be screwy and I’ll never be able to reconcile it against the bank’s statement. Transforming money from electrons in a bank account to Federal Reserve Notes in my pocket has no impact on its value, so one’s initial thought may to represent the cash as an asset account.

2020-07-13 ATM
    Assets:Cash                               $40.00

This would be technically correct, and the best way to do things if every last penny of that cash was going to be tracked. But logging the withdrawal that way will not work if, over some period of time, I spend the $40 cash in a serious of small, untracked transactions. In that case, my Assets:Cash account would show that I have $40 more than reality. When asset accounts are not accurate, the world ends.

The solution is to treat cash as an expense account. The balance of an expense account is less important. It tells you how much money you’ve spent on that category of thing, but it doesn’t represent money that you hold. Effectively, this is saying that the $40 was spent when it was withdrawn at the ATM. It no longer contributes to assets or net worth.

2020-07-13 ATM
    Expenses:Cash                             $40.00

The transaction would look similar if I asked for cash back while buying groceries.

2020-03-20 Lucky Dragon Markets
    Expenses:Food:Groceries                   $58.89
    Expenses:Cash                             $40.00

But the trick is that money doesn’t have to move between an expense account and an asset account. Money can move between any accounts, including two expense accounts. I am strict about tracking food related expenses, so if I buy a burrito with that cash, I’ll want to log it. I can do that like this:

2020-07-18 A Taqueria
    Expenses:Food:Dining:Lunch                 $8.23

If part of your savings are in cash – in a safe deposit box, stuffed in your mattress, buried in the hills, whatever – you would want to treat it as an asset so that you can track the balance.

2020-08-30 ATM
    Assets:Mattress                          $100.00

To illustrate the degree to which I do track cash: Ledger currently reports the balance of Expenses:Cash to be $3797.29. I’ve certainly dealt with significantly more cash than that since 2012. The balance of that account is simply the amount of cash I have acquired but failed to log as spent.

Organizing Ledger

Ledger is a double-entry accounting system that stores data in plain text. I began using it in 2012. Almost every dollar that has passed through my world since then is tracked by Ledger.1

Ledger is not the only plain text accounting system out there. It has inspired others, such as hledger and beancount. I began with Ledger for lack of a compelling argument in favor of the alternatives. After close to a decade of use, my only regret is that I didn’t start using earlier.

My Ledger repository is stored at ~/library/ledger. This repository contains a data directory, which includes yearly Ledger journal files such as data/2019.ldg and data/2020.ldg. Ledger files don’t necessarily need to be split at all, but I like having one file per year. In January, after I clear the last transaction from the previous year, I know the year is locked and the file never gets touched again (unless I go back in to rejigger my account structure).

The root of the directory has a .ledger file which includes all of these data files, plus a special journal file with periodic transactions that I sometimes use for budgeting. My ~/.ledgerrc file tells Ledger to use the .ledger file as the primary journal, which has the effect of including all the yearly files.

$ cat ~/.ledgerrc
--file ~/library/ledger/.ledger

$ cat ~/library/ledger/.ledger
include data/periodic.ldg
include data/2012.ldg
include data/2013.ldg
include data/2014.ldg
include data/2015.ldg
include data/2016.ldg
include data/2017.ldg
include data/2018.ldg
include data/2019.ldg
include data/2020.ldg

Ledger’s include format does support globbing (ie include data/*.ldg) but the ordering of the transactions can get weird, so I prefer to be explicit.

The repository also contains receipts in the receipts directory, invoices in the invoices directory, scans of checks (remember those?) in the checks directory, and CSV dumps from banks in the dump directory.

$ tree -d ~/library/ledger
├── checks
├── data
├── dump
├── invoices
└── receipts

5 directories

The repository is managed using a mix of vanilla git and git-annex.2 It is important to me that the Ledger journal files in the data directory are stored directly in git. I want the ability to diff changes before committing them, and to be able to pull the history of those files. Every other file I want stored in git-annex. I don’t care about the history of files like PDF receipts. They never change. In fact, I want to make them read-only so I can’t accidentally change them. I want encrypted versions of them distributed to my numerous special remotes for safekeeping, and someday I may even want to drop old receipts or invoices from my local store so that they don’t take up disk space until I actually need to read them. That sounds like asking a lot, but git-annex magically solves all the problems with its largefiles configuration option.

$ cat ~/library/ledger/.gitattributes
*.ldg annex.largefiles=nothing

This tells git-annex that any file ending with *.ldg should not be treated as a “large file”, which means it should be added directly to git. Any other file should be added to git-annex and locked, making it read-only. Having this configured means that I can just blindly git annex add . or git add . within the repository and git-annex will always do the right thing.

I don’t run the git-annex assistant in this repository because I don’t want any automatic commits. Like a traditional git repository, I only commit changes to Ledger’s journal files after reviewing the diffs, and I want those commits to have meaningful messages.


  1. I do not always track miscellaneous cash transactions less than $20. If a thing costs more than that, it is worth tracking, regardless of what it is or how it was purchased. If it costs less than that, and it isn't part of a meaningful expense account, I'll probably let laziness win out. If I buy a $8 sandwich for lunch with cash, it'll get logged, because I care about tracking dining expenses. If I buy a $1 pencil erasure, I probably won't log it, because it isn't part of an account worth considering.
  2. I bet you saw that coming.

Isolation Report, Day 2020.07.29

One hundred and thirty nine days of Operation Fuck Off I’m a Hermit Now. Bacon and chocolate supplies restocked.

All systems nominal.

This post was published on . It was tagged with media, quarantine.

Link Log 2020-07-19

Wireless is a trap

I want my tools to be predictable – to have consistent performance and fail in ways that I understand. Wireless protocols are inherently more complex (because many devices share the same airspace) and have more different ways to fail, so they’re much less predictable than wires. For me, the convenience often isn’t worth that cost.

Peer-Reviewed Scientific Journals Don’t Really Do Their Job

In many ways, journals don’t even pretend to ensure the validity of scientific findings. If that were their primary goal, journal policies would require authors to share their data and analysis code with peer reviewers, and would ask reviewers to double-check results. In practice, reviewers can only judge the science based on what’s reported in the writeup, and they usually can’t see the details of the process that led to the findings. (This is kind of like asking a mechanic to evaluate a car without looking under the hood.) And for really important discoveries, you might expect journals to recruit an independent team of scientists to try to replicate a study from scratch. This basically never happens.

How Normie Minimalism and Farmhouse Chic Took Over Contemporary Design

The fetishization of and association with regional manifestations of a labor past is what ties together the minimalism of the industrial loft to an aesthetic that has been increasingly dubbed “modern farmhouse.” Just as the loft romanticizes the backdrop of 19th century urban industry, the modern farmhouse romanticizes the similarly Steinbeck-ian plight of the agricultural worker. It makes sense that an aesthetic marketed towards suburban homeowners would be based off agricultural work, since the history of the suburbs from the Garden City movement to gated communities is based off escape from urban plights and the further-flung expansion into greenfields, or previously agricultural, areas. This fetishized and aestheticized use of the motifs of agriculture also enabled marketing to areas such as the regional South, whose economic production still revolves around agriculture and which never urbanized to the same extent – or in the same way – as the Northeast.

Handmind in Covidtide

Moreover, one of the effects of Covidtide, I think, is that by forcibly breaking some of our technological habits it creatively destabilizes others. To have any one thoughtless pattern of life disrupted is to be put into a frame of mind that allows you to contemplate the deliberate disruption of a different thoughtless pattern. Thus all the people who, after three months of baking bread, are now saying that they’ll never go back to buying their bread from the supermarket. They probably will buy bread from the supermarket; but they’ll know what they are doing, and why. And this is useful knowledge.

The Conspiracy Singularity Has Arrived

The strain of living in this particular time, with a dragging, devastating pandemic and a global uprising against police brutality and racial injustice, crashing together at the highest speed, has accelerated something that’s been going on for years. Call it the conspiracy singularity: the place where many conspiracy communities are suddenly meeting and merging, a melting pot of unimaginable density. UFO conspiracy theorists and QAnon fans are advocating for drinking a bleach solution promoted by anti-vaxxers. QAnon groups and Reopen America groups alike promoted Plandemic, a film clip jam-packed with conspiratorial claims about the causes and spread of COVID. The Freedom Angels, an anti-vaccine group based in California, are among the many such groups joining anti-lockdown protests, using language that feels heavily drawn from the Patriot movement: They’re calling stay-at-home orders “tyranny,” addressing their followers as “Patriots,” and positioning themselves as “a new civil rights movements.”

Dead and Alive: Beliefs in Contradictory Conspiracy Theories

Thus, we predict that for someone with a conspiracist world-view, nearly any theory that assumes deception by officialdomin its explanation for a world event and stands in opposition to the “mainstream” account will garner some agreement. This relationship may hold even to the point that people who believein a world governed by conspiracy are likely to endorse contradictory conspiracy theories about the same topic. Just as Adornoet et al. (1950) found positive correlations in endorsement of contradictory stereotypes, we expect to see positive relationships between endorsement of contradictory conspiracy theories about the same event. For example, the more that participants believe that a person at the center of a death-related conspiracy theory, such as Princess Diana or Osama Bin Laden, is still alive, the more they also tend to believe that the same person was killed, so long as the alleged manner of death involves deception by officialdom.

Aquatic Park

This post was published on . It was tagged with links.

I've started mounting my bike lights via shock cord.

The previously mentioned Orfos Pro LED flares ship with Velcro One-Wrap for mounting. This works well enough, but lately I’ve decided I prefer using shock cord and cord locks. The cordlocks add a little weight to the system, but this setup mounts to all the things I want to mount the lights to, and makes it very easy to tighten. After tightening the lights don’t move around at all, where with the Velcro they would move a little on a bumpy road. This system is also quick to attach and detach, which I appreciate when parking, and can be more easily manipulated when wearing full-fingered gloves.

Orfos Pro Shock Cord Mount

  • Orfos Pro Shock Cord Mount
  • Orfos Pro Shock Cord Mount

This post was published on . It was tagged with micro, bicycle, gear.


There’s always a prevailing mystique in any civilization. It builds itself as a barrier against change, and that always leaves future generations unprepared for the universe’s treachery. All mystiques are the same in building these barriers – the religious mystique, the hero-leader mystique, the messiah mystique, the mystique of science/technology, and the mystique of nature itself. We live in an Imperium which such a mystique has shaped, and now that Imperium is falling apart because most people don’t distinguish between mystique and their universe. You see, the mystique is like demon possession; it tends to take over the consciousness, becoming all things to the observer.

Frank Herbert, Children of Dune

This post was published on . It was tagged with quote.