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

doc: regenerate manuals, removing some smart typography

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-01-24 15:37:40 -08:00
parent eac15369f2
commit 67dde9d4ae
11 changed files with 1052 additions and 682 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
hledger-lib/hledger_csv.5
View File

@ -29,7 +29,7 @@ conversion rules file named \f[C]FILE.csv.rules\f[] in the same
directory. directory.
You can override this with the \f[C]\-\-rules\-file\f[] option. You can override this with the \f[C]\-\-rules\-file\f[] option.
If the rules file does not exist, hledger will auto\-create one with If the rules file does not exist, hledger will auto\-create one with
some example rules, which you'll need to adjust. some example rules, which you\[aq]ll need to adjust.
.PP .PP
At minimum, the rules file must identify the \f[C]date\f[] and At minimum, the rules file must identify the \f[C]date\f[] and
\f[C]amount\f[] fields. \f[C]amount\f[] fields.
@ -90,7 +90,7 @@ ignored.
\f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[] \f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[]
.PP .PP
Skip this number of CSV records at the beginning. Skip this number of CSV records at the beginning.
You'll need this whenever your CSV data contains header lines. You\[aq]ll need this whenever your CSV data contains header lines.
Eg: Eg:
.IP .IP
.nf .nf
@ -104,8 +104,8 @@ skip\ 1
\f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[] \f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[]
.PP .PP
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you'll need to specify \f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
the format. specify the format.
DATEFMT is a strptime\-like date parsing pattern, which must parse the DATEFMT is a strptime\-like date parsing pattern, which must parse the
date field values completely. date field values completely.
Examples: Examples:
@ -140,7 +140,7 @@ date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
.SS field list .SS field list
.PP .PP
\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[], \f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[],
\f[I]\f[CI]FIELDNAME2\f[I]\f[]\&... \f[I]\f[CI]FIELDNAME2\f[I]\f[]...
.PP .PP
This (a) names the CSV fields, in order (names may not contain This (a) names the CSV fields, in order (names may not contain
whitespace; uninteresting names may be left blank), and (b) assigns them whitespace; uninteresting names may be left blank), and (b) assigns them
@ -192,7 +192,7 @@ Field assignments can be used instead of or in addition to a field list.
.PD 0 .PD 0
.P .P
.PD .PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... \ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]...
.PP .PP
\f[C]if\f[] \f[C]if\f[]
.PD 0 .PD 0
@ -202,16 +202,16 @@ Field assignments can be used instead of or in addition to a field list.
.PD 0 .PD 0
.P .P
.PD .PD
\f[I]\f[CI]PATTERN\f[I]\f[]\&... \f[I]\f[CI]PATTERN\f[I]\f[]...
.PD 0 .PD 0
.P .P
.PD .PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... \ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]...
.PP .PP
This applies one or more field assignments, only to those CSV records This applies one or more field assignments, only to those CSV records
matched by one of the PATTERNs. matched by one of the PATTERNs.
The patterns are case\-insensitive regular expressions which match The patterns are case\-insensitive regular expressions which match
anywhere within the whole CSV record (it's not yet possible to match anywhere within the whole CSV record (it\[aq]s not yet possible to match
within a specific field). within a specific field).
When there are multiple patterns they can be written on separate lines, When there are multiple patterns they can be written on separate lines,
unindented. unindented.
@ -244,7 +244,7 @@ banking\ thru\ software
.PP .PP
Include another rules file at this point. Include another rules file at this point.
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to \f[C]RULESFILE\f[] is either an absolute file path or a path relative to
the current file's directory. the current file\[aq]s directory.
Eg: Eg:
.IP .IP
.nf .nf
@ -261,9 +261,9 @@ Consider adding this rule if all of the following are true: you might be
processing just one day of data, your CSV records are in reverse processing just one day of data, your CSV records are in reverse
chronological order (newest first), and you care about preserving the chronological order (newest first), and you care about preserving the
order of same\-day transactions. order of same\-day transactions.
It usually isn't needed, because hledger autodetects the CSV order, but It usually isn\[aq]t needed, because hledger autodetects the CSV order,
when all CSV records have the same date it will assume they are oldest but when all CSV records have the same date it will assume they are
first. oldest first.
.SH CSV TIPS .SH CSV TIPS
.SS CSV ordering .SS CSV ordering
.PP .PP
@ -274,8 +274,9 @@ case where you might need \f[C]newest\-first\f[], see above).
.PP .PP
Each journal entry will have two postings, to \f[C]account1\f[] and Each journal entry will have two postings, to \f[C]account1\f[] and
\f[C]account2\f[] respectively. \f[C]account2\f[] respectively.
It's not yet possible to generate entries with more than two postings. It\[aq]s not yet possible to generate entries with more than two
It's conventional and recommended to use \f[C]account1\f[] for the postings.
It\[aq]s conventional and recommended to use \f[C]account1\f[] for the
account whose CSV we are reading. account whose CSV we are reading.
.SS CSV amounts .SS CSV amounts
.PP .PP

204
hledger-lib/hledger_journal.5
View File

