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

;update manuals

Browse Source
This commit is contained in:
Simon Michael 2021-01-10 15:37:32 -08:00
parent de5dfe2d1b
commit 50a7914b3b
3 changed files with 1953 additions and 1573 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

459
hledger/hledger.1
View File

@ -604,11 +604,18 @@ messages.
.PP .PP
You can also force a specific reader/format by prefixing the file path You can also force a specific reader/format by prefixing the file path
with the format and a colon. with the format and a colon.
Eg to read a .dat file as csv: Eg, to read a .dat file as csv format:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger -f csv:/some/csv-file.dat stats $ hledger -f csv:/some/csv-file.dat stats
\f[R]
.fi
.PP
Or to read stdin (\f[C]-\f[R]) as timeclock format:
.IP
.nf
\f[C]
$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print -ftimeclock:- $ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print -ftimeclock:-
\f[R] \f[R]
.fi .fi
@ -1277,7 +1284,13 @@ A \f[I]any chain of market prices\f[R]: a chain of any market prices,
including both forward and reverse prices (1 and 2 above), leading from including both forward and reverse prices (1 and 2 above), leading from
A to B. A to B.
.PP .PP
Amounts for which no applicable market price can be found, are not There is a limit to the length of these price chains; if hledger reaches
that length without finding a complete chain or exhausting all
possibilities, it will give up (with a \[dq]gave up\[dq] message visible
in \f[C]--debug=2\f[R] output).
That limit is currently 1000.
.PP
Amounts for which no suitable market price can be found, are not
converted. converted.
.SS --infer-value: market prices from transactions .SS --infer-value: market prices from transactions
.PP .PP
@ -1421,7 +1434,6 @@ Convert amounts to cost, using the prices recorded in transactions.
\f[B]\f[CB]--value=then\f[B]\f[R] \f[B]\f[CB]--value=then\f[B]\f[R]
Convert amounts to their value in the default valuation commodity, using Convert amounts to their value in the default valuation commodity, using
market prices on each posting\[aq]s date. market prices on each posting\[aq]s date.
This is currently supported only by the print and register commands.
.TP .TP
\f[B]\f[CB]--value=end\f[B]\f[R] \f[B]\f[CB]--value=end\f[B]\f[R]
Convert amounts to their value in the default valuation commodity, using Convert amounts to their value in the default valuation commodity, using
@ -1604,7 +1616,7 @@ Related: #329, #1083.
.PP .PP
.TS .TS
tab(@); tab(@);
lw(10.6n) lw(13.2n) lw(13.4n) lw(11.0n) lw(13.4n) lw(8.2n). lw(9.5n) lw(11.8n) lw(12.0n) lw(17.2n) lw(12.0n) lw(7.4n).
T{ T{
Report type Report type
T}@T{ T}@T{
@ -1675,7 +1687,7 @@ cost
T}@T{ T}@T{
value at day before report or journal start value at day before report or journal start
T}@T{ T}@T{
not supported valued at day each historical posting was made
T}@T{ T}@T{
value at day before report or journal start value at day before report or journal start
T}@T{ T}@T{
@ -1742,7 +1754,7 @@ sums of costs
T}@T{ T}@T{
value at report end or today of sums of postings value at report end or today of sums of postings
T}@T{ T}@T{
not supported value at posting date
T}@T{ T}@T{
value at report or journal end of sums of postings value at report or journal end of sums of postings
T}@T{ T}@T{
@ -1755,7 +1767,7 @@ like balance changes
T}@T{ T}@T{
like balance changes like balance changes
T}@T{ T}@T{
not supported like balance changes
T}@T{ T}@T{
like balances like balances
T}@T{ T}@T{
@ -1768,7 +1780,7 @@ sum of displayed values
T}@T{ T}@T{
sum of displayed values sum of displayed values
T}@T{ T}@T{
not supported sum of displayed valued
T}@T{ T}@T{
sum of displayed values sum of displayed values
T}@T{ T}@T{
@ -1796,7 +1808,8 @@ sums of costs of postings before report start
T}@T{ T}@T{
value at report start of sums of all postings before report start value at report start of sums of all postings before report start
T}@T{ T}@T{
not supported sums of values of postings before report start at respective posting
dates
T}@T{ T}@T{
value at report start of sums of all postings before report start value at report start of sums of all postings before report start
T}@T{ T}@T{
@ -1809,7 +1822,7 @@ sums of costs of postings in period
T}@T{ T}@T{
same as --value=end same as --value=end
T}@T{ T}@T{
not supported sums of values of postings in period at respective posting dates
T}@T{ T}@T{
balance change in each period, valued at period ends balance change in each period, valued at period ends
T}@T{ T}@T{
@ -1822,7 +1835,8 @@ sums of costs of postings from before report start to period end
T}@T{ T}@T{
same as --value=end same as --value=end
T}@T{ T}@T{
not supported sums of values of postings from before period start to period end at
respective posting dates
T}@T{ T}@T{
period end balances, valued at period ends period end balances, valued at period ends
T}@T{ T}@T{
@ -1835,7 +1849,7 @@ like balance changes/end balances
T}@T{ T}@T{
like balance changes/end balances like balance changes/end balances
T}@T{ T}@T{
not supported like balance changes/end balances
T}@T{ T}@T{
like balances like balances
T}@T{ T}@T{
@ -1848,7 +1862,7 @@ sums, averages of displayed values
T}@T{ T}@T{
sums, averages of displayed values sums, averages of displayed values
T}@T{ T}@T{
not supported sums, averages of displayed values
T}@T{ T}@T{
sums, averages of displayed values sums, averages of displayed values
T}@T{ T}@T{
@ -1861,7 +1875,7 @@ sums of displayed values
T}@T{ T}@T{
sums of displayed values sums of displayed values
T}@T{ T}@T{
not supported sums of displayed values
T}@T{ T}@T{
sums of displayed values sums of displayed values
T}@T{ T}@T{
@ -1874,7 +1888,7 @@ sum, average of column totals
T}@T{ T}@T{
sum, average of column totals sum, average of column totals
T}@T{ T}@T{
not supported sum, average of column totals
T}@T{ T}@T{
sum, average of column totals sum, average of column totals
T}@T{ T}@T{
@ -2449,10 +2463,39 @@ options The output formats supported are (in most modes): \f[C]txt\f[R],
\f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R]. \f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R].
.PP .PP
The balance command can produce several styles of report: The balance command can produce several styles of report:
.SS Classic balance report
.PP .PP
This is the original balance report, as found in Ledger. .SS Single-period flat balance report
It usually looks like this: .PP
This is the default for hledger\[aq]s balance command: a flat list of
all (or with a query, matched) accounts, showing full account names.
Accounts are sorted by declaration order if any, and then by account
name.
Accounts which have zero balance are not shown unless
\f[C]-E/--empty\f[R] is used.
The reported balances\[aq] total is shown as the last line, unless
disabled by \f[C]-N\f[R]/\f[C]--no-total\f[R].
.IP
.nf
\f[C]
$ hledger bal
$1 assets:bank:saving
$-2 assets:cash
$1 expenses:food
$1 expenses:supplies
$-1 income:gifts
$-1 income:salary
$1 liabilities:debts
--------------------
0
\f[R]
.fi
.PP
.SS Single-period tree-mode balance report
.PP
With the \f[C]-t/--tree\f[R] flag, accounts are displayed
hierarchically, showing subaccounts as short names indented below their
parent.
(This is the default style in Ledger and in older hledger versions.)
.IP .IP
.nf .nf
\f[C] \f[C]
@ -2472,38 +2515,30 @@ $ hledger balance
\f[R] \f[R]
.fi .fi
.PP .PP
By default, accounts are displayed hierarchically, with subaccounts For more compact output, \[dq]boring\[dq] accounts containing a single
indented below their parent, with accounts at each level of the tree interesting subaccount and no balance of their own
sorted by declaration order if declared, then by account name. (\f[C]assets:bank\f[R] and \f[C]liabilities\f[R] here) are elided into
the following line, unless \f[C]--no-elide\f[R] is used.
And accounts which have zero balance and no non-zero subaccounts are
omitted, unless \f[C]-E/--empty\f[R] is used.
.PP .PP
\[dq]Boring\[dq] accounts, which contain a single interesting subaccount Account balances in tree mode are \[dq]inclusive\[dq] - they include the
and no balance of their own, are elided into the following line for more balances of any subaccounts.
compact output. Eg, the \f[C]assets\f[R] \f[C]$-1\f[R] balance here includes the
(Eg above, the \[dq]liabilities\[dq] account.) Use \f[C]--no-elide\f[R] \f[C]$1\f[R] from \f[C]assets:bank:saving\f[R] and the \f[C]$-2\f[R]
to prevent this. from \f[C]assets:cash\f[R].
(And it would include balance posted to the \f[C]assets\f[R] account
itself, if there was any).
Note this causes some repetition, and the final total (\f[C]0\f[R]) is
the sum of the top-level balances, not of all the balances shown.
.PP .PP
Account balances are \[dq]inclusive\[dq] - they include the balances of Each group of sibling accounts is sorted separately, by declaration
any subaccounts. order and then by account name.
.SS Customising single-period balance reports
.PP .PP
Accounts which have zero balance (and no non-zero subaccounts) are You can customise the layout of single-period balance reports with
omitted. \f[C]--format FMT\f[R], which sets the format of each line.
Use \f[C]-E/--empty\f[R] to show them. Eg:
.PP
A final total is displayed by default; use \f[C]-N/--no-total\f[R] to
suppress it, eg:
.IP
.nf
\f[C]
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
\f[R]
.fi
.SS Customising the classic balance report
.PP
You can customise the layout of classic balance reports with
\f[C]--format FMT\f[R]:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -2572,32 +2607,13 @@ rendered on one line
.IP \[bu] 2 .IP \[bu] 2
\f[C]%20(total) %2(depth_spacer)%-(account)\f[R] - the default format \f[C]%20(total) %2(depth_spacer)%-(account)\f[R] - the default format
for the single-column balance report for the single-column balance report
.SS Colour support .SS Depth limiting
.PP .PP
In terminal output, when colour is enabled, the balance command shows With a \f[C]depth:N\f[R] query, or \f[C]--depth N\f[R] option, or just
negative amounts in red. \f[C]-N\f[R], balance reports will show accounts only to the specified
.SS Flat mode depth.
.PP This is very useful to hide low-level accounts and get an overview.
To see a flat list instead of the default hierarchical display, use Eg, limiting to depth 1 shows the top-level accounts:
\f[C]--flat\f[R].
In this mode, accounts (unless depth-clipped) show their full names and
\[dq]exclusive\[dq] balance, excluding any subaccount balances.
In this mode, you can also use \f[C]--drop N\f[R] to omit the first few
account name components.
.IP
.nf
\f[C]
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies
\f[R]
.fi
.SS Depth limited balance reports
.PP
With \f[C]--depth N\f[R] or \f[C]depth:N\f[R] or just \f[C]-N\f[R],
balance reports show accounts only to the specified numeric depth.
This is very useful to summarise a complex set of accounts and get an
overview.
.IP .IP
.nf .nf
\f[C] \f[C]
@ -2609,8 +2625,30 @@ $ hledger balance -N -1
\f[R] \f[R]
.fi .fi
.PP .PP
Flat-mode balance reports, which normally show exclusive balances, show Accounts at the depth limit will include the balances of any hidden
inclusive balances at the depth limit. subaccounts (even in flat mode, which normally shows exclusive
balances).
.PP
You can also drop account name components from the start of account
names, using \f[C]--drop N\f[R].
This can be useful to hide unwanted top-level detail.
.SS Colour support
.PP
In terminal output, when colour is enabled, the balance command shows
negative amounts in red.
.SS Sorting by amount
.PP
With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest
(most positive) balances are shown first.
For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest
averaged monthly expenses first.
.PP
Revenues and liability balances are typically negative, however, so
\f[C]-S\f[R] shows these in reverse order.
To work around this, you can add \f[C]--invert\f[R] to flip the signs.
Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or
\f[C]incomestatement\f[R], which also support \f[C]-S\f[R].
Eg: \f[C]hledger is -MAS\f[R].
.SS Percentages .SS Percentages
.PP .PP
With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each
@ -2646,34 +2684,25 @@ accounts.
If there are mixed commodity accounts in the report be sure to use If there are mixed commodity accounts in the report be sure to use
\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single \f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single
commodity. commodity.
.SS Sorting by amount
.PP .PP
With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest .SS Multi-period balance report
(most positive) balances are shown first.
For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest
averaged monthly expenses first.
.PP .PP
Revenues and liability balances are typically negative, however, so Multi-period balance reports are a very useful hledger feature,
\f[C]-S\f[R] shows these in reverse order. activated if you provide one of the reporting interval flags, such as
To work around this, you can add \f[C]--invert\f[R] to flip the signs. \f[C]-M\f[R]/\f[C]--monthly\f[R].
Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or They are similar to single-period balance reports, but they show the
\f[C]incomestatement\f[R], which also support \f[C]-S\f[R]. report as a table, with columns representing one or more successive time
Eg: \f[C]hledger is -MAS\f[R]. periods.
.SS Multicolumn balance report This is the usually the preferred style of balance report in hledger
(even for a single period).
.PP .PP
Multicolumn or tabular balance reports are a very useful hledger Multi-period balance reports come in several types, showing different
feature, and usually the preferred style.
They share many of the above features, but they show the report as a
table, with columns representing time periods.
This mode is activated by providing a reporting interval.
.PP
There are three types of multicolumn balance report, showing different
information: information:
.IP "1." 3 .IP "1." 3
By default: each column shows the sum of postings in that period, ie the A balance change report: by default, each column shows the sum of
account\[aq]s change of balance in that period. postings in that period, ie the account\[aq]s change of balance in that
period.
This is useful eg for a monthly income statement: This is useful eg for a monthly income statement:
.RS 4
.IP .IP
.nf .nf
\f[C] \f[C]
@ -2690,11 +2719,10 @@ Balance changes in 2008:
|| $-1 $1 0 0 || $-1 $1 0 0
\f[R] \f[R]
.fi .fi
.RE
.IP "2." 3 .IP "2." 3
With \f[C]--cumulative\f[R]: each column shows the ending balance for A cumulative end balance report: with \f[C]--cumulative\f[R], each
that period, accumulating the changes across periods, starting from 0 at column shows the end balance for that period, accumulating the changes
the report start date: across periods, starting from 0 at the report start date:
.RS 4 .RS 4
.IP .IP
.nf .nf
@ -2714,11 +2742,12 @@ Ending balances (cumulative) in 2008:
.fi .fi
.RE .RE
.IP "3." 3 .IP "3." 3
With \f[C]--historical/-H\f[R]: each column shows the actual historical A historical end balance report: with \f[C]--historical/-H\f[R], each
ending balance for that period, accumulating the changes across periods, column shows the actual historical end balance for that period,
starting from the actual balance at the report start date. accumulating the changes across periods, and including the balance from
This is useful eg for a multi-period balance sheet, and when you are any postings before the report start date.
showing only the data after a certain start date: This is useful eg for a multi-period balance sheet, and when you want to
see balances only after a certain date:
.RS 4 .RS 4
.IP .IP
.nf .nf
@ -2742,9 +2771,6 @@ Note that \f[C]--cumulative\f[R] or \f[C]--historical/-H\f[R] disable
\f[C]--row-total/-T\f[R], since summing end balances generally does not \f[C]--row-total/-T\f[R], since summing end balances generally does not
make sense. make sense.
.PP .PP
Multicolumn balance reports display accounts in flat mode by default; to
see the hierarchy, use \f[C]--tree\f[R].
.PP
With a reporting interval (like \f[C]--quarterly\f[R] above), the report With a reporting interval (like \f[C]--quarterly\f[R] above), the report
start/end dates will be adjusted if necessary so that they encompass the start/end dates will be adjusted if necessary so that they encompass the
displayed report periods. displayed report periods.
@ -3263,27 +3289,29 @@ check
.P .P
.PD .PD
Check for various kinds of errors in your data. Check for various kinds of errors in your data.
\f[I]experimental\f[R]
.PP .PP
hledger provides a number of built-in error checks to help prevent hledger provides a number of built-in error checks to help prevent
problems in your data. problems in your data.
Some of these are run automatically; or, you can use this Some of these are run automatically; or, you can use this
\f[C]check\f[R] command to run them on demand, with no output and a zero \f[C]check\f[R] command to run them on demand, with no output and a zero
exit code if all is well. exit code if all is well.
Specify their names (or a prefix) as argument(s).
.PP
Some examples: Some examples:
.IP .IP
.nf .nf
\f[C] \f[C]
hledger check # basic checks hledger check # basic checks
hledger check -s # basic + strict checks hledger check -s # basic + strict checks
hledger check ordereddates uniqueleafnames # basic + specified checks hledger check ordereddates payees # basic + two other checks
\f[R] \f[R]
.fi .fi
.PP .PP
Here are the checks currently available: Here are the checks currently available:
.SS Basic checks .SS Basic checks
.PP .PP
These are always run by this command and other commands: These checks are always run automatically, by (almost) all hledger
commands, including \f[C]check\f[R]:
.IP \[bu] 2 .IP \[bu] 2
\f[B]parseable\f[R] - data files are well-formed and can be successfully \f[B]parseable\f[R] - data files are well-formed and can be successfully
parsed parsed
@ -3298,8 +3326,10 @@ passing.
\f[C]-I\f[R]/\f[C]--ignore-assertions\f[R].) \f[C]-I\f[R]/\f[C]--ignore-assertions\f[R].)
.SS Strict checks .SS Strict checks
.PP .PP
These are always run by this and other commands when These additional checks are run when the \f[C]-s\f[R]/\f[C]--strict\f[R]
\f[C]-s\f[R]/\f[C]--strict\f[R] is used (strict mode): (strict mode) flag is used.
Or, they can be run by giving their names as arguments to
\f[C]check\f[R]:
.IP \[bu] 2 .IP \[bu] 2
\f[B]accounts\f[R] - all account names used by transactions have been \f[B]accounts\f[R] - all account names used by transactions have been
declared declared
@ -3307,18 +3337,21 @@ declared
\f[B]commodities\f[R] - all commodity symbols used have been declared \f[B]commodities\f[R] - all commodity symbols used have been declared
.SS Other checks .SS Other checks
.PP .PP
These checks can be run by specifying their names as arguments to the These checks can be run only by giving their names as arguments to
check command: \f[C]check\f[R].
They are more specialised and not desirable for everyone, therefore
optional:
.IP \[bu] 2 .IP \[bu] 2
\f[B]ordereddates\f[R] - transactions are ordered by date (similar to \f[B]ordereddates\f[R] - transactions are ordered by date (similar to
the old \f[C]check-dates\f[R] command) the old \f[C]check-dates\f[R] command)
.IP \[bu] 2 .IP \[bu] 2
\f[B]payees\f[R] - all payees used by transactions have been declared
.IP \[bu] 2
\f[B]uniqueleafnames\f[R] - all account leaf names are unique (similar \f[B]uniqueleafnames\f[R] - all account leaf names are unique (similar
to the old \f[C]check-dupes\f[R] command) to the old \f[C]check-dupes\f[R] command).
.SS Add-on checks .SS Custom checks
.PP .PP
Some checks are not yet integrated with this command, but are available A few more checks are are available as separate add-on commands, in
as add-on commands in
https://github.com/simonmichael/hledger/tree/master/bin: https://github.com/simonmichael/hledger/tree/master/bin:
.IP \[bu] 2 .IP \[bu] 2
\f[B]hledger-check-tagfiles\f[R] - all tag values containing / (a \f[B]hledger-check-tagfiles\f[R] - all tag values containing / (a
@ -3327,8 +3360,8 @@ forward slash) exist as file paths
\f[B]hledger-check-fancyassertions\f[R] - more complex balance \f[B]hledger-check-fancyassertions\f[R] - more complex balance
assertions are passing assertions are passing
.PP .PP
You could make your own similar scripts to perform custom checks; You could make similar scripts to perform your own custom checks.
Cookbook -> Scripting may be helpful. See: Cookbook -> Scripting.
.SS close .SS close
.PP .PP
close, equity close, equity
@ -5198,7 +5231,7 @@ Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. from which hledger derives a hierarchical chart of accounts.
They can be anything you like, but in finance there are traditionally They can be anything you like, but in finance there are traditionally
five top-level accounts: \f[C]assets\f[R], \f[C]liabilities\f[R], five top-level accounts: \f[C]assets\f[R], \f[C]liabilities\f[R],
\f[C]income\f[R], \f[C]expenses\f[R], and \f[C]equity\f[R]. \f[C]revenue\f[R], \f[C]expenses\f[R], and \f[C]equity\f[R].
.PP .PP
Account names may contain single spaces, eg: Account names may contain single spaces, eg:
\f[C]assets:accounts receivable\f[R]. \f[C]assets:accounts receivable\f[R].
@ -5808,6 +5841,15 @@ T}@T{
what the included directives affect what the included directives affect
T} T}
T{ T{
[\f[C]payee\f[R]]
T}@T{
T}@T{
T}@T{
declare a payee name
T}@T{
following entries until end of current file
T}
T{
\f[C]P\f[R] \f[C]P\f[R]
T}@T{ T}@T{
T}@T{ T}@T{
@ -5952,6 +5994,19 @@ Y2010 ; change default year to 2010
assets assets
\f[R] \f[R]
.fi .fi
.SS Declaring payees
.PP
The \f[C]payee\f[R] directive can be used to declare a limited set of
payees which may appear in transaction descriptions.
The \[dq]payees\[dq] check will report an error if any transaction
refers to a payee that has not been declared.
Eg:
.IP
.nf
\f[C]
payee Whole Foods
\f[R]
.fi
.SS Declaring commodities .SS Declaring commodities
.PP .PP
The \f[C]commodity\f[R] directive has several functions: The \f[C]commodity\f[R] directive has several functions:
@ -7961,32 +8016,148 @@ https://hledger.org -> sidebar -> real world setups
https://plaintextaccounting.org -> data import/conversion https://plaintextaccounting.org -> data import/conversion
.SS Setting amounts .SS Setting amounts
.PP .PP
A posting amount can be set in one of these ways: Some tips on using the amount-setting rules discussed above.
.IP \[bu] 2
by assigning (with a fields list or field assignment) to
\f[C]amountN\f[R] (posting N\[aq]s amount) or \f[C]amount\f[R] (posting
1\[aq]s amount)
.IP \[bu] 2
by assigning to \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] (or
\f[C]amount-in\f[R] and \f[C]amount-out\f[R]).
For each CSV record, whichever of these has a non-zero value will be
used, with appropriate sign.
If both contain a non-zero value, this may not work.
.IP \[bu] 2
by assigning to \f[C]balanceN\f[R] (or \f[C]balance\f[R]) instead of the
above, setting the amount indirectly via a balance assignment.
If you do this the default account name may be wrong, so you should set
that explicitly.
.PP .PP
There is some special handling for an amount\[aq]s sign: Here are the ways to set a posting\[aq]s amount:
.IP "1." 3
\f[B]If the CSV has a single amount field:\f[R]
.PD 0
.P
.PD
Assign (via a fields list or a field assignment) to \f[C]amountN\f[R].
This sets the Nth posting\[aq]s amount.
N is usually 1 or 2 but can go up to 99.
.IP "2." 3
\f[B]If the CSV has separate Debit and Credit amount fields:\f[R]
.PD 0
.P
.PD
Assign to \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R].
This sets posting N\[aq]s amount to whichever of these has a non-zero
value, guessing an appropriate sign.
.RS 4
.IP \[bu] 2 .IP \[bu] 2
If an amount value is parenthesised, it will be de-parenthesised and \f[B]If hledger guesses the wrong sign:\f[R]
sign-flipped. .PD 0
.P
.PD
Prepend a minus sign to flip it.
Eg:
.RS 2
.IP
.nf
\f[C]
fields date, description, amount-in, amount-out
amount-out -%amount-out
\f[R]
.fi
.RE
.IP \[bu] 2 .IP \[bu] 2
If an amount value begins with a double minus sign, those cancel out and \f[B]If both fields contain a non-zero value:\f[R]
are removed. .PD 0
.P
.PD
The \f[C]amountN-in\f[R]/\f[C]amountN-out\f[R] rules require that each
CSV record has a non-zero value in exactly one of the two fields, so
that hledger knows which to choose.
So these would all be rejected:
.RS 2
.IP
.nf
\f[C]
\[dq]\[dq], \[dq]\[dq]
\[dq]0\[dq], \[dq]0\[dq]
\[dq]1\[dq], \[dq]none\[dq]
\f[R]
.fi
.PP
If your CSV has amount values like this, use conditional rules instead.
For example, to make hledger to choose the value containing non-zero
digits:
.IP
.nf
\f[C]
fields date, description, in, out
if %in [1-9]
amount1 %in
if %out [1-9]
amount1 %out
\f[R]
.fi
.RE
.RE
.IP "3." 3
\f[B]Using the old numberless syntax:\f[R]
.PD 0
.P
.PD
Assign to \f[C]amount\f[R] (or to \f[C]amount-in\f[R] and
\f[C]amount-out\f[R]).
This sets posting 1\[aq]s and posting 2\[aq]s amounts (and converts
posting 2\[aq]s amount to cost).
This is supported for backwards compatibility (and occasional
convenience).
.IP "4." 3
\f[B]If the CSV has the balance instead of the transaction amount:\f[R]
.PD 0
.P
.PD
Assign to \f[C]balanceN\f[R], which sets posting N\[aq]s amount
indirectly via a balance assignment.
(Old syntax: \f[C]balance\f[R], equivalent to \f[C]balance1\f[R].)
.RS 4
.IP \[bu] 2 .IP \[bu] 2
If an amount value begins with a plus sign, that will be removed \f[B]If hledger guesses the wrong default account name:\f[R]
.PD 0
.P
.PD
When setting the amount via balance assertion, hledger may guess the
wrong default account name.
So, set the account name explicitly, eg:
.RS 2
.IP
.nf
\f[C]
fields date, description, balance1
account1 assets:checking
\f[R]
.fi
.RE
.RE
.SS Amount signs
.PP
There is some special handling for amount signs, to simplify parsing and
sign-flipping:
.IP \[bu] 2
\f[B]If an amount value begins with a plus sign:\f[R]
.PD 0
.P
.PD
that will be removed: \f[C]+AMT\f[R] becomes \f[C]AMT\f[R]
.IP \[bu] 2
\f[B]If an amount value is parenthesised:\f[R]
.PD 0
.P
.PD
it will be de-parenthesised and sign-flipped: \f[C](AMT)\f[R] becomes
\f[C]-AMT\f[R]
.IP \[bu] 2
\f[B]If an amount value has two minus signs (or two sets of parentheses,
or a minus sign and parentheses):\f[R]
.PD 0
.P
.PD
they cancel out and will be removed: \f[C]--AMT\f[R] or \f[C]-(AMT)\f[R]
becomes \f[C]AMT\f[R]
.IP \[bu] 2
\f[B]If an amount value contains just a sign (or just a set of
parentheses):\f[R]
.PD 0
.P
.PD
that is removed, making it an empty value.
\f[C]\[dq]+\[dq]\f[R] or \f[C]\[dq]-\[dq]\f[R] or \f[C]\[dq]()\[dq]\f[R]
becomes \f[C]\[dq]\[dq]\f[R].
.SS Setting currency/commodity .SS Setting currency/commodity
.PP .PP
If the currency/commodity symbol is included in the CSV\[aq]s amount If the currency/commodity symbol is included in the CSV\[aq]s amount

