close

(equity)

close prints several kinds of "closing" and/or "opening" transactions,
useful in various situations: migrating balances to a new journal file,
retaining earnings into equity, consolidating balances, viewing lot
costs.. Like print, it prints valid journal entries. You can copy these
into your journal file(s) when you are happy with how they look.

Flags:
     --clopen[=TAGVAL]      show closing and opening balances transactions,
                            for AL accounts by default
     --close[=TAGVAL]       show just a closing balances transaction
     --open[=TAGVAL]        show just an opening balances transaction
     --assert[=TAGVAL]      show a balance assertions transaction
     --assign[=TAGVAL]      show a balance assignments transaction
     --retain[=TAGVAL]      show a retain earnings transaction, for RX
                            accounts by default
  -x --explicit             show all amounts explicitly
     --show-costs           show amounts with different costs separately
     --interleaved          show source and destination postings together
     --assertion-type=TYPE  =, ==, =* or ==*
     --close-desc=DESC      set closing transaction's description
     --close-acct=ACCT      set closing transaction's destination account
     --open-desc=DESC       set opening transaction's description
     --open-acct=ACCT       set opening transaction's source account
     --round=TYPE           how much rounding or padding should be done when
                            displaying amounts ?
                            none - show original decimal digits,
                                   as in journal (default)
                            soft - just add or remove decimal zeros
                                   to match precision
                            hard - round posting amounts to precision
                                   (can unbalance transactions)
                            all  - also round cost amounts to precision
                                   (can unbalance transactions)

close has six modes, selected by choosing one of the mode flags (--close
is the default). They all do much the same operation, but with different
defaults, useful in different situations.

close --clopen

This is useful if migrating balances to a new journal file at the start
of a new year. It prints a "closing balances" transaction that zeroes
out account balances (Asset and Liability accounts, by default), and an
opposite "opening balances" transaction that restores them again.
Typically, you would run

hledger close --clopen -e NEWYEAR >> $LEDGER_FILE

and then move the opening transaction from the old file to the new file
(and probably also update your LEDGER_FILE environment variable).

Why might you do this ? If your reports are fast, you may not need it.
But at some point you will probably want to partition your data by time,
for performance or data integrity or regulatory reasons. A new file or
set of files per year is common. Then, having each file/fileset
"bookended" with opening and closing balance transactions will allow you
to freely pick and choose which files to read - just the current year,
any past year, any sequence of years, or all of them - while showing
correct account balances in each case. The earliest opening balances
transaction sets correct starting balances, and any later
closing/opening pairs will harmlessly cancel each other out.

The balances will be transferred to and from
equity:opening/closing balances by default. You can override this by
using --close-acct and/or --open-acct.

You can select a different set of accounts to close/open by providing an
account query. Eg to add Equity accounts, provide arguments like
assets liabilities equity or type:ALE. When migrating to a new file,
you'll usually want to bring along the AL or ALE accounts, but not the
RX accounts (Revenue, Expense).

Assertions will be added indicating and checking the new balances of the
closed/opened accounts.

The generated transactions will have a clopen: tag. If the main
journal's base file name contains a number (eg a year number), the tag's
value will be that base file name with the number incremented. Or you
can choose the tag value yourself, by using --clopen=TAGVAL.

close --close

This prints just the closing balances transaction of --clopen. It is the
default if you don't specify a mode.

More customisation options are described below. Among other things, you
can use close --close to generate a transaction moving the balances from
any set of accounts, to a different account. (If you need to move just a
portion of the balance, see hledger-move.)

close --open

