Ignore transactions in ledger-cli

1 November, 2021

Given is a ledger file containing imported bank transactions we want to ignore. Let’s take a pending transaction for example. It has a merely formal character but no mathematical impact. Thus we want transactions having the word pending in the payee line not taken into account from ledger.

2012-03-10 KFC **pending**
    Expenses:Food                $20.00
    Assets:Cash

2012-03-10 KFC
    Expenses:Food                $20.00
    Assets:Cash

Code Snippet 1: example.ledger

             $-40.00  Assets:Cash
              $40.00  Expenses:Food
--------------------
                   0

We circumvent the pending transaction using automated transactions and a complex expression

= @/pending/
    ($account)                  -1

Code Snippet 2: Complex expression in an automated transaction

By prepending 1 with 2, the pending transaction doesn’t get accounted anymore

= @/pending/
    ($account)                  -1

2012-03-10 KFC **pending**
    Expenses:Food                $20.00
    Assets:Cash

2012-03-10 KFC
    Expenses:Food                $20.00
    Assets:Cash

             $-20.00  Assets:Cash
              $20.00  Expenses:Food
--------------------
                   0

The reason lies in the register command. Note that the result from 1 derives from the balance command.

The plain example register on 1 returns:

12-Mar-10 KFC **pending**       Expenses:Food                $20.00       $20.00
                                Assets:Cash                 $-20.00            0
12-Mar-10 KFC                   Expenses:Food                $20.00       $20.00
                                Assets:Cash                 $-20.00            0

Whereas with 2 appended we get this result from the register:

12-Mar-10 KFC **pending**       Expenses:Food                $20.00       $20.00
                                Assets:Cash                 $-20.00            0
                                (Expenses:Food)             $-20.00      $-20.00
                                (Assets:Cash)                $20.00            0
12-Mar-10 KFC                   Expenses:Food                $20.00       $20.00
                                Assets:Cash                 $-20.00            0

Note that the virtual transactions are surrounded by braces.

Summary

By using ledger’s builtin options, we’re able to ignore transactions instead of e.g. deleting them. The applied method uses complex expressions and automated transactions. In ledger terminology, the latter are called virtual transactions. Virtual transactions are evaluated on runtime. They aren’t read from any ledger file. On the opposite, real transactions are transactions that are read from the ledger file. It is crucial to note that virtual transactions can be ignored by using ledger with the real option e.g. ledger -f example.ledger reg --real