slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: update command docs

Browse Source
This commit is contained in:
Simon Michael 2025-01-09 21:05:10 -10:00
parent 6868ab06a4
commit bde97b8f28
2 changed files with 99 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
hledger/Hledger/Cli/Commands/Close.md
View File

@ -9,16 +9,14 @@ You can copy these into your journal file(s) when you are happy with how they lo
```flags ```flags
Flags: Flags:
--close[=NEW] (default) show a closing transaction --clopen[=TAGVAL] show closing and opening balances transactions,
--open[=NEW] show an opening transaction for AL accounts by default
--clopen[=NEW] show closing and opening transactions, for Asset --close[=TAGVAL] show just a closing balances transaction
and Liability accounts by default, tagged for easy --open[=TAGVAL] show just an opening balances transaction
matching. The tag's default value can be overridden --assert[=TAGVAL] show a balance assertions transaction
by providing NEW. --assign[=TAGVAL] show a balance assignments transaction
--assign[=NEW] show opening balance assignments --retain[=TAGVAL] show a retain earnings transaction, for RX
--assert[=NEW] show closing balance assertions accounts by default
--retain[=NEW] show a retain earnings transaction, for Revenue
and Expense accounts by default
-x --explicit show all amounts explicitly -x --explicit show all amounts explicitly
--show-costs show amounts with different costs separately --show-costs show amounts with different costs separately
--interleaved show source and destination postings together --interleaved show source and destination postings together

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

