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

regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-02-20 13:15:41 -08:00
parent 861baadb2b
commit 8620e5414f
6 changed files with 697 additions and 479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
hledger-lib/hledger_journal.5
View File

@ -491,10 +491,10 @@ which is more correct and provides better error checking.
.SS Balance Assertions .SS Balance Assertions
.PP .PP
hledger supports Ledger\-style balance assertions in journal files. hledger supports Ledger\-style balance assertions in journal files.
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s These look like, for example, \f[C]=\ EXPECTEDBALANCE\f[] following a
amount. posting\[aq]s amount.
Eg in this example we assert the expected dollar balance in accounts a Eg here we assert the expected dollar balance in accounts a and b after
and b after each posting: each posting:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -513,7 +513,7 @@ and report an error if any of them fail.
Balance assertions can protect you from, eg, inadvertently disrupting Balance assertions can protect you from, eg, inadvertently disrupting
reconciled balances while cleaning up old entries. reconciled balances while cleaning up old entries.
You can disable them temporarily with the You can disable them temporarily with the
\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for \f[C]\-I/\-\-ignore\-assertions\f[] flag, which can be useful for
troubleshooting or for reading Ledger files. troubleshooting or for reading Ledger files.
.SS Assertions and ordering .SS Assertions and ordering
.PP .PP
@ -558,11 +558,10 @@ We could call this a "partial" balance assertion.
To assert the balance of more than one commodity in an account, you can To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity\[aq]s balance. write multiple postings, each asserting one commodity\[aq]s balance.
.PP .PP
You can make a stronger kind of balance assertion, by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (\f[C]==EXPECTEDBALANCE\f[]). equals sign (\f[C]==\ EXPECTEDBALANCE\f[]).
This "complete" balance assertion asserts the absence of other This asserts that there are no other unasserted commodities in the
commodities (or, that their balance is 0, which to hledger is account (or, that their balance is 0).
equivalent.)
.IP .IP
.nf .nf
\f[C] \f[C]
@ -619,29 +618,19 @@ generate balance assertions with prices), and because balance
\f[I]assignments\f[] do use them (see below). \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 The balance assertions above (\f[C]=\f[] and \f[C]==\f[]) do not count
the posted account\[aq]s exclusive balance. the balance from subaccounts; they check the account\[aq]s exclusive
For example: balance only.
You can assert the balance including subaccounts by writing \f[C]=*\f[]
or \f[C]==*\f[], eg:
.IP .IP
.nf .nf
\f[C] \f[C]
1/1 2019/1/1
\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1 \ \ equity:opening\ balances
\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1 \ \ checking:a\ \ \ \ \ \ \ 5
\ \ equity \ \ checking:b\ \ \ \ \ \ \ 5
\f[] \ \ checking\ \ \ \ \ \ \ \ \ 1\ \ ==*\ 11
.fi
.PP
The balance report\[aq]s flat mode shows these exclusive balances more
clearly:
.IP
.nf
\f[C]
$\ hledger\ bal\ checking\ \-\-flat
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2
\f[] \f[]
.fi .fi
.SS Assertions and virtual postings .SS Assertions and virtual postings

194
hledger-lib/hledger_journal.info
View File

