slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;update CLI usage texts

Browse Source
This commit is contained in:
Simon Michael 2021-02-17 12:07:06 -08:00
parent ad2ab3c823
commit f4c8b52885
4 changed files with 187 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
hledger/Hledger/Cli/Commands/Aregister.txt
View File

@ -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.

258
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -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:

14
hledger/Hledger/Cli/Commands/Payees.txt
View File

@ -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:

18
hledger/Hledger/Cli/Commands/Print.txt
View File

@ -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.