slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-01-29 08:27:29 -08:00
parent 150a74c5a0
commit 06a54f70b0
3 changed files with 1449 additions and 1503 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

661
hledger-lib/hledger_journal.5
View File

@ -30,120 +30,91 @@ the add or web commands to create and update it.
Many users, though, also edit the journal file directly with a text Many users, though, also edit the journal file directly with a text
editor, perhaps assisted by the helper modes for emacs or vim. editor, perhaps assisted by the helper modes for emacs or vim.
.PP .PP
Here\[aq]s an example: Helper modes exist for popular text editors, which make working with
journal files easier.
They add colour, formatting, tab completion, and helpful commands, and
are quite recommended if you edit your journal with a text editor.
They include ledger-mode or hledger-mode for Emacs, vim-ledger for Vim,
hledger-vscode for Visual Studio Code, and others.
See the Editor configuration at hledger.org for the latest information.
.SH FILE FORMAT
.PP
Here\[aq]s a description of each part of the file format (and
hledger\[aq]s data model).
These are mostly in the order you\[aq]ll use them, but in some cases
related concepts have been grouped together for easy reference, or
linked before they are introduced, so feel free to skip over anything
that looks unnecessary right now.
.SS Transactions
.PP
Transactions are the main unit of information in a journal file.
They represent events, typically a movement of some quantity of
commodities between two or more named accounts.
.PP
Each transaction is recorded as a journal entry, beginning with a simple
date in column 0.
This can be followed by any of the following optional fields, separated
by spaces:
.IP \[bu] 2
a status character (empty, \f[C]!\f[R], or \f[C]*\f[R])
.IP \[bu] 2
a code (any short number or text, enclosed in parentheses)
.IP \[bu] 2
a description (any remaining text until end of line or a semicolon)
.IP \[bu] 2
a comment (any remaining text following a semicolon until end of line,
and any following indented lines beginning with a semicolon)
.IP \[bu] 2
0 or more indented \f[I]posting\f[R] lines, describing what was
transferred and the accounts involved.
.PP
Here\[aq]s a simple journal file containing one transaction:
.IP .IP
.nf .nf
\f[C] \f[C]
; A sample journal file. This is a comment. 2008/01/01 income
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 assets:bank:checking $1
liabilities:debts $-1 income:salary $-1
2008/12/31 * pay off ; <- an optional * or ! after the date means \[dq]cleared\[dq] (or anything you want)
liabilities:debts $1
assets:bank:checking
\f[R] \f[R]
.fi .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[R], or \f[C]*\f[R])
.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[R], or \f[C]*\f[R]),
followed by a space
.IP \[bu] 2
(required) an account name (any text, optionally containing \f[B]single
spaces\f[R], until end of line or a double space)
.IP \[bu] 2
(optional) \f[B]two or more spaces\f[R] 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 Dates
.SS Simple dates .SS Simple dates
.PP .PP
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) Dates in the journal file use \f[I]simple dates\f[R] format:
Leading zeros are optional. \f[C]YYYY-MM-DD\f[R] or \f[C]YYYY/MM/DD\f[R] or \f[C]YYYY.MM.DD\f[R],
with leading zeros optional.
The year may be omitted, in which case it will be inferred from the 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 context: the current transaction, the default year set with a default
year directive, or the current date when the command is run. year directive, or the current date when the command is run.
Some examples: \f[C]2010/01/31\f[R], \f[C]1/31\f[R], Some examples: \f[C]2010-01-31\f[R], \f[C]2010/01/31\f[R],
\f[C]2010-01-31\f[R], \f[C]2010.1.31\f[R]. \f[C]2010.1.31\f[R], \f[C]1/31\f[R].
.PP
(The UI also accepts simple dates, as well as the more flexible smart
dates documented in the hledger manual.)
.SS Secondary dates .SS Secondary dates
.PP .PP
Real-life transactions sometimes involve more than one date - eg the Real-life transactions sometimes involve more than one date - eg the
date you write a cheque, and the date it clears in your bank. date you write a cheque, and the date it clears in your bank.
When you want to model this, eg for more accurate balances, you can When you want to model this, eg for more accurate balances, you can
specify individual posting dates, which I recommend. specify individual posting dates.
Or, you can use the secondary dates (aka auxiliary/effective dates)
feature, supported for compatibility with Ledger.
.PP .PP
A secondary date can be written after the primary date, separated by an Or, you can use the older \f[I]secondary date\f[R] feature.
equals sign. (Ledger calls it auxiliary date or effective date.) But I would
The primary date, on the left, is used by default; the secondary date, recommend avoiding this feature; posting dates are almost always clearer
on the right, is used when the \f[C]--date2\f[R] flag is specified and simpler.
(\f[C]--aux-date\f[R] or \f[C]--effective\f[R] also work). We support it mainly for compatibility.
.PP
A secondary date is written after the primary date, following an equals
sign.
The primary date\[aq]s year will be used if the year is omitted.
When running reports, the primary (left) date is used by default, but
with the \f[C]--date2\f[R] flag (or \f[C]--aux-date\f[R] or
\f[C]--effective\f[R]), the secondary (right) date will be used instead.
.PP .PP
The meaning of secondary dates is up to you, but it\[aq]s best to follow The meaning of secondary dates is up to you, but it\[aq]s best to follow
a consistent rule. a consistent rule.
Eg write the bank\[aq]s clearing date as primary, and when needed, the Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the
date the transaction was initiated as secondary. transaction was initiated, if different\[dq], as shown here:
.PP
Here\[aq]s an example.
Note that a secondary date will use the year of the primary date if
unspecified.
.IP .IP
.nf .nf
\f[C] \f[C]
@ -166,12 +137,6 @@ $ hledger register checking --date2
2010-02-19 movie ticket assets:checking $-10 $-10 2010-02-19 movie ticket assets:checking $-10 $-10
\f[R] \f[R]
.fi .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[R] 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 .SS Posting dates
.PP .PP
You can give individual postings a different date from their parent You can give individual postings a different date from their parent
@ -320,6 +285,178 @@ payee/payer name on the left (up to the first \f[C]|\f[R]) and an
additional note field on the right (after the first \f[C]|\f[R]). additional note field on the right (after the first \f[C]|\f[R]).
This may be worthwhile if you need to do more precise querying and This may be worthwhile if you need to do more precise querying and
pivoting by payee or by note. pivoting by payee or by note.
.SS Comments
.PP
Lines in the journal beginning with a semicolon (\f[C];\f[R]) or hash
(\f[C]#\f[R]) or star (\f[C]*\f[R]) 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[R]).
.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 \[dq]end comment\[dq] 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[R]
.fi
.PP
You can also comment larger regions of a file using \f[C]comment\f[R]
and \f[C]end comment\f[R] 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[R]
.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[R]
.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[R]
.fi
.PP
Here,
.IP \[bu] 2
\[dq]\f[C]a comment containing\f[R]\[dq] is just comment text, not a tag
.IP \[bu] 2
\[dq]\f[C]tag1\f[R]\[dq] is a tag with no value
.IP \[bu] 2
\[dq]\f[C]tag2\f[R]\[dq] is another tag, whose value is
\[dq]\f[C]some value ...\f[R]\[dq]
.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[R],
\f[C]TAG2\f[R], \f[C]third-tag\f[R]) and the posting has four (those
plus \f[C]posting-tag\f[R]):
.IP
.nf
\f[C]
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
\f[R]
.fi
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are simple strings.
.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[R], or \f[C]*\f[R]),
followed by a space
.IP \[bu] 2
(required) an account name (any text, optionally containing \f[B]single
spaces\f[R], until end of line or a double space)
.IP \[bu] 2
(optional) \f[B]two or more spaces\f[R] 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 Virtual Postings
.PP
A posting with a parenthesised account name is called a \f[I]virtual
posting\f[R] or \f[I]unbalanced posting\f[R], which means it is exempt
from the usual rule that a transaction\[aq]s postings must balance add
up to zero.
.PP
This is not part of double entry accounting, so you might choose to
avoid this feature.
Or you can use it sparingly for certain special cases where it can be
convenient.
Eg, you could set opening balances without using a balancing equity
account:
.IP
.nf
\f[C]
1/1 opening balances
(assets:checking) $1000
(assets:savings) $2000
\f[R]
.fi
.PP
A posting with a bracketed account name is called a \f[I]balanced
virtual posting\f[R].
The balanced virtual postings in a transaction must add up to zero
(separately from other postings).
Eg:
.IP
.nf
\f[C]
1/1 buy food with cash, update budget envelope subaccounts, & something else
assets:cash $-10 ; <- these balance
expenses:food $7 ; <-
expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance
\f[R]
.fi
.PP
Ordinary non-parenthesised, non-bracketed postings are called \f[I]real
postings\f[R].
You can exclude virtual postings from reports with the
\f[C]-R/--real\f[R] flag or \f[C]real:1\f[R] query.
.SS Account names .SS Account names
.PP .PP
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
@ -465,47 +602,99 @@ indirectly.
amount, or when an amountless posting is balanced using a price\[aq]s 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, use a commodity, or when -V is used.) If you find this causing problems, use a
commodity directive to set the display format. commodity directive to set the display format.
.SS Virtual Postings .SS Transaction prices
.PP .PP
When you parenthesise the account name in a posting, we call that a Within a transaction, you can note an amount\[aq]s price in another
\f[I]virtual posting\f[R], which means: commodity.
.IP \[bu] 2 This can be used to document the cost (in a purchase) or selling price
it is ignored when checking that the transaction is balanced (in a sale).
.IP \[bu] 2 For example, transaction prices are useful to record purchases of a
it is excluded from reports when the \f[C]--real/-R\f[R] flag is used, foreign currency.
or the \f[C]real:1\f[R] query. 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 .PP
You could use this, eg, to set an account\[aq]s opening balance without There are several ways to record a transaction price:
needing to use the \f[C]equity:opening balances\f[R] account: .IP "1." 3
Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount:
.RS 4
.IP .IP
.nf .nf
\f[C] \f[C]
1/1 special unbalanced posting to set initial balance 2009/1/1
(assets:checking) $1000 assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00
\f[R] \f[R]
.fi .fi
.PP .RE
When the account name is bracketed, we call it a \f[I]balanced virtual .IP "2." 3
posting\f[R]. Write the total price, as \f[C]\[at]\[at] TOTALPRICE\f[R] after the
This is like an ordinary virtual posting except the balanced virtual amount:
postings in a transaction must balance to 0, like the real postings (but .RS 4
separately from them).
Balanced virtual postings are also excluded by \f[C]--real/-R\f[R] or
\f[C]real:1\f[R].
.IP .IP
.nf .nf
\f[C] \f[C]
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere 2009/1/1
expenses:food $10 assets:euros \[Eu]100 \[at]\[at] $135 ; one hundred euros purchased at $135 for the lot
assets:cash $-10 assets:dollars
[assets:checking:available] $10 \f[R]
[assets:checking:budget:food] $-10 .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 \[Eu]100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
\f[R]
.fi
.RE
.PP
(Ledger users: Ledger uses a different syntax for fixed prices,
\f[C]{=UNITPRICE}\f[R], which hledger currently ignores).
.PP
Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
price\[aq]s commodity, if any.
(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], 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
\[Eu]100 assets:euros
$ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros\[aq] cost
\f[R] \f[R]
.fi .fi
.PP .PP
Virtual postings have some legitimate uses, but those are few. Note -B is sensitive to the order of postings when a transaction price
You can usually find an equivalent journal entry using real postings, is inferred: the inferred price will be in the commodity of the last
which is more correct and provides better error checking. 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 \[Eu]100 ; for 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal -N --flat -B
\[Eu]-100 assets:dollars # <- the dollars\[aq] selling price
\[Eu]100 assets:euros
\f[R]
.fi
.SS Balance Assertions .SS Balance Assertions
.PP .PP
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
@ -722,200 +911,6 @@ $ hledger print --explicit
(a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2 (a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2
\f[R] \f[R]
.fi .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]\[at] UNITPRICE\f[R] after the amount:
.RS 4
.IP
.nf
\f[C]
2009/1/1
assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00
\f[R]
.fi
.RE
.IP "2." 3
Write the total price, as \f[C]\[at]\[at] TOTALPRICE\f[R] after the
amount:
.RS 4
.IP
.nf
\f[C]
2009/1/1
assets:euros \[Eu]100 \[at]\[at] $135 ; one hundred euros purchased at $135 for the lot
assets:dollars
\f[R]
.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 \[Eu]100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
\f[R]
.fi
.RE
.PP
(Ledger users: Ledger uses a different syntax for fixed prices,
\f[C]{=UNITPRICE}\f[R], which hledger currently ignores).
.PP
Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
price\[aq]s commodity, if any.
(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], 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
\[Eu]100 assets:euros
$ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros\[aq] cost
\f[R]
.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 \[Eu]100 ; for 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal -N --flat -B
\[Eu]-100 assets:dollars # <- the dollars\[aq] selling price
\[Eu]100 assets:euros
\f[R]
.fi
.SS Comments
.PP
Lines in the journal beginning with a semicolon (\f[C];\f[R]) or hash
(\f[C]#\f[R]) or star (\f[C]*\f[R]) 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[R]).
.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 \[dq]end comment\[dq] 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[R]
.fi
.PP
You can also comment larger regions of a file using \f[C]comment\f[R]
and \f[C]end comment\f[R] 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[R]
.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[R]
.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[R]
.fi
.PP
Here,
.IP \[bu] 2
\[dq]\f[C]a comment containing\f[R]\[dq] is just comment text, not a tag
.IP \[bu] 2
\[dq]\f[C]tag1\f[R]\[dq] is a tag with no value
.IP \[bu] 2
\[dq]\f[C]tag2\f[R]\[dq] is another tag, whose value is
\[dq]\f[C]some value ...\f[R]\[dq]
.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[R],
\f[C]TAG2\f[R], \f[C]third-tag\f[R]) and the posting has four (those
plus \f[C]posting-tag\f[R]):
.IP
.nf
\f[C]
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
\f[R]
.fi
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are simple strings.
.SS Directives .SS Directives
.PP .PP
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
@ -1421,11 +1416,14 @@ account other:zoo
would influence the position of \f[C]zoo\f[R] among would influence the position of \f[C]zoo\f[R] among
\f[C]other\f[R]\[aq]s subaccounts, but not the position of \f[C]other\f[R]\[aq]s subaccounts, but not the position of
\f[C]other\f[R] among the top-level accounts. \f[C]other\f[R] among the top-level accounts.
This means: - you will sometimes declare parent accounts (eg This means:
\f[C]account other\f[R] above) that you don\[aq]t intend to post to, .IP \[bu] 2
just to customize their display order - sibling accounts stay together you will sometimes declare parent accounts (eg \f[C]account other\f[R]
(you couldn\[aq]t display \f[C]x:y\f[R] in between \f[C]a:b\f[R] and above) that you don\[aq]t intend to post to, just to customize their
\f[C]a:c\f[R]). display order
.IP \[bu] 2
sibling accounts stay together (you couldn\[aq]t display \f[C]x:y\f[R]
in between \f[C]a:b\f[R] and \f[C]a:c\f[R]).
.SS Rewriting accounts .SS Rewriting accounts
.PP .PP
You can define account alias rules which rewrite your account names, or You can define account alias rules which rewrite your account names, or
@ -1876,15 +1874,6 @@ rules will have these tags added:
.IP \[bu] 2 .IP \[bu] 2
\f[C]_modified:\f[R] - a hidden tag not appearing in the comment; this \f[C]_modified:\f[R] - a hidden tag not appearing in the comment; this
transaction was modified \[dq]just now\[dq]. transaction was modified \[dq]just now\[dq].
.SH EDITOR SUPPORT
.PP
Helper modes exist for popular text editors, which make working with
journal files easier.
They add colour, formatting, tab completion, and helpful commands, and
are quite recommended if you edit your journal with a text editor.
They include ledger-mode or hledger-mode for Emacs, vim-ledger for Vim,
hledger-vscode for Visual Studio Code, and others.
See the Editor configuration at hledger.org for the latest information.
.SH "REPORTING BUGS" .SH "REPORTING BUGS"

1247
hledger-lib/hledger_journal.info
View File

File diff suppressed because it is too large Load Diff

500
hledger-lib/hledger_journal.txt
View File

@ -26,108 +26,80 @@ DESCRIPTION
also edit the journal file directly with a text editor, perhaps as- also edit the journal file directly with a text editor, perhaps as-
sisted by the helper modes for emacs or vim. sisted by the helper modes for emacs or vim.
Here's an example: Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and
; A sample journal file. This is a comment. helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name others. See the Editor configuration at hledger.org for the latest in-
income:salary $-1 ; followed by at least two spaces and an amount formation.
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
FILE FORMAT FILE FORMAT
Here's a description of each part of the file format (and hledger's
data model). These are mostly in the order you'll use them, but in
some cases related concepts have been grouped together for easy refer-
ence, or linked before they are introduced, so feel free to skip over
anything that looks unnecessary right now.
Transactions Transactions
Transactions are movements of some quantity of commodities between Transactions are the main unit of information in a journal file. They
named accounts. Each transaction is represented by a journal entry be- represent events, typically a movement of some quantity of commodities
ginning with a simple date in column 0. This can be followed by any of between two or more named accounts.
the following, separated by spaces:
o (optional) a status character (empty, !, or *) Each transaction is recorded as a journal entry, beginning with a sim-
ple date in column 0. This can be followed by any of the following op-
tional fields, separated by spaces:
o (optional) a transaction code (any short number or text, enclosed in o a status character (empty, !, or *)
parentheses)
o (optional) a transaction description (any remaining text until end of o a code (any short number or text, enclosed in parentheses)
line or a semicolon)
o (optional) a transaction comment (any remaining text following a o a description (any remaining text until end of line or a semicolon)
semicolon until end of line)
Then comes zero or more (but usually at least 2) indented lines repre- o a comment (any remaining text following a semicolon until end of
senting... line, and any following indented lines beginning with a semicolon)
Postings o 0 or more indented posting lines, describing what was transferred and
A posting is an addition of some amount to, or removal of some amount the accounts involved.
from, an account. Each posting line begins with at least one space or
tab (2 or 4 spaces is common), followed by:
o (optional) a status character (empty, !, or *), followed by a space Here's a simple journal file containing one transaction:
o (required) an account name (any text, optionally containing single 2008/01/01 income
spaces, until end of line or a double space) assets:bank:checking $1
income:salary $-1
o (optional) two or more spaces or tabs followed by an amount.
Positive amounts are being added to the account, negative amounts are
being removed.
The amounts within a transaction must always sum up to zero. As a con-
venience, one amount may be left blank; it will be inferred so as to
balance the transaction.
Be sure to note the unusual two-space delimiter between account name
and amount. This makes it easy to write account names containing spa-
ces. But if you accidentally leave only one space (or tab) before the
amount, the amount will be considered part of the account name.
Dates Dates
Simple dates Simple dates
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) Dates in the journal file use simple dates format: YYYY-MM-DD or
Leading zeros are optional. The year may be omitted, in which case it YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
will be inferred from the context - the current transaction, the de- omitted, in which case it will be inferred from the context: the cur-
fault year set with a default year directive, or the current date when rent transaction, the default year set with a default year directive,
the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, or the current date when the command is run. Some examples:
2010.1.31. 2010-01-31, 2010/01/31, 2010.1.31, 1/31.
(The UI also accepts simple dates, as well as the more flexible smart
dates documented in the hledger manual.)
Secondary dates Secondary dates
Real-life transactions sometimes involve more than one date - eg the Real-life transactions sometimes involve more than one date - eg the
date you write a cheque, and the date it clears in your bank. When you date you write a cheque, and the date it clears in your bank. When you
want to model this, eg for more accurate balances, you can specify in- want to model this, eg for more accurate balances, you can specify in-
dividual posting dates, which I recommend. Or, you can use the sec- dividual posting dates.
ondary dates (aka auxiliary/effective dates) feature, supported for
compatibility with Ledger.
A secondary date can be written after the primary date, separated by an Or, you can use the older secondary date feature. (Ledger calls it
equals sign. The primary date, on the left, is used by default; the auxiliary date or effective date.) But I would recommend avoiding this
secondary date, on the right, is used when the --date2 flag is speci- feature; posting dates are almost always clearer and simpler. We sup-
fied (--aux-date or --effective also work). port it mainly for compatibility.
A secondary date is written after the primary date, following an equals
sign. The primary date's year will be used if the year is omitted.
When running reports, the primary (left) date is used by default, but
with the --date2 flag (or --aux-date or --effective), the secondary
(right) date will be used instead.
The meaning of secondary dates is up to you, but it's best to follow a 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 consistent rule. Eg "primary = the bank's clearing date, secondary =
when needed, the date the transaction was initiated as secondary. date the transaction was initiated, if different", as shown here:
Here's an example. Note that a secondary date will use the year of the
primary date if unspecified.
2010/2/23=2/19 movie ticket 2010/2/23=2/19 movie ticket
expenses:cinema $10 expenses:cinema $10
@ -139,12 +111,6 @@ FILE FORMAT
$ hledger register checking --date2 $ hledger register checking --date2
2010-02-19 movie ticket assets:checking $-10 $-10 2010-02-19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the --date2
flag for your reports. They are included in hledger for Ledger compat-
ibility, but posting dates are a more powerful and less confusing al-
ternative.
Posting dates Posting dates
You can give individual postings a different date from their parent You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below) transaction, by adding a posting comment containing a tag (see below)
@ -233,6 +199,136 @@ FILE FORMAT
ter the first |). This may be worthwhile if you need to do more pre- ter the first |). This may be worthwhile if you need to do more pre-
cise querying and pivoting by payee or by note. cise querying and pivoting by payee or by note.
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) 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.)
You can attach comments to a transaction by writing them after the de-
scription 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. Transac-
tion and posting comments must begin with a semicolon (;).
Some examples:
# 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)
You can also comment larger regions of a file using comment and end
comment directives.
Tags
Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
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:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
assets:checking ; a comment containing tag1:, tag2: some value ...
Here,
o "a comment containing" is just comment text, not a tag
o "tag1" is a tag with no value
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-
tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Postings
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:
o (optional) a status character (empty, !, or *), followed by a space
o (required) an account name (any text, optionally containing single
spaces, until end of line or a double space)
o (optional) two or more spaces or tabs followed by an amount.
Positive amounts are being added to the account, negative amounts are
being removed.
The amounts within a transaction must always sum up to zero. As a con-
venience, one amount may be left blank; it will be inferred so as to
balance the transaction.
Be sure to note the unusual two-space delimiter between account name
and amount. This makes it easy to write account names containing spa-
ces. But if you accidentally leave only one space (or tab) before the
amount, the amount will be considered part of the account name.
Virtual Postings
A posting with a parenthesised account name is called a virtual posting
or unbalanced posting, which means it is exempt from the usual rule
that a transaction's postings must balance add up to zero.
This is not part of double entry accounting, so you might choose to
avoid this feature. Or you can use it sparingly for certain special
cases where it can be convenient. Eg, you could set opening balances
without using a balancing equity account:
1/1 opening balances
(assets:checking) $1000
(assets:savings) $2000
A posting with a bracketed account name is called a balanced virtual
posting. The balanced virtual postings in a transaction must add up to
zero (separately from other postings). Eg:
1/1 buy food with cash, update budget envelope subaccounts, & something else
assets:cash $-10 ; <- these balance
expenses:food $7 ; <-
expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance
Ordinary non-parenthesised, non-bracketed postings are called real
postings. You can exclude virtual postings from reports with the
-R/--real flag or real:1 query.
Account names Account names
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can from which hledger derives a hierarchical chart of accounts. They can
@ -334,36 +430,62 @@ FILE FORMAT
when -V is used.) If you find this causing problems, use a commodity when -V is used.) If you find this causing problems, use a commodity
directive to set the display format. directive to set the display format.
Virtual Postings Transaction prices
When you parenthesise the account name in a posting, we call that a Within a transaction, you can note an amount's price in another commod-
virtual posting, which means: ity. 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 cer-
tain date.
o it is ignored when checking that the transaction is balanced There are several ways to record a transaction price:
o it is excluded from reports when the --real/-R flag is used, or the 1. Write the price per unit, as @ UNITPRICE after the amount:
real:1 query.
You could use this, eg, to set an account's opening balance without 2009/1/1
needing to use the equity:opening balances account: assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00
1/1 special unbalanced posting to set initial balance 2. Write the total price, as @@ TOTALPRICE after the amount:
(assets:checking) $1000
When the account name is bracketed, we call it a balanced virtual post- 2009/1/1
ing. This is like an ordinary virtual posting except the balanced vir- assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot
tual postings in a transaction must balance to 0, like the real post- assets:dollars
ings (but separately from them). Balanced virtual postings are also
excluded by --real/-R or real:1.
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere 3. Specify amounts for all postings, using exactly two commodities, and
expenses:food $10 let hledger infer the price that balances the transaction:
assets:cash $-10
[assets:checking:available] $10
[assets:checking:budget:food] $-10
Virtual postings have some legitimate uses, but those are few. You can 2009/1/1
usually find an equivalent journal entry using real postings, which is assets:euros EUR100 ; one hundred euros purchased
more correct and provides better error checking. assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price'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:
$ hledger bal -N --flat
$-135 assets:dollars
EUR100 assets:euros
$ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
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:
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B
EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros
Balance Assertions Balance Assertions
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
@ -528,139 +650,6 @@ FILE FORMAT
2019-01-01 2019-01-01
(a) $1 @ EUR2 = $1 @ EUR2 (a) $1 @ EUR2 = $1 @ EUR2
Transaction prices
Within a transaction, you can note an amount's price in another commod-
ity. 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 cer-
tain date.
There are several ways to record a transaction price:
1. Write the price per unit, as @ UNITPRICE after the amount:
2009/1/1
assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00
2. Write the total price, as @@ TOTALPRICE after the amount:
2009/1/1
assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot
assets:dollars
3. Specify amounts for all postings, using exactly two commodities, and
let hledger infer the price that balances the transaction:
2009/1/1
assets:euros EUR100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price'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:
$ hledger bal -N --flat
$-135 assets:dollars
EUR100 assets:euros
$ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
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:
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B
EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) 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.)
You can attach comments to a transaction by writing them after the de-
scription 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. Transac-
tion and posting comments must begin with a semicolon (;).
Some examples:
# 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)
You can also comment larger regions of a file using comment and end
comment directives.
Tags
Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
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:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
assets:checking ; a comment containing tag1:, tag2: some value ...
Here,
o "a comment containing" is just comment text, not a tag
o "tag1" is a tag with no value
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-
tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives Directives
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are that influences how the journal is processed. hledger's directives are
@ -683,6 +672,11 @@ FILE FORMAT
tries until end of tries until end of
current file or end current file or end
directive directive
apply end apply prepend a common parent to following in- apply end apply prepend a common parent to following in-
account account account names line/included en- account account account names line/included en-
tries until end of tries until end of
@ -1003,11 +997,14 @@ FILE FORMAT
account other:zoo account other:zoo
would influence the position of zoo among other's subaccounts, but not would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you the position of other among the top-level accounts. This means:
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order - o you will sometimes declare parent accounts (eg account other above)
sibling accounts stay together (you couldn't display x:y in between a:b that you don't intend to post to, just to customize their display or-
and a:c). der
o sibling accounts stay together (you couldn't display x:y in between
a:b and a:c).
Rewriting accounts Rewriting accounts
You can define account alias rules which rewrite your account names, or You can define account alias rules which rewrite your account names, or
@ -1383,15 +1380,6 @@ FILE FORMAT
o _modified: - a hidden tag not appearing in the comment; this transac- o _modified: - a hidden tag not appearing in the comment; this transac-
tion was modified "just now". tion was modified "just now".
EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the Editor configuration at hledger.org for the latest in-
formation.
REPORTING BUGS REPORTING BUGS