@ -449,9 +449,9 @@ File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignment
====================== ======================
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in These look like, for example, '= EXPECTEDBALANCE' following a posting's
this example we assert the expected dollar balance in accounts a and b amount. Eg here we assert the expected dollar balance in accounts a and
after each posting: b after each posting:
2013/1/1 2013/1/1
a $1 =$1 a $1 =$1
@ -465,8 +465,8 @@ after each posting:
assertions and report an error if any of them fail. Balance assertions assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with while cleaning up old entries. You can disable them temporarily with
the '--ignore-assertions' flag, which can be useful for troubleshooting the '-I/--ignore-assertions' flag, which can be useful for
or for reading Ledger files. troubleshooting or for reading Ledger files.
* Menu: * Menu:
* Assertions and ordering:: * Assertions and ordering::
@ -533,10 +533,10 @@ This is how assertions work in Ledger also. We could call this a
To assert the balance of more than one commodity in an account, you To assert the balance of more than one commodity in an account, you
can write multiple postings, each asserting one commodity's balance. can write multiple postings, each asserting one commodity's balance.
You can make a stronger kind of balance assertion, by writing a You can make a stronger "total" balance assertion by writing a double
double equals sign ('==EXPECTEDBALANCE'). This "complete" balance equals sign ('== EXPECTEDBALANCE'). This asserts that there are no
assertion asserts the absence of other commodities (or, that their other unasserted commodities in the account (or, that their balance is
balance is 0, which to hledger is equivalent.) 0).
2013/1/1 2013/1/1
a $1 a $1
@ -591,22 +591,16 @@ File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions
1.9.6 Assertions and subaccounts 1.9.6 Assertions and subaccounts
-------------------------------- --------------------------------
Balance assertions do not count the balance from subaccounts; they check The balance assertions above ('=' and '==') do not count the balance
the posted account's exclusive balance. For example: from subaccounts; they check the account's exclusive balance only. You
can assert the balance including subaccounts by writing '=*' or '==*',
eg:
1/1 2019/1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 equity:opening balances
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 checking:a 5
equity checking:b 5
checking 1 ==* 11
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
 
