A User's view of Hledger

Learning about hledger

Blog entries prior to June 2023 site update

In June 2023 I switched to WordPress to manage this site. All the previous blog entries prior to the site update can be found below.

Note that I have made minor edits to the posts below, mostly to improve readability.

June 22, 2023 — Upgrading to hledger version 1.30
Brew made quick work upgrading my hledger program to version 1.30. This had been pending for some time as the upgrade was made available around the first of this month. However, with my schedule being full with other things, I decided the upgrade could wait a few weeks. Yesterday, though, the decks were cleared, and it was a good time to do the upgrade, which proceeded with alacrity.

When I upgraded hledger using Brew, I chose the option to upgrade all programs where there were newer versions. It’s always amazing to me how many programs Brew finds to upgrade. I admit that I almost never think about these other programs that Brew upgrades. One benefit, I suppose, to hledger upgrades is that at the same time I also get the latest version of a host of other programs.

RSS feed not working
The RSS feed for this site has major problems. In July I am planning to use a different system for creating my web entries, and I hope that will solve the problem.

June 15, 2023 — Why save?
I need to add one more thought to the recent series below on saving. And that is to ask: “Why Save?”

Saving isn’t (or at least in my opinion shouldn’t) be a goal in itself. Saving is a means to an end.

One purpose of saving is to have the resources to improve your life and the lives of those around you. But if you are spending all your money now in ways that help you and others, doesn’t that make saving unnecessary? In fact, isn’t it better to spend all your money now, as long as it is benefiting you and others?

Part of the answer is that there are uncertainties in life. We sometimes experience smooth sailing; other times we are faced with rough seas. At one point in the future your needs may be greater, to a significant degree, than your needs today. Therefore, accumulating savings can be a wise plan in order to help yourself and others in the future.

What happened to the planned break in the blog?
On May 18, below, I posted that I was planning a break in this blog until today (June 15). The reason was that my schedule was going to be very busy, and I wouldn’t have the time to come up with new material each week. However, as you can see below, there has been a “Thoughtful Thursday” post each week, without interruption. What happened?

Well, I realized shortly after May 18 that there were some timeless postings I could write about in advance. So I did some work and had the next 3 weeks all ready to go. During those busy weeks, all I had to do was post the pre-written blog entry for each week.

RSS feed not working
The RSS feed for this site has major problems. In July I am planning to use a different system for creating my web entries, and I hope that will solve the problem.

June 8, 2023 — Backpacking and hledger
Imagine that you are backpacking. Naturally, you don’t want to carry too much weight. Therefore, you have bought a camp stove that weighs half of another model you thought about buying. In addition you have a tent that weighs less than the average tent.

So, everything is good, right?

Possibly. Your choice of the stove and tent are good ones in terms of reducing your load. But what else are you carrying? More importantly, what is the total weight of your camping equipment? And is that weight something that you can carry on your 20 mile hike?

What does this have to do with hledger?

If you are tracking your finances, you will know your total expenses. This is like knowing the total weight you are carrying in your backpack on a hike. Knowing the total is more important information than being able to point to individual instances of saving some money here or there.

If you are tracking your finances, you can also compare your total expenses versus your total income. Is your income greater than your expenses? Is it less? This is key information.

What is the financial load you are carrying? How much can you carry? If you are not tracking your personal finances, you won’t know.

RSS feed not working
The RSS feed for this site has major problems. In July I am planning to use a different system for creating my web entries, and I hope that will solve the problem.

June 1, 2023 — What is not a penny saved
Last week, I pointed out how saving pennies was more powerful than earning pennies. The reason is because in general you pay taxes on money earned, but you don’t have to pay taxes on money you save.

It’s time, though, to look at one thing we call saving, but that really isn’t saving. At least it’s not saving that is going to help us to get ahead financially.

What am I talking about? We commonly see this in advertising. “Product X, normally $100 is now $90. Buy it and save $10.”

Of course, this is a saving only if you really needed to buy product X in the first place. By the same logic as above, if I don’t buy product X on sale for $90, I save $90, even better than the $10 that was promoted in the advertisement.

And this will finally lead us, next week, into what this means regarding hledger.

RSS feed not working
The RSS feed for this site has major problems. In July I am planning to use a different system for creating my web entries, and I hope that will solve the problem.

May 25 2023 — Ben Franklin and hledger
Benjamin Franklin is famously quoted as saying “A Penny Saved Is a Penny Earned.”

A wise personal finance teacher once noted that a penny saved is more than a penny earned. That is, most of us have to pay taxes on earnings. So after taxes, you net less than a penny for the one cent that you earned.

On the other hand, the vast majority of us are not taxed on amounts that we save. For example, if I have to buy a loaf of bread and can find it for 50 cents less than I normally pay, I get to keep the entire savings.

So, saving a penny is even better than earning a penny.

What does this have to do with hledger? More on this in the next couple of Thoughtful Thursday posts.

RSS feed not working
The RSS feed for this site has major problems. In July I am planning to use a different system for creating my web entries, and I hope that will solve the problem.

May 18, 2023 — Double duty hledger command; RSS issues with this site; break in the blog until June 15
Most of the time, my hledger data entry goes smoothly. (Yes, I almost always enter my data by hand, using something like the hledger “add” command to speed entry.)

One time when my data entry slows down is when I need to refer to an account I seldom use. What was the exact account name?

Yes, sometimes I can guess the first letter of an account and use autocomplete to fill in the rest of the name, but what happens if that doesn’t work? How can I see what the account name was?

This happened to me the other day. While off the top of my head I couldn’t remember the correct command (more on this later), I did remember that the incomestatement (IS) command would give me what I needed. That is, yes, it gives a report of the income and expenses, but it also lists all the accounts that I have used. Problem solved.

Later, I found that it was the “accounts” command that gives a listing of all the hledger accounts.

In either case, it was useful to pipe the command through “less” as in:

hledger is | less

By piping through “less,” you can scroll up and down the output, assuming that the report takes up more space than can be shown on one screen. When finished, just hit the ‘q’ key to quit.

