simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-26 03:42:25 +03:00
Code Issues Projects Releases Wiki Activity

doc: regen manuals

Browse Source
This commit is contained in:
Simon Michael 2019-01-26 15:56:43 -08:00
parent 550aa408eb
commit 2df8a6c4de
9 changed files with 618 additions and 544 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
hledger-lib/hledger_journal.5
View File

@ -602,8 +602,21 @@ One workaround is to isolate each commodity into its own subaccount:
.fi
.SS Assertions and prices
.PP
Balance assertion (or assignment) amounts should not have a price, as
the meaning of that would be unclear.
Balance assertions ignore transaction prices, and should normally be
written without one:
.IP
.nf
\f[C]
2019/1/1
\ \ (a)\ \ \ \ \ $1\ \@\ €1\ =\ $1
\f[]
.fi
.PP
We do allow prices to be written there, however, and print shows them,
even though they don\[aq]t affect whether the assertion passes or fails.
This is for backward compatibility (hledger\[aq]s close command used to
generate balance assertions with prices), and because balance
\f[I]assignments\f[] do use them (see below).
.SS Assertions and subaccounts
.PP
Balance assertions do not count the balance from subaccounts; they check
@ -682,6 +695,25 @@ assignment).
Note that using balance assignments makes your journal a little less
explicit; to know the exact amount posted, you have to run hledger or do
the calculations yourself, instead of just reading it.
.SS Balance assignments and prices
.PP
A transaction price in a balance assignment will cause the calculated
amount to have that price attached:
.IP
.nf
\f[C]
2019/1/1
\ \ (a)\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $1\ \@\ €2
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ print\ \-\-explicit
2019/01/01
\ \ \ \ (a)\ \ \ \ \ \ \ \ \ $1\ \@\ €2\ =\ $1\ \@\ €2
\f[]
.fi
.SS Transaction prices
.PP
Within a transaction, you can note an amount\[aq]s price in another

158
hledger-lib/hledger_journal.info
View File

@ -573,8 +573,17 @@ File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and
1.9.5 Assertions and prices
---------------------------
Balance assertion (or assignment) amounts should not have a price, as
the meaning of that would be unclear.
Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ €1 = $1
We do allow prices to be written there, however, and print shows
them, even though they don't affect whether the assertion passes or
fails. This is for backward compatibility (hledger's close command used
to generate balance assertions with prices), and because balance
_assignments_ do use them (see below).

File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance Assertions
@ -652,6 +661,25 @@ of the commodity to that account since the last balance assertion or
assignment). Note that using balance assignments makes your journal a
little less explicit; to know the exact amount posted, you have to run
hledger or do the calculations yourself, instead of just reading it.
* Menu:
* Balance assignments and prices::

File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance Assignments
1.10.1 Balance assignments and prices
-------------------------------------
A transaction price in a balance assignment will cause the calculated
amount to have that price attached:
2019/1/1
(a) = $1 @ €2
$ hledger print --explicit
2019/01/01
(a) $1 @ €2 = $1 @ €2