File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions
@ -1619,81 +1613,81 @@ Node: Virtual Postings15032
Ref: #virtual-postings15191 Ref: #virtual-postings15191
Node: Balance Assertions16411 Node: Balance Assertions16411
Ref: #balance-assertions16586 Ref: #balance-assertions16586
Node: Assertions and ordering17537 Node: Assertions and ordering17544
Ref: #assertions-and-ordering17723 Ref: #assertions-and-ordering17730
Node: Assertions and included files18423 Node: Assertions and included files18430
Ref: #assertions-and-included-files18664 Ref: #assertions-and-included-files18671
Node: Assertions and multiple -f options18997 Node: Assertions and multiple -f options19004
Ref: #assertions-and-multiple--f-options19251 Ref: #assertions-and-multiple--f-options19258
Node: Assertions and commodities19383 Node: Assertions and commodities19390
Ref: #assertions-and-commodities19613 Ref: #assertions-and-commodities19620
Node: Assertions and prices20801 Node: Assertions and prices20776
Ref: #assertions-and-prices21013 Ref: #assertions-and-prices20988
Node: Assertions and subaccounts21453 Node: Assertions and subaccounts21428
Ref: #assertions-and-subaccounts21680 Ref: #assertions-and-subaccounts21655
Node: Assertions and virtual postings22201 Node: Assertions and virtual postings21979
Ref: #assertions-and-virtual-postings22441 Ref: #assertions-and-virtual-postings22219
Node: Assertions and precision22583 Node: Assertions and precision22361
Ref: #assertions-and-precision22774 Ref: #assertions-and-precision22552
Node: Balance Assignments23041 Node: Balance Assignments22819
Ref: #balance-assignments23222 Ref: #balance-assignments23000
Node: Balance assignments and prices24386 Node: Balance assignments and prices24164
Ref: #balance-assignments-and-prices24558 Ref: #balance-assignments-and-prices24336
Node: Transaction prices24782 Node: Transaction prices24560
Ref: #transaction-prices24951 Ref: #transaction-prices24729
Node: Comments27219 Node: Comments26997
Ref: #comments27353 Ref: #comments27131
Node: Tags28523 Node: Tags28301
Ref: #tags28641 Ref: #tags28419
Node: Directives30043 Node: Directives29821
Ref: #directives30186 Ref: #directives29964
Node: Comment blocks35793 Node: Comment blocks35571
Ref: #comment-blocks35938 Ref: #comment-blocks35716
Node: Including other files36114 Node: Including other files35892
Ref: #including-other-files36294 Ref: #including-other-files36072
Node: Default year36702 Node: Default year36480
Ref: #default-year36871 Ref: #default-year36649
Node: Declaring commodities37294 Node: Declaring commodities37072
Ref: #declaring-commodities37477 Ref: #declaring-commodities37255
Node: Default commodity38704 Node: Default commodity38482
Ref: #default-commodity38880 Ref: #default-commodity38658
Node: Market prices39516 Node: Market prices39294
Ref: #market-prices39681 Ref: #market-prices39459
Node: Declaring accounts40522 Node: Declaring accounts40300
Ref: #declaring-accounts40698 Ref: #declaring-accounts40476
Node: Account comments41623 Node: Account comments41401
Ref: #account-comments41786 Ref: #account-comments41564
Node: Account subdirectives42181 Node: Account subdirectives41959
Ref: #account-subdirectives42376 Ref: #account-subdirectives42154
Node: Account types42689 Node: Account types42467
Ref: #account-types42873 Ref: #account-types42651
Node: Account display order44517 Node: Account display order44295
Ref: #account-display-order44687 Ref: #account-display-order44465
Node: Rewriting accounts45816 Node: Rewriting accounts45594
Ref: #rewriting-accounts46001 Ref: #rewriting-accounts45779
Node: Basic aliases46735 Node: Basic aliases46513
Ref: #basic-aliases46881 Ref: #basic-aliases46659
Node: Regex aliases47585 Node: Regex aliases47363
Ref: #regex-aliases47756 Ref: #regex-aliases47534
Node: Multiple aliases48474 Node: Multiple aliases48252
Ref: #multiple-aliases48649 Ref: #multiple-aliases48427
Node: end aliases49147 Node: end aliases48925
Ref: #end-aliases49294 Ref: #end-aliases49072
Node: Default parent account49395 Node: Default parent account49173
Ref: #default-parent-account49561 Ref: #default-parent-account49339
Node: Periodic transactions50445 Node: Periodic transactions50223
Ref: #periodic-transactions50627 Ref: #periodic-transactions50405
Node: Two spaces after the period expression51752 Node: Two spaces after the period expression51530
Ref: #two-spaces-after-the-period-expression51997 Ref: #two-spaces-after-the-period-expression51775
Node: Forecasting with periodic transactions52482 Node: Forecasting with periodic transactions52260
Ref: #forecasting-with-periodic-transactions52772 Ref: #forecasting-with-periodic-transactions52550
Node: Budgeting with periodic transactions54459 Node: Budgeting with periodic transactions54237
Ref: #budgeting-with-periodic-transactions54698 Ref: #budgeting-with-periodic-transactions54476
Node: Transaction modifiers55157 Node: Transaction modifiers54935
Ref: #transaction-modifiers55320 Ref: #transaction-modifiers55098
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57304 Node: Auto postings and transaction balancing / inferred amounts / balance assertions57082
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57605 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57383
Node: EDITOR SUPPORT57983 Node: EDITOR SUPPORT57761
Ref: #editor-support58101 Ref: #editor-support57879
 
End Tag Table End Tag Table

407
hledger-lib/hledger_journal.txt
View File