RSS feed not working
RSS is not working for this site. That is, it partially works, but fails in some large ways.

Some background: I generate this site from Emacs org-mode. As part of that process, I use org export to create a static HTML page and a separate XML file. In theory, everything should work. But it doesn’t.

My web searches yesterday for a solution did not result in anything useful to me, at least in terms of using the above approach. However, I think I have found another approach that will bear fruit. This probably won’t happen until July, so my apologies that this won’t be fixed in the immediate future.

Break in the blog until June 15
Things are going to be a bit busy for me over the next few weeks. I am not expecting to have any blog content until June 15. Per my March 9, 2023 vision statement below, I will try to post a “stay tuned” entry on Thursdays (at least Thursday in my time zone!), just to let you know that I haven’t forgotten the blog.

May 11, 2023 — Persevering
The benefit from tracking your finances is more long term than short term. Therefore, you need to find a way to make a habit of tracking your finances, in order to reap the greatest benefit. So how can you persevere at this?

One way to do this is to start small with your tracking. For example, are you starting for the first time tracking your finances? If so, then forget any ideas such as entering the last 5 years of transactions. Just start with today’s transactions. After a year of tracking your expenses, you can always decide to fill in the missing previous 5 years. But the key point will be that after a year you now have the habit of tracking your expenses.

Also, at least at the beginning, reconcile your hledger (or other plaintext accounting system) daily, at least for the first week or so. It’s much easier to catch mistakes if you have just a few transactions to look through. It’s frustrating when an account won’t reconcile, so make it as easy as possible to troubleshoot by having as few transactions that you are reconciling. If you wait several days between reconciling, and you have 20 transactions, but they don’t reconcile, where is the error? Compare that to if you have just 2 transactions, and they don’t reconcile. Much easier to find the problem!

Some people will realistically observe that they are unlikely to make a habit of tracking their finances using a plaintext or other accounting system. One approach that might work for them is that they track their savings and debts monthly. How can they do that? First, make a list of all their debts. Include credit card debt, mortgages, and the $20.00 you borrowed from your brother-in-law. Total it.

Similarly, make a list of any money they have. Include, checking accounts, savings accounts, and perhaps a mutual fund. Total it. Repeat the process at the end of every month. If you can at least make a habit of doing that, you are much better off in terms of seeing what is happening with your finances than doing nothing. And maybe one day, you will be able to make the next step to using something like hledger.

But the key is to find something that you will do consistently. So start small. Persevere. Develop the habit. Then decide if you want to tackle something bigger.

May 4, 2023 — Two of my favorite hledger commands
These days, as I making sure that my tax withholding for 2023 is on track, the aregister (areg) and incomestatement (is) commands are getting a good workout.

One thing that I needed to do was to estimate 2023 income. Normally, one year’s income would be similar to another. However, in the spring of 2022 I left my full time paid position for the world of retirement (at least in terms of earning wages). It occurred to me that if I used the incomestatement command over the last 6 months of 2022 (when I didn’t have any paid employment), this would be a rough estimate of what I could expect for half a year of 2023. Doubling those figures would give me a ballpark estimate for 2023.

For more precise estimates, I use the aregister command to look at specific income or expense categories. The aregister command shows me the individual transactions, which sometimes can be useful for spotting transactions that were in 2022 but might not apply to 2023.

So, between the “is” and “areg” commands, I am building a better forecast.

Warp reminds me to stage and commit git changes
One improvement to my hledger use has been to use git to track changes in my hledger data files. When I started using Warp, I noticed that a command line appears when there have been changes to any files in directories that I am tracking with git. In essence, Warp is telling me that I have made a change to one or more files that I should be staging and committing. When all the git changes have been taken care of, the Warp prompt for pending git changes disappears. For me, this feature falls into the “sometimes it’s good to have a reminder” category.

April 27, 2023 — Trying out importing CSV files
Some years ago, when I was first working with hledger, I experimented with importing CSV data from a financial institution. The idea of importing such data is sound. Specifically, you don’t have to type in your transactions as instead the CSV file from your bank or whatever already has information that you would otherwise have to key in.

At that time, there were so many things new for me in terms of plaintext accounting, that I decided to drop the CSV import. Better to concentrate on a few new things at one time. Now, some years later, it was time to try importing CSV files again.

Part of the reason was to follow up on tracking investment income a bit more carefully. My reasoning is: better data = better feedback. And better feedback leads to better success. See the last two weeks’ entries below for some background on this if you missed it.

The CSV data I downloaded needed some additional processing before I could import it into hledger. My tool of choice for processing the data was a spreadsheet. It’s very easy to open CSV data in a spreadsheet. When you save your changes, you just have to make sure that you are saving the file again as CSV.

I then imported the CSV data into hledger formatted transactions. After examining the newly created transactions, I discovered that I didn’t need all them, so I hand deleted the superfluous ones.

I ran a few reports to check if things were properly imported, and they seemed to be. A step forward!

Next time, I think that I can make things a tad easier by deleting the unneeded transactions in the spreadsheet. Some simple sorting should allow me to group them in such a way that I can delete contiguous rows in one quick operation.

When Emacs auto revert didn’t work
One neat Emacs feature I use is auto-revert, mentioned below in August 29, 2022 — Automatically updating your hledger info in Emacs. This week I discovered a time when it wouldn’t work for me. Specifically, in Emacs ledger mode, I had used narrowing (C-c C-f) to focus on a group of transactions. I returned to the command line, added a transaction, went back to Emacs, but the just-added transaction wasn’t there. Fortunately, I could manually revert the buffer. Of course, if I had had unsaved changes in the buffer, they would have been lost. Not a big deal, but in the future I will save some time if I cancel any narrowing of my Emacs buffer before I add a transaction at the command line.

April 20, 2023 — Getting closer to the truth
As mentioned last week, I wanted to run some hledger reports that I hadn’t run recently. Why miss out on improvements that can come from valuable feedback?

So, I ran the income statement report, which I have found useful in the past. (See my July 25, 2021 — the secret ingredient for a useful income statement report entry below, for example.)

