hledger fan

RSS feed for this page

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: click here
  • how to move from one directory to another: click here
  • how do diplay what's in a text file: click here

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 hledger.

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,

Author: Robert Nielsen

Created: 2022-06-30 Thu 16:49

Validate