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

doc: bring embedded help files up to date

Browse Source
This commit is contained in:
Simon Michael 2016-05-28 12:58:30 -07:00
parent abf1bcbf36
commit bd3212654c
18 changed files with 1065 additions and 906 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

280
hledger-lib/doc/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_journal" "5" "April 2016" "" "hledger User Manuals"
.TH "hledger_journal" "5" "May 2016" "" "hledger User Manuals"
@ -85,25 +85,29 @@ inferred.
.SS Simple dates
.PP
Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
Leading zeroes are optional.
The year may be omitted, in which case it defaults to the current year,
or you can set the default year with a default year directive.
.PP
Leading zeros are optional.
The year may be omitted, in which case it will be inferred from the
context \- the current transaction, the default year set with a default
year directive, or the current date when the command is run.
Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[],
\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[].
.SS Secondary dates
.PP
Real\-life transactions sometimes involve more than one date \- eg the
date you write a cheque, and the date it clears in your bank.
When you want to model this, eg for more accurate balances, write both
dates separated by an equals sign.
The \f[I]primary date\f[], on the left, is used by default; the
\f[I]secondary date\f[], on the right, is used when the
\f[C]\-\-date2\f[] flag is specified (For Ledger compatibility,
\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work.)
When you want to model this, eg for more accurate balances, you can
specify individual #posting\-dates, which I recommend.
Or, you can use the secondary dates (aka auxiliary/effective dates)
feature, supported for compatibility with Ledger.
.PP
Their meaning is up to you, but it\[aq]s best to follow a consistent
rule.
A secondary date can be written after the primary date, separated by an
equals sign.
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
(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work).
.PP
The meaning of secondary dates is up to you, but it\[aq]s best to follow
a consistent rule.
Eg write the bank\[aq]s clearing date as primary, and when needed, the
date the transaction was initiated as secondary.
.PP
@ -133,15 +137,16 @@ $\ hledger\ register\ checking\ \-\-date2
\f[]
.fi
.PP
Secondary dates require some effort: you must use them consistently in
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the
\f[C]\-\-date2\f[] flag for your reports.
Arguably they are now obsolete, superseded by...
They are included in hledger for Ledger compatibility, but posting dates
are a more powerful and less confusing alternative.
.SS Posting dates
.PP
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like
\f[C]date:DATE\f[], where DATE is a simple date.
transaction, by adding a posting comment containing a tag (see below)
like \f[C]date:DATE\f[].
This is probably the best way to control posting dates precisely.
Eg in this example the expense should appear in May reports, and the
deduction from checking should be reported on 6/1 for easy bank
@ -157,28 +162,31 @@ reconciliation:
.IP
.nf
\f[C]
$\ hledger\ \-f\ tt.j\ register\ food
$\ hledger\ \-f\ t.j\ register\ food
2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ tt.j\ register\ checking
$\ hledger\ \-f\ t.j\ register\ checking
2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.PP
A posting date will use the year of the transaction date if unspecified.
DATE should be a simple date; if the year is not specified it will use
the year of the transaction\[aq]s date.
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
value if they are present, eg a \f[C]date:\f[] tag with no value is not
allowed.
.PP
You can also set the secondary date, with \f[C]date2:DATE2\f[].
For compatibility, Ledger\[aq]s older posting date syntax is also
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]
in a posting comment.
.PP
When using any of these forms, be sure to provide a valid simple date or
you\[aq]ll get a parse error.
Eg a \f[C]date:\f[] tag with no value is not allowed.
Ledger\[aq]s earlier, more compact bracketed date syntax is also
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
\f[C]0123456789/\-.=\f[] characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
infers its year from DATE.
.SS Account names
.PP
Account names typically have several parts separated by a full colon,
@ -189,67 +197,87 @@ five top\-level accounts: \f[C]assets\f[], \f[C]liabilities\f[],
.PP
Account names may contain single spaces, eg:
\f[C]assets:accounts\ receivable\f[].
Because of this, they must always be followed by at least two spaces (or
newline).
Because of this, they must always be followed by \f[B]two or more
spaces\f[] (or newline).
.PP
Account names can be aliased.
.SS Amounts
.PP
After the account name, there is usually an amount.
Important: between account name and amount, there must be \f[B]two or
more\f[] spaces.
more spaces\f[].
.PP
The amount is a number, optionally with a currency symbol or commodity
name on either the left or right.
Negative amounts may have the minus sign either before or after the
currency symbol (\f[C]\-$1\f[] or \f[C]$\-1\f[]).
Commodity names which contain more than just letters should be enclosed
in double quotes (\f[C]1\ "person\ hours"\f[]).
.SS Decimal points and digit groups
Amounts consist of a number and (usually) a currency symbol or commodity
name.
Some examples:
.PP
hledger supports flexible decimal point and digit group separator
styles, to support international variations.
Numbers can use either a period (\f[C]\&.\f[]) or a comma (\f[C],\f[])
as decimal point.
They can also have digit group separators at any position (eg thousands
separators) which can be comma or period \- whichever one you did not
use as a decimal point.
If you use digit group separators, you must also include a decimal point
in at least one number in the same commodity, so that hledger knows
which character is which.
Eg, write \f[C]$1,000.00\f[] or \f[C]$1.000,00\f[].
.SS Amount display styles
\f[C]2.00001\f[]
.PD 0
.P
.PD
\f[C]$1\f[]
.PD 0
.P
.PD
\f[C]4000\ AAPL\f[]
.PD 0
.P
.PD
\f[C]3\ "green\ apples"\f[]
.PD 0
.P
.PD
\f[C]\-$1,000,000.00\f[]
.PD 0
.P
.PD
\f[C]INR\ 9,99,99,999.00\f[]
.PD 0
.P
.PD
\f[C]EUR\ \-2.000.000,00\f[]
.PP
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
As you can see, the amount format is somewhat flexible:
.IP \[bu] 2
amounts are a number (the "quantity") and optionally a currency
symbol/commodity name (the "commodity").
.IP \[bu] 2
the commodity is a symbol, word, or double\-quoted phrase, on the left
or right, with or without a separating space
.IP \[bu] 2
negative amounts with a commodity on the left can have the minus sign
before or after it
.IP \[bu] 2
digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods (in
which case comma is used for decimal point)
.PP
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity.
Amount styles include:
(Except for price amounts, which are always formatted as written).
The display format is chosen as follows:
.IP \[bu] 2
the position (left or right) and spacing (space or no separator) of the
commodity symbol
if there is a commodity directive specifying the format, that is used
.IP \[bu] 2
the digit group separator character (comma or period) and digit group
sizes, if any
otherwise the format is inferred from the first posting amount in that
commodity in the journal, and the precision (number of decimal places)
will be the maximum from all posting amounts in that commmodity
.IP \[bu] 2
the decimal point character (period or comma)
.IP \[bu] 2
the display precision (number of decimal places displayed)
or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[]).
.PP
The canonical style is generally the style of the first posting amount
seen in a commodity.
However the display precision will be the highest precision seen in all
posting amounts in that commmodity.
.PP
The precisions used in a price amount, or a D directive, don\[aq]t
affect the canonical display precision directly, but they can affect it
indirectly, eg when D\[aq]s default commodity is applied to a
commodity\-less amount or when an amountless posting is balanced using a
price\[aq]s commodity (actually this last case does not influence the
canonical display precision but probably should).
Price amounts and amounts in D directives usually don\[aq]t affect
amount format inference, but in some situations they can do so
indirectly.
(Eg when D\[aq]s default commodity is applied to a commodity\-less
amount, or when an amountless posting is balanced using a price\[aq]s
commodity, or when \-V is used.) If you find this causing problems, set
the desired format with a commodity directive.
.SS Virtual Postings
.PP
When you parenthesise the account name in a posting, that posting is
considered \f[I]virtual\f[], which means:
When you parenthesise the account name in a posting, we call that a
\f[I]virtual posting\f[], which means:
.IP \[bu] 2
it is ignored when checking that the transaction is balanced
.IP \[bu] 2
@ -265,20 +293,28 @@ needing to use the \f[C]equity:opening\ balances\f[] account:
\ \ (assets:checking)\ \ \ $1000
\f[]
.fi
.SS Balanced Virtual Postings
.PP
When the account name is bracketed, the posting is \f[I]balanced
virtual\f[], which is just like a virtual posting except the balanced
virtual postings in a transaction must balance to 0, like the real
postings (but separately from them).
When the account name is bracketed, we call it a \f[I]balanced virtual
posting\f[].
This is like an ordinary virtual posting except the balanced virtual
postings in a transaction must balance to 0, like the real postings (but
separately from them).
Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or
\f[C]real:1\f[].
.IP
.nf
\f[C]
1/1\ buy\ food\ with\ cash,\ and\ update\ some\ budget\-tracking\ subaccounts\ elsewhere
\ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10
\ \ [assets:checking:available]\ \ \ \ \ $10
\ \ [assets:checking:budget:food]\ \ $\-10
\f[]
.fi
.PP
Virtual postings are a feature inherited from Ledger can can
occasionally be useful, but they can be a crutch and you should think
twice or three times before using them.
You can almost always find an equivalent journal entry using two or more
real postings that will be more correct and more error\-proof.
Virtual postings have some legitimate uses, but those are few.
You can usually find an equivalent journal entry using real postings,
which is more correct and provides better error checking.
.SS Balance Assertions
.PP
hledger supports ledger\-style balance assertions in journal files.
@ -547,7 +583,7 @@ posting\-tag):
.fi
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are always simple strings.
values are simple strings.
.SS Directives
.SS Account aliases
.PP
@ -721,46 +757,50 @@ spellings were also supported.
A line containing just \f[C]comment\f[] starts a multi\-line comment,
and a line containing just \f[C]end\ comment\f[] ends it.
See comments.
.SS commodity directive
.PP
The \f[C]commodity\f[] directive predefines commodities (currently this
is just informational), and also it may define the display format for
amounts in this commodity (overriding the automatically inferred
format).
.PP
It may be written on a single line, like this:
.IP
.nf
\f[C]
;\ commodity\ EXAMPLEAMOUNT
;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated,
;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and
;\ separating\ thousands\ with\ comma.
commodity\ 1,000.0000\ AAAA
\f[]
.fi
.PP
or on multiple lines, using the "format" subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
.nf
\f[C]
;\ commodity\ SYMBOL
;\ \ \ format\ EXAMPLEAMOUNT
;\ display\ indian\ rupees\ with\ currency\ name\ on\ the\ left,
;\ thousands,\ lakhs\ and\ crores\ comma\-separated,
;\ period\ as\ decimal\ point,\ and\ two\ decimal\ places.
commodity\ INR
\ \ format\ INR\ 9,99,99,999.00
\f[]
.fi
.SS Default commodity
.PP
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount.
The commodity (and the sample amount\[aq]s display style) will be
The commodity (and the sample amount\[aq]s display format) will be
applied to all subsequent commodity\-less amounts, up to the next D
directive.
(Note this is different from Ledger\[aq]s default commodity directive.)
.PP
Also note the directive itself does not influence the commodity\[aq]s
default display style, but the amount it is applied to might.
Here\[aq]s an example:
.IP
.nf
\f[C]
;\ set\ £\ as\ the\ default\ commodity
D\ £1,000.00
2010/1/1
\ \ a\ \ 2340
\ \ b
2014/1/1
\ \ c\ \ £1000
\ \ d
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ print
2010/01/01
\ \ \ \ a\ \ \ \ \ £2,340.00
\ \ \ \ b\ \ \ \ £\-2,340.00
2014/01/01
\ \ \ \ c\ \ \ \ \ £1,000.00
\ \ \ \ d\ \ \ \ £\-1,000.00
\f[]
.fi
.SS Default year
.PP
You can set a default year to be used for subsequent dates which
@ -800,12 +840,10 @@ include\ path/to/file.journal
.PP
If the path does not begin with a slash, it is relative to the current
file.
.PP
Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive may only be used in journal files, and
currently it may only include other journal files (eg, not CSV or
timeclock files.)
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.
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with

