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

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-11-18 18:25:11 -10:00
parent 99bbc22de1
commit 6c86648e02
3 changed files with 1956 additions and 1819 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
hledger/hledger.1
View File

@ -1122,7 +1122,7 @@ use whatever width they need.
Multi\-period multi\-currency reports can often be wider than the Multi\-period multi\-currency reports can often be wider than the
window. window.
Besides using a pager, helpful techniques for this situation include 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]\-\-transpose\f[R], \f[CR]\-\-tree\f[R], \f[CR]\-\-depth\f[R],
\f[CR]\-\-drop\f[R], switching to html output, etc. \f[CR]\-\-drop\f[R], switching to html output, etc.
.SS Box\-drawing characters .SS Box\-drawing characters
@ -1368,9 +1368,20 @@ These environment variables affect hledger:
specifies the \f[CR]less\f[R] options hledger should use. specifies the \f[CR]less\f[R] options hledger should use.
(Otherwise, \f[CR]LESS\f[R] + custom options are used.) (Otherwise, \f[CR]LESS\f[R] + custom options are used.)
.PP .PP
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified \f[B]LEDGER_FILE\f[R] The default journal file, to be used when no
with \f[CR]\-f/\-\-file\f[R]. \f[CR]\-f/\-\-file\f[R] option is provided.
Default: \f[CR]$HOME/.hledger.journal\f[R]. 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 .PP
\f[B]NO_COLOR\f[R] If this environment variable exists (with any value, \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 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 declare the field separator, instead of relying on file extension
T} T}
T{ T{
\f[B]\f[CB]skip\f[B]\f[R] \f[B]\f[CB]decimal\-mark\f[B]\f[R]
T}@T{ T}@T{
skip one or more header lines at start of file declare the decimal mark used in CSV amounts, when ambiguous
T} T}
T{ T{
\f[B]\f[CB]date\-format\f[B]\f[R] \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 overall file
T} T}
T{ T{
\f[B]\f[CB]decimal\-mark\f[B]\f[R] \f[B]\f[CB]skip\f[B]\f[R]
T}@T{ 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}
T{ T{
\f[B]\f[CB]fields\f[B] list\f[R] \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 conditionally assign values to hledger fields, using compact syntax
T} T}
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] \f[B]\f[CB]balance\-type\f[B]\f[R]
T}@T{ T}@T{
select which type of balance assertions/assignments to generate 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]. files, then run \f[CR]hledger import rules/*\f[R].
.PP .PP
See also \[dq]Working with CSV > Reading files specified by rule\[dq]. 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] 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 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 downloaded data here with a shell command or script, to make it more
suitable for conversion. 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, 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 and/or they can be inferred from the costs recorded in transactions, by
using the \f[CR]\-\-infer\-market\-prices\f[R] flag. 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 .SS \-X: Value in specified commodity
The \f[CR]\-X/\-\-exchange=COMM\f[R] option is like \f[CR]\-V\f[R], The \f[CR]\-X COMM\f[R] (or \f[CR]\-\-exchange=COMM\f[R]) option
except you tell it which currency you want to convert to, and it tries converts amounts to their market value in the specified commodity, using
to convert everything to that. 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 .SS Valuation date
Market prices can change from day to day. Market prices can change from day to day.
hledger will use the prices on a particular valuation date (or on more 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 .PP
There is a detailed tutorial at https://hledger.org/add.html. There is a detailed tutorial at https://hledger.org/add.html.
.SS add and balance assertions .SS add and balance assertions
Since hledger 1.43, whenever you enter a posting amount, \f[CR]add\f[R] Since hledger 1.43, you can add a balance assertion by writing
will re\-check all balance assertions in the journal, and if any of them \f[CR]AMOUNT = BALANCE\f[R] when asked for an amount.
fail, it will report the problem and ask for the amount again. Eg \f[CR]100 = 500\f[R].
.PP .PP
You can also add a new balance assertion, following the amount as in Also, each time you enter a new amount, hledger re\-checks all balance
journal format. assertions in the journal and rejects the new amount if it would make
.PP any of them fail.
The new transaction\[aq]s date, and the new posting\[aq]s posting date You can run \f[CR]add\f[R] with
if any (entered in a comment following the amount), will influence \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable balance
assertion checking. 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 .SS add and balance assignments
Balance assignments are not recalculated during a \f[CR]hledger add\f[R] Since hledger 1.51, you can add a balance assignment by writing
session. \f[CR]= BALANCE\f[R] (or \f[CR]==\f[R], \f[CR]=*\f[R] etc) when asked
When \f[CR]add\f[R] runs, it sees the journal with all balance for an amount.
assignments already processed and converted to assertions. The missing amount will be calculated automatically.
So if you add a new posting which is dated earlier than a balance .PP
assignment, it will break the assertion and be rejected. \f[CR]add\f[R] normally won\[aq]t let you add a new posting which is
You can make it work by using \f[CR]hledger add \-I\f[R]. 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 .SS import
Import new transactions from one or more data files to the main journal. Import new transactions from one or more data files to the main journal.
.IP .IP
@ -9977,6 +10028,10 @@ Auto postings can generate too many amountless postings.
.IP \[bu] 2 .IP \[bu] 2
\f[CR]\-\-infer\-costs or \-\-infer\-equity\f[R] can generate \f[CR]\-\-infer\-costs or \-\-infer\-equity\f[R] can generate
too\-complex redundant costs. 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 .SS print, other features
With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown
converted to cost. converted to cost.
@ -10115,9 +10170,12 @@ option.
This is a more \[dq]real world\[dq], bank\-like view than the This is a more \[dq]real world\[dq], bank\-like view than the
\f[CR]register\f[R] command (which shows individual postings, possibly \f[CR]register\f[R] command (which shows individual postings, possibly
from multiple accounts, not necessarily in historical mode). from multiple accounts, not necessarily in historical mode).
As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and As a quick rule of thumb:
reconciling real\-world asset/liability accounts \- use .IP \[bu] 2
\f[CR]register\f[R] for reviewing detailed revenues/expenses. \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 .PP
Note this command\[aq]s non\-standard, and required, first argument; it Note this command\[aq]s non\-standard, and required, first argument; it
specifies the account whose register will be shown. 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. run these checks, providing instant feedback as you edit the journal.
.PP .PP
Here are the checks currently available. Here are the checks currently available.
Generally, they are performed in the order they are shown here (and only They are generally checked in the order they are shown here, and only
the first failure is reported). the first failure will be reported.
.SS Basic checks .SS Basic checks
These important checks are performed by default, by almost all hledger These important checks are performed by default, by almost all hledger
commands: commands:
@ -12685,26 +12743,27 @@ This ensures that all files exist and are readable.
\f[B]autobalanced\f[R] \- all transactions are balanced, after \f[B]autobalanced\f[R] \- all transactions are balanced, after
automatically inferring missing amounts and conversion rates and then automatically inferring missing amounts and conversion rates and then
converting amounts to cost. 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 .IP \[bu] 2
\f[B]assertions\f[R] \- all balance assertions in the journal are \f[B]assertions\f[R] \- all balance assertions in the journal are
passing. passing.
Balance assertions are a strong defense against errors; they help catch Balance assertions are a strong defense against errors, catching many
many problems. problems.
If this check gets in your way, you can disable it with This check is on by default, but if it gets in your way, you can disable
\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R]. it temporarily with \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R], or
Or you can add that to your config file to disable it by default (and as a default by adding that flag to your config file.
then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or (Then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or
\f[CR]hledger check assertions\f[R] to enable it). \f[CR]hledger check assertions\f[R] when you want to enable it).
.SS Strict checks .SS Strict checks
These additional checks are performed by all commands when the When the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (AKA strict
\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (strict mode). mode), all commands will perform the following additional checks (and
They provide extra error\-catching power to keep your data clean and \f[CR]assertions\f[R], above).
correct. These provide extra error\-catching power to help you keep your data
Strict mode also always enables the \f[CR]assertions\f[R] check. clean and correct:
.IP \[bu] 2 .IP \[bu] 2
\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but all conversions \f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but implicit
between commodities must use explicit cost notation or equity postings. conversions between commodities are not allowed; all conversion
transactions must use cost notation or equity postings.
This prevents wrong conversions caused by typos. This prevents wrong conversions caused by typos.
.IP \[bu] 2 .IP \[bu] 2
\f[B]commodities\f[R] \- all commodity symbols used must be declared. \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 asset/liability accounts, which in turn should encourage you to
reconcile regularly with those real world balances \- another strong reconcile regularly with those real world balances \- another strong
defense against errors. defense against errors.
\f[CR]hledger close \-\-assert\f[R] can help generate assertion entries. (\f[CR]hledger close \-\-assert >>$LEDGER_FILE\f[R] is a convenient way
Over time the older assertions become somewhat redundant, and you can to add new balance assertions.
remove them if you like (they don\[aq]t affect performance much, but Later these become quite redundant, and you might choose to remove them
they add some noise to the journal). to reduce clutter.)
.IP \[bu] 2 .IP \[bu] 2
\f[B]uniqueleafnames\f[R] \- no two accounts may have the same last \f[B]uniqueleafnames\f[R] \- no two accounts may have the same last
account name part (eg the \f[CR]checking\f[R] in 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. See also Cookbook > Scripting.
Here are some examples from hledger/bin/: Here are some examples from hledger/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
forward slash) exist as file paths \f[CR]/\f[R] exist as file paths
.IP \[bu] 2 .IP \[bu] 2
\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
@ -12986,8 +13045,7 @@ When correctly configured:
.IP \[bu] 2 .IP \[bu] 2
\f[CR]env | grep LEDGER_FILE\f[R] will show your new setting \f[CR]env | grep LEDGER_FILE\f[R] will show your new setting
.IP \[bu] 2 .IP \[bu] 2
and so should \f[CR]hledger setup\f[R] and (once the file exists) and so should \f[CR]hledger setup\f[R] and \f[CR]hledger files\f[R].
\f[CR]hledger files\f[R].
.SS Set LEDGER_FILE on mac .SS Set LEDGER_FILE on mac
In a terminal window, follow the unix procedure above. In a terminal window, follow the unix procedure above.
.PP .PP

947
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

174
hledger/hledger.txt
View File

@ -782,8 +782,8 @@ Output
Balance reports (balance, balancesheet, incomestatement...) use what- Balance reports (balance, balancesheet, incomestatement...) use what-
ever width they need. Multi-period multi-currency reports can often be ever width they need. Multi-period multi-currency reports can often be
wider than the window. Besides using a pager, helpful techniques for wider than the window. Besides using a pager, helpful techniques for
this situation include --layout=bare, -V, cur:, --transpose, --tree, this situation include --layout=bare, -X COMM, cur:, --transpose,
--depth, --drop, switching to html output, etc. --tree, --depth, --drop, switching to html output, etc.
Box-drawing characters Box-drawing characters
hledger draws simple table borders by default, to minimise the risk of 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 options hledger should use. (Otherwise, LESS + custom options are
used.) used.)
LEDGER_FILE The main journal file to use when not specified with LEDGER_FILE The default journal file, to be used when no -f/--file op-
-f/--file. Default: $HOME/.hledger.journal. 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 NO_COLOR If this environment variable exists (with any value, including
empty), hledger will not use ANSI color codes in terminal output, un- empty), hledger will not use ANSI color codes in terminal output, un-
@ -3333,7 +3343,8 @@ CSV
data has data has
separator declare the field separator, instead of rely- separator declare the field separator, instead of rely-
ing on file extension 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 date-format declare how to parse CSV dates/date-times
timezone declare the time zone of ambiguous CSV timezone declare the time zone of ambiguous CSV
date-times date-times
@ -3341,8 +3352,8 @@ CSV
records, newest first, all with the same date records, newest first, all with the same date
intra-day-reversed improve txn order when: same-day txns are in intra-day-reversed improve txn order when: same-day txns are in
opposite order to the overall file opposite order to the overall file
decimal-mark declare the decimal mark used in CSV amounts, skip (at top level) skip header line(s) at start of
when ambiguous file
fields list name CSV fields for easy reference, and op- fields list name CSV fields for easy reference, and op-
tionally assign their values to hledger fields tionally assign their values to hledger fields
Field assignment assign a CSV value or interpolated text value 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) or skip a record or end (skip rest of file)
if table conditionally assign values to hledger fields, if table conditionally assign values to hledger fields,
using compact syntax 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- balance-type select which type of balance assertions/as-
signments to generate signments to generate
include inline another CSV rules file include inline another CSV rules file
@ -3393,14 +3406,15 @@ CSV
See also "Working with CSV > Reading files specified by rule". 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 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 command (or command pipeline). If hledger's CSV rules aren't enough,
downloaded data here with a shell command or script, to make it more you can pre-process the downloaded data here with a shell command or
suitable for conversion. The command will be executed by your default script, to make it more suitable for conversion. The command will be
shell, in the directory of the rules file, will receive the data file's executed by your default shell, in the directory of the rules file,
content as standard input, and should output zero or more lines of will receive the data file's content as standard input, and should out-
character-separated-values, suitable for conversion by the CSV rules. put zero or more lines of character-separated-values, suitable for con-
version by the CSV rules.
Examples: Examples:
@ -6229,15 +6243,38 @@ Value reporting
and/or they can be inferred from the costs recorded in transactions, by and/or they can be inferred from the costs recorded in transactions, by
using the --infer-market-prices flag. 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 -X: Value in specified commodity
The -X/--exchange=COMM option is like -V, except you tell it which cur- The -X COMM (or --exchange=COMM) option converts amounts to their mar-
rency you want to convert to, and it tries to convert everything to ket value in the specified commodity, using the market prices in effect
that. 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 Valuation date
Market prices can change from day to day. hledger will use the prices 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. There is a detailed tutorial at https://hledger.org/add.html.
add and balance assertions add and balance assertions
Since hledger 1.43, whenever you enter a posting amount, add will Since hledger 1.43, you can add a balance assertion by writing AMOUNT =
re-check all balance assertions in the journal, and if any of them BALANCE when asked for an amount. Eg 100 = 500.
fail, it will report the problem and ask for the amount again.
You can also add a new balance assertion, following the amount as in Also, each time you enter a new amount, hledger re-checks all balance
journal format. 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-
The new transaction's date, and the new posting's posting date if any able balance assertion checking.
(entered in a comment following the amount), will influence assertion
checking.
You can use -I/--ignore-assertions to disable assertion checking tem-
porarily.
add and balance assignments add and balance assignments
Balance assignments are not recalculated during a hledger add session. Since hledger 1.51, you can add a balance assignment by writing = BAL-
When add runs, it sees the journal with all balance assignments already ANCE (or ==, =* etc) when asked for an amount. The missing amount will
processed and converted to assertions. So if you add a new posting be calculated automatically.
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. 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
Import new transactions from one or more data files to the main jour- 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 o --infer-costs or --infer-equity can generate too-complex redundant
costs. 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 print, other features
With -B/--cost, amounts with costs are shown converted to cost. 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 This is a more "real world", bank-like view than the register command
(which shows individual postings, possibly from multiple accounts, not (which shows individual postings, possibly from multiple accounts, not
necessarily in historical mode). As a quick rule of thumb: - use areg- necessarily in historical mode). As a quick rule of thumb:
ister for reviewing and reconciling real-world asset/liability accounts
- use register for reviewing detailed revenues/expenses. 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 Note this command's non-standard, and required, first argument; it
specifies the account whose register will be shown. You can write the 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 If you are an Emacs user, you can also configure flycheck-hledger to
run these checks, providing instant feedback as you edit the journal. run these checks, providing instant feedback as you edit the journal.
Here are the checks currently available. Generally, they are performed Here are the checks currently available. They are generally checked in
in the order they are shown here (and only the first failure is re- the order they are shown here, and only the first failure will be re-
ported). ported.
Basic checks Basic checks
These important checks are performed by default, by almost all hledger 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- o autobalanced - all transactions are balanced, after automatically in-
ferring missing amounts and conversion rates and then converting ferring missing amounts and conversion rates and then converting
amounts to cost. This ensures that each transaction's entry is well amounts to cost. This ensures that each transaction's journal entry
formed. is well formed.
o assertions - all balance assertions in the journal are passing. Bal- o assertions - all balance assertions in the journal are passing. Bal-
ance assertions are a strong defense against errors; they help catch ance assertions are a strong defense against errors, catching many
many problems. If this check gets in your way, you can disable it problems. This check is on by default, but if it gets in your way,
with -I/--ignore-assertions. Or you can add that to your config file you can disable it temporarily with -I/--ignore-assertions, or as a
to disable it by default (and then use -s/--strict or hledger check default by adding that flag to your config file. (Then use
assertions to enable it). -s/--strict or hledger check assertions when you want to enable it).
Strict checks Strict checks
These additional checks are performed by all commands when the When the -s/--strict flag is used (AKA strict mode), all commands will
-s/--strict flag is used (strict mode). They provide extra er- perform the following additional checks (and assertions, above). These
ror-catching power to keep your data clean and correct. Strict mode provide extra error-catching power to help you keep your data clean and
also always enables the assertions check. correct:
o balanced - like autobalanced, but all conversions between commodities o balanced - like autobalanced, but implicit conversions between com-
must use explicit cost notation or equity postings. This prevents modities are not allowed; all conversion transactions must use cost
wrong conversions caused by typos. notation or equity postings. This prevents wrong conversions caused
by typos.
o commodities - all commodity symbols used must be declared. This o commodities - all commodity symbols used must be declared. This
guards against mistyping or omitting commodity symbols. guards against mistyping or omitting commodity symbols.
@ -10157,10 +10200,9 @@ Maintenance commands
courage adding balance assertions for your active asset/liability ac- courage adding balance assertions for your active asset/liability ac-
counts, which in turn should encourage you to reconcile regularly counts, which in turn should encourage you to reconcile regularly
with those real world balances - another strong defense against er- with those real world balances - another strong defense against er-
rors. hledger close --assert can help generate assertion entries. rors. (hledger close --assert >>$LEDGER_FILE is a convenient way to
Over time the older assertions become somewhat redundant, and you can add new balance assertions. Later these become quite redundant, and
remove them if you like (they don't affect performance much, but they you might choose to remove them to reduce clutter.)
add some noise to the journal).
o uniqueleafnames - no two accounts may have the same last account name o uniqueleafnames - no two accounts may have the same last account name
part (eg the checking in assets:bank:checking). This ensures each 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 You can build your own custom checks with add-on command scripts. See
also Cookbook > Scripting. Here are some examples from hledger/bin/: also Cookbook > Scripting. Here are some examples from hledger/bin/:
o hledger-check-tagfiles - all tag values containing / (a forward o hledger-check-tagfiles - all tag values containing / exist as file
slash) exist as file paths paths
o hledger-check-fancyassertions - more complex balance assertions are o hledger-check-fancyassertions - more complex balance assertions are
passing passing
@ -10382,7 +10424,7 @@ PART 5: COMMON TASKS
o env | grep LEDGER_FILE will show your new setting 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 Set LEDGER_FILE on mac
In a terminal window, follow the unix procedure above. In a terminal window, follow the unix procedure above.