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

243
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,60 +154,66 @@ 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
@ -214,18 +226,21 @@ FFIILLEE FFOORRMMAATT
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.
@ -429,7 +444,7 @@ FFIILLEE FFOORRMMAATT
(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
@ -554,37 +569,40 @@ FFIILLEE FFOORRMMAATT
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.
@ -613,13 +631,10 @@ FFIILLEE FFOORRMMAATT
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

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

@ -9,11 +9,10 @@ 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

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

57
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,11 +218,20 @@ 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-
@ -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,9 +552,10 @@ 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
@ -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"'