Hledger: Robust Plain Text Accounting

I'm hledger's lead developer, thanks for the mention. If you have any questions or hit any snags trying it out, I'm ready to help. Critique of product, docs etc. is welcome. Last time (2017) we got 2 out of 41 comments about hledger, so I'm hoping for a few more. :) https://hledger.org/release-notes has the (software) changes since then. Our chat is #hledger on Freenode: http://webchat.freenode.net/?channels=hledger

These ledger formats have what feels to me an overly verbose multi-line structure for each transaction.

For 20 years, I have been using a format that combines a diary and ledger. The 'to' and 'from' accounts are either bank/asset accounts (sav, cc, hl for home loan, ...) or spend categories (snack, shopping, clothes, ... ). Each year I finish 31 December with a `# Closing balances` section for each bank/investment/pension account, then start a new text file `2019.txt` with an `# Opening balances` section before 1 January's entry.

Here is a typical day's format:

  # 2019-05-27 Mon
  2.50    sav>lunch    Cafe Nero - Coffee
  100.00  sav>cc       Transfer - Credit card repayment
  amt     from>to      forex: shop - desc [txn #] 
  # Diary
  * <topic> - <what>
  * Times - Sleep 01:00-06:00 5h. Run 45m. Work 08:00-18:00 10h.
  * Work - Meeting with xxx on xxx. We agreed to xxx.
  * Friends - Lunch with xxx
  * Note - Running shoes are Asics GT-2000, size 48, model T500N.
  # Links
  * Hledger: Robust plain text accounting - https://news.ycombinator.com/item?id=20012499

When I got married, all our accounts switched to joint ones. I didn't want to track my my partner's side of our spending. So these logs became more a personal diary than a fully reconciled ledger. Anything I want to remember long-term goes either there or secured in a password safe.

See also https://plaintextaccounting.org for more on the broader ledger ecosystem.

Personally I prefer beancount, incredibly pluggable in python (imo a friendlier language to haskell), additionally much stricter in multiple aspects. Been maintaining my ledger with ledger-cli and then beacount for 10 years now.

I've recently come across two systems that use hledger for processing bank statements: https://pauley.org.za/hledger-flow/ https://github.com/adept/full-fledged-hledger/wiki

They treat the statements as the single source of truth, with preprocessing and rules that can be used to turn them into hledger journals.

I would appreciate a small section on the README file that explains how to compile the program, what are the requirements (e.g., what debian packages to install), and a minimal cli use case.

Also, running "make" prints a daunting 96 lines of text of which the last 50 (the ones that you get to see) are mostly useless. If I run "make build" it starts to download stuff from the internet, which I find extremely impolite, as I already downloaded the source code. What is the point of not including all the neeedded source code in the source distribution?

Discussion from 2017: https://news.ycombinator.com/item?id=15818682.

If you're using Emacs and are not familiar with double-entry accounting this video is a good introduction : https://www.youtube.com/watch?v=cjoCNRpLanY (it's based on ledger not hledger)

Does Hledger support encrypting the ledger file? I don't mean placing the ledger in an encrypted container and mounting/unmounting as necessary, but I guess 'natively' as part of the file (think an encrypted Excel document).

I'm a GnuCash user, but my biggest gripe is not being able to encrypt my accounting file. I'd love to have it sync across my devices via x cloud platform, but I'm always paranoid about uploading anything that isn't password protected. If I was able to do that it'd be the push that gets me to switch from the GnuCash GUI to a plaintext account.

Maybe there's some other way I haven't thought of without a high barrier to entry like constantly mounting and unmounting an encrypted container to make changes.

I just spent the last week reconciling my books, using my scores of Excel files as a source, moving them to ledger.

I learned rudimentary double-entry accounting in high school, and I love that ledger enforces it so that I can be strict about my tracking. I still have to figure out how to produce balance sheets and income statements so that I can confirm that my accounts are balanced correctly. Honestly wish I had done this sooner.

Edit: Looking at beancount again, I should just use that instead of ledger. Ledger's simple, elegant, and nice, but I'm a Python guy, and I should just use what I know.

I've used the original ledger [0] for a few years to track my day-to-day cash flow and appreciate the simplicity. I create a new file every year and manage it with standard Unix tools, plus a few shell and Python wrappers to make entries and reports a little easier.