This prints just the opening balances transaction of --clopen. (It is
similar to Ledger's equity command.)

close --assert

This prints a transaction that asserts the account balances as they are
on the end date (and adds an assert: tag). It could be useful as
documention and to guard against changes.

close --assign

This prints a transaction that assigns the account balances as they are
on the end date (and adds an "assign:" tag). Unlike balance assertions,
assignments will post changes to balances as needed to reach the
specified amounts.

This is another way to set starting balances when migrating to a new
file, and it will set them correctly even in the presence of earlier
files which do not have a closing balances transaction. However, it can
hide errors, and disturb the accounting equation, so --clopen is usually
recommended.

close --retain

This is like --close, but it closes Revenue and Expense account balances
by default. They will be transferred to equity:retained earnings, or
another account specified with --close-acct.

Revenues and expenses correspond to changes in equity. They are
categorised separately for reporting purposes, but traditionally at the
end of each accounting period, businesses consolidate them into equity,
This is called "retaining earnings", or "closing the books".

In personal accounting, there's not much reason to do this, and most
people don't. (One reason to do it is to help the balancesheetequity
report show a zero total, demonstrating that the accounting equation
(A-L=E) is satisfied.)

close customisation

In all modes, the following things can be overridden:

- the accounts to be closed/opened, with account query arguments
- the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
- the transaction descriptions, with --close-desc=DESC and
  --open-desc=DESC
- the transaction's tag value, with a --MODE=NEW option argument
- the closing/opening dates, with -e OPENDATE

By default, the closing date is yesterday, or the journal's end date,
whichever is later; and the opening date is always one day after the
closing date. You can change these by specifying a report end date; the
closing date will be the last day of the report period. Eg -e 2024 means
"close on 2023-12-31, open on 2024-01-01".

With --x/--explicit, the balancing amount will be shown explicitly, and
if it involves multiple commodities, a separate posting will be
generated for each of them (similar to print -x).

With --interleaved, each individual transfer is shown with source and
destination postings next to each other (perhaps useful for
troubleshooting).

With --show-costs, balances' costs are also shown, with different costs
kept separate. This may generate very large journal entries, if you have
many currency conversions or investment transactions. close --show-costs
is currently the best way to view investment lots with hledger. (To move
or dispose of lots, see the more capable hledger-move script.)

close and balance assertions

close adds balance assertions verifying that the accounts have been
reset to zero in a closing transaction or restored to their previous
balances in an opening transaction. These provide useful error checking,
but you can ignore them temporarily with -I, or remove them if you
prefer.

Single-commodity, subaccount-exclusive balance assertions (=) are
generated by default. This can be changed with --assertion-type='==*'
(eg).

When running close you should probably avoid using -C, -R, status:
(filtering by status or realness) or --auto (generating postings), since
the generated balance assertions would then require these.

Transactions with multiple dates (eg posting dates) spanning the file
boundary also can disrupt the balance assertions:

2023-12-30 a purchase made in december, cleared in january
    expenses:food          5
    assets:bank:checking  -5  ; date: 2023-01-02

To solve this you can transfer the money to and from a temporary
account, splitting the multi-day transaction into two single-day
transactions:

; in 2022.journal:
2022-12-30 a purchase made in december, cleared in january
    expenses:food          5
    equity:pending        -5

; in 2023.journal:
2023-01-02 last year's transaction cleared
    equity:pending         5 = 0
    assets:bank:checking  -5

close examples

Retain earnings

Record 2022's revenues/expenses as retained earnings on 2022-12-31,
appending the generated transaction to the journal:

$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal

After this, to see 2022's revenues and expenses you must exclude the
retain earnings transaction:

$ hledger -f 2022.journal is not:desc:'retain earnings'

Migrate balances to a new file

Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:

$ hledger close --clopen -f 2022.journal -p 2022
# copy/paste the closing transaction to the end of 2022.journal
# copy/paste the opening transaction to the start of 2023.journal

After this, to see 2022's end-of-year balances you must exclude the
closing balances transaction:

$ hledger -f 2022.journal bs not:desc:'closing balances'

For more flexibility, it helps to tag closing and opening transactions
with eg clopen:NEWYEAR, then you can ensure correct balances by
excluding all opening/closing transactions except the first, like so:

$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:clopen=2022 or not tag:clopen'
$ hledger bs -Y -f 2021.j                     expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2022.j                     expr:'tag:clopen=2022 or not tag:clopen'
$ hledger bs -Y -f 2023.j                     # unclosed file, no query needed

More detailed close examples

See examples/multi-year.