@ -6,29 +6,31 @@
.SH NAME .SH NAME
.PP .PP
Journal \- hledger's default file format, representing a General Journal Journal \- hledger\[aq]s default file format, representing a General
Journal
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
hledger's usual data source is a plain text file containing journal hledger\[aq]s usual data source is a plain text file containing journal
entries in hledger journal format. entries in hledger journal format.
This file represents a standard accounting general journal. This file represents a standard accounting general journal.
I use file names ending in \f[C]\&.journal\f[], but that's not required. I use file names ending in \f[C]\&.journal\f[], but that\[aq]s not
required.
The journal file contains a number of transaction entries, each The journal file contains a number of transaction entries, each
describing a transfer of money (or any commodity) between two or more describing a transfer of money (or any commodity) between two or more
named accounts, in a simple format readable by both hledger and humans. named accounts, in a simple format readable by both hledger and humans.
.PP .PP
hledger's journal format is a compatible subset, mostly, of ledger's hledger\[aq]s journal format is a compatible subset, mostly, of
journal format, so hledger can work with compatible ledger journal files ledger\[aq]s journal format, so hledger can work with compatible ledger
as well. journal files as well.
It's safe, and encouraged, to run both hledger and ledger on the same It\[aq]s safe, and encouraged, to run both hledger and ledger on the
journal file, eg to validate the results you're getting. same journal file, eg to validate the results you\[aq]re getting.
.PP .PP
You can use hledger without learning any more about this file; just use You can use hledger without learning any more about this file; just use
the add or web commands to create and update it. the add or web commands to create and update it.
Many users, though, also edit the journal file directly with a text Many users, though, also edit the journal file directly with a text
editor, perhaps assisted by the helper modes for emacs or vim. editor, perhaps assisted by the helper modes for emacs or vim.
.PP .PP
Here's an example: Here\[aq]s an example:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -81,7 +83,7 @@ line or a semicolon)
semicolon until end of line) semicolon until end of line)
.PP .PP
Then comes zero or more (but usually at least 2) indented lines Then comes zero or more (but usually at least 2) indented lines
representing\&... representing...
.SS Postings .SS Postings
.PP .PP
A posting is an addition of some amount to, or removal of some amount A posting is an addition of some amount to, or removal of some amount
@ -134,12 +136,12 @@ The primary date, on the left, is used by default; the secondary date,
on the right, is used when the \f[C]\-\-date2\f[] flag is specified on the right, is used when the \f[C]\-\-date2\f[] flag is specified
(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work). (\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work).
.PP .PP
The meaning of secondary dates is up to you, but it's best to follow a The meaning of secondary dates is up to you, but it\[aq]s best to follow
consistent rule. a consistent rule.
Eg write the bank's clearing date as primary, and when needed, the date Eg write the bank\[aq]s clearing date as primary, and when needed, the
the transaction was initiated as secondary. date the transaction was initiated as secondary.
.PP .PP
Here's an example. Here\[aq]s an example.
Note that a secondary date will use the year of the primary date if Note that a secondary date will use the year of the primary date if
unspecified. unspecified.
.IP .IP
@ -203,14 +205,14 @@ $\ hledger\ \-f\ t.j\ register\ checking
.fi .fi
.PP .PP
DATE should be a simple date; if the year is not specified it will use DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. the year of the transaction\[aq]s date.
You can set the secondary date similarly, with \f[C]date2:DATE2\f[]. You can set the secondary date similarly, with \f[C]date2:DATE2\f[].
The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date
value if they are present, eg a \f[C]date:\f[] tag with no value is not value if they are present, eg a \f[C]date:\f[] tag with no value is not
allowed. allowed.
.PP .PP
Ledger's earlier, more compact bracketed date syntax is also supported: Ledger\[aq]s earlier, more compact bracketed date syntax is also
\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]. supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
hledger will attempt to parse any square\-bracketed sequence of the hledger will attempt to parse any square\-bracketed sequence of the
\f[C]0123456789/\-.=\f[] characters in this way. \f[C]0123456789/\-.=\f[] characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2 With this syntax, DATE infers its year from the transaction and DATE2
@ -254,11 +256,11 @@ When reporting, you can filter by status with the
\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in \f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in
hledger\-ui. hledger\-ui.
.PP .PP
Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq] Note, in Ledger and in older versions of hledger, the "unmarked" state
state is called \[lq]uncleared\[rq]. is called "uncleared".
As of hledger 1.3 we have renamed it to unmarked for clarity. As of hledger 1.3 we have renamed it to unmarked for clarity.
.PP .PP
To replicate Ledger and old hledger's behaviour of also matching To replicate Ledger and old hledger\[aq]s behaviour of also matching
pending, combine \-U and \-P. pending, combine \-U and \-P.
.PP .PP
Status marks are optional, but can be helpful eg for reconciling with Status marks are optional, but can be helpful eg for reconciling with
@ -268,9 +270,8 @@ status.
Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c
C\-e, or posting status with C\-c C\-c. C\-e, or posting status with C\-c C\-c.
.PP .PP
What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq] What "uncleared", "pending", and "cleared" actually mean is up to you.
actually mean is up to you. Here\[aq]s one suggestion:
Here's one suggestion:
.PP .PP
.TS .TS
tab(@); tab(@);
@ -304,10 +305,10 @@ bank soon (like uncashed checks), and no flags to see the most
up\-to\-date state of your finances. up\-to\-date state of your finances.
.SS Description .SS Description
.PP .PP
A transaction's description is the rest of the line following the date A transaction\[aq]s description is the rest of the line following the
and status mark (or until a comment begins). date and status mark (or until a comment begins).
Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it Sometimes called the "narration" in traditional bookkeeping, it can be
can be used for whatever you wish, or left blank. used for whatever you wish, or left blank.
Transaction descriptions can be queried, unlike comments. Transaction descriptions can be queried, unlike comments.
.SS Payee and note .SS Payee and note
.PP .PP
@ -380,8 +381,8 @@ Some examples:
.PP .PP
As you can see, the amount format is somewhat flexible: As you can see, the amount format is somewhat flexible:
.IP \[bu] 2 .IP \[bu] 2
amounts are a number (the \[lq]quantity\[rq]) and optionally a currency amounts are a number (the "quantity") and optionally a currency
symbol/commodity name (the \[lq]commodity\[rq]). symbol/commodity name (the "commodity").
.IP \[bu] 2 .IP \[bu] 2
the commodity is a symbol, word, or phrase, on the left or right, with the commodity is a symbol, word, or phrase, on the left or right, with
or without a separating space. or without a separating space.
@ -400,8 +401,8 @@ from digit groups separator
.IP \[bu] 2 .IP \[bu] 2
scientific E\-notation is allowed. scientific E\-notation is allowed.
Be careful not to use a digit group separator character in scientific Be careful not to use a digit group separator character in scientific
notation, as it's not supported and it might get mistaken for a decimal notation, as it\[aq]s not supported and it might get mistaken for a
point. decimal point.
(Declaring the digit group separator character explicitly with a (Declaring the digit group separator character explicitly with a
commodity directive will prevent this.) commodity directive will prevent this.)
.PP .PP
@ -439,13 +440,13 @@ will be the maximum from all posting amounts in that commmodity
or if there are no such amounts in the journal, a default format is used or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[]). (like \f[C]$1000.00\f[]).
.PP .PP
Price amounts and amounts in \f[C]D\f[] directives usually don't affect Price amounts and amounts in \f[C]D\f[] directives usually don\[aq]t
amount format inference, but in some situations they can do so affect amount format inference, but in some situations they can do so
indirectly. indirectly.
(Eg when D's default commodity is applied to a commodity\-less amount, (Eg when D\[aq]s default commodity is applied to a commodity\-less
or when an amountless posting is balanced using a price's commodity, or amount, or when an amountless posting is balanced using a price\[aq]s
when \-V is used.) If you find this causing problems, set the desired commodity, or when \-V is used.) If you find this causing problems, set
format with a commodity directive. the desired format with a commodity directive.
.SS Virtual Postings .SS Virtual Postings
.PP .PP
When you parenthesise the account name in a posting, we call that a When you parenthesise the account name in a posting, we call that a
@ -456,7 +457,7 @@ it is ignored when checking that the transaction is balanced
it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used, it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used,
or the \f[C]real:1\f[] query. or the \f[C]real:1\f[] query.
.PP .PP
You could use this, eg, to set an account's opening balance without You could use this, eg, to set an account\[aq]s opening balance without
needing to use the \f[C]equity:opening\ balances\f[] account: needing to use the \f[C]equity:opening\ balances\f[] account:
.IP .IP
.nf .nf
@ -490,7 +491,8 @@ 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's amount. These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
amount.
Eg in this example we assert the expected dollar balance in accounts a Eg in this example we assert the expected dollar balance in accounts a
and b after each posting: and b after each posting:
.IP .IP
@ -515,7 +517,7 @@ You can disable them temporarily with the
troubleshooting or for reading Ledger files. troubleshooting or for reading Ledger files.
.SS Assertions and ordering .SS Assertions and ordering
.PP .PP
hledger sorts an account's postings and assertions first by date and hledger sorts an account\[aq]s postings and assertions first by date and
then (for postings on the same day) by parse order. then (for postings on the same day) by parse order.
Note this is different from Ledger, which sorts assertions only by parse Note this is different from Ledger, which sorts assertions only by parse
order. order.
@ -534,31 +536,31 @@ intra\-day balances.
With included files, things are a little more complicated. With included files, things are a little more complicated.
Including preserves the ordering of postings and assertions. Including preserves the ordering of postings and assertions.
If you have multiple postings to an account on the same day, split If you have multiple postings to an account on the same day, split
across different files, and you also want to assert the account's across different files, and you also want to assert the account\[aq]s
balance on the same day, you'll have to put the assertion in the right balance on the same day, you\[aq]ll have to put the assertion in the
file. right file.
.SS Assertions and multiple \-f options .SS Assertions and multiple \-f options
.PP .PP
Balance assertions don't work well across files specified with multiple Balance assertions don\[aq]t work well across files specified with
\-f options. multiple \-f options.
Use include or concatenate the files instead. Use include or concatenate the files instead.
.SS Assertions and commodities .SS Assertions and commodities
.PP .PP
The asserted balance must be a simple single\-commodity amount, and in The asserted balance must be a simple single\-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity\[aq]s balance within the
(possibly multi\-commodity) account balance. (possibly multi\-commodity) account balance.
.PD 0 .PD 0
.P .P
.PD .PD
This is how assertions work in Ledger also. This is how assertions work in Ledger also.
We could call this a \[lq]partial\[rq] balance assertion. We could call this a "partial" balance assertion.
.PP .PP
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\[aq]s balance.
.PP .PP
You can make a stronger kind of balance assertion, by writing a double You can make a stronger kind of balance assertion, by writing a double
equals sign (\f[C]==EXPECTEDBALANCE\f[]). equals sign (\f[C]==EXPECTEDBALANCE\f[]).
This \[lq]complete\[rq] balance assertion asserts the absence of other This "complete" balance assertion asserts the absence of other
commodities (or, that their balance is 0, which to hledger is commodities (or, that their balance is 0, which to hledger is
equivalent.) equivalent.)
.IP .IP
@ -581,8 +583,8 @@ equivalent.)
\f[] \f[]
.fi .fi
.PP .PP
It's not yet possible to make a complete assertion about a balance that It\[aq]s not yet possible to make a complete assertion about a balance
has multiple commodities. that has multiple commodities.
One workaround is to isolate each commodity into its own subaccount: One workaround is to isolate each commodity into its own subaccount:
.IP .IP
.nf .nf
@ -605,7 +607,7 @@ the meaning of that would be unclear.
.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
the posted account's exclusive balance. the posted account\[aq]s exclusive balance.
For example: For example:
.IP .IP
.nf .nf
@ -617,7 +619,7 @@ For example:
\f[] \f[]
.fi .fi
.PP .PP
The balance report's flat mode shows these exclusive balances more The balance report\[aq]s flat mode shows these exclusive balances more
clearly: clearly:
.IP .IP
.nf .nf
@ -673,16 +675,16 @@ or when adjusting a balance to reality:
\f[] \f[]
.fi .fi
.PP .PP
The calculated amount depends on the account's balance in the commodity The calculated amount depends on the account\[aq]s balance in the
at that point (which depends on the previously\-dated postings of the commodity at that point (which depends on the previously\-dated postings
commodity to that account since the last balance assertion or of the commodity to that account since the last balance assertion or
assignment). 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 Transaction prices .SS Transaction prices
.PP .PP
Within a transaction, you can note an amount's price in another Within a transaction, you can note an amount\[aq]s price in another
commodity. commodity.
This can be used to document the cost (in a purchase) or selling price This can be used to document the cost (in a purchase) or selling price
(in a sale). (in a sale).
@ -736,8 +738,8 @@ hledger infer the price that balances the transaction:
\f[C]{=UNITPRICE}\f[], which hledger currently ignores). \f[C]{=UNITPRICE}\f[], which hledger currently ignores).
.PP .PP
Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their
transaction price's commodity, if any. transaction price\[aq]s commodity, if any.
(mnemonic: \[lq]B\[rq] is from \[lq]cost Basis\[rq], as in Ledger). (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:
.IP .IP
.nf .nf
@ -754,7 +756,7 @@ $\ hledger\ bal\ \-N\ \-\-flat\ \-B
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. amount.
So if example 3's postings are reversed, while the transaction is So if example 3\[aq]s postings are reversed, while the transaction is
equivalent, \-B shows something different: equivalent, \-B shows something different:
.IP .IP
.nf .nf
@ -837,7 +839,8 @@ comma or end of line, with leading/trailing whitespace removed:
\f[] \f[]
.fi .fi
.PP .PP
Note this means hledger's tag values can not contain commas or newlines. Note this means hledger\[aq]s tag values can not contain commas or
newlines.
Ending at commas means you can write multiple short tags on one line, Ending at commas means you can write multiple short tags on one line,
comma separated: comma separated:
.IP .IP
@ -849,13 +852,12 @@ comma separated:
.PP .PP
Here, Here,
.IP \[bu] 2 .IP \[bu] 2
\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a "\f[C]a\ comment\ containing\f[]" is just comment text, not a tag
tag
.IP \[bu] 2 .IP \[bu] 2
\[lq]\f[C]tag1\f[]\[rq] is a tag with no value "\f[C]tag1\f[]" is a tag with no value
.IP \[bu] 2 .IP \[bu] 2
\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is "\f[C]tag2\f[]" is another tag, whose value is
\[lq]\f[C]some\ value\ ...\f[]\[rq] "\f[C]some\ value\ ...\f[]"
.PP .PP
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.
@ -871,18 +873,19 @@ For example, the following transaction has three tags (\f[C]A\f[],
\f[] \f[]
.fi .fi
.PP .PP
Tags are like Ledger's metadata feature, except hledger's tag values are Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
simple strings. values are simple strings.
.SS Directives .SS Directives
.PP .PP
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. that influences how the journal is processed.
hledger's directives are based on a subset of Ledger's, but there are hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but
many differences (and also some differences between hledger versions). there are many differences (and also some differences between hledger
versions).
.PP .PP
Directives' behaviour and interactions can get a little bit complex, so Directives\[aq] behaviour and interactions can get a little bit complex,
here is a table summarising the directives and their effects, with links so here is a table summarising the directives and their effects, with
to more detailed docs. links to more detailed docs.
.PP .PP
.TS .TS
tab(@); tab(@);
@ -1064,8 +1067,8 @@ The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files. It can include journal, timeclock or timedot files, but not CSV files.
.SS Default year .SS Default year
.PP .PP
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
specify a year. don\[aq]t specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year. This is a line beginning with \f[C]Y\f[] followed by the year.
Eg: Eg:
.IP .IP
@ -1105,7 +1108,7 @@ commodity\ 1,000.0000\ AAAA
\f[] \f[]
.fi .fi
.PP .PP
or on multiple lines, using the \[lq]format\[rq] subdirective. or on multiple lines, using the "format" subdirective.
In this case the commodity symbol appears twice and should be the same In this case the commodity symbol appears twice and should be the same
in both places: in both places:
.IP .IP
@ -1134,7 +1137,7 @@ digits).
.PP .PP
The \f[C]D\f[] directive sets a default commodity (and display format), The \f[C]D\f[] directive sets a default commodity (and display format),
to be used for amounts without a commodity symbol (ie, plain numbers). to be used for amounts without a commodity symbol (ie, plain numbers).
(Note this differs from Ledger's default commodity directive.) The (Note this differs from Ledger\[aq]s default commodity directive.) The
commodity and display format will be applied to all subsequent commodity and display format will be applied to all subsequent
commodity\-less amounts, or until the next \f[C]D\f[] directive. commodity\-less amounts, or until the next \f[C]D\f[] directive.
.IP .IP
@ -1156,9 +1159,9 @@ written with a decimal point.
.PP .PP
The \f[C]P\f[] directive declares a market price, which is an exchange The \f[C]P\f[] directive declares a market price, which is an exchange
rate between two commodities on a certain date. rate between two commodities on a certain date.
(In Ledger, they are called \[lq]historical prices\[rq].) These are (In Ledger, they are called "historical prices".) These are often
often obtained from a stock exchange, cryptocurrency exchange, or the obtained from a stock exchange, cryptocurrency exchange, or the foreign
foreign exchange market. exchange market.
.PP .PP
Here is the format: Here is the format:
.IP .IP
@ -1198,7 +1201,7 @@ reference.
They can store extra information about accounts (account numbers, notes, They can store extra information about accounts (account numbers, notes,
etc.) etc.)
.IP \[bu] 2 .IP \[bu] 2
They can help hledger know your accounts' types (asset, liability, They can help hledger know your accounts\[aq] types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and equity, revenue, expense), useful for reports like balancesheet and
incomestatement. incomestatement.
.IP \[bu] 2 .IP \[bu] 2
@ -1268,7 +1271,7 @@ If you name your top\-level accounts with some variation of
detected automatically. detected automatically.
.SS Account types declared with tags .SS Account types declared with tags
.PP .PP
More generally, you can declare an account's type with an account More generally, you can declare an account\[aq]s type with an account
directive, by writing a \f[C]type:\f[] tag in a comment, followed by one directive, by writing a \f[C]type:\f[] tag in a comment, followed by one
of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[], of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[],
\f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[] \f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[]
@ -1332,7 +1335,7 @@ account\ expenses
\f[] \f[]
.fi .fi
.PP .PP
you'll see those accounts displayed in declaration order, not you\[aq]ll see those accounts displayed in declaration order, not
alphabetically: alphabetically:
.IP .IP
.nf .nf
@ -1358,13 +1361,14 @@ account\ other:zoo
\f[] \f[]
.fi .fi
.PP .PP
would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s would influence the position of \f[C]zoo\f[] among \f[C]other\f[]\[aq]s
subaccounts, but not the position of \f[C]other\f[] among the top\-level subaccounts, but not the position of \f[C]other\f[] among the top\-level
accounts. accounts.
This means: \- you will sometimes declare parent accounts (eg This means: \- you will sometimes declare parent accounts (eg
\f[C]account\ other\f[] above) that you don't intend to post to, just to \f[C]account\ other\f[] above) that you don\[aq]t intend to post to,
customize their display order \- sibling accounts stay together (you just to customize their display order \- sibling accounts stay together
couldn't display \f[C]x:y\f[] in between \f[C]a:b\f[] and \f[C]a:c\f[]). (you couldn\[aq]t display \f[C]x:y\f[] in between \f[C]a:b\f[] and
\f[C]a:c\f[]).
.SS Rewriting accounts .SS Rewriting accounts
.PP .PP
You can define account alias rules which rewrite your account names, or You can define account alias rules which rewrite your account names, or
@ -1403,7 +1407,7 @@ alias\ OLD\ =\ NEW
Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the
command line. command line.
This affects all entries. This affects all entries.
It's useful for trying out aliases interactively. It\[aq]s useful for trying out aliases interactively.
.PP .PP
OLD and NEW are case sensitive full account names. OLD and NEW are case sensitive full account names.
hledger will replace any occurrence of the old account name with the new hledger will replace any occurrence of the old account name with the new
@ -1549,8 +1553,8 @@ Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
.PP .PP
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). expression can work (useful or not).
They will be relative to today's date, unless a Y default year directive They will be relative to today\[aq]s date, unless a Y default year
is in effect, in which case they will be relative to Y/1/1. directive is in effect, in which case they will be relative to Y/1/1.
.SS Two spaces after the period expression .SS Two spaces after the period expression
.PP .PP
If the period expression is followed by a transaction description, these If the period expression is followed by a transaction description, these
@ -1593,9 +1597,9 @@ journal, or today if there are no normal transactions.
ends on the report end date if specified with \-e/\-p/date:, or 180 days ends on the report end date if specified with \-e/\-p/date:, or 180 days
from today. from today.
.PP .PP
where \[lq]today\[rq] means the current date at report time. where "today" means the current date at report time.
The \[lq]later of\[rq] rule ensures that forecast transactions do not The "later of" rule ensures that forecast transactions do not overlap
overlap normal transactions in time; they will begin only after normal normal transactions in time; they will begin only after normal
transactions end. transactions end.
.PP .PP
Forecasting can be useful for estimating balances into the future, and Forecasting can be useful for estimating balances into the future, and
@ -1627,14 +1631,14 @@ and Forecasting.
.PP .PP
Transaction modifier rules describe changes that should be applied Transaction modifier rules describe changes that should be applied
automatically to certain transactions. automatically to certain transactions.
Currently, this means adding extra postings (also known as Currently, this means adding extra postings (also known as "automated
\[lq]automated postings\[rq]). postings").
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
.PP .PP
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 matches except the first line is an equals sign followed by a query that matches
certain postings (mnemonic: \f[C]=\f[] suggests matching). certain postings (mnemonic: \f[C]=\f[] suggests matching).
And each \[lq]posting\[rq] is actually a posting\-generating rule: And each "posting" is actually a posting\-generating rule:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1656,13 +1660,13 @@ The commodity symbol (if any) from the matched posting will be added to
this. this.
.IP \[bu] 2 .IP \[bu] 2
a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N). a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N).
The matched posting's amount (and total price, if any) will be The matched posting\[aq]s amount (and total price, if any) will be
multiplied by N. multiplied by N.
.IP \[bu] 2 .IP \[bu] 2
a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N, a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N,
and symbol S). and symbol S).
The matched posting's amount will be multiplied by N, and its commodity The matched posting\[aq]s amount will be multiplied by N, and its
symbol will be replaced with S. commodity symbol will be replaced with S.
.PP .PP
Some examples: Some examples:
.IP .IP