The hardest part is just getting started and getting into the habit of maintaining the ledger. Once you start tracking it's difficult to stop! Seeing all of your accounts line up is a reward in itself.

[0] https://www.ledger-cli.org

See also http://hledger.alhur.es/, hledger compiled for the web in a playground (you can also save your stuff to remoteStorage).

Source: https://github.com/fiatjaf/hledger-web

hledger looks pretty amazing, but there are so many dependencies and updates with Haskell programs. Almost every other day I'm updating like 20 Haskell packages for hledger or pandoc when I run a system update. It isn't inherently bad, but never had this issue with a C or Go program.

Hledger is pretty good for basic accounting. I recently had to do some tracking of stocks and lots and forex and the developers decided not to implement lot-based tracking. Which made it impossible to accurately track money.

So back to plain ledger. If I was starting over I'd probably consider beancount. But there's only so much I can do a day.

A ledger should be a database with only select and insert privileges. eg. No update or delete queries should be allowed.

I used to be a heavy ledger-cli user and wrote about my setup here http://nibrahim.net.in/2015/11/07/ledger_and_personal_financ...

I looked into plain text accounting but Swedish bookkeeping/accounting practises forbid practises where past records can be modified. It needs to be append-only. I started developing a command line accounting tool using SQLite and Go but it is only half-finished.

Does it do 'envelope' style budgets like YNAB?

This is exactly how I do my accounting: record transactions in a plain text file, which is processed by the system, resulting in various ledger and account type objects being in a certain state, which can then be subject to queries and reports.

Mine is written in TXR Lisp. It is not released to the public.

All input is recorded via function call expressions, which are of course S-exps. There is only one single macro in the whole thing: def-date-var defines a variable that exhibits different values depending on a effective date context (established by a dynamically scoped date variable). With this we can do things like different tax rates for different periods, without having to introduce such things as parameters appearing in every input item.

> The amounts within a transaction must always sum up to zero. As a convenience, one amount may be left blank; it will be inferred so as to balance the transaction.

I also have transactions that sum to zero. There can be three or more account deltas in a transaction, not only two.

This is not how accounting is taught in North America, though; I came up with it myself.

Inferring one amount is a bad idea. My system throws an exception if the transaction amounts do not add to zero.

However, the entry of items is done via various convenience functions, most of which generate the necessary transactions against all the right accounts. For instance, recording a new asset:

  (record-asset 1 "Discombobulator" :cca-50 ;; ID, description, capital-cost-allowance class
                (date 2017 1 23) ($ 79.99) ($ 4.00) ($ 5.60)) ;; base price, GST, PST taxes.

Different items need their own syntax. I don't want to record a simple purchase of a recurring expense in the same way that I record an invoice.

I bind a new variable when recording an invoice:

  (defparml %inv-0042%
    (new invoice
         number 42
         provider %my-addr%
         client %foo-client-addr%
         remit-to "Kazinator"
         remit-days 25
         date (date 2017 6 30)
         items (list (new time-unit
                          start (date 2017 6 1)
                          end (date 2017 6 2)
                          hours 16
                          rate %rate-foo-client-2017%)
                     (new time-unit
                          start (date 2017 6 5)
                          end (date 2017 6 9)
                          hours 40
                          rate %rate-foo-client-2017%)
                     (new time-unit
                          start (date 2017 6 12)
                          end (date 2017 6 16)
                          hours 40
                          rate %rate-foo-client-2017%)
                     (new time-unit
                          start (date 2017 6 19)
                          end (date 2017 6 23)
                          hours 40
                          rate %rate-foo-client-2017%)
                     (new time-unit
                          start (date 2017 6 26)
                          end (date 2017 6 30)
                          hours 40
                          rate %rate-foo-client-2017%))))

This is then recorded using a plain function call to the convenience function record-invoice:

  (record-invoice %inv-0042% "Invoice 0042 issued to Foo, Inc.")

When the invoice is paid:

  (record-paid-invoice %inv-0042% "Invoice 0042 paid by Foo, Inc."
                       (date 2017 7 31))

To generate a nice HTML invoice, at the REPL, I just call the .(html ...) method of the invoice object, which takes a stream argument.

  1> (with-stream (s (open-file "invoice.html" "w"))
       %inv-0042%.(html s))