;doc: update embedded manuals
This commit is contained in:
parent
99bbc22de1
commit
6c86648e02
@ -1122,7 +1122,7 @@ use whatever width they need.
|
||||
Multi\-period multi\-currency reports can often be wider than the
|
||||
window.
|
||||
Besides using a pager, helpful techniques for this situation include
|
||||
\f[CR]\-\-layout=bare\f[R], \f[CR]\-V\f[R], \f[CR]cur:\f[R],
|
||||
\f[CR]\-\-layout=bare\f[R], \f[CR]\-X COMM\f[R], \f[CR]cur:\f[R],
|
||||
\f[CR]\-\-transpose\f[R], \f[CR]\-\-tree\f[R], \f[CR]\-\-depth\f[R],
|
||||
\f[CR]\-\-drop\f[R], switching to html output, etc.
|
||||
.SS Box\-drawing characters
|
||||
@ -1368,9 +1368,20 @@ These environment variables affect hledger:
|
||||
specifies the \f[CR]less\f[R] options hledger should use.
|
||||
(Otherwise, \f[CR]LESS\f[R] + custom options are used.)
|
||||
.PP
|
||||
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
|
||||
with \f[CR]\-f/\-\-file\f[R].
|
||||
Default: \f[CR]$HOME/.hledger.journal\f[R].
|
||||
\f[B]LEDGER_FILE\f[R] The default journal file, to be used when no
|
||||
\f[CR]\-f/\-\-file\f[R] option is provided.
|
||||
For example, it could be \f[CR]\[ti]/finance/main.journal\f[R].
|
||||
This can also be a glob pattern, eg \f[CR]./2???.journal\f[R].
|
||||
(If the glob matches multiple files, only the alphanumerically first one
|
||||
is used.)
|
||||
If LEDGER_FILE points to a non\-existent file, an error will be raised.
|
||||
If the value is the empty string, it is ignored.
|
||||
.PP
|
||||
If LEDGER_FILE is not set and \f[CR]\-f\f[R] is not provided, the
|
||||
default journal file is \f[CR]$HOME/.hledger.journal\f[R] (or if a home
|
||||
directory can\[aq]t be detected, \f[CR]./.hledger.journal\f[R]).
|
||||
.PP
|
||||
See also Common tasks > Setting LEDGER_FILE.
|
||||
.PP
|
||||
\f[B]NO_COLOR\f[R] If this environment variable exists (with any value,
|
||||
including empty), hledger will not use ANSI color codes in terminal
|
||||
@ -4311,9 +4322,9 @@ T}@T{
|
||||
declare the field separator, instead of relying on file extension
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]skip\f[B]\f[R]
|
||||
\f[B]\f[CB]decimal\-mark\f[B]\f[R]
|
||||
T}@T{
|
||||
skip one or more header lines at start of file
|
||||
declare the decimal mark used in CSV amounts, when ambiguous
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]date\-format\f[B]\f[R]
|
||||
@ -4338,9 +4349,9 @@ improve txn order when: same\-day txns are in opposite order to the
|
||||
overall file
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]decimal\-mark\f[B]\f[R]
|
||||
\f[B]\f[CB]skip\f[B]\f[R]
|
||||
T}@T{
|
||||
declare the decimal mark used in CSV amounts, when ambiguous
|
||||
(at top level) skip header line(s) at start of file
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]fields\f[B] list\f[R]
|
||||
@ -4365,6 +4376,16 @@ T}@T{
|
||||
conditionally assign values to hledger fields, using compact syntax
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]skip\f[B]\f[R]
|
||||
T}@T{
|
||||
(inside an \f[CR]if\f[R] rule) skip current record(s)
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]end\f[B]\f[R]
|
||||
T}@T{
|
||||
(inside an \f[CR]if\f[R] rule) skip all remaining records
|
||||
T}
|
||||
T{
|
||||
\f[B]\f[CB]balance\-type\f[B]\f[R]
|
||||
T}@T{
|
||||
select which type of balance assertions/assignments to generate
|
||||
@ -4421,9 +4442,9 @@ All this enables a convenient workflow where can you just download CSV
|
||||
files, then run \f[CR]hledger import rules/*\f[R].
|
||||
.PP
|
||||
See also \[dq]Working with CSV > Reading files specified by rule\[dq].
|
||||
.SS Data cleaning / generating commands
|
||||
.SS Data cleaning / data generating commands
|
||||
After \f[CR]source\f[R]\[aq]s file pattern, you can write \f[CR]|\f[R]
|
||||
(pipe) and a data cleaning command.
|
||||
(pipe) and a data cleaning command (or command pipeline).
|
||||
If hledger\[aq]s CSV rules aren\[aq]t enough, you can pre\-process the
|
||||
downloaded data here with a shell command or script, to make it more
|
||||
suitable for conversion.
|
||||
@ -8019,15 +8040,43 @@ aliases for this, which are often sufficient.
|
||||
The market prices are declared with a special \f[CR]P\f[R] directive,
|
||||
and/or they can be inferred from the costs recorded in transactions, by
|
||||
using the \f[CR]\-\-infer\-market\-prices\f[R] flag.
|
||||
.SS \-V: Value
|
||||
The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in
|
||||
their default \f[I]valuation commodity\f[R], using the market prices in
|
||||
effect on the \f[I]valuation date(s)\f[R], if any.
|
||||
More on these in a minute.
|
||||
.SS \-X: Value in specified commodity
|
||||
The \f[CR]\-X/\-\-exchange=COMM\f[R] option is like \f[CR]\-V\f[R],
|
||||
except you tell it which currency you want to convert to, and it tries
|
||||
to convert everything to that.
|
||||
The \f[CR]\-X COMM\f[R] (or \f[CR]\-\-exchange=COMM\f[R]) option
|
||||
converts amounts to their market value in the specified commodity, using
|
||||
the market prices in effect on the \f[I]valuation date(s)\f[R], if any.
|
||||
(More on these in a minute.)
|
||||
.PP
|
||||
Use this when you want to (eg) show everything in your base currency as
|
||||
far as possible.
|
||||
(Commodities for which no conversion rate can be found, will not be
|
||||
converted.)
|
||||
.PP
|
||||
COMM should be the full commodity symbol or name.
|
||||
Remember to quote special shell characters, if needed.
|
||||
Some examples:
|
||||
.IP \[bu] 2
|
||||
\f[CR]\-X€\f[R]
|
||||
.IP \[bu] 2
|
||||
\f[CR]\-X$\f[R] (nothing after $, no quoting needed)
|
||||
.IP \[bu] 2
|
||||
\f[CR]\-X CNY\f[R] (the space after \-X is optional)
|
||||
.IP \[bu] 2
|
||||
\f[CR]\-X \[aq]red apples\[aq]\f[R]
|
||||
.IP \[bu] 2
|
||||
\f[CR]\-X \[aq]r&r\[aq]\f[R]
|
||||
.SS \-V: Value in default commodity(s)
|
||||
The \f[CR]\-V/\-\-market\f[R] flag is a variant of \f[CR]\-X\f[R] where
|
||||
you don\[aq]t have to specify COMM.
|
||||
Instead it tries to guess a \f[I]default valuation commodity\f[R] for
|
||||
each original commodity, based on the market prices in effect on the
|
||||
valuation date(s).
|
||||
.PP
|
||||
\f[CR]\-V\f[R] can often be a convenient shortcut for
|
||||
\f[CR]\-X MYCURRENCY\f[R], but not always; depending on your data it
|
||||
could guess multiple valuation commodities.
|
||||
Usually you want to convert to a single commodity, so it\[aq]s better to
|
||||
use \f[CR]\-X\f[R], unless you\[aq]re sure \f[CR]\-V\f[R] is doing what
|
||||
you want.
|
||||
.SS Valuation date
|
||||
Market prices can change from day to day.
|
||||
hledger will use the prices on a particular valuation date (or on more
|
||||
@ -9216,27 +9265,29 @@ Provide answers for the first four prompts:
|
||||
.PP
|
||||
There is a detailed tutorial at https://hledger.org/add.html.
|
||||
.SS add and balance assertions
|
||||
Since hledger 1.43, whenever you enter a posting amount, \f[CR]add\f[R]
|
||||
will re\-check all balance assertions in the journal, and if any of them
|
||||
fail, it will report the problem and ask for the amount again.
|
||||
Since hledger 1.43, you can add a balance assertion by writing
|
||||
\f[CR]AMOUNT = BALANCE\f[R] when asked for an amount.
|
||||
Eg \f[CR]100 = 500\f[R].
|
||||
.PP
|
||||
You can also add a new balance assertion, following the amount as in
|
||||
journal format.
|
||||
.PP
|
||||
The new transaction\[aq]s date, and the new posting\[aq]s posting date
|
||||
if any (entered in a comment following the amount), will influence
|
||||
Also, each time you enter a new amount, hledger re\-checks all balance
|
||||
assertions in the journal and rejects the new amount if it would make
|
||||
any of them fail.
|
||||
You can run \f[CR]add\f[R] with
|
||||
\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable balance
|
||||
assertion checking.
|
||||
.PP
|
||||
You can use \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable
|
||||
assertion checking temporarily.
|
||||
.SS add and balance assignments
|
||||
Balance assignments are not recalculated during a \f[CR]hledger add\f[R]
|
||||
session.
|
||||
When \f[CR]add\f[R] runs, it sees the journal with all balance
|
||||
assignments already processed and converted to assertions.
|
||||
So if you add a new posting which is dated earlier than a balance
|
||||
assignment, it will break the assertion and be rejected.
|
||||
You can make it work by using \f[CR]hledger add \-I\f[R].
|
||||
Since hledger 1.51, you can add a balance assignment by writing
|
||||
\f[CR]= BALANCE\f[R] (or \f[CR]==\f[R], \f[CR]=*\f[R] etc) when asked
|
||||
for an amount.
|
||||
The missing amount will be calculated automatically.
|
||||
.PP
|
||||
\f[CR]add\f[R] normally won\[aq]t let you add a new posting which is
|
||||
dated earlier than an existing balance assignment.
|
||||
(Because when \f[CR]add\f[R] runs, existing balance assignments have
|
||||
already been calculated and converted to amounts and balance
|
||||
assertions.)
|
||||
You can allow it by disabling balance assertion checking with
|
||||
\f[CR]\-I\f[R].
|
||||
.SS import
|
||||
Import new transactions from one or more data files to the main journal.
|
||||
.IP
|
||||
@ -9977,6 +10028,10 @@ Auto postings can generate too many amountless postings.
|
||||
.IP \[bu] 2
|
||||
\f[CR]\-\-infer\-costs or \-\-infer\-equity\f[R] can generate
|
||||
too\-complex redundant costs.
|
||||
.IP \[bu] 2
|
||||
Because print always shows transactions in date order, balance
|
||||
assertions involving non\-date\-ordered transactions (and same\-day
|
||||
postings) could be disrupted.
|
||||
.SS print, other features
|
||||
With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown
|
||||
converted to cost.
|
||||
@ -10115,9 +10170,12 @@ option.
|
||||
This is a more \[dq]real world\[dq], bank\-like view than the
|
||||
\f[CR]register\f[R] command (which shows individual postings, possibly
|
||||
from multiple accounts, not necessarily in historical mode).
|
||||
As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and
|
||||
reconciling real\-world asset/liability accounts \- use
|
||||
\f[CR]register\f[R] for reviewing detailed revenues/expenses.
|
||||
As a quick rule of thumb:
|
||||
.IP \[bu] 2
|
||||
\f[CR]aregister\f[R] is best when reconciling real\-world
|
||||
asset/liability accounts
|
||||
.IP \[bu] 2
|
||||
\f[CR]register\f[R] is best when reviewing individual revenues/expenses.
|
||||
.PP
|
||||
Note this command\[aq]s non\-standard, and required, first argument; it
|
||||
specifies the account whose register will be shown.
|
||||
@ -12672,8 +12730,8 @@ If you are an Emacs user, you can also configure flycheck\-hledger to
|
||||
run these checks, providing instant feedback as you edit the journal.
|
||||
.PP
|
||||
Here are the checks currently available.
|
||||
Generally, they are performed in the order they are shown here (and only
|
||||
the first failure is reported).
|
||||
They are generally checked in the order they are shown here, and only
|
||||
the first failure will be reported.
|
||||
.SS Basic checks
|
||||
These important checks are performed by default, by almost all hledger
|
||||
commands:
|
||||
@ -12685,26 +12743,27 @@ This ensures that all files exist and are readable.
|
||||
\f[B]autobalanced\f[R] \- all transactions are balanced, after
|
||||
automatically inferring missing amounts and conversion rates and then
|
||||
converting amounts to cost.
|
||||
This ensures that each transaction\[aq]s entry is well formed.
|
||||
This ensures that each transaction\[aq]s journal entry is well formed.
|
||||
.IP \[bu] 2
|
||||
\f[B]assertions\f[R] \- all balance assertions in the journal are
|
||||
passing.
|
||||
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
|
||||
\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R].
|
||||
Or you can add that to your config file to disable it by default (and
|
||||
then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or
|
||||
\f[CR]hledger check assertions\f[R] to enable it).
|
||||
Balance assertions are a strong defense against errors, catching many
|
||||
problems.
|
||||
This check is on by default, but if it gets in your way, you can disable
|
||||
it temporarily with \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R], or
|
||||
as a default by adding that flag to your config file.
|
||||
(Then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or
|
||||
\f[CR]hledger check assertions\f[R] when you want to enable it).
|
||||
.SS Strict checks
|
||||
These additional checks are performed by all commands when the
|
||||
\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (strict mode).
|
||||
They provide extra error\-catching power to keep your data clean and
|
||||
correct.
|
||||
Strict mode also always enables the \f[CR]assertions\f[R] check.
|
||||
When the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (AKA strict
|
||||
mode), all commands will perform the following additional checks (and
|
||||
\f[CR]assertions\f[R], above).
|
||||
These provide extra error\-catching power to help you keep your data
|
||||
clean and correct:
|
||||
.IP \[bu] 2
|
||||
\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but all conversions
|
||||
between commodities must use explicit cost notation or equity postings.
|
||||
\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but implicit
|
||||
conversions between commodities are not allowed; all conversion
|
||||
transactions must use cost notation or equity postings.
|
||||
This prevents wrong conversions caused by typos.
|
||||
.IP \[bu] 2
|
||||
\f[B]commodities\f[R] \- all commodity symbols used must be declared.
|
||||
@ -12737,10 +12796,10 @@ 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.
|
||||
\f[CR]hledger close \-\-assert\f[R] can help generate assertion entries.
|
||||
Over time the older assertions become somewhat redundant, and you can
|
||||
remove them if you like (they don\[aq]t affect performance much, but
|
||||
they add some noise to the journal).
|
||||
(\f[CR]hledger close \-\-assert >>$LEDGER_FILE\f[R] is a convenient way
|
||||
to add new balance assertions.
|
||||
Later these become quite redundant, and you might choose to remove them
|
||||
to reduce clutter.)
|
||||
.IP \[bu] 2
|
||||
\f[B]uniqueleafnames\f[R] \- no two accounts may have the same last
|
||||
account name part (eg the \f[CR]checking\f[R] in
|
||||
@ -12752,8 +12811,8 @@ You can build your own custom checks with add\-on command scripts.
|
||||
See also Cookbook > Scripting.
|
||||
Here are some examples from hledger/bin/:
|
||||
.IP \[bu] 2
|
||||
\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing / (a
|
||||
forward slash) exist as file paths
|
||||
\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing
|
||||
\f[CR]/\f[R] exist as file paths
|
||||
.IP \[bu] 2
|
||||
\f[B]hledger\-check\-fancyassertions\f[R] \- more complex balance
|
||||
assertions are passing
|
||||
@ -12986,8 +13045,7 @@ When correctly configured:
|
||||
.IP \[bu] 2
|
||||
\f[CR]env | grep LEDGER_FILE\f[R] will show your new setting
|
||||
.IP \[bu] 2
|
||||
and so should \f[CR]hledger setup\f[R] and (once the file exists)
|
||||
\f[CR]hledger files\f[R].
|
||||
and so should \f[CR]hledger setup\f[R] and \f[CR]hledger files\f[R].
|
||||
.SS Set LEDGER_FILE on mac
|
||||
In a terminal window, follow the unix procedure above.
|
||||
.PP
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -782,8 +782,8 @@ Output
|
||||
Balance reports (balance, balancesheet, incomestatement...) use what-
|
||||
ever width they need. Multi-period multi-currency reports can often be
|
||||
wider than the window. Besides using a pager, helpful techniques for
|
||||
this situation include --layout=bare, -V, cur:, --transpose, --tree,
|
||||
--depth, --drop, switching to html output, etc.
|
||||
this situation include --layout=bare, -X COMM, cur:, --transpose,
|
||||
--tree, --depth, --drop, switching to html output, etc.
|
||||
|
||||
Box-drawing characters
|
||||
hledger draws simple table borders by default, to minimise the risk of
|
||||
@ -1009,8 +1009,18 @@ Environment
|
||||
options hledger should use. (Otherwise, LESS + custom options are
|
||||
used.)
|
||||
|
||||
LEDGER_FILE The main journal file to use when not specified with
|
||||
-f/--file. Default: $HOME/.hledger.journal.
|
||||
LEDGER_FILE The default journal file, to be used when no -f/--file op-
|
||||
tion is provided. For example, it could be ~/finance/main.journal.
|
||||
This can also be a glob pattern, eg ./2???.journal. (If the glob
|
||||
matches multiple files, only the alphanumerically first one is used.)
|
||||
If LEDGER_FILE points to a non-existent file, an error will be raised.
|
||||
If the value is the empty string, it is ignored.
|
||||
|
||||
If LEDGER_FILE is not set and -f is not provided, the default journal
|
||||
file is $HOME/.hledger.journal (or if a home directory can't be de-
|
||||
tected, ./.hledger.journal).
|
||||
|
||||
See also Common tasks > Setting LEDGER_FILE.
|
||||
|
||||
NO_COLOR If this environment variable exists (with any value, including
|
||||
empty), hledger will not use ANSI color codes in terminal output, un-
|
||||
@ -3333,7 +3343,8 @@ CSV
|
||||
data has
|
||||
separator declare the field separator, instead of rely-
|
||||
ing on file extension
|
||||
skip skip one or more header lines at start of file
|
||||
decimal-mark declare the decimal mark used in CSV amounts,
|
||||
when ambiguous
|
||||
date-format declare how to parse CSV dates/date-times
|
||||
timezone declare the time zone of ambiguous CSV
|
||||
date-times
|
||||
@ -3341,8 +3352,8 @@ CSV
|
||||
records, newest first, all with the same date
|
||||
intra-day-reversed improve txn order when: same-day txns are in
|
||||
opposite order to the overall file
|
||||
decimal-mark declare the decimal mark used in CSV amounts,
|
||||
when ambiguous
|
||||
skip (at top level) skip header line(s) at start of
|
||||
file
|
||||
fields list name CSV fields for easy reference, and op-
|
||||
tionally assign their values to hledger fields
|
||||
Field assignment assign a CSV value or interpolated text value
|
||||
@ -3351,6 +3362,8 @@ CSV
|
||||
or skip a record or end (skip rest of file)
|
||||
if table conditionally assign values to hledger fields,
|
||||
using compact syntax
|
||||
skip (inside an if rule) skip current record(s)
|
||||
end (inside an if rule) skip all remaining records
|
||||
balance-type select which type of balance assertions/as-
|
||||
signments to generate
|
||||
include inline another CSV rules file
|
||||
@ -3393,14 +3406,15 @@ CSV
|
||||
|
||||
See also "Working with CSV > Reading files specified by rule".
|
||||
|
||||
Data cleaning / generating commands
|
||||
Data cleaning / data generating commands
|
||||
After source's file pattern, you can write | (pipe) and a data cleaning
|
||||
command. If hledger's CSV rules aren't enough, you can pre-process the
|
||||
downloaded data here with a shell command or script, to make it more
|
||||
suitable for conversion. The command will be executed by your default
|
||||
shell, in the directory of the rules file, will receive the data file's
|
||||
content as standard input, and should output zero or more lines of
|
||||
character-separated-values, suitable for conversion by the CSV rules.
|
||||
command (or command pipeline). If hledger's CSV rules aren't enough,
|
||||
you can pre-process the downloaded data here with a shell command or
|
||||
script, to make it more suitable for conversion. The command will be
|
||||
executed by your default shell, in the directory of the rules file,
|
||||
will receive the data file's content as standard input, and should out-
|
||||
put zero or more lines of character-separated-values, suitable for con-
|
||||
version by the CSV rules.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -6229,15 +6243,38 @@ Value reporting
|
||||
and/or they can be inferred from the costs recorded in transactions, by
|
||||
using the --infer-market-prices flag.
|
||||
|
||||
-V: Value
|
||||
The -V/--market flag converts amounts to market value in their default
|
||||
valuation commodity, using the market prices in effect on the valuation
|
||||
date(s), if any. More on these in a minute.
|
||||
|
||||
-X: Value in specified commodity
|
||||
The -X/--exchange=COMM option is like -V, except you tell it which cur-
|
||||
rency you want to convert to, and it tries to convert everything to
|
||||
that.
|
||||
The -X COMM (or --exchange=COMM) option converts amounts to their mar-
|
||||
ket value in the specified commodity, using the market prices in effect
|
||||
on the valuation date(s), if any. (More on these in a minute.)
|
||||
|
||||
Use this when you want to (eg) show everything in your base currency as
|
||||
far as possible. (Commodities for which no conversion rate can be
|
||||
found, will not be converted.)
|
||||
|
||||
COMM should be the full commodity symbol or name. Remember to quote
|
||||
special shell characters, if needed. Some examples:
|
||||
|
||||
o -X
|
||||
|
||||
o -X$ (nothing after $, no quoting needed)
|
||||
|
||||
o -X CNY (the space after -X is optional)
|
||||
|
||||
o -X 'red apples'
|
||||
|
||||
o -X 'r&r'
|
||||
|
||||
-V: Value in default commodity(s)
|
||||
The -V/--market flag is a variant of -X where you don't have to specify
|
||||
COMM. Instead it tries to guess a default valuation commodity for each
|
||||
original commodity, based on the market prices in effect on the valua-
|
||||
tion date(s).
|
||||
|
||||
-V can often be a convenient shortcut for -X MYCURRENCY, but not al-
|
||||
ways; depending on your data it could guess multiple valuation commodi-
|
||||
ties. Usually you want to convert to a single commodity, so it's bet-
|
||||
ter to use -X, unless you're sure -V is doing what you want.
|
||||
|
||||
Valuation date
|
||||
Market prices can change from day to day. hledger will use the prices
|
||||
@ -7120,26 +7157,24 @@ Data entry commands
|
||||
There is a detailed tutorial at https://hledger.org/add.html.
|
||||
|
||||
add and balance assertions
|
||||
Since hledger 1.43, whenever you enter a posting amount, add will
|
||||
re-check all balance assertions in the journal, and if any of them
|
||||
fail, it will report the problem and ask for the amount again.
|
||||
Since hledger 1.43, you can add a balance assertion by writing AMOUNT =
|
||||
BALANCE when asked for an amount. Eg 100 = 500.
|
||||
|
||||
You can also add a new balance assertion, following the amount as in
|
||||
journal format.
|
||||
|
||||
The new transaction's date, and the new posting's posting date if any
|
||||
(entered in a comment following the amount), will influence assertion
|
||||
checking.
|
||||
|
||||
You can use -I/--ignore-assertions to disable assertion checking tem-
|
||||
porarily.
|
||||
Also, each time you enter a new amount, hledger re-checks all balance
|
||||
assertions in the journal and rejects the new amount if it would make
|
||||
any of them fail. You can run add with -I/--ignore-assertions to dis-
|
||||
able balance assertion checking.
|
||||
|
||||
add and balance assignments
|
||||
Balance assignments are not recalculated during a hledger add session.
|
||||
When add runs, it sees the journal with all balance assignments already
|
||||
processed and converted to assertions. So if you add a new posting
|
||||
which is dated earlier than a balance assignment, it will break the as-
|
||||
sertion and be rejected. You can make it work by using hledger add -I.
|
||||
Since hledger 1.51, you can add a balance assignment by writing = BAL-
|
||||
ANCE (or ==, =* etc) when asked for an amount. The missing amount will
|
||||
be calculated automatically.
|
||||
|
||||
add normally won't let you add a new posting which is dated earlier
|
||||
than an existing balance assignment. (Because when add runs, existing
|
||||
balance assignments have already been calculated and converted to
|
||||
amounts and balance assertions.) You can allow it by disabling balance
|
||||
assertion checking with -I.
|
||||
|
||||
import
|
||||
Import new transactions from one or more data files to the main jour-
|
||||
@ -7788,6 +7823,10 @@ Standard report commands
|
||||
o --infer-costs or --infer-equity can generate too-complex redundant
|
||||
costs.
|
||||
|
||||
o Because print always shows transactions in date order, balance asser-
|
||||
tions involving non-date-ordered transactions (and same-day postings)
|
||||
could be disrupted.
|
||||
|
||||
print, other features
|
||||
With -B/--cost, amounts with costs are shown converted to cost.
|
||||
|
||||
@ -7912,9 +7951,12 @@ Standard report commands
|
||||
|
||||
This is a more "real world", bank-like view than the register command
|
||||
(which shows individual postings, possibly from multiple accounts, not
|
||||
necessarily in historical mode). As a quick rule of thumb: - use areg-
|
||||
ister for reviewing and reconciling real-world asset/liability accounts
|
||||
- use register for reviewing detailed revenues/expenses.
|
||||
necessarily in historical mode). As a quick rule of thumb:
|
||||
|
||||
o aregister is best when reconciling real-world asset/liability ac-
|
||||
counts
|
||||
|
||||
o register is best when reviewing individual revenues/expenses.
|
||||
|
||||
Note this command's non-standard, and required, first argument; it
|
||||
specifies the account whose register will be shown. You can write the
|
||||
@ -10095,9 +10137,9 @@ Maintenance commands
|
||||
If you are an Emacs user, you can also configure flycheck-hledger to
|
||||
run these checks, providing instant feedback as you edit the journal.
|
||||
|
||||
Here are the checks currently available. Generally, they are performed
|
||||
in the order they are shown here (and only the first failure is re-
|
||||
ported).
|
||||
Here are the checks currently available. They are generally checked in
|
||||
the order they are shown here, and only the first failure will be re-
|
||||
ported.
|
||||
|
||||
Basic checks
|
||||
These important checks are performed by default, by almost all hledger
|
||||
@ -10109,25 +10151,26 @@ Maintenance commands
|
||||
|
||||
o autobalanced - all transactions are balanced, after automatically in-
|
||||
ferring missing amounts and conversion rates and then converting
|
||||
amounts to cost. This ensures that each transaction's entry is well
|
||||
formed.
|
||||
amounts to cost. This ensures that each transaction's journal entry
|
||||
is well formed.
|
||||
|
||||
o assertions - all balance assertions in the journal are passing. Bal-
|
||||
ance 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).
|
||||
ance assertions are a strong defense against errors, catching many
|
||||
problems. This check is on by default, but if it gets in your way,
|
||||
you can disable it temporarily with -I/--ignore-assertions, or as a
|
||||
default by adding that flag to your config file. (Then use
|
||||
-s/--strict or hledger check assertions when you want to enable it).
|
||||
|
||||
Strict checks
|
||||
These additional checks are performed by all commands when the
|
||||
-s/--strict flag is used (strict mode). They provide extra er-
|
||||
ror-catching power to keep your data clean and correct. Strict mode
|
||||
also always enables the assertions check.
|
||||
When the -s/--strict flag is used (AKA strict mode), all commands will
|
||||
perform the following additional checks (and assertions, above). These
|
||||
provide extra error-catching power to help you keep your data clean and
|
||||
correct:
|
||||
|
||||
o balanced - like autobalanced, but all conversions between commodities
|
||||
must use explicit cost notation or equity postings. This prevents
|
||||
wrong conversions caused by typos.
|
||||
o balanced - like autobalanced, but implicit conversions between com-
|
||||
modities are not allowed; all conversion transactions must use cost
|
||||
notation or equity postings. This prevents wrong conversions caused
|
||||
by typos.
|
||||
|
||||
o commodities - all commodity symbols used must be declared. This
|
||||
guards against mistyping or omitting commodity symbols.
|
||||
@ -10157,10 +10200,9 @@ Maintenance commands
|
||||
courage adding balance assertions for your active asset/liability ac-
|
||||
counts, which in turn should encourage you to reconcile regularly
|
||||
with those real world balances - another strong defense against er-
|
||||
rors. 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).
|
||||
rors. (hledger close --assert >>$LEDGER_FILE is a convenient way to
|
||||
add new balance assertions. Later these become quite redundant, and
|
||||
you might choose to remove them to reduce clutter.)
|
||||
|
||||
o uniqueleafnames - no two accounts may have the same last account name
|
||||
part (eg the checking in assets:bank:checking). This ensures each
|
||||
@ -10171,8 +10213,8 @@ Maintenance commands
|
||||
You can build your own custom checks with add-on command scripts. See
|
||||
also Cookbook > Scripting. Here are some examples from hledger/bin/:
|
||||
|
||||
o hledger-check-tagfiles - all tag values containing / (a forward
|
||||
slash) exist as file paths
|
||||
o hledger-check-tagfiles - all tag values containing / exist as file
|
||||
paths
|
||||
|
||||
o hledger-check-fancyassertions - more complex balance assertions are
|
||||
passing
|
||||
@ -10382,7 +10424,7 @@ PART 5: COMMON TASKS
|
||||
|
||||
o env | grep LEDGER_FILE will show your new setting
|
||||
|
||||
o and so should hledger setup and (once the file exists) hledger files.
|
||||
o and so should hledger setup and hledger files.
|
||||
|
||||
Set LEDGER_FILE on mac
|
||||
In a terminal window, follow the unix procedure above.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user