@ -358,9 +358,9 @@ FILE FORMAT
Balance Assertions Balance Assertions
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in These look like, for example, = EXPECTEDBALANCE following a posting's
this example we assert the expected dollar balance in accounts a and b amount. Eg here we assert the expected dollar balance in accounts a
after each posting: and b after each posting:
2013/1/1 2013/1/1
a $1 =$1 a $1 =$1
@ -374,7 +374,7 @@ FILE FORMAT
and report an error if any of them fail. Balance assertions can pro- and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the cleaning up old entries. You can disable them temporarily with the
--ignore-assertions flag, which can be useful for troubleshooting or -I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files. for reading Ledger files.
Assertions and ordering Assertions and ordering
@ -412,10 +412,9 @@ FILE FORMAT
To assert the balance of more than one commodity in an account, you can To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance. write multiple postings, each asserting one commodity's balance.
You can make a stronger kind of balance assertion, by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (==EXPECTEDBALANCE). This "complete" balance assertion equals sign (== EXPECTEDBALANCE). This asserts that there are no other
asserts the absence of other commodities (or, that their balance is 0, unasserted commodities in the account (or, that their balance is 0).
which to hledger is equivalent.)
2013/1/1 2013/1/1
a $1 a $1
@ -433,7 +432,7 @@ FILE FORMAT
a 0 == $1 a 0 == $1
It's not yet possible to make a complete assertion about a balance that It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity has multiple commodities. One workaround is to isolate each commodity
into its own subaccount: into its own subaccount:
2013/1/1 2013/1/1
@ -447,51 +446,44 @@ FILE FORMAT
a:euro 0 == 1 a:euro 0 == 1
Assertions and prices Assertions and prices
Balance assertions ignore transaction prices, and should normally be Balance assertions ignore transaction prices, and should normally be
written without one: written without one:
2019/1/1 2019/1/1
(a) $1 @ 1 = $1 (a) $1 @ 1 = $1
We do allow prices to be written there, however, and print shows them, 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. even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign- generate balance assertions with prices), and because balance assign-
ments do use them (see below). ments do use them (see below).
Assertions and subaccounts Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they The balance assertions above (= and ==) do not count the balance from
check the posted account's exclusive balance. For example: subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg:
1/1 2019/1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 equity:opening balances
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 checking:a 5
equity checking:b 5
checking 1 ==* 11
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
Assertions and virtual postings Assertions and virtual postings
Balance assertions are checked against all postings, both real and vir- Balance assertions are checked against all postings, both real and vir-
tual. They are not affected by the --real/-R flag or real: query. tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision Assertions and precision
Balance assertions compare the exactly calculated amounts, which are Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser- limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts. tions. Balance assertion failure messages show exact amounts.
Balance Assignments Balance Assignments
Ledger-style balance assignments are also supported. These are like Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when the assertion. This can be a convenience during data entry, eg when
setting opening balances: setting opening balances:
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
@ -509,14 +501,14 @@ FILE FORMAT
expenses:misc expenses:misc
The calculated amount depends on the account's balance in the commodity The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign- commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little ment). Note that using balance assignments makes your journal a little
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 Balance assignments and prices
A transaction price in a balance assignment will cause the calculated A transaction price in a balance assignment will cause the calculated
amount to have that price attached: amount to have that price attached:
2019/1/1 2019/1/1
@ -528,9 +520,9 @@ FILE FORMAT
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.
@ -559,7 +551,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:
@ -570,8 +562,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:
@ -585,14 +577,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:
@ -616,24 +608,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:
@ -647,69 +639,70 @@ 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
@ -720,7 +713,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
@ -730,9 +723,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)
@ -740,37 +733,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
@ -790,8 +783,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
@ -801,8 +794,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
@ -814,19 +807,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
@ -841,9 +834,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:
@ -854,39 +847,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
@ -904,7 +897,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
@ -917,18 +910,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):
@ -939,8 +932,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
@ -950,7 +943,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
@ -961,8 +954,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:
@ -984,16 +977,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).
@ -1012,14 +1005,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
@ -1027,54 +1020,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
@ -1091,7 +1084,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
@ -1100,18 +1093,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
@ -1122,17 +1115,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:
@ -1145,66 +1138,66 @@ 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. They can be enabled by using automatically to certain transactions. They can be enabled by using
the --auto flag. Currently, just one kind of change is possible: the --auto flag. Currently, just one kind of change is possible:
adding extra postings. These rule-generated postings are known as adding extra postings. These rule-generated postings are known as
"automated postings" or "auto postings". "automated postings" or "auto postings".
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
@ -1212,20 +1205,20 @@ FILE FORMAT
ACCT [AMT] ACCT [AMT]
... ...
These posting rules look like normal postings, except the amount can These posting rules look 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.
@ -1265,28 +1258,28 @@ FILE FORMAT
Currently, transaction modifiers are applied / auto postings are added: Currently, transaction modifiers are applied / auto postings are added:
o after missing amounts are inferred, and transactions are checked for o after missing amounts are inferred, and transactions are checked for
balancedness, balancedness,
o but before balance assertions are checked. o but before balance assertions are checked.
Note this means that journal entries must be balanced both before and Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893 after auto postings are added. This changed in hledger 1.12+; see #893
for background. for background.
EDITOR SUPPORT EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa- others. See the [[Cookbook]] at hledger.org for the latest informa-
tion. tion.
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)
@ -1300,7 +1293,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)

