A User's view of Hledger

Learning about hledger

Time to close out 2023 (in May)

As I have written previously, I don’t need to close out my yearly hledger file immediately after a calendar year ends. In fact, there are advantages to waiting a few months. For example, completions using the hledger “add” command work better if there is already a history of commands to draw on when entering a new transaction. If I start a new file with no previous transactions, there are no defaults for “add” to suggest, slowing me down.

However, now that we are in the 5th month of the year, I decided that it was time to split my current file into two, one for 2023 and one for 2024.

Closing a year in hledger is one of those tasks that happen with such infrequency, that I have to remind myself of the details. The first thing that I needed to do was to remember the exact command to use. Checking out the hledger documentation, I picked the option.

hledger close --migrate=NEWYEAR -e NEWYEAR

My first task was to read the documentation correctly, which I didn’t succeed at.

The correct way to understand the above command is that NEWYEAR means the 4-digit calendar year. In my case it would be 2024.

How hard is that to understand? Well, in my case I organize my hledger data files by calendar year, so I first thought NEWYEAR meant the name of the file for the new year. Fortunately, the only harm in making that mistake was losing a minute or two in some head scratching.

Once I entered the year as a four-digit number, the command worked fine.

I had one additional thing that I wanted to do. Specifically, in my opening balance statements I had a number of opening balances for accounts that I don’t reconcile in hledger. It’s a long story, but since I don’t reconcile these accounts, the amounts of the opening balances have very little meaning. In short, they are lines that I would qualify as clutter (yes, they are real accounts; no the number is not the actual opening balance, because I don’t balance that account). Less clutter is almost always better, so I wondered if I could safely get rid of these extraneous lines.

First, I tried commenting out one line, just to try that approach. But then there was an error message when I ran a test hledger command.

By the way, running a short hledger command is my standard trick for testing if there are any errors in an hledger data file. If there are errors, you get a message telling you a) that there is a problem and b) where the problem is. If no errors, you see the result of the command.

Second, I tried deleting one of the opening balance statements, leaving a blank line. That didn’t work, either.

The solution was to delete the line of data and the blank line. Lesson learned was that in my opening balances not to have any commented out lines or blank lines.

The only other thing to do in terms of setting up the file for 2024 was to remember to mark the opening balances as reconciled. Otherwise, reconciling won’t work for those accounts.

Upgrade to hledger version 1.33.1

In case you haven’t heard, hledger version 1.33.1 is out. No problems on my end with the upgrading process.