6
hledger-lib/hledger_timeclock.5
View File

@ -9,7 +9,7 @@ Timeclock \- the time logging format of timeclock.el, as read by hledger
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
hledger can read timeclock files. hledger can read timeclock files.
As with Ledger, these are (a subset of) timeclock.el's format, As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
containing clock\-in and clock\-out entries as in the example below. containing clock\-in and clock\-out entries as in the example below.
The date is a simple date. The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ]. The time format is HH:MM[:SS][+\-ZZZZ].
@ -67,8 +67,8 @@ at the command line, use these bash aliases:
.IP \[bu] 2 .IP \[bu] 2
or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x
repository. repository.
These rely on a \[lq]timeclock\[rq] executable which I think is just the These rely on a "timeclock" executable which I think is just the ledger
ledger 2 executable renamed. 2 executable renamed.
.SH "REPORTING BUGS" .SH "REPORTING BUGS"

12
hledger-lib/hledger_timedot.5
View File

@ -5,7 +5,7 @@
.SH NAME .SH NAME
.PP .PP
Timedot \- hledger's human\-friendly time logging format Timedot \- hledger\[aq]s human\-friendly time logging format
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
Timedot is a plain text format for logging dated, categorised quantities Timedot is a plain text format for logging dated, categorised quantities
@ -16,10 +16,10 @@ precise or too interruptive.
It can be formatted like a bar chart, making clear at a glance where It can be formatted like a bar chart, making clear at a glance where
time was spent. time was spent.
.PP .PP
Though called \[lq]timedot\[rq], this format is read by hledger as Though called "timedot", this format is read by hledger as commodityless
commodityless quantities, so it could be used to represent dated quantities, so it could be used to represent dated quantities other than
quantities other than time. time.
In the docs below we'll assume it's time. In the docs below we\[aq]ll assume it\[aq]s time.
.SH FILE FORMAT .SH FILE FORMAT
.PP .PP
A timedot file contains a series of day entries. A timedot file contains a series of day entries.
@ -34,7 +34,7 @@ Quantities can be written as:
.IP \[bu] 2 .IP \[bu] 2
a sequence of dots (.) representing quarter hours. a sequence of dots (.) representing quarter hours.
Spaces may optionally be used for grouping and readability. Spaces may optionally be used for grouping and readability.
Eg: \&.... Eg: ....
\&.. \&..
.IP \[bu] 2 .IP \[bu] 2
an integral or decimal number, representing hours. an integral or decimal number, representing hours.

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