@ -2,24 +2,21 @@ close
(equity) (equity)
close generates several kinds of "closing" and/or "opening" close prints several kinds of "closing" and/or "opening" transactions,
transactions, useful in certain situations, including migrating balances useful in various situations: migrating balances to a new journal file,
to a new journal file, retaining earnings into equity, consolidating retaining earnings into equity, consolidating balances, viewing lot
balances, or viewing lots. Like print, it prints valid journal entries. costs.. Like print, it prints valid journal entries. You can copy these
You can append or copy these to your journal file(s) when you are happy into your journal file(s) when you are happy with how they look.
with how they look.
Flags: Flags:
--migrate[=NEW] show closing and opening transactions, for Asset --clopen[=TAGVAL] show closing and opening balances transactions,
and Liability accounts by default, tagged for easy for AL accounts by default
matching. The tag's default value can be overridden --close[=TAGVAL] show just a closing balances transaction
by providing NEW. --open[=TAGVAL] show just an opening balances transaction
--close[=NEW] (default) show a closing transaction --assert[=TAGVAL] show a balance assertions transaction
--open[=NEW] show an opening transaction --assign[=TAGVAL] show a balance assignments transaction
--assign[=NEW] show opening balance assignments --retain[=TAGVAL] show a retain earnings transaction, for RX
--assert[=NEW] show closing balance assertions accounts by default
--retain[=NEW] show a retain earnings transaction, for Revenue
and Expense accounts by default
-x --explicit show all amounts explicitly -x --explicit show all amounts explicitly
--show-costs show amounts with different costs separately --show-costs show amounts with different costs separately
--interleaved show source and destination postings together --interleaved show source and destination postings together
@ -39,86 +36,99 @@ Flags:
all - also round cost amounts to precision all - also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
close currently has six modes, selected by a single mode flag: 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 --migrate close --clopen
This is the most common mode. It prints a "closing balances" transaction This is useful if migrating balances to a new journal file at the start
that zeroes out all asset and liability balances (by default), and an of a new year. It prints a "closing balances" transaction that zeroes
opposite "opening balances" transaction that restores them again. The out account balances (Asset and Liability accounts, by default), and an
balancing account will be equity:opening/closing balances (or another opposite "opening balances" transaction that restores them again.
specified by --close-acct or --open-acct). Typically, you would run
This is useful when migrating balances to a new journal file at the hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
start of a new year. Essentially, you run
hledger close --migrate=NEWYEAR -e NEWYEAR and then copy the closing
transaction to the end of the old file and the opening transaction to
the start of the new file. The opening transaction sets correct starting
balances in the new file when it is used alone, and the closing
transaction keeps balances correct when you use both old and new files
together, by cancelling out the following opening transaction and
preventing buildup of duplicated opening balances. Think of the
closing/opening pair as "moving the balances into the next file".
You can close a different set of accounts by providing a query. Eg if and then move the opening transaction from the old file to the new file
you want to include equity, you can add assets liabilities equity or (and probably also update your LEDGER_FILE environment variable).
type:ALE arguments. (The balancing account is always excluded.) Revenues
and expenses usually are not migrated to a new file directly; see
--retain below.
The generated transactions will have a start: tag, with its value set to Why might you do this ? If your reports are fast, you may not need it.
--migrate's NEW argument if any, for easier matching or exclusion. When But at some point you will probably want to partition your data by time,
NEW is not specified, it will be inferred if possible by incrementing a for performance or data integrity or regulatory reasons. A new file or
number (eg a year number) within the default journal's main file name. set of files per year is common. Then, having each file/fileset
The other modes behave similarly. "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 an equity account:
equity:opening/closing balances by default, You can override this by
declaring an account with type V/Conversion, or 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).
The generated transactions will have a clopen: tag. If the main
journal's file name contains a number (eg a year number), the tag's
value will be that file name with the number incremented. Or you can
choose the tag value yourself, by using --clopen=TAGVAL.
close --close close --close
This prints just the closing balances transaction of --migrate. It is This prints just the closing balances transaction of --clopen. It is the
the default behaviour if you specify no mode flag. Using the default if you don't specify a mode.
customisation options below, you can move balances from any set of
accounts to a different account. 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 close --open
This prints just the opening balances transaction of --migrate. It is This prints just the opening balances transaction of --clopen. (It is
similar to Ledger's equity command. similar to Ledger's equity command.)
close --assert close --assert
This prints a "closing balances" transaction (with balances: tag), that This prints a transaction that asserts the account balances as they are
just declares balance assertions for the current balances without on the end date (and adds an assert: tag). It could be useful as
changing them. It could be useful as documention and to guard against documention and to guard against changes.
changes.
close --assign close --assign
This prints an "opening balances" transaction that restores the account This prints a transaction that assigns the account balances as they are
balances using balance assignments. Balance assignments work regardless on the end date (and adds an "assign:" tag). Unlike balance assertions,
of any previous balance, so a preceding closing balances transaction is assignments will post changes to balances as needed to reach the
not needed. specified amounts.
However, omitting the closing balances transaction would unbalance This is another way to set starting balances when migrating to a new
equity. This is relatively harmless for personal reports, but it file, and it will set them correctly even in the presence of earlier
disturbs the accounting equation, removing a source of error detection. files which do not have a closing balances transaction. However, it can
So --migrate is generally the best way to set to set balances in new hide errors, and disturb the accounting equation, so --clopen is usually
files, for now. recommended.
close --retain close --retain
This is like --close with different defaults: it prints a "retain This is like --close, but with different defaults: it prints a
earnings" transaction (with retain: tag), that transfers revenue and transaction that transfers Revenue and Expense balances to
expense balances to equity:retained earnings. equity:retained earnings (and adds a retain: tag).
This is a different kind of closing, called "retaining earnings" or This is called "retaining earnings", or "closing the books". Revenues
"closing the books"; it is traditionally performed by businesses at the and expenses correspond to changes in equity. They are initially kept
end of each accounting period, to consolidate revenues and expenses into separate for reporting purposes, but traditionally at the end of each
the main equity balance. ("Revenues" and "expenses" are actually equity accounting period, businesses consolidate them into equity,
by another name, kept separate temporarily for reporting purposes.)
In personal accounting you generally don't need to do this, unless you In personal accounting, there's not much reason to do this, and most
want the balancesheetequity report to show a zero total, demonstrating people don't. One reason to do it is to help the balancesheetequity
that the accounting equation (A-L=E) is satisfied. report show a zero total, demonstrating that the accounting equation
(A-L=E) is satisfied.
close customisation close customisation
@ -207,7 +217,7 @@ Migrate balances to a new file
Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
$ hledger close --migrate -f 2022.journal -p 2022 $ hledger close --clopen -f 2022.journal -p 2022
# copy/paste the closing transaction to the end of 2022.journal # copy/paste the closing transaction to the end of 2022.journal
# copy/paste the opening transaction to the start of 2023.journal # copy/paste the opening transaction to the start of 2023.journal
@ -217,14 +227,14 @@ closing balances transaction:
$ hledger -f 2022.journal bs not:desc:'closing balances' $ hledger -f 2022.journal bs not:desc:'closing balances'
For more flexibility, it helps to tag closing and opening transactions For more flexibility, it helps to tag closing and opening transactions
with eg start:NEWYEAR, then you can ensure correct balances by excluding with eg clopen:NEWYEAR, then you can ensure correct balances by
all opening/closing transactions except the first, like so: excluding all opening/closing transactions except the first, like so:
$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start' $ 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:start=2021 or not tag:start' $ 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:start=2022 or not tag:start' $ 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:start=2021 or not tag:start' $ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2022.j expr:'tag:start=2022 or not tag:start' $ 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 $ hledger bs -Y -f 2023.j # unclosed file, no query needed
More detailed close examples More detailed close examples