403
hledger-lib/doc/hledger_journal.5.info
View File

@ -119,11 +119,11 @@ File: hledger_journal.5.info, Node: Simple dates, Next: Secondary dates, Up:
------------------
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeroes are optional. The year may be omitted, in which case it
defaults to the current year, or you can set the default year with a
default year directive.
Some examples: `2010/01/31', `1/31', `2010-01-31', `2010.1.31'.
Leading zeros are optional. The year may be omitted, in which case it
will be inferred from the context - the current transaction, the default
year set with a default year directive, or the current date when the
command is run. Some examples: `2010/01/31', `1/31', `2010-01-31',
`2010.1.31'.

File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates
@ -133,15 +133,19 @@ File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Pre
Real-life transactions sometimes involve more than one date - eg the
date you write a cheque, and the date it clears in your bank. When you
want to model this, eg for more accurate balances, write both dates
separated by an equals sign. The _primary date_, on the left, is used
by default; the _secondary date_, on the right, is used when the
`--date2' flag is specified (For Ledger compatibility, `--aux-date' or
`--effective' also work.)
want to model this, eg for more accurate balances, you can specify
individual #posting-dates, which I recommend. Or, you can use the
secondary dates (aka auxiliary/effective dates) feature, supported for
compatibility with Ledger.
Their meaning is up to you, but it's best to follow a consistent
rule. Eg write the bank's clearing date as primary, and when needed,
the date the transaction was initiated as secondary.
A secondary date can be written after the primary date, separated by
an equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the `--date2' flag is
specified (`--aux-date' or `--effective' also work).
The meaning of secondary dates is up to you, but it's best to follow
a consistent rule. Eg write the bank's clearing date as primary, and
when needed, the date the transaction was initiated as secondary.
Here's an example. Note that a secondary date will use the year of
the primary date if unspecified.
@ -159,10 +163,11 @@ $ hledger register checking
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort: you must use them consistently
Secondary dates require some effort; you must use them consistently
in your journal entries and remember whether to use or not use the
`--date2' flag for your reports. Arguably they are now obsolete,
superseded by...
`--date2' flag for your reports. They are included in hledger for
Ledger compatibility, but posting dates are a more powerful and less
confusing alternative.

File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up: Dates
@ -171,11 +176,11 @@ File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up:
-------------------
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like `date:DATE',
where DATE is a simple date. This is probably the best way to control
posting dates precisely. Eg in this example the expense should appear in
May reports, and the deduction from checking should be reported on 6/1
for easy bank reconciliation:
transaction, by adding a posting comment containing a tag (see below)
like `date:DATE'. This is probably the best way to control posting
dates precisely. Eg in this example the expense should appear in May
reports, and the deduction from checking should be reported on 6/1 for
easy bank reconciliation:
2015/5/30
@ -183,23 +188,24 @@ for easy bank reconciliation:
assets:checking ; bank cleared it on monday, date:6/1
$ hledger -f tt.j register food
$ hledger -f t.j register food
2015/05/30 expenses:food $10 $10
$ hledger -f tt.j register checking
$ hledger -f t.j register checking
2015/06/01 assets:checking $-10 $-10
A posting date will use the year of the transaction date if
unspecified.
DATE should be a simple date; if the year is not specified it will
use the year of the transaction's date. You can set the secondary date
similarly, with `date2:DATE2'. The `date:' or `date2:' tags must have a
valid simple date value if they are present, eg a `date:' tag with no
value is not allowed.
You can also set the secondary date, with `date2:DATE2'. For
compatibility, Ledger's older posting date syntax is also supported:
`[DATE]', `[DATE=DATE2]' or `[=DATE2]' in a posting comment.
When using any of these forms, be sure to provide a valid simple
date or you'll get a parse error. Eg a `date:' tag with no value is not
allowed.
Ledger's earlier, more compact bracketed date syntax is also
supported: `[DATE]', `[DATE=DATE2]' or `[=DATE2]'. hledger will attempt
to parse any square-bracketed sequence of the `0123456789/-.='
characters in this way. With this syntax, DATE infers its year from the
transaction and DATE2 infers its year from DATE.

File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Dates, Up: FILE FORMAT
@ -213,8 +219,8 @@ anything you like, but in finance there are traditionally five top-level
accounts: `assets', `liabilities', `income', `expenses', and `equity'.
Account names may contain single spaces, eg: `assets:accounts
receivable'. Because of this, they must always be followed by at least
two spaces (or newline).
receivable'. Because of this, they must always be followed by *two or
more spaces* (or newline).
Account names can be aliased.
@ -225,65 +231,56 @@ File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Ac
===========
After the account name, there is usually an amount. Important: between
account name and amount, there must be *two or more* spaces.
account name and amount, there must be *two or more spaces*.
The amount is a number, optionally with a currency symbol or
commodity name on either the left or right. Negative amounts may have
the minus sign either before or after the currency symbol (`-$1' or
`$-1'). Commodity names which contain more than just letters should be
enclosed in double quotes (`1 "person hours"').
Amounts consist of a number and (usually) a currency symbol or
commodity name. Some examples:
* Menu:
`2.00001'
`$1'
`4000 AAPL'
`3 "green apples"'
`-$1,000,000.00'
`INR 9,99,99,999.00'
`EUR -2.000.000,00'
* Decimal points and digit groups::
* Amount display styles::
As you can see, the amount format is somewhat flexible:

File: hledger_journal.5.info, Node: Decimal points and digit groups, Next: Amount display styles, Up: Amounts
* amounts are a number (the "quantity") and optionally a currency
symbol/commodity name (the "commodity").
1.4.1 Decimal points and digit groups
-------------------------------------
* the commodity is a symbol, word, or double-quoted phrase, on the
left or right, with or without a separating space
hledger supports flexible decimal point and digit group separator
styles, to support international variations. Numbers can use either a
period (`.') or a comma (`,') as decimal point. They can also have
digit group separators at any position (eg thousands separators) which
can be comma or period - whichever one you did not use as a decimal
point. If you use digit group separators, you must also include a
decimal point in at least one number in the same commodity, so that
hledger knows which character is which. Eg, write `$1,000.00' or
`$1.000,00'.
* negative amounts with a commodity on the left can have the minus
sign before or after it

