simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-28 12:54:07 +03:00
Code Issues Projects Releases Wiki Activity

;dev: doc: update CLI usage texts

Browse Source
This commit is contained in:
Simon Michael 2021-07-11 14:38:22 -10:00
parent 44c5eb5136
commit 31de526872
1 changed files with 165 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
hledger/Hledger/Cli/Commands/Close.txt
View File

@ -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