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 .\"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 .SS Simple dates
.PP .PP
Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D) Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
Leading zeroes are optional. Leading zeros are optional.
The year may be omitted, in which case it defaults to the current year, The year may be omitted, in which case it will be inferred from the
or you can set the default year with a default year directive. context \- the current transaction, the default year set with a default
.PP year directive, or the current date when the command is run.
Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[], 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[]. \f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[].
.SS Secondary dates .SS Secondary dates
.PP .PP
Real\-life transactions sometimes involve more than one date \- eg the Real\-life transactions sometimes involve more than one date \- eg the
date you write a cheque, and the date it clears in your bank. 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 When you want to model this, eg for more accurate balances, you can
dates separated by an equals sign. specify individual #posting\-dates, which I recommend.
The \f[I]primary date\f[], on the left, is used by default; the Or, you can use the secondary dates (aka auxiliary/effective dates)
\f[I]secondary date\f[], on the right, is used when the feature, supported for compatibility with Ledger.
\f[C]\-\-date2\f[] flag is specified (For Ledger compatibility,
\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work.)
.PP .PP
Their meaning is up to you, but it\[aq]s best to follow a consistent A secondary date can be written after the primary date, separated by an
rule. 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 Eg write the bank\[aq]s clearing date as primary, and when needed, the
date the transaction was initiated as secondary. date the transaction was initiated as secondary.
.PP .PP
@ -133,15 +137,16 @@ $\ hledger\ register\ checking\ \-\-date2
\f[] \f[]
.fi .fi
.PP .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 your journal entries and remember whether to use or not use the
\f[C]\-\-date2\f[] flag for your reports. \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 .SS Posting dates
.PP .PP
You can give individual postings a different date from their parent You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like transaction, by adding a posting comment containing a tag (see below)
\f[C]date:DATE\f[], where DATE is a simple date. like \f[C]date:DATE\f[].
This is probably the best way to control posting dates precisely. This is probably the best way to control posting dates precisely.
Eg in this example the expense should appear in May reports, and the 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 deduction from checking should be reported on 6/1 for easy bank
@ -157,28 +162,31 @@ reconciliation:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ tt.j\ register\ food $\ hledger\ \-f\ t.j\ register\ food
2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10 2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10
\f[] \f[]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ tt.j\ register\ checking $\ hledger\ \-f\ t.j\ register\ checking
2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10 2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10
\f[] \f[]
.fi .fi
.PP .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 .PP
You can also set the secondary date, with \f[C]date2:DATE2\f[]. Ledger\[aq]s earlier, more compact bracketed date syntax is also
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[].
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
in a posting comment. \f[C]0123456789/\-.=\f[] characters in this way.
.PP With this syntax, DATE infers its year from the transaction and DATE2
When using any of these forms, be sure to provide a valid simple date or infers its year from DATE.
you\[aq]ll get a parse error.
Eg a \f[C]date:\f[] tag with no value is not allowed.
.SS Account names .SS Account names
.PP .PP
Account names typically have several parts separated by a full colon, 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 .PP
Account names may contain single spaces, eg: Account names may contain single spaces, eg:
\f[C]assets:accounts\ receivable\f[]. \f[C]assets:accounts\ receivable\f[].
Because of this, they must always be followed by at least two spaces (or Because of this, they must always be followed by \f[B]two or more
newline). spaces\f[] (or newline).
.PP .PP
Account names can be aliased. Account names can be aliased.
.SS Amounts .SS Amounts
.PP .PP
After the account name, there is usually an amount. After the account name, there is usually an amount.
Important: between account name and amount, there must be \f[B]two or Important: between account name and amount, there must be \f[B]two or
more\f[] spaces. more spaces\f[].
.PP .PP
The amount is a number, optionally with a currency symbol or commodity Amounts consist of a number and (usually) a currency symbol or commodity
name on either the left or right. name.
Negative amounts may have the minus sign either before or after the Some examples:
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
.PP .PP
hledger supports flexible decimal point and digit group separator \f[C]2.00001\f[]
styles, to support international variations. .PD 0
Numbers can use either a period (\f[C]\&.\f[]) or a comma (\f[C],\f[]) .P
as decimal point. .PD
They can also have digit group separators at any position (eg thousands \f[C]$1\f[]
separators) which can be comma or period \- whichever one you did not .PD 0
use as a decimal point. .P
If you use digit group separators, you must also include a decimal point .PD
in at least one number in the same commodity, so that hledger knows \f[C]4000\ AAPL\f[]
which character is which. .PD 0
Eg, write \f[C]$1,000.00\f[] or \f[C]$1.000,00\f[]. .P
.SS Amount display styles .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 .PP
Based on how you format amounts, hledger will infer canonical display As you can see, the amount format is somewhat flexible:
styles for each commodity, and use these when displaying amounts in that .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. commodity.
Amount styles include: (Except for price amounts, which are always formatted as written).
The display format is chosen as follows:
.IP \[bu] 2 .IP \[bu] 2
the position (left or right) and spacing (space or no separator) of the if there is a commodity directive specifying the format, that is used
commodity symbol
.IP \[bu] 2 .IP \[bu] 2
the digit group separator character (comma or period) and digit group otherwise the format is inferred from the first posting amount in that
sizes, if any 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 .IP \[bu] 2
the decimal point character (period or comma) or if there are no such amounts in the journal, a default format is used
.IP \[bu] 2 (like \f[C]$1000.00\f[]).
the display precision (number of decimal places displayed)
.PP .PP
The canonical style is generally the style of the first posting amount Price amounts and amounts in D directives usually don\[aq]t affect
seen in a commodity. amount format inference, but in some situations they can do so
However the display precision will be the highest precision seen in all indirectly.
posting amounts in that commmodity. (Eg when D\[aq]s default commodity is applied to a commodity\-less
.PP amount, or when an amountless posting is balanced using a price\[aq]s
The precisions used in a price amount, or a D directive, don\[aq]t commodity, or when \-V is used.) If you find this causing problems, set
affect the canonical display precision directly, but they can affect it the desired format with a commodity directive.
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).
.SS Virtual Postings .SS Virtual Postings
.PP .PP
When you parenthesise the account name in a posting, that posting is When you parenthesise the account name in a posting, we call that a
considered \f[I]virtual\f[], which means: \f[I]virtual posting\f[], which means:
.IP \[bu] 2 .IP \[bu] 2
it is ignored when checking that the transaction is balanced it is ignored when checking that the transaction is balanced
.IP \[bu] 2 .IP \[bu] 2
@ -265,20 +293,28 @@ needing to use the \f[C]equity:opening\ balances\f[] account:
\ \ (assets:checking)\ \ \ $1000 \ \ (assets:checking)\ \ \ $1000
\f[] \f[]
.fi .fi
.SS Balanced Virtual Postings
.PP .PP
When the account name is bracketed, the posting is \f[I]balanced When the account name is bracketed, we call it a \f[I]balanced virtual
virtual\f[], which is just like a virtual posting except the balanced posting\f[].
virtual postings in a transaction must balance to 0, like the real This is like an ordinary virtual posting except the balanced virtual
postings (but separately from them). 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 Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or
\f[C]real:1\f[]. \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 .PP
Virtual postings are a feature inherited from Ledger can can Virtual postings have some legitimate uses, but those are few.
occasionally be useful, but they can be a crutch and you should think You can usually find an equivalent journal entry using real postings,
twice or three times before using them. which is more correct and provides better error checking.
You can almost always find an equivalent journal entry using two or more
real postings that will be more correct and more error\-proof.
.SS Balance Assertions .SS Balance Assertions
.PP .PP
hledger supports ledger\-style balance assertions in journal files. hledger supports ledger\-style balance assertions in journal files.
@ -547,7 +583,7 @@ posting\-tag):
.fi .fi
.PP .PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag 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 Directives
.SS Account aliases .SS Account aliases
.PP .PP
@ -721,46 +757,50 @@ spellings were also supported.
A line containing just \f[C]comment\f[] starts a multi\-line comment, 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. and a line containing just \f[C]end\ comment\f[] ends it.
See comments. 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 .SS Default commodity
.PP .PP
You can set a default commodity, to be used for amounts without one. You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount. 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 applied to all subsequent commodity\-less amounts, up to the next D
directive. directive.
(Note this is different from Ledger\[aq]s default commodity 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 .SS Default year
.PP .PP
You can set a default year to be used for subsequent dates which You can set a default year to be used for subsequent dates which
@ -800,12 +840,10 @@ include\ path/to/file.journal
.PP .PP
If the path does not begin with a slash, it is relative to the current If the path does not begin with a slash, it is relative to the current
file. file.
.PP
Glob patterns (\f[C]*\f[]) are not currently supported. Glob patterns (\f[C]*\f[]) are not currently supported.
.PP .PP
The \f[C]include\f[] directive may only be used in journal files, and The \f[C]include\f[] directive can only be used in journal files.
currently it may only include other journal files (eg, not CSV or It can include journal, timeclock or timedot files, but not CSV files.
timeclock files.)
.SH EDITOR SUPPORT .SH EDITOR SUPPORT
.PP .PP
Add\-on modes exist for various text editors, to make working with 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) 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 Leading zeros 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 will be inferred from the context - the current transaction, the default
default year directive. 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',
Some examples: `2010/01/31', `1/31', `2010-01-31', `2010.1.31'. `2010.1.31'.
 