1424
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

463
hledger/hledger.txt
View File

@ -453,9 +453,12 @@ DATA FILES
relevant error messages. relevant error messages.
You can also force a specific reader/format by prefixing the file path You can also force a specific reader/format by prefixing the file path
with the format and a colon. Eg to read a .dat file as csv: with the format and a colon. Eg, to read a .dat file as csv format:
$ hledger -f csv:/some/csv-file.dat stats $ hledger -f csv:/some/csv-file.dat stats
Or to read stdin (-) as timeclock format:
$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
Multiple files Multiple files
@ -557,7 +560,6 @@ TIME PERIODS
Examples: Examples:
-b 2016/3/17 begin on St. Patrick's day 2016 -b 2016/3/17 begin on St. Patrick's day 2016
-e 12/1 end at the start of december 1st of the current year -e 12/1 end at the start of december 1st of the current year
(11/30 will be the last date included) (11/30 will be the last date included)
-b thismonth all transactions on or after the 1st of the current month -b thismonth all transactions on or after the 1st of the current month
@ -627,8 +629,6 @@ TIME PERIODS
-p "2009Q1" first quarter of 2009, -p "2009Q1" first quarter of 2009,
equivalent to "2009/1/1 to equivalent to "2009/1/1 to
2009/4/1" 2009/4/1"
-p "q4" fourth quarter of the cur- -p "q4" fourth quarter of the cur-
rent year rent year
@ -873,7 +873,12 @@ VALUATION
ing both forward and reverse prices (1 and 2 above), leading from A ing both forward and reverse prices (1 and 2 above), leading from A
to B. to B.
Amounts for which no applicable market price can be found, are not con- There is a limit to the length of these price chains; if hledger
reaches that length without finding a complete chain or exhausting all
possibilities, it will give up (with a "gave up" message visible in
--debug=2 output). That limit is currently 1000.
Amounts for which no suitable market price can be found, are not con-
verted. verted.
--infer-value: market prices from transactions --infer-value: market prices from transactions
@ -986,8 +991,7 @@ VALUATION
--value=then --value=then
Convert amounts to their value in the default valuation commod- Convert amounts to their value in the default valuation commod-
ity, using market prices on each posting's date. This is cur- ity, using market prices on each posting's date.
rently supported only by the print and register commands.
--value=end --value=end
Convert amounts to their value in the default valuation commod- Convert amounts to their value in the default valuation commod-
@ -1124,88 +1128,105 @@ VALUATION
problems, please report them, ideally with a reproducible example. Re- problems, please report them, ideally with a reproducible example. Re-
lated: #329, #1083. lated: #329, #1083.
Report type -B, -V, -X --value=then --value=end --value=DATE, Report -B, -V, -X --value=then --value=end --value=DATE,
--value=cost --value=now type --value=cost --value=now
-------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------
print print
posting cost value at re- value at value at re- value at posting cost value at re- value at posting value at re- value at
amounts port end or posting date port or jour- DATE/today amounts port end or date port or DATE/today
today nal end today journal end
balance unchanged unchanged unchanged unchanged unchanged
balance as- unchanged unchanged unchanged unchanged unchanged asser-
ser-
tions/as- tions/as-
signments signments
register register
starting cost value at day not sup- value at day value at
balance before report ported before report DATE/today
(-H) or journal or journal
starting cost value at day valued at day value at day value at
balance before re- each historical before re- DATE/today
(-H) port or posting was made port or
journal journal
start start start start
posting cost value at re- value at value at re- value at posting cost value at re- value at posting value at re- value at
amounts port end or posting date port or jour- DATE/today amounts port end or date port or DATE/today
today nal end today journal end
summary summarised value at pe- sum of post- value at pe- value at summary summarised value at pe- sum of postings value at pe- value at
posting cost riod ends ings in in- riod ends DATE/today posting cost riod ends in interval, val- riod ends DATE/today
amounts terval, val- amounts ued at interval
with report ued at in- with re- start
interval terval start port in-
running to- sum/average sum/average sum/average sum/average sum/average terval
tal/average of displayed of displayed of displayed of displayed of displayed running sum/average sum/average sum/average of sum/average sum/average
values values values values values total/av- of displayed of displayed displayed values of displayed of displayed
erage values values values values
balance balance
(bs, bse, (bs, bse,
cf, is) cf, is)
balance sums of costs value at re- not sup- value at re- value at balance sums of value at re- value at posting value at re- value at
changes port end or ported port or jour- DATE/today of changes costs port end or date port or DATE/today of
today of sums nal end of sums of post- today of journal end sums of post-
of postings sums of post- ings sums of of sums of ings
ings postings postings
budget like balance like balance not sup- like balances like balance budget like balance like balance like balance like bal- like balance
amounts changes changes ported changes amounts changes changes changes ances changes
(--budget) (--bud-
grand total sum of dis- sum of dis- not sup- sum of dis- sum of dis- get)
played values played values ported played values played values grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis-
tal played val- played val- valued played val- played values
ues ues ues
balance balance
(bs, bse, (bs, bse,
cf, is) cf, is)
with report with re-
interval port in-
starting sums of costs value at re- not sup- value at re- sums of post- terval
balances of postings port start of ported port start of ings before starting sums of value at re- sums of values of value at re- sums of post-
(-H) before report sums of all sums of all report start balances costs of port start postings before port start ings before
start postings be- postings be- (-H) postings be- of sums of report start at of sums of report start
fore report fore report fore report all postings respective post- all postings
start start start before re- ing dates before re-
balance sums of costs same as not sup- balance value at port start port start
changes of postings --value=end ported change in DATE/today of balance sums of same as sums of values of balance value at
(bal, is, in period each period, sums of post- changes costs of --value=end postings in pe- change in DATE/today of
bs valued at pe- ings (bal, is, postings in riod at respec- each period, sums of post-
--change, riod ends bs period tive posting valued at ings
--change, dates period ends
cf cf
--change) --change)
end bal- sums of costs same as not sup- period end value at end bal- sums of same as sums of values of period end value at
ances (bal of postings --value=end ported balances, DATE/today of ances costs of --value=end postings from be- balances, DATE/today of
-H, is --H, from before valued at pe- sums of post- (bal -H, postings fore period start valued at sums of post-
bs, cf) report start riod ends ings is --H, from before to period end at period ends ings
to period end bs, cf) report start respective post-
budget like balance like balance not sup- like balances like balance to period ing dates
amounts changes/end changes/end ported changes/end end
(--budget) balances balances balances budget like balance like balance like balance like bal- like balance
row totals, sums, aver- sums, aver- not sup- sums, aver- sums, aver- amounts changes/end changes/end changes/end bal- ances changes/end
row aver- ages of dis- ages of dis- ported ages of dis- ages of dis- (--bud- balances balances ances balances
ages (-T, played values played values played values played values get)
-A) row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver-
column to- sums of dis- sums of dis- not sup- sums of dis- sums of dis- tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis-
tals played values played values ported played values played values averages played val- played val- played val- played values
grand to- sum, average sum, average not sup- sum, average sum, average (-T, -A) ues ues ues
tal, grand of column to- of column to- ported of column to- of column to- column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis-
average tals tals tals tals totals played val- played val- values played val- played values
ues ues ues
grand to- sum, average sum, average sum, average of sum, average sum, average
tal, of column of column column totals of column of column to-
grand av- totals totals totals tals
erage
--cumulative is omitted to save space, it works like -H but with a zero --cumulative is omitted to save space, it works like -H but with a zero
starting balance. starting balance.
@ -1664,9 +1685,29 @@ COMMANDS
The balance command can produce several styles of report: The balance command can produce several styles of report:
Classic balance report Single-period flat balance report
This is the original balance report, as found in Ledger. It usually This is the default for hledger's balance command: a flat list of all
looks like this: (or with a query, matched) accounts, showing full account names. Ac-
counts are sorted by declaration order if any, and then by account
name. Accounts which have zero balance are not shown unless -E/--empty
is used. The reported balances' total is shown as the last line, un-
less disabled by -N/--no-total.
$ hledger bal
$1 assets:bank:saving
$-2 assets:cash
$1 expenses:food
$1 expenses:supplies
$-1 income:gifts
$-1 income:salary
$1 liabilities:debts
--------------------
0
Single-period tree-mode balance report
With the -t/--tree flag, accounts are displayed hierarchically, showing
subaccounts as short names indented below their parent. (This is the
default style in Ledger and in older hledger versions.)
$ hledger balance $ hledger balance
$-1 assets $-1 assets
@ -1682,32 +1723,25 @@ COMMANDS
-------------------- --------------------
0 0
By default, accounts are displayed hierarchically, with subaccounts in- For more compact output, "boring" accounts containing a single inter-
dented below their parent, with accounts at each level of the tree esting subaccount and no balance of their own (assets:bank and liabili-
sorted by declaration order if declared, then by account name. ties here) are elided into the following line, unless --no-elide is
used. And accounts which have zero balance and no non-zero subaccounts
are omitted, unless -E/--empty is used.
"Boring" accounts, which contain a single interesting subaccount and no Account balances in tree mode are "inclusive" - they include the bal-
balance of their own, are elided into the following line for more com- ances of any subaccounts. Eg, the assets $-1 balance here includes the
pact output. (Eg above, the "liabilities" account.) Use --no-elide to $1 from assets:bank:saving and the $-2 from assets:cash. (And it would
prevent this. include balance posted to the assets account itself, if there was any).
Note this causes some repetition, and the final total (0) is the sum of
the top-level balances, not of all the balances shown.
Account balances are "inclusive" - they include the balances of any Each group of sibling accounts is sorted separately, by declaration or-
subaccounts. der and then by account name.
Accounts which have zero balance (and no non-zero subaccounts) are Customising single-period balance reports
omitted. Use -E/--empty to show them. You can customise the layout of single-period balance reports with
--format FMT, which sets the format of each line. Eg:
A final total is displayed by default; use -N/--no-total to suppress
it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
Customising the classic balance report
You can customise the layout of classic balance reports with --format
FMT:
$ hledger balance --format "%20(account) %12(total)" $ hledger balance --format "%20(account) %12(total)"
assets $-1 assets $-1
@ -1769,25 +1803,11 @@ COMMANDS
o %20(total) %2(depth_spacer)%-(account) - the default format for the o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report single-column balance report
Colour support Depth limiting
In terminal output, when colour is enabled, the balance command shows With a depth:N query, or --depth N option, or just -N, balance reports
negative amounts in red. 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
Flat mode shows the top-level accounts:
To see a flat list instead of the default hierarchical display, use
--flat. In this mode, accounts (unless depth-clipped) show their full
names and "exclusive" balance, excluding any subaccount balances. In
this mode, you can also use --drop N to omit the first few account name
components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies
Depth limited balance reports
With --depth N or depth:N or just -N, balance reports show accounts
only to the specified numeric depth. This is very useful to summarise
a complex set of accounts and get an overview.
$ hledger balance -N -1 $ hledger balance -N -1
$-1 assets $-1 assets
@ -1795,8 +1815,28 @@ COMMANDS
$-2 income $-2 income
$1 liabilities $1 liabilities
Flat-mode balance reports, which normally show exclusive balances, show Accounts at the depth limit will include the balances of any hidden
inclusive balances at the depth limit. subaccounts (even in flat mode, which normally shows exclusive bal-
ances).
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) bal-
ances 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 --in-
vert 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 Percentages
With -% or --percent, balance reports show each account's value ex- With -% or --percent, balance reports show each account's value ex-
@ -1825,30 +1865,20 @@ COMMANDS
counts. If there are mixed commodity accounts in the report be sure to counts. 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. use -V or -B to coerce the report into using a single commodity.
Sorting by amount Multi-period balance report
With -S/--sort-amount, accounts with the largest (most positive) bal- Multi-period balance reports are a very useful hledger feature, acti-
ances are shown first. For example, hledger bal expenses -MAS shows vated if you provide one of the reporting interval flags, such as
your biggest averaged monthly expenses first. -M/--monthly. They are similar to single-period balance reports, but
they show the report as a table, with columns representing one or more
successive time periods. This is the usually the preferred style of
balance report in hledger (even for a single period).
Revenues and liability balances are typically negative, however, so -S Multi-period balance reports come in several types, showing different
shows these in reverse order. To work around this, you can add --in-
vert to flip the signs. Or, use one of the sign-flipping reports like
balancesheet or incomestatement, which also support -S. Eg: hledger is
-MAS.
Multicolumn balance report
Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent-
ing time periods. This mode is activated by providing a reporting in-
terval.
There are three types of multicolumn balance report, showing different
information: information:
1. By default: each column shows the sum of postings in that period, ie 1. A balance change report: by default, each column shows the sum of
the account's change of balance in that period. This is useful eg postings in that period, ie the account's change of balance in that
for a monthly income statement: period. This is useful eg for a monthly income statement:
$ hledger balance --quarterly income expenses -E $ hledger balance --quarterly income expenses -E
Balance changes in 2008: Balance changes in 2008:
@ -1862,9 +1892,9 @@ COMMANDS
-------------------++--------------------------------- -------------------++---------------------------------
|| $-1 $1 0 0 || $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that pe- 2. A cumulative end balance report: with --cumulative, each column
riod, accumulating the changes across periods, starting from 0 at shows the end balance for that period, accumulating the changes
the report start date: across periods, starting from 0 at the report start date:
$ hledger balance --quarterly income expenses -E --cumulative $ hledger balance --quarterly income expenses -E --cumulative
Ending balances (cumulative) in 2008: Ending balances (cumulative) in 2008:
@ -1878,11 +1908,12 @@ COMMANDS
-------------------++------------------------------------------------- -------------------++-------------------------------------------------
|| $-1 0 0 0 || $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending 3. A historical end balance report: with --historical/-H, each column
balance for that period, accumulating the changes across periods, shows the actual historical end balance for that period, accumulat-
starting from the actual balance at the report start date. This is ing the changes across periods, and including the balance from any
useful eg for a multi-period balance sheet, and when you are showing postings before the report start date. This is useful eg for a
only the data after a certain start date: multi-period balance sheet, and when you want to see balances only
after a certain date:
$ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
Ending balances (historical) in 2008/04/01-2008/12/31: Ending balances (historical) in 2008/04/01-2008/12/31:
@ -1899,9 +1930,6 @@ COMMANDS
Note that --cumulative or --historical/-H disable --row-total/-T, since Note that --cumulative or --historical/-H disable --row-total/-T, since
summing end balances generally does not make sense. summing end balances generally does not make sense.
Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass start/end dates will be adjusted if necessary so that they encompass
the displayed report periods. This is so that the first and last peri- the displayed report periods. This is so that the first and last peri-
@ -2323,21 +2351,25 @@ COMMANDS
check check
check check
Check for various kinds of errors in your data. experimental Check for various kinds of errors in your data.
hledger provides a number of built-in error checks to help prevent hledger provides a number of built-in error checks to help prevent
problems in your data. Some of these are run automatically; or, you problems in your data. Some of these are run automatically; or, you
can use this check command to run them on demand, with no output and a can use this check command to run them on demand, with no output and a
zero exit code if all is well. Some examples: zero exit code if all is well. Specify their names (or a prefix) as
argument(s).
Some examples:
hledger check # basic checks hledger check # basic checks
hledger check -s # basic + strict checks hledger check -s # basic + strict checks
hledger check ordereddates uniqueleafnames # basic + specified checks hledger check ordereddates payees # basic + two other checks
Here are the checks currently available: Here are the checks currently available:
Basic checks Basic checks
These are always run by this command and other commands: These checks are always run automatically, by (almost) all hledger com-
mands, including check:
o parseable - data files are well-formed and can be successfully parsed o parseable - data files are well-formed and can be successfully parsed
@ -2349,27 +2381,30 @@ COMMANDS
(This check can be disabled with -I/--ignore-assertions.) (This check can be disabled with -I/--ignore-assertions.)
Strict checks Strict checks
These are always run by this and other commands when -s/--strict is These additional checks are run when the -s/--strict (strict mode) flag
used (strict mode): is used. Or, they can be run by giving their names as arguments to
check:
o accounts - all account names used by transactions have been declared o accounts - all account names used by transactions have been declared
o commodities - all commodity symbols used have been declared o commodities - all commodity symbols used have been declared
Other checks Other checks
These checks can be run by specifying their names as arguments to the These checks can be run only by giving their names as arguments to
check command: check. They are more specialised and not desirable for everyone,
therefore optional:
o ordereddates - transactions are ordered by date (similar to the old o ordereddates - transactions are ordered by date (similar to the old
check-dates command) check-dates command)
o uniqueleafnames - all account leaf names are unique (similar to the o payees - all payees used by transactions have been declared
old check-dupes command)
Add-on checks o uniqueleafnames - all account leaf names are unique (similar to the
Some checks are not yet integrated with this command, but are available old check-dupes command).
as add-on commands in https://github.com/simonmichael/hledger/tree/mas-
ter/bin: Custom checks
A few more checks are are available as separate add-on commands, in
https://github.com/simonmichael/hledger/tree/master/bin:
o hledger-check-tagfiles - all tag values containing / (a forward o hledger-check-tagfiles - all tag values containing / (a forward
slash) exist as file paths slash) exist as file paths
@ -2377,8 +2412,8 @@ COMMANDS
o hledger-check-fancyassertions - more complex balance assertions are o hledger-check-fancyassertions - more complex balance assertions are
passing passing
You could make your own similar scripts to perform custom checks; Cook- You could make similar scripts to perform your own custom checks. See:
book -> Scripting may be helpful. Cookbook -> Scripting.
close close
close, equity close, equity
@ -3772,7 +3807,7 @@ JOURNAL FORMAT
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five top- be anything you like, but in finance there are traditionally five top-
level accounts: assets, liabilities, income, expenses, and equity. level accounts: assets, liabilities, revenue, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv- Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more able. Because of this, they must always be followed by two or more
@ -4190,6 +4225,10 @@ JOURNAL FORMAT
in reports in reports
include include entries/directives what the included include include entries/directives what the included
from another file directives affect from another file directives affect
[payee] declare a payee name following entries
until end of cur-
rent file
P declare a market price for a amounts of that P declare a market price for a amounts of that
commodity commodity in re- commodity commodity in re-
ports, when -V is ports, when -V is
@ -4214,8 +4253,6 @@ JOURNAL FORMAT
dis- how to display amounts of a commodity in reports (symbol side dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places) play and spacing, digit groups, decimal separator, decimal places)
style style
direc- which entries and (when there are multiple files) which files direc- which entries and (when there are multiple files) which files
tive are affected by a directive tive are affected by a directive
scope scope
@ -4291,6 +4328,14 @@ JOURNAL FORMAT
expenses 1 expenses 1
assets assets
Declaring payees
The payee directive can be used to declare a limited set of payees
which may appear in transaction descriptions. The "payees" check will
report an error if any transaction refers to a payee that has not been
declared. Eg:
payee Whole Foods
Declaring commodities Declaring commodities
The commodity directive has several functions: The commodity directive has several functions:
@ -5035,8 +5080,6 @@ CSV FORMAT
by patterns, alternate syntax by patterns, alternate syntax
end skip the remaining CSV records end skip the remaining CSV records
date-format how to parse dates in CSV records date-format how to parse dates in CSV records
decimal-mark the decimal mark used in CSV amounts, if decimal-mark the decimal mark used in CSV amounts, if
ambiguous ambiguous
newest-first disambiguate record order when there's newest-first disambiguate record order when there's
@ -5790,29 +5833,79 @@ CSV FORMAT
o https://plaintextaccounting.org -> data import/conversion o https://plaintextaccounting.org -> data import/conversion
Setting amounts Setting amounts
A posting amount can be set in one of these ways: Some tips on using the amount-setting rules discussed above.
o by assigning (with a fields list or field assignment) to amountN Here are the ways to set a posting's amount:
(posting N's amount) or amount (posting 1's amount)
o by assigning to amountN-in and amountN-out (or amount-in and amount- 1. If the CSV has a single amount field:
out). For each CSV record, whichever of these has a non-zero value Assign (via a fields list or a field assignment) to amountN. This sets
will be used, with appropriate sign. If both contain a non-zero the Nth posting's amount. N is usually 1 or 2 but can go up to 99.
value, this may not work.
o by assigning to balanceN (or balance) instead of the above, setting 2. If the CSV has separate Debit and Credit amount fields:
the amount indirectly via a balance assignment. If you do this the Assign to amountN-in and amountN-out. This sets posting N's amount to
default account name may be wrong, so you should set that explicitly. whichever of these has a non-zero value, guessing an appropriate sign.
There is some special handling for an amount's sign: o If hledger guesses the wrong sign:
Prepend a minus sign to flip it. Eg:
o If an amount value is parenthesised, it will be de-parenthesised and fields date, description, amount-in, amount-out
sign-flipped. amount-out -%amount-out
o If an amount value begins with a double minus sign, those cancel out o If both fields contain a non-zero value:
and are removed. The amountN-in/amountN-out rules require that each CSV record has a
non-zero value in exactly one of the two fields, so that hledger
knows which to choose. So these would all be rejected:
o If an amount value begins with a plus sign, that will be removed "", ""
"0", "0"
"1", "none"
If your CSV has amount values like this, use conditional rules
instead. For example, to make hledger to choose the value con-
taining non-zero digits:
fields date, description, in, out
if %in [1-9]
amount1 %in
if %out [1-9]
amount1 %out
3. Using the old numberless syntax:
Assign to amount (or to amount-in and amount-out). This sets posting
1's and posting 2's amounts (and converts posting 2's amount to cost).
This is supported for backwards compatibility (and occasional conve-
nience).
4. If the CSV has the balance instead of the transaction amount:
Assign to balanceN, which sets posting N's amount indirectly via a bal-
ance assignment. (Old syntax: balance, equivalent to balance1.)
o If hledger guesses the wrong default account name:
When setting the amount via balance assertion, hledger may guess
the wrong default account name. So, set the account name explic-
itly, eg:
fields date, description, balance1
account1 assets:checking
Amount signs
There is some special handling for amount signs, to simplify parsing
and sign-flipping:
o If an amount value begins with a plus sign:
that will be removed: +AMT becomes AMT
o If an amount value is parenthesised:
it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
o If an amount value has two minus signs (or two sets of parentheses,
or a minus sign and parentheses):
they cancel out and will be removed: --AMT or -(AMT) becomes AMT
o If an amount value contains just a sign (or just a set of parenthe-
ses):
that is removed, making it an empty value. "+" or "-" or "()" becomes
"".
Setting currency/commodity Setting currency/commodity
If the currency/commodity symbol is included in the CSV's amount If the currency/commodity symbol is included in the CSV's amount