@ -20,17 +20,17 @@ other commodity, using double\-entry accounting and a simple, editable
file format. file format.
hledger is inspired by and largely compatible with ledger(1). hledger is inspired by and largely compatible with ledger(1).
.PP .PP
hledger\-ui is hledger's curses\-style interface, providing an efficient hledger\-ui is hledger\[aq]s curses\-style interface, providing an
full\-window text UI for viewing accounts and transactions, and some efficient full\-window text UI for viewing accounts and transactions,
limited data entry capability. and some limited data entry capability.
It is easier than hledger's command\-line interface, and sometimes It is easier than hledger\[aq]s command\-line interface, and sometimes
quicker and more convenient than the web interface. quicker and more convenient than the web interface.
.PP .PP
Note hledger\-ui has some different defaults: \- it generates Note hledger\-ui has some different defaults: \- it generates
rule\-based transactions and postings by default (\[en]forecast and rule\-based transactions and postings by default (\-\-forecast and
\[en]auto are always on). \-\-auto are always on).
\- it hides transactions dated in the future by default (change this \- it hides transactions dated in the future by default (change this
with \[en]future or the F key). with \-\-future or the F key).
Experimental. Experimental.
.PP .PP
Like hledger, it reads data from one or more files in hledger journal, Like hledger, it reads data from one or more files in hledger journal,
@ -57,7 +57,7 @@ use this custom display theme
.RE .RE
.TP .TP
.B \f[C]\-\-register=ACCTREGEX\f[] .B \f[C]\-\-register=ACCTREGEX\f[]
start in the (first) matched account's register screen start in the (first) matched account\[aq]s register screen
.RS .RS
.RE .RE
.TP .TP
@ -96,7 +96,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules)
.RE .RE
.TP .TP
.B \f[C]\-\-separator=CHAR\f[] .B \f[C]\-\-separator=CHAR\f[]
Field separator to expect when reading CSV (default: `,') Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS .RS
.RE .RE
.TP .TP
@ -264,7 +264,7 @@ Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style
movement keys are also supported. movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, to move A tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it. faster you may want to adjust it.
(If you're on a mac, the Karabiner app is one way to do that.) (If you\[aq]re on a mac, the Karabiner app is one way to do that.)
.PP .PP
With shift pressed, the cursor keys adjust the report period, limiting With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown). the transactions to be shown (by default, all are shown).
@ -272,9 +272,9 @@ the transactions to be shown (by default, all are shown).
report period durations: year, quarter, month, week, day. report period durations: year, quarter, month, week, day.
Then, \f[C]shift\-left/right\f[] moves to the previous/next period. Then, \f[C]shift\-left/right\f[] moves to the previous/next period.
\f[C]t\f[] sets the report period to today. \f[C]t\f[] sets the report period to today.
With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq] With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the
period (the current day, week, month, quarter, or year), the period will current day, week, month, quarter, or year), the period will move
move automatically to track the current date. automatically to track the current date.
To set a non\-standard period, you can use \f[C]/\f[] and a To set a non\-standard period, you can use \f[C]/\f[] and a
\f[C]date:\f[] query. \f[C]date:\f[] query.
.PP .PP
@ -299,8 +299,8 @@ convenient.
Or, it cancels a minibuffer edit or help dialog in progress. Or, it cancels a minibuffer edit or help dialog in progress.
.PP .PP
\f[C]CTRL\-l\f[] redraws the screen and centers the selection if \f[C]CTRL\-l\f[] redraws the screen and centers the selection if
possible (selections near the top won't be centered, since we don't possible (selections near the top won\[aq]t be centered, since we
scroll above the top). don\[aq]t scroll above the top).
.PP .PP
\f[C]g\f[] reloads from the data file(s) and updates the current screen \f[C]g\f[] reloads from the data file(s) and updates the current screen
and any previous screens. and any previous screens.
@ -310,7 +310,7 @@ and any previous screens.
Disabling balance assertions temporarily can be useful for Disabling balance assertions temporarily can be useful for
troubleshooting. troubleshooting.
.PP .PP
\f[C]a\f[] runs command\-line hledger's add command, and reloads the \f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the
updated file. updated file.
This allows some basic data entry. This allows some basic data entry.
.PP .PP
@ -333,7 +333,8 @@ Additional screen\-specific keys are described below.
.SS Accounts screen .SS Accounts screen
.PP .PP
This is normally the first screen displayed. This is normally the first screen displayed.
It lists accounts and their balances, like hledger's balance command. It lists accounts and their balances, like hledger\[aq]s balance
command.
By default, it shows all accounts and their latest ending balances By default, it shows all accounts and their latest ending balances
(including the balances of subaccounts). (including the balances of subaccounts).
if you specify a query on the command line, it shows just the matched if you specify a query on the command line, it shows just the matched
@ -380,8 +381,8 @@ all three, the filter is removed.)
balances are shown (hledger\-ui shows zero items by default, unlike balances are shown (hledger\-ui shows zero items by default, unlike
command\-line hledger). command\-line hledger).
.PP .PP
Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions Press \f[C]right\f[] or \f[C]enter\f[] to view an account\[aq]s
register. transactions register.
.SS Register screen .SS Register screen
.PP .PP
This screen shows the transactions affecting a particular account, like This screen shows the transactions affecting a particular account, like
@ -392,7 +393,7 @@ the other account(s) involved, in abbreviated form.
(If there are both real and virtual postings, it shows only the accounts (If there are both real and virtual postings, it shows only the accounts
affected by real postings.) affected by real postings.)
.IP \[bu] 2 .IP \[bu] 2
the overall change to the current account's balance; positive for an the overall change to the current account\[aq]s balance; positive for an
inflow to this account, negative for an outflow. inflow to this account, negative for an outflow.
.IP \[bu] 2 .IP \[bu] 2
the running historical total or period total for the current account, the running historical total or period total for the current account,
@ -405,10 +406,10 @@ If the historical total is not disturbed by a filter query, it will be
the running historical balance you would see on a bank register for the the running historical balance you would see on a bank register for the
current account. current account.
.PP .PP
Transactions affecting this account's subaccounts will be included in Transactions affecting this account\[aq]s subaccounts will be included
the register if the accounts screen is in tree mode, or if it's in flat in the register if the accounts screen is in tree mode, or if it\[aq]s
mode but this account has subaccounts which are not shown due to a depth in flat mode but this account has subaccounts which are not shown due to
limit. a depth limit.
In other words, the register always shows the transactions contributing In other words, the register always shows the transactions contributing
to the balance shown on the accounts screen. to the balance shown on the accounts screen.
.PD 0 .PD 0
@ -435,10 +436,10 @@ transaction in detail.
.SS Transaction screen .SS Transaction screen
.PP .PP
This screen shows a single transaction, as a general journal entry, This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format similar to hledger\[aq]s print command and journal format
(hledger_journal(5)). (hledger_journal(5)).
.PP .PP
The transaction's date(s) and any cleared flag, transaction code, The transaction\[aq]s date(s) and any cleared flag, transaction code,
description, comments, along with all of its account postings are shown. description, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in Simple transactions have two postings, but there can be more (or in
certain cases, fewer). certain cases, fewer).
@ -449,9 +450,9 @@ In the title bar, the numbers in parentheses show your position within
that account register. that account register.
They will vary depending on which account register you came from They will vary depending on which account register you came from
(remember most transactions appear in multiple account registers). (remember most transactions appear in multiple account registers).
The #N number preceding them is the transaction's position within the The #N number preceding them is the transaction\[aq]s position within
complete unfiltered journal, which is a more stable id (at least until the complete unfiltered journal, which is a more stable id (at least
the next reload). until the next reload).
.SS Error screen .SS Error screen
.PP .PP
This screen will appear if there is a problem, such as a parse error, This screen will appear if there is a problem, such as a parse error,
@ -479,7 +480,7 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
The need to precede options with \f[C]\-\-\f[] when invoked from hledger The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward. is awkward.
.PP .PP
\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin). \f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin).
.PP .PP
\f[C]\-V\f[] affects only the accounts screen. \f[C]\-V\f[] affects only the accounts screen.
.PP .PP

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

@ -23,9 +23,9 @@ DESCRIPTION
web interface. web interface.
Note hledger-ui has some different defaults: - it generates rule-based Note hledger-ui has some different defaults: - it generates rule-based
transactions and postings by default (-forecast and -auto are always transactions and postings by default (--forecast and --auto are always
on). - it hides transactions dated in the future by default (change on). - it hides transactions dated in the future by default (change
this with -future or the F key). Experimental. this with --future or the F key). Experimental.
Like hledger, it reads data from one or more files in hledger journal, Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
@ -73,7 +73,7 @@ OPTIONS
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
Field separator to expect when reading CSV (default: `,') Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW --alias=OLD=NEW
rename accounts named OLD to NEW rename accounts named OLD to NEW

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

@ -20,7 +20,7 @@ other commodity, using double\-entry accounting and a simple, editable
file format. file format.
hledger is inspired by and largely compatible with ledger(1). hledger is inspired by and largely compatible with ledger(1).
.PP .PP
hledger\-web is hledger's web interface. hledger\-web is hledger\[aq]s web interface.
It starts a simple web application for browsing and adding transactions, It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible. and optionally opens it in a web browser window if possible.
It provides a more user\-friendly UI than the hledger CLI or hledger\-ui It provides a more user\-friendly UI than the hledger CLI or hledger\-ui
@ -42,8 +42,8 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
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 .PP
By default, hledger\-web starts the web app in \[lq]transient mode\[rq] By default, hledger\-web starts the web app in "transient mode" and also
and also opens it in your default web browser if possible. 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 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 open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it). (no requests and no browser windows viewing it).
@ -61,8 +61,9 @@ if you are running multiple hledger\-web instances.
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname, You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website. hledger\-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server's configured The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80). configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
80).
.PP .PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static 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 files, eg for better caching or cookie\-less serving on high performance
@ -90,7 +91,7 @@ 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 above.
.TP .TP
.B \f[C]\-\-serve\f[] .B \f[C]\-\-serve\f[]
serve and log requests, don't browse or auto\-exit serve and log requests, don\[aq]t browse or auto\-exit
.RS .RS
.RE .RE
.TP .TP
@ -134,7 +135,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules)
.RE .RE
.TP .TP
.B \f[C]\-\-separator=CHAR\f[] .B \f[C]\-\-separator=CHAR\f[]
Field separator to expect when reading CSV (default: `,') Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS .RS
.RE .RE
.TP .TP
@ -302,7 +303,8 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
The need to precede options with \f[C]\-\-\f[] when invoked from hledger The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward. is awkward.
.PP .PP
\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin). \f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from
stdin).
.PP .PP
Query arguments and some hledger options are ignored. Query arguments and some hledger options are ignored.
.PP .PP

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

@ -106,7 +106,7 @@ OPTIONS
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
Field separator to expect when reading CSV (default: `,') Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW --alias=OLD=NEW
rename accounts named OLD to NEW rename accounts named OLD to NEW

518
hledger/hledger.1
View File

File diff suppressed because it is too large Load Diff

400
hledger/hledger.info
View File

@ -1220,6 +1220,10 @@ Show accounts and their balances. Aliases: b, bal.
'-O FMT --output-format=FMT' '-O FMT --output-format=FMT'
select the output format. Supported formats: txt, csv, html. select the output format. Supported formats: txt, csv, html.
'--transpose'
transposes rows and columns in multi-column reports. 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 above write output to FILE. A file extension matching one of the above
@ -1585,42 +1589,158 @@ expense categories to construct a minimal monthly budget:
$ hledger balance -M --budget $ hledger balance -M --budget
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12 || Nov Dec
======================++================================================= ======================++====================================================
<unbudgeted> || $20 $100 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++------------------------------------------------- ----------------------++----------------------------------------------------
|| 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. '--show-unbudgeted' shows unbudgeted accounts as well. are shown. In the example above, transactions in 'expenses:gifts' and
Top-level accounts with no budget goals anywhere below them are grouped 'expenses:supplies' are counted towards 'expenses' budget, but accounts
under '<unbudgeted>'. 'expenses:gifts' and 'expenses:supplies' are not shown, as they don't
have any budgets.
You can use '--show-unbudgeted' shows unbudgeted accounts as well:
$ hledger balance -M --budget --show-unbudgeted
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
You can roll over unspent budgets to next period with '--cumulative': You can roll over unspent budgets to next period with '--cumulative':
$ hledger balance -M --budget --cumulative $ hledger balance -M --budget --cumulative
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31 || Nov Dec
======================++================================================= ======================++====================================================
<unbudgeted> || $20 $120 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++------------------------------------------------- ----------------------++----------------------------------------------------
|| 0 0 || 0 [ 0] 0 [ 0]
Note, the '-S/--sort-amount' flag is not yet fully supported with Note, the '-S/--sort-amount' flag is not yet fully supported with
'--budget'. '--budget'.
For more examples, see Budgeting and Forecasting. For more examples, see Budgeting and Forecasting.
* Menu:
* Nested budgets::

File: hledger.info, Node: Nested budgets, Up: Budget report
4.4.7.1 Nested budgets
......................
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
budget(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity
means that budget for both 'expenses:personal' and 'expenses' is $1100.
Transactions in 'expenses:personal:electronics' will be counted both
towards its $100 budget and $1100 of 'expenses:personal' , and
transactions in any other subaccount of 'expenses:personal' would be
counted towards only towards the budget of 'expenses:personal'.
For example, let's consider these transactions:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
As you can see, we have transactions in
'expenses:personal:electronics:upgrades' and 'expenses:personal:train
tickets', and since both of these accounts are without explicitly
defined budget, these transactions would be counted towards budgets of
'expenses:personal:electronics' and 'expenses:personal' accordingly:
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
And with '--show-unbudgeted', we can get a better picture of budget
allocation and consumption:
$ hledger balance --budget -M --show-unbudgeted
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 0 [ 0]
4.4.8 Output format 4.4.8 Output format
------------------- -------------------
@ -1851,15 +1971,11 @@ File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMAND
4.10 close 4.10 close
========== ==========
close, equity close, equity Prints a "closing balances" transaction and an "opening
balances" transaction that bring account balances to and from zero,
Prints a "closing balances" transaction and an "opening balances" respectively. Useful for bringing asset/liability balances forward into
transaction, that bring account balances to and from zero, respectively. a new journal file, or for closing out revenues/expenses to retained
Useful for, eg: earnings at the end of a period.
* bringing asset/liability balances forward into a new journal file
* closing out revenues/expenses to retained earnings at the end of a
period
The closing transaction transfers balances to "equity:closing The closing transaction transfers balances to "equity:closing
balances". The opening transaction transfers balances from balances". The opening transaction transfers balances from
@ -1881,7 +1997,7 @@ register reports; you can exclude them with a query like
"close the books" at the end of an accounting period, transferring "close the books" at the end of an accounting period, transferring
income statement account balances to retained earnings. (You may want income statement account balances to retained earnings. (You may want
to change the equity account name to something like "equity:retained to change the equity account name to something like "equity:retained
earnings" for clarity.) earnings".)
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
@ -1900,7 +2016,7 @@ 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!_
@ -2660,122 +2776,124 @@ Node: Smart dates14210
Ref: #smart-dates14351 Ref: #smart-dates14351
Node: Report start & end date15757 Node: Report start & end date15757
Ref: #report-start-end-date15929 Ref: #report-start-end-date15929
Node: Report intervals16994 Node: Report intervals16995
Ref: #report-intervals17159 Ref: #report-intervals17160
Node: Period expressions17560 Node: Period expressions17561
Ref: #period-expressions17720 Ref: #period-expressions17721
Node: Depth limiting21677 Node: Depth limiting21678
Ref: #depth-limiting21821 Ref: #depth-limiting21822
Node: Pivoting22163 Node: Pivoting22164
Ref: #pivoting22281 Ref: #pivoting22282
Node: Cost23957 Node: Cost23958
Ref: #cost24065 Ref: #cost24066
Node: Market value24183 Node: Market value24184
Ref: #market-value24318 Ref: #market-value24319
Node: Combining -B and -V25684 Node: Combining -B and -V25685
Ref: #combining--b-and--v25847 Ref: #combining--b-and--v25848
Node: Output destination25994 Node: Output destination25995
Ref: #output-destination26156 Ref: #output-destination26157
Node: Output format26439 Node: Output format26440
Ref: #output-format26591 Ref: #output-format26592
Node: Regular expressions26976 Node: Regular expressions26977
Ref: #regular-expressions27113 Ref: #regular-expressions27114
Node: QUERIES28474 Node: QUERIES28475
Ref: #queries28576 Ref: #queries28577
Node: COMMANDS32538 Node: COMMANDS32539
Ref: #commands32650 Ref: #commands32651
Node: accounts33650 Node: accounts33651
Ref: #accounts33748 Ref: #accounts33749
Node: activity34994 Node: activity34995
Ref: #activity35104 Ref: #activity35105
Node: add35464 Node: add35465
Ref: #add35563 Ref: #add35564
Node: balance38224 Node: balance38225
Ref: #balance38335 Ref: #balance38336
Node: Classic balance report41418 Node: Classic balance report41526
Ref: #classic-balance-report41591 Ref: #classic-balance-report41699
Node: Customising the classic balance report42960 Node: Customising the classic balance report43068
Ref: #customising-the-classic-balance-report43188 Ref: #customising-the-classic-balance-report43296
Node: Colour support45262 Node: Colour support45370
Ref: #colour-support45429 Ref: #colour-support45537
Node: Flat mode45602 Node: Flat mode45710
Ref: #flat-mode45750 Ref: #flat-mode45858
Node: Depth limited balance reports46163 Node: Depth limited balance reports46271
Ref: #depth-limited-balance-reports46363 Ref: #depth-limited-balance-reports46471
Node: Multicolumn balance report46819 Node: Multicolumn balance report46927
Ref: #multicolumn-balance-report47017 Ref: #multicolumn-balance-report47125
Node: Budget report52197 Node: Budget report52305
Ref: #budget-report52340 Ref: #budget-report52448
Ref: #output-format-155374 Node: Nested budgets57152
Node: balancesheet55452 Ref: #nested-budgets57264
Ref: #balancesheet55588 Ref: #output-format-160764
Node: balancesheetequity57899 Node: balancesheet60842
Ref: #balancesheetequity58048 Ref: #balancesheet60978
Node: cashflow58585 Node: balancesheetequity63289
Ref: #cashflow58713 Ref: #balancesheetequity63438
Node: check-dates60836 Node: cashflow63975
Ref: #check-dates60963 Ref: #cashflow64103
Node: check-dupes61080 Node: check-dates66226
Ref: #check-dupes61204 Ref: #check-dates66353
Node: close61341 Node: check-dupes66470
Ref: #close61449 Ref: #check-dupes66594
Node: files64891 Node: close66731
Ref: #files64992 Ref: #close66839
Node: help65133 Node: files70253
Ref: #help65233 Ref: #files70354
Node: import66307 Node: help70495
Ref: #import66421 Ref: #help70595
Node: incomestatement67151 Node: import71669
Ref: #incomestatement67285 Ref: #import71783
Node: prices69689 Node: incomestatement72513
Ref: #prices69804 Ref: #incomestatement72647
Node: print70076 Node: prices75051
Ref: #print70186 Ref: #prices75166
Node: print-unique75080 Node: print75438
Ref: #print-unique75206 Ref: #print75548
Node: register75274 Node: print-unique80442
Ref: #register75401 Ref: #print-unique80568
Node: Custom register output79902 Node: register80636
Ref: #custom-register-output80031 Ref: #register80763
Node: register-match81261 Node: Custom register output85264
Ref: #register-match81395 Ref: #custom-register-output85393
Node: rewrite81578 Node: register-match86623
Ref: #rewrite81693 Ref: #register-match86757
Node: roi81762 Node: rewrite86940
Ref: #roi81860 Ref: #rewrite87055
Node: stats81976 Node: roi87124
Ref: #stats82075 Ref: #roi87222
Node: tags82945 Node: stats87338
Ref: #tags83043 Ref: #stats87437
Node: test83279 Node: tags88307
Ref: #test83363 Ref: #tags88405
Node: ADD-ON COMMANDS84071 Node: test88641
Ref: #add-on-commands84181 Ref: #test88725
Node: Official add-ons85468 Node: ADD-ON COMMANDS89433
Ref: #official-add-ons85608 Ref: #add-on-commands89543
Node: api85695 Node: Official add-ons90830
Ref: #api85784 Ref: #official-add-ons90970
Node: ui85836 Node: api91057
Ref: #ui85935 Ref: #api91146
Node: web85993 Node: ui91198
Ref: #web86082 Ref: #ui91297
Node: Third party add-ons86128 Node: web91355
Ref: #third-party-add-ons86303 Ref: #web91444
Node: diff86438 Node: Third party add-ons91490
Ref: #diff86535 Ref: #third-party-add-ons91665
Node: iadd86634 Node: diff91800
Ref: #iadd86748 Ref: #diff91897
Node: interest86831 Node: iadd91996
Ref: #interest86952 Ref: #iadd92110
Node: irr87047 Node: interest92193
Ref: #irr87145 Ref: #interest92314
Node: Experimental add-ons87276 Node: irr92409
Ref: #experimental-add-ons87428 Ref: #irr92507
Node: autosync87708 Node: Experimental add-ons92638
Ref: #autosync87819 Ref: #experimental-add-ons92790
Node: chart88058 Node: autosync93070
Ref: #chart88177 Ref: #autosync93181
Node: check88248 Node: chart93420
Ref: #check88350 Ref: #chart93539
Node: check93610
Ref: #check93712
 
End Tag Table End Tag Table

232
hledger/hledger.txt
View File

@ -135,7 +135,7 @@ OPTIONS
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
Field separator to expect when reading CSV (default: `,') Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW --alias=OLD=NEW
rename accounts named OLD to NEW rename accounts named OLD to NEW
@ -444,8 +444,8 @@ OPTIONS
Examples: Examples:
-b 2016/3/17 begin on St. Patrick's day -b 2016/3/17 begin on St. Patrick's
2016 day 2016
-e 12/1 end at the start of decem- -e 12/1 end at the start of decem-
ber 1st of the current ber 1st of the current
year (11/30 will be the year (11/30 will be the
@ -538,10 +538,10 @@ OPTIONS
For example: For example:
-p "weekly from 2009/1/1 to 2009/4/1" - -p "weekly from 2009/1/1 to 2009/4/1"
starts on 2008/12/29, closest preceed- -- starts on 2008/12/29, closest pre-
ing Monday ceeding Monday
-p "monthly in 2008/11/25" - starts on -p "monthly in 2008/11/25" -- starts on
2018/11/01 2018/11/01
-p "quar- -p "quar-
terly from 2009-05-05 to 2009-06-01" - terly from 2009-05-05 to 2009-06-01" -
@ -561,14 +561,14 @@ OPTIONS
Examples: Examples:
-p "bimonthly from 2008" - periods will -p "bimonthly from 2008" -- periods
have boundaries on 2008/01/01, will have boundaries on 2008/01/01,
2008/03/01, ... 2008/03/01, ...
-p "every 2 weeks" - starts on closest -p "every 2 weeks" -- starts on closest
preceeding Monday preceeding Monday
-p "every 5 month from 2009/03" - peri- -p "every 5 month from 2009/03" --
ods will have boundaries on 2009/03/01, periods will have boundaries on
2009/08/01, ... 2009/03/01, 2009/08/01, ...
If you want intervals that start on arbitrary day of your choosing and If you want intervals that start on arbitrary day of your choosing and
span a week, month or year, you need to use any of the following: span a week, month or year, you need to use any of the following:
@ -580,18 +580,18 @@ OPTIONS
Examples: Examples:
-p "every 2nd day of week" - periods -p "every 2nd day of week" -- periods
will go from Tue to Tue will go from Tue to Tue
-p "every Tue" - same -p "every Tue" -- same
-p "every 15th day" - period boundaries -p "every 15th day" -- period bound-
will be on 15th of each month aries will be on 15th of each month
-p "every 2nd Monday" - period bound- -p "every 2nd Monday" -- period bound-
aries will be on second Monday of each aries will be on second Monday of each
month month
-p "every 11/05" - yearly periods with -p "every 11/05" -- yearly periods with
boundaries on 5th of Nov boundaries on 5th of Nov
-p "every 5th Nov" - same -p "every 5th Nov" -- same
-p "every Nov 5th" - same -p "every Nov 5th" -- same
Show historical balances at end of 15th each month (N is exclusive end Show historical balances at end of 15th each month (N is exclusive end
date): date):
@ -714,7 +714,7 @@ OPTIONS
the prices on each column's end date.) the prices on each column's end date.)
Combining -B and -V Combining -B and -V
Using -B/-cost and -V/-value together is currently allowed, but the Using -B/--cost and -V/--value together is currently allowed, but the
results are probably not meaningful. Let us know if you find a use for results are probably not meaningful. Let us know if you find a use for
this. this.
@ -918,7 +918,7 @@ COMMANDS
in flat mode: omit N leading account name parts in flat mode: omit N leading account name parts
This command lists account names, either declared with account direc- This command lists account names, either declared with account direc-
tives (-declared), posted to (-used), or both (default). With query tives (--declared), posted to (--used), or both (default). With query
arguments, only matched account names and account names referenced by arguments, only matched account names and account names referenced by
matched postings are shown. It shows a flat list by default. With matched postings are shown. It shows a flat list by default. With
--tree, it uses indentation to show the account hierarchy. In flat --tree, it uses indentation to show the account hierarchy. In flat
@ -1088,6 +1088,10 @@ COMMANDS
-O FMT --output-format=FMT -O FMT --output-format=FMT
select the output format. Supported formats: txt, csv, html. select the output format. Supported formats: txt, csv, html.
--transpose
transposes rows and columns in multi-column reports. 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.
@ -1108,7 +1112,7 @@ COMMANDS
transactions transactions
--show-unbudgeted --show-unbudgeted
with -budget, show unbudgeted accounts also 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-
@ -1127,7 +1131,7 @@ COMMANDS
tions in the journal; instead you'll have all transactions after a cer- tions in the journal; instead you'll have all transactions after a cer-
tain date, and an "opening balances" transaction setting the correct tain date, and an "opening balances" transaction setting the correct
starting balance on that date. Then the balance command will show starting balance on that date. Then the balance command will show
real-world account balances. In some cases the -H/-historical flag is real-world account balances. In some cases the -H/--historical flag is
used to ensure this (more below). used to ensure this (more below).
The balance command can produce several styles of report: The balance command can produce several styles of report:
@ -1383,8 +1387,8 @@ COMMANDS
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 with income, expenses, time usage, etc. --budget is most often combined
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:
@ -1418,43 +1422,151 @@ COMMANDS
$ hledger balance -M --budget $ hledger balance -M --budget
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12 || Nov Dec
======================++================================================= ======================++====================================================
<unbudgeted> || $20 $100 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++------------------------------------------------- ----------------------++----------------------------------------------------
|| 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. --show-unbudgeted shows unbudgeted accounts as well. are shown. In the example above, transactions in expenses:gifts and
Top-level accounts with no budget goals anywhere below them are grouped expenses:supplies are counted towards expenses budget, but accounts
under <unbudgeted>. expenses:gifts and expenses:supplies are not shown, as they don't have
any budgets.
You can use --show-unbudgeted shows unbudgeted accounts as well:
$ hledger balance -M --budget --show-unbudgeted
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
You can roll over unspent budgets to next period with --cumulative: You can roll over unspent budgets to next period with --cumulative:
$ hledger balance -M --budget --cumulative $ hledger balance -M --budget --cumulative
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31 || Nov Dec
======================++================================================= ======================++====================================================
<unbudgeted> || $20 $120 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++------------------------------------------------- ----------------------++----------------------------------------------------
|| 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
You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity
means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both
towards its $100 budget and $1100 of expenses:personal , and transac-
tions in any other subaccount of expenses:personal would be counted
towards only towards the budget of expenses:personal.
For example, let's consider these transactions:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac-
tions would be counted towards budgets of expenses:personal:electronics
and expenses:personal accordingly:
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
And with --show-unbudgeted, we can get a better picture of budget allo-
cation and consumption:
$ hledger balance --budget -M --show-unbudgeted
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 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.
@ -1646,16 +1758,11 @@ COMMANDS
example: http://stefanorodighiero.net/software/hledger-dupes.html example: http://stefanorodighiero.net/software/hledger-dupes.html
close close
close, equity close, equity Prints a "closing balances" transaction and an "opening
balances" transaction that bring account balances to and from zero,
Prints a "closing balances" transaction and an "opening balances" respectively. Useful for bringing asset/liability balances forward
transaction, that bring account balances to and from zero, respec- into a new journal file, or for closing out revenues/expenses to
tively. Useful for, eg: retained earnings at the end of a period.
o bringing asset/liability balances forward into a new journal file
o closing out revenues/expenses to 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-
@ -1677,7 +1784,7 @@ COMMANDS
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" for clarity.) 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
@ -1689,13 +1796,13 @@ COMMANDS
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!
@ -1775,11 +1882,11 @@ COMMANDS
each one. So eg to add new transactions from all CSV files to the main each one. So eg to add new transactions from all CSV files to the main
journal, it's just: hledger import *.csv journal, it's just: hledger import *.csv
New transactions are detected in the same way as print -new: by assum- New transactions are detected in the same way as print --new: by assum-
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
@ -1864,10 +1971,11 @@ COMMANDS
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 prices. --inverted-costs, also print inverse prices based on transaction
Prices (and postings providing prices) can be filtered by a query. prices. Prices (and postings providing prices) can be filtered by a
query.
print print
Show transactions from the journal. Aliases: p, txns. Show transactions from the journal. Aliases: p, txns.
@ -1997,7 +2105,7 @@ COMMANDS
-A --average -A --average
show running average of posting amounts instead of total show running average of posting amounts instead of total
(implies -empty) (implies --empty)
-r --related -r --related
show postings' siblings instead show postings' siblings instead
@ -2087,7 +2195,7 @@ COMMANDS
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) ---------------------------------->
@ -2285,7 +2393,7 @@ TROUBLESHOOTING
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.