File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates 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 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 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 want to model this, eg for more accurate balances, you can specify
separated by an equals sign. The _primary date_, on the left, is used individual #posting-dates, which I recommend. Or, you can use the
by default; the _secondary date_, on the right, is used when the secondary dates (aka auxiliary/effective dates) feature, supported for
`--date2' flag is specified (For Ledger compatibility, `--aux-date' or compatibility with Ledger.
`--effective' also work.)
Their meaning is up to you, but it's best to follow a consistent A secondary date can be written after the primary date, separated by
rule. Eg write the bank's clearing date as primary, and when needed, an equals sign. The primary date, on the left, is used by default; the
the date the transaction was initiated as secondary. 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 Here's an example. Note that a secondary date will use the year of
the primary date if unspecified. the primary date if unspecified.
@ -159,10 +163,11 @@ $ hledger register checking
$ hledger register checking --date2 $ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10 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 in your journal entries and remember whether to use or not use the
`--date2' flag for your reports. Arguably they are now obsolete, `--date2' flag for your reports. They are included in hledger for
superseded by... 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 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 You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like `date:DATE', transaction, by adding a posting comment containing a tag (see below)
where DATE is a simple date. This is probably the best way to control like `date:DATE'. This is probably the best way to control posting
posting dates precisely. Eg in this example the expense should appear in dates precisely. Eg in this example the expense should appear in May
May reports, and the deduction from checking should be reported on 6/1 reports, and the deduction from checking should be reported on 6/1 for
for easy bank reconciliation: easy bank reconciliation:
2015/5/30 2015/5/30
@ -183,23 +188,24 @@ for easy bank reconciliation:
assets:checking ; bank cleared it on monday, date:6/1 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 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 2015/06/01 assets:checking $-10 $-10
A posting date will use the year of the transaction date if DATE should be a simple date; if the year is not specified it will
unspecified. 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 Ledger's earlier, more compact bracketed date syntax is also
compatibility, Ledger's older posting date syntax is also supported: supported: `[DATE]', `[DATE=DATE2]' or `[=DATE2]'. hledger will attempt
`[DATE]', `[DATE=DATE2]' or `[=DATE2]' in a posting comment. to parse any square-bracketed sequence of the `0123456789/-.='
characters in this way. With this syntax, DATE infers its year from the
When using any of these forms, be sure to provide a valid simple transaction and DATE2 infers its year from DATE.
date or you'll get a parse error. Eg a `date:' tag with no value is not
allowed.
 
File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Dates, Up: FILE FORMAT 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'. accounts: `assets', `liabilities', `income', `expenses', and `equity'.
Account names may contain single spaces, eg: `assets:accounts Account names may contain single spaces, eg: `assets:accounts
receivable'. Because of this, they must always be followed by at least receivable'. Because of this, they must always be followed by *two or
two spaces (or newline). more spaces* (or newline).
Account names can be aliased. 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 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 Amounts consist of a number and (usually) a currency symbol or
commodity name on either the left or right. Negative amounts may have commodity name. Some examples:
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"').
* 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:: As you can see, the amount format is somewhat flexible:
* Amount display styles::
 * amounts are a number (the "quantity") and optionally a currency
File: hledger_journal.5.info, Node: Decimal points and digit groups, Next: Amount display styles, Up: Amounts 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 * negative amounts with a commodity on the left can have the minus
styles, to support international variations. Numbers can use either a sign before or after it
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'.
 * digit groups (thousands, or any other grouping) can be separated by
File: hledger_journal.5.info, Node: Amount display styles, Prev: Decimal points and digit groups, Up: Amounts 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 * if there is a commodity directive specifying the format, that is
styles for each commodity, and use these when displaying amounts in that used
commodity. Amount styles include:
* the position (left or right) and spacing (space or no separator) * otherwise the format is inferred from the first posting amount in
of the commodity symbol 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 * or if there are no such amounts in the journal, a default format
group sizes, if any is used (like `$1000.00').
* the decimal point character (period or comma) Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly. (Eg
* the display precision (number of decimal places displayed) 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
The canonical style is generally the style of the first posting when -V is used.) If you find this causing problems, set the desired
amount seen in a commodity. However the display precision will be the format with a commodity directive.
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).
 
