diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index f030962f1..bb2896a86 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -1,96 +1,192 @@ close, equity -Prints a "closing balances" transaction and an "opening balances" -transaction that bring account balances to and from zero, respectively. -These can be added to your journal file(s), eg to bring asset/liability -balances forward into a new journal file, or to close out -revenues/expenses to retained earnings at the end of a period. +Prints a sample "closing" transaction bringing specified account +balances to zero, and an inverse "opening" transaction restoring the +same account balances. + +If like most people you split your journal files by time, eg by year: at +the end of the year you can use this command to "close out" your asset +and liability (and perhaps equity) balances in the old file, and +reinitialise them in the new file. This helps ensure that report +balances remain correct whether you are including old files or not. +(Because all closing/opening transactions except the very first will +cancel out - see example below.) + +Some people also use this command to close out revenue and expense +balances at the end of an accounting period. This properly records the +period's profit/loss as "retained earnings" (part of equity), and allows +the accounting equation (A-L=E) to balance, which you could then check +by the bse report's zero total. _FLAGS -You can print just one of these transactions by using the --close or ---open flag. You can customise their descriptions with the --close-desc -and --open-desc options. +You can print just the closing transaction by using the --close flag, or +just the opening transaction with the --open flag. -One amountless posting to "equity:opening/closing balances" is added to -balance the transactions, by default. You can customise this account -name with --close-acct and --open-acct; if you specify only one of -these, it will be used for both. +Their descriptions are closing balances and opening balances by default; +you can customise these with the --close-desc and --open-desc options. -With --x/--explicit, the equity posting's amount will be shown. And if -it involves multiple commodities, a posting for each commodity will be -shown, as with the print command. +Just one balancing equity posting is used by default, with the amount +left implicit. The default account name is +equity:opening/closing balances. You can customise the account name(s) +with --close-acct and --open-acct. (If you specify only one of these, it +will be used for both.) -With --interleaved, the equity postings are shown next to the postings -they balance, which makes troubleshooting easier. +With --x/--explicit, the equity posting's amount will be shown +explicitly, and if it involves multiple commodities, there will be a +separate equity posting for each commodity (as in the print command). -By default, transaction prices in the journal are ignored when -generating the closing/opening transactions. With --show-costs, this -cost information is preserved (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. +With --interleaved, each equity posting is shown next to the posting it +balances (good for troubleshooting). -close usage +close and prices -If you split your journal files by time (eg yearly), you will typically -run this command at the end of the year, and save the closing -transaction as last entry of the old file, and the opening transaction -as the first entry of the new file. This makes the files self contained, -so that correct balances are reported no matter which of them are -loaded. Ie, if you load just one file, the balances are initialised -correctly; or if you load several files, the redundant closing/opening -transactions cancel each other out. (They will show up in print or -register reports; you can exclude them with a query like -not:desc:'(opening|closing) balances'.) +Transaction prices are ignored (and discarded) by closing/opening +transactions, by default. With --show-costs, they are preserved; there +will be a separate equity posting for each cost in each commodity. This +means balance -B reports will look the same after the transition. Note +if you have many foreign currency or investment transactions, this will +generate very large journal entries. -If you're running a business, you might also use this command to "close -the books" at the end of an accounting period, transferring income -statement account balances to retained earnings. (You may want to change -the equity account name to something like "equity:retained earnings".) +close date -By default, the closing transaction is dated yesterday, the balances are -calculated as of end of yesterday, and the opening transaction is dated -today. To close on some other date, use: hledger close -e OPENINGDATE. -Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also -use -p or date:PERIOD (any starting date is ignored). +The default closing date is yesterday, or the journal's end date, +whichever is later. -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. +Unless you are running close on exactly the first day of the new period, +you'll want to override the closing date. This is done by specifying a +report period, where "last day of the report period" will be the closing +date. The opening date is always the following day. So to close on +2020-12-31 and open on 2021-01-01, any of these work -Examples: +- -p 2020 +- date:2020 +- -e 2021-01-01 (remember -e specifies an exclusive end date) +- -e 2021 -Carrying asset/liability balances into a new file for 2019: +Example: close asset/liability accounts for file transition -$ hledger close -f 2018.journal -e 2019 assets liabilities --open - # (copy/paste the output to the start of your 2019 journal file) -$ hledger close -f 2018.journal -e 2019 assets liabilities --close - # (copy/paste the output to the end of your 2018 journal file) +Carrying asset/liability balances from 2020.journal into a new file for +2021: -Now: +$ hledger close -f 2020.journal -p 2020 assets liabilities +# copy/paste the closing transaction to the end of 2020.journal +# copy/paste the opening transaction to the start of 2021.journal -$ hledger bs -f 2019.journal # one file - balances are correct -$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct -$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn +Or: -Transactions spanning the closing date can complicate matters, breaking -balance assertions: +$ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction +$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction -2018/12/30 a purchase made in 2018, clearing the following year +Now, + +$ hledger bs -f 2021.journal # just new file - balances correct +$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct +$ hledger bs -f 2020.journal # just old files - balances are zero ? + # (exclude final closing txn, see below) + +Hiding opening/closing transactions + +Although the closing/opening transactions cancel out, they will be +visible in reports like print and register, creating some visual +clutter. You can exclude them all with a query, like: + +$ hledger print not:desc:'opening|closing' # less typing +$ hledger print not:'equity:opening/closing balances' # more precise + +But when reporting on multiple files, this can get a bit tricky; you may +need to keep the earliest opening balances, for a historical register +report; or you may need to suppress a closing transaction, to see +year-end balances. If you find yourself needing more precise queries, +here's one solution: add more easily-matched tags to opening/closing +transactions, like this: + +; 2019.journal +2019-01-01 opening balances ; earliest opening txn, no tag here +... +2019-12-31 closing balances ; close:2019 +... + +; 2020.journal +2020-01-01 opening balances ; open:2020 +... +2020-12-31 closing balances ; close:2020 +... + +; 2021.journal +2021-01-01 opening balances ; open:2021 +... + +Now with + +; all.journal +include 2019.journal +include 2020.journal +include 2021.journal + +you could do eg: + +$ hledger -f all.journal reg -H checking not:tag:'open|close' + # all years checking register, hiding non-essential opening/closing txns + +$ hledger -f all.journal bs -p 2020 not:tag:close=2020 + # 2020 year end balances, suppressing 2020 closing txn + +$ hledger -f 2020.journal bs not:tag:close + # 2020 year end balances, easier case + +close and balance assertions + +The closing and opening transactions will include balance assertions, +verifying that the accounts have first been reset to zero and then +restored to their previous balance. These provide valuable error +checking, alerting you when things get out of line, but you can ignore +them temporarily with -I or just remove them if you prefer. + +You probably shouldn't use status or realness filters (like -C or -R or +status:) with close, or the generated balance assertions will depend on +these flags. Likewise, if you run this command with --auto, the balance +assertions would probably always require --auto. + +Multi-day transactions (where some postings have a different date) break +the balance assertions, because the money is temporarily "invisible" +while in transit: + +2020/12/30 a purchase made in december, cleared in the next year expenses:food 5 - assets:bank:checking -5 ; [2019/1/2] + assets:bank:checking -5 ; date: 2021/1/2 -Here's one way to resolve that: +To fix the assertions, you can add a temporary account to track such +in-transit money (splitting the multi-day transaction into two +single-day transactions): -; in 2018.journal: -2018/12/30 a purchase made in 2018, clearing the following year +; in 2020.journal: +2020/12/30 a purchase made in december, cleared in the next year expenses:food 5 liabilities:pending -; in 2019.journal: -2019/1/2 clearance of last year's pending transactions +; in 2021.journal: +2021/1/2 clearance of last year's pending transactions liabilities:pending 5 = 0 - assets:checking + assets:bank:checking + +Example: close revenue/expense accounts to retained earnings + +Here, the opening transaction is supressed with --close, as it's +probably not needed. Also you'll want to use a different equity account +name: + +$ hledger close -f 2021.journal -p 2021Q1 --close --close-acct='equity:retained earnings' revenues expenses >> 2021.journal + # close 2021 first quarter revenues/expenses + +Or, operating on the default journal: + +$ hledger close -p Q1 --close --close-acct='equity:retained earnings' revenues expenses >> $LEDGER_FILE + # close current year's first quarter revenues/expenses + +Now, eg: + +$ hledger bse -p Q1 + # Q1 full balance sheet, total should be zero + +$ hledger is -p Q1 not:'retained earnings' + # Q1 income statement, must suppress the closing txn