File: hledger_journal.info, Node: Transaction prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT
@ -1597,67 +1625,69 @@ Node: Assertions and commodities19383
Ref: #assertions-and-commodities19613
Node: Assertions and prices20801
Ref: #assertions-and-prices21013
Node: Assertions and subaccounts21122
Ref: #assertions-and-subaccounts21349
Node: Assertions and virtual postings21870
Ref: #assertions-and-virtual-postings22110
Node: Assertions and precision22252
Ref: #assertions-and-precision22443
Node: Balance Assignments22710
Ref: #balance-assignments22891
Node: Transaction prices24011
Ref: #transaction-prices24180
Node: Comments26448
Ref: #comments26582
Node: Tags27752
Ref: #tags27870
Node: Directives29272
Ref: #directives29415
Node: Comment blocks35022
Ref: #comment-blocks35167
Node: Including other files35343
Ref: #including-other-files35523
Node: Default year35931
Ref: #default-year36100
Node: Declaring commodities36523
Ref: #declaring-commodities36706
Node: Default commodity37933
Ref: #default-commodity38109
Node: Market prices38745
Ref: #market-prices38910
Node: Declaring accounts39751
Ref: #declaring-accounts39927
Node: Account comments40852
Ref: #account-comments41015
Node: Account subdirectives41410
Ref: #account-subdirectives41605
Node: Account types41918
Ref: #account-types42102
Node: Account display order43746
Ref: #account-display-order43916
Node: Rewriting accounts45045
Ref: #rewriting-accounts45230
Node: Basic aliases45964
Ref: #basic-aliases46110
Node: Regex aliases46814
Ref: #regex-aliases46985
Node: Multiple aliases47703
Ref: #multiple-aliases47878
Node: end aliases48376
Ref: #end-aliases48523
Node: Default parent account48624
Ref: #default-parent-account48790
Node: Periodic transactions49674
Ref: #periodic-transactions49856
Node: Two spaces after the period expression50981
Ref: #two-spaces-after-the-period-expression51226
Node: Forecasting with periodic transactions51711
Ref: #forecasting-with-periodic-transactions52001
Node: Budgeting with periodic transactions53688
Ref: #budgeting-with-periodic-transactions53927
Node: Transaction Modifiers54386
Ref: #transaction-modifiers54549
Node: EDITOR SUPPORT56530
Ref: #editor-support56648
Node: Assertions and subaccounts21453
Ref: #assertions-and-subaccounts21680
Node: Assertions and virtual postings22201
Ref: #assertions-and-virtual-postings22441
Node: Assertions and precision22583
Ref: #assertions-and-precision22774
Node: Balance Assignments23041
Ref: #balance-assignments23222
Node: Balance assignments and prices24386
Ref: #balance-assignments-and-prices24558
Node: Transaction prices24782
Ref: #transaction-prices24951
Node: Comments27219
Ref: #comments27353
Node: Tags28523
Ref: #tags28641
Node: Directives30043
Ref: #directives30186
Node: Comment blocks35793
Ref: #comment-blocks35938
Node: Including other files36114
Ref: #including-other-files36294
Node: Default year36702
Ref: #default-year36871
Node: Declaring commodities37294
Ref: #declaring-commodities37477
Node: Default commodity38704
Ref: #default-commodity38880
Node: Market prices39516
Ref: #market-prices39681
Node: Declaring accounts40522
Ref: #declaring-accounts40698
Node: Account comments41623
Ref: #account-comments41786
Node: Account subdirectives42181
Ref: #account-subdirectives42376
Node: Account types42689
Ref: #account-types42873
Node: Account display order44517
Ref: #account-display-order44687
Node: Rewriting accounts45816
Ref: #rewriting-accounts46001
Node: Basic aliases46735
Ref: #basic-aliases46881
Node: Regex aliases47585
Ref: #regex-aliases47756
Node: Multiple aliases48474
Ref: #multiple-aliases48649
Node: end aliases49147
Ref: #end-aliases49294
Node: Default parent account49395
Ref: #default-parent-account49561
Node: Periodic transactions50445
Ref: #periodic-transactions50627
Node: Two spaces after the period expression51752
Ref: #two-spaces-after-the-period-expression51997
Node: Forecasting with periodic transactions52482
Ref: #forecasting-with-periodic-transactions52772
Node: Budgeting with periodic transactions54459
Ref: #budgeting-with-periodic-transactions54698
Node: Transaction Modifiers55157
Ref: #transaction-modifiers55320
Node: EDITOR SUPPORT57301
Ref: #editor-support57419

End Tag Table

347
hledger-lib/hledger_journal.txt
View File