163
hledger-web/hledger-web.1
View File

@ -41,54 +41,15 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, \f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
For more about this see hledger(1), hledger_journal(5) etc. For more about this see hledger(1), hledger_journal(5) etc.
.PP .SH OPTIONS
By default, hledger\-web starts the web app in "transient mode" and also
opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
With \f[C]\-\-serve\f[], it just runs the web app without exiting, and
logs requests to the console.
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[C]\-\-host\f[] to change this, eg
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
.PP
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
if you are running multiple hledger\-web instances.
.PP
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
80).
.PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static
files, eg for better caching or cookie\-less serving on high performance
websites.
.PP
Note there is no built\-in access control (aside from listening on
127.0.0.1 by default).
So you will need to hide hledger\-web behind an authenticating proxy
(such as apache or nginx) if you want to restrict who can see and add
entries to your journal.
.PP .PP
Command\-line options and arguments may be used to set an initial filter Command\-line options and arguments may be used to set an initial filter
on the data. on the data.
This is not shown in the web UI, but it will be applied in addition to These filter options are not shown in the web UI, but it will be applied
any search query entered there. in addition to any search query entered there.
.PP
With journal and timeclock files (but not CSV files, currently) the web
app detects changes made by other means and will show the new data on
the next request.
If a change makes the file unparseable, hledger\-web will show an error
until the file has been fixed.
.SH OPTIONS
.PP .PP
Note: if invoking hledger\-web as a hledger subcommand, write Note: if invoking hledger\-web as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above. \f[C]\-\-\f[] before options, as shown in the synopsis above.
.TP .TP
.B \f[C]\-\-serve\f[] .B \f[C]\-\-serve\f[]
serve and log requests, don\[aq]t browse or auto\-exit serve and log requests, don\[aq]t browse or auto\-exit
@ -119,6 +80,17 @@ serve them from another server for efficiency, you would set the url
with this. with this.
.RS .RS
.RE .RE
.TP
.B \f[C]\-\-capabilities=CAP[,CAP..]\f[]
enable the view, add, and/or manage capabilities (default: view,add)
.RS
.RE
.TP
.B \f[C]\-\-capabilities\-header=HTTPHEADER\f[]
read capabilities to enable from a HTTP header, like
X\-Sandstorm\-Permissions (default: disabled)
.RS
.RE
.PP .PP
hledger input options: hledger input options:
.TP .TP
@ -286,6 +258,111 @@ show debug output (levels 1\-9, default: 1)
A \@FILE argument will be expanded to the contents of FILE, which should A \@FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. contain one command line option/argument per line.
(To prevent this, insert a \f[C]\-\-\f[] argument before.) (To prevent this, insert a \f[C]\-\-\f[] argument before.)
.PP
By default, hledger\-web starts the web app in "transient mode" and also
opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
With \f[C]\-\-serve\f[], it just runs the web app without exiting, and
logs requests to the console.
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[C]\-\-host\f[] to change this, eg
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
.PP
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
if you are running multiple hledger\-web instances.
.PP
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
80).
.PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static
files, eg for better caching or cookie\-less serving on high performance
websites.
.SH PERMISSIONS
.PP
By default, hledger\-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
.PP
You can restrict who can reach it by
.IP \[bu] 2
setting the IP address it listens on (see \f[C]\-\-host\f[] above).
By default it listens on 127.0.0.1, accessible to all users on the local
machine.
.IP \[bu] 2
putting it behind an authenticating proxy, using eg apache or nginx
.IP \[bu] 2
custom firewall rules
.PP
You can restrict what the users who reach it can do, by
.IP \[bu] 2
using the \f[C]\-\-capabilities=CAP[,CAP..]\f[] flag when you start it,
enabling one or more of the following capabilities.
The default value is \f[C]view,add\f[]:
.RS 2
.IP \[bu] 2
\f[C]view\f[] \- allows viewing the journal file and all included files
.IP \[bu] 2
\f[C]add\f[] \- allows adding new transactions to the main journal file
.IP \[bu] 2
\f[C]manage\f[] \- allows editing, uploading or downloading the main or
included files
.RE
.IP \[bu] 2
using the \f[C]\-\-capabilities\-header=HTTPHEADER\f[] flag to specify a
HTTP header from which it will read capabilities to enable.
hledger\-web on Sandstorm uses the X\-Sandstorm\-Permissions header to
integrate with Sandstorm\[aq]s permissions.
This is disabled by default.
.SH EDITING, UPLOADING, DOWNLOADING
.PP
If you enable the \f[C]manage\f[] capability mentioned above, you\[aq]ll
see a new "spanner" button to the right of the search form.
Clicking this will let you edit, upload, or download the journal file or
any files it includes.
.PP
Note, unlike any other hledger command, in this mode you (or any
visitor) can alter or wipe the data files.
.PP
Normally whenever a file is changed in this way, hledger\-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger\-web is not aware of version control systems,
currently; if you use one, you\[aq]ll have to arrange to commit the
changes yourself (eg with a cron job or a file watcher like entr).
.PP
Changes which would leave the journal file(s) unparseable or non\-valid
(eg with failing balance assertions) are prevented.
(Probably.
This needs re\-testing.)
.SH RELOADING
.PP
hledger\-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger\-web), and it will show the new
data when you reload the page or navigate to a new page.
If a change makes a file unparseable, hledger\-web will display an error
message until the file has been fixed.
.SH JSON API
.PP
In addition to the web UI, hledger\-web provides some JSON API routes.
These are similar to the API provided by the hledger\-api tool, but it
may be convenient to have them in hledger\-web also.
.IP
.nf
\f[C]
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
\f[]
.fi
.SH ENVIRONMENT .SH ENVIRONMENT
.PP .PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with \f[B]LEDGER_FILE\f[] The journal file path when not specified with