First question: How accurate is the information in the report? As I was reviewing the numbers, I suspected that there was some missing income information. And my suspicions proved true. Specifically, this was income related to investments.

How did this happen? It’s likely because I don’t track investments in hledger. That is, if did double entry accounting for investments, I would reconcile them as part of that process. Reconciling would show missing transactions, including the above missing income. At least, that’s what I think. As I don’t track investments this way, I can’t say this with certainty. But I suspect that it is true.

However, I did find a way to reconcile the income. I simply took my yearly investor statement and reconciled my investment income transactions against the yearly statement. Once the hledger generated results for the year matched the yearly report, I was confident of my plaintext accounting entries. And now my income statement report is more accurate.

Returning to the theme of valuable feedback, it’s highly unlikely that feedback is going to be helpful if it is significantly erroneous. Yes, you need more than just reasonably accurate numbers. But if your numbers aren’t close to the truth, you are not going to wring any valuable insights from them.

April 13, 2023 — How to improve your life
I gave a presentation yesterday to a Toastmasters group. One of my main points was the importance of useful feedback. That is, if you want to improve an area of your life, and you are not getting actionable feedback on how you are doing in that specific area, any progress you make is going to be hit or miss. Or more likely hit or miss or miss or miss.

It occurred to me that one of the values of a program like hledger is the information that it can give you regarding your financial life. I am not sure that I have been taking full advantage of hledger’s reporting to provide all the feedback that would be useful. Time for me to generate some reports that I haven’t been looking at recently…

hledger upgrade to 1.29.2
In case you missed it, hledger version 1.29.2 was recently announced. Homebrew made the upgrade process almost boringly simple on my Mac. This is a case where “boring simple” is very welcome!

More Warp
Warp continues to make my command line work with hledger easier. One minor, but nice feature, is how Warp handles command line recall.

At a “normal” command line, you press the up arrow and see the previous command that you entered. Press the up arrow again, and you see the penultimate command. And so on.

Warp does things slightly differently. When you press the up arrow, you see not only the previous command, but a list of the last five commands that you entered. I find this useful when I am looking for a command that I entered maybe 2 or 3 commands ago. It’s helpful for me to see the last 5 commands in one fell swoop, then pick the one I want. Before I used Warp, I would press the up arrow, see if the command was the one I wanted, if not press the up arrow again and repeat until I found the command. I prefer Warp’s showing me the last 5 commands all at once.

April 6, 2023 — Closing out a fiscal year in hledger
I successfully closed out 2022! I made some mistakes along the way. This was good, since one of the purposes of this website is to make mistakes so that you don’t have to.

Also, since closing out a year means that, well, it happens once a year for me, what are the chances that I will remember everything I need to 12 months from now? I think that future self me will benefit from these notes.

The process
Some background: as mentioned last week, my 2022 hledger file had all the 2022 transactions plus the first 3 months of 2023.

So the first thing was to create an empty 2023 file. Then I copied all the 2023 transactions from the 2022 file to the new 2023 file.

Then, it’s back to the 2022 file to (gulp) delete all the 2023 transactions. Yes, the 2023 transactions are now in the 2023 file, but I still felt some apprehension about deleting the original ones.

Now, it’s time to close out the 2022 year. Time to go to the command line (in spite of my brain first telling me to use an Emacs command — no, “close” is a command line command)!

The first time I ran the command, I noticed that the closing transactions had an April date. Later I figured out that if I had used the “-p 2022” option, it would have given me the date at the end of the calendar year I was closing. No big deal, since you can change the date yourself after you paste it in your hledger file.

Next problem was that I had neglected to note that the current (1.29) version of hledger does “close” differently from previous versions.

In the past, “close” generated both the closing transaction (for the year being closed) and opening transaction (to start the next year). Now, more logically perhaps, “close” just gives the transaction to close the year.

To get the opening transaction for 2023, I ended up using the –open option. Turns out, there is a –migrate option that may work even better next year.

Other things to do with the file for the new year

  • If last year’s hledger file had things like a commodity or accounts declared, copy them to the start of your new year’s file
  • Reconciling won’t work properly unless you remember to mark the appropriate opening balance as cleared. For the second point, in other words, if your opening balance includes the line: assets:MyBank:checking $300.00 = $300.00 Then, if you run a command to show all the cleared checking transactions, the total won’t be correct, because your opening transaction wasn’t marked as “clear.” So, mark the opening balance as “clear” or else you won’t get an accurate total of your cleared transactions.

March 30, 2023 — Getting ready to close out 2022, more on Warp
I am getting ready to close out 2022 for hledger.

Shouldn’t I have done that in January? Or do I have a financial year that ends in March?

The answer for both questions is “no,” at least for the way I work with hledger.

That is, for my personal accounting, I have no intrinsic need for closing out a year. Never closing out a prior year would work for me.

Except for one thing. I sometimes don’t remember how I typed a name of a payee previously. For example, was it “Jones’ Plumbing and Heating” or “Jones and Associates” or something similar? I want to keep names consistent, as it makes reporting easier.

So, as I enter a payee for a transaction, I type the first few letters, in the above case “Jon” and press the tab key to show me every payee I had previously as a payee that began with “Jon.”

So far, so good. However, if there are several years worth of transactions in my history, pressing the tab key brings up unnecessary information. For example, there was a one-time transaction I had 5 years ago, but has never occured since. I don’t need to see that.

Therefore, for me, it’s worth periodically closing an hledger year. Closing out a past year helps reduce clutter.

But April will work just fine in terms of when I close out the prior year.

More on Warp
Last week I mentioned how Warp was working well for me. One additional feature that I just tried this week was using tabs (not the “tab key” but like tabs in a browser). Specifically, I have one tab set up for my hledger work, and another set up for other command line work I do. Previously, I had to change directories when switching from hledger to other work. Now, it’s a simple click on a Warp tab, and I am ready to work on one or the other.

Another advantage is that each tab seems to have its own command history. I haven’t tested it extensively, but it seems that my hledger tab has just the commands I used in that tab. The other tab has only the commands that I used in that tab. Nice touch!