@ -447,8 +447,17 @@ FILE FORMAT
a:euro 0 == 1
Assertions and prices
Balance assertion (or assignment) amounts should not have a price, as
the meaning of that would be unclear.
Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ 1 = $1
We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
ments do use them (see below).
Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they
@ -506,11 +515,22 @@ FILE FORMAT
less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it.
Balance assignments and prices
A transaction price in a balance assignment will cause the calculated
amount to have that price attached:
2019/1/1
(a) = $1 @ 2
$ hledger print --explicit
2019/01/01
(a) $1 @ 2 = $1 @ 2
Transaction prices
Within a transaction, you can note an amount's price in another commod-
ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer-
tain date.
@ -539,7 +559,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price's
Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above:
@ -550,8 +570,8 @@ FILE FORMAT
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last
Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last
amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different:
@ -565,14 +585,14 @@ FILE FORMAT
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;).
Some examples:
@ -596,24 +616,24 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using comment and
You can also comment larger regions of a file using comment and
end comment directives.
Tags
Tags are a way to add extra labels or labelled data to postings and
Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
Tags can have a value, which is the text after the colon, up to the
Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@ -627,68 +647,69 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
A directive is a line in the journal beginning with a special keyword,
A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with
here is a table summarising the directives and their effects, with
links to more detailed docs.
direc- end subdi- purpose can affect (as of
direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06)
tives
-------------------------------------------------------------------------------------------------
account any document account names, all entries in all
text declare account types & dis- files, before or
account any document account names, all entries in all
text declare account types & dis- files, before or
play order after
alias end aliases rewrite account names following
inline/included
entries until end
of current file or
of current file or
end directive
apply account end apply account prepend a common parent to following
apply account end apply account prepend a common parent to following
account names inline/included
entries until end
of current file or
of current file or
end directive
comment end comment ignore part of journal following
inline/included
entries until end
of current file or
of current file or
end directive
commodity format declare a commodity and its number notation:
commodity format declare a commodity and its number notation:
number notation & display following entries
style in that commodity
in all files; dis-
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
less entries and
entries in that
commodity in all
commodity in all
files; display
style: amounts of
that commodity in
@ -699,7 +720,7 @@ FILE FORMAT
commodity commodity in
reports, when -V is
used
Y declare a year for yearless following
Y declare a year for yearless following
dates inline/included
entries until end
of current file
@ -709,9 +730,9 @@ FILE FORMAT
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@ -719,37 +740,37 @@ FILE FORMAT
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
writing file options in a different order. It can be surprising at
times though.
Comment blocks
A line containing just comment starts a commented region of the file,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -769,8 +790,8 @@ FILE FORMAT
assets
Declaring commodities
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -780,8 +801,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
@ -793,19 +814,19 @@ FILE FORMAT
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
The D directive sets a default commodity (and display format), to be
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
@ -820,9 +841,9 @@ FILE FORMAT
a decimal point.
Market prices
The P directive declares a market price, which is an exchange rate
The P directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@ -833,39 +854,39 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, giving the price in commodity B of one unit of commodity A.
These two market price directives say that one euro was worth 1.35 US
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35
P 2010/1/1 $1.40
The -V/--value flag can be used to convert reported amounts to another
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
account directives can be used to pre-declare accounts. Though not
account directives can be used to pre-declare accounts. Though not
required, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer-
ence.
o They can store extra information about accounts (account numbers,
o They can store extra information about accounts (account numbers,
notes, etc.)
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
o They control account display order in reports, allowing non-alpha-
o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command,
o They help with account name completion in the add command,
hledger-iadd, hledger-web, ledger-mode etc.
The simplest form is just the word account followed by a hledger-style
The simplest form is just the word account followed by a hledger-style
account name, eg:
account assets:bank:checking
@ -883,7 +904,7 @@ FILE FORMAT
the next line instead.
Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just
We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
@ -896,18 +917,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are
bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
Account types declared with tags
More generally, you can declare an account's type with an account
directive, by writing a type: tag in a comment, followed by one of the
More generally, you can declare an account's type with an account
directive, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@ -918,8 +939,8 @@ FILE FORMAT
account expenses ; type:Expenses
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A
@ -929,7 +950,7 @@ FILE FORMAT
account expenses X
Overriding auto-detected types
If you ever override the types of those auto-detected english account
If you ever override the types of those auto-detected english account
names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why
@ -940,8 +961,8 @@ FILE FORMAT
account - ; type:L
Account display order
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal:
@ -963,16 +984,16 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
@ -991,14 +1012,14 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or
do not affect account names being entered via hledger add or
hledger-web.
See also Cookbook: Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -1006,54 +1027,54 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub-
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub-
accounts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
There is also a more powerful variant that uses a regular expression,
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
1. alias directives, most recently seen first (recent directives take
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
end aliases
You can clear (forget) all currently defined aliases with the
You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@ -1070,7 +1091,7 @@ FILE FORMAT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -1079,18 +1100,18 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
account.
Periodic transactions
Periodic transaction rules describe transactions that recur. They
Periodic transaction rules describe transactions that recur. They
allow you to generate future transactions for forecasting, without hav-
ing to write them out explicitly in the journal (with --forecast).
ing to write them out explicitly in the journal (with --forecast).
Secondly, they also can be used to define budget goals (with --budget).
A periodic transaction rule looks like a normal journal entry, with the
@ -1101,17 +1122,17 @@ FILE FORMAT
expenses:rent $2000
assets:bank:checking
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg
monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not.
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
Two spaces after the period expression
If the period expression is followed by a transaction description,
If the period expression is followed by a transaction description,
these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example:
@ -1124,65 +1145,65 @@ FILE FORMAT
income:acme inc
Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates
With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
the generating period expression.
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
forecast period:
o begins on the later of
o the report start date if specified with -b/-p/date:
o the day after the latest normal (non-periodic) transaction in the
o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
o ends on the report end date if specified with -e/-p/date:, or 180
o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
actions with periodic rules, and every so often copy the output of
actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
For more details, see: balance: Budget report and Cookbook: Budgeting
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
Transaction Modifiers
Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding
Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding
extra postings (also known as "automated postings"). Transaction modi-
fiers are enabled by the --auto flag.
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each
"posting" is actually a posting-generating rule:
= QUERY
@ -1193,17 +1214,17 @@ FILE FORMAT
The posting rules look just like normal postings, except the amount can
be:
o a normal amount with a commodity symbol, eg $2. This will be used
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
o a numeric multiplier, eg *2 (a star followed by a number N). The
o a numeric multiplier, eg *2 (a star followed by a number N). The
matched posting's amount (and total price, if any) will be multiplied
by N.
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
@ -1239,16 +1260,16 @@ FILE FORMAT
assets:checking $20
Postings added by transaction modifiers participate in transaction bal-
ancing, missing amount inference and balance assertions, like regular
ancing, missing amount inference and balance assertions, like regular
postings.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger
These were written with Ledger in mind, but also work with hledger
files:
@ -1267,7 +1288,7 @@ EDITOR SUPPORT
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -1281,7 +1302,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

2
hledger-ui/hledger-ui.1
View File

@ -424,7 +424,7 @@ Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[]
toggles cleared transactions.
(By default, transactions with all statuses are shown; if you activate
one or two status filters, only those transactions are shown; and if you
activate all three, the filter is removed.)q
activate all three, the filter is removed.)
.PP
\f[C]R\f[] toggles real mode, in which virtual postings are ignored.
.PP

10
hledger-ui/hledger-ui.info
View File

@ -349,7 +349,7 @@ transactions. Similarly, 'P' toggles pending transactions, and 'C'
toggles cleared transactions. (By default, transactions with all
statuses are shown; if you activate one or two status filters, only
those transactions are shown; and if you activate all three, the filter
is removed.)q
is removed.)
'R' toggles real mode, in which virtual postings are ignored.
@ -408,9 +408,9 @@ Node: Accounts screen8148
Ref: #accounts-screen8276
Node: Register screen10492
Ref: #register-screen10647
Node: Transaction screen12644
Ref: #transaction-screen12802
Node: Error screen13672
Ref: #error-screen13794
Node: Transaction screen12643
Ref: #transaction-screen12801
Node: Error screen13671
Ref: #error-screen13793

