From f4c8b528852d601a37eb0129b1e6e230087231cb Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 17 Feb 2021 12:07:06 -0800 Subject: [PATCH] ;update CLI usage texts --- hledger/Hledger/Cli/Commands/Aregister.txt | 53 +++-- hledger/Hledger/Cli/Commands/Balance.txt | 258 ++++++++++----------- hledger/Hledger/Cli/Commands/Payees.txt | 14 +- hledger/Hledger/Cli/Commands/Print.txt | 18 +- 4 files changed, 187 insertions(+), 156 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index fd4e26d20..ffdbbda10 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -1,35 +1,52 @@ aregister, areg -Show transactions affecting a particular account, and the account's -running balance. + +Show the transactions and running historical balance in an account, with +each line item representing one transaction. _FLAGS -aregister shows the transactions affecting a particular account (and its -subaccounts), from the point of view of that account. Each line shows: +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. -- the transaction's (or posting's, see below) date -- the names of the other account(s) involved -- the net change to this account's balance -- the account's historical running balance (including balance from - transactions before the report start date). +Note this is unlike the register command, which shows individual +postings and does not always show a single account or a historical +balance. -With aregister, each line represents a whole transaction - as in -hledger-ui, hledger-web, and your bank statement. By contrast, the -register command shows individual postings, across all accounts. You -might prefer aregister for reconciling with real-world asset/liability -accounts, and 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. -An account must be specified as the first argument, which should be the -full account name or an account pattern (regular expression). aregister -will show transactions in this account (the first one matched) and any -of its subaccounts. +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 +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.) Any additional arguments form a query which will filter the transactions shown. +Each aregister line item shows: + +- the transaction's date (or the relevant posting's date if different, + see below) +- the names of all the other account(s) involved in this transaction + (probably abbreviated) +- the total change to this account's balance from this transaction +- the account's historical running balance after this transaction. + 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. diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index a45156fdd..f17212b58 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -85,130 +85,6 @@ sum of the top-level balances, not of all the balances shown. Each group of sibling accounts is sorted separately, by declaration order and then by account name. -Customising single-period balance reports - -You can customise the layout of single-period balance reports with ---format FMT, which sets the format of each line. Eg: - -$ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 - -The FMT format string (plus a newline) specifies the formatting applied -to each account/balance pair. It may contain any suitable text, with -data fields interpolated like so: - -%[MIN][.MAX](FIELDNAME) - -- MIN pads with spaces to at least this width (optional) - -- MAX truncates at this width (optional) - -- FIELDNAME must be enclosed in parentheses, and can be one of: - - - depth_spacer - a number of spaces equal to the account's depth, - or if MIN is specified, MIN * depth spaces. - - account - the account's name - - total - the account's balance/posted total, right justified - -Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - -- %_ - render on multiple lines, bottom-aligned (the default) -- %^ - render on multiple lines, top-aligned -- %, - render on one line, comma-separated - -There are some quirks. Eg in one-line mode, %(depth_spacer) has no -effect, instead %(account) has indentation built in. Experimentation may -be needed to get pleasing results. - -Some example formats: - -- %(total) - the account's total -- %-20.20(account) - the account's name, left justified, padded to 20 - characters and clipped at 20 characters -- %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on - one line -- %20(total) %2(depth_spacer)%-(account) - the default format for the - single-column balance report - -Depth limiting - -With a depth:N query, or --depth N option, or just -N, balance reports -will show accounts only to the specified depth. This is very useful to -hide low-level accounts and get an overview. Eg, limiting to depth 1 -shows the top-level accounts: - -$ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - -Accounts at the depth limit will include the balances of any hidden -subaccounts (even in flat mode, which normally shows exclusive -balances). - -You can also drop account name components from the start of account -names, using --drop N. This can be useful to hide unwanted top-level -detail. - -Colour support - -In terminal output, when colour is enabled, the balance command shows -negative amounts in red. - -Sorting by amount - -With -S/--sort-amount, accounts with the largest (most positive) -balances are shown first. For example, hledger bal expenses -MAS shows -your biggest averaged monthly expenses first. - -Revenues and liability balances are typically negative, however, so -S -shows these in reverse order. To work around this, you can add --invert -to flip the signs. Or, use one of the sign-flipping reports like -balancesheet or incomestatement, which also support -S. Eg: -hledger is -MAS. - -Percentages - -With -% or --percent, balance reports show each account's value -expressed as a percentage of the column's total. This is useful to get -an overview of the relative sizes of account balances. For example to -obtain an overview of expenses: - -$ hledger balance expenses -% - 100.0 % expenses - 50.0 % food - 50.0 % supplies --------------------- - 100.0 % - -Note that --tree does not have an effect on -%. The percentages are -always relative to the total sum of each column, they are never relative -to the parent account. - -Since the percentages are relative to the columns sum, it is usually not -useful to calculate percentages if the signs of the amounts are mixed. -Although the results are technically correct, they are most likely -useless. Especially in a balance report that sums up to zero (eg -hledger balance -B) all percentage values will be zero. - -This flag does not work if the report contains any mixed commodity -accounts. If there are mixed commodity accounts in the report be sure to -use -V or -B to coerce the report into using a single commodity. - Multi-period balance report Multi-period balance reports are a very useful hledger feature, @@ -325,13 +201,137 @@ When the report is still too wide, a good workaround is to pipe it into less -RS (-R for colour, -S to chop long lines). Eg: hledger bal -D --color=yes | less -RS. +Depth limiting + +With a depth:N query, or --depth N option, or just -N, balance reports +will show accounts only to the specified depth. This is very useful to +hide low-level accounts and get an overview. Eg, limiting to depth 1 +shows the top-level accounts: + +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + +Accounts at the depth limit will include the balances of any hidden +subaccounts (even in flat mode, which normally shows exclusive +balances). + +You can also drop account name components from the start of account +names, using --drop N. This can be useful to hide unwanted top-level +detail. + +Colour support + +In terminal output, when colour is enabled, the balance command shows +negative amounts in red. + +Sorting by amount + +With -S/--sort-amount, accounts with the largest (most positive) +balances are shown first. For example, hledger bal expenses -MAS shows +your biggest averaged monthly expenses first. + +Revenues and liability balances are typically negative, however, so -S +shows these in reverse order. To work around this, you can add --invert +to flip the signs. Or, use one of the sign-flipping reports like +balancesheet or incomestatement, which also support -S. Eg: +hledger is -MAS. + +Percentages + +With -% or --percent, balance reports show each account's value +expressed as a percentage of the column's total. This is useful to get +an overview of the relative sizes of account balances. For example to +obtain an overview of expenses: + +$ hledger balance expenses -% + 100.0 % expenses + 50.0 % food + 50.0 % supplies +-------------------- + 100.0 % + +Note that --tree does not have an effect on -%. The percentages are +always relative to the total sum of each column, they are never relative +to the parent account. + +Since the percentages are relative to the columns sum, it is usually not +useful to calculate percentages if the signs of the amounts are mixed. +Although the results are technically correct, they are most likely +useless. Especially in a balance report that sums up to zero (eg +hledger balance -B) all percentage values will be zero. + +This flag does not work if the report contains any mixed commodity +accounts. If there are mixed commodity accounts in the report be sure to +use -V or -B to coerce the report into using a single commodity. + +Customising single-period balance reports + +You can customise the layout of single-period balance reports with +--format FMT, which sets the format of each line. Eg: + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. It may contain any suitable text, with +data fields interpolated like so: + +%[MIN][.MAX](FIELDNAME) + +- MIN pads with spaces to at least this width (optional) + +- MAX truncates at this width (optional) + +- FIELDNAME must be enclosed in parentheses, and can be one of: + + - depth_spacer - a number of spaces equal to the account's depth, + or if MIN is specified, MIN * depth spaces. + - account - the account's name + - total - the account's balance/posted total, right justified + +Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + +- %_ - render on multiple lines, bottom-aligned (the default) +- %^ - render on multiple lines, top-aligned +- %, - render on one line, comma-separated + +There are some quirks. Eg in one-line mode, %(depth_spacer) has no +effect, instead %(account) has indentation built in. Experimentation may +be needed to get pleasing results. + +Some example formats: + +- %(total) - the account's total +- %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters +- %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line +- %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + Budget report -With --budget, extra columns are displayed showing budget goals for each -account and period, if any. Budget goals are defined by periodic -transactions. This is very useful for comparing planned and actual -income, expenses, time usage, etc. --budget is most often combined with -a report interval. +There is also a special balance report mode for showing budget +performance. The --budget flag activates extra columns showing the +budget goals for each account and period, if any. For this report, +budget goals are defined by periodic transactions. This is very useful +for comparing planned and actual income, expenses, time usage, etc. For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: diff --git a/hledger/Hledger/Cli/Commands/Payees.txt b/hledger/Hledger/Cli/Commands/Payees.txt index e0a2f2df9..4556d64b2 100644 --- a/hledger/Hledger/Cli/Commands/Payees.txt +++ b/hledger/Hledger/Cli/Commands/Payees.txt @@ -3,11 +3,15 @@ List the unique payee/payer names that appear in transactions. _FLAGS -This command lists the unique payee/payer names that appear in -transactions, in alphabetic order. You can add a query to select a -subset of transactions. The payee/payer is the part of the transaction -description before a | character (or if there is no |, the whole -description). +This command lists unique payee/payer names which have been declared +with payee directives (--declared), used in transaction descriptions +(--used), or both (the default). + +The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). + +You can add query arguments to select a subset of transactions. This +implies --used. Example: diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 90d6d0ddf..0298fb441 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -5,9 +5,21 @@ _FLAGS The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). + +Amounts are shown mostly normalised to commodity display style, eg the +placement of commodity symbols will be consistent. All of their decimal +places are shown, as in the original journal entry (with one alteration: +in some cases trailing zeroes are added.) + Amounts are shown right-aligned within each transaction (but not across -all transactions). Directives and inter-transaction comments are not -shown. Eg: +all transactions). + +Directives and inter-transaction comments are not shown, currently. This +means the print command is somewhat lossy, and if you are using it to +reformat your journal you should take care to also copy over the +directives and file-level comments. + +Eg: $ hledger print 2008/01/01 income @@ -41,8 +53,6 @@ $ hledger print assets:cash | hledger -f- -I reg expenses:food There are some situations where print's output can become unparseable: -- Rounding amounts according to commodity display styles can cause - transactions to appear unbalanced. - Valuation affects posting amounts but not balance assertion or balance assignment amounts, potentially causing those to fail. - Auto postings can generate postings with too many missing amounts.