File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT 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 1.5 Virtual Postings
==================== ====================
When you parenthesise the account name in a posting, that posting is When you parenthesise the account name in a posting, we call that a
considered _virtual_, which means: _virtual posting_, which means:
* it is ignored when checking that the transaction is balanced * 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 1/1 special unbalanced posting to set initial balance
(assets:checking) $1000 (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::
 1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
File: hledger_journal.5.info, Node: Balanced Virtual Postings, Up: Virtual Postings expenses:food $10
assets:cash $-10
[assets:checking:available] $10
[assets:checking:budget:food] $-10
1.5.1 Balanced Virtual Postings 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.
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.
 
File: hledger_journal.5.info, Node: Balance Assertions, Next: Prices, Prev: Virtual Postings, Up: FILE FORMAT 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: (a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values Tags are like Ledger's metadata feature, except hledger's tag values
are always simple strings. are simple strings.
 
File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT 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:: * account directive::
* apply account directive:: * apply account directive::
* Multi-line comments:: * Multi-line comments::
* commodity directive::
* Default commodity:: * Default commodity::
* Default year:: * Default year::
* Including other files:: * Including other files::
@ -791,7 +784,7 @@ include personal.journal
also supported. 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 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. 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 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 the D directive with a sample amount. The commodity (and the sample
amount's display style) will be applied to all subsequent commodity-less amount's display format) will be applied to all subsequent
amounts, up to the next D directive. (Note this is different from commodity-less amounts, up to the next D directive. (Note this is
Ledger's default commodity directive.) 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
 
File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives 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 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 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 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 include path/to/file.journal
If the path does not begin with a slash, it is relative to the 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 can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
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.)
 
File: hledger_journal.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top File: hledger_journal.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -917,67 +916,63 @@ Node: Dates3351
Ref: #dates3479 Ref: #dates3479
Node: Simple dates3544 Node: Simple dates3544
Ref: #simple-dates3672 Ref: #simple-dates3672
Node: Secondary dates3976 Node: Secondary dates4036
Ref: #secondary-dates4132 Ref: #secondary-dates4192
Node: Posting dates5408 Node: Posting dates5753
Ref: #posting-dates5539 Ref: #posting-dates5884
Node: Account names6715 Node: Account names7255
Ref: #account-names6854 Ref: #account-names7394
Node: Amounts7338 Node: Amounts7879
Ref: #amounts7476 Ref: #amounts8017
Node: Decimal points and digit groups8003 Node: Virtual Postings10015
Ref: #decimal-points-and-digit-groups8196 Ref: #virtual-postings10176
Node: Amount display styles8751 Node: Balance Assertions11396
Ref: #amount-display-styles8924 Ref: #balance-assertions11560
Node: Virtual Postings10003 Node: Assertions and ordering12382
Ref: #virtual-postings10164 Ref: #assertions-and-ordering12567
Node: Balanced Virtual Postings10683 Node: Assertions and commodities13598
Ref: #balanced-virtual-postings10837 Ref: #assertions-and-commodities13824
Node: Balance Assertions11452 Node: Assertions and subaccounts14516
Ref: #balance-assertions11616 Ref: #assertions-and-subaccounts14750
Node: Assertions and ordering12438 Node: Assertions and virtual postings15272
Ref: #assertions-and-ordering12623 Ref: #assertions-and-virtual-postings15481
Node: Assertions and commodities13654 Node: Prices15622
Ref: #assertions-and-commodities13880 Ref: #prices15754
Node: Assertions and subaccounts14572 Node: Transaction prices15805
Ref: #assertions-and-subaccounts14806 Ref: #transaction-prices15950
Node: Assertions and virtual postings15328 Node: Market prices17557
Ref: #assertions-and-virtual-postings15537 Ref: #market-prices17692
Node: Prices15678 Node: Comments18580
Ref: #prices15810 Ref: #comments18702
Node: Transaction prices15861 Node: Tags19814
Ref: #transaction-prices16006 Ref: #tags19932
Node: Market prices17613 Node: Directives20855
Ref: #market-prices17748 Ref: #directives20970
Node: Comments18636 Node: Account aliases21163
Ref: #comments18758 Ref: #account-aliases21309
Node: Tags19870 Node: Basic aliases21911
Ref: #tags19988 Ref: #basic-aliases22056
Node: Directives20918 Node: Regex aliases22744
Ref: #directives21033 Ref: #regex-aliases22914
Node: Account aliases21202 Node: Multiple aliases23684
Ref: #account-aliases21348 Ref: #multiple-aliases23858
Node: Basic aliases21950 Node: end aliases24354
Ref: #basic-aliases22095 Ref: #end-aliases24496
Node: Regex aliases22783 Node: account directive24598
Ref: #regex-aliases22953 Ref: #account-directive24780
Node: Multiple aliases23723 Node: apply account directive25076
Ref: #multiple-aliases23897 Ref: #apply-account-directive25274
Node: end aliases24393 Node: Multi-line comments25935
Ref: #end-aliases24535 Ref: #multi-line-comments26127
Node: account directive24637 Node: commodity directive26254
Ref: #account-directive24819 Ref: #commodity-directive26440
Node: apply account directive25115 Node: Default commodity27313
Ref: #apply-account-directive25313 Ref: #default-commodity27488
Node: Multi-line comments25974 Node: Default year27809
Ref: #multi-line-comments26164 Ref: #default-year27976
Node: Default commodity26291 Node: Including other files28399
Ref: #default-commodity26466 Ref: #including-other-files28558
Node: Default year27161 Node: EDITOR SUPPORT28954
Ref: #default-year27328 Ref: #editor-support29074
Node: Including other files27751
Ref: #including-other-files27910
Node: EDITOR SUPPORT28327
Ref: #editor-support28447
 
End Tag Table End Tag Table

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

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

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

@ -93,8 +93,6 @@ FFIILLEE FFOORRMMAATT
-------------------- --------------------
4.50 4.50
default year directives may be used.
Here is a sample.timedot. 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 .RS
.RE .RE
.TP .TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[] .B \f[C]\-\-date2\f[]
use postings/txns\[aq] secondary dates instead show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS .RS
.RE .RE
.TP .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 set start date, end date, and/or reporting interval all at once
(overrides the flags above) (overrides the flags above)
`--date2 --aux-date' `--date2'
use postings/txns' secondary dates instead show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared' `-C --cleared'
include only cleared postings/txns include only cleared postings/txns
@ -273,17 +273,17 @@ Node: OPTIONS682
Ref: #options781 Ref: #options781
Node: hledger options1547 Node: hledger options1547
Ref: #hledger-options1653 Ref: #hledger-options1653
Node: KEYS2829 Node: KEYS2836
Ref: #keys2926 Ref: #keys2933
Node: SCREENS3323 Node: SCREENS3330
Ref: #screens3410 Ref: #screens3417
Node: Accounts screen3500 Node: Accounts screen3507
Ref: #accounts-screen3630 Ref: #accounts-screen3637
Node: Register screen4475 Node: Register screen4482
Ref: #register-screen4632 Ref: #register-screen4639
Node: Transaction screen6014 Node: Transaction screen6021
Ref: #transaction-screen6174 Ref: #transaction-screen6181
Node: Error screen7041 Node: Error screen7048
Ref: #error-screen7165 Ref: #error-screen7172
 
End Tag Table 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 set start date, end date, and/or reporting interval all at once
(overrides the flags above) (overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee ----ddaattee22
use postings/txns' secondary dates instead show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd --CC ----cclleeaarreedd
include only cleared postings/txns 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 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. you want to restrict who can see and add entries to your journal.
.PP .PP
Command\-line options and arguments may be used to set an initial filter
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 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 If a change makes the file unparseable, hledger\-web will show an error
until the file has been fixed. until the file has been fixed.
.SH OPTIONS .SH OPTIONS
@ -178,8 +184,8 @@ set start date, end date, and/or reporting interval all at once
.RS .RS
.RE .RE
.TP .TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[] .B \f[C]\-\-date2\f[]
use postings/txns\[aq] secondary dates instead show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS .RS
.RE .RE
.TP .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 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. 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 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. web app detects changes made by other means and will show the new data
If a change makes the file unparseable, hledger-web will show an error on the next request. If a change makes the file unparseable, hledger-web
until the file has been fixed. will show an error until the file has been fixed.
* Menu: * 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 set start date, end date, and/or reporting interval all at once
(overrides the flags above) (overrides the flags above)
`--date2 --aux-date' `--date2'
use postings/txns' secondary dates instead show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared' `-C --cleared'
include only cleared postings/txns include only cleared postings/txns
@ -167,9 +171,9 @@ The following common hledger options should also work:
 
Tag Table: Tag Table:
Node: Top90 Node: Top90
Node: OPTIONS2622 Node: OPTIONS2834
Ref: #options2709 Ref: #options2921
Node: hledger options3572 Node: hledger options3784
Ref: #hledger-options3679 Ref: #hledger-options3891
 
End Tag Table 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 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. 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 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 app detects changes made by other means and will show the new data on
a change makes the file unparseable, hledger-web will show an error the next request. If a change makes the file unparseable, hledger-web
until the file has been fixed. will show an error until the file has been fixed.
OOPPTTIIOONNSS OOPPTTIIOONNSS
Note: if invoking hledger-web as a hledger subcommand, write -- before 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 set start date, end date, and/or reporting interval all at once
(overrides the flags above) (overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee ----ddaattee22
use postings/txns' secondary dates instead show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd --CC ----cclleeaarreedd
include only cleared postings/txns 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 $\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
\f[] \f[]
.fi .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 .SH OPTIONS
.PP .PP
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just 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 .RS
.RE .RE
.TP .TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[] .B \f[C]\-\-date2\f[]
use postings/txns\[aq] secondary dates instead show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS .RS
.RE .RE
.TP .TP
@ -308,12 +329,27 @@ show empty/zero things which are normally omitted
show amounts in their cost price\[aq]s commodity show amounts in their cost price\[aq]s commodity
.RS .RS
.RE .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 .SS Multiple files
.PP .PP
One may specify the \f[C]\-\-file\ FILE\f[] option multiple times. You can specify multiple \f[C]\-f/\-\-file\ FILE\f[] options.
This is equivalent to concatenating the files to standard input and This is like combining all the files into one, except they can have
passing \f[C]\-\-file\ \-\f[], except that the add command functions different formats.
normally and adds entries to the first specified file. Also directives and aliases in one file do not affect subsequent files
(if you need that, use the include directive instead).
.SS Repeated options .SS Repeated options
.PP .PP
Otherwise, if a reporting option is repeated, the last one takes Otherwise, if a reporting option is repeated, the last one takes
@ -657,13 +693,16 @@ match transaction descriptions
.RE .RE
.TP .TP
.B \f[B]\f[C]date:PERIODEXPR\f[]\f[] .B \f[B]\f[C]date:PERIODEXPR\f[]\f[]
match dates within the specified period (which should not include a match dates within the specified period.
reporting interval 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 .RS
.RE .RE
.TP .TP
.B \f[B]\f[C]date2:PERIODEXPR\f[]\f[] .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 .RS
.RE .RE
.TP .TP
@ -695,8 +734,6 @@ transaction.
before any of the above negates the match. before any of the above negates the match.
.RS .RS
.RE .RE
.PP
* * * * *
.PP .PP
Some of these can also be expressed as command\-line options (eg 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[]). \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. generate them from CSV.
For more interactive data entry, there is the \f[C]add\f[] command, For more interactive data entry, there is the \f[C]add\f[] command,
which prompts interactively on the console for new transactions, and which prompts interactively on the console for new transactions, and
appends them to the journal file (existing transactions are not appends them to the journal file (if there are multiple
changed). \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. This is the only hledger command that writes to the journal file.
.PP .PP
To use it, just run \f[C]hledger\ add\f[] and follow the prompts. 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 .PP
Prints all journal entries, adding specified custom postings to matched Prints all journal entries, adding specified custom postings to matched
entries. 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 .IP
.nf .nf
\f[C] \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 print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart $ 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 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 set start date, end date, and/or reporting interval all at once
(overrides the flags above) (overrides the flags above)
`--date2 --aux-date' `--date2'
use postings/txns' secondary dates instead show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared' `-C --cleared'
include only cleared postings/txns include only cleared postings/txns
@ -228,6 +243,15 @@ command name.
`-B --cost' `-B --cost'
show amounts in their cost price's commodity 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: * Menu:
* Multiple files:: * Multiple files::
@ -244,10 +268,10 @@ File: hledger.1.info, Node: Multiple files, Next: Repeated options, Up: OPTIO
2.1 Multiple files 2.1 Multiple files
================== ==================
One may specify the `--file FILE' option multiple times. This is You can specify multiple `-f/--file FILE' options. This is like
equivalent to concatenating the files to standard input and passing combining all the files into one, except they can have different
`--file -', except that the add command functions normally and adds formats. Also directives and aliases in one file do not affect
entries to the first specified file. 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 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 match transaction descriptions
*`date:PERIODEXPR'* *`date:PERIODEXPR'*
match dates within the specified period (which should not include a match dates within the specified period. PERIODEXPR should not
reporting interval include a reporting interval. The command-line `--date2' flag
makes this match secondary dates instead (like the `-b'/`-e'/`-p'
options).
*`date2:PERIODEXPR'* *`date2:PERIODEXPR'*
as above, but match secondary dates match secondary dates within the specified period. PERIODEXPR
should not include a reporting interval.
*`depth:N'* *`depth:N'*
match (or display, depending on command) accounts at or above this match (or display, depending on command) accounts at or above this
@ -506,8 +533,7 @@ match (or negatively match)
*`not:'* *`not:'*
before any of the above negates the match. 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 `depth:2' is equivalent to `--depth 2'). Generally you can mix options
and query arguments, and the resulting query will be their intersection and query arguments, and the resulting query will be their intersection
(perhaps excluding the `-p/--period' option). (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, Many hledger users edit their journals directly with a text editor,
or generate them from CSV. For more interactive data entry, there is the or generate them from CSV. For more interactive data entry, there is the
`add' command, which prompts interactively on the console for new `add' command, which prompts interactively on the console for new
transactions, and appends them to the journal file (existing transactions, and appends them to the journal file (if there are
transactions are not changed). This is the only hledger command that 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. writes to the journal file.
To use it, just run `hledger add' and follow the prompts. You can 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 Prints all journal entries, adding specified custom postings to matched
entries. 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 -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
@ -2009,97 +2041,97 @@ Tag Table:
Node: Top82 Node: Top82
Node: EXAMPLES1754 Node: EXAMPLES1754
Ref: #examples1856 Ref: #examples1856
Node: OPTIONS3508 Node: OPTIONS3860
Ref: #options3612 Ref: #options3964
Node: Multiple files6386 Node: Multiple files7217
Ref: #multiple-files6511 Ref: #multiple-files7342
Node: Repeated options6750 Node: Repeated options7607
Ref: #repeated-options6902 Ref: #repeated-options7759
Node: Depth limiting7022 Node: Depth limiting7879
Ref: #depth-limiting7167 Ref: #depth-limiting8024
Node: Smart dates7368 Node: Smart dates8225
Ref: #smart-dates7509 Ref: #smart-dates8366
Node: Reporting interval8506 Node: Reporting interval9363
Ref: #reporting-interval8665 Ref: #reporting-interval9522
Node: Period expressions9008 Node: Period expressions9865
Ref: #period-expressions9175 Ref: #period-expressions10032
Node: Regular Expressions11221 Node: Regular Expressions12078
Ref: #regular-expressions11363 Ref: #regular-expressions12220
Node: QUERIES12846 Node: QUERIES13703
Ref: #queries12950 Ref: #queries13807
Node: COMMANDS16125 Node: COMMANDS17109
Ref: #commands16239 Ref: #commands17223
Node: accounts16912 Node: accounts17896
Ref: #accounts17012 Ref: #accounts17996
Node: activity17994 Node: activity18978
Ref: #activity18106 Ref: #activity19090
Node: add18465 Node: add19449
Ref: #add18566 Ref: #add19550
Node: balance21160 Node: balance22209
Ref: #balance21273 Ref: #balance22322
Node: Flat mode23989 Node: Flat mode25038
Ref: #flat-mode24116 Ref: #flat-mode25165
Node: Depth limited balance reports24535 Node: Depth limited balance reports25584
Ref: #depth-limited-balance-reports24738 Ref: #depth-limited-balance-reports25787
Node: Multicolumn balance reports25159 Node: Multicolumn balance reports26208
Ref: #multicolumn-balance-reports25361 Ref: #multicolumn-balance-reports26410
Node: Market value30010 Node: Market value31059
Ref: #market-value30174 Ref: #market-value31223
Node: Custom balance output30667 Node: Custom balance output31716
Ref: #custom-balance-output30840 Ref: #custom-balance-output31889
Node: Output destination32944 Node: Output destination33993
Ref: #output-destination33109 Ref: #output-destination34158
Node: CSV output33379 Node: CSV output34428
Ref: #csv-output33498 Ref: #csv-output34547
Node: balancesheet33895 Node: balancesheet34944
Ref: #balancesheet34023 Ref: #balancesheet35072
Node: cashflow34675 Node: cashflow35724
Ref: #cashflow34792 Ref: #cashflow35841
Node: help35482 Node: help36531
Ref: #help35594 Ref: #help36643
Node: incomestatement36431 Node: incomestatement37480
Ref: #incomestatement36561 Ref: #incomestatement37610
Node: info37288 Node: info38337
Ref: #info37395 Ref: #info38444
Node: man37757 Node: man38806
Ref: #man37854 Ref: #man38903
Node: print38257 Node: print39306
Ref: #print38362 Ref: #print39411
Node: register39713 Node: register40762
Ref: #register39826 Ref: #register40875
Node: Custom register output44167 Node: Custom register output45216
Ref: #custom-register-output44298 Ref: #custom-register-output45347
Node: stats45595 Node: stats46644
Ref: #stats45701 Ref: #stats46750
Node: test46582 Node: test47631
Ref: #test46669 Ref: #test47718
Node: ADD-ON COMMANDS47036 Node: ADD-ON COMMANDS48085
Ref: #add-on-commands47172 Ref: #add-on-commands48221
Node: api48460 Node: api49509
Ref: #api48552 Ref: #api49601
Node: autosync48586 Node: autosync49635
Ref: #autosync48701 Ref: #autosync49750
Node: diff51016 Node: diff52065
Ref: #diff51126 Ref: #diff52175
Node: equity51790 Node: equity52839
Ref: #equity51904 Ref: #equity52953
Node: interest53232 Node: interest54281
Ref: #interest53349 Ref: #interest54398
Node: irr56433 Node: irr57482
Ref: #irr56546 Ref: #irr57595
Node: print-unique58921 Node: print-unique59970
Ref: #print-unique59051 Ref: #print-unique60100
Node: rewrite59309 Node: rewrite60358
Ref: #rewrite59428 Ref: #rewrite60477
Node: ui59731 Node: ui61006
Ref: #ui59831 Ref: #ui61106
Node: web59872 Node: web61147
Ref: #web59960 Ref: #web61235
Node: TROUBLESHOOTING59993 Node: TROUBLESHOOTING61268
Ref: #troubleshooting60112 Ref: #troubleshooting61387
Node: Run-time problems60166 Node: Run-time problems61441
Ref: #run-time-problems60309 Ref: #run-time-problems61584
Node: Known limitations62253 Node: Known limitations63528
Ref: #known-limitations62396 Ref: #known-limitations63671
 
End Tag Table 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 print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart $ 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 OOPPTTIIOONNSS
To see general usage and the command list: hledger -h or just hledger 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 set start date, end date, and/or reporting interval all at once
(overrides the flags above) (overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee ----ddaattee22
use postings/txns' secondary dates instead show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd --CC ----cclleeaarreedd
include only cleared postings/txns include only cleared postings/txns
@ -205,156 +218,165 @@ OOPPTTIIOONNSS
--BB ----ccoosstt --BB ----ccoosstt
show amounts in their cost price's commodity 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 MMuullttiippllee ffiilleess
One may specify the --file FILE option multiple times. This is equiva- You can specify multiple -f/--file FILE options. This is like combin-
lent to concatenating the files to standard input and passing --file -, ing all the files into one, except they can have different formats.
except that the add command functions normally and adds entries to the Also directives and aliases in one file do not affect subsequent files
first specified file. (if you need that, use the include directive instead).
RReeppeeaatteedd ooppttiioonnss RReeppeeaatteedd ooppttiioonnss
Otherwise, if a reporting option is repeated, the last one takes prece- Otherwise, if a reporting option is repeated, the last one takes prece-
dence. Eg -p jan -p feb is equivalent to -p feb. dence. Eg -p jan -p feb is equivalent to -p feb.
DDeepptthh lliimmiittiinngg DDeepptthh lliimmiittiinngg
With the --depth N option, commands like account, balance and register With the --depth N option, commands like account, balance and register
will show only the uppermost accounts in the account tree, down to will show only the uppermost accounts in the account tree, down to
level N. Use this when you want a summary with less detail. level N. Use this when you want a summary with less detail.
SSmmaarrtt ddaatteess SSmmaarrtt ddaatteess
hledger's user interfaces accept a flexible "smart date" syntax (unlike hledger's user interfaces accept a flexible "smart date" syntax (unlike
dates in the journal file). Smart dates allow some english words, can 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 be relative to today's date, and can have less-significant date parts
omitted (defaulting to 1). omitted (defaulting to 1).
Examples: Examples:
tab(@); l l. T{ 2009/1/1, 2009/01/01, 2009-1-1, 2009.1.1 T}@T{ simple 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 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, 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 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 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 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{ 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 lastweek T}@T{ spaces are optional T} T{ today, yesterday, tomorrow
T}@T{ T} T}@T{ T}
RReeppoorrttiinngg iinntteerrvvaall RReeppoorrttiinngg iinntteerrvvaall
A reporting interval can be specified so that commands like register, A reporting interval can be specified so that commands like register,
balance and activity will divide their reports into multiple report balance and activity will divide their reports into multiple report
periods. The basic intervals can be selected with one of -D/--daily, periods. The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
plex intervals may be specified with a period expression. plex intervals may be specified with a period expression.
PPeerriioodd eexxpprreessssiioonnss PPeerriioodd eexxpprreessssiioonnss
The -p/--period option accepts period expressions, a shorthand way of The -p/--period option accepts period expressions, a shorthand way of
expressing a start date, end date, and or reporting interval all at expressing a start date, end date, and or reporting interval all at
once. Note a period expression on the command line will cause any 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. 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- hledger's period expressions are similar to Ledger's, though not iden-
tical. Here's a basic period expression specifying the first quarter tical. Here's a basic period expression specifying the first quarter
of 2009. Note, hledger always treats start dates as inclusive and end of 2009. Note, hledger always treats start dates as inclusive and end
dates as exclusive: dates as exclusive:
-p "from 2009/1/1 to 2009/4/1" -p "from 2009/1/1 to 2009/4/1"
Keywords like "from" and "to" are optional, and so are the spaces, 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 long as you don't run two dates together. "to" can also be written as
"-". These are equivalent to the above: "-". 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} -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: 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} -p "this year to 4/1" T}
If you specify only one date, the missing start or end date will be the If you specify only one date, the missing start or end date will be the
earliest or latest transaction in your journal: earliest or latest transaction in your journal:
tab(@); l l. T{ -p "from 2009/1/1" T}@T{ everything after january 1, 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{ 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} 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: date like so:
tab(@); l l. T{ -p "2009" T}@T{ the year 2009; equivalent to "2009/1/1 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- "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} lent to "2009/1/1 to 2009/1/2" T}
Period expressions can also start with (or be) a reporting interval: Period expressions can also start with (or be) a reporting interval:
daily, weekly, monthly, quarterly, yearly, or one of the every ... daily, weekly, monthly, quarterly, yearly, or one of the every ...
expressions below. Optionally the word in may appear between the expressions below. Optionally the word in may appear between the
reporting interval and the start/end dates. Examples: reporting interval and the start/end dates. Examples:
tab(@); l. T{ -p "weekly from 2009/1/1 to 2009/4/1" 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- -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{ 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} -p "every 15th day of month" T} T{ -p "every 4th day of week" T}
RReegguullaarr EExxpprreessssiioonnss RReegguullaarr EExxpprreessssiioonnss
hledger uses regular expressions in a number of places: 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 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
+o CSV rules conditional blocks: if 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 --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: general they:
+o are case insensitive +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) matched)
+o are POSIX extended regular expressions +o are POSIX extended regular expressions
+o also support GNU word boundaries (\<, \>, \b, \B) +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 replacement strings
+o do not support mode modifiers like (?s) +o do not support mode modifiers like (?s)
Some things to note: Some things to note:
+o In the alias directive and --alias option, regular expressions must +o In the alias directive and --alias option, regular expressions must
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
these are not required. these are not required.
+o To match a regular expression metacharacter like $ as a literal char- +o To match a regular expression metacharacter like $ as a literal char-
acter, prepend a backslash. Eg to search for amounts with the dollar acter, prepend a backslash. Eg to search for amounts with the dollar
sign in hledger-web, write cur:\$. 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 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:\\$. dollar sign from the command line, write cur:'\$' or cur:\\$.
QQUUEERRIIEESS QQUUEERRIIEESS
One of hledger's strengths is being able to quickly report on precise One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres- subsets of your data. Most commands accept an optional query expres-
sion, written as arguments after the command name, to filter the data 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 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 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: 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) match (or negatively match)
+o any of the description terms AND +o any of the description terms AND
@ -381,22 +403,22 @@ QQUUEERRIIEESS
same as above same as above
aammtt::NN,, aammtt::<<NN,, aammtt::<<==NN,, aammtt::>>NN,, aammtt::>>==NN aammtt::NN,, aammtt::<<NN,, aammtt::<<==NN,, aammtt::>>NN,, aammtt::>>==NN
match postings with a single-commodity amount that is equal to, match postings with a single-commodity amount that is equal to,
less than, or greater than N. (Multi-commodity amounts are not less than, or greater than N. (Multi-commodity amounts are not
tested, and will always match.) The comparison has two modes: if 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 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. ignoring sign.
ccooddee::RREEGGEEXX ccooddee::RREEGGEEXX
match by transaction code (eg check number) match by transaction code (eg check number)
ccuurr::RREEGGEEXX ccuurr::RREEGGEEXX
match postings or transactions including any amounts whose cur- match postings or transactions including any amounts whose cur-
rency/commodity symbol is fully matched by REGEX. (For a par- rency/commodity symbol is fully matched by REGEX. (For a par-
tial match, use .*REGEX.*). Note, to match characters which are tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend 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: level of quoting to hide it from the shell, so eg do:
hledger print cur:'\$' or hledger print cur:\\$. hledger print cur:'\$' or hledger print cur:\\$.
@ -404,11 +426,14 @@ QQUUEERRIIEESS
match transaction descriptions match transaction descriptions
ddaattee::PPEERRIIOODDEEXXPPRR ddaattee::PPEERRIIOODDEEXXPPRR
match dates within the specified period (which should not match dates within the specified period. PERIODEXPR should not
include a reporting interval include a reporting interval. The command-line --date2 flag
makes this match secondary dates instead (like the -b/-e/-p
options).
ddaattee22::PPEERRIIOODDEEXXPPRR ddaattee22::PPEERRIIOODDEEXXPPRR
as above, but match secondary dates match secondary dates within the specified period. PERIODEXPR
should not include a reporting interval.
ddeepptthh::NN ddeepptthh::NN
match (or display, depending on command) accounts at or above match (or display, depending on command) accounts at or above
@ -429,8 +454,6 @@ QQUUEERRIIEESS
nnoott:: before any of the above negates the match. nnoott:: before any of the above negates the match.
* * * * *
Some of these can also be expressed as command-line options (eg depth:2 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 is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps 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 Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans- add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (existing transactions actions, and appends them to the journal file (if there are multiple
are not changed). This is the only hledger command that writes to the -f FILE options, the first file is used.) Existing transactions are not
journal file. 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 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. control-d or control-c to exit.
Features: 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. transaction (by description) as a template.
+o You can also set the initial defaults with command line arguments. +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 Readline-style edit keys can be used during data entry.
+o The tab key will auto-complete whenever possible - accounts, descrip- +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. 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. bare numbers entered.
+o A parenthesised transaction code may be entered following a date. +o A parenthesised transaction code may be entered following a date.
+o Comments and tags may be entered following a description or amount. +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. 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. supports it.
Example (see the tutorial for a detailed explanation): Example (see the tutorial for a detailed explanation):
@ -632,7 +656,7 @@ CCOOMMMMAANNDDSS
--OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT
select the output format. Supported formats: txt, csv. 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. most featureful and most useful command.
$ hledger balance $ hledger balance
@ -649,24 +673,24 @@ CCOOMMMMAANNDDSS
-------------------- --------------------
0 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 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. 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 indented below their parent. "Boring" accounts, which contain a single
interesting subaccount and no balance of their own, are elided into the 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.) 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. 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. 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: it:
$ hledger balance -p 2008/6 expenses --no-total $ hledger balance -p 2008/6 expenses --no-total
@ -676,9 +700,9 @@ CCOOMMMMAANNDDSS
FFllaatt mmooddee FFllaatt mmooddee
To see a flat list of full account names instead of the default hierar- 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 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. few account name components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1 $ hledger balance -p 2008/6 expenses -N --flat --drop 1
@ -686,9 +710,9 @@ CCOOMMMMAANNDDSS
$1 supplies $1 supplies
DDeepptthh lliimmiitteedd bbaallaannccee rreeppoorrttss DDeepptthh lliimmiitteedd bbaallaannccee rreeppoorrttss
With --depth N, balance shows accounts only to the specified depth. With --depth N, balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less This is very useful to show a complex charts of accounts in less
detail. In flat mode, balances from accounts below the depth limit detail. In flat mode, balances from accounts below the depth limit
will be shown as part of a parent account at the depth limit. will be shown as part of a parent account at the depth limit.
$ hledger balance -N --depth 1 $ hledger balance -N --depth 1
@ -698,12 +722,12 @@ CCOOMMMMAANNDDSS
$1 liabilities $1 liabilities
MMuullttiiccoolluummnn bbaallaannccee rreeppoorrttss MMuullttiiccoolluummnn bbaallaannccee rreeppoorrttss
With a reporting interval, multiple balance columns will be shown, one With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column balance for each report period. There are three types of multi-column balance
report, showing different information: report, showing different information:
1. By default: each column shows the sum of postings in that period, ie 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: for a monthly income statement:
$ hledger balance --quarterly income expenses -E $ hledger balance --quarterly income expenses -E
@ -718,8 +742,8 @@ CCOOMMMMAANNDDSS
-------------------++--------------------------------- -------------------++---------------------------------
|| $-1 $1 0 0 || $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that 2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at period, accumulating the changes across periods, starting from 0 at
the report start date: the report start date:
$ hledger balance --quarterly income expenses -E --cumulative $ hledger balance --quarterly income expenses -E --cumulative
@ -735,8 +759,8 @@ CCOOMMMMAANNDDSS
|| $-1 0 0 0 || $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending 3. With --historical/-H: each column shows the actual historical ending
balance for that period, accumulating the changes across periods, balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is 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 useful eg for a multi-period balance sheet, and when you are showing
only the data after a certain start date: only the data after a certain start date:
@ -752,26 +776,26 @@ CCOOMMMMAANNDDSS
----------------------++------------------------------------- ----------------------++-------------------------------------
|| 0 0 0 || 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. to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass 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- the displayed report periods. This is so that the first and last peri-
ods will be "full" and comparable to the others. ods will be "full" and comparable to the others.
The -E/--empty flag does two things in multicolumn balance reports: The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the date will be considered, not just the ones with activity during the
report period (use -E to include low-activity accounts which would oth- report period (use -E to include low-activity accounts which would oth-
erwise would be omitted). erwise would be omitted).
The -T/--row-total flag adds an additional column showing the total for The -T/--row-total flag adds an additional column showing the total for
each row. each row.
The -A/--average flag adds a column showing the average value in each The -A/--average flag adds a column showing the average value in each
row. row.
Here's an example of all three: Here's an example of all three:
@ -794,16 +818,16 @@ CCOOMMMMAANNDDSS
MMaarrkkeett vvaalluuee MMaarrkkeett vvaalluuee
The -V/--value flag converts all the reported amounts to their "current The -V/--value flag converts all the reported amounts to their "current
market value" using their default market price. That is the latest market value" using their default market price. That is the latest
market price (P directive) found in the journal (or an included file), 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. 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 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. amounts (which -B/--cost uses). Using -B and -V together is allowed.
CCuussttoomm bbaallaannccee oouuttppuutt 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: output with --format FMT:
$ hledger balance --format "%20(account) %12(total)" $ hledger balance --format "%20(account) %12(total)"
@ -821,7 +845,7 @@ CCOOMMMMAANNDDSS
0 0
The FMT format string (plus a newline) specifies the formatting applied 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: data fields interpolated like so:
%[MIN][.MAX](FIELDNAME) %[MIN][.MAX](FIELDNAME)
@ -832,14 +856,14 @@ CCOOMMMMAANNDDSS
+o FIELDNAME must be enclosed in parentheses, and can be one of: +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. if MIN is specified, MIN * depth spaces.
+o account - the account's name +o account - the account's name
+o total - the account's balance/posted total, right justified +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: modity amounts are rendered:
+o %_ - render on multiple lines, bottom-aligned (the default) +o %_ - render on multiple lines, bottom-aligned (the default)
@ -848,7 +872,7 @@ CCOOMMMMAANNDDSS
+o %, - render on one line, comma-separated +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. effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results. Experimentation may be needed to get pleasing results.
@ -856,19 +880,19 @@ CCOOMMMMAANNDDSS
+o %(total) - the account's total +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 characters and clipped at 20 characters
+o %,%-50(account) %25(total) - account name padded to 50 characters, +o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on total padded to 20 characters, with multiple commodities rendered on
one line 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 single-column balance report
OOuuttppuutt ddeessttiinnaattiioonn OOuuttppuutt ddeessttiinnaattiioonn
The balance, print, register and stats commands can write their output The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the to a destination other than the console. This is controlled by the
-o/--output-file option. -o/--output-file option.
$ hledger balance -o - # write to stdout (the default) $ hledger balance -o - # write to stdout (the default)
@ -876,8 +900,8 @@ CCOOMMMMAANNDDSS
CCSSVV oouuttppuutt CCSSVV oouuttppuutt
The balance, print and register commands can write their output as CSV. The balance, print and register commands can write their output as CSV.
This is useful for exporting data to other applications, eg to make This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the -O/--output-format charts in a spreadsheet. This is controlled by the -O/--output-format
option, or by specifying a .csv file extension with -o/--output-file. option, or by specifying a .csv file extension with -o/--output-file.
$ hledger balance -O csv # write CSV to stdout $ hledger balance -O csv # write CSV to stdout
@ -891,8 +915,8 @@ CCOOMMMMAANNDDSS
----ddrroopp==NN ----ddrroopp==NN
in flat mode: omit N leading account name parts in flat mode: omit N leading account name parts
This command displays a simple balance sheet. It currently assumes This command displays a simple balance sheet. It currently assumes
that you have top-level accounts named asset and liability (plural that you have top-level accounts named asset and liability (plural
forms also allowed.) forms also allowed.)
$ hledger balancesheet $ hledger balancesheet
@ -922,9 +946,9 @@ CCOOMMMMAANNDDSS
----ddrroopp==NN ----ddrroopp==NN
in flat mode: omit N leading account name parts in flat mode: omit N leading account name parts
This command displays a simple cashflow statement It shows the change This command displays a simple cashflow statement It shows the change
in all "cash" (ie, liquid assets) accounts for the period. It cur- in all "cash" (ie, liquid assets) accounts for the period. It cur-
rently assumes that cash accounts are under a top-level account named 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.) asset and do not contain receivable or A/R (plural forms also allowed.)
$ hledger cashflow $ hledger cashflow
@ -944,11 +968,11 @@ CCOOMMMMAANNDDSS
hheellpp hheellpp
Show one of the hledger manuals. Show one of the hledger manuals.
The help command displays any of the main hledger man pages. (Unlike The help command displays any of the main hledger man pages. (Unlike
hledger --help, which displays only the hledger man page.) Run it with hledger --help, which displays only the hledger man page.) Run it with
no arguments to list available topics (their names are shortened for no arguments to list available topics (their names are shortened for
easier typing), and run hledger help TOPIC to select one. The output 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 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. wish to pipe it into a pager. See also info and man.
$ hledger help $ hledger help
@ -977,8 +1001,8 @@ CCOOMMMMAANNDDSS
----ddrroopp==NN ----ddrroopp==NN
in flat mode: omit N leading account name parts in flat mode: omit N leading account name parts
This command displays a simple income statement. It currently assumes This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.) (plural forms also allowed.)
$ hledger incomestatement $ hledger incomestatement
@ -1005,30 +1029,30 @@ CCOOMMMMAANNDDSS
iinnffoo iinnffoo
Show one of the hledger manuals using info. Show one of the hledger manuals using info.
The info command displays any of the hledger reference manuals using The info command displays any of the hledger reference manuals using
the info hypertextual documentation viewer. This can be a very effi- the info hypertextual documentation viewer. This can be a very effi-
cient way to browse large manuals. It requires the "info" program to cient way to browse large manuals. It requires the "info" program to
be available in your PATH. 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). als).
mmaann mmaann
Show one of the hledger manuals using man. Show one of the hledger manuals using man.
The man command displays any of the hledger reference manuals using The man command displays any of the hledger reference manuals using
man, the standard documentation viewer on unix systems. This will fit man, the standard documentation viewer on unix systems. This will fit
the text to your terminal width, and probably invoke a pager automati- the text to your terminal width, and probably invoke a pager automati-
cally. It requires the "man" program to be available in your PATH. 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). als).
pprriinntt pprriinntt
Show transactions from the journal. Show transactions from the journal.
--mm SSTTRR ----mmaattcchh==SSTTRR --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 and is most recent
--oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]]
@ -1060,12 +1084,12 @@ CCOOMMMMAANNDDSS
liabilities:debts $1 liabilities:debts $1
assets:bank:checking $-1 assets:bank:checking $-1
The print command displays full transactions from the journal file, The print command displays full transactions from the journal file,
tidily formatted and showing all amounts explicitly. The output of tidily formatted and showing all amounts explicitly. The output of
print is always a valid hledger journal, but it does always not pre- print is always a valid hledger journal, but it does always not pre-
serve all original content exactly (eg directives). 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. -B/--cost) shows cost amounts.
The print command also supports output destination and CSV output. The print command also supports output destination and CSV output.
@ -1077,14 +1101,14 @@ CCOOMMMMAANNDDSS
include prior postings in the running total include prior postings in the running total
--AA ----aavveerraaggee --AA ----aavveerraaggee
show a running average instead of the running total (implies show a running average instead of the running total (implies
--empty) --empty)
--rr ----rreellaatteedd --rr ----rreellaatteedd
show postings' siblings instead show postings' siblings instead
--ww NN ----wwiiddtthh==NN --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) sets description width as well)
--oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]]
@ -1095,7 +1119,7 @@ CCOOMMMMAANNDDSS
select the output format. Supported formats: txt, csv. select the output format. Supported formats: txt, csv.
The register command displays postings, one per line, and their running The register command displays postings, one per line, and their running
total. This is typically used with a query selecting a particular total. This is typically used with a query selecting a particular
account, to see that account's activity: account, to see that account's activity:
$ hledger register checking $ hledger register checking
@ -1104,8 +1128,8 @@ CCOOMMMMAANNDDSS
2008/06/02 save assets:bank:checking $-1 $1 2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0 2008/12/31 pay off assets:bank:checking $-1 0
The --historical/-H flag adds the balance from any undisplayed prior The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance: only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical $ hledger register checking -b 2008/6 --historical
@ -1115,22 +1139,22 @@ CCOOMMMMAANNDDSS
The --depth option limits the amount of sub-account detail displayed. The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It the whole report period). This flag implies --empty (see below). It
works best when showing just one account and one commodity. 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. the postings which would normally be shown.
With a reporting interval, register shows summary postings, one per With a reporting interval, register shows summary postings, one per
interval, aggregating the postings to each account: interval, aggregating the postings to each account:
$ hledger register --monthly income $ hledger register --monthly income
2008/01 income:salary $-1 $-1 2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2 2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them: not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E $ hledger register --monthly income -E
@ -1147,7 +1171,7 @@ CCOOMMMMAANNDDSS
2008/11 0 $-2 2008/11 0 $-2
2008/12 0 $-2 2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated: option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h $ hledger register --monthly assets --depth 1h
@ -1155,19 +1179,19 @@ CCOOMMMMAANNDDSS
2008/06 assets $-1 0 2008/06 assets $-1 0
2008/12 assets $-1 $-1 2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report. length and comparable to the others in the report.
CCuussttoomm rreeggiisstteerr oouuttppuutt CCuussttoomm rreeggiisstteerr oouuttppuutt
register uses the full terminal width by default, except on windows. register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option. a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a (about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated: description width as part of --width's argument, comma-separated:
--width W,D . Here's a diagram: --width W,D . Here's a diagram:
<--------------------------------- width (W) ----------------------------------> <--------------------------------- width (W) ---------------------------------->
@ -1183,7 +1207,7 @@ CCOOMMMMAANNDDSS
$ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
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. put-format options for controlling output destination and CSV output.
ssttaattss ssttaattss
@ -1205,8 +1229,8 @@ CCOOMMMMAANNDDSS
Accounts : 8 (depth 3) Accounts : 8 (depth 3)
Commodities : 1 ($) Commodities : 1 ($)
The stats command displays summary information for the whole journal, The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report or a matched part of it. With a reporting interval, it shows a report
for each report period. for each report period.
The stats command also supports -o/--output-file for controlling output The stats command also supports -o/--output-file for controlling output
@ -1218,37 +1242,37 @@ CCOOMMMMAANNDDSS
$ hledger test $ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0 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 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 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. be able to check your hledger executable for smoke at any time.
AADDDD--OONN CCOOMMMMAANNDDSS AADDDD--OONN CCOOMMMMAANNDDSS
Add-on commands are executables in your PATH whose name starts with Add-on commands are executables in your PATH whose name starts with
hledger- and ends with any of these file extensions: none, 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 .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. 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 hledger will detect these and include them in the command list and let
you invoke them with hledger ADDONCMD. However there are some limita- you invoke them with hledger ADDONCMD. However there are some limita-
tions: tions:
+o Options appearing before ADDONCMD will be visible only to hledger and +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 will not be passed to the add-on. Eg: hledger -h web shows hledger's
usage, hledger web -h shows hledger-web's usage. usage, hledger web -h shows hledger-web's usage.
+o Options understood only by the add-on must go after a -- argument to +o Options understood only by the add-on must go after a -- argument to
hide them from hledger, which would otherwise reject them. Eg: hide them from hledger, which would otherwise reject them. Eg:
hledger web -- --server. 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. eg: hledger-web --server.
Add-ons which are written in haskell can take advantage of the Add-ons which are written in haskell can take advantage of the
hledger-lib library for journal parsing, reporting, command-line hledger-lib library for journal parsing, reporting, command-line
options, etc. 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: tory in the hledger source, or elsewhere:
aappii aappii
@ -1306,11 +1330,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
WF:4303001832 -$6.00 WF:4303001832 -$6.00
[assets:business:bank:wf:bchecking:banking] $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 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 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 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 alternative to hledger's built-in CSV reader, especially if your bank
supports OFX download. supports OFX download.
ddiiffff ddiiffff
@ -1336,9 +1360,9 @@ AADDDD--OONN CCOOMMMMAANNDDSS
2015/02/02 2015/02/02
(acct:two) $2 (acct:two) $2
hledger-diff compares two journal files. Given an account name, it hledger-diff compares two journal files. Given an account name, it
prints out the transactions affecting that account which are in one prints out the transactions affecting that account which are in one
journal file but not in the other. This can be useful for reconciling journal file but not in the other. This can be useful for reconciling
existing journals with bank statements. existing journals with bank statements.
eeqquuiittyy eeqquuiittyy
@ -1365,14 +1389,14 @@ AADDDD--OONN CCOOMMMMAANNDDSS
equity:opening balances 0 equity:opening balances 0
This prints a journal entry which zeroes out the specified accounts (or This prints a journal entry which zeroes out the specified accounts (or
all accounts) with a transfer to/from "equity:closing balances" (like all accounts) with a transfer to/from "equity:closing balances" (like
Ledger's equity command). Also, it prints an similar entry with oppo- Ledger's equity command). Also, it prints an similar entry with oppo-
site sign for restoring the balances from "equity:opening balances". site sign for restoring the balances from "equity:opening balances".
These can be useful for ending one journal file and starting a new one, 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 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. file, or on several files concatenated with include.
iinntteerreesstt iinntteerreesstt
@ -1453,11 +1477,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
Liabilities:Bank EUR 3700.00 Liabilities:Bank EUR 3700.00
hledger-interest computes interests for a given account. Using command hledger-interest computes interests for a given account. Using command
line flags, the program can be configured to use various schemes for 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- 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. thermore, it supports a (small) number of interest schemes, i.e.
annual interest with a fixed rate and the scheme mandated by the German 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. for more.
iirrrr iirrrr
@ -1515,11 +1539,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
2011/04/01 - 2011/05/01: 32.24% 2011/04/01 - 2011/05/01: 32.24%
2011/05/01 - 2011/06/01: 95.92% 2011/05/01 - 2011/06/01: 95.92%
hledger-irr computes the internal rate of return, also known as the hledger-irr computes the internal rate of return, also known as the
effective interest rate, of a given investment. After specifying what effective interest rate, of a given investment. After specifying what
account holds the investment, and what account stores the gains (or account holds the investment, and what account stores the gains (or
losses, or fees, or cost), it calculates the hypothetical annual rate losses, or fees, or cost), it calculates the hypothetical annual rate
of fixed rate investment that would have provided the exact same cash of fixed rate investment that would have provided the exact same cash
flow. See the package page for more. flow. See the package page for more.
pprriinntt--uunniiqquuee pprriinntt--uunniiqquuee
@ -1539,6 +1563,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
Prints all journal entries, adding specified custom postings to matched Prints all journal entries, adding specified custom postings to matched
entries. 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 -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'