End Tag Table

3
hledger-ui/hledger-ui.txt
View File

@ -314,8 +314,7 @@ SCREENS
transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is
removed.)q
tions are shown; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.

18
hledger/hledger.1
View File

@ -1639,11 +1639,6 @@ show performance compared to budget goals defined by periodic
transactions
.RS
.RE
.TP
.B \f[C]\-\-show\-unbudgeted\f[]
with \-\-budget, show unbudgeted accounts also
.RS
.RE
.PP
The balance command is hledger\[aq]s most versatile command.
Note, despite the name, it is not always used for showing real\-world
@ -1934,6 +1929,8 @@ Second, all accounts which existed at the report start date will be
considered, not just the ones with activity during the report period
(use \-E to include low\-activity accounts which would otherwise would
be omitted).
With \f[C]\-\-budget\f[], \f[C]\-\-empty\f[] also shows unbudgeted
accounts.
.PP
The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing
the total for each row.
@ -2040,12 +2037,11 @@ In the example above, transactions in \f[C]expenses:gifts\f[] and
but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are
not shown, as they don\[aq]t have any budgets.
.PP
You can use \f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as
well:
You can use \f[C]\-\-empty\f[] shows unbudgeted accounts as well:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-show\-unbudgeted
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-empty
Budget\ performance\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\
@ -2174,12 +2170,12 @@ Budget\ performance\ in\ 2019/01:
\f[]
.fi
.PP
And with \f[C]\-\-show\-unbudgeted\f[], we can get a better picture of
budget allocation and consumption:
And with \f[C]\-\-empty\f[], we can get a better picture of budget
allocation and consumption:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-\-budget\ \-M\ \-\-show\-unbudgeted
$\ hledger\ balance\ \-\-budget\ \-M\ \-\-empty
Budget\ performance\ in\ 2019/01:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\

190
hledger/hledger.info
View File

