;doc: update command docs
This commit is contained in:
Simon Michael
parent
2899b46c59
commit
8498894a96
@ -25,22 +25,21 @@ Features:
|
||||
- You can also set the initial defaults with command line arguments.
|
||||
- Readline-style edit keys can be used during data entry.
|
||||
- The tab key will auto-complete whenever possible - accounts,
|
||||
payees/descriptions, dates (yesterday, today, tomorrow). If the
|
||||
input area is empty, it will insert the default value.
|
||||
payees/descriptions, dates (yesterday, today, tomorrow). If the input
|
||||
area is empty, it will insert the default value.
|
||||
- A parenthesised transaction code may be entered following a date.
|
||||
- Comments and tags may be entered following a description or amount.
|
||||
- If you make a mistake, enter < at any prompt to go one step
|
||||
backward.
|
||||
- If you make a mistake, enter < at any prompt to go one step backward.
|
||||
- Input prompts are displayed in a different colour when the terminal
|
||||
supports it.
|
||||
|
||||
Notes:
|
||||
|
||||
- If you enter a number with no commodity symbol, and you have
|
||||
declared a default commodity with a D directive, you might expect
|
||||
add to add this symbol for you. It does not do this; we assume that
|
||||
if you are using a D directive you prefer not to see the commodity
|
||||
symbol repeated on amounts in the journal.
|
||||
- If you enter a number with no commodity symbol, and you have declared
|
||||
a default commodity with a D directive, you might expect add to add
|
||||
this symbol for you. It does not do this; we assume that if you are
|
||||
using a D directive you prefer not to see the commodity symbol
|
||||
repeated on amounts in the journal.
|
||||
|
||||
Examples:
|
||||
|
||||
|
||||
@ -74,16 +74,16 @@ listing account balances, balance changes, values, value changes and
|
||||
more, during one time period or many. Generally it shows a table, with
|
||||
rows representing accounts, and columns representing periods.
|
||||
|
||||
Note there are some higher-level variants of the balance command with
|
||||
convenient defaults, which can be simpler to use: balancesheet,
|
||||
balancesheetequity, cashflow and incomestatement. When you need more
|
||||
control, then use balance.
|
||||
Note there are some variants of the balance command with convenient
|
||||
defaults, which are simpler to use: balancesheet, balancesheetequity,
|
||||
cashflow and incomestatement. When you need more control, then use
|
||||
balance.
|
||||
|
||||
balance features
|
||||
|
||||
Here's a quick overview of the balance command's features, followed by
|
||||
more detailed descriptions and examples. Many of these work with the
|
||||
higher-level commands as well.
|
||||
other balance-like commands as well (bs, cf, is..).
|
||||
|
||||
balance can show..
|
||||
|
||||
@ -122,8 +122,7 @@ balance can show..
|
||||
|
||||
..with..
|
||||
|
||||
- totals (-T), averages (-A), percentages (-%), inverted sign
|
||||
(--invert)
|
||||
- totals (-T), averages (-A), percentages (-%), inverted sign (--invert)
|
||||
- rows and columns swapped (--transpose)
|
||||
- another field used as account name (--pivot)
|
||||
- custom-formatted line items (single-period reports only) (--format)
|
||||
@ -210,8 +209,8 @@ interpolated like so:
|
||||
|
||||
- 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.
|
||||
- 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
|
||||
|
||||
@ -272,17 +271,16 @@ $ hledger -f examples/sample.journal balance
|
||||
|
||||
Notes:
|
||||
|
||||
- "Boring" accounts are combined with their subaccount for more
|
||||
compact output, unless --no-elide is used. Boring accounts have no
|
||||
balance of their own and just one subaccount (eg assets:bank and
|
||||
liabilities above).
|
||||
- "Boring" accounts are combined with their subaccount for more compact
|
||||
output, unless --no-elide is used. Boring accounts have no balance of
|
||||
their own and just one subaccount (eg assets:bank and liabilities
|
||||
above).
|
||||
|
||||
- All balances shown are "inclusive", ie including the balances from
|
||||
all subaccounts. Note this means some repetition in the output,
|
||||
which requires explanation when sharing reports with
|
||||
non-plaintextaccounting-users. A tree mode report's final total is
|
||||
the sum of the top-level balances shown, not of all the balances
|
||||
shown.
|
||||
- All balances shown are "inclusive", ie including the balances from all
|
||||
subaccounts. Note this means some repetition in the output, which
|
||||
requires explanation when sharing reports with
|
||||
non-plaintextaccounting-users. A tree mode report's final total is the
|
||||
sum of the top-level balances shown, not of all the balances shown.
|
||||
|
||||
- Each group of sibling accounts (ie, under a common parent) is sorted
|
||||
separately.
|
||||
@ -342,8 +340,9 @@ commodity, it is treated as 0).
|
||||
|
||||
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 higher-level reports, which flip
|
||||
the sign automatically. Eg: hledger incomestatement -MAS).
|
||||
to flip the signs. Or you could use one of the higher-level balance
|
||||
reports (bs, is..), which flip the sign automatically (eg:
|
||||
hledger is -MAS).
|
||||
|
||||
Percentages
|
||||
|
||||
@ -385,13 +384,13 @@ Balance changes in 2008:
|
||||
|
||||
Notes:
|
||||
|
||||
- The report's start/end dates will be expanded, if necessary, to
|
||||
fully encompass the displayed subperiods (so that the first and last
|
||||
- The report's start/end dates will be expanded, if necessary, to fully
|
||||
encompass the displayed subperiods (so that the first and last
|
||||
subperiods have the same duration as the others).
|
||||
- Leading and trailing periods (columns) containing all zeroes are not
|
||||
shown, unless -E/--empty is used.
|
||||
- Accounts (rows) containing all zeroes are not shown, unless
|
||||
-E/--empty is used.
|
||||
- Accounts (rows) containing all zeroes are not shown, unless -E/--empty
|
||||
is used.
|
||||
- Amounts with many commodities are shown in abbreviated form, unless
|
||||
--no-elide is used.
|
||||
- Average and/or total columns can be added with the -A/--average and
|
||||
@ -399,9 +398,9 @@ Notes:
|
||||
- The --transpose flag can be used to exchange rows and columns.
|
||||
- The --pivot FIELD option causes a different transaction field to be
|
||||
used as "account name". See PIVOTING.
|
||||
- The --summary-only flag (--summary also works) hides all but the
|
||||
Total and Average columns (those should be enabled with --row-total
|
||||
and -A/--average).
|
||||
- The --summary-only flag (--summary also works) hides all but the Total
|
||||
and Average columns (those should be enabled with --row-total and
|
||||
-A/--average).
|
||||
|
||||
Multi-period reports with many periods can be too wide for easy viewing
|
||||
in the terminal. Here are some ways to handle that:
|
||||
@ -412,8 +411,7 @@ in the terminal. Here are some ways to handle that:
|
||||
- Use a more compact layout like --layout=bare
|
||||
- Maximize the terminal window
|
||||
- Reduce the terminal's font size
|
||||
- View with a pager like less, eg:
|
||||
hledger bal -D --color=yes | less -RS
|
||||
- View with a pager like less, eg: hledger bal -D --color=yes | less -RS
|
||||
- Output as CSV and use a CSV viewer like visidata
|
||||
(hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
|
||||
(M-x csv-mode, C-c C-a), or a spreadsheet
|
||||
@ -454,7 +452,7 @@ balances:
|
||||
flag. (-H causes report start date to be ignored when summing
|
||||
postings.)
|
||||
|
||||
Balance report types
|
||||
Balance report modes
|
||||
|
||||
The balance command is quite flexible; here is the full detail on how to
|
||||
control what it reports. If the following seems complicated, don't
|
||||
@ -463,15 +461,15 @@ experimentation to get familiar with all the report modes.
|
||||
|
||||
There are three important option groups:
|
||||
|
||||
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
|
||||
hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ...
|
||||
|
||||
Calculation type
|
||||
Calculation mode
|
||||
|
||||
The basic calculation to perform for each table cell. It is one of:
|
||||
|
||||
- --sum : sum the posting amounts (default)
|
||||
- --budget : sum the amounts, but also show the budget goal amount
|
||||
(for each account/period)
|
||||
- --budget : sum the amounts, but also show the budget goal amount (for
|
||||
each account/period)
|
||||
- --valuechange : show the change in period-end historical balance
|
||||
values (caused by deposits, withdrawals, and/or market price
|
||||
fluctuations)
|
||||
@ -479,56 +477,61 @@ The basic calculation to perform for each table cell. It is one of:
|
||||
balance minus each amount's original cost)
|
||||
- --count : show the count of postings
|
||||
|
||||
Accumulation type
|
||||
Accumulation mode
|
||||
|
||||
How amounts should accumulate across a report's subperiods/columns.
|
||||
Another way to say it: which time period's postings should contribute to
|
||||
each cell's calculation. It is one of:
|
||||
|
||||
- --change : calculate with postings from column start to column end,
|
||||
ie "just this column". Typically used to see revenues/expenses.
|
||||
(default for balance, cashflow, incomestatement)
|
||||
- --change : calculate with postings from column start to column end, ie
|
||||
"just this column". Typically used to see revenues/expenses. (default
|
||||
for balance, cashflow, incomestatement)
|
||||
|
||||
- --cumulative : calculate with postings from report start to column
|
||||
end, ie "previous columns plus this column". Typically used to show
|
||||
changes accumulated since the report's start date. Not often used.
|
||||
|
||||
- --historical/-H : calculate with postings from journal start to
|
||||
column end, ie "all postings from before report start date until
|
||||
this column's end". Typically used to see historical end balances of
|
||||
- --historical/-H : calculate with postings from journal start to column
|
||||
end, ie "all postings from before report start date until this
|
||||
column's end". Typically used to see historical end balances of
|
||||
assets/liabilities/equity. (default for balancesheet,
|
||||
balancesheetequity)
|
||||
|
||||
Valuation type
|
||||
Valuation mode
|
||||
|
||||
Which kind of value or cost conversion should be applied, if any, before
|
||||
displaying the report. It is one of:
|
||||
displaying the report. See Cost reporting and Value reporting for more
|
||||
about conversions.
|
||||
|
||||
- no valuation type : don't convert to cost or value (default)
|
||||
- --value=cost[,COMM] : convert amounts to cost (then optionally to
|
||||
some other commodity)
|
||||
A valuation (or cost) mode can be selected with the --value option:
|
||||
|
||||
- no conversion : don't convert to cost or value (default)
|
||||
- --value=cost[,COMM] : convert amounts to cost (then optionally to some
|
||||
other commodity)
|
||||
- --value=then[,COMM] : convert amounts to market value on transaction
|
||||
dates
|
||||
- --value=end[,COMM] : convert amounts to market value on period end
|
||||
date(s)
|
||||
(default with --valuechange, --gain)
|
||||
- --value=now[,COMM] : convert amounts to market value on today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on
|
||||
another date
|
||||
- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on another
|
||||
date
|
||||
|
||||
or one of the equivalent simpler flags:
|
||||
or with the legacy -B/-V/-X options, which are equivalent and easier to
|
||||
type:
|
||||
|
||||
- -B/--cost : like --value=cost (though, note --cost and --value are
|
||||
independent options which can both be used at once)
|
||||
- -B/--cost : like --value=cost
|
||||
- -V/--market : like --value=end
|
||||
- -X COMM/--exchange COMM : like --value=end,COMM
|
||||
|
||||
See Cost reporting and Value reporting for more about these.
|
||||
Note that --value can also convert to cost, as a convenience; but
|
||||
actually --cost and --value are independent options, and could be used
|
||||
together.
|
||||
|
||||
Combining balance report types
|
||||
Combining balance report modes
|
||||
|
||||
Most combinations of these options should produce reasonable reports,
|
||||
but if you find any that seem wrong or misleading, let us know. The
|
||||
Most combinations of these modes should produce reasonable reports, but
|
||||
if you find any that seem wrong or misleading, let us know. The
|
||||
following restrictions are applied:
|
||||
|
||||
- --valuechange implies --value=end
|
||||
@ -564,8 +567,8 @@ valuation show:
|
||||
|
||||
Budget report
|
||||
|
||||
The --budget report type is like a regular balance report, but with two
|
||||
main differences:
|
||||
The --budget report is like a regular balance report, but with two main
|
||||
differences:
|
||||
|
||||
- Budget goals and performance percentages are also shown, in brackets
|
||||
- Accounts which don't have budget goals are hidden by default.
|
||||
@ -628,11 +631,11 @@ version should be relatively robust and intuitive, but you may still
|
||||
find surprises. Here are more notes to help with learning and
|
||||
troubleshooting.
|
||||
|
||||
- In the above example, expenses:bus and expenses:food are shown
|
||||
because they have budget goals during the report period.
|
||||
- In the above example, expenses:bus and expenses:food are shown because
|
||||
they have budget goals during the report period.
|
||||
|
||||
- Their parent expenses is also shown, with budget goals aggregated
|
||||
from the children.
|
||||
- Their parent expenses is also shown, with budget goals aggregated from
|
||||
the children.
|
||||
|
||||
- The subaccounts expenses:food:groceries and expenses:food:dining are
|
||||
not shown since they have no budget goal of their own, but they
|
||||
@ -647,11 +650,10 @@ troubleshooting.
|
||||
- --depth or depth: can be used to limit report depth in the usual way
|
||||
(but will not reveal unbudgeted subaccounts).
|
||||
|
||||
- Amounts are always inclusive of subaccounts (even in -l/--list
|
||||
mode).
|
||||
- Amounts are always inclusive of subaccounts (even in -l/--list mode).
|
||||
|
||||
- Numbers displayed in a --budget report will not always agree with
|
||||
the totals, because of hidden unbudgeted accounts; this is normal.
|
||||
- Numbers displayed in a --budget report will not always agree with the
|
||||
totals, because of hidden unbudgeted accounts; this is normal.
|
||||
-E/--empty can be used to reveal the hidden accounts.
|
||||
|
||||
- In the periodic rules used for setting budget goals, unbalanced
|
||||
@ -662,8 +664,8 @@ troubleshooting.
|
||||
(The <unbudgeted> account is occasionally hard to exclude; this is
|
||||
because of date surprises, discussed below.)
|
||||
|
||||
- When you have multiple currencies, you may want to convert them to
|
||||
one (-X COMM --infer-market-prices) and/or show just one at a time
|
||||
- When you have multiple currencies, you may want to convert them to one
|
||||
(-X COMM --infer-market-prices) and/or show just one at a time
|
||||
(cur:COMM). If you do need to show multiple currencies at once,
|
||||
--layout bare can be helpful.
|
||||
|
||||
@ -765,11 +767,11 @@ four possible values:
|
||||
- --layout=wide[,WIDTH]: commodities are shown on a single line,
|
||||
optionally elided to WIDTH
|
||||
- --layout=tall: each commodity is shown on a separate line
|
||||
- --layout=bare: commodity symbols are in their own column, amounts
|
||||
are bare numbers
|
||||
- --layout=tidy: data is normalised to easily-consumed "tidy" form,
|
||||
with one row per data value. (This one is currently supported only
|
||||
by the balance command.)
|
||||
- --layout=bare: commodity symbols are in their own column, amounts are
|
||||
bare numbers
|
||||
- --layout=tidy: data is normalised to easily-consumed "tidy" form, with
|
||||
one row per data value. (This one is currently supported only by the
|
||||
balance command.)
|
||||
|
||||
Here are the --layout modes supported by each output format Only CSV
|
||||
output supports all of them:
|
||||
@ -901,9 +903,8 @@ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layo
|
||||
Balance report output
|
||||
|
||||
As noted in Output format, if you choose HTML output (by using -O html
|
||||
or -o somefile.html), it will use the UTF-8 text encoding, And you can
|
||||
create a hledger.css file in the same directory to customise the
|
||||
report's appearance.
|
||||
or -o somefile.html), you can create a hledger.css file in the same
|
||||
directory to customise the report's appearance.
|
||||
|
||||
The HTML and FODS output formats can generate hyperlinks to a
|
||||
hledger-web register view for each account and period. E.g. if your
|
||||
|
||||
@ -61,8 +61,7 @@ types). Or if no such accounts are declared, it shows accounts
|
||||
|
||||
- under a top-level account named asset (case insensitive, plural
|
||||
allowed)
|
||||
- whose name contains some variation of cash, bank, checking or
|
||||
saving.
|
||||
- whose name contains some variation of cash, bank, checking or saving.
|
||||
|
||||
More precisely: all accounts matching this case insensitive regular
|
||||
expression:
|
||||
|
||||
@ -28,79 +28,79 @@ These important checks are performed by default, by almost all hledger
|
||||
commands:
|
||||
|
||||
- parseable - data files are in a supported format, with no syntax
|
||||
errors and no invalid include directives. This ensures that all
|
||||
files exist and are readable.
|
||||
errors and no invalid include directives. This ensures that all files
|
||||
exist and are readable.
|
||||
|
||||
- autobalanced - all transactions are balanced, after inferring
|
||||
missing amounts and conversion costs where possible, and then
|
||||
converting to cost. This ensures that each individual transaction is
|
||||
well formed.
|
||||
- autobalanced - all transactions are balanced, after automatically
|
||||
inferring missing amounts and conversion rates and then converting
|
||||
amounts to cost. This ensures that each transaction's entry is well
|
||||
formed.
|
||||
|
||||
- assertions - all balance assertions in the journal are passing.
|
||||
Balance assertions are like canaries in your journal, they catch
|
||||
many problems. They can get in the way sometimes; you can disable
|
||||
them temporarily with -I/--ignore-assertions (unless overridden with
|
||||
-s/--strict or hledger check assertions).
|
||||
Balance assertions are a strong defense against errors; they help
|
||||
catch many problems. If this check gets in your way, you can disable
|
||||
it with -I/--ignore-assertions. Or you can add that to your config
|
||||
file to disable it by default (and then use -s/--strict or
|
||||
hledger check assertions to enable it).
|
||||
|
||||
Strict checks
|
||||
|
||||
These additional checks are performed by any command when the
|
||||
-s/--strict flag is used (strict mode). Strict mode always enables the
|
||||
balance assertions check, also. These provide extra error-catching power
|
||||
when you are serious about keeping your data clean and free of typos:
|
||||
These additional checks are performed by all commands when the
|
||||
-s/--strict flag is used (strict mode). They provide extra
|
||||
error-catching power to keep your data clean and correct. Strict mode
|
||||
also always enables the assertions check.
|
||||
|
||||
- balanced - like autobalanced, but in conversion transactions, costs
|
||||
must be written explicitly. This ensures some redundancy in the
|
||||
entry, which helps prevent typos.
|
||||
- balanced - like autobalanced, but all conversions between commodities
|
||||
must use explicit cost notation or equity postings. This prevents
|
||||
wrong conversions caused by typos.
|
||||
|
||||
- commodities - all commodity symbols used must be declared. This
|
||||
guards against mistyping or omitting commodity symbols.
|
||||
- commodities - all commodity symbols used must be declared. This guards
|
||||
against mistyping or omitting commodity symbols. Declaring commodities
|
||||
also sets their precision for display and transaction balancing.
|
||||
|
||||
- accounts - all account names used must be declared. This prevents
|
||||
the use of mis-spelled or outdated account names.
|
||||
- accounts - all account names used must be declared. This prevents the
|
||||
use of mis-spelled or outdated account names.
|
||||
|
||||
Other checks
|
||||
|
||||
These other checks are not wanted by everyone, but can be run using the
|
||||
check command:
|
||||
These are not wanted by everyone, but can be run using the check
|
||||
command:
|
||||
|
||||
- ordereddates - within each file, transactions are ordered by date.
|
||||
This is a simple and effective error catcher, and you should use it.
|
||||
Alas! not everyone wants it. If you do, use
|
||||
hledger check -s ordereddates. When enabled, this check is performed
|
||||
early, before balance assertions (because copy-pasted dates are
|
||||
often the root cause of balance assertion failures).
|
||||
- tags - all tags used must be declared. This prevents mis-spelled tag
|
||||
names. Note hledger fairly often finds unintended tags in comments.
|
||||
|
||||
- payees - all payees used by transactions must be declared. This will
|
||||
force you to always use known/declared payee names. For most people
|
||||
this is a bit too restrictive.
|
||||
- payees - all payees used in transactions must be declared. This will
|
||||
force you to declare any new payee name before using it. Most people
|
||||
will probably find this a bit too strict.
|
||||
|
||||
- tags - all tags used by transactions must be declared. This prevents
|
||||
mistyped tag names.
|
||||
- ordereddates - within each file, transactions must be ordered by date.
|
||||
This is a simple and effective error catcher. It's not included in
|
||||
strict mode, but you can add it by running
|
||||
hledger check -s ordereddates. If enabled, this check is performed
|
||||
before balance assertions.
|
||||
|
||||
- recentassertions - all accounts with balance assertions must have a
|
||||
balance assertion within the last 7 days before their latest
|
||||
posting. This encourages you to add balance assertions fairly
|
||||
regularly for your active asset/liability accounts, which in turn
|
||||
should encourage you to check and reconcile with their real world
|
||||
balances fairly regularly. close --assert can be helpful. (The older
|
||||
balance assertions become redundant; you can remove them
|
||||
periodically, or leave them in place, perhaps commented, as
|
||||
documentation.)
|
||||
- recentassertions - all accounts with balance assertions must have one
|
||||
that's within the 7 days before their latest posting. This will
|
||||
encourage adding balance assertions for your active asset/liability
|
||||
accounts, which in turn should encourage you to reconcile regularly
|
||||
with those real world balances - another strong defense against
|
||||
errors. hledger close --assert can help generate assertion entries.
|
||||
Over time the older assertions become somewhat redundant, and you can
|
||||
remove them if you like (they don't affect performance much, but they
|
||||
add some noise to the journal).
|
||||
|
||||
- uniqueleafnames - no two accounts may have the same leaf name. The
|
||||
leaf name is the last colon-separated part of an account name, eg
|
||||
checking in assets:bank:checking. This encourages you to keep those
|
||||
unique, effectively giving each account a short name which is easier
|
||||
to remember and to type in reporting commands.
|
||||
- uniqueleafnames - no two accounts may have the same last account name
|
||||
part (eg the checking in assets:bank:checking). This ensures each
|
||||
account can be matched by a unique short name, easier to remember and
|
||||
to type.
|
||||
|
||||
Custom checks
|
||||
|
||||
You can build your own custom checks with add-on command scripts. See
|
||||
also Cookbook > Scripting. Here are some examples from hledger/bin/:
|
||||
|
||||
- hledger-check-tagfiles - all tag values containing / (a forward
|
||||
slash) exist as file paths
|
||||
- hledger-check-tagfiles - all tag values containing / (a forward slash)
|
||||
exist as file paths
|
||||
|
||||
- hledger-check-fancyassertions - more complex balance assertions are
|
||||
passing
|
||||
|
||||
@ -137,8 +137,7 @@ close customisation
|
||||
In all modes, the following things can be overridden:
|
||||
|
||||
- the accounts to be closed/opened, with account query arguments
|
||||
- the balancing account, with --close-acct=ACCT and/or
|
||||
--open-acct=ACCT
|
||||
- the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
|
||||
- the transaction descriptions, with --close-desc=DESC and
|
||||
--open-desc=DESC
|
||||
- the transaction's tag value, with a --MODE=NEW option argument
|
||||
|
||||
@ -94,8 +94,7 @@ works:
|
||||
|
||||
If this goes wrong, it's relatively easy to repair:
|
||||
|
||||
- You'll notice it before import when you preview with
|
||||
import --dry-run.
|
||||
- You'll notice it before import when you preview with import --dry-run.
|
||||
- Or after import when you try to reconcile your hledger account
|
||||
balances with your bank.
|
||||
- hledger print -f FILE.csv will show all recently downloaded
|
||||
@ -190,5 +189,5 @@ data):
|
||||
|
||||
- Two or more of the new CSV records are identical, and generate
|
||||
identical new journal entries.
|
||||
- A new CSV record generates a journal entry identical to one(s)
|
||||
already in the journal.
|
||||
- A new CSV record generates a journal entry identical to one(s) already
|
||||
in the journal.
|
||||
|
||||
@ -25,11 +25,11 @@ Flags:
|
||||
--base-url=URLPREFIX in html output, generate links to hledger-web,
|
||||
with this prefix. (Usually the base url shown by
|
||||
hledger-web; can also be relative.)
|
||||
--location add file/line number tags to print output
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, beancount, csv, tsv, html, fods, json, sql.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
--location add file/line number tags to print output.
|
||||
```
|
||||
|
||||
The print command displays full journal entries (transactions)
|
||||
|
||||
@ -24,6 +24,7 @@ Flags:
|
||||
--base-url=URLPREFIX in html output, generate links to hledger-web,
|
||||
with this prefix. (Usually the base url shown by
|
||||
hledger-web; can also be relative.)
|
||||
--location add file/line number tags to print output
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, beancount, csv, tsv, html, fods, json, sql.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
@ -86,8 +87,8 @@ styles:
|
||||
|
||||
- --round=none show amounts with original precisions (default)
|
||||
- --round=soft add/remove decimal zeros in amounts (except costs)
|
||||
- --round=hard round amounts (except costs), possibly hiding
|
||||
significant digits
|
||||
- --round=hard round amounts (except costs), possibly hiding significant
|
||||
digits
|
||||
- --round=all round all amounts and costs
|
||||
|
||||
soft is good for non-lossy cleanup, formatting amounts more consistently
|
||||
@ -132,6 +133,9 @@ description is most similar to DESC. DESC should contain at least two
|
||||
characters. If there is no similar-enough match, no transaction will be
|
||||
shown and the program exit code will be non-zero.
|
||||
|
||||
With --location, print adds the source file and line number to every
|
||||
transaction, as a tag.
|
||||
|
||||
print output format
|
||||
|
||||
This command also supports the output destination and output format
|
||||
@ -141,8 +145,8 @@ csv, tsv (Added in 1.32), json and sql.
|
||||
The beancount format tries to produce Beancount-compatible output, as
|
||||
follows:
|
||||
|
||||
- Transaction and postings with unmarked status are converted to
|
||||
cleared (*) status.
|
||||
- Transaction and postings with unmarked status are converted to cleared
|
||||
(*) status.
|
||||
- Transactions' payee and note are backslash-escaped and
|
||||
double-quote-escaped and wrapped in double quotes.
|
||||
- Transaction tags are copied to Beancount #tag format.
|
||||
@ -150,12 +154,12 @@ follows:
|
||||
currency symbols like $ are converted to the corresponding currency
|
||||
names.
|
||||
- Account name parts are capitalised and unsupported characters are
|
||||
replaced with -. If an account name part does not begin with a
|
||||
letter, or if the first part is not Assets, Liabilities, Equity,
|
||||
Income, or Expenses, an error is raised. (Use --alias options to
|
||||
bring your accounts into compliance.)
|
||||
- An open directive is generated for each account used, on the
|
||||
earliest transaction date.
|
||||
replaced with -. If an account name part does not begin with a letter,
|
||||
or if the first part is not Assets, Liabilities, Equity, Income, or
|
||||
Expenses, an error is raised. (Use --alias options to bring your
|
||||
accounts into compliance.)
|
||||
- An open directive is generated for each account used, on the earliest
|
||||
transaction date.
|
||||
|
||||
Some limitations:
|
||||
|
||||
@ -182,13 +186,13 @@ $ hledger print -Ocsv
|
||||
|
||||
- There is one CSV record per posting, with the parent transaction's
|
||||
fields repeated.
|
||||
- The "txnidx" (transaction index) field shows which postings belong
|
||||
to the same transaction. (This number might change if transactions
|
||||
are reordered within the file, files are parsed/included in a
|
||||
different order, etc.)
|
||||
- The "txnidx" (transaction index) field shows which postings belong to
|
||||
the same transaction. (This number might change if transactions are
|
||||
reordered within the file, files are parsed/included in a different
|
||||
order, etc.)
|
||||
- The amount is separated into "commodity" (the symbol) and "amount"
|
||||
(numeric quantity) fields.
|
||||
- The numeric amount is repeated in either the "credit" or "debit"
|
||||
column, for convenience. (Those names are not accurate in the
|
||||
accounting sense; it just puts negative amounts under credit and
|
||||
zero or greater amounts under debit.)
|
||||
accounting sense; it just puts negative amounts under credit and zero
|
||||
or greater amounts under debit.)
|
||||
|
||||
@ -127,8 +127,8 @@ This command predates print --auto, and currently does much the same
|
||||
thing, but with these differences:
|
||||
|
||||
- with multiple files, rewrite lets rules in any file affect all other
|
||||
files. print --auto uses standard directive scoping; rules affect
|
||||
only child files.
|
||||
files. print --auto uses standard directive scoping; rules affect only
|
||||
child files.
|
||||
|
||||
- rewrite's query limits which transactions can be rewritten; all are
|
||||
printed. print --auto's query limits which transactions are printed.
|
||||
|
||||
@ -72,8 +72,8 @@ needs to know which part of the investment value is your contributions
|
||||
and which is due to the return on investment.
|
||||
|
||||
- "Cash flow" is depositing or withdrawing money, buying or selling
|
||||
assets, or otherwise converting between your investment commodity
|
||||
and any other commodity. Example:
|
||||
assets, or otherwise converting between your investment commodity and
|
||||
any other commodity. Example:
|
||||
|
||||
2019-01-01 Investing in Snake Oil
|
||||
assets:cash -$100
|
||||
@ -171,5 +171,5 @@ References:
|
||||
- Explanation of IRR
|
||||
- Explanation of TWR
|
||||
- IRR vs TWR
|
||||
- Examples of computing IRR and TWR and discussion of the limitations
|
||||
of both metrics
|
||||
- Examples of computing IRR and TWR and discussion of the limitations of
|
||||
both metrics
|
||||
|
||||
@ -35,8 +35,8 @@ a simple syntax:
|
||||
without the usual hledger first word
|
||||
- empty lines are ignored
|
||||
- text from # to end of line is a comment, and ignored
|
||||
- you can use single or double quotes to quote arguments when needed,
|
||||
as on the command line
|
||||
- you can use single or double quotes to quote arguments when needed, as
|
||||
on the command line
|
||||
- these extra commands are available: echo TEXT prints some text, and
|
||||
exit or quit ends the run.
|
||||
|
||||
|
||||
@ -1,6 +1,61 @@
|
||||
setup
|
||||
|
||||
Check and help set up various installation things.
|
||||
Check the status of the hledger installation.
|
||||
|
||||
Flags:
|
||||
no command-specific flags
|
||||
|
||||
setup tests your hledger installation and prints a list of results,
|
||||
sometimes with helpful hints. This is a good first command to run after
|
||||
installing hledger. Also after upgrading, or when something's not
|
||||
working, or just when you want a reminder of where things are.
|
||||
|
||||
It makes one network request to detect the latest hledger release
|
||||
version. It's ok if this fails or times out. It will use ANSI color by
|
||||
default, unless disabled by NO_COLOR or --color=n. It does not use a
|
||||
pager or a config file.
|
||||
|
||||
It expects that the hledger version you are running is installed in your
|
||||
PATH. If not, it will stop until you have done that (to keep things
|
||||
simple).
|
||||
|
||||
Example:
|
||||
|
||||
$ hledger setup
|
||||
Checking your hledger setup..
|
||||
Legend: good, neutral, unknown, warning
|
||||
|
||||
hledger
|
||||
* is a released version ? no hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64
|
||||
* is up to date ? yes 1.42.99 installed, latest is 1.42.1
|
||||
* is a native binary for this machine ? yes aarch64
|
||||
* is installed in PATH ? yes /Users/simon/.local/bin/hledger
|
||||
* has a system text encoding configured ? yes UTF-8, data files should use this encoding
|
||||
* has a user config file ? (optional) no
|
||||
* current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf
|
||||
* the config file is readable ? yes /Users/simon/src/hledger/hledger.conf
|
||||
|
||||
terminal
|
||||
* the NO_COLOR variable is defined ? no
|
||||
* --color is configured by config file ? no
|
||||
* hledger will use color by default ? yes
|
||||
* the PAGER variable is defined ? yes less
|
||||
* --pager is configured by config file ? no
|
||||
* hledger will use a pager when needed ? yes /opt/homebrew/bin/less
|
||||
* the LESS variable is defined ? yes
|
||||
* the HLEDGER_LESS variable is defined ? no
|
||||
* adjusting LESS variable for color etc. ? yes
|
||||
* --pretty is enabled by config file ? no tables will use ASCII characters
|
||||
* bash shell completions are installed ? ?
|
||||
* zsh shell completions are installed ? ?
|
||||
|
||||
journal
|
||||
* the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal
|
||||
* a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal
|
||||
* it includes additional files ? yes 15
|
||||
* all commodities are declared ? yes 10
|
||||
* all accounts are declared ? yes 160
|
||||
* all accounts have types ? no 14 untyped
|
||||
* accounts of each type were detected ? yes ALERXCV
|
||||
* commodities/accounts are checked ? no use -s to check commodities/accounts
|
||||
* balance assertions are checked ? yes use -I to ignore assertions
|
||||
|
||||
@ -20,9 +20,8 @@ It also shows some run time statistics:
|
||||
- throughput: the number of transactions processed per second
|
||||
- live: the peak memory in use by the program to do its work
|
||||
- alloc: the peak memory allocation from the OS as seen by GHC.
|
||||
Measuring this externally, eg with GNU time, is more accurate;
|
||||
usually that will be a larger number; sometimes (with swapping?)
|
||||
smaller.
|
||||
Measuring this externally, eg with GNU time, is more accurate; usually
|
||||
that will be a larger number; sometimes (with swapping?) smaller.
|
||||
|
||||
The stats command's run time is similar to that of a balance report.
|
||||
|
||||
|
||||
@ -14,11 +14,12 @@ sanity-check the installed hledger executable on your platform. All
|
||||
tests are expected to pass - if you ever see a failure, please report as
|
||||
a bug!
|
||||
|
||||
This command also accepts tasty test runner options, written after a --
|
||||
(double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
|
||||
ANSI colour codes disabled:
|
||||
Any arguments before a -- argument will be passed to the tasty test
|
||||
runner as test-selecting -p patterns, and any arguments after -- will be
|
||||
passed to tasty unchanged.
|
||||
|
||||
$ hledger test -- -pData.Amount --color=never
|
||||
Examples:
|
||||
|
||||
For help on these, see https://github.com/feuerbach/tasty#options
|
||||
(-- --help currently doesn't show them).
|
||||
$ hledger test # run all unit tests
|
||||
$ hledger test balance # run tests with "balance" in their name
|
||||
$ hledger test -- -h # show tasty's options
|
||||
|
||||
Loading…
Reference in New Issue
Block a user