968 lines
29 KiB
Groff
968 lines
29 KiB
Groff
.\"t
|
|
|
|
.TH "hledger_journal" "5" "January 2017" "hledger dev" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
Journal \- hledger\[aq]s default file format, representing a General
|
|
Journal
|
|
.SH DESCRIPTION
|
|
.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
|
|
.SH FILE FORMAT
|
|
.SS 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 posting is on its own line, consisting of:
|
|
.IP \[bu] 2
|
|
indentation of one or more spaces (or tabs)
|
|
.IP \[bu] 2
|
|
optionally, a \f[C]!\f[] or \f[C]*\f[] status flag followed by a space
|
|
.IP \[bu] 2
|
|
an account name, optionally containing single spaces
|
|
.IP \[bu] 2
|
|
optionally, two or more spaces or tabs followed by an amount
|
|
.PP
|
|
Usually there are two or more postings, though one or none is also
|
|
possible.
|
|
The 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.
|
|
.SS Dates
|
|
.SS Simple dates
|
|
.PP
|
|
Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
|
|
Leading zeros are optional.
|
|
The year may be omitted, in which case it will be inferred from the
|
|
context \- the current transaction, the default year set with a default
|
|
year directive, or the current date when the command is run.
|
|
Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[],
|
|
\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[].
|
|
.SS Secondary dates
|
|
.PP
|
|
Real\-life transactions sometimes involve more than one date \- eg the
|
|
date you write a cheque, and the date it clears in your bank.
|
|
When you want to model this, eg for more accurate balances, you can
|
|
specify individual posting dates, which I recommend.
|
|
Or, you can use the secondary dates (aka auxiliary/effective dates)
|
|
feature, supported for compatibility with Ledger.
|
|
.PP
|
|
A secondary date can be written after the primary date, separated by an
|
|
equals sign.
|
|
The primary date, on the left, is used by default; the secondary date,
|
|
on the right, is used when the \f[C]\-\-date2\f[] flag is specified
|
|
(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work).
|
|
.PP
|
|
The meaning of secondary dates is up to you, but it\[aq]s best to follow
|
|
a consistent rule.
|
|
Eg write the bank\[aq]s clearing date as primary, and when needed, the
|
|
date the transaction was initiated as secondary.
|
|
.PP
|
|
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.
|
|
They are included in hledger for Ledger compatibility, but posting dates
|
|
are a more powerful and less confusing alternative.
|
|
.SS Posting dates
|
|
.PP
|
|
You can give individual postings a different date from their parent
|
|
transaction, by adding a posting comment containing a tag (see below)
|
|
like \f[C]date:DATE\f[].
|
|
This is probably the best way to control posting dates precisely.
|
|
Eg in this example the expense should appear in May reports, and the
|
|
deduction from checking should be reported on 6/1 for easy bank
|
|
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\ t.j\ register\ food
|
|
2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ t.j\ register\ checking
|
|
2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
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
|
|
Ledger\[aq]s earlier, more compact bracketed date syntax is also
|
|
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
|
|
hledger will attempt to parse any square\-bracketed sequence of the
|
|
\f[C]0123456789/\-.=\f[] characters in this way.
|
|
With this syntax, DATE infers its year from the transaction and DATE2
|
|
infers its year from DATE.
|
|
.SS Account names
|
|
.PP
|
|
Account names typically have several parts separated by a full colon,
|
|
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 \f[B]two or more
|
|
spaces\f[] (or newline).
|
|
.PP
|
|
Account names can be aliased.
|
|
.SS Amounts
|
|
.PP
|
|
After the account name, there is usually an amount.
|
|
Important: between account name and amount, there must be \f[B]two or
|
|
more spaces\f[].
|
|
.PP
|
|
Amounts consist of a number and (usually) a currency symbol or commodity
|
|
name.
|
|
Some examples:
|
|
.PP
|
|
\f[C]2.00001\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]$1\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]4000\ AAPL\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]3\ "green\ apples"\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]\-$1,000,000.00\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]INR\ 9,99,99,999.00\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]EUR\ \-2.000.000,00\f[]
|
|
.PP
|
|
As you can see, the amount format is somewhat flexible:
|
|
.IP \[bu] 2
|
|
amounts are a number (the "quantity") and optionally a currency
|
|
symbol/commodity name (the "commodity").
|
|
.IP \[bu] 2
|
|
the commodity is a symbol, word, or phrase, on the left or right, with
|
|
or without a separating space.
|
|
If the commodity contains numbers, spaces or non\-word punctuation it
|
|
must be enclosed in double quotes.
|
|
.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.
|
|
(Except for price amounts, which are always formatted as written).
|
|
The display format is chosen as follows:
|
|
.IP \[bu] 2
|
|
if there is a commodity directive specifying the format, that is used
|
|
.IP \[bu] 2
|
|
otherwise the format is inferred from the first posting amount in that
|
|
commodity in the journal, and the precision (number of decimal places)
|
|
will be the maximum from all posting amounts in that commmodity
|
|
.IP \[bu] 2
|
|
or if there are no such amounts in the journal, a default format is used
|
|
(like \f[C]$1000.00\f[]).
|
|
.PP
|
|
Price amounts and amounts in D directives usually don\[aq]t affect
|
|
amount format inference, but in some situations they can do so
|
|
indirectly.
|
|
(Eg when D\[aq]s default commodity is applied to a commodity\-less
|
|
amount, or when an amountless posting is balanced using a price\[aq]s
|
|
commodity, or when \-V is used.) If you find this causing problems, set
|
|
the desired format with a commodity directive.
|
|
.SS Virtual Postings
|
|
.PP
|
|
When you parenthesise the account name in a posting, we call that a
|
|
\f[I]virtual posting\f[], which means:
|
|
.IP \[bu] 2
|
|
it is ignored when checking that the transaction is balanced
|
|
.IP \[bu] 2
|
|
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
|
|
.PP
|
|
When the account name is bracketed, we call it a \f[I]balanced virtual
|
|
posting\f[].
|
|
This is like an ordinary virtual posting except the balanced virtual
|
|
postings in a transaction must balance to 0, like the real postings (but
|
|
separately from them).
|
|
Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or
|
|
\f[C]real:1\f[].
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
1/1\ buy\ food\ with\ cash,\ and\ update\ some\ budget\-tracking\ subaccounts\ elsewhere
|
|
\ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
|
|
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10
|
|
\ \ [assets:checking:available]\ \ \ \ \ $10
|
|
\ \ [assets:checking:budget:food]\ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Virtual postings have some legitimate uses, but those are few.
|
|
You can usually find an equivalent journal entry using real postings,
|
|
which is more correct and provides better error checking.
|
|
.SS Balance Assertions
|
|
.PP
|
|
hledger supports Ledger\-style balance assertions in journal files.
|
|
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.
|
|
.SS Balance Assignments
|
|
.PP
|
|
Ledger\-style balance assignments are also supported.
|
|
These are like balance assertions, but with no posting amount on the
|
|
left side of the equals sign; instead it is calculated automatically so
|
|
as to satisfy the assertion.
|
|
This can be a convenience during data entry, eg when setting opening
|
|
balances:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ starting\ a\ new\ journal,\ set\ asset\ account\ balances\
|
|
2016/1/1\ opening\ balances
|
|
\ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ =\ $409.32
|
|
\ \ assets:savings\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $735.24
|
|
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ =\ $42
|
|
\ \ equity:opening\ balances
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or when adjusting a balance to reality:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ no\ cash\ left;\ update\ balance,\ record\ any\ untracked\ spending\ as\ a\ generic\ expense
|
|
2016/1/15
|
|
\ \ assets:cash\ \ \ \ =\ $0
|
|
\ \ expenses:misc
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The calculated amount depends on the account\[aq]s balance in the
|
|
commodity at that point (which depends on the previously\-dated postings
|
|
of the commodity to that account since the last balance assertion or
|
|
assignment).
|
|
Note that using balance assignments makes your journal a little less
|
|
explicit; to know the exact amount posted, you have to run hledger or do
|
|
the calculations yourself, instead of just reading it.
|
|
.SS Prices
|
|
.SS Transaction prices
|
|
.PP
|
|
Within a transaction posting, you can record an amount\[aq]s price in
|
|
another commodity.
|
|
This can be used to document the cost (for a purchase), or selling price
|
|
(for a sale), or the exchange rate that was used, for this transaction.
|
|
These transaction prices are fixed, and do not change over time.
|
|
.PP
|
|
Amounts with transaction prices can be displayed in the transaction
|
|
price\[aq]s commodity, by using the \f[C]\-\-cost/\-B\f[] flag supported
|
|
by most hledger commands (mnemonic: "cost Basis").
|
|
.PP
|
|
There are several ways to record 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.
|
|
(Ledger calls them historical prices.) For example, the prices published
|
|
by a stock exchange or the foreign exchange market.
|
|
Some commands (balance, currently) can use this information to show the
|
|
market value of things at a given date.
|
|
.PP
|
|
To record market prices, use P directives in the main journal or in an
|
|
included file.
|
|
Their format is:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
P\ DATE\ COMMODITYBEINGPRICED\ UNITPRICE
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
DATE is a simple date as usual.
|
|
COMMODITYBEINGPRICED is the symbol of the commodity being priced (just
|
|
the symbol, no quantity).
|
|
UNITPRICE is an ordinary amount (symbol and quantity) in a second
|
|
commodity, specifying the unit price or conversion rate for the first
|
|
commodity in terms of the second, on the given date.
|
|
.PP
|
|
For example, the following directives say that one euro was worth 1.35
|
|
US dollars during 2009, and $1.40 from 2010 onward:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
P\ 2009/1/1\ €\ $1.35
|
|
P\ 2010/1/1\ €\ $1.40
|
|
\f[]
|
|
.fi
|
|
.SS 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
|
|
.SS 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 simple strings.
|
|
.SS 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 1.0, 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 commodity directive
|
|
.PP
|
|
The \f[C]commodity\f[] directive predefines commodities (currently this
|
|
is just informational), and also it may define the display format for
|
|
amounts in this commodity (overriding the automatically inferred
|
|
format).
|
|
.PP
|
|
It may be written on a single line, like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ commodity\ EXAMPLEAMOUNT
|
|
|
|
;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated,
|
|
;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and
|
|
;\ separating\ thousands\ with\ comma.
|
|
commodity\ 1,000.0000\ AAAA
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or on multiple lines, using the "format" subdirective.
|
|
In this case the commodity symbol appears twice and should be the same
|
|
in both places:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ commodity\ SYMBOL
|
|
;\ \ \ format\ EXAMPLEAMOUNT
|
|
|
|
;\ display\ indian\ rupees\ with\ currency\ name\ on\ the\ left,
|
|
;\ thousands,\ lakhs\ and\ crores\ comma\-separated,
|
|
;\ period\ as\ decimal\ point,\ and\ two\ decimal\ places.
|
|
commodity\ INR
|
|
\ \ format\ INR\ 9,99,99,999.00
|
|
\f[]
|
|
.fi
|
|
.SS Default commodity
|
|
.PP
|
|
The D directive sets a default commodity (and display format), to be
|
|
used for amounts without a commodity symbol (ie, plain numbers).
|
|
(Note this differs from Ledger\[aq]s default commodity directive.) The
|
|
commodity and display format will be applied to all subsequent
|
|
commodity\-less amounts, or until the next D directive.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars
|
|
#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places)
|
|
D\ $1,000.00
|
|
|
|
1/1
|
|
\ \ a\ \ \ \ \ 5\ \ \ \ #\ <\-\ commodity\-less\ amount,\ becomes\ $1
|
|
\ \ b
|
|
\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.
|
|
Glob patterns (\f[C]*\f[]) are not currently supported.
|
|
.PP
|
|
The \f[C]include\f[] directive can only be used in journal files.
|
|
It can include journal, timeclock or timedot files, but not CSV files.
|
|
.SH EDITOR SUPPORT
|
|
.PP
|
|
Add\-on modes exist for various text editors, to make working with
|
|
journal files easier.
|
|
They add colour, navigation aids and helpful commands.
|
|
For hledger users who edit the journal file directly (the majority),
|
|
using one of these modes is quite recommended.
|
|
.PP
|
|
These were written with Ledger in mind, but also work with hledger
|
|
files:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(16.5n) lw(51.5n).
|
|
T{
|
|
Emacs
|
|
T}@T{
|
|
http://www.ledger\-cli.org/3.0/doc/ledger\-mode.html
|
|
T}
|
|
T{
|
|
Vim
|
|
T}@T{
|
|
https://github.com/ledger/ledger/wiki/Getting\-started
|
|
T}
|
|
T{
|
|
Sublime Text
|
|
T}@T{
|
|
https://github.com/ledger/ledger/wiki/Using\-Sublime\-Text
|
|
T}
|
|
T{
|
|
Textmate
|
|
T}@T{
|
|
https://github.com/ledger/ledger/wiki/Using\-TextMate\-2
|
|
T}
|
|
T{
|
|
Text Wrangler \
|
|
T}@T{
|
|
https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-TextWrangler
|
|
T}
|
|
.TE
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger IRC channel or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2016 Simon Michael.
|
|
.br
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
|
|
ledger(1)
|
|
|
|
http://hledger.org
|