slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages 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 .fi
.SS Assertions and prices .SS Assertions and prices
.PP .PP
Balance assertion (or assignment) amounts should not have a price, as Balance assertions ignore transaction prices, and should normally be
the meaning of that would be unclear. 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 .SS Assertions and subaccounts
.PP .PP
Balance assertions do not count the balance from subaccounts; they check 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 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 explicit; to know the exact amount posted, you have to run hledger or do
the calculations yourself, instead of just reading it. 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 .SS Transaction prices
.PP .PP
Within a transaction, you can note an amount\[aq]s price in another 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 1.9.5 Assertions and prices
--------------------------- ---------------------------
Balance assertion (or assignment) amounts should not have a price, as Balance assertions ignore transaction prices, and should normally be
the meaning of that would be unclear. 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 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 assignment). Note that using balance assignments makes your journal a
little less explicit; to know the exact amount posted, you have to run little less explicit; to know the exact amount posted, you have to run
hledger or do the calculations yourself, instead of just reading it. 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 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 Ref: #assertions-and-commodities19613
Node: Assertions and prices20801 Node: Assertions and prices20801
Ref: #assertions-and-prices21013 Ref: #assertions-and-prices21013
Node: Assertions and subaccounts21122 Node: Assertions and subaccounts21453
Ref: #assertions-and-subaccounts21349 Ref: #assertions-and-subaccounts21680
Node: Assertions and virtual postings21870 Node: Assertions and virtual postings22201
Ref: #assertions-and-virtual-postings22110 Ref: #assertions-and-virtual-postings22441
Node: Assertions and precision22252 Node: Assertions and precision22583
Ref: #assertions-and-precision22443 Ref: #assertions-and-precision22774
Node: Balance Assignments22710 Node: Balance Assignments23041
Ref: #balance-assignments22891 Ref: #balance-assignments23222
Node: Transaction prices24011 Node: Balance assignments and prices24386
Ref: #transaction-prices24180 Ref: #balance-assignments-and-prices24558
Node: Comments26448 Node: Transaction prices24782
Ref: #comments26582 Ref: #transaction-prices24951
Node: Tags27752 Node: Comments27219
Ref: #tags27870 Ref: #comments27353
Node: Directives29272 Node: Tags28523
Ref: #directives29415 Ref: #tags28641
Node: Comment blocks35022 Node: Directives30043
Ref: #comment-blocks35167 Ref: #directives30186
Node: Including other files35343 Node: Comment blocks35793
Ref: #including-other-files35523 Ref: #comment-blocks35938
Node: Default year35931 Node: Including other files36114
Ref: #default-year36100 Ref: #including-other-files36294
Node: Declaring commodities36523 Node: Default year36702
Ref: #declaring-commodities36706 Ref: #default-year36871
Node: Default commodity37933 Node: Declaring commodities37294
Ref: #default-commodity38109 Ref: #declaring-commodities37477
Node: Market prices38745 Node: Default commodity38704
Ref: #market-prices38910 Ref: #default-commodity38880
Node: Declaring accounts39751 Node: Market prices39516
Ref: #declaring-accounts39927 Ref: #market-prices39681
Node: Account comments40852 Node: Declaring accounts40522
Ref: #account-comments41015 Ref: #declaring-accounts40698
Node: Account subdirectives41410 Node: Account comments41623
Ref: #account-subdirectives41605 Ref: #account-comments41786
Node: Account types41918 Node: Account subdirectives42181
Ref: #account-types42102 Ref: #account-subdirectives42376
Node: Account display order43746 Node: Account types42689
Ref: #account-display-order43916 Ref: #account-types42873
Node: Rewriting accounts45045 Node: Account display order44517
Ref: #rewriting-accounts45230 Ref: #account-display-order44687
Node: Basic aliases45964 Node: Rewriting accounts45816
Ref: #basic-aliases46110 Ref: #rewriting-accounts46001
Node: Regex aliases46814 Node: Basic aliases46735
Ref: #regex-aliases46985 Ref: #basic-aliases46881
Node: Multiple aliases47703 Node: Regex aliases47585
Ref: #multiple-aliases47878 Ref: #regex-aliases47756
Node: end aliases48376 Node: Multiple aliases48474
Ref: #end-aliases48523 Ref: #multiple-aliases48649
Node: Default parent account48624 Node: end aliases49147
Ref: #default-parent-account48790 Ref: #end-aliases49294
Node: Periodic transactions49674 Node: Default parent account49395
Ref: #periodic-transactions49856 Ref: #default-parent-account49561
Node: Two spaces after the period expression50981 Node: Periodic transactions50445
Ref: #two-spaces-after-the-period-expression51226 Ref: #periodic-transactions50627
Node: Forecasting with periodic transactions51711 Node: Two spaces after the period expression51752
Ref: #forecasting-with-periodic-transactions52001 Ref: #two-spaces-after-the-period-expression51997
Node: Budgeting with periodic transactions53688 Node: Forecasting with periodic transactions52482
Ref: #budgeting-with-periodic-transactions53927 Ref: #forecasting-with-periodic-transactions52772
Node: Transaction Modifiers54386 Node: Budgeting with periodic transactions54459
Ref: #transaction-modifiers54549 Ref: #budgeting-with-periodic-transactions54698
Node: EDITOR SUPPORT56530 Node: Transaction Modifiers55157
Ref: #editor-support56648 Ref: #transaction-modifiers55320
Node: EDITOR SUPPORT57301
Ref: #editor-support57419
 