183
hledger-web/hledger-web.info
View File

@ -25,56 +25,26 @@ journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps '$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), 'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc. hledger_journal(5) etc.
By default, hledger-web starts the web app in "transient mode" and
also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
0.0.0.0' to listen on all configured addresses.
Similarly, use '--port' to set a TCP port other than 5000, eg if you
are running multiple hledger-web instances.
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hyperlinks, useful eg for integrating hledger-web
within a larger website. The default is 'http://HOST:PORT/' using the
server's configured host address and TCP port (or 'http://HOST' if PORT
is 80).
With '--file-url' you can set a different base url for static files,
eg for better caching or cookie-less serving on high performance
websites.
Note there is no built-in access control (aside from listening on
127.0.0.1 by default). So you will need to hide hledger-web behind an
authenticating proxy (such as apache or nginx) if you want to restrict
who can see and add entries to your journal.
Command-line options and arguments may be used to set an initial
filter on the data. This is not shown in the web UI, but it will be
applied in addition to any search query entered there.
With journal and timeclock files (but not CSV files, currently) the
web app detects changes made by other means and will show the new data
on the next request. If a change makes the file unparseable,
hledger-web will show an error until the file has been fixed.
* Menu: * Menu:
* OPTIONS:: * OPTIONS::
* PERMISSIONS::
* EDITING UPLOADING DOWNLOADING::
* RELOADING::
* JSON API::
 
