From daa95aeb7b0254a679c4b493ed28244a8f760fd9 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 11 Jul 2021 13:41:04 -1000 Subject: [PATCH] imp: close: doc: rewrite manual (#1604) --- hledger/Hledger/Cli/Commands/Close.md | 238 ++++++++++++++++++-------- 1 file changed, 169 insertions(+), 69 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index 867f5cd07..7286e8f0a 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/hledger/Hledger/Cli/Commands/Close.md @@ -1,104 +1,204 @@ 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](#balancesheetequity) 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](#report-start--end-date), +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 + +Carrying asset/liability balances from 2020.journal into a new file for 2021: ```shell -$ 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) +$ 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 ``` -Now: +Or: ```shell -$ 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 +$ 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 ``` -Transactions spanning the closing date can complicate matters, breaking balance assertions: +Now, + +```shell +$ 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: + +```shell +$ 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](#queries), here's one solution: +add more easily-matched tags to opening/closing transactions, like this: ```journal -2018/12/30 a purchase made in 2018, clearing the following year +; 2019.journal +2019-01-01 opening balances ; earliest opening txn, no tag here +... +2019-12-31 closing balances ; close:2019 +... +``` +```journal +; 2020.journal +2020-01-01 opening balances ; open:2020 +... +2020-12-31 closing balances ; close:2020 +... +``` +```journal +; 2021.journal +2021-01-01 opening balances ; open:2021 +... +``` + +Now with +```journal +; all.journal +include 2019.journal +include 2020.journal +include 2021.journal +``` +you could do eg: +```shell +$ 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: + +```journal +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): ```journal -; 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: + +```shell +$ 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: + +```shell +$ hledger close -p Q1 --close --close-acct='equity:retained earnings' revenues expenses >> $LEDGER_FILE + # close current year's first quarter revenues/expenses +``` + + +Now, eg: + +```shell +$ 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 ```