Menu Home

Accounting in Plain Text, Part 2

Using hledger’s Built-in "add" Command

When you first install hledger, you literally start with a blank slate–or in this case, a blank journal file. There are a couple of ways to add journal entries. One is to use hledger’s built-in add tool, which you can start by typing hledger add at the command prompt.

The add tool asks you for a series of inputs, which looks like this:

This, in turn, produces the following entry in the journal file:

2019/02/25 initial deposit
    assets:cash:checking:bank 1234             100
    equity:opening blanace                    -100

You should notice a few things here:

  1. hledger formats its journal dates as YYYY/MM/DD. When entering data using the add command, however, you have more flexibility. By default, the program assumes you want to use today’s date. But let’s say you want to enter an item from the previous day. You could simply enter the month and date (2/4) or even just type yesterday. The add program will interpret what you mean and format the data for the journal appropriately.
  2. Every entry in the journal must involve at least two accounts. (This is double-entry bookkeeping, after all.) It doesn’t matter what order you enter the accounts. And hledger does not come with any preset chart of accounts. It is up to you to decide what accounts are necessary. I will discuss this in greater detail in my next post.
  3. In the example above, I did not have to enter a dollar amount for the second account. The add program inserted a default amount equal to the negative of the amount for the first account. This makes it easy to ensure your books are properly balanced.

Using the add command is completely optional. And it is also limited to what it says on the proverbial box. You cannot use add to modify or delete existing journal entries. To do that, you need to open the journal file directly with a text editor.

One final note for now on add: It has an auto-complete feature. So if you start making a new journal entry that appears similar to a prior one, the program will use the earlier data as a set of defaults:

Date [2019/02/25]: 
Description: client payment
Using this similar transaction for defaults:
2019/02/25 client payment
    assets:cash:bank 1234              50
    income:writing:acme               -50

Account 1 [assets:cash:bank 1234]: 

Editing Journal Files in Pluma

Every Linux-based operating system and user interface has at least one (and often multiple) text editors included. In Ubuntu MATE, the default editor is Pluma. Here is what the sample journal I started above looks like when you open it with Pluma:

Notice there are line numbers. These are not part of the journal file itself. Rather, they are displayed as part of the Pluma interface. You can turn the line numbers off by going to Edit -> Preferences on the menu bar if you wish. I prefer the line numbers personally, as it can help keep in keeping track of journal entries, especially when you get into the thousands of lines.

How to Properly Format Journal Entries

Hledger has one basic rule when it comes to journal entries: There must be at least two spaces between the name of the account and the amount. To illustrate what I mean, I typed the following entry by hand into my sample journal using Pluma:

2019/02/25 client payment
    assets:cash:bank 1234 50
    income:writing:acme -50

As you can see, I only put one space–not two–between the account names and the amounts. So when I then tried to run another hledger command from the terminal emulator, I received this error message:

hledger: could not balance this transaction – can’t have more than one real posting with no amount (remember to put 2 or more spaces before amounts)

You will also get an error message if there is an unbalanced journal entry. Let’s say I modify the example above as follows:

2019/02/25 client payment
    assets:cash:bank 1234    50
    income:writing:acme     -60

If I then run an hledger command from the terminal, I get:

hledger: could not balance this transaction (real postings are off by -10)

An easy way to avoid this problem, at lest for simple journal entries, is to leave the second amount blank, like this:

2019/02/25 client payment
    assets:cash:bank 1234    50

When you run an hledger command on this, the program automatically fills in the missing "-50" amount on the second account to ensure the entry is balanced.

Using Three or More Accounts in a Journal Entry

So far my examples have been for entries with just two accounts, one debit and one credit. But hledger allows you to use as many accounts per entry as needed. For instance, I have clients that typically pay me using PayPal, which deducts a transaction fee. I can record this as a single journal as follows:

2019/02/25 client payment
    assets:cash:paypal 		50
    expenses:paypal fees	-1.65

Once again, you don’t need to enter a specific amount for the third account, as hledger will balance it automatically.

Making Notes in the Journal

Depending on how you like to keep records, you may want to put some "marginal" notes to your journal. This is easy enough to accomplish. You can insert a comment into the journal using a semicolon (;). A comment refers to information that hledger disregards.

Comments should be inserted either on blank lines or following amounts. Here is an illustration:

; this is an example of a comment.

2019/02/25 initial deposit
    assets:cash:checking:bank 1234             100
    equity:opening balance                    -100

2019/02/25 client payment
    assets:cash:bank 1234              50  ;  invoice 2019-01

Coming Up in Part 3

In the next post I’ll go into more detail about how to create a chart of accounts when working with hledger. Although hledger is a general purpose accounting tool, my focus will be on keeping books as a self-employed professional in the United States who needs to file a Form 1040, Schedule C, every year with the Internal Revenue Service.

Categories: Linux Tutorials

Tagged as:

S.M. Oliva

Blog ghostwriter

%d bloggers like this: