1289 lines
38 KiB
Groff
1289 lines
38 KiB
Groff
.\"t
|
|
|
|
.TH "hledger_journal" "5" "January 2018" "hledger 1.5.99" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
Journal \- hledger's default file format, representing a General Journal
|
|
.SH DESCRIPTION
|
|
.PP
|
|
hledger'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'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's journal format is a compatible subset, mostly, of ledger's
|
|
journal format, so hledger can work with compatible ledger journal files
|
|
as well.
|
|
It's safe, and encouraged, to run both hledger and ledger on the same
|
|
journal file, eg to validate the results you'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'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/10/01\ take\ a\ loan
|
|
\ \ \ \ assets:bank:checking\ \ $1
|
|
\ \ \ \ liabilities:debts\ \ \ \ $\-1
|
|
|
|
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 movements of some quantity of commodities between named
|
|
accounts.
|
|
Each transaction is represented by a journal entry beginning with a
|
|
simple date in column 0.
|
|
This can be followed by any of the following, separated by spaces:
|
|
.IP \[bu] 2
|
|
(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[])
|
|
.IP \[bu] 2
|
|
(optional) a transaction code (any short number or text, enclosed in
|
|
parentheses)
|
|
.IP \[bu] 2
|
|
(optional) a transaction description (any remaining text until end of
|
|
line or a semicolon)
|
|
.IP \[bu] 2
|
|
(optional) a transaction comment (any remaining text following a
|
|
semicolon until end of line)
|
|
.PP
|
|
Then comes zero or more (but usually at least 2) indented lines
|
|
representing\&...
|
|
.SS Postings
|
|
.PP
|
|
A posting is an addition of some amount to, or removal of some amount
|
|
from, an account.
|
|
Each posting line begins with at least one space or tab (2 or 4 spaces
|
|
is common), followed by:
|
|
.IP \[bu] 2
|
|
(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]),
|
|
followed by a space
|
|
.IP \[bu] 2
|
|
(required) an account name (any text, optionally containing \f[B]single
|
|
spaces\f[], until end of line or a double space)
|
|
.IP \[bu] 2
|
|
(optional) \f[B]two or more spaces\f[] or tabs followed by an amount.
|
|
.PP
|
|
Positive amounts are being added to the account, negative amounts are
|
|
being removed.
|
|
.PP
|
|
The amounts within a transaction must always sum up to zero.
|
|
As a convenience, one amount may be left blank; it will be inferred so
|
|
as to balance the transaction.
|
|
.PP
|
|
Be sure to note the unusual two\-space delimiter between account name
|
|
and amount.
|
|
This makes it easy to write account names containing spaces.
|
|
But if you accidentally leave only one space (or tab) before the amount,
|
|
the amount will be considered part of the account name.
|
|
.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'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.
|
|
.PP
|
|
Here'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'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'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 Status
|
|
.PP
|
|
Transactions, or individual postings within a transaction, can have a
|
|
status mark, which is a single character before the transaction
|
|
description or posting account name, separated from it by a space,
|
|
indicating one of three statuses:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
mark \
|
|
T}@T{
|
|
status
|
|
T}
|
|
_
|
|
T{
|
|
\
|
|
T}@T{
|
|
unmarked
|
|
T}
|
|
T{
|
|
\f[C]!\f[]
|
|
T}@T{
|
|
pending
|
|
T}
|
|
T{
|
|
\f[C]*\f[]
|
|
T}@T{
|
|
cleared
|
|
T}
|
|
.TE
|
|
.PP
|
|
When reporting, you can filter by status with the
|
|
\f[C]\-U/\-\-unmarked\f[], \f[C]\-P/\-\-pending\f[], and
|
|
\f[C]\-C/\-\-cleared\f[] flags; or the \f[C]status:\f[],
|
|
\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in
|
|
hledger\-ui.
|
|
.PP
|
|
Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq]
|
|
state is called \[lq]uncleared\[rq].
|
|
As of hledger 1.3 we have renamed it to unmarked for clarity.
|
|
.PP
|
|
To replicate Ledger and old hledger's behaviour of also matching
|
|
pending, combine \-U and \-P.
|
|
.PP
|
|
Status marks are optional, but can be helpful eg for reconciling with
|
|
real\-world accounts.
|
|
Some editor modes provide highlighting and shortcuts for working with
|
|
status.
|
|
Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c
|
|
C\-e, or posting status with C\-c C\-c.
|
|
.PP
|
|
What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq]
|
|
actually mean is up to you.
|
|
Here's one suggestion:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(9.9n) lw(60.1n).
|
|
T{
|
|
status
|
|
T}@T{
|
|
meaning
|
|
T}
|
|
_
|
|
T{
|
|
uncleared
|
|
T}@T{
|
|
recorded but not yet reconciled; needs review
|
|
T}
|
|
T{
|
|
pending
|
|
T}@T{
|
|
tentatively reconciled (if needed, eg during a big reconciliation)
|
|
T}
|
|
T{
|
|
cleared
|
|
T}@T{
|
|
complete, reconciled as far as possible, and considered correct
|
|
T}
|
|
.TE
|
|
.PP
|
|
With this scheme, you would use \f[C]\-PC\f[] to see the current balance
|
|
at your bank, \f[C]\-U\f[] to see things which will probably hit your
|
|
bank soon (like uncashed checks), and no flags to see the most
|
|
up\-to\-date state of your finances.
|
|
.SS Description
|
|
.PP
|
|
A transaction's description is the rest of the line following the date
|
|
and status mark (or until a comment begins).
|
|
Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it
|
|
can be used for whatever you wish, or left blank.
|
|
Transaction descriptions can be queried, unlike comments.
|
|
.SS Payee and note
|
|
.PP
|
|
You can optionally include a \f[C]|\f[] (pipe) character in a
|
|
description to subdivide it into a payee/payer name on the left and
|
|
additional notes on the right.
|
|
This may be worthwhile if you need to do more precise querying and
|
|
pivoting by payee.
|
|
.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[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]1\ 999\ 999.9455\f[]
|
|
.PP
|
|
As you can see, the amount format is somewhat flexible:
|
|
.IP \[bu] 2
|
|
amounts are a number (the \[lq]quantity\[rq]) and optionally a currency
|
|
symbol/commodity name (the \[lq]commodity\[rq]).
|
|
.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
|
|
space or comma or period and should be used as separator between all
|
|
groups
|
|
.IP \[bu] 2
|
|
decimal part can be separated by comma or period and should be different
|
|
from digit groups separator
|
|
.PP
|
|
You can use any of these variations when recording data.
|
|
However, there is some ambiguous way of representing numbers like
|
|
\f[C]$1.000\f[] and \f[C]$1,000\f[] both may mean either one thousand or
|
|
one dollar.
|
|
By default hledger will assume that this is sole delimiter is used only
|
|
for decimals.
|
|
On the other hand commodity format declared prior to that line will help
|
|
to resolve that ambiguity differently:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
commodity\ $1,000.00
|
|
|
|
2017/12/25\ New\ life\ of\ Scrooge
|
|
\ \ \ \ expenses:gifts\ \ $1,000
|
|
\ \ \ \ assets
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Though journal may contain mixed styles to represent amount, 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'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.
|
|
.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'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'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'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.
|
|
.SS Assertions and included files
|
|
.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's
|
|
balance on the same day, you'll have to put the assertion in the right
|
|
file.
|
|
.SS Assertions and multiple \-f options
|
|
.PP
|
|
Balance assertions don't work well across files specified with multiple
|
|
\-f options.
|
|
Use include or concatenate the files instead.
|
|
.SS Assertions and commodities
|
|
.PP
|
|
The asserted balance must be a simple single\-commodity amount, and in
|
|
fact the assertion checks only this commodity's balance within the
|
|
(possibly multi\-commodity) account balance.
|
|
We could call this a 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's balance in such a multi\-commodity account,
|
|
you can add multiple postings (with amount 0 if necessary).
|
|
But note that no matter how many assertions you add, you can't be sure
|
|
the account does not contain some unexpected commodity.
|
|
(We'll add support for this kind of total balance assertion if there's
|
|
demand.)
|
|
.SS Assertions and subaccounts
|
|
.PP
|
|
Balance assertions do not count the balance from subaccounts; they check
|
|
the posted account'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'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'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, you can note an amount's price in another
|
|
commodity.
|
|
This can be used to document the cost (in a purchase) or selling price
|
|
(in a sale).
|
|
For example, transaction prices are useful to record purchases of a
|
|
foreign currency.
|
|
.PP
|
|
Transaction prices are fixed, and do not change over time.
|
|
(Ledger users: Ledger uses a different syntax for fixed prices,
|
|
\f[C]{=UNITPRICE}\f[], which hledger currently ignores).
|
|
.PP
|
|
There are several ways to record a transaction price:
|
|
.IP "1." 3
|
|
Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each
|
|
\ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.IP "2." 3
|
|
Write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot
|
|
\ \ assets:dollars
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.IP "3." 3
|
|
Specify amounts for all postings, using exactly two commodities, and let
|
|
hledger infer the price that balances the transaction:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased
|
|
\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Amounts with transaction prices can be displayed in the transaction
|
|
price's commodity by using the \f[C]\-B/\-\-cost\f[] flag (except for
|
|
#551) (\[lq]B\[rq] is from \[lq]cost Basis\[rq]).
|
|
Eg for the above, here is how \-B affects the balance report:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ bal\ \-N\ \-\-flat
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
|
|
$\ hledger\ bal\ \-N\ \-\-flat\ \-B
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note \-B is sensitive to the order of postings when a transaction price
|
|
is inferred: the inferred price will be in the commodity of the last
|
|
amount.
|
|
So if example 3's postings are reversed, while the transaction is
|
|
equivalent, \-B shows something different:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2009/1/1
|
|
\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ 135\ dollars\ sold
|
|
\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ for\ 100\ euros
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ bal\ \-N\ \-\-flat\ \-B
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €\-100\ \ assets:dollars\ \ #\ <\-\ the\ dollars\[aq]\ selling\ price
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.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.
|
|
hledger can use these prices to show the market value of things at a
|
|
given date, see market value.
|
|
.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.
|
|
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 star (\f[C]*\f[]) are comments, and will be ignored.
|
|
(Star comments cause org\-mode nodes to be ignored, allowing emacs users
|
|
to fold and navigate their journals with org\-mode or orgstruct\-mode.)
|
|
.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.
|
|
Transaction and posting comments must begin with a semicolon
|
|
(\f[C];\f[]).
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ a\ file\ comment
|
|
|
|
;\ also\ a\ file\ comment
|
|
|
|
comment
|
|
This\ is\ a\ multiline\ file\ comment,
|
|
which\ continues\ until\ a\ line
|
|
where\ the\ "end\ comment"\ string
|
|
appears\ on\ its\ own\ (or\ end\ of\ file).
|
|
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\ file\ comment\ (because\ not\ indented)
|
|
\f[]
|
|
.fi
|
|
.SS Tags
|
|
.PP
|
|
Tags are a way to add extra labels or labelled data to postings and
|
|
transactions, which you can then search or pivot on.
|
|
.PP
|
|
A simple tag is a word (which may contain hyphens) followed by a full
|
|
colon, written inside a transaction or posting comment line:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2017/1/16\ bought\ groceries\ \ \ \ ;\ sometag:
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Tags can have a value, which is the text after the colon, up to the next
|
|
comma or end of line, with leading/trailing whitespace removed:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\ \ \ \ expenses:food\ \ \ \ $10\ \ \ ;\ a\-posting\-tag:\ the\ tag\ value
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note this means hledger's tag values can not contain commas or newlines.
|
|
Ending at commas means you can write multiple short tags on one line,
|
|
comma separated:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\ \ \ \ assets:checking\ \ \ \ \ \ \ ;\ a\ comment\ containing\ tag1:,\ tag2:\ some\ value\ ...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Here,
|
|
.IP \[bu] 2
|
|
\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a
|
|
tag
|
|
.IP \[bu] 2
|
|
\[lq]\f[C]tag1\f[]\[rq] is a tag with no value
|
|
.IP \[bu] 2
|
|
\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is
|
|
\[lq]\f[C]some\ value\ ...\f[]\[rq]
|
|
.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 (\f[C]A\f[],
|
|
\f[C]TAG2\f[], \f[C]third\-tag\f[]) and the posting has four (those plus
|
|
\f[C]posting\-tag\f[]):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
1/1\ a\ transaction\ \ ;\ A:,\ TAG2:
|
|
\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ <\-\ with\ a\ value
|
|
\ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag:
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Tags are like Ledger's metadata feature, except hledger'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'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 Cookbook: rewrite account names.
|
|
.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'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:
|
|
.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.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
alias\ /^(.+):bank:([^:]+)(.*)/\ =\ \\1:\\2\ \\3
|
|
#\ rewrites\ "assets:bank:wells\ fargo:checking"\ to\ \ "assets:wells\ fargo\ checking"
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Also note that REPLACEMENT continues to the end of line (or on command
|
|
line, to end of option argument), so it can contain trailing whitespace.
|
|
.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 predeclares account names.
|
|
The simplest form is \f[C]account\ ACCTNAME\f[], eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets:bank:checking
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Currently this mainly helps with account name autocompletion in eg
|
|
hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
In future it will also help detect misspelled accounts.
|
|
.PP
|
|
Account names can be followed by a numeric account code:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
|
|
account\ assets:bank:checking\ \ \ \ 1110
|
|
account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
|
|
account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
|
|
account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This affects account display order in reports: accounts with codes are
|
|
listed before accounts without codes, in increasing code order.
|
|
(Otherwise, accounts are listed alphabetically.) Account codes should be
|
|
all numeric digits, unique, and separated from the account name by at
|
|
least two spaces (since account names may contain single spaces).
|
|
By convention, often the first digit indicates the type of account, as
|
|
in this numbering scheme and the example above.
|
|
In future, we might use this to recognize account types.
|
|
.PP
|
|
An account directive can also have indented subdirectives following it,
|
|
which are currently ignored.
|
|
Here is the full syntax:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ account\ ACCTNAME\ \ [OPTIONALCODE]
|
|
;\ \ \ [OPTIONALSUBDIRECTIVES]
|
|
|
|
account\ assets:bank:checking\ \ \ 1110
|
|
\ \ a\ comment
|
|
\ \ some\-tag:12345
|
|
\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 \[lq]format\[rq] 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'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'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 Periodic transactions
|
|
.PP
|
|
Periodic transactions are a kind of rule with a dual purpose: they can
|
|
specify recurring future transactions (with \f[C]\-\-forecast\f[]), or
|
|
budget goals (with \f[C]\-\-budget\f[]).
|
|
They look a bit like a transaction, except the first line is a tilde
|
|
(\f[C]~\f[]) followed by a period expression:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
~\ weekly
|
|
\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck
|
|
\ \ income:acme\ inc
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
With \f[C]\-\-forecast\f[], each periodic transaction rule generates
|
|
recurring \[lq]forecast\[rq] transactions at the specified interval,
|
|
beginning the day after the latest recorded journal transaction (or
|
|
today, if there are no transactions) and ending 6 months from today (or
|
|
at the report end date, if specified).
|
|
.PP
|
|
With \f[C]balance\ \-\-budget\f[], each periodic transaction declares
|
|
recurring budget goals for the specified accounts.
|
|
Eg the example above declares the goal of receiving $400 from
|
|
\f[C]income:acme\ inc\f[] (and also, depositing $400 into
|
|
\f[C]assets:bank:checking\f[]) every week.
|
|
.PP
|
|
For more details, see: balance: Budgeting and Budgeting and Forecasting.
|
|
.SH Automated postings
|
|
.PP
|
|
Automated postings are postings added automatically by rule to certain
|
|
transactions (with \f[C]\-\-auto\f[]).
|
|
An automated posting rule looks like a transaction where the first line
|
|
is an equal sign (\f[C]=\f[]) followed by a query:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
=\ expenses:gifts
|
|
\ \ \ \ budget:gifts\ \ *\-1
|
|
\ \ \ \ assets:budget\ \ *1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The posting amounts can be of the form \f[C]*N\f[], which means \[lq]the
|
|
amount of the matched transaction's first posting, multiplied by N\[rq].
|
|
They can also be ordinary fixed amounts.
|
|
Fixed amounts with no commodity symbol will be given the same commodity
|
|
as the matched transaction's first posting.
|
|
.PP
|
|
This example adds a corresponding (unbalanced) budget posting to every
|
|
transaction involving the \f[C]expenses:gifts\f[] account:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
=\ expenses:gifts
|
|
\ \ \ \ (budget:gifts)\ \ *\-1
|
|
|
|
2017\-12\-14
|
|
\ \ expenses:gifts\ \ $20
|
|
\ \ assets
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print\ \-\-auto
|
|
2017/12/14
|
|
\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
|
|
\ \ \ \ assets
|
|
\ \ \ \ (budget:gifts)\ \ \ \ \ \ \ \ \ \ \ \ $\-20
|
|
\f[]
|
|
.fi
|
|
.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(12.2n) lw(57.8n).
|
|
T{
|
|
Editor
|
|
T}@T{
|
|
T}
|
|
_
|
|
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/Editing\-Ledger\-files\-with\-Sublime\-Text\-or\-RubyMine
|
|
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}
|
|
T{
|
|
Visual Studio Code
|
|
T}@T{
|
|
https://marketplace.visualstudio.com/items?itemName=mark\-hansen.hledger\-vscode
|
|
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
|