File: hledger_journal.5.info, Node: Amount display styles, Prev: Decimal points and digit groups, Up: Amounts
* digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods
(in which case comma is used for decimal point)
1.4.2 Amount display styles
---------------------------
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
commodity. Amount styles include:
* if there is a commodity directive specifying the format, that is
used
* the position (left or right) and spacing (space or no separator)
of the commodity symbol
* otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of
decimal places) will be the maximum from all posting amounts in
that commmodity
* the digit group separator character (comma or period) and digit
group sizes, if any
* or if there are no such amounts in the journal, a default format
is used (like `$1000.00').
* the decimal point character (period or comma)
* the display precision (number of decimal places displayed)
The canonical style is generally the style of the first posting
amount seen in a commodity. However the display precision will be the
highest precision seen in all posting amounts in that commmodity.
The precisions used in a price amount, or a D directive, don't affect
the canonical display precision directly, but they can affect it
indirectly, eg when D's default commodity is applied to a commodity-less
amount or when an amountless posting is balanced using a price's
commodity (actually this last case does not influence the canonical
display precision but probably should).
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly. (Eg
when D's default commodity is applied to a commodity-less amount, or
when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, set the desired
format with a commodity directive.

File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT
@ -291,8 +288,8 @@ File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions
1.5 Virtual Postings
====================
When you parenthesise the account name in a posting, that posting is
considered _virtual_, which means:
When you parenthesise the account name in a posting, we call that a
_virtual posting_, which means:
* it is ignored when checking that the transaction is balanced
@ -306,27 +303,22 @@ needing to use the `equity:opening balances' account:
1/1 special unbalanced posting to set initial balance
(assets:checking) $1000
* Menu:
When the account name is bracketed, we call it a _balanced virtual
posting_. This is like an ordinary virtual posting except the balanced
virtual postings in a transaction must balance to 0, like the real
postings (but separately from them). Balanced virtual postings are also
excluded by `--real/-R' or `real:1'.
* Balanced Virtual Postings::

File: hledger_journal.5.info, Node: Balanced Virtual Postings, Up: Virtual Postings
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
expenses:food $10
assets:cash $-10
[assets:checking:available] $10
[assets:checking:budget:food] $-10
1.5.1 Balanced Virtual Postings
-------------------------------
When the account name is bracketed, the posting is _balanced virtual_,
which is just like a virtual posting except the balanced virtual
postings in a transaction must balance to 0, like the real postings
(but separately from them). Balanced virtual postings are also excluded
by `--real/-R' or `real:1'.
Virtual postings are a feature inherited from Ledger can can
occasionally be useful, but they can be a crutch and you should think
twice or three times before using them. You can almost always find an
equivalent journal entry using two or more real postings that will be
more correct and more error-proof.
Virtual postings have some legitimate uses, but those are few. You
can usually find an equivalent journal entry using real postings, which
is more correct and provides better error checking.

File: hledger_journal.5.info, Node: Balance Assertions, Next: Prices, Prev: Virtual Postings, Up: FILE FORMAT
@ -602,7 +594,7 @@ and the posting has four (A, TAG2, third-tag, posting-tag):
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
are always simple strings.
are simple strings.

File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
@ -616,6 +608,7 @@ File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
* account directive::
* apply account directive::
* Multi-line comments::
* commodity directive::
* Default commodity::
* Default year::
* Including other files::
@ -791,7 +784,7 @@ include personal.journal
also supported.

File: hledger_journal.5.info, Node: Multi-line comments, Next: Default commodity, Prev: apply account directive, Up: Directives
File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
1.10.4 Multi-line comments
--------------------------
@ -800,47 +793,56 @@ A line containing just `comment' starts a multi-line comment, and a
line containing just `end comment' ends it. See comments.

File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: Multi-line comments, Up: Directives
File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
1.10.5 Default commodity
1.10.5 commodity directive
--------------------------
The `commodity' directive predefines commodities (currently this is
just informational), and also it may define the display format for
amounts in this commodity (overriding the automatically inferred
format).
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated,
; using period as decimal point, with four decimal places, and
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
; format EXAMPLEAMOUNT
; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated,
; period as decimal point, and two decimal places.
commodity INR
format INR 9,99,99,999.00

File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
1.10.6 Default commodity
------------------------
You can set a default commodity, to be used for amounts without one. Use
the D directive with a sample amount. The commodity (and the sample
amount's display style) will be applied to all subsequent commodity-less
amounts, up to the next D directive. (Note this is different from
Ledger's default commodity directive.)
Also note the directive itself does not influence the commodity's
default display style, but the amount it is applied to might. Here's an
example:
; set £ as the default commodity
D £1,000.00
2010/1/1
a 2340
b
2014/1/1
c £1000
d
$ hledger print
2010/01/01
a £2,340.00
b £-2,340.00
2014/01/01
c £1,000.00
d £-1,000.00
amount's display format) will be applied to all subsequent
commodity-less amounts, up to the next D directive. (Note this is
different from Ledger's default commodity directive.)

File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
1.10.6 Default year
1.10.7 Default year
-------------------
You can set a default year to be used for subsequent dates which don't
@ -867,7 +869,7 @@ Y2010 ; change default year to 2010

File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives
1.10.7 Including other files
1.10.8 Including other files
----------------------------
You can pull in the content of additional journal files by writing an
@ -877,13 +879,10 @@ include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the
current file.
current file. Glob patterns (`*') are not currently supported.
Glob patterns (`*') are not currently supported.
The `include' directive may only be used in journal files, and
currently it may only include other journal files (eg, not CSV or
timeclock files.)
The `include' directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -917,67 +916,63 @@ Node: Dates3351
Ref: #dates3479
Node: Simple dates3544
Ref: #simple-dates3672
Node: Secondary dates3976
Ref: #secondary-dates4132
Node: Posting dates5408
Ref: #posting-dates5539
Node: Account names6715
Ref: #account-names6854
Node: Amounts7338
Ref: #amounts7476
Node: Decimal points and digit groups8003
Ref: #decimal-points-and-digit-groups8196
Node: Amount display styles8751
Ref: #amount-display-styles8924
Node: Virtual Postings10003
Ref: #virtual-postings10164
Node: Balanced Virtual Postings10683
Ref: #balanced-virtual-postings10837
Node: Balance Assertions11452
Ref: #balance-assertions11616
Node: Assertions and ordering12438
Ref: #assertions-and-ordering12623
Node: Assertions and commodities13654
Ref: #assertions-and-commodities13880
Node: Assertions and subaccounts14572
Ref: #assertions-and-subaccounts14806
Node: Assertions and virtual postings15328
Ref: #assertions-and-virtual-postings15537
Node: Prices15678
Ref: #prices15810
Node: Transaction prices15861
Ref: #transaction-prices16006
Node: Market prices17613
Ref: #market-prices17748
Node: Comments18636
Ref: #comments18758
Node: Tags19870
Ref: #tags19988
Node: Directives20918
Ref: #directives21033
Node: Account aliases21202
Ref: #account-aliases21348
Node: Basic aliases21950
Ref: #basic-aliases22095
Node: Regex aliases22783
Ref: #regex-aliases22953
Node: Multiple aliases23723
Ref: #multiple-aliases23897
Node: end aliases24393
Ref: #end-aliases24535
Node: account directive24637
Ref: #account-directive24819
Node: apply account directive25115
Ref: #apply-account-directive25313
Node: Multi-line comments25974
Ref: #multi-line-comments26164
Node: Default commodity26291
Ref: #default-commodity26466
Node: Default year27161
Ref: #default-year27328
Node: Including other files27751
Ref: #including-other-files27910
Node: EDITOR SUPPORT28327
Ref: #editor-support28447
Node: Secondary dates4036
Ref: #secondary-dates4192
Node: Posting dates5753
Ref: #posting-dates5884
Node: Account names7255
Ref: #account-names7394
Node: Amounts7879
Ref: #amounts8017
Node: Virtual Postings10015
Ref: #virtual-postings10176
Node: Balance Assertions11396
Ref: #balance-assertions11560
Node: Assertions and ordering12382
Ref: #assertions-and-ordering12567
Node: Assertions and commodities13598
Ref: #assertions-and-commodities13824
Node: Assertions and subaccounts14516
Ref: #assertions-and-subaccounts14750
Node: Assertions and virtual postings15272
Ref: #assertions-and-virtual-postings15481
Node: Prices15622
Ref: #prices15754
Node: Transaction prices15805
Ref: #transaction-prices15950
Node: Market prices17557
Ref: #market-prices17692
Node: Comments18580
Ref: #comments18702
Node: Tags19814
Ref: #tags19932
Node: Directives20855
Ref: #directives20970
Node: Account aliases21163
Ref: #account-aliases21309
Node: Basic aliases21911
Ref: #basic-aliases22056
Node: Regex aliases22744
Ref: #regex-aliases22914
Node: Multiple aliases23684
Ref: #multiple-aliases23858
Node: end aliases24354
Ref: #end-aliases24496
Node: account directive24598
Ref: #account-directive24780
Node: apply account directive25076
Ref: #apply-account-directive25274
Node: Multi-line comments25935
Ref: #multi-line-comments26127
Node: commodity directive26254
Ref: #commodity-directive26440
Node: Default commodity27313
Ref: #default-commodity27488
Node: Default year27809
Ref: #default-year27976
Node: Including other files28399
Ref: #including-other-files28558
Node: EDITOR SUPPORT28954
Ref: #editor-support29074

End Tag Table

425
hledger-lib/doc/hledger_journal.5.txt
View File

@ -75,24 +75,28 @@ FFIILLEE FFOORRMMAATT
DDaatteess
SSiimmppllee ddaatteess
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeroes are optional. The year may be omitted, in which case it
defaults to the current year, or you can set the default year with a
default year directive.
Some examples: 2010/01/31, 1/31, 2010-01-31, 2010.1.31.
Leading zeros are optional. The year may be omitted, in which case it
will be inferred from the context - the current transaction, the
default year set with a default year directive, or the current date
when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31,
2010.1.31.
SSeeccoonnddaarryy ddaatteess
Real-life transactions sometimes involve more than one date - eg the
date you write a cheque, and the date it clears in your bank. When you
want to model this, eg for more accurate balances, write both dates
separated by an equals sign. The _p_r_i_m_a_r_y _d_a_t_e, on the left, is used by
default; the _s_e_c_o_n_d_a_r_y _d_a_t_e, on the right, is used when the --date2
flag is specified (For Ledger compatibility, --aux-date or --effective
also work.)
want to model this, eg for more accurate balances, you can specify
individual #posting-dates, which I recommend. Or, you can use the sec-
ondary dates (aka auxiliary/effective dates) feature, supported for
compatibility with Ledger.
Their meaning is up to you, but it's best to follow a consistent rule.
Eg write the bank's clearing date as primary, and when needed, the date
the transaction was initiated as secondary.
A secondary date can be written after the primary date, separated by an
equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the --date2 flag is speci-
fied (--aux-date or --effective also work).
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg write the bank's clearing date as primary, and
when needed, the date the transaction was initiated as secondary.
Here's an example. Note that a secondary date will use the year of the
primary date if unspecified.
@ -107,39 +111,41 @@ FFIILLEE FFOORRMMAATT
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort: you must use them consistently in
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the --date2
flag for your reports. Arguably they are now obsolete, superseded
by...
flag for your reports. They are included in hledger for Ledger compat-
ibility, but posting dates are a more powerful and less confusing
alternative.
PPoossttiinngg ddaatteess
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like date:DATE, where
DATE is a simple date. This is probably the best way to control post-
ing dates precisely. Eg in this example the expense should appear in
May reports, and the deduction from checking should be reported on 6/1
for easy bank reconciliation:
You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below)
like date:DATE. This is probably the best way to control posting dates
precisely. Eg in this example the expense should appear in May
reports, and the deduction from checking should be reported on 6/1 for
easy bank reconciliation:
2015/5/30
expenses:food $10 ; food purchased on saturday 5/30
assets:checking ; bank cleared it on monday, date:6/1
$ hledger -f tt.j register food
$ hledger -f t.j register food
2015/05/30 expenses:food $10 $10
$ hledger -f tt.j register checking
$ hledger -f t.j register checking
2015/06/01 assets:checking $-10 $-10
A posting date will use the year of the transaction date if unspeci-
fied.
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. You can set the secondary date
similarly, with date2:DATE2. The date: or date2: tags must have a
valid simple date value if they are present, eg a date: tag with no
value is not allowed.
You can also set the secondary date, with date2:DATE2. For compatibil-
ity, Ledger's older posting date syntax is also supported: [DATE],
[DATE=DATE2] or [=DATE2] in a posting comment.
When using any of these forms, be sure to provide a valid simple date
or you'll get a parse error. Eg a date: tag with no value is not
allowed.
Ledger's earlier, more compact bracketed date syntax is also supported:
[DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
square-bracketed sequence of the 0123456789/-.= characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
infers its year from DATE.
AAccccoouunntt nnaammeess
Account names typically have several parts separated by a full colon,
@ -148,89 +154,98 @@ FFIILLEE FFOORRMMAATT
top-level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by at least two
spaces (or newline).
able. Because of this, they must always be followed by ttwwoo oorr mmoorree
ssppaacceess (or newline).
Account names can be aliased.
AAmmoouunnttss
After the account name, there is usually an amount. Important: between
account name and amount, there must be ttwwoo oorr mmoorree spaces.
account name and amount, there must be ttwwoo oorr mmoorree ssppaacceess.
The amount is a number, optionally with a currency symbol or commodity
name on either the left or right. Negative amounts may have the minus
sign either before or after the currency symbol (-$1 or $-1). Commod-
ity names which contain more than just letters should be enclosed in
double quotes (1 "person hours").
Amounts consist of a number and (usually) a currency symbol or commod-
ity name. Some examples:
DDeecciimmaall ppooiinnttss aanndd ddiiggiitt ggrroouuppss
hledger supports flexible decimal point and digit group separator
styles, to support international variations. Numbers can use either a
period (.) or a comma (,) as decimal point. They can also have digit
group separators at any position (eg thousands separators) which can be
comma or period - whichever one you did not use as a decimal point. If
you use digit group separators, you must also include a decimal point
in at least one number in the same commodity, so that hledger knows
which character is which. Eg, write $1,000.00 or $1.000,00.
2.00001
$1
4000 AAPL
3 "green apples"
-$1,000,000.00
INR 9,99,99,999.00
EUR -2.000.000,00
AAmmoouunntt ddiissppllaayy ssttyylleess
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in
that commodity. Amount styles include:
As you can see, the amount format is somewhat flexible:
+o the position (left or right) and spacing (space or no separator) of
the commodity symbol
+o amounts are a number (the "quantity") and optionally a currency sym-
bol/commodity name (the "commodity").
+o the digit group separator character (comma or period) and digit group
sizes, if any
+o the commodity is a symbol, word, or double-quoted phrase, on the left
or right, with or without a separating space
+o the decimal point character (period or comma)
+o negative amounts with a commodity on the left can have the minus sign
before or after it
+o the display precision (number of decimal places displayed)
+o digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods
(in which case comma is used for decimal point)
The canonical style is generally the style of the first posting amount
seen in a commodity. However the display precision will be the highest
precision seen in all posting amounts in that commmodity.
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
The precisions used in a price amount, or a D directive, don't affect
the canonical display precision directly, but they can affect it indi-
rectly, eg when D's default commodity is applied to a commodity-less
amount or when an amountless posting is balanced using a price's com-
modity (actually this last case does not influence the canonical dis-
play precision but probably should).
+o if there is a commodity directive specifying the format, that is used
+o otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of decimal
places) will be the maximum from all posting amounts in that commmod-
ity
+o or if there are no such amounts in the journal, a default format is
used (like $1000.00).
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount,
or when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, set the desired
format with a commodity directive.
VViirrttuuaall PPoossttiinnggss
When you parenthesise the account name in a posting, that posting is
considered _v_i_r_t_u_a_l, which means:
When you parenthesise the account name in a posting, we call that a
_v_i_r_t_u_a_l _p_o_s_t_i_n_g, which means:
+o it is ignored when checking that the transaction is balanced
+o it is excluded from reports when the --real/-R flag is used, or the
+o it is excluded from reports when the --real/-R flag is used, or the
real:1 query.
You could use this, eg, to set an account's opening balance without
You could use this, eg, to set an account's opening balance without
needing to use the equity:opening balances account:
1/1 special unbalanced posting to set initial balance
(assets:checking) $1000
BBaallaanncceedd VViirrttuuaall PPoossttiinnggss
When the account name is bracketed, the posting is _b_a_l_a_n_c_e_d _v_i_r_t_u_a_l,
which is just like a virtual posting except the balanced virtual post-
ings in a transaction must balance to 0, like the real postings (but
separately from them). Balanced virtual postings are also excluded by
--real/-R or real:1.
When the account name is bracketed, we call it a _b_a_l_a_n_c_e_d _v_i_r_t_u_a_l _p_o_s_t_-
_i_n_g. This is like an ordinary virtual posting except the balanced vir-
tual postings in a transaction must balance to 0, like the real post-
ings (but separately from them). Balanced virtual postings are also
excluded by --real/-R or real:1.
Virtual postings are a feature inherited from Ledger can can occasion-
ally be useful, but they can be a crutch and you should think twice or
three times before using them. You can almost always find an equiva-
lent journal entry using two or more real postings that will be more
correct and more error-proof.
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
expenses:food $10
assets:cash $-10
[assets:checking:available] $10
[assets:checking:budget:food] $-10
Virtual postings have some legitimate uses, but those are few. You can
usually find an equivalent journal entry using real postings, which is
more correct and provides better error checking.
BBaallaannccee AAsssseerrttiioonnss
hledger supports ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b
hledger supports ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b
after each posting:
2013/1/1
@ -242,48 +257,48 @@ FFIILLEE FFOORRMMAATT
b $-1 =$-2
After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
--ignore-assertions flag, which can be useful for troubleshooting or
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files.
AAsssseerrttiioonnss aanndd oorrddeerriinngg
hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif-
hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif-
ferent from Ledger, which sorts assertions only by parse order. (Also,
Ledger assertions do not see the accumulated effect of repeated post-
Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differ-
ently-dated transactions within the journal. But if you reorder
So, hledger balance assertions keep working if you reorder differ-
ently-dated transactions within the journal. But if you reorder
same-dated transactions or postings, assertions might break and require
updating. This order dependence does bring an advantage: precise con-
updating. This order dependence does bring an advantage: precise con-
trol over the order of postings and assertions within a day, so you can
assert intra-day balances.
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same
day, you'll have to put the assertion in the right file.
AAsssseerrttiioonnss aanndd ccoommmmooddiittiieess
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a par-
tial balance assertion. This is compatible with Ledger, and makes it
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a par-
tial balance assertion. This is compatible with Ledger, and makes it
possible to make assertions about accounts containing multiple commodi-
ties.
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)
AAsssseerrttiioonnss aanndd ssuubbaaccccoouunnttss
Balance assertions do not count the balance from subaccounts; they
Balance assertions do not count the balance from subaccounts; they
check the posted account's exclusive balance. For example:
1/1
@ -291,7 +306,7 @@ FFIILLEE FFOORRMMAATT
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
equity
The balance report's flat mode shows these exclusive balances more
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
@ -306,19 +321,19 @@ FFIILLEE FFOORRMMAATT
PPrriicceess
TTrraannssaaccttiioonn pprriicceess
When recording a transaction, you can also record an amount's price in
another commodity. This documents the exchange rate, cost (of a pur-
chase), or selling price (of a sale) that was in effect within this
particular transaction (or more precisely, within the particular post-
When recording a transaction, you can also record an amount's price in
another commodity. This documents the exchange rate, cost (of a pur-
chase), or selling price (of a sale) that was in effect within this
particular transaction (or more precisely, within the particular post-
ing). These transaction prices are fixed, and do not change.
Such priced amounts can be displayed in their transaction price's com-
modity, by using the --cost/-B flag (B for "cost Basis"), supported by
Such priced amounts can be displayed in their transaction price's com-
modity, by using the --cost/-B flag (B for "cost Basis"), supported by
most hledger commands.
There are three ways to specify a transaction price:
1. Write the unit price (aka exchange rate), as @ UNITPRICE after the
1. Write the unit price (aka exchange rate), as @ UNITPRICE after the
amount:
2009/1/1
@ -332,7 +347,7 @@ FFIILLEE FFOORRMMAATT
assets:cash
3. Or let hledger infer the price so as to balance the transaction. To
permit this, you must fully specify all posting amounts, and their
permit this, you must fully specify all posting amounts, and their
sum must have a non-zero amount in exactly two commodities:
2009/1/1
@ -346,17 +361,17 @@ FFIILLEE FFOORRMMAATT
assets:foreign currency $135.00
assets:cash $-135.00
Example use for transaction prices: recording the effective conversion
Example use for transaction prices: recording the effective conversion
rate of purchases made in a foreign currency.
MMaarrkkeett pprriicceess
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities, usually from some
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities, usually from some
public market which publishes such rates.
When market prices are known, the -V/--value option will use them to
convert reported amounts to their market value as of the report end
date. This option is currently available only with the balance com-
When market prices are known, the -V/--value option will use them to
convert reported amounts to their market value as of the report end
date. This option is currently available only with the balance com-
mand.
You record market prices (Ledger calls them historical prices) with a P
@ -366,7 +381,7 @@ FFIILLEE FFOORRMMAATT
P DATE COMMODITYSYMBOL UNITPRICE
For example, the following directives say that the euro's exchange rate
was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
unknown before 2009).
P 2009/1/1 ^a~ $1.35
@ -375,17 +390,17 @@ FFIILLEE FFOORRMMAATT
Example use for market prices: tracking the value of stocks.
CCoommmmeennttss
Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
to the end of the file.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Some examples:
@ -410,30 +425,30 @@ FFIILLEE FFOORRMMAATT
; a journal comment (because not indented)
TTaaggss
A _t_a_g is a word followed by a full colon inside a transaction or post-
ing comment. You can write multiple tags, comma separated. Eg:
; a comment containing sometag:, anothertag:. You can search for tags
A _t_a_g is a word followed by a full colon inside a transaction or post-
ing comment. You can write multiple tags, comma separated. Eg:
; a comment containing sometag:, anothertag:. You can search for tags
with the tag: query.
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace. (So
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace. (So
hledger tag values can not contain commas or newlines).
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (A, TAG2, third-tag, posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, this time with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
are always simple strings.
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
DDiirreeccttiivveess
AAccccoouunntt aalliiaasseess
You can define aliases which rewrite your account names (after reading
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
@ -450,8 +465,8 @@ FFIILLEE FFOORRMMAATT
See also How to use account aliases.
BBaassiicc aalliiaasseess
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -459,53 +474,53 @@ FFIILLEE FFOORRMMAATT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are full account names. hledger will replace any occur-
rence of the old account name with the new one. Subaccounts are also
OLD and NEW are full account names. hledger will replace any occur-
rence of the old account name with the new one. Subaccounts are also
affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
RReeggeexx aalliiaasseess
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in
hledger 0.24-0.25):
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Note, cur-
rently regular expression aliases may cause noticeable slow-downs.
rently regular expression aliases may cause noticeable slow-downs.
(And if you use Ledger on your hledger file, they will be ignored.) Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
MMuullttiippllee aalliiaasseess
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
1. alias directives, most recently seen first (recent directives take
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
eenndd aalliiaasseess
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
aaccccoouunntt ddiirreeccttiivvee
The account directive predefines account names, as in Ledger and Bean-
count. This may be useful for your own documentation; hledger doesn't
The account directive predefines account names, as in Ledger and Bean-
count. This may be useful for your own documentation; hledger doesn't
make use of it yet.
; account ACCT
@ -520,8 +535,8 @@ FFIILLEE FFOORRMMAATT
; etc.
aappppllyy aaccccoouunntt ddiirreeccttiivvee
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@ -538,7 +553,7 @@ FFIILLEE FFOORRMMAATT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -547,47 +562,50 @@ FFIILLEE FFOORRMMAATT
apply account personal
include personal.journal
Prior to hledger 0.28, legacy account and end spellings were also sup-
Prior to hledger 0.28, legacy account and end spellings were also sup-
ported.
MMuullttii--lliinnee ccoommmmeennttss
A line containing just comment starts a multi-line comment, and a line
A line containing just comment starts a multi-line comment, and a line
containing just end comment ends it. See comments.
ccoommmmooddiittyy ddiirreeccttiivvee
The commodity directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated,
; using period as decimal point, with four decimal places, and
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
; format EXAMPLEAMOUNT
; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated,
; period as decimal point, and two decimal places.
commodity INR
format INR 9,99,99,999.00
DDeeffaauulltt ccoommmmooddiittyy
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount. The commodity (and the sam-
ple amount's display style) will be applied to all subsequent commod-
ity-less amounts, up to the next D directive. (Note this is different
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount. The commodity (and the sam-
ple amount's display format) will be applied to all subsequent commod-
ity-less amounts, up to the next D directive. (Note this is different
from Ledger's default commodity directive.)
Also note the directive itself does not influence the commodity's
default display style, but the amount it is applied to might. Here's
an example:
; set ^A-L as the default commodity
D ^A-L1,000.00
2010/1/1
a 2340
b
2014/1/1
c ^A-L1000
d
$ hledger print
2010/01/01
a ^A-L2,340.00
b ^A-L-2,340.00
2014/01/01
c ^A-L1,000.00
d ^A-L-1,000.00
DDeeffaauulltt yyeeaarr
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -607,19 +625,16 @@ FFIILLEE FFOORRMMAATT
assets
IInncclluuddiinngg ootthheerr ffiilleess
You can pull in the content of additional journal files by writing an
You can pull in the content of additional journal files by writing an
include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file.
If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported.
Glob patterns (*) are not currently supported.
The include directive may only be used in journal files, and currently
it may only include other journal files (eg, not CSV or timeclock
files.)
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
EEDDIITTOORR SSUUPPPPOORRTT
Add-on modes exist for various text editors, to make working with jour-
@ -665,4 +680,4 @@ SSEEEE AALLSSOO
April 2016 hledger_journal(5)
May 2016 hledger_journal(5)

2
hledger-lib/doc/hledger_timeclock.5
View File

@ -11,7 +11,7 @@ Timeclock \- the time logging format of timeclock.el, as read by hledger
hledger can read timeclock files.
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.
The date is a simple date (also, default year directives work).
The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ].
Seconds and timezone are optional.
The timezone, if present, must be four digits and is ignored (currently

8
hledger-lib/doc/hledger_timeclock.5.info
View File

@ -9,10 +9,10 @@ hledger_timeclock(5)
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as
in the example below. The date is a simple date (also, default year
directives work). The time format is HH:MM[:SS][+-ZZZZ]. Seconds and
timezone are optional. The timezone, if present, must be four digits and
is ignored (currently the time is always interpreted as a local time).
in the example below. The date is a simple date. The time format is
HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, if
present, must be four digits and is ignored (currently the time is
always interpreted as a local time).
i 2015/03/30 09:00:00 some:account name optional description after two spaces

23
hledger-lib/doc/hledger_timeclock.5.txt
View File

@ -9,20 +9,19 @@ NNAAMMEE
DDEESSCCRRIIPPTTIIOONN
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as
in the example below. The date is a simple date (also, default year
directives work). The time format is HH:MM[:SS][+-ZZZZ]. Seconds and
timezone are optional. The timezone, if present, must be four digits
and is ignored (currently the time is always interpreted as a local
time).
in the example below. The date is a simple date. The time format is
HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone,
if present, must be four digits and is ignored (currently the time is
always interpreted as a local time).
i 2015/03/30 09:00:00 some:account name optional description after two spaces
o 2015/03/30 09:20:00
i 2015/03/31 22:21:45 another account
o 2015/04/01 02:00:34
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account. Or if the session spans more than
one day, it is split into several transactions, one for each day. For
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account. Or if the session spans more than
one day, it is split into several transactions, one for each day. For
the above time log, hledger print generates these journal entries:
$ hledger -f t.timeclock print
@ -43,7 +42,7 @@ DDEESSCCRRIIPPTTIIOONN
To generate time logs, ie to clock in and clock out, you could:
+o use emacs and the built-in timeclock.el, or the extended time-
+o use emacs and the built-in timeclock.el, or the extended time-
clock-x.el and perhaps the extras in ledgerutils.el
+o at the command line, use these bash aliases:
@ -52,13 +51,13 @@ DDEESSCCRRIIPPTTIIOONN
alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
+o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2
rely on a "timeclock" executable which I think is just the ledger 2
executable renamed.
RREEPPOORRTTIINNGG BBUUGGSS
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)
@ -72,7 +71,7 @@ CCOOPPYYRRIIGGHHTT
SSEEEE AALLSSOO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

2
hledger-lib/doc/hledger_timedot.5
View File

@ -120,8 +120,6 @@ $\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4
\f[]
.fi
.PP
default year directives may be used.
.PP
Here is a sample.timedot.

2
hledger-lib/doc/hledger_timedot.5.info
View File

@ -109,8 +109,6 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
--------------------
4.50
default year directives may be used.
Here is a sample.timedot.

2
hledger-lib/doc/hledger_timedot.5.txt
View File

@ -93,8 +93,6 @@ FFIILLEE FFOORRMMAATT
--------------------
4.50
default year directives may be used.
Here is a sample.timedot.

4
hledger-ui/doc/hledger-ui.1
View File

@ -139,8 +139,8 @@ set start date, end date, and/or reporting interval all at once
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.B \f[C]\-\-date2\f[]
show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS
.RE
.TP

28
hledger-ui/doc/hledger-ui.1.info
View File

@ -106,8 +106,8 @@ The following common hledger options should also work:
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
`--date2 --aux-date'
use postings/txns' secondary dates instead
`--date2'
show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared'
include only cleared postings/txns
@ -273,17 +273,17 @@ Node: OPTIONS682
Ref: #options781
Node: hledger options1547
Ref: #hledger-options1653
Node: KEYS2829
Ref: #keys2926
Node: SCREENS3323
Ref: #screens3410
Node: Accounts screen3500
Ref: #accounts-screen3630
Node: Register screen4475
Ref: #register-screen4632
Node: Transaction screen6014
Ref: #transaction-screen6174
Node: Error screen7041
Ref: #error-screen7165
Node: KEYS2836
Ref: #keys2933
Node: SCREENS3330
Ref: #screens3417
Node: Accounts screen3507
Ref: #accounts-screen3637
Node: Register screen4482
Ref: #register-screen4639
Node: Transaction screen6021
Ref: #transaction-screen6181
Node: Error screen7048
Ref: #error-screen7172

End Tag Table

4
hledger-ui/doc/hledger-ui.1.txt
View File

@ -94,8 +94,8 @@ OOPPTTIIOONNSS
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee
use postings/txns' secondary dates instead
----ddaattee22
show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd
include only cleared postings/txns

12
hledger-web/doc/hledger-web.1
View File

@ -73,8 +73,14 @@ Note there is no built\-in access control, 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
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.
.PP
With journal and timeclock files (but not CSV files, currently) the web
app detects changes and will show the new data on the next request.
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
@ -178,8 +184,8 @@ set start date, end date, and/or reporting interval all at once
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.B \f[C]\-\-date2\f[]
show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS
.RE
.TP

22
hledger-web/doc/hledger-web.1.info
View File

@ -51,10 +51,14 @@ the PORT in the base url.
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 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.
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:
@ -139,8 +143,8 @@ The following common hledger options should also work:
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
`--date2 --aux-date'
use postings/txns' secondary dates instead
`--date2'
show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared'
include only cleared postings/txns
@ -167,9 +171,9 @@ The following common hledger options should also work:

Tag Table:
Node: Top90
Node: OPTIONS2622
Ref: #options2709
Node: hledger options3572
Ref: #hledger-options3679
Node: OPTIONS2834
Ref: #options2921
Node: hledger options3784
Ref: #hledger-options3891

End Tag Table

14
hledger-web/doc/hledger-web.1.txt
View File

@ -61,10 +61,14 @@ DDEESSCCRRIIPPTTIIOONN
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 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.
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.
OOPPTTIIOONNSS
Note: if invoking hledger-web as a hledger subcommand, write -- before
@ -128,8 +132,8 @@ OOPPTTIIOONNSS
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee
use postings/txns' secondary dates instead
----ddaattee22
show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd
include only cleared postings/txns

69
hledger/doc/hledger.1
View File

@ -142,6 +142,27 @@ $\ hledger\ print\ desc:shop\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transacti
$\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
\f[]
.fi
.PP
With the journal
.IP
.nf
\f[C]
2016/02/16\ Member\ Fee\ Payment\ John\ Doe
\ \ \ \ assets:bank\ account\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
\ \ \ \ income:member\ fees\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\ \ \ \ \ \ ;\ member:\ John\ Doe
\f[]
.fi
.PP
the \-\-pivot comand will output the following:
.IP
.nf
\f[C]
$\ hledger\ bal\ \-\-pivot\ member
\ \ \ \ 2\ EUR\ \ assets:bank\ account
\ \ \ \-2\ EUR\ \ member:John\ Doe
\f[]
.fi
.SH OPTIONS
.PP
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just
@ -269,8 +290,8 @@ set start date, end date, and/or reporting interval all at once
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.B \f[C]\-\-date2\f[]
show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS
.RE
.TP
@ -308,12 +329,27 @@ show empty/zero things which are normally omitted
show amounts in their cost price\[aq]s commodity
.RS
.RE
.TP
.B `\-\-pivot TAG
will transform the journal before any other processing by replacing the
account name of every posting having the tag TAG with content VALUE by
the account name "TAG:VALUE".
.RS
.RE
The TAG will only match if it is a full\-length match.
The pivot will only happen if the TAG is on a posting, not if it is on
the transaction.
If the tag value is a multi:level:account:name the new account name will
be "TAG:multi:level:account:name".
.RS
.RE
.SS Multiple files
.PP
One may specify the \f[C]\-\-file\ FILE\f[] option multiple times.
This is equivalent to concatenating the files to standard input and
passing \f[C]\-\-file\ \-\f[], except that the add command functions
normally and adds entries to the first specified file.
You can specify multiple \f[C]\-f/\-\-file\ FILE\f[] options.
This is like combining all the files into one, except they can have
different formats.
Also directives and aliases in one file do not affect subsequent files
(if you need that, use the include directive instead).
.SS Repeated options
.PP
Otherwise, if a reporting option is repeated, the last one takes
@ -657,13 +693,16 @@ match transaction descriptions
.RE
.TP
.B \f[B]\f[C]date:PERIODEXPR\f[]\f[]
match dates within the specified period (which should not include a
reporting interval
match dates within the specified period.
PERIODEXPR should not include a reporting interval.
The command\-line \f[C]\-\-date2\f[] flag makes this match secondary
dates instead (like the \f[C]\-b\f[]/\f[C]\-e\f[]/\f[C]\-p\f[] options).
.RS
.RE
.TP
.B \f[B]\f[C]date2:PERIODEXPR\f[]\f[]
as above, but match secondary dates
match secondary dates within the specified period.
PERIODEXPR should not include a reporting interval.
.RS
.RE
.TP
@ -695,8 +734,6 @@ transaction.
before any of the above negates the match.
.RS
.RE
.PP
* * * * *
.PP
Some of these can also be expressed as command\-line options (eg
\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]).
@ -827,8 +864,9 @@ Many hledger users edit their journals directly with a text editor, or
generate them from CSV.
For more interactive data entry, there is the \f[C]add\f[] command,
which prompts interactively on the console for new transactions, and
appends them to the journal file (existing transactions are not
changed).
appends them to the journal file (if there are multiple
\f[C]\-f\ FILE\f[] options, the first file is used.) Existing
transactions are not changed.
This is the only hledger command that writes to the journal file.
.PP
To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
@ -2103,6 +2141,11 @@ $\ LEDGER_FILE=unique.journal\ hledger\ print\-unique
.PP
Prints all journal entries, adding specified custom postings to matched
entries.
.PP
hledger\-rewrite.hs, in hledger\[aq]s extra directory (compilation
optional), adds postings to existing transactions, optionally with an
amount based on the existing transaction\[aq]s first amount.
See the script for more details.
.IP
.nf
\f[C]

242
hledger/doc/hledger.1.info
View File

@ -114,6 +114,21 @@ $ hledger reg 'assets:some bank:checking' # show postings to/from this checking
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
With the journal
2016/02/16 Member Fee Payment John Doe
assets:bank account 2 EUR
income:member fees -2 EUR
; member: John Doe
the -pivot comand will output the following:
$ hledger bal --pivot member
2 EUR assets:bank account
-2 EUR member:John Doe

File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
@ -204,8 +219,8 @@ command name.
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
`--date2 --aux-date'
use postings/txns' secondary dates instead
`--date2'
show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared'
include only cleared postings/txns
@ -228,6 +243,15 @@ command name.
`-B --cost'
show amounts in their cost price's commodity
`-pivot TAG
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG will
only match if it is a full-length match. The pivot will only
happen if the TAG is on a posting, not if it is on the transaction.
If the tag value is a multi:level:account:name the new account
name will be "TAG:multi:level:account:name".
* Menu:
* Multiple files::
@ -244,10 +268,10 @@ File: hledger.1.info, Node: Multiple files, Next: Repeated options, Up: OPTIO
2.1 Multiple files
==================
One may specify the `--file FILE' option multiple times. This is
equivalent to concatenating the files to standard input and passing
`--file -', except that the add command functions normally and adds
entries to the first specified file.
You can specify multiple `-f/--file FILE' options. This is like
combining all the files into one, except they can have different
formats. Also directives and aliases in one file do not affect
subsequent files (if you need that, use the include directive instead).

File: hledger.1.info, Node: Repeated options, Next: Depth limiting, Prev: Multiple files, Up: OPTIONS
@ -480,11 +504,14 @@ match (or negatively match)
match transaction descriptions
*`date:PERIODEXPR'*
match dates within the specified period (which should not include a
reporting interval
match dates within the specified period. PERIODEXPR should not
include a reporting interval. The command-line `--date2' flag
makes this match secondary dates instead (like the `-b'/`-e'/`-p'
options).
*`date2:PERIODEXPR'*
as above, but match secondary dates
match secondary dates within the specified period. PERIODEXPR
should not include a reporting interval.
*`depth:N'*
match (or display, depending on command) accounts at or above this
@ -506,8 +533,7 @@ match (or negatively match)
*`not:'*
before any of the above negates the match.
-----------------------------------------------------------------------
Some of these can also be expressed as command-line options (eg
Some of these can also be expressed as command-line options (eg
`depth:2' is equivalent to `--depth 2'). Generally you can mix options
and query arguments, and the resulting query will be their intersection
(perhaps excluding the `-p/--period' option).
@ -648,8 +674,9 @@ Prompt for transactions and add them to the journal.
Many hledger users edit their journals directly with a text editor,
or generate them from CSV. For more interactive data entry, there is the
`add' command, which prompts interactively on the console for new
transactions, and appends them to the journal file (existing
transactions are not changed). This is the only hledger command that
transactions, and appends them to the journal file (if there are
multiple `-f FILE' options, the first file is used.) Existing
transactions are not changed. This is the only hledger command that
writes to the journal file.
To use it, just run `hledger add' and follow the prompts. You can
@ -1877,6 +1904,11 @@ File: hledger.1.info, Node: rewrite, Next: ui, Prev: print-unique, Up: ADD-O
Prints all journal entries, adding specified custom postings to matched
entries.
hledger-rewrite.hs, in hledger's extra directory (compilation
optional), adds postings to existing transactions, optionally with an
amount based on the existing transaction's first amount. See the script
for more details.
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
@ -2009,97 +2041,97 @@ Tag Table:
Node: Top82
Node: EXAMPLES1754
Ref: #examples1856
Node: OPTIONS3508
Ref: #options3612
Node: Multiple files6386
Ref: #multiple-files6511
Node: Repeated options6750
Ref: #repeated-options6902
Node: Depth limiting7022
Ref: #depth-limiting7167
Node: Smart dates7368
Ref: #smart-dates7509
Node: Reporting interval8506
Ref: #reporting-interval8665
Node: Period expressions9008
Ref: #period-expressions9175
Node: Regular Expressions11221
Ref: #regular-expressions11363
Node: QUERIES12846
Ref: #queries12950
Node: COMMANDS16125
Ref: #commands16239
Node: accounts16912
Ref: #accounts17012
Node: activity17994
Ref: #activity18106
Node: add18465
Ref: #add18566
Node: balance21160
Ref: #balance21273
Node: Flat mode23989
Ref: #flat-mode24116
Node: Depth limited balance reports24535
Ref: #depth-limited-balance-reports24738
Node: Multicolumn balance reports25159
Ref: #multicolumn-balance-reports25361
Node: Market value30010
Ref: #market-value30174
Node: Custom balance output30667
Ref: #custom-balance-output30840
Node: Output destination32944
Ref: #output-destination33109
Node: CSV output33379
Ref: #csv-output33498
Node: balancesheet33895
Ref: #balancesheet34023
Node: cashflow34675
Ref: #cashflow34792
Node: help35482
Ref: #help35594
Node: incomestatement36431
Ref: #incomestatement36561
Node: info37288
Ref: #info37395
Node: man37757
Ref: #man37854
Node: print38257
Ref: #print38362
Node: register39713
Ref: #register39826
Node: Custom register output44167
Ref: #custom-register-output44298
Node: stats45595
Ref: #stats45701
Node: test46582
Ref: #test46669
Node: ADD-ON COMMANDS47036
Ref: #add-on-commands47172
Node: api48460
Ref: #api48552
Node: autosync48586
Ref: #autosync48701
Node: diff51016
Ref: #diff51126
Node: equity51790
Ref: #equity51904
Node: interest53232
Ref: #interest53349
Node: irr56433
Ref: #irr56546
Node: print-unique58921
Ref: #print-unique59051
Node: rewrite59309
Ref: #rewrite59428
Node: ui59731
Ref: #ui59831
Node: web59872
Ref: #web59960
Node: TROUBLESHOOTING59993
Ref: #troubleshooting60112
Node: Run-time problems60166
Ref: #run-time-problems60309
Node: Known limitations62253
Ref: #known-limitations62396
Node: OPTIONS3860
Ref: #options3964
Node: Multiple files7217
Ref: #multiple-files7342
Node: Repeated options7607
Ref: #repeated-options7759
Node: Depth limiting7879
Ref: #depth-limiting8024
Node: Smart dates8225
Ref: #smart-dates8366
Node: Reporting interval9363
Ref: #reporting-interval9522
Node: Period expressions9865
Ref: #period-expressions10032
Node: Regular Expressions12078
Ref: #regular-expressions12220
Node: QUERIES13703
Ref: #queries13807
Node: COMMANDS17109
Ref: #commands17223
Node: accounts17896
Ref: #accounts17996
Node: activity18978
Ref: #activity19090
Node: add19449
Ref: #add19550
Node: balance22209
Ref: #balance22322
Node: Flat mode25038
Ref: #flat-mode25165
Node: Depth limited balance reports25584
Ref: #depth-limited-balance-reports25787
Node: Multicolumn balance reports26208
Ref: #multicolumn-balance-reports26410
Node: Market value31059
Ref: #market-value31223
Node: Custom balance output31716
Ref: #custom-balance-output31889
Node: Output destination33993
Ref: #output-destination34158
Node: CSV output34428
Ref: #csv-output34547
Node: balancesheet34944
Ref: #balancesheet35072
Node: cashflow35724
Ref: #cashflow35841
Node: help36531
Ref: #help36643
Node: incomestatement37480
Ref: #incomestatement37610
Node: info38337
Ref: #info38444
Node: man38806
Ref: #man38903
Node: print39306
Ref: #print39411
Node: register40762
Ref: #register40875
Node: Custom register output45216
Ref: #custom-register-output45347
Node: stats46644
Ref: #stats46750
Node: test47631
Ref: #test47718
Node: ADD-ON COMMANDS48085
Ref: #add-on-commands48221
Node: api49509
Ref: #api49601
Node: autosync49635
Ref: #autosync49750
Node: diff52065
Ref: #diff52175
Node: equity52839
Ref: #equity52953
Node: interest54281
Ref: #interest54398
Node: irr57482
Ref: #irr57595
Node: print-unique59970
Ref: #print-unique60100
Node: rewrite60358
Ref: #rewrite60477
Node: ui61006
Ref: #ui61106
Node: web61147
Ref: #web61235
Node: TROUBLESHOOTING61268
Ref: #troubleshooting61387
Node: Run-time problems61441
Ref: #run-time-problems61584
Node: Known limitations63528
Ref: #known-limitations63671

End Tag Table

429
hledger/doc/hledger.1.txt
View File

@ -103,6 +103,19 @@ EEXXAAMMPPLLEESS
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
With the journal
2016/02/16 Member Fee Payment John Doe
assets:bank account 2 EUR
income:member fees -2 EUR
; member: John Doe
the --pivot comand will output the following:
$ hledger bal --pivot member
2 EUR assets:bank account
-2 EUR member:John Doe
OOPPTTIIOONNSS
To see general usage and the command list: hledger -h or just hledger
@ -181,8 +194,8 @@ OOPPTTIIOONNSS
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee
use postings/txns' secondary dates instead
----ddaattee22
show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd
include only cleared postings/txns
@ -205,156 +218,165 @@ OOPPTTIIOONNSS
--BB ----ccoosstt
show amounts in their cost price's commodity
``----ppiivvoott TTAAGG
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE".
The TAG will only match if it is a full-length match. The pivot will
only happen if the TAG is on a posting, not if it is on the transac-
tion. If the tag value is a multi:level:account:name the new account
name will be "TAG:multi:level:account:name".
MMuullttiippllee ffiilleess
One may specify the --file FILE option multiple times. This is equiva-
lent to concatenating the files to standard input and passing --file -,
except that the add command functions normally and adds entries to the
first specified file.
You can specify multiple -f/--file FILE options. This is like combin-
ing all the files into one, except they can have different formats.
Also directives and aliases in one file do not affect subsequent files
(if you need that, use the include directive instead).
RReeppeeaatteedd ooppttiioonnss
Otherwise, if a reporting option is repeated, the last one takes prece-
dence. Eg -p jan -p feb is equivalent to -p feb.
DDeepptthh lliimmiittiinngg
With the --depth N option, commands like account, balance and register
will show only the uppermost accounts in the account tree, down to
With the --depth N option, commands like account, balance and register
will show only the uppermost accounts in the account tree, down to
level N. Use this when you want a summary with less detail.
SSmmaarrtt ddaatteess
hledger's user interfaces accept a flexible "smart date" syntax (unlike
dates in the journal file). Smart dates allow some english words, can
be relative to today's date, and can have less-significant date parts
dates in the journal file). Smart dates allow some english words, can
be relative to today's date, and can have less-significant date parts
omitted (defaulting to 1).
Examples:
tab(@); l l. T{ 2009/1/1, 2009/01/01, 2009-1-1, 2009.1.1 T}@T{ simple
dates, several separators allowed T} T{ 2009/1, 2009 T}@T{ same as
above - a missing day or month defaults to 1 T} T{ 1/1, january, jan,
this year T}@T{ relative dates, meaning january 1 of the current year
tab(@); l l. T{ 2009/1/1, 2009/01/01, 2009-1-1, 2009.1.1 T}@T{ simple
dates, several separators allowed T} T{ 2009/1, 2009 T}@T{ same as
above - a missing day or month defaults to 1 T} T{ 1/1, january, jan,
this year T}@T{ relative dates, meaning january 1 of the current year
T} T{ next year T}@T{ january 1 of next year T} T{ this month T}@T{ the
1st of the current month T} T{ this week T}@T{ the most recent monday
T} T{ last week T}@T{ the monday of the week before this one T} T{
lastweek T}@T{ spaces are optional T} T{ today, yesterday, tomorrow
1st of the current month T} T{ this week T}@T{ the most recent monday
T} T{ last week T}@T{ the monday of the week before this one T} T{
lastweek T}@T{ spaces are optional T} T{ today, yesterday, tomorrow
T}@T{ T}
RReeppoorrttiinngg iinntteerrvvaall
A reporting interval can be specified so that commands like register,
balance and activity will divide their reports into multiple report
periods. The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
A reporting interval can be specified so that commands like register,
balance and activity will divide their reports into multiple report
periods. The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
plex intervals may be specified with a period expression.
PPeerriioodd eexxpprreessssiioonnss
The -p/--period option accepts period expressions, a shorthand way of
expressing a start date, end date, and or reporting interval all at
once. Note a period expression on the command line will cause any
The -p/--period option accepts period expressions, a shorthand way of
expressing a start date, end date, and or reporting interval all at
once. Note a period expression on the command line will cause any
other date flags (-b/-e/-D/-W/-M/-Q/-Y) to be ignored.
hledger's period expressions are similar to Ledger's, though not iden-
tical. Here's a basic period expression specifying the first quarter
of 2009. Note, hledger always treats start dates as inclusive and end
hledger's period expressions are similar to Ledger's, though not iden-
tical. Here's a basic period expression specifying the first quarter
of 2009. Note, hledger always treats start dates as inclusive and end
dates as exclusive:
-p "from 2009/1/1 to 2009/4/1"
Keywords like "from" and "to" are optional, and so are the spaces, as
long as you don't run two dates together. "to" can also be written as
Keywords like "from" and "to" are optional, and so are the spaces, as
long as you don't run two dates together. "to" can also be written as
"-". These are equivalent to the above:
tab(@); l. T{ -p "2009/1/1 2009/4/1" T} T{ -p2009/1/1to2009/4/1 T} T{
tab(@); l. T{ -p "2009/1/1 2009/4/1" T} T{ -p2009/1/1to2009/4/1 T} T{
-p2009/1/1-2009/4/1 T}
Dates are smart dates, so if the current year is 2009, the above can
Dates are smart dates, so if the current year is 2009, the above can
also be written as:
tab(@); l. T{ -p "1/1 4/1" T} T{ -p "january-apr" T} T{
tab(@); l. T{ -p "1/1 4/1" T} T{ -p "january-apr" T} T{
-p "this year to 4/1" T}
If you specify only one date, the missing start or end date will be the
earliest or latest transaction in your journal:
tab(@); l l. T{ -p "from 2009/1/1" T}@T{ everything after january 1,
2009 T} T{ -p "from 2009/1" T}@T{ the same T} T{ -p "from 2009" T}@T{
tab(@); l l. T{ -p "from 2009/1/1" T}@T{ everything after january 1,
2009 T} T{ -p "from 2009/1" T}@T{ the same T} T{ -p "from 2009" T}@T{
the same T} T{ -p "to 2009" T}@T{ everything before january 1, 2009 T}
A single date with no "from" or "to" defines both the start and end
A single date with no "from" or "to" defines both the start and end
date like so:
tab(@); l l. T{ -p "2009" T}@T{ the year 2009; equivalent to "2009/1/1
to 2010/1/1" T} T{ -p "2009/1" T}@T{ the month of jan; equivalent to
to 2010/1/1" T} T{ -p "2009/1" T}@T{ the month of jan; equivalent to
"2009/1/1 to 2009/2/1" T} T{ -p "2009/1/1" T}@T{ just that day; equiva-
lent to "2009/1/1 to 2009/1/2" T}
Period expressions can also start with (or be) a reporting interval:
daily, weekly, monthly, quarterly, yearly, or one of the every ...
expressions below. Optionally the word in may appear between the
Period expressions can also start with (or be) a reporting interval:
daily, weekly, monthly, quarterly, yearly, or one of the every ...
expressions below. Optionally the word in may appear between the
reporting interval and the start/end dates. Examples:
tab(@); l. T{ -p "weekly from 2009/1/1 to 2009/4/1" T} T{
-p "monthly in 2008" T} T{ -p "bimonthly from 2008" T} T{ -p "quar-
terly" T} T{ -p "every 2 weeks" T} T{ -p "every 5 days from 1/3" T} T{
tab(@); l. T{ -p "weekly from 2009/1/1 to 2009/4/1" T} T{
-p "monthly in 2008" T} T{ -p "bimonthly from 2008" T} T{ -p "quar-
terly" T} T{ -p "every 2 weeks" T} T{ -p "every 5 days from 1/3" T} T{
-p "every 15th day of month" T} T{ -p "every 4th day of week" T}
RReegguullaarr EExxpprreessssiioonnss
hledger uses regular expressions in a number of places:
+o query terms, on the command line and in the hledger-web search form:
+o query terms, on the command line and in the hledger-web search form:
REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
+o CSV rules conditional blocks: if REGEX ...
+o account alias directives and options: alias /REGEX/ = REPLACEMENT,
+o account alias directives and options: alias /REGEX/ = REPLACEMENT,
--alias /REGEX/=REPLACEMENT
hledger's regular expressions come from the regex-tdfa library. In
hledger's regular expressions come from the regex-tdfa library. In
general they:
+o are case insensitive
+o are infix matching (do not need to match the entire thing being
+o are infix matching (do not need to match the entire thing being
matched)
+o are POSIX extended regular expressions
+o also support GNU word boundaries (\<, \>, \b, \B)
+o and parenthesised capturing groups and numeric backreferences in
+o and parenthesised capturing groups and numeric backreferences in
replacement strings
+o do not support mode modifiers like (?s)
Some things to note:
+o In the alias directive and --alias option, regular expressions must
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
+o In the alias directive and --alias option, regular expressions must
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
these are not required.
+o To match a regular expression metacharacter like $ as a literal char-
acter, prepend a backslash. Eg to search for amounts with the dollar
sign in hledger-web, write cur:\$.
+o On the command line, some metacharacters like $ have a special mean-
+o On the command line, some metacharacters like $ have a special mean-
ing to the shell and so must be escaped a second time, with single or
double quotes or another backslash. Eg, to match amounts with the
double quotes or another backslash. Eg, to match amounts with the
dollar sign from the command line, write cur:'\$' or cur:\\$.
QQUUEERRIIEESS
One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres-
sion, written as arguments after the command name, to filter the data
by date, account name or other criteria. The syntax is similar to a
One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres-
sion, written as arguments after the command name, to filter the data
by date, account name or other criteria. The syntax is similar to a
web search: one or more space-separated search terms, quotes to enclose
whitespace, optional prefixes to match specific fields. Multiple
whitespace, optional prefixes to match specific fields. Multiple
search terms are combined as follows:
All commands except print: show transactions/postings/accounts which
All commands except print: show transactions/postings/accounts which
match (or negatively match)
+o any of the description terms AND
@ -381,22 +403,22 @@ QQUUEERRIIEESS
same as above
aammtt::NN,, aammtt::<<NN,, aammtt::<<==NN,, aammtt::>>NN,, aammtt::>>==NN
match postings with a single-commodity amount that is equal to,
less than, or greater than N. (Multi-commodity amounts are not
match postings with a single-commodity amount that is equal to,
less than, or greater than N. (Multi-commodity amounts are not
tested, and will always match.) The comparison has two modes: if
N is preceded by a + or - sign (or is 0), the two signed numbers
are compared. Otherwise, the absolute magnitudes are compared,
are compared. Otherwise, the absolute magnitudes are compared,
ignoring sign.
ccooddee::RREEGGEEXX
match by transaction code (eg check number)
ccuurr::RREEGGEEXX
match postings or transactions including any amounts whose cur-
rency/commodity symbol is fully matched by REGEX. (For a par-
match postings or transactions including any amounts whose cur-
rency/commodity symbol is fully matched by REGEX. (For a par-
tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend
\. And when using the command line you need to add one more
\. And when using the command line you need to add one more
level of quoting to hide it from the shell, so eg do:
hledger print cur:'\$' or hledger print cur:\\$.
@ -404,11 +426,14 @@ QQUUEERRIIEESS
match transaction descriptions
ddaattee::PPEERRIIOODDEEXXPPRR
match dates within the specified period (which should not
include a reporting interval
match dates within the specified period. PERIODEXPR should not
include a reporting interval. The command-line --date2 flag
makes this match secondary dates instead (like the -b/-e/-p
options).
ddaattee22::PPEERRIIOODDEEXXPPRR
as above, but match secondary dates
match secondary dates within the specified period. PERIODEXPR
should not include a reporting interval.
ddeepptthh::NN
match (or display, depending on command) accounts at or above
@ -429,8 +454,6 @@ QQUUEERRIIEESS
nnoott:: before any of the above negates the match.
* * * * *
Some of these can also be expressed as command-line options (eg depth:2
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
@ -529,17 +552,18 @@ CCOOMMMMAANNDDSS
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (existing transactions
are not changed). This is the only hledger command that writes to the
journal file.
actions, and appends them to the journal file (if there are multiple
-f FILE options, the first file is used.) Existing transactions are not
changed. This is the only hledger command that writes to the journal
file.
To use it, just run hledger add and follow the prompts. You can add as
many transactions as you like; when you are finished, enter . or press
many transactions as you like; when you are finished, enter . or press
control-d or control-c to exit.
Features:
+o add tries to provide useful defaults, using the most similar recent
+o add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
+o You can also set the initial defaults with command line arguments.
@ -547,20 +571,20 @@ CCOOMMMMAANNDDSS
+o Readline-style edit keys can be used during data entry.
+o The tab key will auto-complete whenever possible - accounts, descrip-
tions, dates (yesterday, today, tomorrow). If the input area is
tions, dates (yesterday, today, tomorrow). If the input area is
empty, it will insert the default value.
+o If the journal defines a default commodity, it will be added to any
+o If the journal defines a default commodity, it will be added to any
bare numbers entered.
+o A parenthesised transaction code may be entered following a date.
+o Comments and tags may be entered following a description or amount.
+o If you make a mistake, enter < at any prompt to restart the transac-
+o If you make a mistake, enter < at any prompt to restart the transac-
tion.
+o Input prompts are displayed in a different colour when the terminal
+o Input prompts are displayed in a different colour when the terminal
supports it.
Example (see the tutorial for a detailed explanation):
@ -632,7 +656,7 @@ CCOOMMMMAANNDDSS
--OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT
select the output format. Supported formats: txt, csv.
The balance command displays accounts and balances. It is hledger's
The balance command displays accounts and balances. It is hledger's
most featureful and most useful command.
$ hledger balance
@ -649,24 +673,24 @@ CCOOMMMMAANNDDSS
--------------------
0
More precisely, the balance command shows the _c_h_a_n_g_e to each account's
More precisely, the balance command shows the _c_h_a_n_g_e to each account's
balance caused by all (matched) postings. In the common case where you
do not filter by date and your journal sets the correct opening bal-
do not filter by date and your journal sets the correct opening bal-
ances, this is the same as the account's ending balance.
By default, accounts are displayed hierarchically, with subaccounts
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. "Boring" accounts, which contain a single
interesting subaccount and no balance of their own, are elided into the
following line for more compact output. (Use --no-elide to prevent
following line for more compact output. (Use --no-elide to prevent
this.)
Each account's balance is the "inclusive" balance - it includes the
Each account's balance is the "inclusive" balance - it includes the
balances of any subaccounts.
Accounts which have zero balance (and no non-zero subaccounts) are
Accounts which have zero balance (and no non-zero subaccounts) are
omitted. Use -E/--empty to show them.
A final total is displayed by default; use -N/--no-total to suppress
A final total is displayed by default; use -N/--no-total to suppress
it:
$ hledger balance -p 2008/6 expenses --no-total
@ -676,9 +700,9 @@ CCOOMMMMAANNDDSS
FFllaatt mmooddee
To see a flat list of full account names instead of the default hierar-
chical display, use --flat. In this mode, accounts (unless
chical display, use --flat. In this mode, accounts (unless
depth-clipped) show their "exclusive" balance, excluding any subaccount
balances. In this mode, you can also use --drop N to omit the first
balances. In this mode, you can also use --drop N to omit the first
few account name components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
@ -686,9 +710,9 @@ CCOOMMMMAANNDDSS
$1 supplies
DDeepptthh lliimmiitteedd bbaallaannccee rreeppoorrttss
With --depth N, balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less
detail. In flat mode, balances from accounts below the depth limit
With --depth N, balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less
detail. In flat mode, balances from accounts below the depth limit
will be shown as part of a parent account at the depth limit.
$ hledger balance -N --depth 1
@ -698,12 +722,12 @@ CCOOMMMMAANNDDSS
$1 liabilities
MMuullttiiccoolluummnn bbaallaannccee rreeppoorrttss
With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column balance
With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column balance
report, showing different information:
1. By default: each column shows the sum of postings in that period, ie
the account's change of balance in that period. This is useful eg
the account's change of balance in that period. This is useful eg
for a monthly income statement:
$ hledger balance --quarterly income expenses -E
@ -718,8 +742,8 @@ CCOOMMMMAANNDDSS
-------------------++---------------------------------
|| $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
the report start date:
$ hledger balance --quarterly income expenses -E --cumulative
@ -735,8 +759,8 @@ CCOOMMMMAANNDDSS
|| $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending
balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is
balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is
useful eg for a multi-period balance sheet, and when you are showing
only the data after a certain start date:
@ -752,26 +776,26 @@ CCOOMMMMAANNDDSS
----------------------++-------------------------------------
|| 0 0 0
Multi-column balance reports display accounts in flat mode by default;
Multi-column balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
the displayed report periods. This is so that the first and last peri-
ods will be "full" and comparable to the others.
The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
report period (use -E to include low-activity accounts which would oth-
erwise would be omitted).
The -T/--row-total flag adds an additional column showing the total for
each row.
The -A/--average flag adds a column showing the average value in each
The -A/--average flag adds a column showing the average value in each
row.
Here's an example of all three:
@ -794,16 +818,16 @@ CCOOMMMMAANNDDSS
MMaarrkkeett vvaalluuee
The -V/--value flag converts all the reported amounts to their "current
market value" using their default market price. That is the latest
market price (P directive) found in the journal (or an included file),
market value" using their default market price. That is the latest
market price (P directive) found in the journal (or an included file),
for the amount's commodity, dated on or before the report end date.
Unlike Ledger, hledger's -V only uses the market prices recorded with P
directives, ignoring transaction prices recorded as part of posting
directives, ignoring transaction prices recorded as part of posting
amounts (which -B/--cost uses). Using -B and -V together is allowed.
CCuussttoomm bbaallaannccee oouuttppuutt
In simple (non-multi-column) balance reports, you can customise the
In simple (non-multi-column) balance reports, you can customise the
output with --format FMT:
$ hledger balance --format "%20(account) %12(total)"
@ -821,7 +845,7 @@ CCOOMMMMAANNDDSS
0
The FMT format string (plus a newline) specifies the formatting applied
to each account/balance pair. It may contain any suitable text, with
to each account/balance pair. It may contain any suitable text, with
data fields interpolated like so:
%[MIN][.MAX](FIELDNAME)
@ -832,14 +856,14 @@ CCOOMMMMAANNDDSS
+o FIELDNAME must be enclosed in parentheses, and can be one of:
+o depth_spacer - a number of spaces equal to the account's depth, or
+o depth_spacer - a number of spaces equal to the account's depth, or
if MIN is specified, MIN * depth spaces.
+o account - the account's name
+o total - the account's balance/posted total, right justified
Also, FMT can begin with an optional prefix to control how multi-com-
Also, FMT can begin with an optional prefix to control how multi-com-
modity amounts are rendered:
+o %_ - render on multiple lines, bottom-aligned (the default)
@ -848,7 +872,7 @@ CCOOMMMMAANNDDSS
+o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results.
@ -856,19 +880,19 @@ CCOOMMMMAANNDDSS
+o %(total) - the account's total
+o %-20.20(account) - the account's name, left justified, padded to 20
+o %-20.20(account) - the account's name, left justified, padded to 20
characters and clipped at 20 characters
+o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
+o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
one line
+o %20(total) %2(depth_spacer)%-(account) - the default format for the
+o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report
OOuuttppuutt ddeessttiinnaattiioonn
The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the
The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the
-o/--output-file option.
$ hledger balance -o - # write to stdout (the default)
@ -876,8 +900,8 @@ CCOOMMMMAANNDDSS
CCSSVV oouuttppuutt
The balance, print and register commands can write their output as CSV.
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the -O/--output-format
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the -O/--output-format
option, or by specifying a .csv file extension with -o/--output-file.
$ hledger balance -O csv # write CSV to stdout
@ -891,8 +915,8 @@ CCOOMMMMAANNDDSS
----ddrroopp==NN
in flat mode: omit N leading account name parts
This command displays a simple balance sheet. It currently assumes
that you have top-level accounts named asset and liability (plural
This command displays a simple balance sheet. It currently assumes
that you have top-level accounts named asset and liability (plural
forms also allowed.)
$ hledger balancesheet
@ -922,9 +946,9 @@ CCOOMMMMAANNDDSS
----ddrroopp==NN
in flat mode: omit N leading account name parts
This command displays a simple cashflow statement It shows the change
in all "cash" (ie, liquid assets) accounts for the period. It cur-
rently assumes that cash accounts are under a top-level account named
This command displays a simple cashflow statement It shows the change
in all "cash" (ie, liquid assets) accounts for the period. It cur-
rently assumes that cash accounts are under a top-level account named
asset and do not contain receivable or A/R (plural forms also allowed.)
$ hledger cashflow
@ -944,11 +968,11 @@ CCOOMMMMAANNDDSS
hheellpp
Show one of the hledger manuals.
The help command displays any of the main hledger man pages. (Unlike
hledger --help, which displays only the hledger man page.) Run it with
no arguments to list available topics (their names are shortened for
easier typing), and run hledger help TOPIC to select one. The output
is similar to a man page, but fixed width. It may be long, so you may
The help command displays any of the main hledger man pages. (Unlike
hledger --help, which displays only the hledger man page.) Run it with
no arguments to list available topics (their names are shortened for
easier typing), and run hledger help TOPIC to select one. The output
is similar to a man page, but fixed width. It may be long, so you may
wish to pipe it into a pager. See also info and man.
$ hledger help
@ -977,8 +1001,8 @@ CCOOMMMMAANNDDSS
----ddrroopp==NN
in flat mode: omit N leading account name parts
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@ -1005,30 +1029,30 @@ CCOOMMMMAANNDDSS
iinnffoo
Show one of the hledger manuals using info.
The info command displays any of the hledger reference manuals using
the info hypertextual documentation viewer. This can be a very effi-
cient way to browse large manuals. It requires the "info" program to
The info command displays any of the hledger reference manuals using
the info hypertextual documentation viewer. This can be a very effi-
cient way to browse large manuals. It requires the "info" program to
be available in your PATH.
As with help, run it with no arguments to list available topics (manu-
As with help, run it with no arguments to list available topics (manu-
als).
mmaann
Show one of the hledger manuals using man.
The man command displays any of the hledger reference manuals using
man, the standard documentation viewer on unix systems. This will fit
the text to your terminal width, and probably invoke a pager automati-
The man command displays any of the hledger reference manuals using
man, the standard documentation viewer on unix systems. This will fit
the text to your terminal width, and probably invoke a pager automati-
cally. It requires the "man" program to be available in your PATH.
As with help, run it with no arguments to list available topics (manu-
As with help, run it with no arguments to list available topics (manu-
als).
pprriinntt
Show transactions from the journal.
--mm SSTTRR ----mmaattcchh==SSTTRR
show the transaction whose description is most similar to STR,
show the transaction whose description is most similar to STR,
and is most recent
--oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]]
@ -1060,12 +1084,12 @@ CCOOMMMMAANNDDSS
liabilities:debts $1
assets:bank:checking $-1
The print command displays full transactions from the journal file,
tidily formatted and showing all amounts explicitly. The output of
print is always a valid hledger journal, but it does always not pre-
The print command displays full transactions from the journal file,
tidily formatted and showing all amounts explicitly. The output of
print is always a valid hledger journal, but it does always not pre-
serve all original content exactly (eg directives).
hledger's print command also shows all unit prices in effect, or (with
hledger's print command also shows all unit prices in effect, or (with
-B/--cost) shows cost amounts.
The print command also supports output destination and CSV output.
@ -1077,14 +1101,14 @@ CCOOMMMMAANNDDSS
include prior postings in the running total
--AA ----aavveerraaggee
show a running average instead of the running total (implies
show a running average instead of the running total (implies
--empty)
--rr ----rreellaatteedd
show postings' siblings instead
--ww NN ----wwiiddtthh==NN
set output width (default: terminal width or COLUMNS. -wN,M
set output width (default: terminal width or COLUMNS. -wN,M
sets description width as well)
--oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]]
@ -1095,7 +1119,7 @@ CCOOMMMMAANNDDSS
select the output format. Supported formats: txt, csv.
The register command displays postings, one per line, and their running
total. This is typically used with a query selecting a particular
total. This is typically used with a query selecting a particular
account, to see that account's activity:
$ hledger register checking
@ -1104,8 +1128,8 @@ CCOOMMMMAANNDDSS
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical
@ -1115,22 +1139,22 @@ CCOOMMMMAANNDDSS
The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead
The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It
the whole report period). This flag implies --empty (see below). It
works best when showing just one account and one commodity.
The --related/-r flag shows the _o_t_h_e_r postings in the transactions of
The --related/-r flag shows the _o_t_h_e_r postings in the transactions of
the postings which would normally be shown.
With a reporting interval, register shows summary postings, one per
With a reporting interval, register shows summary postings, one per
interval, aggregating the postings to each account:
$ hledger register --monthly income
2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are
Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E
@ -1147,7 +1171,7 @@ CCOOMMMMAANNDDSS
2008/11 0 $-2
2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth
Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@ -1155,19 +1179,19 @@ CCOOMMMMAANNDDSS
2008/06 assets $-1 0
2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report.
CCuussttoomm rreeggiisstteerr oouuttppuutt
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
--width W,D . Here's a diagram:
<--------------------------------- width (W) ---------------------------------->
@ -1183,7 +1207,7 @@ CCOOMMMMAANNDDSS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
The register command also supports the -o/--output-file and -O/--out-
The register command also supports the -o/--output-file and -O/--out-
put-format options for controlling output destination and CSV output.
ssttaattss
@ -1205,8 +1229,8 @@ CCOOMMMMAANNDDSS
Accounts : 8 (depth 3)
Commodities : 1 ($)
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
The stats command also supports -o/--output-file for controlling output
@ -1218,37 +1242,37 @@ CCOOMMMMAANNDDSS
$ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
This command runs hledger's built-in unit tests and displays a quick
This command runs hledger's built-in unit tests and displays a quick
report. With a regular expression argument, it selects only tests with
matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.
AADDDD--OONN CCOOMMMMAANNDDSS
Add-on commands are executables in your PATH whose name starts with
hledger- and ends with any of these file extensions: none,
.hs,.lhs,.pl,.py,.rb,.rkt,.sh,.bat,.com,.exe. Also, an add-on's name
Add-on commands are executables in your PATH whose name starts with
hledger- and ends with any of these file extensions: none,
.hs,.lhs,.pl,.py,.rb,.rkt,.sh,.bat,.com,.exe. Also, an add-on's name
may not be the same as any built-in command or alias.
hledger will detect these and include them in the command list and let
you invoke them with hledger ADDONCMD. However there are some limita-
hledger will detect these and include them in the command list and let
you invoke them with hledger ADDONCMD. However there are some limita-
tions:
+o Options appearing before ADDONCMD will be visible only to hledger and
will not be passed to the add-on. Eg: hledger -h web shows hledger's
usage, hledger web -h shows hledger-web's usage.
+o Options understood only by the add-on must go after a -- argument to
hide them from hledger, which would otherwise reject them. Eg:
+o Options understood only by the add-on must go after a -- argument to
hide them from hledger, which would otherwise reject them. Eg:
hledger web -- --server.
Sometimes it may be more convenient to just run the add-on directly,
Sometimes it may be more convenient to just run the add-on directly,
eg: hledger-web --server.
Add-ons which are written in haskell can take advantage of the
hledger-lib library for journal parsing, reporting, command-line
Add-ons which are written in haskell can take advantage of the
hledger-lib library for journal parsing, reporting, command-line
options, etc.
Here are some hledger add-ons available from Hackage, the extra direc-
Here are some hledger add-ons available from Hackage, the extra direc-
tory in the hledger source, or elsewhere:
aappii
@ -1306,11 +1330,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
WF:4303001832 -$6.00
[assets:business:bank:wf:bchecking:banking] $6.00
ledger-autosync, which includes a hledger-autosync alias, downloads
ledger-autosync, which includes a hledger-autosync alias, downloads
transactions from your bank(s) via OFX, and prints just the new ones as
journal entries which you can add to your journal. It can also operate
on .OFX files which you've downloaded manually. It can be a nice
alternative to hledger's built-in CSV reader, especially if your bank
on .OFX files which you've downloaded manually. It can be a nice
alternative to hledger's built-in CSV reader, especially if your bank
supports OFX download.
ddiiffff
@ -1336,9 +1360,9 @@ AADDDD--OONN CCOOMMMMAANNDDSS
2015/02/02
(acct:two) $2
hledger-diff compares two journal files. Given an account name, it
prints out the transactions affecting that account which are in one
journal file but not in the other. This can be useful for reconciling
hledger-diff compares two journal files. Given an account name, it
prints out the transactions affecting that account which are in one
journal file but not in the other. This can be useful for reconciling
existing journals with bank statements.
eeqquuiittyy
@ -1365,14 +1389,14 @@ AADDDD--OONN CCOOMMMMAANNDDSS
equity:opening balances 0
This prints a journal entry which zeroes out the specified accounts (or
all accounts) with a transfer to/from "equity:closing balances" (like
Ledger's equity command). Also, it prints an similar entry with oppo-
all accounts) with a transfer to/from "equity:closing balances" (like
Ledger's equity command). Also, it prints an similar entry with oppo-
site sign for restoring the balances from "equity:opening balances".
These can be useful for ending one journal file and starting a new one,
respectively. By zeroing your asset and liability accounts at the end
respectively. By zeroing your asset and liability accounts at the end
of a file and restoring them at the start of the next one, you will see
correct asset/liability balances whether you run hledger on just one
correct asset/liability balances whether you run hledger on just one
file, or on several files concatenated with include.
iinntteerreesstt
@ -1453,11 +1477,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
Liabilities:Bank EUR 3700.00
hledger-interest computes interests for a given account. Using command
line flags, the program can be configured to use various schemes for
day-counting, such as act/act, 30/360, 30E/360, and 30/360isda. Fur-
thermore, it supports a (small) number of interest schemes, i.e.
line flags, the program can be configured to use various schemes for
day-counting, such as act/act, 30/360, 30E/360, and 30/360isda. Fur-
thermore, it supports a (small) number of interest schemes, i.e.
annual interest with a fixed rate and the scheme mandated by the German
BGB288 (Basiszins f~A1/4r Verbrauchergesch~Aoxfte). See the package page
BGB288 (Basiszins f~A1/4r Verbrauchergesch~Aoxfte). See the package page
for more.
iirrrr
@ -1515,11 +1539,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
2011/04/01 - 2011/05/01: 32.24%
2011/05/01 - 2011/06/01: 95.92%
hledger-irr computes the internal rate of return, also known as the
effective interest rate, of a given investment. After specifying what
account holds the investment, and what account stores the gains (or
losses, or fees, or cost), it calculates the hypothetical annual rate
of fixed rate investment that would have provided the exact same cash
hledger-irr computes the internal rate of return, also known as the
effective interest rate, of a given investment. After specifying what
account holds the investment, and what account stores the gains (or
losses, or fees, or cost), it calculates the hypothetical annual rate
of fixed rate investment that would have provided the exact same cash
flow. See the package page for more.
pprriinntt--uunniiqquuee
@ -1539,6 +1563,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
Prints all journal entries, adding specified custom postings to matched
entries.
hledger-rewrite.hs, in hledger's extra directory (compilation
optional), adds postings to existing transactions, optionally with an
amount based on the existing transaction's first amount. See the
script for more details.
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'