File: hledger-web.info, Node: OPTIONS, Prev: Top, Up: Top File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
1 OPTIONS 1 OPTIONS
********* *********
Note: if invoking hledger-web as a hledger subcommand, write '--' before Command-line options and arguments may be used to set an initial filter
options as shown above. on the data. These filter options are not shown in the web UI, but it
will be applied in addition to any search query entered there.
Note: if invoking hledger-web as a hledger subcommand, write '--'
before options, as shown in the synopsis above.
'--serve' '--serve'
@ -96,6 +66,14 @@ options as shown above.
normally serves static files itself, but if you wanted to serve normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url with them from another server for efficiency, you would set the url with
this. this.
'--capabilities=CAP[,CAP..]'
enable the view, add, and/or manage capabilities (default:
view,add)
'--capabilities-header=HTTPHEADER'
read capabilities to enable from a HTTP header, like
X-Sandstorm-Permissions (default: disabled)
hledger input options: hledger input options:
@ -209,10 +187,129 @@ the last one takes precedence.
should contain one command line option/argument per line. (To prevent should contain one command line option/argument per line. (To prevent
this, insert a '--' argument before.) this, insert a '--' argument before.)
By default, hledger-web starts the web app in "transient mode" and
also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
0.0.0.0' to listen on all configured addresses.
Similarly, use '--port' to set a TCP port other than 5000, eg if you
are running multiple hledger-web instances.
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hyperlinks, useful eg for integrating hledger-web
within a larger website. The default is 'http://HOST:PORT/' using the
server's configured host address and TCP port (or 'http://HOST' if PORT
is 80).
With '--file-url' you can set a different base url for static files,
eg for better caching or cookie-less serving on high performance
websites.

File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
2 PERMISSIONS
*************
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by
* setting the IP address it listens on (see '--host' above). By
default it listens on 127.0.0.1, accessible to all users on the
local machine.
* putting it behind an authenticating proxy, using eg apache or nginx
* custom firewall rules
You can restrict what the users who reach it can do, by
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
enabling one or more of the following capabilities. The default
value is 'view,add':
* 'view' - allows viewing the journal file and all included
files
* 'add' - allows adding new transactions to the main journal
file
* 'manage' - allows editing, uploading or downloading the main
or included files
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.