End Tag Table End Tag Table

347
hledger-lib/hledger_journal.txt
View File

@ -447,8 +447,17 @@ FILE FORMAT
a:euro 0 == 1 a:euro 0 == 1
Assertions and prices Assertions and prices
Balance assertion (or assignment) amounts should not have a price, as Balance assertions ignore transaction prices, and should normally be
the meaning of that would be unclear. 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 Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they 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 less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it. 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 Transaction prices
Within a transaction, you can note an amount's price in another commod- 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 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 price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See 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- also market prices, which represent prevailing exchange rates on a cer-
tain date. tain date.
@ -539,7 +559,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores). 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). 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: Eg here is how -B affects the balance report for the example above:
@ -550,8 +570,8 @@ FILE FORMAT
$-135 assets:dollars $-135 assets:dollars
$135 assets:euros # <- the euros' cost $135 assets:euros # <- the euros' cost
Note -B is sensitive to the order of postings when a transaction price 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 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 amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different: is equivalent, -B shows something different:
@ -565,14 +585,14 @@ FILE FORMAT
Comments Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) are comments, and will be ignored. (Star comments cause org-mode (*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.) journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post- description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines. writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;). Transaction and posting comments must begin with a semicolon (;).
Some examples: Some examples:
@ -596,24 +616,24 @@ FILE FORMAT
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; 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. end comment directives.
Tags 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. 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: colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag: 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: next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value 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 lines. Ending at commas means you can write multiple short tags on one
line, comma separated: line, comma separated:
@ -627,68 +647,69 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..." o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting. postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag): third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2: 1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value ; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag: (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. are simple strings.
Directives 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 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 based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions). some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so 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. 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) tive directive rec- 2018/06)
tives tives
------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------
account any document account names, all entries in all account any document account names, all entries in all
text declare account types & dis- files, before or text declare account types & dis- files, before or
play order after play order after
alias end aliases rewrite account names following alias end aliases rewrite account names following
inline/included inline/included
entries until end entries until end
of current file or of current file or
end directive 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 account names inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
comment end comment ignore part of journal following comment end comment ignore part of journal following
inline/included inline/included
entries until end entries until end
of current file or of current file or
end directive 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 number notation & display following entries
style in that commodity style in that commodity
in all files; dis- in all files; dis-
play style: amounts play style: amounts
of that commodity of that commodity
in reports in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries notation & display style for modityless entries
commodityless amounts in all files; num- commodityless amounts in all files; num-
ber notation: fol- ber notation: fol-
lowing commodity- lowing commodity-
less entries and less entries and
entries in that entries in that
commodity in all commodity in all
files; display files; display
style: amounts of style: amounts of
that commodity in that commodity in
@ -699,7 +720,7 @@ FILE FORMAT
commodity commodity in commodity commodity in
reports, when -V is reports, when -V is
used used
Y declare a year for yearless following Y declare a year for yearless following
dates inline/included dates inline/included
entries until end entries until end
of current file of current file
@ -709,9 +730,9 @@ FILE FORMAT
subdirec- optional indented directive line immediately following a par- subdirec- optional indented directive line immediately following a par-
tive ent directive tive ent directive
number how to interpret numbers when parsing journal entries (the number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same each commodity can have its own notation, even in the same
file.) file.)
display how to display amounts of a commodity in reports (symbol side display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places) style and spacing, digit groups, decimal separator, decimal places)
@ -719,37 +740,37 @@ FILE FORMAT
scope are affected by a directive scope are affected by a directive
As you can see, directives vary in which journal entries and files they 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. (reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f 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 options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro- typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by 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. times though.
Comment blocks 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) and a line containing just end comment (or the end of the current file)
ends it. See also comments. ends it. See also comments.
Including other files 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: directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current 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. 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. include journal, timeclock or timedot files, but not CSV files.
Default year Default year
You can set a default year to be used for subsequent dates which don't 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. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -769,8 +790,8 @@ FILE FORMAT
assets assets
Declaring commodities Declaring commodities
The commodity directive declares commodities which may be used in the The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written journal (though currently we do not enforce this). It may be written
on a single line, like this: on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -780,8 +801,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places: places:
; commodity SYMBOL ; commodity SYMBOL
@ -793,19 +814,19 @@ FILE FORMAT
commodity INR commodity INR
format INR 9,99,99,999.00 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- display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable; mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by always be written with a decimal point (a period or comma, followed by
0 or more decimal digits). 0 or more decimal digits).
Default commodity 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 used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive. amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars # commodity-less amounts should be treated as dollars
@ -820,9 +841,9 @@ FILE FORMAT
a decimal point. a decimal point.
Market prices 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 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. cryptocurrency exchange, or the foreign exchange market.
Here is the format: Here is the format:
@ -833,39 +854,39 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced 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. 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: dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35 P 2009/1/1 $1.35
P 2010/1/1 $1.40 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. commodity using these prices.
Declaring accounts 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: required, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer- o They can document your intended chart of accounts, providing a refer-
ence. ence.
o They can store extra information about accounts (account numbers, o They can store extra information about accounts (account numbers,
notes, etc.) notes, etc.)
o They can help hledger know your accounts' types (asset, liability, o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and equity, revenue, expense), useful for reports like balancesheet and
incomestatement. 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). 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. 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 name, eg:
account assets:bank:checking account assets:bank:checking
@ -883,7 +904,7 @@ FILE FORMAT
the next line instead. the next line instead.
Account subdirectives Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.: for compatibility.:
account assets:bank:checking account assets:bank:checking
@ -896,18 +917,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED] [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types Account types
hledger recognises five types (or classes) of account: Asset, Liabil- hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow. reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types Auto-detected account types
If you name your top-level accounts with some variation of assets, lia- 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. detected automatically.
Account types declared with tags Account types declared with tags
More generally, you can declare an account's type with an account 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 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 words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive): ALERX (case insensitive):
@ -918,8 +939,8 @@ FILE FORMAT
account expenses ; type:Expenses account expenses ; type:Expenses
Account types declared with account type codes Account types declared with account type codes
Or, you can write one of those letters separated from the account name 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- by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13: cated as of hledger 1.13:
account assets A account assets A
@ -929,7 +950,7 @@ FILE FORMAT
account expenses X account expenses X
Overriding auto-detected types 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: names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
@ -940,8 +961,8 @@ FILE FORMAT
account - ; type:L account - ; type:L
Account display order Account display order
Account directives also set the order in which accounts are displayed, Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal: you have these account directives in the journal:
@ -963,16 +984,16 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order. Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently, each group of sibling accounts under the same parent). And currently,
this directive: this directive:
account other:zoo account other:zoo
would influence the position of zoo among other's subaccounts, but not would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order - 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 sibling accounts stay together (you couldn't display x:y in between a:b
and a:c). and a:c).
@ -991,14 +1012,14 @@ FILE FORMAT
o customising reports o customising reports
Account aliases also rewrite account names in account directives. They 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. hledger-web.
See also Cookbook: Rewrite account names. See also Cookbook: Rewrite account names.
Basic aliases Basic aliases
To set an account alias, use the alias directive in your journal file. 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 This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional: included files. The spaces around the = are optional:
alias OLD = NEW alias OLD = NEW
@ -1006,54 +1027,54 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This 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. affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub- replace any occurrence of the old account name with the new one. Sub-
accounts are also affected. Eg: accounts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking 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" # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases 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: indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'. or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE- inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref- MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg: erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command 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- line, to end of option argument), so it can contain trailing white-
space. space.
Multiple aliases Multiple aliases
You can define as many aliases as you like using directives or com- You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol- aliases are non-recursive by default). Aliases are applied in the fol-
lowing order: 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) precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line 2. alias options, in the order they appear on the command line
end aliases 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 directive:
end aliases end aliases
Default parent account Default parent account
You can specify a parent account which will be prepended to all You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and accounts within a section of the journal. Use the apply account and
end apply account directives like so: end apply account directives like so:
apply account home apply account home
@ -1070,7 +1091,7 @@ FILE FORMAT
home:food $10 home:food $10
home:cash $-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: file. Included files are also affected, eg:
apply account business apply account business
@ -1079,18 +1100,18 @@ FILE FORMAT
apply account personal apply account personal
include personal.journal 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. ported.
A default parent account also affects account directives. It does not A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent account aliases are present, they are applied after the default parent
account. account.
Periodic transactions 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- 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). Secondly, they also can be used to define budget goals (with --budget).
A periodic transaction rule looks like a normal journal entry, with the A periodic transaction rule looks like a normal journal entry, with the
@ -1101,17 +1122,17 @@ FILE FORMAT
expenses:rent $2000 expenses:rent $2000
assets:bank:checking assets:bank:checking
There is an additional constraint on the period expression: the start There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg 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. 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 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 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 date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1. they will be relative to Y/1/1.
Two spaces after the period expression 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 these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden- where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example: tally alter their meaning, as in this example:
@ -1124,65 +1145,65 @@ FILE FORMAT
income:acme inc income:acme inc
Forecasting with periodic transactions 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 future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like 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 normal transactions, but with an extra tag named recur, whose value is
the generating period expression. the generating period expression.
Forecast transactions start on the first occurrence, and end on the Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The last occurrence, of their interval within the forecast period. The
forecast period: forecast period:
o begins on the later of o begins on the later of
o the report start date if specified with -b/-p/date: 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. 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. days from today.
where "today" means the current date at report time. The "later of" where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac- rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end. tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal means that forecasted transactions are automatically replaced by normal
transactions as you add those. transactions as you add those.
Forecasting can also help with data entry: describe most of your trans- 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. print --forecast to the journal.
You can generate one-time transactions too: just write a period expres- You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.) forecast transactions on previous dates.)
Budgeting with periodic transactions Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command, With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com- checking) every month. Goals and actual performance can then be com-
pared in budget reports. 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. and Forecasting.
Transaction Modifiers Transaction Modifiers
Transaction modifier rules describe changes that should be applied Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding automatically to certain transactions. Currently, this means adding
extra postings (also known as "automated postings"). Transaction modi- extra postings (also known as "automated postings"). Transaction modi-
fiers are enabled by the --auto flag. fiers are enabled by the --auto flag.
A transaction modifier rule looks quite like a normal transaction, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each matches certain postings (mnemonic: = suggests matching). And each
"posting" is actually a posting-generating rule: "posting" is actually a posting-generating rule:
= QUERY = QUERY
@ -1193,17 +1214,17 @@ FILE FORMAT
The posting rules look just like normal postings, except the amount can The posting rules look just like normal postings, except the amount can
be: 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. as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post- o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this. 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 matched posting's amount (and total price, if any) will be multiplied
by N. 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 symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S. its commodity symbol will be replaced with S.
@ -1239,16 +1260,16 @@ FILE FORMAT
assets:checking $20 assets:checking $20
Postings added by transaction modifiers participate in transaction bal- 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. postings.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. 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: files:
@ -1267,7 +1288,7 @@ EDITOR SUPPORT
REPORTING BUGS 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) or hledger mail list)
@ -1281,7 +1302,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) 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. toggles cleared transactions.
(By default, transactions with all statuses are shown; if you activate (By default, transactions with all statuses are shown; if you activate
one or two status filters, only those transactions are shown; and if you 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 .PP
\f[C]R\f[] toggles real mode, in which virtual postings are ignored. \f[C]R\f[] toggles real mode, in which virtual postings are ignored.
.PP .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 toggles cleared transactions. (By default, transactions with all
statuses are shown; if you activate one or two status filters, only statuses are shown; if you activate one or two status filters, only
those transactions are shown; and if you activate all three, the filter 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. 'R' toggles real mode, in which virtual postings are ignored.
@ -408,9 +408,9 @@ Node: Accounts screen8148
Ref: #accounts-screen8276 Ref: #accounts-screen8276
Node: Register screen10492 Node: Register screen10492
Ref: #register-screen10647 Ref: #register-screen10647
Node: Transaction screen12644 Node: Transaction screen12643
Ref: #transaction-screen12802 Ref: #transaction-screen12801
Node: Error screen13672 Node: Error screen13671
Ref: #error-screen13794 Ref: #error-screen13793
 
End Tag Table 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 transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac- shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is tions are shown; and if you activate all three, the filter is removed.)
removed.)q
R toggles real mode, in which virtual postings are ignored. 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 transactions
.RS .RS
.RE .RE
.TP
.B \f[C]\-\-show\-unbudgeted\f[]
with \-\-budget, show unbudgeted accounts also
.RS
.RE
.PP .PP
The balance command is hledger\[aq]s most versatile command. The balance command is hledger\[aq]s most versatile command.
Note, despite the name, it is not always used for showing real\-world 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 considered, not just the ones with activity during the report period
(use \-E to include low\-activity accounts which would otherwise would (use \-E to include low\-activity accounts which would otherwise would
be omitted). be omitted).
With \f[C]\-\-budget\f[], \f[C]\-\-empty\f[] also shows unbudgeted
accounts.
.PP .PP
The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing
the total for each row. 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 but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are
not shown, as they don\[aq]t have any budgets. not shown, as they don\[aq]t have any budgets.
.PP .PP
You can use \f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as You can use \f[C]\-\-empty\f[] shows unbudgeted accounts as well:
well:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-show\-unbudgeted $\ hledger\ balance\ \-M\ \-\-budget\ \-\-empty
Budget\ performance\ in\ 2017/11/01\-2017/12/31: Budget\ performance\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\
@ -2174,12 +2170,12 @@ Budget\ performance\ in\ 2019/01:
\f[] \f[]
.fi .fi
.PP .PP
And with \f[C]\-\-show\-unbudgeted\f[], we can get a better picture of And with \f[C]\-\-empty\f[], we can get a better picture of budget
budget allocation and consumption: allocation and consumption:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ balance\ \-\-budget\ \-M\ \-\-show\-unbudgeted $\ hledger\ balance\ \-\-budget\ \-M\ \-\-empty
Budget\ performance\ in\ 2019/01: Budget\ performance\ in\ 2019/01:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 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 show performance compared to budget goals defined by periodic
transactions transactions
'--show-unbudgeted'
with -budget, show unbudgeted accounts also
The balance command is hledger's most versatile command. Note, The balance command is hledger's most versatile command. Note,
despite the name, it is not always used for showing real-world account 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 shown). Second, all accounts which existed at the report start date
will be considered, not just the ones with activity during the report will be considered, not just the ones with activity during the report
period (use -E to include low-activity accounts which would otherwise 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 The '-T/--row-total' flag adds an additional column showing the total
for each row. 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 'expenses:gifts' and 'expenses:supplies' are not shown, as they don't
have any budgets. 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: Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec || Nov Dec
@ -1725,10 +1723,10 @@ Budget performance in 2019/01:
-------------------------------++------------------------------- -------------------------------++-------------------------------
|| 0 [ 0] || 0 [ 0]
And with '--show-unbudgeted', we can get a better picture of budget And with '--empty', we can get a better picture of budget allocation
allocation and consumption: and consumption:
$ hledger balance --budget -M --show-unbudgeted $ hledger balance --budget -M --empty
Budget performance in 2019/01: Budget performance in 2019/01:
|| Jan || Jan
@ -2808,92 +2806,92 @@ Node: add35465
Ref: #add35564 Ref: #add35564
Node: balance38225 Node: balance38225
Ref: #balance38336 Ref: #balance38336
Node: Classic balance report41526 Node: Classic balance report41456
Ref: #classic-balance-report41699 Ref: #classic-balance-report41629
Node: Customising the classic balance report43068 Node: Customising the classic balance report42998
Ref: #customising-the-classic-balance-report43296 Ref: #customising-the-classic-balance-report43226
Node: Colour support45370 Node: Colour support45300
Ref: #colour-support45537 Ref: #colour-support45467
Node: Flat mode45710 Node: Flat mode45640
Ref: #flat-mode45858 Ref: #flat-mode45788
Node: Depth limited balance reports46271 Node: Depth limited balance reports46201
Ref: #depth-limited-balance-reports46471 Ref: #depth-limited-balance-reports46401
Node: Multicolumn balance report46927 Node: Multicolumn balance report46857
Ref: #multicolumn-balance-report47125 Ref: #multicolumn-balance-report47055
Node: Budget report52305 Node: Budget report52295
Ref: #budget-report52448 Ref: #budget-report52438
Node: Nested budgets57152 Node: Nested budgets57122
Ref: #nested-budgets57264 Ref: #nested-budgets57234
Ref: #output-format-160764 Ref: #output-format-160714
Node: balancesheet60842 Node: balancesheet60792
Ref: #balancesheet60978 Ref: #balancesheet60928
Node: balancesheetequity63289 Node: balancesheetequity63239
Ref: #balancesheetequity63438 Ref: #balancesheetequity63388
Node: cashflow63975 Node: cashflow63925
Ref: #cashflow64103 Ref: #cashflow64053
Node: check-dates66226 Node: check-dates66176
Ref: #check-dates66353 Ref: #check-dates66303
Node: check-dupes66470 Node: check-dupes66420
Ref: #check-dupes66594 Ref: #check-dupes66544
Node: close66731 Node: close66681
Ref: #close66839 Ref: #close66789
Node: files70253 Node: files70203
Ref: #files70354 Ref: #files70304
Node: help70495 Node: help70445
Ref: #help70595 Ref: #help70545
Node: import71669 Node: import71619
Ref: #import71783 Ref: #import71733
Node: incomestatement72513 Node: incomestatement72463
Ref: #incomestatement72647 Ref: #incomestatement72597
Node: prices75051 Node: prices75001
Ref: #prices75166 Ref: #prices75116
Node: print75438 Node: print75388
Ref: #print75548 Ref: #print75498
Node: print-unique80442 Node: print-unique80392
Ref: #print-unique80568 Ref: #print-unique80518
Node: register80636 Node: register80586
Ref: #register80763 Ref: #register80713
Node: Custom register output85264 Node: Custom register output85214
Ref: #custom-register-output85393 Ref: #custom-register-output85343
Node: register-match86623 Node: register-match86573
Ref: #register-match86757 Ref: #register-match86707
Node: rewrite86940 Node: rewrite86890
Ref: #rewrite87055 Ref: #rewrite87005
Node: roi87124 Node: roi87074
Ref: #roi87222 Ref: #roi87172
Node: stats87338 Node: stats87288
Ref: #stats87437 Ref: #stats87387
Node: tags88307 Node: tags88257
Ref: #tags88405 Ref: #tags88355
Node: test88641 Node: test88591
Ref: #test88725 Ref: #test88675
Node: ADD-ON COMMANDS89433 Node: ADD-ON COMMANDS89383
Ref: #add-on-commands89543 Ref: #add-on-commands89493
Node: Official add-ons90830 Node: Official add-ons90780
Ref: #official-add-ons90970 Ref: #official-add-ons90920
Node: api91057 Node: api91007
Ref: #api91146 Ref: #api91096
Node: ui91198 Node: ui91148
Ref: #ui91297 Ref: #ui91247
Node: web91355 Node: web91305
Ref: #web91444 Ref: #web91394
Node: Third party add-ons91490 Node: Third party add-ons91440
Ref: #third-party-add-ons91665 Ref: #third-party-add-ons91615
Node: diff91800 Node: diff91750
Ref: #diff91897 Ref: #diff91847
Node: iadd91996 Node: iadd91946
Ref: #iadd92110 Ref: #iadd92060
Node: interest92193 Node: interest92143
Ref: #interest92314 Ref: #interest92264
Node: irr92409 Node: irr92359
Ref: #irr92507 Ref: #irr92457
Node: Experimental add-ons92638 Node: Experimental add-ons92588
Ref: #experimental-add-ons92790 Ref: #experimental-add-ons92740
Node: autosync93070 Node: autosync93020
Ref: #autosync93181 Ref: #autosync93131
Node: chart93420 Node: chart93370
Ref: #chart93539 Ref: #chart93489
Node: check93610 Node: check93560
Ref: #check93712 Ref: #check93662
 
End Tag Table End Tag Table

398
hledger/hledger.txt
View File

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