diff --git a/hledger/Hledger/Cli/Commands/Accounts.txt b/hledger/Hledger/Cli/Commands/Accounts.txt index 98b5e12cb..419ed688f 100644 --- a/hledger/Hledger/Cli/Commands/Accounts.txt +++ b/hledger/Hledger/Cli/Commands/Accounts.txt @@ -1,4 +1,5 @@ accounts + Show account names. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Activity.txt b/hledger/Hledger/Cli/Commands/Activity.txt index 9926d7c42..b9866ab73 100644 --- a/hledger/Hledger/Cli/Commands/Activity.txt +++ b/hledger/Hledger/Cli/Commands/Activity.txt @@ -1,4 +1,5 @@ activity + Show an ascii barchart of posting counts per interval. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Add.txt b/hledger/Hledger/Cli/Commands/Add.txt index 90e218f0a..73d5b21d3 100644 --- a/hledger/Hledger/Cli/Commands/Add.txt +++ b/hledger/Hledger/Cli/Commands/Add.txt @@ -1,4 +1,5 @@ add + Prompt for transactions and add them to the journal. Any arguments will be used as default inputs for the first N prompts. diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index 63a704589..a6e92f347 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -1,4 +1,6 @@ -aregister, areg +aregister + +(areg) Show the transactions and running historical balance of a single account, with each transaction displayed as one line. diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 3d36bdc21..ddf94468f 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -1,4 +1,7 @@ -balance, bal +balance + +(bal) + Show accounts and their balances. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.txt b/hledger/Hledger/Cli/Commands/Balancesheet.txt index a4bb13d37..0341b0667 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheet.txt @@ -1,4 +1,7 @@ -balancesheet, bs +balancesheet + +(bs) + This command displays a balance sheet, showing historical ending balances of asset and liability accounts. (To see equity as well, use the balancesheetequity command.) Amounts are shown with normal positive diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt index 8f139270d..b327a4f92 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt @@ -1,4 +1,7 @@ -balancesheetequity, bse +balancesheetequity + +(bse) + This command displays a balance sheet, showing historical ending balances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements. diff --git a/hledger/Hledger/Cli/Commands/Cashflow.txt b/hledger/Hledger/Cli/Commands/Cashflow.txt index df743c678..f017159a4 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.txt +++ b/hledger/Hledger/Cli/Commands/Cashflow.txt @@ -1,4 +1,7 @@ -cashflow, cf +cashflow + +(cf) + This command displays a cashflow statement, showing the inflows and outflows affecting "cash" (ie, liquid, easily convertible) assets. Amounts are shown with normal positive sign, as in conventional diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index e18b576f1..bc2a5f1b6 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -1,4 +1,5 @@ check + Check for various kinds of errors in your data. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index b3b3aaec6..b745bfbf6 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -1,203 +1,166 @@ -close, equity -Prints a sample "closing" transaction bringing specified account -balances to zero, and an inverse "opening" transaction restoring the -same account balances. +close -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.) +close [--retain | --migrate | --open] [QUERY] -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. +By default: prints a transaction that zeroes out ("closes") all +accounts, transferring their balances to an equity account. Query +arguments can be added to override the accounts selection. Three other +modes are supported: + +--retain: prints a transaction closing revenue and expense balances. +This is traditionally done by businesses at the end of each accounting +period; it is less necessary in personal and computer-based accounting, +but it can help balance the accounting equation A=L+E. + +--migrate: prints a transaction to close asset, liability and most +equity balances, and another transaction to re-open them. This can be +useful when starting a new file (for performance or data protection). +Adding the closing transaction to the old file allows old and new files +to be combined. + +--open: as above, but prints just the opening transaction. This can be +useful for starting a new file, leaving the old file unchanged. Similar +to Ledger's equity command. _FLAGS -You can print just the closing transaction by using the --close flag, or -just the opening transaction with the --open flag. +You can change the equity account name with --close-acct ACCT. It +defaults to equity:retained earnings with --retain, or +equity:opening/closing balances otherwise. -Their descriptions are closing balances and opening balances by default; -you can customise these with the --close-desc and --open-desc options. +You can change the transaction description(s) with --close-desc 'DESC' +and --open-desc 'DESC'. It defaults to retain earnings with --retain, or +closing balances and opening balances otherwise. -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.) +Just one posting to the equity account will be used by default, with an +implicit amount. -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). +With --x/--explicit the amount will be shown explicitly, and if it +involves multiple commodities, a separate posting will be generated for +each commodity. -With --interleaved, each equity posting is shown next to the posting it -balances (good for troubleshooting). +With --interleaved, each equity posting is shown next to the +corresponding source/destination posting. + +The default closing date is yesterday or the journal's end date, +whichever is later. You can change this by specifying a report end date; +the last day of the report period will be the closing date. Eg -e 2022 +means "close on 2022-12-31". + +The default closing date is yesterday, or the journal's end date, +whichever is later. You can change this by specifying a report end date; +(The report start date does not matter.) The last day of the report +period will be the closing date; eg -e 2022 means "close on 2022-12-31". +The opening date is always the day after the closing date. close and costs -Costs 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. - -close date - -The default closing date is yesterday, or the journal's end date, -whichever is later. - -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 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 (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these -will work: - - ----------------------------------------------------------------------- - end date explanation - argument - --------------- ------------------------------------------------------- - -e 2021-01-01 end dates are exclusive - - -e 2021 equivalent, per smart dates - - -p 2020 equivalent, the period's begin date is ignored - - date:2020 equivalent query - ----------------------------------------------------------------------- - -Example: close asset/liability accounts for file transition - -Carrying asset/liability balances from 2020.journal into a new file for -2021: - -$ 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 - -Or: - -$ 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 - -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 ; clopen:2020 -... - -; 2020.journal -2020-01-01 opening balances ; clopen:2020 -... -2020-12-31 closing balances ; clopen:2021 -... - -; 2021.journal -2021-01-01 opening balances ; clopen: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:clopen - # all years checking register, hiding non-essential opening/closing txns - -$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 - # 2020 year end balances, suppressing 2020 closing txn +With --show-costs, any amount costs are shown, with separate postings +for each cost. (This currently the best way to view investment assets, +showing lots and cost bases.) If you have many currency conversion or +investment transactions, it can generate very large journal entries. 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. +Balance assertions will be generated, verifying that the accounts have +been reset to zero (and then restored to their previous balances, if +there is an opening transaction). -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. +These provide useful error checking, but you can ignore them temporarily +with -I, or remove them if you prefer. -Multi-day transactions (where some postings have a different date) break -the balance assertions, because the money is temporarily "invisible" -while in transit: +You probably should avoid filtering transactions by status or realness +(-C, -R, status:), or generating postings (--auto), with this command, +since the balance assertions would depend on these. -2020/12/30 a purchase made in december, cleared in the next year +Note custom posting dates spanning the file boundary will disrupt the +balance assertions: + +2023-12-30 a purchase made in december, cleared in january expenses:food 5 - assets:bank:checking -5 ; date: 2021/1/2 + assets:bank:checking -5 ; date: 2023-01-02 -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): +To solve that you can transfer the money to and from a temporary +account, in effect splitting the multi-day transaction into two +single-day transactions: -; in 2020.journal: -2020/12/30 a purchase made in december, cleared in the next year +; in 2022.journal: +2022-12-30 a purchase made in december, cleared in january expenses:food 5 - liabilities:pending + equity:pending -5 -; in 2021.journal: -2021/1/2 clearance of last year's pending transactions - liabilities:pending 5 = 0 - assets:bank:checking +; in 2023.journal: +2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 -Example: close revenue/expense accounts to retained earnings +Example: retain earnings -For this, use --close to suppress the opening transaction, as it's not -needed. Also you'll want to change the equity account name to your -equivalent of "equity:retained earnings". +Record 2022's revenues/expenses as retained earnings on 2022-12-31, +appending the generated transaction to the journal: -Closing 2021's first quarter revenues/expenses: +$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal -$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ - --close-acct='equity:retained earnings' >> 2021.journal +Now 2022's income statement will show only zeroes. To see it again, +exclude the retain transaction. Eg: -The same, using the default journal and current year: +$ hledger -f 2022.journal is not:desc:'retain earnings' -$ hledger close --close revenues expenses -p Q1 \ - --close-acct='equity:retained earnings' >> $LEDGER_FILE +Example: migrate balances to a new file -Now, the first quarter's balance sheet should show a zero (unless you -are using @/@@ notation without equity postings): +Close assets/liabilities/equity on 2022-12-31 and re-open them on +2023-01-01: -$ hledger bse -p Q1 +$ hledger close --migrate -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 -And we must suppress the closing transaction to see the first quarter's -income statement (using the description; not:'retained earnings' won't -work here): +Now 2022's balance sheet will show only zeroes, indicating a balanced +accounting equation. (Unless you are using @/@@ notation - in that case, +try adding --infer-equity.) To see it again, exclude the closing +transaction. Eg: -$ hledger is -p Q1 not:desc:'closing balances' +$ hledger -f 2022.journal bs not:desc:'closing balances' + +Example: excluding closing/opening transactions + +When combining many files for multi-year reports, the closing/opening +transactions cause some noise in reports like print and register. You +can exclude them as shown above, but not:desc:... could be fragile, and +also you will need to avoid excluding the very first opening +transaction, which can be awkward. Here is a way to do it, using tags: +add clopen: tags to all opening/closing balances transactions except the +first, like this: + +; 2021.journal +2021-06-01 first opening balances +... +2021-12-31 closing balances ; clopen:2022 +... + +; 2022.journal +2022-01-01 opening balances ; clopen:2022 +... +2022-12-31 closing balances ; clopen:2023 +... + +; 2023.journal +2023-01-01 opening balances ; clopen:2023 +... + +Now, assuming a combined journal like: + +; all.journal +include 2021.journal +include 2022.journal +include 2023.journal + +The clopen: tag can exclude all but the first opening transaction. To +show a clean multi-year checking register: + +$ hledger -f all.journal areg checking not:tag:clopen + +And the year values allow more precision. To show 2022's year-end +balance sheet: + +$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 diff --git a/hledger/Hledger/Cli/Commands/Codes.txt b/hledger/Hledger/Cli/Commands/Codes.txt index 8c6937548..40cdf4292 100644 --- a/hledger/Hledger/Cli/Commands/Codes.txt +++ b/hledger/Hledger/Cli/Commands/Codes.txt @@ -1,4 +1,5 @@ codes + List the codes seen in transactions, in the order parsed. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Commodities.txt b/hledger/Hledger/Cli/Commands/Commodities.txt index ac94166a1..c312a586c 100644 --- a/hledger/Hledger/Cli/Commands/Commodities.txt +++ b/hledger/Hledger/Cli/Commands/Commodities.txt @@ -1,4 +1,5 @@ commodities + List all commodity/currency symbols used or declared in the journal. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Descriptions.txt b/hledger/Hledger/Cli/Commands/Descriptions.txt index 7b3e7cde0..f7c06f9a4 100644 --- a/hledger/Hledger/Cli/Commands/Descriptions.txt +++ b/hledger/Hledger/Cli/Commands/Descriptions.txt @@ -1,4 +1,5 @@ descriptions + List the unique descriptions that appear in transactions. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Diff.txt b/hledger/Hledger/Cli/Commands/Diff.txt index bd9432ff4..1e284f3a6 100644 --- a/hledger/Hledger/Cli/Commands/Diff.txt +++ b/hledger/Hledger/Cli/Commands/Diff.txt @@ -1,4 +1,5 @@ diff + Compares a particular account's transactions in two input files. It shows any transactions to this account which are in one file but not in the other. diff --git a/hledger/Hledger/Cli/Commands/Files.txt b/hledger/Hledger/Cli/Commands/Files.txt index c842e986a..d1fb0c79f 100644 --- a/hledger/Hledger/Cli/Commands/Files.txt +++ b/hledger/Hledger/Cli/Commands/Files.txt @@ -1,4 +1,5 @@ files + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. diff --git a/hledger/Hledger/Cli/Commands/Help.txt b/hledger/Hledger/Cli/Commands/Help.txt index 2a45d003a..eb06d1b30 100644 --- a/hledger/Hledger/Cli/Commands/Help.txt +++ b/hledger/Hledger/Cli/Commands/Help.txt @@ -1,4 +1,5 @@ help + Show the hledger user manual in the terminal, with info, man, or a pager. With a TOPIC argument, open it at that topic if possible. TOPIC can be any heading in the manual, or a heading prefix, case insensitive. diff --git a/hledger/Hledger/Cli/Commands/Import.txt b/hledger/Hledger/Cli/Commands/Import.txt index f9f9e6d47..0dc6d52a8 100644 --- a/hledger/Hledger/Cli/Commands/Import.txt +++ b/hledger/Hledger/Cli/Commands/Import.txt @@ -1,4 +1,5 @@ import + Read new transactions added to each FILE since last run, and add them to the journal. Or with --dry-run, just print the transactions that would be added. Or with --catchup, just mark all of the FILEs' transactions as diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.txt b/hledger/Hledger/Cli/Commands/Incomestatement.txt index 97820c3ee..91f8f4534 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.txt +++ b/hledger/Hledger/Cli/Commands/Incomestatement.txt @@ -1,4 +1,7 @@ -incomestatement, is +incomestatement + +(is) + This command displays an income statement, showing revenues and expenses during one or more periods. Amounts are shown with normal positive sign, as in conventional financial statements. diff --git a/hledger/Hledger/Cli/Commands/Notes.txt b/hledger/Hledger/Cli/Commands/Notes.txt index 483c6acad..49d54dbe8 100644 --- a/hledger/Hledger/Cli/Commands/Notes.txt +++ b/hledger/Hledger/Cli/Commands/Notes.txt @@ -1,4 +1,5 @@ notes + List the unique notes that appear in transactions. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Payees.txt b/hledger/Hledger/Cli/Commands/Payees.txt index 4556d64b2..35e3897eb 100644 --- a/hledger/Hledger/Cli/Commands/Payees.txt +++ b/hledger/Hledger/Cli/Commands/Payees.txt @@ -1,4 +1,5 @@ payees + List the unique payee/payer names that appear in transactions. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Prices.txt b/hledger/Hledger/Cli/Commands/Prices.txt index 8c0cf3290..bdb1a4cd4 100644 --- a/hledger/Hledger/Cli/Commands/Prices.txt +++ b/hledger/Hledger/Cli/Commands/Prices.txt @@ -1,4 +1,5 @@ prices + Print market price directives from the journal. With --infer-market-prices, generate additional market prices from costs. With --infer-reverse-prices, also generate market prices by inverting diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index b8cb11477..433ab457f 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -1,4 +1,5 @@ print + Show transaction journal entries, sorted by date. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Register.txt b/hledger/Hledger/Cli/Commands/Register.txt index 8c33ef2f9..e70e8c6ce 100644 --- a/hledger/Hledger/Cli/Commands/Register.txt +++ b/hledger/Hledger/Cli/Commands/Register.txt @@ -1,4 +1,7 @@ -register, reg +register + +(reg) + Show postings and their running total. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Rewrite.txt b/hledger/Hledger/Cli/Commands/Rewrite.txt index 03e6a6dbc..fd3aa185f 100644 --- a/hledger/Hledger/Cli/Commands/Rewrite.txt +++ b/hledger/Hledger/Cli/Commands/Rewrite.txt @@ -1,4 +1,5 @@ rewrite + Print all transactions, rewriting the postings of matched transactions. For now the only rewrite available is adding new postings, like print --auto. diff --git a/hledger/Hledger/Cli/Commands/Roi.txt b/hledger/Hledger/Cli/Commands/Roi.txt index 97ccdfe66..a4234839f 100644 --- a/hledger/Hledger/Cli/Commands/Roi.txt +++ b/hledger/Hledger/Cli/Commands/Roi.txt @@ -1,4 +1,5 @@ roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. diff --git a/hledger/Hledger/Cli/Commands/Stats.txt b/hledger/Hledger/Cli/Commands/Stats.txt index c310b4a1f..5dc1293e6 100644 --- a/hledger/Hledger/Cli/Commands/Stats.txt +++ b/hledger/Hledger/Cli/Commands/Stats.txt @@ -1,4 +1,5 @@ stats + Show journal and performance statistics. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Tags.txt b/hledger/Hledger/Cli/Commands/Tags.txt index 774e5ce4c..53244c4a3 100644 --- a/hledger/Hledger/Cli/Commands/Tags.txt +++ b/hledger/Hledger/Cli/Commands/Tags.txt @@ -1,4 +1,5 @@ tags + List the tags used in the journal, or their values. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Test.txt b/hledger/Hledger/Cli/Commands/Test.txt index 5ced20f4b..b09f786d3 100644 --- a/hledger/Hledger/Cli/Commands/Test.txt +++ b/hledger/Hledger/Cli/Commands/Test.txt @@ -1,4 +1,5 @@ test + Run built-in unit tests. _FLAGS