File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
3 EDITING, UPLOADING, DOWNLOADING
*********************************
If you enable the 'manage' capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it
includes.
Note, unlike any other hledger command, in this mode you (or any
visitor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems,
currently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or
non-valid (eg with failing balance assertions) are prevented.
(Probably. This needs re-testing.)

File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOADING DOWNLOADING, Up: Top
4 RELOADING
***********
hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new data
when you reload the page or navigate to a new page. If a change makes a
file unparseable, hledger-web will display an error message until the
file has been fixed.

File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top
5 JSON API
**********
In addition to the web UI, hledger-web provides some JSON API routes.
These are similar to the API provided by the hledger-api tool, but it
may be convenient to have them in hledger-web also.
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS3160 Node: OPTIONS1360
Ref: #options3245 Ref: #options1465
Node: PERMISSIONS6555
Ref: #permissions6694
Node: EDITING UPLOADING DOWNLOADING7906
Ref: #editing-uploading-downloading8087
Node: RELOADING8921
Ref: #reloading9055
Node: JSON API9365
Ref: #json-api9459
 
End Tag Table End Tag Table

180
hledger-web/hledger-web.txt
View File

@ -35,45 +35,13 @@ DESCRIPTION
C:/Users/USER/.hledger.journal). For more about this see hledger(1), C:/Users/USER/.hledger.journal). For more about this see hledger(1),
hledger_journal(5) etc. hledger_journal(5) etc.
By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg
--host 0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances.
You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites.
Note there is no built-in access control (aside from listening on
127.0.0.1 by default). So you will need to hide hledger-web behind an
authenticating proxy (such as apache or nginx) if you want to restrict
who can see and add entries to your journal.
Command-line options and arguments may be used to set an initial filter
on the data. This is not shown in the web UI, but it will be applied
in addition to any search query entered there.
With journal and timeclock files (but not CSV files, currently) the web
app detects changes made by other means and will show the new data on
the next request. If a change makes the file unparseable, hledger-web
will show an error until the file has been fixed.
OPTIONS OPTIONS
Note: if invoking hledger-web as a hledger subcommand, write -- before Command-line options and arguments may be used to set an initial filter
options as shown above. on the data. These filter options are not shown in the web UI, but it
will be applied in addition to any search query entered there.
Note: if invoking hledger-web as a hledger subcommand, write -- before
options, as shown in the synopsis above.
--serve --serve
serve and log requests, don't browse or auto-exit serve and log requests, don't browse or auto-exit
@ -85,16 +53,24 @@ OPTIONS
listen on this TCP port (default: 5000) listen on this TCP port (default: 5000)
--base-url=URL --base-url=URL
set the base url (default: http://IPADDR:PORT). You would set the base url (default: http://IPADDR:PORT). You would
change this when sharing over the network, or integrating within change this when sharing over the network, or integrating within
a larger website. a larger website.
--file-url=URL --file-url=URL
set the static files url (default: BASEURL/static). hledger-web set the static files url (default: BASEURL/static). hledger-web
normally serves static files itself, but if you wanted to serve normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url them from another server for efficiency, you would set the url
with this. with this.
--capabilities=CAP[,CAP..]
enable the view, add, and/or manage capabilities (default:
view,add)
--capabilities-header=HTTPHEADER
read capabilities to enable from a HTTP header, like X-Sand-
storm-Permissions (default: disabled)
hledger input options: hledger input options:
-f FILE --file=FILE -f FILE --file=FILE
@ -102,7 +78,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal) $LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE --rules-file=RULESFILE
Conversion rules file to use when reading CSV (default: Conversion rules file to use when reading CSV (default:
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
@ -143,11 +119,11 @@ OPTIONS
multiperiod/multicolumn report by year multiperiod/multicolumn report by year
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax (overrides the flags above)
--date2 --date2
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
effects) effects)
-U --unmarked -U --unmarked
@ -166,21 +142,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep hide/aggregate accounts or postings more than NUM levels deep
-E --empty -E --empty
show items with zero amount, normally hidden (and vice-versa in show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost at transaction time (using the convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
-V --value -V --value
convert amounts to their market value on the report end date convert amounts to their market value on the report end date
(using the most recent applicable market price, if any) (using the most recent applicable market price, if any)
--auto apply automated posting rules to modify transactions. --auto apply automated posting rules to modify transactions.
--forecast --forecast
apply periodic transaction rules to generate future transac- apply periodic transaction rules to generate future transac-
tions, to 6 months from now or report end date. tions, to 6 months from now or report end date.
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
@ -200,22 +176,114 @@ OPTIONS
show debug output (levels 1-9, default: 1) show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this, contain one command line option/argument per line. (To prevent this,
insert a -- argument before.) insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg
--host 0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances.
You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites.
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local
machine.
o putting it behind an authenticating proxy, using eg apache or nginx
o custom firewall rules
You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or
included files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it
includes.
Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message
until the file has been fixed.
JSON API
In addition to the web UI, hledger-web provides some JSON API routes.
These are similar to the API provided by the hledger-api tool, but it
may be convenient to have them in hledger-web also.
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
ENVIRONMENT ENVIRONMENT
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 options with -- when invoked from hledger is awk- The need to precede options with -- when invoked from hledger is awk-
ward. ward.
-f- doesn't work (hledger-web can't read from stdin). -f- doesn't work (hledger-web can't read from stdin).
@ -229,7 +297,7 @@ BUGS
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)
@ -243,7 +311,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)