From bf2e9f24b8981af1d5eee71fa724c3049e1e4085 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 8 Aug 2021 09:37:05 -1000 Subject: [PATCH] ;doc: update CLI usage texts --- hledger/Hledger/Cli/Commands/Aregister.txt | 60 +++++++++------------- hledger/Hledger/Cli/Commands/Balance.txt | 57 ++++++++++++++++++++ 2 files changed, 81 insertions(+), 36 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index ffdbbda10..9a492c333 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -1,36 +1,39 @@ aregister, areg -Show the transactions and running historical balance in an account, with -each line item representing one transaction. +Show the transactions and running historical balance of a single +account, with each transaction displayed as one line. _FLAGS -aregister shows the transactions affecting a particular account and its -subaccounts, with each line item representing a whole transaction - as -in bank statements, hledger-ui, hledger-web and other accounting apps. +aregister shows the overall transactions affecting a particular account +(and any subaccounts). Each report line represents one transaction in +this account. Transactions before the report start date are always +included in the running balance (--historical mode is always on). -Note this is unlike the register command, which shows individual -postings and does not always show a single account or a historical -balance. +This is a more "real world", bank-like view than the register command +(which shows individual postings, possibly from multiple accounts, not +necessarily in historical mode). As a quick rule of thumb: - use +aregister for reviewing and reconciling real-world asset/liability +accounts - use register for reviewing detailed revenues/expenses. -A reminder, "historical" balances include any balance from transactions -before the report start date, so (if opening balances are recorded -correctly) aregister will show the real-world balances of an account, as -you would see in a bank statement. - -As a quick rule of thumb, use aregister for reconciling real-world -asset/liability accounts and register for reviewing detailed -revenues/expenses. - -aregister shows the register for just one account (and its subaccounts). -This account must be specified as the first argument. You can write +aregister requires one argument: the account to report on. You can write either the full account name, or a case-insensitive regular expression which will select the alphabetically first matched account. (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, hledger areg checking would select assets:aaa:checking.) +Transactions involving subaccounts of this account will also be shown. +aregister ignores depth limits, so its final total will always match a +balance report with similar arguments. + Any additional arguments form a query which will filter the transactions -shown. +shown. Note some queries will disturb the running balance, causing it to +be different from the account's real-world running balance. + +An example: this shows the transactions and historical running balance +during july, in the first account whose name contains "checking": + +$ hledger areg checking date:jul Each aregister line item shows: @@ -44,11 +47,8 @@ Each aregister line item shows: Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. -aregister ignores a depth limit, so its final total will always match a -balance report with similar arguments. - This command also supports the output destination and output format -options The output formats supported are txt, csv, and json. +options. The output formats supported are txt, csv, and json. aregister and custom posting dates @@ -61,15 +61,3 @@ the one shown by register -H with the same arguments. To filter strictly by transaction date instead, add the --txn-dates flag. If you use this flag and some of your postings have custom dates, it's probably best to assume the running balance is wrong. - -Examples: - -Show all transactions and historical running balance in the first -account whose name contains "checking": - -$ hledger areg checking - -Show transactions and historical running balance in all asset accounts -during july: - -$ hledger areg assets date:jul diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 1733b78d7..e1e334db6 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -58,6 +58,8 @@ balance can show.. - rows and columns swapped (--transpose) - another field used as account name (--pivot) - custom-formatted line items (single-period reports only) (--format) +- commodities shown in a separate column, one per row + (--commodity-column) This command supports the output destination and output format options, with output formats txt, csv, json, and (multi-period reports only:) @@ -230,6 +232,61 @@ in the terminal. Here are some ways to handle that: - Output as HTML and view with a browser: hledger bal -D -o a.html && open a.html +Commodity column + +With --commodity-column, commodity symbols are displayed in a separate +column, and amounts are displayed as bare numbers. In this mode, each +report row will show amounts for a single commodity, using extra rows +when necessary. It can be useful for a cleaner display of reports with +many commodities: + +$ hledger bal -T -Y +Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total +==================++============================================================================================================================= + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++----------------------------------------------------------------------------------------------------------------------------- + total || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + +$ hledger bal -T -Y --commodity-column +Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + +This flag also affects CSV output, which is useful for producing data +that is easier to consume, eg when making charts: + +$ hledger bal -T -O csv +"account","balance" +"Assets:US:ETrade","70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT" +"total","70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT" + +$ hledger bal -T -O csv --commodity-column +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"total","GLD","70.00" +"total","ITOT","17.00" +"total","USD","5120.50" +"total","VEA","36.00" +"total","VHT","294.00" + Sorting by amount With -S/--sort-amount, accounts with the largest (most positive)