draft of new close doc

Close.md

close, equity
Adds a "closing balances" transaction to the main journal file, that brings selected account balances to zero. Also (by default), adds the inverse "opening balances" transaction to a new journal file (creating it if necessary), restoring those account balances as they were in the old journal.

This can be used to bring asset/liability balances forward into a new journal file, or to close out revenues/expenses to retained earnings at the end of an accounting period. More on this below.

_FLAGS

close appends to journal files

This command appends one new transaction to the old (current) journal file, and another one to a new journal file, by default. Or you can write just the closing transaction, or just the opening transaction, by using the --close or --open flag. Or you can use --dry-run, to just print the transactions to stdout without writing anything. It's a good idea to do this first, to preview and fine tune.

You can specify the new journal's file name with -o/--output-file FILE. Otherwise, hledger will guess it like so:

• if the old journal's file name contains a group of four digits, that will be replaced by YYYY, the year of the opening date (see below). Eg main-2019.journal could become main-2020.journal.

• otherwise, -YYYY will be appended to the old file name (before the extension). Eg main.journal could become main-2020.journal.

If the new file already exists, hledger will test that it's a valid hledger journal before appending to it. The names of any files written to will be displayed (on stderr).

Closing/opening date

The opening date is always one day after the closing date. By default, the opening date is today and the closing date is yesterday. (So closing balances are calculated as of end of yesterday.)

So if you are doing a year-end close and you run this command on january 1, closing date will be december 31 and opening date will be january 1, which is probably what you want.

More generally, you should specify the opening date, by setting a report end date. So let's assume the closing date was december 31 of 2019 and you're running this command some time in mid-january of 2020; then you would set the opening date to january 1 like so:

hledger close -e 2020-01-01

(or in an equivalent form if you prefer):

hledger close -e 2020     # january 1 of 2020
hledger close -e 1/1      # january 1 of current year
hledger close -p 2019     # period spanning old year, end date is 2020-01-01 (start date is ignored)
hledger close date:2019   # same as above

Closing/opening transactions

The default transaction descriptions are "closing balances" and "opening balances". You can customise these with --close-desc and --open-desc.

Closing balances are normally transferred to, and opening balances are transferred from, an equity account; "equity:opening/closing balances" by default. You can change this account name with --close-acct. And you can optionally set a different opening account name with --open-acct.

The equity posting is normally left amountless, for brevity. With --x/--explicit, the amount will be shown (and if it involves multiple commodities, multiple single-commodity postings will be shown).

With --interleaved, equity postings are shown next to each posting that they balance, which makes troubleshooting easier.

By default, transaction prices in the journal are ignored when generating the closing/opening transactions. With --show-costs, this cost information is preserved, ie balance -B reports will be unchanged after the transition. Separate postings are generated for each cost in each commodity. Note this can generate very large journal entries, if you have many foreign currency or investment transactions.

Both transactions will include balance assertions for the closed/reopened accounts. You probably shouldn't use status or realness filters (like -C or -R or status:) with this command, or the generated balance assertions will depend on these flags. Likewise, if you run this command with --auto, the balance assertions will probably always require --auto.

When is close useful ?

Case 1: multi-file journals

Most hledger users sooner or later split their journal files by time, eg yearly - for performance, to compartmentalise old and new data, and/or to simplify the default reports.

Since the new file should be self-contained, it must initialise all asset and liability balances to what they were at the end of the old file. close helps generate the opening balances transaction which does this.

But also, sometimes you will want to run reports spanning both files. Now the new file's opening balances transaction is redundant and distorts the balances. To work around it, we add an equal but opposite closing balances transaction to the old file. Now the matched closing and opening transactions cancel out and the balances remain accurate. Two slight issues remain:

• The closing and opening transactions appear in print and register reports. You can ignore them, or exclude them with a query like not:desc:'(closing|opening) balances'.

• To see the year-end balance sheet for the old file, you need to exclude the closing transaction: not:desc:closing.

Example: starting a new file for the new year:

$ echo $LEDGER_FILE
2019.journal
$ hledger close -e 2020 assets liabilities
..adds closing transaction to 2019.journal..
..adds opening transaction to 2020.journal..

$ hledger bs -f 2020.journal                   # new file, balances are correct
$ hledger bs -f 2019.journal -f 2020.journal   # both files, balances are still correct
$ hledger bs -f 2019.journal not:desc:closing  # must exclude closing txn to see old file's year-end balances

An issue arises when a transaction's postings have different dates, falling on either side of the closing date. Eg a purchase made in december that clears in january:

2019-12-30 store
    expenses:food          10
    assets:bank:checking  -10  ; date: 2020-01-02

This will cause hledger to generate a year-end balance assertion for that checking account that differs from the bank's year-end balance. If this causes you problems, just transfer such amounts to and from a temporary account ("liabilities:pending" here) to avoid disturbing the checking assertion:

In 2019.journal:

2019-12-30 store
    expenses:food          10
    liabilities:pending

In 2020.journal:

2020-01-02 store
    liabilities:pending    10 = 0  ; clearing from 2019-12-30
    assets:checking

Case 2: retained earnings

If you're running a business, you might also use this command to "close the books" at the end of an accounting period, transferring revenue and expense balances to equity:retained earnings. This is a standard practice in traditional accounting. Eg:

$ echo $LEDGER_FILE
2020.journal
$ hledger close -e 2020-04-01 --close --close-acct='equity:retained earnings' revenues expenses
..adds Q1-closing transaction to 2020.journal..

This may or may not be useful to do in the context of hledger. At least, it should make the balancesheetequity report accurate, showing that the accounting equation is satisfied.