830 lines
25 KiB
Groff
830 lines
25 KiB
Groff
|
|
.TH "hledger_journal" "5" "October 2015" "" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
hledger_journal \- reference for hledger\[aq]s journal file format
|
|
.SH DESCRIPTION
|
|
.IP \[bu] 2
|
|
toc
|
|
.PP
|
|
hledger\[aq]s usual data source is a plain text file containing journal
|
|
entries in hledger journal format.
|
|
This file represents a standard accounting general journal.
|
|
I use file names ending in \f[C]\&.journal\f[], but that\[aq]s not
|
|
required.
|
|
The journal file contains a number of transaction entries, each
|
|
describing a transfer of money (or any commodity) between two or more
|
|
named accounts, in a simple format readable by both hledger and humans.
|
|
.PP
|
|
hledger\[aq]s journal format is a compatible subset, mostly, of
|
|
ledger\[aq]s journal format, so hledger can work with compatible ledger
|
|
journal files as well.
|
|
It\[aq]s safe, and encouraged, to run both hledger and ledger on the
|
|
same journal file, eg to validate the results you\[aq]re getting.
|
|
.PP
|
|
You can use hledger without learning any more about this file; just use
|
|
the add or web commands to create and update it.
|
|
Many users, though, also edit the journal file directly with a text
|
|
editor, perhaps assisted by the helper modes for emacs or vim.
|
|
.PP
|
|
Here\[aq]s an example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ A\ sample\ journal\ file.\ This\ is\ a\ comment.
|
|
|
|
2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ transaction\[aq]s\ first\ line\ starts\ in\ column\ 0,\ contains\ date\ and\ description
|
|
\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ posting\ lines\ start\ with\ whitespace,\ each\ contains\ an\ account\ name
|
|
\ \ \ \ income:salary\ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ \ \ \ followed\ by\ at\ least\ two\ spaces\ and\ an\ amount
|
|
|
|
2008/06/01\ gift
|
|
\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ at\ least\ two\ postings\ in\ a\ transaction
|
|
\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ <\-\ their\ amounts\ must\ balance\ to\ 0
|
|
|
|
2008/06/02\ save
|
|
\ \ \ \ assets:bank:saving\ \ \ \ $1
|
|
\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ ;\ <\-\ one\ amount\ may\ be\ omitted;\ here\ $\-1\ is\ inferred
|
|
|
|
2008/06/03\ eat\ &\ shop\ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ description\ can\ be\ anything
|
|
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ expenses:supplies\ \ \ \ \ $1\ \ \ \ ;\ <\-\ this\ transaction\ debits\ two\ expense\ accounts
|
|
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ $\-2\ inferred
|
|
|
|
2008/12/31\ *\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ an\ optional\ *\ or\ !\ after\ the\ date\ means\ "cleared"\ (or\ anything\ you\ want)
|
|
\ \ \ \ liabilities:debts\ \ \ \ \ $1
|
|
\ \ \ \ assets:bank:checking
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Now let\[aq]s explore the available journal file syntax in detail.
|
|
.SH TRANSACTIONS
|
|
.PP
|
|
Transactions are represented by journal entries.
|
|
Each begins with a simple date in column 0, followed by three optional
|
|
fields with spaces between them:
|
|
.IP \[bu] 2
|
|
a status flag, which can be empty or \f[C]!\f[] or \f[C]*\f[] (meaning
|
|
"uncleared", "pending" and "cleared", or whatever you want)
|
|
.IP \[bu] 2
|
|
a transaction code (eg a check number),
|
|
.IP \[bu] 2
|
|
and/or a description
|
|
.PP
|
|
then some number of postings, of some amount to some account, each on
|
|
its own line.
|
|
Usually there are at least two postings, though one or even none is
|
|
possible.
|
|
.PP
|
|
The (real) posting amounts within a transaction must always balance, ie
|
|
add up to 0.
|
|
Optionally one amount can be left blank, in which case it will be
|
|
inferred.
|
|
.SH DATES
|
|
.SS Simple dates
|
|
.PP
|
|
Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
|
|
Leading zeroes are optional.
|
|
The year may be omitted, in which case it defaults to the current year,
|
|
or you can set the default year with a default year directive.
|
|
.PP
|
|
Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[],
|
|
\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[].
|
|
.SS Secondary dates
|
|
.PP
|
|
Real\-life transactions sometimes involve more than one date \- eg the
|
|
date you write a cheque, and the date it clears in your bank.
|
|
When you want to model this, eg for more accurate balances, write both
|
|
dates separated by an equals sign.
|
|
The \f[I]primary date\f[], on the left, is used by default; the
|
|
\f[I]secondary date\f[], on the right, is used when the
|
|
\f[C]\-\-date2\f[] flag is specified (For Ledger compatibility,
|
|
\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work.)
|
|
.PP
|
|
Their meaning is up to you, but it\[aq]s best to follow a consistent
|
|
rule.
|
|
Eg write the bank\[aq]s clearing date as primary, and when needed, the
|
|
date the transaction was initiated as secondary.
|
|
.PP
|
|
Here\[aq]s an example.
|
|
Note that a secondary date will use the year of the primary date if
|
|
unspecified.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2010/2/23=2/19\ movie\ ticket
|
|
\ \ expenses:cinema\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
|
|
\ \ assets:checking
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ checking
|
|
2010/02/23\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ checking\ \-\-date2
|
|
2010/02/19\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Secondary dates require some effort: you must use them consistently in
|
|
your journal entries and remember whether to use or not use the
|
|
\f[C]\-\-date2\f[] flag for your reports.
|
|
Arguably they are now obsolete, superseded by...
|
|
.SS Posting dates
|
|
.PP
|
|
You can give individual postings a different date from their parent
|
|
transaction, by adding a posting tag (see below) like
|
|
\f[C]date:DATE\f[], where DATE is a simple date.
|
|
This is probably the best way to control posting dates precisely.
|
|
Eg in this example the expense should appear in May reports, and the
|
|
deduction from checking should be reported on 6/1 for easy bank
|
|
reconciliation:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2015/5/30
|
|
\ \ \ \ expenses:food\ \ \ \ \ $10\ \ \ ;\ food\ purchased\ on\ saturday\ 5/30
|
|
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ ;\ bank\ cleared\ it\ on\ monday,\ date:6/1
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ tt.j\ register\ food
|
|
2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ tt.j\ register\ checking
|
|
2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
A posting date will use the year of the transaction date if unspecified.
|
|
.PP
|
|
You can also set the secondary date, with \f[C]date2:DATE2\f[].
|
|
For compatibility, Ledger\[aq]s older posting date syntax is also
|
|
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]
|
|
in a posting comment.
|
|
.PP
|
|
When using any of these forms, be sure to provide a valid simple date or
|
|
you\[aq]ll get a parse error.
|
|
Eg a \f[C]date:\f[] tag with no value is not allowed.
|
|
.SH ACCOUNT NAMES
|
|
.PP
|
|
Account names typically have several parts separated by a full colon,
|
|
from which hledger derives a hierarchical chart of accounts.
|
|
They can be anything you like, but in finance there are traditionally
|
|
five top\-level accounts: \f[C]assets\f[], \f[C]liabilities\f[],
|
|
\f[C]income\f[], \f[C]expenses\f[], and \f[C]equity\f[].
|
|
.PP
|
|
Account names may contain single spaces, eg:
|
|
\f[C]assets:accounts\ receivable\f[].
|
|
Because of this, they must always be followed by at least two spaces (or
|
|
newline).
|
|
.PP
|
|
Account names can be aliased.
|
|
.SH AMOUNTS
|
|
.PP
|
|
After the account name, there is usually an amount.
|
|
Important: between account name and amount, there must be \f[B]two or
|
|
more\f[] spaces.
|
|
.PP
|
|
The amount is a number, optionally with a currency symbol or commodity
|
|
name on either the left or right.
|
|
Negative amounts may have the minus sign either before or after the
|
|
currency symbol (\f[C]\-$1\f[] or \f[C]$\-1\f[]).
|
|
Commodity names which contain more than just letters should be enclosed
|
|
in double quotes (\f[C]1\ "person\ hours"\f[]).
|
|
.SS Decimal points and digit groups
|
|
.PP
|
|
hledger supports flexible decimal point and digit group separator
|
|
styles, to support international variations.
|
|
Numbers can use either a period (\f[C]\&.\f[]) or a comma (\f[C],\f[])
|
|
as decimal point.
|
|
They can also have digit group separators at any position (eg thousands
|
|
separators) which can be comma or period \- whichever one you did not
|
|
use as a decimal point.
|
|
If you use digit group separators, you must also include a decimal point
|
|
in at least one number in the same commodity, so that hledger knows
|
|
which character is which.
|
|
Eg, write \f[C]$1,000.00\f[] or \f[C]$1.000,00\f[].
|
|
.SS Amount display styles
|
|
.PP
|
|
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:
|
|
.IP \[bu] 2
|
|
the position (left or right) and spacing (space or no separator) of the
|
|
commodity symbol
|
|
.IP \[bu] 2
|
|
the digit group separator character (comma or period) and digit group
|
|
sizes, if any
|
|
.IP \[bu] 2
|
|
the decimal point character (period or comma)
|
|
.IP \[bu] 2
|
|
the display precision (number of decimal places displayed)
|
|
.PP
|
|
The canonical style is generally the style of the first posting amount
|
|
seen in a commodity.
|
|
However the display precision will be the highest precision seen in all
|
|
posting amounts in that commmodity.
|
|
.PP
|
|
The precisions used in a price amount, or a D directive, don\[aq]t
|
|
affect the canonical display precision directly, but they can affect it
|
|
indirectly, eg when D\[aq]s default commodity is applied to a
|
|
commodity\-less amount or when an amountless posting is balanced using a
|
|
price\[aq]s commodity (actually this last case does not influence the
|
|
canonical display precision but probably should).
|
|
.SH VIRTUAL POSTINGS
|
|
.PP
|
|
When you parenthesise the account name in a posting, that posting is
|
|
considered \f[I]virtual\f[], which means:
|
|
.IP \[bu] 2
|
|
it is ignored when checking that the transaction is balanced
|
|
.IP \[bu] 2
|
|
it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used,
|
|
or the \f[C]real:1\f[] query.
|
|
.PP
|
|
You could use this, eg, to set an account\[aq]s opening balance without
|
|
needing to use the \f[C]equity:opening\ balances\f[] account:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
1/1\ special\ unbalanced\ posting\ to\ set\ initial\ balance
|
|
\ \ (assets:checking)\ \ \ $1000
|
|
\f[]
|
|
.fi
|
|
.SS Balanced Virtual Postings
|
|
.PP
|
|
When the account name is bracketed, the posting is \f[I]balanced
|
|
virtual\f[], which is just like a virtual posting except the balanced
|
|
virtual postings in a transaction must balance to 0, like the real
|
|
postings (but separately from them).
|
|
Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or
|
|
\f[C]real:1\f[].
|
|
.PP
|
|
Virtual postings are a feature inherited from Ledger can can
|
|
occasionally be useful, but they can be a crutch and you should think
|
|
twice or three times before using them.
|
|
You can almost always find an equivalent journal entry using two or more
|
|
real postings that will be more correct and more error\-proof.
|
|
.SH BALANCE ASSERTIONS
|
|
.PP
|
|
hledger supports ledger\-style balance assertions in journal files.
|
|
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
|
|
amount.
|
|
Eg in this example we assert the expected dollar balance in accounts a
|
|
and b after each posting:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2013/1/1
|
|
\ \ a\ \ \ $1\ \ =$1
|
|
\ \ b\ \ \ \ \ \ \ =$\-1
|
|
|
|
2013/1/2
|
|
\ \ a\ \ \ $1\ \ =$2
|
|
\ \ b\ \ $\-1\ \ =$\-2
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
After reading a journal file, hledger will check all balance assertions
|
|
and report an error if any of them fail.
|
|
Balance assertions can protect you from, eg, inadvertently disrupting
|
|
reconciled balances while cleaning up old entries.
|
|
You can disable them temporarily with the
|
|
\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for
|
|
troubleshooting or for reading Ledger files.
|
|
.SS Assertions and ordering
|
|
.PP
|
|
hledger sorts an account\[aq]s postings and assertions first by date and
|
|
then (for postings on the same day) by parse order.
|
|
Note this is different from Ledger, which sorts assertions only by parse
|
|
order.
|
|
(Also, Ledger assertions do not see the accumulated effect of repeated
|
|
postings to the same account within a transaction.)
|
|
.PP
|
|
So, hledger balance assertions keep working if you reorder
|
|
differently\-dated transactions within the journal.
|
|
But if you reorder same\-dated transactions or postings, assertions
|
|
might break and require updating.
|
|
This order dependence does bring an advantage: precise control over the
|
|
order of postings and assertions within a day, so you can assert
|
|
intra\-day balances.
|
|
.PP
|
|
With included files, things are a little more complicated.
|
|
Including preserves the ordering of postings and assertions.
|
|
If you have multiple postings to an account on the same day, split
|
|
across different files, and you also want to assert the account\[aq]s
|
|
balance on the same day, you\[aq]ll have to put the assertion in the
|
|
right file.
|
|
.SS Assertions and commodities
|
|
.PP
|
|
The asserted balance must be a simple single\-commodity amount, and in
|
|
fact the assertion checks only this commodity\[aq]s balance within the
|
|
(possibly multi\-commodity) account balance.
|
|
We could call this a partial balance assertion.
|
|
This is compatible with Ledger, and makes it possible to make assertions
|
|
about accounts containing multiple commodities.
|
|
.PP
|
|
To assert each commodity\[aq]s balance in such a multi\-commodity
|
|
account, you can add multiple postings (with amount 0 if necessary).
|
|
But note that no matter how many assertions you add, you can\[aq]t be
|
|
sure the account does not contain some unexpected commodity.
|
|
(We\[aq]ll add support for this kind of total balance assertion if
|
|
there\[aq]s demand.)
|
|
.SS Assertions and subaccounts
|
|
.PP
|
|
Balance assertions do not count the balance from subaccounts; they check
|
|
the posted account\[aq]s exclusive balance.
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
1/1
|
|
\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1
|
|
\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1
|
|
\ \ equity
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The balance report\[aq]s flat mode shows these exclusive balances more
|
|
clearly:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ bal\ checking\ \-\-flat
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2
|
|
\f[]
|
|
.fi
|
|
.SS Assertions and virtual postings
|
|
.PP
|
|
Balance assertions are checked against all postings, both real and
|
|
virtual.
|
|
They are not affected by the \f[C]\-\-real/\-R\f[] flag or
|
|
\f[C]real:\f[] query.
|
|
.SH PRICES
|
|
.SS Transaction prices
|
|
.PP
|
|
When recording a transaction, you can also record an amount\[aq]s price
|
|
in another commodity.
|
|
This documents the exchange rate, cost (of a purchase), or selling price
|
|
(of a sale) that was in effect within this particular transaction (or
|
|
more precisely, within the particular posting).
|
|
These transaction prices are fixed, and do not change.
|
|
.PP
|
|
Such priced amounts can be displayed in their transaction price\[aq]s
|
|
commodity, by using the \f[C]\-\-cost/\-B\f[] flag (B for "cost Basis"),
|
|
supported by most hledger commands.
|
|
.PP
|
|
There are three ways to specify a transaction price:
|
|
.IP "1." 3
|
|
Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[]
|
|
after the amount:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each
|
|
\ \ assets:cash
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.IP "2." 3
|
|
Or write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot
|
|
\ \ assets:cash
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.IP "3." 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
|
|
sum must have a non\-zero amount in exactly two commodities:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros
|
|
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.PP
|
|
With any of the above examples we get:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print\ \-B
|
|
2009/01/01
|
|
\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00
|
|
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Example use for transaction prices: recording the effective conversion
|
|
rate of purchases made in a foreign currency.
|
|
.SS Market prices
|
|
.PP
|
|
Market prices are not tied to a particular transaction; they represent
|
|
historical exchange rates between two commodities, usually from some
|
|
public market which publishes such rates.
|
|
.PP
|
|
When market prices are known, the \f[C]\-V/\-\-value\f[] option will use
|
|
them to convert reported amounts to their market value as of the report
|
|
end date.
|
|
This option is currently available only with the balance command.
|
|
.PP
|
|
You record market prices (Ledger calls them historical prices) with a P
|
|
directive, in the journal or perhaps in a separate included file.
|
|
Market price directives have the format:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
P\ DATE\ COMMODITYSYMBOL\ UNITPRICE
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
For example, the following directives say that the euro\[aq]s exchange
|
|
rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
|
|
unknown before 2009).
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
P\ 2009/1/1\ €\ $1.35
|
|
P\ 2010/1/1\ €\ $1.40
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Example use for market prices: tracking the value of stocks.
|
|
.SH COMMENTS
|
|
.PP
|
|
Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
|
|
(\f[C]#\f[]) or asterisk (\f[C]*\f[]) are comments, and will be ignored.
|
|
(Asterisk comments make it easy to treat your journal like an org\-mode
|
|
outline in emacs.)
|
|
.PP
|
|
Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[]
|
|
directives is a (multi\-line) comment.
|
|
If there is no \f[C]end\ comment\f[], the comment extends to the end of
|
|
the file.
|
|
.PP
|
|
You can attach comments to a transaction by writing them after the
|
|
description and/or indented on the following lines (before the
|
|
postings).
|
|
Similarly, you can attach comments to an individual posting by writing
|
|
them after the amount and/or indented on the following lines.
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ a\ journal\ comment
|
|
|
|
;\ also\ a\ journal\ comment
|
|
|
|
comment
|
|
This\ is\ a\ multiline\ comment,
|
|
which\ continues\ until\ a\ line
|
|
where\ the\ "end\ comment"\ string
|
|
appears\ on\ its\ own.
|
|
end\ comment
|
|
|
|
2012/5/14\ something\ \ ;\ a\ transaction\ comment
|
|
\ \ \ \ ;\ the\ transaction\ comment,\ continued
|
|
\ \ \ \ posting1\ \ 1\ \ ;\ a\ comment\ for\ posting\ 1
|
|
\ \ \ \ posting2
|
|
\ \ \ \ ;\ a\ comment\ for\ posting\ 2
|
|
\ \ \ \ ;\ another\ comment\ line\ for\ posting\ 2
|
|
;\ a\ journal\ comment\ (because\ not\ indented)
|
|
\f[]
|
|
.fi
|
|
.SH TAGS
|
|
.PP
|
|
A \f[I]tag\f[] is a word followed by a full colon inside a transaction
|
|
or posting comment.
|
|
You can write multiple tags, comma separated.
|
|
Eg: \f[C];\ a\ comment\ containing\ sometag:,\ anothertag:\f[].
|
|
You can search for tags with the \f[C]tag:\f[] query.
|
|
.PP
|
|
A tag can also have a value, which is any text between the colon and the
|
|
next comma or newline, excluding leading/trailing whitespace.
|
|
(So hledger tag values can not contain commas or newlines).
|
|
.PP
|
|
Tags in a transaction comment affect the transaction and all of its
|
|
postings, while tags in a posting comment affect only that posting.
|
|
For example, the following transaction has three tags (A, TAG2,
|
|
third\-tag) and the posting has four (A, TAG2, third\-tag,
|
|
posting\-tag):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
1/1\ a\ transaction\ \ ;\ A:,\ TAG2:
|
|
\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ this\ time\ with\ a\ value
|
|
\ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag:
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
|
|
values are always simple strings.
|
|
.SH DIRECTIVES
|
|
.SS Account aliases
|
|
.PP
|
|
You can define aliases which rewrite your account names (after reading
|
|
the journal, before generating reports).
|
|
hledger\[aq]s account aliases can be useful for:
|
|
.IP \[bu] 2
|
|
expanding shorthand account names to their full form, allowing easier
|
|
data entry and a less verbose journal
|
|
.IP \[bu] 2
|
|
adapting old journals to your current chart of accounts
|
|
.IP \[bu] 2
|
|
experimenting with new account organisations, like a new hierarchy or
|
|
combining two accounts into one
|
|
.IP \[bu] 2
|
|
customising reports
|
|
.PP
|
|
See also How to use account aliases.
|
|
.SS Basic aliases
|
|
.PP
|
|
To set an account alias, use the \f[C]alias\f[] directive in your
|
|
journal file.
|
|
This affects all subsequent journal entries in the current file or its
|
|
included files.
|
|
The spaces around the = are optional:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
alias\ OLD\ =\ NEW
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the
|
|
command line.
|
|
This affects all entries.
|
|
It\[aq]s useful for trying out aliases interactively.
|
|
.PP
|
|
OLD and NEW are full account names.
|
|
hledger will replace any occurrence of the old account name with the new
|
|
one.
|
|
Subaccounts are also affected.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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"
|
|
\f[]
|
|
.fi
|
|
.SS Regex aliases
|
|
.PP
|
|
There is also a more powerful variant that uses a regular expression,
|
|
indicated by the forward slashes.
|
|
(This was the default behaviour in hledger 0.24\-0.25):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
alias\ /REGEX/\ =\ REPLACEMENT
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or \f[C]\-\-alias\ \[aq]/REGEX/=REPLACEMENT\[aq]\f[].
|
|
.PP
|
|
REGEX is a case\-insensitive regular expression.
|
|
Anywhere it matches inside an account name, the matched part will be
|
|
replaced by REPLACEMENT.
|
|
If REGEX contains parenthesised match groups, these can be referenced by
|
|
the usual numeric backreferences in REPLACEMENT.
|
|
Note, currently regular expression aliases may cause noticeable
|
|
slow\-downs.
|
|
(And if you use Ledger on your hledger file, they will be ignored.) Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
alias\ /^(.+):bank:([^:]+)(.*)/\ =\ \\1:\\2\ \\3
|
|
#\ rewrites\ "assets:bank:wells\ fargo:checking"\ to\ \ "assets:wells\ fargo\ checking"
|
|
\f[]
|
|
.fi
|
|
.SS Multiple aliases
|
|
.PP
|
|
You can define as many aliases as you like using directives or
|
|
command\-line options.
|
|
Aliases are recursive \- each alias sees the result of applying previous
|
|
ones.
|
|
(This is different from Ledger, where aliases are non\-recursive by
|
|
default).
|
|
Aliases are applied in the following order:
|
|
.IP "1." 3
|
|
alias directives, most recently seen first (recent directives take
|
|
precedence over earlier ones; directives not yet seen are ignored)
|
|
.IP "2." 3
|
|
alias options, in the order they appear on the command line
|
|
.SS end aliases
|
|
.PP
|
|
You can clear (forget) all currently defined aliases with the
|
|
\f[C]end\ aliases\f[] directive:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
end\ aliases
|
|
\f[]
|
|
.fi
|
|
.SS account directive
|
|
.PP
|
|
The \f[C]account\f[] directive predefines account names, as in Ledger
|
|
and Beancount.
|
|
This may be useful for your own documentation; hledger doesn\[aq]t make
|
|
use of it yet.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ account\ ACCT
|
|
;\ \ \ OPTIONAL\ COMMENTS/TAGS...
|
|
|
|
account\ assets:bank:checking
|
|
\ a\ comment
|
|
\ acct\-no:12345
|
|
|
|
account\ expenses:food
|
|
|
|
;\ etc.
|
|
\f[]
|
|
.fi
|
|
.SS apply account directive
|
|
.PP
|
|
You can specify a parent account which will be prepended to all accounts
|
|
within a section of the journal.
|
|
Use the \f[C]apply\ account\f[] and \f[C]end\ apply\ account\f[]
|
|
directives like so:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
apply\ account\ home
|
|
|
|
2010/1/1
|
|
\ \ \ \ food\ \ \ \ $10
|
|
\ \ \ \ cash
|
|
|
|
end\ apply\ account
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
which is equivalent to:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2010/01/01
|
|
\ \ \ \ home:food\ \ \ \ \ \ \ \ \ \ \ $10
|
|
\ \ \ \ home:cash\ \ \ \ \ \ \ \ \ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If \f[C]end\ apply\ account\f[] is omitted, the effect lasts to the end
|
|
of the file.
|
|
Included files are also affected, eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
apply\ account\ business
|
|
include\ biz.journal
|
|
end\ apply\ account
|
|
apply\ account\ personal
|
|
include\ personal.journal
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Prior to hledger 0.28, legacy \f[C]account\f[] and \f[C]end\f[]
|
|
spellings were also supported.
|
|
.SS Multi\-line comments
|
|
.PP
|
|
A line containing just \f[C]comment\f[] starts a multi\-line comment,
|
|
and a line containing just \f[C]end\ comment\f[] ends it.
|
|
See comments.
|
|
.SS Default commodity
|
|
.PP
|
|
You can set a default commodity, to be used for amounts without one.
|
|
Use the D directive with a sample amount.
|
|
The commodity (and the sample amount\[aq]s display style) will be
|
|
applied to all subsequent commodity\-less amounts, up to the next D
|
|
directive.
|
|
(Note this is different from Ledger\[aq]s default commodity directive.)
|
|
.PP
|
|
Also note the directive itself does not influence the commodity\[aq]s
|
|
default display style, but the amount it is applied to might.
|
|
Here\[aq]s an example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ set\ £\ as\ the\ default\ commodity
|
|
D\ £1,000.00
|
|
|
|
2010/1/1
|
|
\ \ a\ \ 2340
|
|
\ \ b
|
|
|
|
2014/1/1
|
|
\ \ c\ \ £1000
|
|
\ \ d
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print
|
|
2010/01/01
|
|
\ \ \ \ a\ \ \ \ \ £2,340.00
|
|
\ \ \ \ b\ \ \ \ £\-2,340.00
|
|
|
|
2014/01/01
|
|
\ \ \ \ c\ \ \ \ \ £1,000.00
|
|
\ \ \ \ d\ \ \ \ £\-1,000.00
|
|
\f[]
|
|
.fi
|
|
.SS Default year
|
|
.PP
|
|
You can set a default year to be used for subsequent dates which
|
|
don\[aq]t specify a year.
|
|
This is a line beginning with \f[C]Y\f[] followed by the year.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009
|
|
|
|
12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15
|
|
\ \ expenses\ \ 1
|
|
\ \ assets
|
|
|
|
Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010
|
|
|
|
2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected
|
|
\ \ expenses\ \ 1
|
|
\ \ assets
|
|
|
|
1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31
|
|
\ \ expenses\ \ 1
|
|
\ \ assets
|
|
\f[]
|
|
.fi
|
|
.SS Including other files
|
|
.PP
|
|
You can pull in the content of additional journal files by writing an
|
|
include directive, like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
include\ path/to/file.journal
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If the path does not begin with a slash, it is relative to the current
|
|
file.
|
|
.PP
|
|
Glob patterns (\f[C]*\f[]) are not currently supported.
|
|
.PP
|
|
The \f[C]include\f[] directive may only be used in journal files, and
|
|
currently it may only include other journal files (eg, not CSV or
|
|
timelog files.)
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org.
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com>
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2015 Simon Michael.
|
|
.br
|
|
Released under GNU GPLv3+.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
|
|
.br
|
|
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
|
|
|
|
For more information, see http://hledger.org.
|