From 88cf7556c43090ac6aa93066bda137fa8481f0b8 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 7 Aug 2021 09:31:32 -1000 Subject: [PATCH] ;doc: update CLI usage texts --- hledger/Hledger/Cli/Commands/Aregister.txt | 60 +++++++++------------- 1 file changed, 24 insertions(+), 36 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index ffdbbda100e..9a492c333a5 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