@ -1243,9 +1243,6 @@ Show accounts and their balances. Aliases: b, bal.
show performance compared to budget goals defined by periodic
transactions
'--show-unbudgeted'
with -budget, show unbudgeted accounts also
The balance command is hledger's most versatile command. Note,
despite the name, it is not always used for showing real-world account
@ -1510,7 +1507,8 @@ period (without -E, leading and trailing columns with all zeroes are not
shown). Second, all accounts which existed at the report start date
will be considered, not just the ones with activity during the report
period (use -E to include low-activity accounts which would otherwise
would be omitted).
would be omitted). With '--budget', '--empty' also shows unbudgeted
accounts.
The '-T/--row-total' flag adds an additional column showing the total
for each row.
@ -1608,9 +1606,9 @@ are shown. In the example above, transactions in 'expenses:gifts' and
'expenses:gifts' and 'expenses:supplies' are not shown, as they don't
have any budgets.
You can use '--show-unbudgeted' shows unbudgeted accounts as well:
You can use '--empty' shows unbudgeted accounts as well:
$ hledger balance -M --budget --show-unbudgeted
$ hledger balance -M --budget --empty
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
@ -1725,10 +1723,10 @@ Budget performance in 2019/01:
-------------------------------++-------------------------------
|| 0 [ 0]
And with '--show-unbudgeted', we can get a better picture of budget
allocation and consumption:
And with '--empty', we can get a better picture of budget allocation
and consumption:
$ hledger balance --budget -M --show-unbudgeted
$ hledger balance --budget -M --empty
Budget performance in 2019/01:
|| Jan
@ -2808,92 +2806,92 @@ Node: add35465
Ref: #add35564
Node: balance38225
Ref: #balance38336
Node: Classic balance report41526
Ref: #classic-balance-report41699
Node: Customising the classic balance report43068
Ref: #customising-the-classic-balance-report43296
Node: Colour support45370
Ref: #colour-support45537
Node: Flat mode45710
Ref: #flat-mode45858
Node: Depth limited balance reports46271
Ref: #depth-limited-balance-reports46471
Node: Multicolumn balance report46927
Ref: #multicolumn-balance-report47125
Node: Budget report52305
Ref: #budget-report52448
Node: Nested budgets57152
Ref: #nested-budgets57264
Ref: #output-format-160764
Node: balancesheet60842
Ref: #balancesheet60978
Node: balancesheetequity63289
Ref: #balancesheetequity63438
Node: cashflow63975
Ref: #cashflow64103
Node: check-dates66226
Ref: #check-dates66353
Node: check-dupes66470
Ref: #check-dupes66594
Node: close66731
Ref: #close66839
Node: files70253
Ref: #files70354
Node: help70495
Ref: #help70595
Node: import71669
Ref: #import71783
Node: incomestatement72513
Ref: #incomestatement72647
Node: prices75051
Ref: #prices75166
Node: print75438
Ref: #print75548
Node: print-unique80442
Ref: #print-unique80568
Node: register80636
Ref: #register80763
Node: Custom register output85264
Ref: #custom-register-output85393
Node: register-match86623
Ref: #register-match86757
Node: rewrite86940
Ref: #rewrite87055
Node: roi87124
Ref: #roi87222
Node: stats87338
Ref: #stats87437
Node: tags88307
Ref: #tags88405
Node: test88641
Ref: #test88725
Node: ADD-ON COMMANDS89433
Ref: #add-on-commands89543
Node: Official add-ons90830
Ref: #official-add-ons90970
Node: api91057
Ref: #api91146
Node: ui91198
Ref: #ui91297
Node: web91355
Ref: #web91444
Node: Third party add-ons91490
Ref: #third-party-add-ons91665
Node: diff91800
Ref: #diff91897
Node: iadd91996
Ref: #iadd92110
Node: interest92193
Ref: #interest92314
Node: irr92409
Ref: #irr92507
Node: Experimental add-ons92638
Ref: #experimental-add-ons92790
Node: autosync93070
Ref: #autosync93181
Node: chart93420
Ref: #chart93539
Node: check93610
Ref: #check93712
Node: Classic balance report41456
Ref: #classic-balance-report41629
Node: Customising the classic balance report42998
Ref: #customising-the-classic-balance-report43226
Node: Colour support45300
Ref: #colour-support45467
Node: Flat mode45640
Ref: #flat-mode45788
Node: Depth limited balance reports46201
Ref: #depth-limited-balance-reports46401
Node: Multicolumn balance report46857
Ref: #multicolumn-balance-report47055
Node: Budget report52295
Ref: #budget-report52438
Node: Nested budgets57122
Ref: #nested-budgets57234
Ref: #output-format-160714
Node: balancesheet60792
Ref: #balancesheet60928
Node: balancesheetequity63239
Ref: #balancesheetequity63388
Node: cashflow63925
Ref: #cashflow64053
Node: check-dates66176
Ref: #check-dates66303
Node: check-dupes66420
Ref: #check-dupes66544
Node: close66681
Ref: #close66789
Node: files70203
Ref: #files70304
Node: help70445
Ref: #help70545
Node: import71619
Ref: #import71733
Node: incomestatement72463
Ref: #incomestatement72597
Node: prices75001
Ref: #prices75116
Node: print75388
Ref: #print75498
Node: print-unique80392
Ref: #print-unique80518
Node: register80586
Ref: #register80713
Node: Custom register output85214
Ref: #custom-register-output85343
Node: register-match86573
Ref: #register-match86707
Node: rewrite86890
Ref: #rewrite87005
Node: roi87074
Ref: #roi87172
Node: stats87288
Ref: #stats87387
Node: tags88257
Ref: #tags88355
Node: test88591
Ref: #test88675
Node: ADD-ON COMMANDS89383
Ref: #add-on-commands89493
Node: Official add-ons90780
Ref: #official-add-ons90920
Node: api91007
Ref: #api91096
Node: ui91148
Ref: #ui91247
Node: web91305
Ref: #web91394
Node: Third party add-ons91440
Ref: #third-party-add-ons91615
Node: diff91750
Ref: #diff91847
Node: iadd91946
Ref: #iadd92060
Node: interest92143
Ref: #interest92264
Node: irr92359
Ref: #irr92457
Node: Experimental add-ons92588
Ref: #experimental-add-ons92740
Node: autosync93020
Ref: #autosync93131
Node: chart93370
Ref: #chart93489
Node: check93560
Ref: #check93662

End Tag Table

398
hledger/hledger.txt
View File