March 23, 2023 — Warping my command line
Warp (https://www.warp.dev/) is my new favorite way to use the command line on my Mac.

What’s to like about it? For one, I really like the command area that stays at the bottom of the screen. Admittedly, this brings back some nostalgia of working with a text editor called Kedit (https://www.kedit.com). Such a powerful program, one that unfortunately didn’t succeed in the marketplace.

Emacs, a much more widely known program, also puts a “permanent” command area at the bottom of the screen. I find it helpful to have separate command and output areas.

Another thing to like is that Warp organizes each output of a command into a separate block. This has the advantage of making it easy to copy the output of one command, or even the block of output along with the associated command with just a single click.

On my to-do list is to learn some of the additional features. For example, there is an AI mode, where you type want you want to accomplish, and Warp suggests a command to do so. There are several more interesting features, which I hope to explore at some future point.

However, I can say right now that Warp works so well for me that it has completely replaced the normal command line.

Currently, Warp exists only for the Mac, but Warp’s web site says they are developing versions for the web, Linux, and Windows.

One caveat, at least for some people, is that Warp is not currently open source. If that’s a problem for you, you will want to wait until Warp comes out with an open-source version.

For me, though, Warp is a program that puts a gentle smile on my face when I need to turn to it.

March 16, 2023 — A brew trick for upgrading hledger
Here is a brew trick that I just learned, one that was helpful in upgrading hledger. Specifically, it is to run the “brew update” command before running “brew outdated.”

That is, I had recently seen the news that hledger 1.29 was available. But would it be available in brew, the program I use to upgrade hledger? I used the “brew outdated” command to list all the programs that needed upgrading, but hledger was not on the list.

It occurred to me to first update brew itself, then check again for outdated programs. After getting the latest update to brew, it now showed me that there was indeed a new version of hledger available.

I then proceeded with upgrading all the outdated programs, including hledger.

Once brew finished, I checked hledger, to make sure my system was running hledger 1.29. This checking wasn’t because of pure paranoia; I have seen cases where a new version of a program gets installed on my computer, but for whatever reason, the old one is still running by default. Happily, hledger reported it was now version 1.29. Under the motto of “trust but verify,” I ran a sample hledger command, just to make sure things were running correctly. Which they were, so success!

The lesson learned was not to totally believe the output of “brew outdated” unless you have just updated brew.

March 9, 2023 — Steps toward an hledger vision
Here is a vision that I have. It’s helping people to find out how useful hledger can be.

That’s why I started this website/blog. As I was reviewing my vision, I realized that the implementation was lacking.

My original plan was to write an entry when an idea struck. Upon taking stock, however, it was obvious that the entries were too spaced out. Sometimes there were months between entries. Surely, I had things worth sharing, but for whatever reason they weren’t making it to the website.

So here’s the change. Thursday is now a publishing day. I like to think of it as “Thoughtful Thursday,” where I offer something useful from a users perspective.

This will mean a weekly schedule for new content. I realize that there may be times when life happens, and it is not possible to come up with something. If that happens, I will at least try to make an entry saying so. But I hope that those will be rare.

hledger has been a great tool for me, and I want to help others learn more about it. So, hello to Thoughtful Thursdays.

March 2, 2023 — Fixing data entry faux pas faster
Here is a tip that has improved my hledger workflow.

Some background: As mentioned in my Needful negativity (February 5, 2022 entry below), I enter salary information in two stages. The first is to enter information with only the deposited amount as the correct figure. All the other line items in the entry, such as federal and state withholding are entered as estimated figures. The reason for this is that I don’t have immediate access to any of the line items except the deposited amount. I want to reconcile the account where the money was deposited within a couple of days after the event, rather than waiting several days later when I have the complete information.

The second step occurs several weeks later, when in one fell swoop I change the estimated amounts for the actual figures. It doesn’t have to be several weeks later, but there is a process involved in getting the other information, so I usually put it off for some time. In any case, I have already reconciled the amount deposited, which was of immediate import.

And when I finally get around to making the updates, I occasionally make typos. I get a sign wrong. I copy a number incorrectly. The usual suspects.

If I am aware of an error after making changes to several transactions (i.e., several paychecks), it takes some time locate the bad entry in my hledger file. I am not talking about a huge amount of time; it’s just that there was room for improvement.

Here is the change that I made:

  • I make all the needed changes to one entry
  • I save the file
  • I switch windows to one with the command line (note: if you don’t know how to use the Windows Alt + tab or the Mac Command + tab, it’s a great timesaver)
  • I run any hledger command, usually just by pressing the up arrow and enter
  • hledger will either run the command (telling me that there is no error) or give me an error message
  • If there is an error, I switch windows back to the file with my hledger data. Since I just finished editing the transaction with the problem, I don’t have to search for the problematic transaction. It’s right there for me to edit. I repeat the above steps (i.e., make the change and make sure my “correction” didn’t introduce a new error!)
  • On the other hand, if there is no error, I go to the next transaction and repeat the above steps until I have updated all my transactions

In summary, after I make the updates to one transaction, I check to see if there is an error. If so, I correct it on the spot. If not, I update the next transaction.

Honestly, I am not sure how much total time it saves, but perhaps the main benefit is that the above is an easier workflow. If there is an error, my cursor is already at the transaction that needs correcting. I make the correction, test again, and move to the next transaction.

October 24, 2022 — How much did I spend using credit cards?
How much did I spend this year using credit cards?

To get this answer, I started by examining the structure of my hledger data files. I noticed two things.

First, any credit card expenses that I have are listed under “Liabilities,” such as:


Second, there are only credit card transactions under “Liabilities.”

Given the above, the following hledger command was the first one that I found that appeared to work:

: hledger -f 2022.hledger areg Liabilities “amt:<0”

Note two things about the “amt:<0” portion:

  • If you don’t include “amt:<0”, any payments you make against credit cards gets subtracted from your expenses. Since credit card expenses are all negative figures, use the “amt:<0” to get just the expenses.
  • You want to have quotation marks around the “amt:<0”; otherwise, your shell is likely to fail to properly execute the command.

Finally, if your hledger file has any starting balances or carry forward amounts for your liabiities, these will be included in your total. This may or may not be what you want. For example, my hledger file has an opening balance that I don’t want included (as I want only the actual expenses this year on the credit card). Therefore, I modified the command to the following to not included the opening balance:

: hledger -f 2022.hledger areg Liabilities “amt:<0” not:desc:opening

September 19, 2022 — hledger 1.27.1 now available via brew
That was fast. Just 5 days ago I upgraded to hledger 1.27. Now 1.27.1 is available via brew for Mac OS.

I wouldn’t have even known, except I was using brew for something else when it informed me that I had 4 outdated programs. (OK, brew calls them “packages” rather than programs.) In any case, brew informed me that I could use the following command to see which ones were outdated.

: brew outdated

So I entered the above command, saw that hledger 1.27.1 was available, and quickly upgraded so that I have the latest and the greatest.

My thanks to all the people who keep hledger up to date and running!

September 14, 2022 — hledger 1.27 available now on brew
Yes, hledger 1.27 has been out since the first of the month. However, since I use brew for my hledger upgrades, I have been waiting for brew to have 1.27 available. I just saw today that brew was ready with version 1.27.

The process was remarkably fast. Not only that, but brew was forgiving of a mistake I made (specifically, I told it to install hledger when I should said to upgrade it). In addition, after finishing the installation, brew reported that it removed the files for the previous version of hledger. No need to have those around, at least in my case.

There is a certain magical beauty when software runs correctly, quickly, and helpfully…

August 29, 2022 — Automatically updating your hledger info in Emacs
I work almost daily with hledger, so I nearly always have Emacs open to show my working hledger file. One common thing I do is add new transactions to the file. When I add transactions, say with the hledger “add” command, the hledger file gets updated. However, what Emacs shows on your screen doesn’t get updated until you specifically tell Emacs to do so.

In Emacs speak, updating what is on your screen to match changes made to a file is called “reverting.” For a long time, I was reverting my Emacs files manually. This works, but is an extra step everytime I make a change to a file.

However, I ran across a neat way to make Emacs automatically do the reverting. This means that now everytime I use “add” to add a transaction, the moment my hledger file changes, Emacs updates what is on the screen to match.

Specifically, I did this by adding the following line to my .emacs file:

: (global-auto-revert-mode 1)

Now my hledger information in Emacs is automatically updated without my having to do an extra step.

June 30, 2022 — Remember the future!
Just because something works now doesn’t mean that it will work in the future. This happened to me with the categories I used in hledger. My naming convention worked for a while, but after some changes to my banking, some problems emerged.

Before looking specifically at accounting categories, let’s consider labels or signs in general. For example, there is a school near me that several years ago changed their parking restrictions. They replaced the sign with the old rules and added above the new rules a second large sign that read “NEW.” That worked for a while. Anyone coming into the parking lot couldn’t miss the large bright orange “NEW” sign that called attention to the new rules on the sign below it. However, fast forward several years to today, and the “NEW” sign is still there.

What purpose does the large orange “NEW” sign continue to serve after multiple years have passed? It’s now an old “NEW” sign. What would happen if the school needed to change the parking restrictions again. Would it put up a new sign with the rules and change the “NEW” sign to “NEW NEW”? In retrospect, it would have been better if they had added a sign that said “Effective Sep. 1, 2014.”

Note: I have seen signs that say something like “Effective Sep. 1,” but the problem is, how do you understand the sign when the date is 9 months later? Which Sep. 1st are they referring to, the one from last year or the one in 3 months? In short, it’s easy find something that works for the moment, but the real trick is finding something that works both now and in the future.

What does this have to do with hledger categories? They are like signs for you and for others who will see your hledger reports. So when thinking about categories for hledger, ask yourself:

  • Does this work now?
  • Will it work in the future? For example, if you have one checking account, the following categorization can work: : Assets:Checking However, will you ever open an additional checking account in the future? If so, what will you call it? For example, assume that the above account is with Acme, and the new account is with BigBank. You can name the new account : Assets:BigBank:Checking Notice, though, that the first account, Assets:Checking, is now ambiguous since you have two checking accounts. You can still successfully run your hledger reports, but you will always have the mental step of remembering that Assets:Checking is your first checking account, the one with Acme, not BigBank. There is still more to consider, though. What if you are using hledger to track the expenses for a group of people, and two people have checking accounts with Acme? One solution is to add the name of the person, as in the following example. : Assets:Acme:Mary Checking The above is good if you think of the correct category names ahead of time. However, what do you do if you realize you need to change your hledger account names after the fact? This exact problem happened to me. One of my hledger categories, one that I thought would never be duplicated, went from one to three. (Remember, one of the purposes of this website is for you to learn from my mistakes!) As I was thinking of possible solutions, I remembered that the sed tool could be very helpful for this. After a few false starts, I found a specific command that would work. First, let’s assume that I need to change two account names in the file myfile.hledger:
  • Assets:Checking to Assets:Acme:Mary Checking
  • Assets:BigBank:Checking to Assets:BigBank:Fred Checking If you need the above changes, here is a sed command that will work: sed ‘s/Assets:Checking/Assets:Acme:Mary Checking/; s/Assets:BigBank:Checking/Assets:BigBank:Fred Checking/’ myfile.hledger > myfile.new

Notice that I output the sed command to a new file (myfile.new). This way, I can check the new file to confirm everything works. If there is a problem, my original file is still intact. On the other hand, if there are no problems, I rename the original file myfile.hledger to something like myfile.bak (in case I ever need the original file) and then rename myfile.new to myfile.hledger.

The moral of the story: Use some careful thinking about the future when you create your accounting categories, but if you make a mistake, sed can get you back on track.

June 27, 2022 — Fooled by “brew update” vs. “brew upgrade”
The commands “brew update” and “brew upgrade” look so similar to me. As a result, I find it hard to remember that “brew update” is basically to get the latest version of brew, while “brew upgrade” is to obtain the latest version of a program installed by brew.

Apparently, the software engineers had me in mind when they designed brew. After I typed in the erroneous command, I was politely told:

: Error: This command updates brew itself, and does not take formula names.
: Use brew upgrade hledger instead.

Next, I entered the correct command, and was rewarded with the latest version of hledger.

Of course, the above works only if you used brew to install hledger in the first place. If you have hledger installed, but you can’t remember if you used brew to install it, run the command:

: brew list

If “hledger” appears in the output, then brew installed hledger on your system at some point in the past.

May 31, 2022 — hledger helps detect unauthorized withdrawal
OK, the title does have a clickbait element to it, but it is basically true.

Here is what happened, as best I can tell from my account statement and conversations with the people who work at my financial institution. One Saturday, a few months ago, someone walked into a credit union several states away and made two cash withdrawals against our account. It somehow didn’t matter that we didn’t have an account at the credit union from where they withdrew the money. It also didn’t matter that the person making the withdrawal didn’t have authorization to make a withdrawal from our account (again, our account was not at the place where they withdrew the money). Just the same, the person got the money, and it came out of our account.

The good news is that one of my hledger habits is to regularly reconcile my accounts. This a worthwhile habit for a couple of reasons. For one, if I wait too long before reconciling and there is a problem, it seems to become exponentially more difficult to locate the problem the more transactions there are that I am reconciling at a time. So, I save myself frustration by having only a few transactions to reconcile at a time. Also, if there is an erroneous transaction, such as the one above, it’s better to know about the problem and tackle it sooner rather than later.

In this case, I noticed the withdrawal the very next day as I was reconciling the account. At first, I thought it might be some electronic payment that I wasn’t remembering, but the more I looked, the clearer it became that there was something wrong. So, I called our financial institution to consult with them. When they answered the phone, they were very good about working to verify who I was before they could discuss details of the account. The irony is that after they asked me a number of questions they politely informed me that they could not verify my identity, so they could not discuss the account over the phone with me. Interesting that one person can walk into a credit union and successfully pretend to be me, but the next day I couldn’t prove to be me! Well, if an error is to be made, I admit that it is much better to be too cautious about accepting one’s identity than the alternative. I just wish the credit union in the other state had been as cautious as my financial institution.

To wrap up the story, it took an in-person visit at our financial institution to get things back on track. We filled out the necessary paperwork, and our financial institution made good the missing money. They also made a modification to our account that they said would help prevent such things from happening in the future. While the unauthorized withdrawal was frankly, scary, I am glad that I am regularly reconciling my accounts and thereby staying on top of what is happening, financially speaking.

February 5, 2022 — Needful negativity
One of the reasons that I am a fan of hledger is not because I have mastered all the ins and outs of the program. Rather, it’s because hledger helps me, including when I make mistakes.

As an example, I was recently updating a posting for my salary. In this case, I needed to update a posting that I previously entered, but one that had the correct information only for the amount deposited in my checking account. Why was that? At the time I originally created the posting, I didn’t have easy access to the other numbers (gross salary, various deductions). So, I satisfied myself with having the correct number for the checking account deposit amount, which would let me reconcile my checking account. However, I would have to come back later and put in the correct numbers on the other lines.

So my entry would have looked something like the following, except I am using dummy information. (Dummy information keeps me from feeling like a dummy were I to post my real numbers on the internet for all the world to see.)

: 2022-01-20 My Salary
: Income:Salary:Me ; needs correcting
: Expenses:State tax $100.00
: Expenses:Federal tax $300.00
: Expenses:Social Security $30.00
: * Assets:MyBank:Checking $700.00

In the above, I have reconciled the amount deposited in my checking account. I don’t know what my gross income or the 3 deductions were, but those can be corrected later. I have put a comment in the posting to easily find it in the future. That is, I can use the search function to find where I have made a note about a correction needed.

After a sufficient amount of procrastination, I decide it’s time to put in the correct figures for the rest of the posting. I dig around, and I find the following in a pay statement:

: Gross income = $1,200.00
: State tax = $100.00
: Federal tax = $350.00
: Social Security = $50.00
: Net income = $700.00

So, I edit the posting in hledger to read:

: 2022-01-20 My Salary
: Income:Salary:Me $1,200.00
: Expenses:State tax $100.00
: Expenses:Federal tax $350.00
: Expenses:Social Security $50.00
: * Assets:MyBank:Checking $700.00

I run one of my hledger commands, and up pops the following (anonymized) message:

: hledger: “/Users/xxxxx/Documents/hledger/blog/example.hledger” (lines 1-6)
: could not balance this transaction:
: real postings all have the same sign
: 2022-01-20 My Salary
: Income:Salary:Me $1,200.00
: Expenses:State tax $100.00
: Expenses:Federal tax $350.00
: Expenses:Social Security $50.00
: * Assets:MyBank:Checking $700.00

That’s right, I forgot that income needs a minus sign. One quick edit changes the above to:

: 2022-01-20 My Salary
: Income:Salary:Me -$1,200.00
: Expenses:State tax $100.00
: Expenses:Federal tax $350.00
: Expenses:Social Security $50.00
: * Assets:MyBank:Checking $700.00

As in the January 23 entry below, the hledger help message was what I needed to quickly get back on track. And I like getting back on track quickly. It doesn’t happen all the time, but when it does such as in the above example, it’s a good feeling and worth noting.

January 23, 2022 — hledger help helps
The hledger error messages have been very helpful to me recently. I am not sure if they have gotten better over the years or if they have always been there, but some recent ones have been immediately helpful.

For example, I was using hledger add today, and I entered at date as 202-11-10, when of course I meant 2021-11-10. After pressing enter, I immediately saw:

: A valid hledger smart date is required. Eg: 2014/2/14, 14, yesterday.

In one concise line I see the cause of the problem (invalid date format), what date format should be used (a smart date), and three examples.

Speaking of the examples, if you are not aware of using a single number, such as “14” to indicate the 14th of the current month in the current year, it’s a handy timesaver.

October 16, 2021 — What I sed
In my last post (see October 10, 2021 below), I created an hledger report that showed what we spent our money on when we bought something from Amazon and I labeled it as a Home expense. This was useful to me because I use Home as a very general category, and the fact that I bought something from Amazon for the home gives me very few clues about what it could be.

My report now shows me transactions such as the following

: 2021-05-02 Amazon
: Expenses:Home $11.61 ; cards
: * Liabilities:CreditCard $-11.61

This is good and useful. Even better would be to generate a report that had just the line with the Home expenses. That is, I don’t want to see the line telling me who the vendor was, since in every case it’s the same. Similarly, I don’t need the line telling me where the money came from for the purchase. All I want to see for each transaction is the line

:  Expenses:Home               $11.61  ; cards

In addition, this should work even if the purchase had items in more than one expense category.

: 2021-05-02 Amazon
: Expenses:Home $11.61 ; cards
: Expenses:Auto $10.00 ; car wash
: * Liabilities:CreditCard $-21.61

That is, even with the above, the report would include only the Home expense:

: Expenses:Home $11.61 ; cards

The sed utility is one way to deal with this. That is, if you have a list of transactions such as

: 2021-05-02 Amazon
: Expenses:Home $11.61 ; cards
: Expenses:Auto $10.00 ; car wash
: * Liabilities:CreditCard $-21.61

The following sed command will show just the lines that include the word “Home” in them.

: sed -n ‘/Home/p’

Well, almost. You either have to create a file with hledger

: hledger print payee:Amazon > myfile.txt

and then give that file to the sed command to operate on

: sed -n ‘/Home/p’ myfile.txt

Or you can feed the hledger command output directly into sed with a pipe:

: hledger print payee:Amazon | sed -n ‘/Home/p’

The first option (creating a file and then processing the file with sed) I find conceptually easier. That is, I don’t use pipes that often, so I have to stop and think exactly what is happening when I use a pipe. It’s easier for me to understand if I first create a file and examine the contents of the file before running it through sed.

The second option (using the pipe) has fewer steps, so it’s a better long term solution.

The report is in very good shape now. I can see all the Amazon expenses categorized as “Home” in a short list because there is only one line per transaction.

There are still a couple minor improvements that I will try to make. For example, can I include the date in the output, but still have just one line per transaction? Is there a way to total the expenses? Stay tuned!

October 10, 2021 — What happens in hledger when an infinite category meets an infinite vendor?
Some of our budget categories are perfectly communicative. For example, if I see a transaction with the category Expenses:Utilities:Electric, I know it’s a payment to our electric company for an electric bill.

Other categories are slightly more ambiguous. For example, Expenses:Automotive includes gasoline, auto repairs, and even parking costs. Thus, it’s not 100% clear from the category exactly what we spent our money on.

And then there is Expenses:Home. Basically, these are miscellaneous expenses involved with running a household. Here are some of the disparate items in our Expenses:Home account:

  • postage stamps
  • a fry pan
  • greeting cards
  • a washing machine Some of the above transactions are easily explained by seeing who the vendor was. For example, if I see a home expense from our local appliance store, I know it’s an appliance. And since we (thankfully!) don’t buy appliances that often, a quick look at the date will cause me to say “That’s the clothes washer.” Similarly, if I see a home expense from the USPS, it’s likely stamps. However, one online vendor we use sells almost every kind of item. So, if I see a home expense from Amazon, it could be anything. My formula to desribe this is: : An infinite category (home) X an infinite vendor (Amazon) = zero specificity. How to fix this? First, I used a comment to identify the Amazon home expenses. So instead of: : Expenses:Home $11.61

I now have:

: Expenses:Home $11.61 ; cards

Now at the command line I can enter:

: hledger -f print Home payee:Amazon

The output includes transactions such as:

: 2021-05-02 Amazon
: Expenses:Home $11.61 ; cards
: * Liabilities:CreditCard $-11.61

This looks good, except for two problems. First, it prints the whole transaction, when all I need is the line that has the price and the comment. Second, some Amazon transactions are for multiple items, some categorized as home and some other categories. I want to see just the lines with the home expenses

The solution will appear in the next posting.

[This post was edited to add the example output of the print command.]

September 28, 2021 — Expenses vs. Budget
One of the benefits of keeping track of your expenses should be that you learn something. One particular bit of education comes from comparing your actual expenses against your budgeted amounts.

I find two ways of comparing expenses useful. The first is the more obvious one: compare expenses to date vs. budgeted amount to date. For example, for January how much did you spend on groceries versus how much did you plan to spend? If you are spending more, what needs to be changed? Increase the budget for food by deceasing another category? Change your shopping habits to buy more beans and rice and less filet mignon?

Using the command line, you would enter something like the following. It’s not shown below, but in my case I have to specify my data file and my budget file explicitly. I believe you can have both in the default file, but I don’t have mine set up that way.

hledger bal Expenses –budget -b 2021-01 -e 2021-02

One of the lines of output from the above command might look like:

Expenses:Utilities:Cell phones || $44.81 [ 90% of $50.00]

This tells me that for January I spent a bit less than budgeted on cell phone.

The above works fine for items that you regularly purchase, whose expenses are spread out evenly throughout the year. However, for lumpier purchases, I have found something that works better. Specifically, I compare the amount expended to date against the yearly budget.

The command to do this would be something like:

hledger bal Expenses –budget

Running the above command at the end of September might tell me that I have spent 41% of my budgeted money for gifts. I can quickly see the total amount budgeted and know how much is available for gift giving the rest of the year, including December, when we usually spend significantly more on gifts compared to other months.

In short, make sure that budgeting pays you back with an education.

August 30, 2021 — What I learned from my first recorded transaction
The very first plaintext transaction I ever recorded is dated August 3, 2015. This was for a museum visit, and it occurred when we were on vacation. As I entered my first plaintext accounting transaction, I got to the point where I needed to decide what category the expense was.

Let’s see, museums are educational, so perhaps it should be an educational expense. That didn’t seem exactly right, as there was definitely a strong recreational component, too. Hey, we were on vacation and doing something because it appealed to us. So, perhaps it should be categorized as entertainment. That was closer, but by the same reasoning just about everything we spent money on during a vacation ultimately could be thought of as entertainment. For example, we buy gas so that we can travel to our vacation destination. So the gas expense is entertainment?

What I finally decided on, was to have a category called “travel.” So, if we go on a trip, meals, lodging, gas, and even that museum visit are categorized as a travel expense. Also, the travel expense category is inclusive enough that it still works if the trip is not a vacation trip, such as to help a relative move to a new place.

Obviously, there is no one right way to do decide which category an expense is, but six years later the travel category still works for our household.

August 15, 2021 — What are the basics that hledger command line users should know?
As I write about hledger command line usage during the dog days of summer where I live, some people will say that I am barking up the wrong tree. That is, you don’t need the command line to work with hledger, doggone it.

Very true! But if you want to use the command line with hledger, there are a few basic things that you should know.

If you are using bash, here are three videos that I created that cover the basics of what I believe every command line user of hledger should know:

  • what files are in your current directory: https://www.youtube.com/watch?v=uW4QMqNXl6U&t=13s
  • how to move from one directory to another: https://www.youtube.com/watch?v=_vaD1GYDMgI&t=2s
  • how do diplay what’s in a text file: https://www.youtube.com/watch?v=ToCZjcCRHyE&t=13s

Once you are comfortable entering some commands on the command line, you should learn some shortcuts to avoid retyping:

  • the up arrow retrieves the last command
  • continuing to press the up arrow retrieves each prior command
  • you can edit a previous command (e.g., add a word or delete something) befoe you press enter to execute the command
  • hledger commands have abbreviations. For example, “register” can be appreviated “reg” on the command line

There’s a lot of command line usage that can be applied to hledger. And much of what you learn about the command line can be applied in many other situations.

To sum up: if you are going to work with hledger on the command line, there is some basic knowledge really worth sinking your teeth into.

July 25, 2021 — the secret ingredient for a useful income statement report
The generic income statement report is one I frequently run, because it’s so useful. But there is one option that makes it especially useful.

Specifically, specify -S, to sort from largest to smallest subtotals. Without the sort, the expense categories appear in alphabetical order. Not bad, but seeing the categories ranked by amounts makes it easier to get a grasp on what is more significant and what is less significant. Let’s face it, if your Expenses:Zebras subtotal is relatively large, shouldn’t it be listed near the top?

In short, the income statement report, using the -S option is a heavy hitter in making clear what is happening with our household expenses and income. It helps focus in on the larger line items, the ones that potentially can make the greatest difference.

July 13, 2021 — the hotdog eating contest
In language learning, one milestone is when you dream for the first time in the language you are studying. I’m not sure if such a milestone applies to financial tracking, but that is what happened to me. That is, I dreamed that I was logged into my bank site, finding new expenses to add to my recorded transactions. Then I saw $315.00 my wife had spent to enter a hot dog eating contest. I asked her about this unusual expense.

This brings up an interesting point. One of the benefits of tracking your expenses is that it can help you communicate with people you share your finances with. However, the way that you ask a question can make a big difference. For example, if good communication is the goal, avoid asking something like the following:

  • Why in the world would you spend that much money to enter such a ridiculous contest?
  • Why didn’t you tell me about this expense ahead of time?
  • Is it worth spending our money on that?

I find it very easy to ask a question like one of the above. And even if I find better words to use, my tone and body language are probably communicating that I think it is a ridiculous expense.

I am not an expert on what best to say, but it is probably something like:

  • Tell me about the contest. Commentary: for this to work, I am going to need to get the tone right. That is, it has to be genuinely curious. Also, I am going to need to listen without interruption. Does this mean that I have to agree? Absolutely not. But if communication is the goal, I need to understand what is happening with the other person.

What happened in the rest of my dream? When I asked her about the expenses, she explained that they were to cover the costs of the things needed for the contest. In my other-world state of consciousness, this made sense, and that was the end of it. I am glad, though, when I woke up to find out that the expense wasn’t real!

The moral of the story: hledger can help us if we have a dream to communicate, but it is up to us to communicate well rather than poorly.

July 12, 2021 — forward with hledger and backward with Emacs
I successfully upgraded my version of hledger. Brew helpfully made the change to version 1.22. It also upgraded a ton of other programs. This was because I had used the command

brew upgrade

If you don’t specify a program to upgrade, Brew updgrades everthing on its list.
In my case, “everything” included Emacs. Unfortunately, my Macbook refused to run Emacs after the upgrade, complaining about not being able to verify the new program.

This is not good, as I use Emacs for my hledger data files. Fortunately, there was a fix. It was something like: System Utilities, Security & Privacy, General tab. At that point, there was a message at the bottom of the window referring to the problem with Emacs and asking me to OK running the program.

Now Emacs is running fine again.

Why am I a fan of hledger?
What I do with my finances matters.

If I really believe that — and I do — then it is important to know what is
happening with my finances.

There are two types of “knowing.” One is the general impression that I have
about what happened with my finances. This requires no particular effort but
is often hazy, missing key information, or just plain wrong.

The second type is to know what actually happened. This requires a
bit of work. But the payoff is that you have accurate information
about your finances rather than an erroneous impression.

I use a tool such as hledger so that I can accurately answer questions
such as:

  • Where did my money go?
  • How is my spending lining up with my values?
  • How am I doing in terms of moving toward my goals?

In short, what I do with my finances matters. And hledger gives me accurate, useful information about my finances. Therefore, I am a fan of

What will you find on this website?
This is a user’s view of hledger. I’m not an accountant or a
bookkeeper. In fact, I have never even taken a course in accounting
or bookkeeping. I simply use hledger to get a better handle on my finances.

Here you will find real-life examples of

  • what I am doing.
  • what my mistakes are. (Let me make the mistakes so that you don’t
    have to!)
  • what is working for me.

Where can you find out more about hledger?
One of the best places to start is with https://hledger.org

Leave a Reply