1816 lines
52 KiB
Groff
1816 lines
52 KiB
Groff
.\"t
|
|
|
|
.TH "hledger_journal" "5" "January 2019" "hledger 1.12.99" "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/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\[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 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 "unmarked" state
|
|
is called "uncleared".
|
|
As of hledger 1.3 we have renamed it to unmarked for clarity.
|
|
.PP
|
|
To replicate Ledger and old hledger\[aq]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 "uncleared", "pending", and "cleared" actually mean is up to you.
|
|
Here\[aq]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\[aq]s description is the rest of the line following the
|
|
date and status mark (or until a comment begins).
|
|
Sometimes called the "narration" 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[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]EUR\ 1E3\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]1000E\-6s\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
|
|
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
|
|
.IP \[bu] 2
|
|
scientific E\-notation is allowed.
|
|
Be careful not to use a digit group separator character in scientific
|
|
notation, as it\[aq]s not supported and it might get mistaken for a
|
|
decimal point.
|
|
(Declaring the digit group separator character explicitly with a
|
|
commodity directive will prevent this.)
|
|
.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 \f[C]D\f[] 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.
|
|
.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\[aq]s
|
|
balance on the same day, you\[aq]ll have to put the assertion in the
|
|
right file.
|
|
.SS Assertions and multiple \-f options
|
|
.PP
|
|
Balance assertions don\[aq]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\[aq]s balance within the
|
|
(possibly multi\-commodity) account balance.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
This is how assertions work in Ledger also.
|
|
We could call this a "partial" balance assertion.
|
|
.PP
|
|
To assert the balance of more than one commodity in an account, you can
|
|
write multiple postings, each asserting one commodity\[aq]s balance.
|
|
.PP
|
|
You can make a stronger kind of balance assertion, by writing a double
|
|
equals sign (\f[C]==EXPECTEDBALANCE\f[]).
|
|
This "complete" balance assertion asserts the absence of other
|
|
commodities (or, that their balance is 0, which to hledger is
|
|
equivalent.)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2013/1/1
|
|
\ \ a\ \ \ $1
|
|
\ \ a\ \ \ \ 1€
|
|
\ \ b\ \ $\-1
|
|
\ \ c\ \ \ \-1€
|
|
|
|
2013/1/2\ \ ;\ These\ assertions\ succeed
|
|
\ \ a\ \ \ \ 0\ \ =\ \ $1
|
|
\ \ a\ \ \ \ 0\ \ =\ \ \ 1€
|
|
\ \ b\ \ \ \ 0\ ==\ $\-1
|
|
\ \ c\ \ \ \ 0\ ==\ \ \-1€
|
|
|
|
2013/1/3\ \ ;\ This\ assertion\ fails\ as\ \[aq]a\[aq]\ also\ contains\ 1€
|
|
\ \ a\ \ \ \ 0\ ==\ \ $1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
It\[aq]s not yet possible to make a complete assertion about a balance
|
|
that has multiple commodities.
|
|
One workaround is to isolate each commodity into its own subaccount:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2013/1/1
|
|
\ \ a:usd\ \ \ $1
|
|
\ \ a:euro\ \ \ 1€
|
|
\ \ b
|
|
|
|
2013/1/2
|
|
\ \ a\ \ \ \ \ \ \ \ 0\ ==\ \ 0
|
|
\ \ a:usd\ \ \ \ 0\ ==\ $1
|
|
\ \ a:euro\ \ \ 0\ ==\ \ 1€
|
|
\f[]
|
|
.fi
|
|
.SS Assertions and prices
|
|
.PP
|
|
Balance assertions ignore transaction prices, and should normally be
|
|
written without one:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2019/1/1
|
|
\ \ (a)\ \ \ \ \ $1\ \@\ €1\ =\ $1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
We do allow prices to be written there, however, and print shows them,
|
|
even though they don\[aq]t affect whether the assertion passes or fails.
|
|
This is for backward compatibility (hledger\[aq]s close command used to
|
|
generate balance assertions with prices), and because balance
|
|
\f[I]assignments\f[] do use them (see below).
|
|
.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 Assertions and precision
|
|
.PP
|
|
Balance assertions compare the exactly calculated amounts, which are not
|
|
always what is shown by reports.
|
|
Eg a commodity directive may limit the display precision, but this will
|
|
not affect balance assertions.
|
|
Balance assertion failure messages show exact amounts.
|
|
.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 Balance assignments and prices
|
|
.PP
|
|
A transaction price in a balance assignment will cause the calculated
|
|
amount to have that price attached:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2019/1/1
|
|
\ \ (a)\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $1\ \@\ €2
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print\ \-\-explicit
|
|
2019/01/01
|
|
\ \ \ \ (a)\ \ \ \ \ \ \ \ \ $1\ \@\ €2\ =\ $1\ \@\ €2
|
|
\f[]
|
|
.fi
|
|
.SS Transaction prices
|
|
.PP
|
|
Within a transaction, you can note an amount\[aq]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.
|
|
Note transaction prices are fixed at the time of the transaction, and do
|
|
not change over time.
|
|
See also market prices, which represent prevailing exchange rates on a
|
|
certain date.
|
|
.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
|
|
(Ledger users: Ledger uses a different syntax for fixed prices,
|
|
\f[C]{=UNITPRICE}\f[], which hledger currently ignores).
|
|
.PP
|
|
Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their
|
|
transaction price\[aq]s commodity, if any.
|
|
(mnemonic: "B" is from "cost Basis", as in Ledger).
|
|
Eg here is how \-B affects the balance report for the example above:
|
|
.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\[aq]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 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
|
|
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
|
|
.PP
|
|
You can also comment larger regions of a file using \f[C]comment\f[] and
|
|
\f[C]end\ comment\f[] directives.
|
|
.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\[aq]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
|
|
"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag
|
|
.IP \[bu] 2
|
|
"\f[C]tag1\f[]" is a tag with no value
|
|
.IP \[bu] 2
|
|
"\f[C]tag2\f[]" is another tag, whose value is
|
|
"\f[C]some\ value\ ...\f[]"
|
|
.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\[aq]s metadata feature, except hledger\[aq]s tag
|
|
values are simple strings.
|
|
.SS Directives
|
|
.PP
|
|
A directive is a line in the journal beginning with a special keyword,
|
|
that influences how the journal is processed.
|
|
hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but
|
|
there are many differences (and also some differences between hledger
|
|
versions).
|
|
.PP
|
|
Directives\[aq] behaviour and interactions can get a little bit complex,
|
|
so here is a table summarising the directives and their effects, with
|
|
links to more detailed docs.
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n).
|
|
T{
|
|
directive
|
|
T}@T{
|
|
end directive
|
|
T}@T{
|
|
subdirectives
|
|
T}@T{
|
|
purpose
|
|
T}@T{
|
|
can affect (as of 2018/06)
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]account\f[]
|
|
T}@T{
|
|
T}@T{
|
|
any text
|
|
T}@T{
|
|
document account names, declare account types & display order
|
|
T}@T{
|
|
all entries in all files, before or after
|
|
T}
|
|
T{
|
|
\f[C]alias\f[]
|
|
T}@T{
|
|
\f[C]end\ aliases\f[]
|
|
T}@T{
|
|
T}@T{
|
|
rewrite account names
|
|
T}@T{
|
|
following inline/included entries until end of current file or end
|
|
directive
|
|
T}
|
|
T{
|
|
\f[C]apply\ account\f[]
|
|
T}@T{
|
|
\f[C]end\ apply\ account\f[]
|
|
T}@T{
|
|
T}@T{
|
|
prepend a common parent to account names
|
|
T}@T{
|
|
following inline/included entries until end of current file or end
|
|
directive
|
|
T}
|
|
T{
|
|
\f[C]comment\f[]
|
|
T}@T{
|
|
\f[C]end\ comment\f[]
|
|
T}@T{
|
|
T}@T{
|
|
ignore part of journal
|
|
T}@T{
|
|
following inline/included entries until end of current file or end
|
|
directive
|
|
T}
|
|
T{
|
|
\f[C]commodity\f[]
|
|
T}@T{
|
|
T}@T{
|
|
\f[C]format\f[]
|
|
T}@T{
|
|
declare a commodity and its number notation & display style
|
|
T}@T{
|
|
number notation: following entries in that commodity in all files;
|
|
display style: amounts of that commodity in reports
|
|
T}
|
|
T{
|
|
\f[C]D\f[]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
declare a commodity, number notation & display style for commodityless
|
|
amounts
|
|
T}@T{
|
|
commodity: all commodityless entries in all files; number notation:
|
|
following commodityless entries and entries in that commodity in all
|
|
files; display style: amounts of that commodity in reports
|
|
T}
|
|
T{
|
|
\f[C]include\f[]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
include entries/directives from another file
|
|
T}@T{
|
|
what the included directives affect
|
|
T}
|
|
T{
|
|
\f[C]P\f[]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
declare a market price for a commodity
|
|
T}@T{
|
|
amounts of that commodity in reports, when \-V is used
|
|
T}
|
|
T{
|
|
\f[C]Y\f[]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
declare a year for yearless dates
|
|
T}@T{
|
|
following inline/included entries until end of current file
|
|
T}
|
|
.TE
|
|
.PP
|
|
And some definitions:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(8.9n) lw(61.1n).
|
|
T{
|
|
subdirective
|
|
T}@T{
|
|
optional indented directive line immediately following a parent
|
|
directive
|
|
T}
|
|
T{
|
|
number notation
|
|
T}@T{
|
|
how to interpret numbers when parsing journal entries (the identity of
|
|
the decimal separator character).
|
|
(Currently each commodity can have its own notation, even in the same
|
|
file.)
|
|
T}
|
|
T{
|
|
display style
|
|
T}@T{
|
|
how to display amounts of a commodity in reports (symbol side and
|
|
spacing, digit groups, decimal separator, decimal places)
|
|
T}
|
|
T{
|
|
directive scope
|
|
T}@T{
|
|
which entries and (when there are multiple files) which files are
|
|
affected by a directive
|
|
T}
|
|
.TE
|
|
.PP
|
|
As you can see, directives vary in which journal entries and files they
|
|
affect, and whether they are focussed on input (parsing) or output
|
|
(reports).
|
|
Some directives have multiple effects.
|
|
.PP
|
|
If you have a journal made up of multiple files, or pass multiple \-f
|
|
options on the command line, note that directives which affect input
|
|
typically last only until the end of their defining file.
|
|
This provides more simplicity and predictability, eg reports are not
|
|
changed by writing file options in a different order.
|
|
It can be surprising at times though.
|
|
.SS Comment blocks
|
|
.PP
|
|
A line containing just \f[C]comment\f[] starts a commented region of the
|
|
file, and a line containing just \f[C]end\ comment\f[] (or the end of
|
|
the current file) ends it.
|
|
See also comments.
|
|
.SS Including other files
|
|
.PP
|
|
You can pull in the content of additional 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.
|
|
The include file path may contain common glob patterns (e.g.
|
|
\f[C]*\f[]).
|
|
.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.
|
|
.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 Declaring commodities
|
|
.PP
|
|
The \f[C]commodity\f[] directive declares commodities which may be used
|
|
in the journal (though currently we do not enforce this).
|
|
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
|
|
.PP
|
|
Commodity directives have a second purpose: they define the standard
|
|
display format for amounts in the commodity.
|
|
Normally the display format is inferred from journal entries, but this
|
|
can be unpredictable; declaring it with a commodity directive overrides
|
|
this and removes ambiguity.
|
|
Towards this end, amounts in commodity directives must always be written
|
|
with a decimal point (a period or comma, followed by 0 or more decimal
|
|
digits).
|
|
.SS Default commodity
|
|
.PP
|
|
The \f[C]D\f[] 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 \f[C]D\f[] 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
|
|
.PP
|
|
As with the \f[C]commodity\f[] directive, the amount must always be
|
|
written with a decimal point.
|
|
.SS Market prices
|
|
.PP
|
|
The \f[C]P\f[] directive declares a market price, which is an exchange
|
|
rate between two commodities on a certain date.
|
|
(In Ledger, they are called "historical prices".) These are often
|
|
obtained from a stock exchange, cryptocurrency exchange, or the foreign
|
|
exchange market.
|
|
.PP
|
|
Here is the format:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
P\ DATE\ COMMODITYA\ COMMODITYBAMOUNT
|
|
\f[]
|
|
.fi
|
|
.IP \[bu] 2
|
|
DATE is a simple date
|
|
.IP \[bu] 2
|
|
COMMODITYA is the symbol of the commodity being priced
|
|
.IP \[bu] 2
|
|
COMMODITYBAMOUNT is an amount (symbol and quantity) in a second
|
|
commodity, giving the price in commodity B of one unit of commodity A.
|
|
.PP
|
|
These two market price 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
|
|
.PP
|
|
The \f[C]\-V/\-\-value\f[] flag can be used to convert reported amounts
|
|
to another commodity using these prices.
|
|
.SS Declaring accounts
|
|
.PP
|
|
\f[C]account\f[] directives can be used to pre\-declare accounts.
|
|
Though not required, they can provide several benefits:
|
|
.IP \[bu] 2
|
|
They can document your intended chart of accounts, providing a
|
|
reference.
|
|
.IP \[bu] 2
|
|
They can store extra information about accounts (account numbers, notes,
|
|
etc.)
|
|
.IP \[bu] 2
|
|
They can help hledger know your accounts\[aq] types (asset, liability,
|
|
equity, revenue, expense), useful for reports like balancesheet and
|
|
incomestatement.
|
|
.IP \[bu] 2
|
|
They control account display order in reports, allowing non\-alphabetic
|
|
sorting (eg Revenues to appear above Expenses).
|
|
.IP \[bu] 2
|
|
They help with account name completion in the add command,
|
|
hledger\-iadd, hledger\-web, ledger\-mode etc.
|
|
.PP
|
|
The simplest form is just the word \f[C]account\f[] followed by a
|
|
hledger\-style account name, eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets:bank:checking
|
|
\f[]
|
|
.fi
|
|
.SS Account comments
|
|
.PP
|
|
Comments, beginning with a semicolon, optionally including tags, can be
|
|
written after the account name, and/or on following lines.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets:bank:checking\ \ ;\ a\ comment
|
|
\ \ ;\ another\ comment
|
|
\ \ ;\ acctno:12345,\ a\ tag
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Tip: comments on the same line require hledger 1.12+.
|
|
If you need your journal to be compatible with older hledger versions,
|
|
write comments on the next line instead.
|
|
.SS Account subdirectives
|
|
.PP
|
|
We also allow (and ignore) Ledger\-style indented subdirectives, just
|
|
for compatibility.:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets:bank:checking
|
|
\ \ format\ blah\ blah\ \ ;\ <\-\ subdirective,\ ignored
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Here is the full syntax of account directives:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ ACCTNAME\ \ [ACCTTYPE]\ [;COMMENT]
|
|
\ \ [;COMMENTS]
|
|
\ \ [LEDGER\-STYLE\ SUBDIRECTIVES,\ IGNORED]
|
|
\f[]
|
|
.fi
|
|
.SS Account types
|
|
.PP
|
|
hledger recognises five types (or classes) of account: Asset, Liability,
|
|
Equity, Revenue, Expense.
|
|
This is used by a few accounting\-aware reports such as balancesheet,
|
|
incomestatement and cashflow.
|
|
.SS Auto\-detected account types
|
|
.PP
|
|
If you name your top\-level accounts with some variation of
|
|
\f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[],
|
|
\f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are
|
|
detected automatically.
|
|
.SS Account types declared with tags
|
|
.PP
|
|
More generally, you can declare an account\[aq]s type with an account
|
|
directive, by writing a \f[C]type:\f[] tag in a comment, followed by one
|
|
of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[],
|
|
\f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[]
|
|
(case insensitive):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets\ \ \ \ \ \ \ ;\ type:Asset
|
|
account\ liabilities\ \ ;\ type:Liability
|
|
account\ equity\ \ \ \ \ \ \ ;\ type:Equity
|
|
account\ revenues\ \ \ \ \ ;\ type:Revenue
|
|
account\ expenses\ \ \ \ \ ;\ type:Expenses
|
|
\f[]
|
|
.fi
|
|
.SS Account types declared with account type codes
|
|
.PP
|
|
Or, you can write one of those letters separated from the account name
|
|
by two or more spaces, but this should probably be considered deprecated
|
|
as of hledger 1.13:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets\ \ \ \ \ \ \ A
|
|
account\ liabilities\ \ L
|
|
account\ equity\ \ \ \ \ \ \ E
|
|
account\ revenues\ \ \ \ \ R
|
|
account\ expenses\ \ \ \ \ X
|
|
\f[]
|
|
.fi
|
|
.SS Overriding auto\-detected types
|
|
.PP
|
|
If you ever override the types of those auto\-detected english account
|
|
names mentioned above, you might need to help the reports a bit.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ make\ "liabilities"\ not\ have\ the\ liability\ type\ \-\ who\ knows\ why
|
|
account\ liabilities\ \ \ ;\ type:E
|
|
|
|
;\ we\ need\ to\ ensure\ some\ other\ account\ has\ the\ liability\ type,\
|
|
;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\
|
|
account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ ;\ type:L
|
|
\f[]
|
|
.fi
|
|
.SS Account display order
|
|
.PP
|
|
Account directives also set the order in which accounts are displayed,
|
|
eg in reports, the hledger\-ui accounts screen, and the hledger\-web
|
|
sidebar.
|
|
By default accounts are listed in alphabetical order.
|
|
But if you have these account directives in the journal:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ assets
|
|
account\ liabilities
|
|
account\ equity
|
|
account\ revenues
|
|
account\ expenses
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
you\[aq]ll see those accounts displayed in declaration order, not
|
|
alphabetically:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ accounts\ \-1
|
|
assets
|
|
liabilities
|
|
equity
|
|
revenues
|
|
expenses
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Undeclared accounts, if any, are displayed last, in alphabetical order.
|
|
.PP
|
|
Note that sorting is done at each level of the account tree (within each
|
|
group of sibling accounts under the same parent).
|
|
And currently, this directive:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
account\ other:zoo
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
would influence the position of \f[C]zoo\f[] among \f[C]other\f[]\[aq]s
|
|
subaccounts, but not the position of \f[C]other\f[] among the top\-level
|
|
accounts.
|
|
This means: \- you will sometimes declare parent accounts (eg
|
|
\f[C]account\ other\f[] above) that you don\[aq]t intend to post to,
|
|
just to customize their display order \- sibling accounts stay together
|
|
(you couldn\[aq]t display \f[C]x:y\f[] in between \f[C]a:b\f[] and
|
|
\f[C]a:c\f[]).
|
|
.SS Rewriting accounts
|
|
.PP
|
|
You can define account alias rules which rewrite your account names, or
|
|
parts of them, before generating reports.
|
|
This 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
|
|
Account aliases also rewrite account names in account directives.
|
|
They do not affect account names being entered via hledger add or
|
|
hledger\-web.
|
|
.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\[aq]s useful for trying out aliases interactively.
|
|
.PP
|
|
OLD and NEW are case sensitive 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 \f[C]end\ aliases\f[]
|
|
.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 Default parent account
|
|
.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.
|
|
.PP
|
|
A default parent account also affects account directives.
|
|
It does not affect account names being entered via hledger add or
|
|
hledger\-web.
|
|
If account aliases are present, they are applied after the default
|
|
parent account.
|
|
.SS Periodic transactions
|
|
.PP
|
|
Periodic transaction rules describe transactions that recur.
|
|
They allow you to generate future transactions for forecasting, without
|
|
having to write them out explicitly in the journal (with
|
|
\f[C]\-\-forecast\f[]).
|
|
Secondly, they also can be used to define budget goals (with
|
|
\f[C]\-\-budget\f[]).
|
|
.PP
|
|
A periodic transaction rule looks like a normal journal entry, with the
|
|
date replaced by a tilde (\f[C]~\f[]) followed by a period expression
|
|
(mnemonic: \f[C]~\f[] looks like a recurring sine wave.):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
~\ monthly
|
|
\ \ \ \ expenses:rent\ \ \ \ \ \ \ \ \ \ $2000
|
|
\ \ \ \ assets:bank:checking
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
There is an additional constraint on the period expression: the start
|
|
date must fall on a natural boundary of the interval.
|
|
Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
|
|
\f[C]monthly\ from\ 2018/1/15\f[] is not.
|
|
.PP
|
|
Partial or relative dates (M/D, D, tomorrow, last week) in the period
|
|
expression can work (useful or not).
|
|
They will be relative to today\[aq]s date, unless a Y default year
|
|
directive is in effect, in which case they will be relative to Y/1/1.
|
|
.SS Two spaces after the period expression
|
|
.PP
|
|
If the period expression is followed by a transaction description, these
|
|
must be separated by \f[B]two or more spaces\f[].
|
|
This helps hledger know where the period expression ends, so that
|
|
descriptions can not accidentally alter their meaning, as in this
|
|
example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ 2\ or\ more\ spaces\ needed\ here,\ so\ the\ period\ is\ not\ understood\ as\ "every\ 2\ months\ in\ 2020"
|
|
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
|
|
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
|
|
~\ every\ 2\ months\ \ in\ 2020,\ we\ will\ review
|
|
\ \ \ \ assets:bank:checking\ \ \ $1500
|
|
\ \ \ \ income:acme\ inc
|
|
\f[]
|
|
.fi
|
|
.SS Forecasting with periodic transactions
|
|
.PP
|
|
With the \f[C]\-\-forecast\f[] flag, each periodic transaction rule
|
|
generates future transactions recurring at the specified interval.
|
|
These are not saved in the journal, but appear in all reports.
|
|
They will look like normal transactions, but with an extra tag named
|
|
\f[C]recur\f[], whose value is the generating period expression.
|
|
.PP
|
|
Forecast transactions start on the first occurrence, and end on the last
|
|
occurrence, of their interval within the forecast period.
|
|
The forecast period:
|
|
.IP \[bu] 2
|
|
begins on the later of
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
the report start date if specified with \-b/\-p/date:
|
|
.IP \[bu] 2
|
|
the day after the latest normal (non\-periodic) transaction in the
|
|
journal, or today if there are no normal transactions.
|
|
.RE
|
|
.IP \[bu] 2
|
|
ends on the report end date if specified with \-e/\-p/date:, or 180 days
|
|
from today.
|
|
.PP
|
|
where "today" means the current date at report time.
|
|
The "later of" rule ensures that forecast transactions do not overlap
|
|
normal transactions in time; they will begin only after normal
|
|
transactions end.
|
|
.PP
|
|
Forecasting can be useful for estimating balances into the future, and
|
|
experimenting with different scenarios.
|
|
Note the start date logic means that forecasted transactions are
|
|
automatically replaced by normal transactions as you add those.
|
|
.PP
|
|
Forecasting can also help with data entry: describe most of your
|
|
transactions with periodic rules, and every so often copy the output of
|
|
\f[C]print\ \-\-forecast\f[] to the journal.
|
|
.PP
|
|
You can generate one\-time transactions too: just write a period
|
|
expression specifying a date with no report interval.
|
|
(You could also write a normal transaction with a future date, but
|
|
remember this disables forecast transactions on previous dates.)
|
|
.SS Budgeting with periodic transactions
|
|
.PP
|
|
With the \f[C]\-\-budget\f[] flag, currently supported by the balance
|
|
command, each periodic transaction rule declares recurring budget goals
|
|
for the specified accounts.
|
|
Eg the first example above declares a goal of spending $2000 on rent
|
|
(and also, a goal of depositing $2000 into checking) every month.
|
|
Goals and actual performance can then be compared in budget reports.
|
|
.PP
|
|
For more details, see: balance: Budget report and Cookbook: Budgeting
|
|
and Forecasting.
|
|
.PP
|
|
.SS Transaction Modifiers
|
|
.PP
|
|
Transaction modifier rules describe changes that should be applied
|
|
automatically to certain transactions.
|
|
Currently, this means adding extra postings (also known as "automated
|
|
postings").
|
|
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
|
|
.PP
|
|
A transaction modifier rule looks quite like a normal transaction,
|
|
except the first line is an equals sign followed by a query that matches
|
|
certain postings (mnemonic: \f[C]=\f[] suggests matching).
|
|
And each "posting" is actually a posting\-generating rule:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
=\ QUERY
|
|
\ \ \ \ ACCT\ \ AMT
|
|
\ \ \ \ ACCT\ \ [AMT]
|
|
\ \ \ \ ...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The posting rules look just like normal postings, except the amount can
|
|
be:
|
|
.IP \[bu] 2
|
|
a normal amount with a commodity symbol, eg \f[C]$2\f[].
|
|
This will be used as\-is.
|
|
.IP \[bu] 2
|
|
a number, eg \f[C]2\f[].
|
|
The commodity symbol (if any) from the matched posting will be added to
|
|
this.
|
|
.IP \[bu] 2
|
|
a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N).
|
|
The matched posting\[aq]s amount (and total price, if any) will be
|
|
multiplied by N.
|
|
.IP \[bu] 2
|
|
a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N,
|
|
and symbol S).
|
|
The matched posting\[aq]s amount will be multiplied by N, and its
|
|
commodity symbol will be replaced with S.
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;\ every\ time\ I\ buy\ food,\ schedule\ a\ dollar\ donation
|
|
=\ expenses:food
|
|
\ \ \ \ (liabilities:charity)\ \ \ $\-1
|
|
|
|
;\ when\ I\ buy\ a\ gift,\ also\ deduct\ that\ amount\ from\ a\ budget\ envelope\ subaccount
|
|
=\ expenses:gifts
|
|
\ \ \ \ assets:checking:gifts\ \ *\-1
|
|
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ *1
|
|
|
|
2017/12/1
|
|
\ \ expenses:food\ \ \ \ $10
|
|
\ \ assets:checking
|
|
|
|
2017/12/14
|
|
\ \ expenses:gifts\ \ \ $20
|
|
\ \ assets:checking
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print\ \-\-auto
|
|
2017/12/01
|
|
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
|
|
\ \ \ \ assets:checking
|
|
\ \ \ \ (liabilities:charity)\ \ \ \ \ \ $\-1
|
|
|
|
2017/12/14
|
|
\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
|
|
\ \ \ \ assets:checking
|
|
\ \ \ \ assets:checking:gifts\ \ \ \ \ \-$20
|
|
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Postings added by transaction modifiers participate in transaction
|
|
balancing, missing amount inference and balance assertions, like regular
|
|
postings.
|
|
.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/vim\-ledger
|
|
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
|