@ -1111,9 +1111,6 @@ COMMANDS
show performance compared to budget goals defined by periodic
transactions
--show-unbudgeted
with --budget, show unbudgeted accounts also
The balance command is hledger's most versatile command. Note, despite
the name, it is not always used for showing real-world account bal-
ances; the more accounting-aware balancesheet and incomestatement may
@ -1348,12 +1345,13 @@ COMMANDS
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
report period (use -E to include low-activity accounts which would oth-
erwise would be omitted).
erwise would be omitted). With --budget, --empty also shows unbudgeted
accounts.
The -T/--row-total flag adds an additional column showing the total for
each row.
The -A/--average flag adds a column showing the average value in each
The -A/--average flag adds a column showing the average value in each
row.
Here's an example of all three:
@ -1377,20 +1375,20 @@ COMMANDS
Limitations:
In multicolumn reports the -V/--value flag uses the market price on the
report end date, for all columns (not the price on each column's end
report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic bal-
Eliding of boring parent accounts in tree mode, as in the classic bal-
ance report, is not yet supported in multicolumn reports.
Budget report
With --budget, extra columns are displayed showing budget goals for
each account and period, if any. Budget goals are defined by periodic
transactions. This is very useful for comparing planned and actual
income, expenses, time usage, etc. --budget is most often combined
With --budget, extra columns are displayed showing budget goals for
each account and period, if any. Budget goals are defined by periodic
transactions. This is very useful for comparing planned and actual
income, expenses, time usage, etc. --budget is most often combined
with a report interval.
For example, you can take average monthly expenses in the common
For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
;; Budget
@ -1435,15 +1433,15 @@ COMMANDS
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
By default, only accounts with budget goals during the report period
are shown. In the example above, transactions in expenses:gifts and
expenses:supplies are counted towards expenses budget, but accounts
expenses:gifts and expenses:supplies are not shown, as they don't have
By default, only accounts with budget goals during the report period
are shown. In the example above, transactions in expenses:gifts and
expenses:supplies are counted towards expenses budget, but accounts
expenses:gifts and expenses:supplies are not shown, as they don't have
any budgets.
You can use --show-unbudgeted shows unbudgeted accounts as well:
You can use --empty shows unbudgeted accounts as well:
$ hledger balance -M --budget --show-unbudgeted
$ hledger balance -M --budget --empty
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
@ -1479,18 +1477,18 @@ COMMANDS
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
Note, the -S/--sort-amount flag is not yet fully supported with --bud-
Note, the -S/--sort-amount flag is not yet fully supported with --bud-
get.
For more examples, see Budgeting and Forecasting.
Nested budgets
You can add budgets to any account in your account hierarchy. If you
You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their
get(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
@ -1500,13 +1498,13 @@ COMMANDS
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity
means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both
towards its $100 budget and $1100 of expenses:personal , and transac-
tions in any other subaccount of expenses:personal would be counted
Transactions in expenses:personal:electronics will be counted both
towards its $100 budget and $1100 of expenses:personal , and transac-
tions in any other subaccount of expenses:personal would be counted
towards only towards the budget of expenses:personal.
For example, let's consider these transactions:
@ -1532,9 +1530,9 @@ COMMANDS
expenses:personal $30.00
liabilities
As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac-
As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac-
tions would be counted towards budgets of expenses:personal:electronics
and expenses:personal accordingly:
@ -1550,10 +1548,10 @@ COMMANDS
-------------------------------++-------------------------------
|| 0 [ 0]
And with --show-unbudgeted, we can get a better picture of budget allo-
cation and consumption:
And with --empty, we can get a better picture of budget allocation and
consumption:
$ hledger balance --budget -M --show-unbudgeted
$ hledger balance --budget -M --empty
Budget performance in 2019/01:
|| Jan
@ -1568,16 +1566,16 @@ COMMANDS
|| 0 [ 0]
Output format
The balance command supports output destination and output format
The balance command supports output destination and output format
selection.
balancesheet
This command displays a simple balance sheet, showing historical ending
balances of asset and liability accounts (ignoring any report begin
date). It assumes that these accounts are under a top-level asset or
liability account (case insensitive, plural forms also allowed). Note
this report shows all account balances with normal positive sign (like
conventional financial statements, unlike balance/print/register)
balances of asset and liability accounts (ignoring any report begin
date). It assumes that these accounts are under a top-level asset or
liability account (case insensitive, plural forms also allowed). Note
this report shows all account balances with normal positive sign (like
conventional financial statements, unlike balance/print/register)
(experimental). (bs)
--change
@ -1585,7 +1583,7 @@ COMMANDS
balances
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of historical ending balances
-H --historical
@ -1641,16 +1639,16 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
balancesheetequity
Just like balancesheet, but also reports Equity (which it assumes is
Just like balancesheet, but also reports Equity (which it assumes is
under a top-level equity account).
Example:
@ -1680,10 +1678,10 @@ COMMANDS
0
cashflow
This command displays a simple cashflow statement, showing changes in
"cash" accounts. It assumes that these accounts are under a top-level
asset account (case insensitive, plural forms also allowed) and do not
contain receivable or A/R in their name. Note this report shows all
This command displays a simple cashflow statement, showing changes in
"cash" accounts. It assumes that these accounts are under a top-level
asset account (case insensitive, plural forms also allowed) and do not
contain receivable or A/R in their name. Note this report shows all
account balances with normal positive sign (like conventional financial
statements, unlike balance/print/register) (experimental). (cf)
@ -1691,7 +1689,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1742,69 +1740,69 @@ COMMANDS
$-1
With a reporting interval, multiple columns will be shown, one for each
report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report
report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
check-dates
Check that transactions are sorted by increasing date. With a query,
Check that transactions are sorted by increasing date. With a query,
only matched transactions' dates are checked.
check-dupes
Report account names having the same leaf but different prefixes. An
Report account names having the same leaf but different prefixes. An
example: http://stefanorodighiero.net/software/hledger-dupes.html
close
close, equity Prints a "closing balances" transaction and an "opening
balances" transaction that bring account balances to and from zero,
respectively. Useful for bringing asset/liability balances forward
into a new journal file, or for closing out revenues/expenses to
close, equity Prints a "closing balances" transaction and an "opening
balances" transaction that bring account balances to and from zero,
respectively. Useful for bringing asset/liability balances forward
into a new journal file, or for closing out revenues/expenses to
retained earnings at the end of a period.
The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open-
ing balances". You can chose to print just one of the transactions by
The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open-
ing balances". You can chose to print just one of the transactions by
using the --opening or --closing flag.
If you split your journal files by time (eg yearly), you will typically
run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open-
run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open-
ing|closing) balances'.)
If you're running a business, you might also use this command to "close
the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to
the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to
change the equity account name to something like "equity:retained earn-
ings".)
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
You can also use -p or date:PERIOD (any starting date is ignored).
Both transactions will include balance assertions for the
closed/reopened accounts. You probably shouldn't use status or real-
ness filters (like -C or -R or status:) with this command, or the gen-
closed/reopened accounts. You probably shouldn't use status or real-
ness filters (like -C or -R or status:) with this command, or the gen-
erated balance assertions will depend on these flags. Likewise, if you
run this command with --auto, the balance assertions will probably
run this command with --auto, the balance assertions will probably
always require --auto.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
Carrying asset/liability balances into a new file for 2019, all from
command line:
Warning: we use >> here to append; be careful not to type a single >
Warning: we use >> here to append; be careful not to type a single >
which would wipe your journal!
$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
@ -1836,19 +1834,19 @@ COMMANDS
assets:checking
files
List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown.
List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown.
help
Show any of the hledger manuals.
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one.
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags.
$ hledger help
@ -1872,7 +1870,7 @@ COMMANDS
...
import
Read new transactions added to each FILE since last run, and add them
Read new transactions added to each FILE since last run, and add them
to the main journal file.
--dry-run
@ -1886,24 +1884,24 @@ COMMANDS
ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files.
The --dry-run output is in journal format, so you can filter it, eg to
The --dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
incomestatement
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
unlike balance/print/register) (experimental). (is)
--change
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1937,8 +1935,8 @@ COMMANDS
--sort-amount
sort by amount instead of account code/name
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@ -1963,25 +1961,25 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
prices
Print market price directives from the journal. With --costs, also
print synthetic market prices based on transaction prices. With
Print market price directives from the journal. With --costs, also
print synthetic market prices based on transaction prices. With
--inverted-costs, also print inverse prices based on transaction
prices. Prices (and postings providing prices) can be filtered by a
prices. Prices (and postings providing prices) can be filtered by a
query.
print
Show transactions from the journal. Aliases: p, txns.
-m STR --match=STR
show the transaction whose description is most similar to STR,
show the transaction whose description is most similar to STR,
and is most recent
--new show only newer-dated transactions added in each file since last
@ -1994,7 +1992,7 @@ COMMANDS
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger print
@ -2025,39 +2023,39 @@ COMMANDS
it does not preserve directives or inter-transaction comments
Normally, the journal entry's explicit or implicit amount style is pre-
served. Ie when an amount is omitted in the journal, it will be omit-
ted in the output. You can use the -x/--explicit flag to make all
served. Ie when an amount is omitted in the journal, it will be omit-
ted in the output. You can use the -x/--explicit flag to make all
amounts explicit, which can be useful for troubleshooting or for making
your journal more readable and robust against data entry errors. Note,
-x will cause postings with a multi-commodity amount (these can arise
when a multi-commodity transaction has an implicit amount) will be
split into multiple single-commodity postings, for valid journal out-
-x will cause postings with a multi-commodity amount (these can arise
when a multi-commodity transaction has an implicit amount) will be
split into multiple single-commodity postings, for valid journal out-
put.
With -B/--cost, amounts with transaction prices are converted to cost
With -B/--cost, amounts with transaction prices are converted to cost
using that price. This can be used for troubleshooting.
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is
no similar-enough match, no transaction will be shown.
With --new, for each FILE being read, hledger reads (and writes) a spe-
cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for
ignoring already-seen entries in import data, such as downloaded CSV
cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for
ignoring already-seen entries in import data, such as downloaded CSV
files. Eg:
$ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file
This assumes that transactions added to FILE always have same or
increasing dates, and that transactions on the same day do not get
This assumes that transactions added to FILE always have same or
increasing dates, and that transactions on the same day do not get
reordered. See also the import command.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion. Here's an example of print's CSV output:
$ hledger print -Ocsv
@ -2074,20 +2072,20 @@ COMMANDS
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
o There is one CSV record per posting, with the parent transaction's
o There is one CSV record per posting, with the parent transaction's
fields repeated.
o The "txnidx" (transaction index) field shows which postings belong to
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
order, etc.)
o The amount is separated into "commodity" (the symbol) and "amount"
o The amount is separated into "commodity" (the symbol) and "amount"
(numeric quantity) fields.
o The numeric amount is repeated in either the "credit" or "debit" col-
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
greater amounts under debit.)
print-unique
@ -2100,7 +2098,7 @@ COMMANDS
show running total from report start date (default)
-H --historical
show historical running total/balance (includes postings before
show historical running total/balance (includes postings before
report start date)
-A --average
@ -2111,18 +2109,18 @@ COMMANDS
show postings' siblings instead
-w N --width=N
set output width (default: terminal width or COLUMNS. -wN,M
set output width (default: terminal width or COLUMNS. -wN,M
sets description width as well)
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
The register command displays postings, one per line, and their running
total. This is typically used with a query selecting a particular
total. This is typically used with a query selecting a particular
account, to see that account's activity:
$ hledger register checking
@ -2131,8 +2129,8 @@ COMMANDS
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical
@ -2142,23 +2140,23 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead
The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one
account and one commodity.
The --related/-r flag shows the other postings in the transactions of
The --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown.
With a reporting interval, register shows summary postings, one per
With a reporting interval, register shows summary postings, one per
interval, aggregating the postings to each account:
$ hledger register --monthly income
2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are
Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E
@ -2175,7 +2173,7 @@ COMMANDS
2008/11 0 $-2
2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth
Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@ -2183,19 +2181,19 @@ COMMANDS
2008/06 assets $-1 0
2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report.
Custom register output
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
--width W,D . Here's a diagram:
<--------------------------------- width (W) ---------------------------------->
@ -2211,26 +2209,26 @@ COMMANDS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
register-match
Print the one posting whose transaction description is closest to DESC,
in the style of the register command. Helps ledger-autosync detect
in the style of the register command. Helps ledger-autosync detect
already-seen transactions when importing.
rewrite
Print all transactions, adding custom postings to the matched ones.
roi
Shows time-weighted (TWR) and money-weighted (IRR) rate of return on
Shows time-weighted (TWR) and money-weighted (IRR) rate of return on
your investments. See roi --help for more.
stats
Show some journal statistics.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger stats
@ -2245,61 +2243,61 @@ COMMANDS
Accounts : 8 (depth 3)
Commodities : 1 ($)
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
tags
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
shown. With additional QUERY arguments, only transactions matching the
query are considered.
test
Run built-in unit tests.
Prints test names and their results on stdout. If any test fails or
Prints test names and their results on stdout. If any test fails or
gives an error, the exit code will be non-zero.
Test names include a group prefix. If a (exact, case sensitive) group
prefix, or a full test name is provided as the first argument, only
Test names include a group prefix. If a (exact, case sensitive) group
prefix, or a full test name is provided as the first argument, only
that group or test is run.
If a numeric second argument is provided, it will set the randomness
seed, for repeatable results from tests using randomness (currently
If a numeric second argument is provided, it will set the randomness
seed, for repeatable results from tests using randomness (currently
none of them).
This is mainly used by developers, but it's nice to be able to san-
This is mainly used by developers, but it's nice to be able to san-
ity-check your installed hledger executable at any time. All tests are
expected to pass - if you ever see otherwise, something has gone wrong,
please report a bug!
ADD-ON COMMANDS
hledger also searches for external add-on commands, and will include
hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten-
whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
Add-ons can be invoked like any hledger command, but there are a few
Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred:
o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
@ -2317,7 +2315,7 @@ ADD-ON COMMANDS
hledger-web provides a simple web interface.
Third party add-ons
These are maintained separately, and usually updated shortly after a
These are maintained separately, and usually updated shortly after a
hledger release.
diff
@ -2325,7 +2323,7 @@ ADD-ON COMMANDS
journal file and another.
iadd
hledger-iadd is a curses-style, more interactive replacement for the
hledger-iadd is a curses-style, more interactive replacement for the
add command.
interest
@ -2333,19 +2331,19 @@ ADD-ON COMMANDS
ing to various schemes.
irr
hledger-irr calculates the internal rate of return of an investment
hledger-irr calculates the internal rate of return of an investment
account, but it's superseded now by the built-in roi command.
Experimental add-ons
These are available in source form in the hledger repo's bin/ direc-
These are available in source form in the hledger repo's bin/ direc-
tory; installing them is pretty easy. They may be less mature and doc-
umented than built-in commands. Reading and tweaking these is a good
umented than built-in commands. Reading and tweaking these is a good
way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
chart
@ -2355,21 +2353,21 @@ ADD-ON COMMANDS
hledger-check.hs checks more powerful account balance assertions.
ENVIRONMENT
COLUMNS The screen width used by the register command. Default: the
COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede addon command options with -- when invoked from
The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@ -2382,33 +2380,33 @@ BUGS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
Not all of Ledger's journal file syntax is supported. See file format
Not all of Ledger's journal file syntax is supported. See file format
differences.
On large data files, hledger is slower and uses more memory than
On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command 'hledger' found"
stack and cabal install binaries into a special directory, which should
be added to your PATH environment variable. Eg on unix-like systems,
be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu
@ -2427,7 +2425,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
If we preferred to use eg fr_FR.utf8, we might have to install that
If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr
@ -2448,7 +2446,7 @@ TROUBLESHOOTING
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -2462,7 +2460,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)