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:
--close[=NEW] (default) show a closing transaction
--open[=NEW] show an opening transaction
--clopen[=NEW] show closing and opening transactions, for Asset
and Liability accounts by default, tagged for easy
matching. The tag's default value can be overridden
by providing NEW.
--assign[=NEW] show opening balance assignments
--assert[=NEW] show closing balance assertions
--retain[=NEW] show a retain earnings transaction, for Revenue
and Expense accounts by default
--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

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

@ -2,24 +2,21 @@ close
(equity)
close generates several kinds of "closing" and/or "opening"
transactions, useful in certain situations, including migrating balances
to a new journal file, retaining earnings into equity, consolidating
balances, or viewing lots. Like print, it prints valid journal entries.
You can append or copy these to your journal file(s) when you are happy
with how they look.
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:
--migrate[=NEW] show closing and opening transactions, for Asset
and Liability accounts by default, tagged for easy
matching. The tag's default value can be overridden
by providing NEW.
--close[=NEW] (default) show a closing transaction
--open[=NEW] show an opening transaction
--assign[=NEW] show opening balance assignments
--assert[=NEW] show closing balance assertions
--retain[=NEW] show a retain earnings transaction, for Revenue
and Expense accounts by default
--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
@ -39,86 +36,99 @@ Flags:
all - also round cost amounts to precision
(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
that zeroes out all asset and liability balances (by default), and an
opposite "opening balances" transaction that restores them again. The
balancing account will be equity:opening/closing balances (or another
specified by --close-acct or --open-acct).
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
This is useful when migrating balances to a new journal file at the
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".
hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
You can close a different set of accounts by providing a query. Eg if
you want to include equity, you can add assets liabilities equity or
type:ALE arguments. (The balancing account is always excluded.) Revenues
and expenses usually are not migrated to a new file directly; see
--retain below.
and then move the opening transaction from the old file to the new file
(and probably also update your LEDGER_FILE environment variable).
The generated transactions will have a start: tag, with its value set to
--migrate's NEW argument if any, for easier matching or exclusion. When
NEW is not specified, it will be inferred if possible by incrementing a
number (eg a year number) within the default journal's main file name.
The other modes behave similarly.
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 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
This prints just the closing balances transaction of --migrate. It is
the default behaviour if you specify no mode flag. Using the
customisation options below, you can move balances from any set of
accounts to a different account.
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 --migrate. It is
similar to Ledger's equity command.
This prints just the opening balances transaction of --clopen. (It is
similar to Ledger's equity command.)
close --assert
This prints a "closing balances" transaction (with balances: tag), that
just declares balance assertions for the current balances without
changing them. It could be useful as documention and to guard against
changes.
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 an "opening balances" transaction that restores the account
balances using balance assignments. Balance assignments work regardless
of any previous balance, so a preceding closing balances transaction is
not needed.
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.
However, omitting the closing balances transaction would unbalance
equity. This is relatively harmless for personal reports, but it
disturbs the accounting equation, removing a source of error detection.
So --migrate is generally the best way to set to set balances in new
files, for now.
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 with different defaults: it prints a "retain
earnings" transaction (with retain: tag), that transfers revenue and
expense balances to equity:retained earnings.
This is like --close, but with different defaults: it prints a
transaction that transfers Revenue and Expense balances to
equity:retained earnings (and adds a retain: tag).
This is a different kind of closing, called "retaining earnings" or
"closing the books"; it is traditionally performed by businesses at the
end of each accounting period, to consolidate revenues and expenses into
the main equity balance. ("Revenues" and "expenses" are actually equity
by another name, kept separate temporarily for reporting purposes.)
This is called "retaining earnings", or "closing the books". Revenues
and expenses correspond to changes in equity. They are initially kept
separate for reporting purposes, but traditionally at the end of each
accounting period, businesses consolidate them into equity,
In personal accounting you generally don't need to do this, unless you
want the balancesheetequity report to show a zero total, demonstrating
that the accounting equation (A-L=E) is satisfied.
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
@ -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:
$ 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 opening transaction to the start of 2023.journal
@ -217,14 +227,14 @@ 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 start:NEWYEAR, then you can ensure correct balances by excluding
all opening/closing transactions except the first, like so:
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:start=2021 or not tag:start'
$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:start=2022 or not tag:start'
$ hledger bs -Y -f 2021.j expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2022.j expr:'tag:start=2022 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: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