doc: journal: expand transactions/postings/status sections (#553)
This commit is contained in:
Simon Michael
parent
2f5d950f0e
commit
34af40024a
@ -61,34 +61,49 @@ Here\[aq]s an example:
|
||||
.SH FILE FORMAT
|
||||
.SS Transactions
|
||||
.PP
|
||||
Transactions are represented by journal entries.
|
||||
Each begins with a simple date in column 0, followed by three optional
|
||||
fields with spaces between them:
|
||||
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
|
||||
a status flag, which can be empty or \f[C]!\f[] or \f[C]*\f[] (meaning
|
||||
"uncleared", "pending" and "cleared", or whatever you want)
|
||||
(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[])
|
||||
.IP \[bu] 2
|
||||
a transaction code (eg a check number),
|
||||
(optional) a transaction code (any short number or text, eg a check
|
||||
number)
|
||||
.IP \[bu] 2
|
||||
and/or a description
|
||||
(optional) a transaction description (any remaining text until end of
|
||||
line)
|
||||
.PP
|
||||
then some number of postings, of some amount to some account.
|
||||
Each posting is on its own line, consisting of:
|
||||
.IP \[bu] 2
|
||||
indentation of one or more spaces (or tabs)
|
||||
.IP \[bu] 2
|
||||
optionally, a \f[C]!\f[] or \f[C]*\f[] status flag followed by a space
|
||||
.IP \[bu] 2
|
||||
an account name, optionally containing single spaces
|
||||
.IP \[bu] 2
|
||||
optionally, two or more spaces or tabs followed by an amount
|
||||
Then comes zero or more (but usually at least 2) indented lines
|
||||
representing...
|
||||
.SS Postings
|
||||
.PP
|
||||
Usually there are two or more postings, though one or none is also
|
||||
possible.
|
||||
The posting amounts within a transaction must always balance, ie add up
|
||||
to 0.
|
||||
Optionally one amount can be left blank, in which case it will be
|
||||
inferred.
|
||||
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
|
||||
@ -195,6 +210,49 @@ 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
|
||||
More about the status field: transactions, or individual postings within
|
||||
a transaction, can be in one of three states, represented by a single
|
||||
character:
|
||||
.IP \[bu] 2
|
||||
empty (no status character) = uncleared
|
||||
.IP \[bu] 2
|
||||
\f[C]!\f[] = pending (aka "tentatively cleared")
|
||||
.IP \[bu] 2
|
||||
\f[C]*\f[] = cleared
|
||||
.PP
|
||||
When reporting, you can filter by status using the
|
||||
\f[C]\-C/\-\-cleared\f[] and \f[C]\-U/\-\-uncleared\f[] flags or the
|
||||
\f[C]status:\f[] query.
|
||||
.PP
|
||||
This feature is optional, but can be helpful for reconciling with
|
||||
real\-world accounts.
|
||||
What "uncleared", "pending", and "cleared" actually mean is up to you.
|
||||
My recommendation: use cleared (\f[C]*\f[]) to mark transactions that
|
||||
are "complete", ie:
|
||||
.IP \[bu] 2
|
||||
they have cleared with the bank, or the cash has been handed over
|
||||
.IP \[bu] 2
|
||||
you are satisfied they are recorded accurately in the journal
|
||||
.IP \[bu] 2
|
||||
the resulting account balance reported by hledger agrees exactly with
|
||||
the external source of truth, if any (eg the bank\[aq]s online register
|
||||
or statement)
|
||||
.PP
|
||||
Then, with \-\-cleared you\[aq]ll see the current balance at your bank,
|
||||
with \-\-uncleared you\[aq]ll see things which will probably hit your
|
||||
bank soon (eg uncashed checks), and with neither flag (the default)
|
||||
you\[aq]ll see the most up\-to\-date state of your finances.
|
||||
.PP
|
||||
I don\[aq]t use pending (\f[C]!\f[]), but perhaps it is useful in very
|
||||
tricky reconciliations, as a temporary marker for transactions matched
|
||||
so far, allowing you start over more easily.
|
||||
.PP
|
||||
Tip: some editor modes highlight entries differently based on their
|
||||
status.
|
||||
In Emacs ledger\-mode, you can toggle transaction status with
|
||||
\f[C]C\-c\ C\-e\f[], or posting status with \f[C]C\-c\ C\-c\f[].
|
||||
.SS Account names
|
||||
.PP
|
||||
Account names typically have several parts separated by a full colon,
|
||||
|
||||
@ -64,7 +64,9 @@ File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev:
|
||||
* Menu:
|
||||
|
||||
* Transactions::
|
||||
* Postings::
|
||||
* Dates::
|
||||
* Status::
|
||||
* Account names::
|
||||
* Amounts::
|
||||
* Virtual Postings::
|
||||
@ -76,37 +78,57 @@ File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev:
|
||||
* Directives::
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Transactions, Next: Dates, Up: FILE FORMAT
|
||||
File: hledger_journal.5.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
|
||||
|
||||
1.1 Transactions
|
||||
================
|
||||
|
||||
Transactions are represented by journal entries. Each begins with a
|
||||
simple date in column 0, followed by three optional fields with spaces
|
||||
between them:
|
||||
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:
|
||||
|
||||
* a status flag, which can be empty or '!' or '*' (meaning
|
||||
"uncleared", "pending" and "cleared", or whatever you want)
|
||||
* a transaction code (eg a check number),
|
||||
* and/or a description
|
||||
* (optional) a status character (empty, '!', or '*')
|
||||
* (optional) a transaction code (any short number or text, eg a check
|
||||
number)
|
||||
* (optional) a transaction description (any remaining text until end
|
||||
of line)
|
||||
|
||||
then some number of postings, of some amount to some account. Each
|
||||
posting is on its own line, consisting of:
|
||||
|
||||
* indentation of one or more spaces (or tabs)
|
||||
* optionally, a '!' or '*' status flag followed by a space
|
||||
* an account name, optionally containing single spaces
|
||||
* optionally, two or more spaces or tabs followed by an amount
|
||||
|
||||
Usually there are two or more postings, though one or none is also
|
||||
possible. The posting amounts within a transaction must always balance,
|
||||
ie add up to 0. Optionally one amount can be left blank, in which case
|
||||
it will be inferred.
|
||||
Then comes zero or more (but usually at least 2) indented lines
|
||||
representing...
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Dates, Next: Account names, Prev: Transactions, Up: FILE FORMAT
|
||||
File: hledger_journal.5.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT
|
||||
|
||||
1.2 Dates
|
||||
1.2 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:
|
||||
|
||||
* (optional) a status character (empty, '!', or '*'), followed by a
|
||||
space
|
||||
* (required) an account name (any text, optionally containing *single
|
||||
spaces*, until end of line or a double space)
|
||||
* (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
|
||||
convenience, 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
|
||||
spaces. But if you accidentally leave only one space (or tab) before
|
||||
the amount, the amount will be considered part of the account name.
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT
|
||||
|
||||
1.3 Dates
|
||||
=========
|
||||
|
||||
* Menu:
|
||||
@ -118,7 +140,7 @@ File: hledger_journal.5.info, Node: Dates, Next: Account names, Prev: Transac
|
||||
|
||||
File: hledger_journal.5.info, Node: Simple dates, Next: Secondary dates, Up: Dates
|
||||
|
||||
1.2.1 Simple dates
|
||||
1.3.1 Simple dates
|
||||
------------------
|
||||
|
||||
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
|
||||
@ -131,7 +153,7 @@ command is run. Some examples: '2010/01/31', '1/31', '2010-01-31',
|
||||
|
||||
File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates
|
||||
|
||||
1.2.2 Secondary dates
|
||||
1.3.2 Secondary dates
|
||||
---------------------
|
||||
|
||||
Real-life transactions sometimes involve more than one date - eg the
|
||||
@ -172,7 +194,7 @@ confusing alternative.
|
||||
|
||||
File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up: Dates
|
||||
|
||||
1.2.3 Posting dates
|
||||
1.3.3 Posting dates
|
||||
-------------------
|
||||
|
||||
You can give individual postings a different date from their parent
|
||||
@ -205,9 +227,50 @@ characters in this way. With this syntax, DATE infers its year from the
|
||||
transaction and DATE2 infers its year from DATE.
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Dates, Up: FILE FORMAT
|
||||
File: hledger_journal.5.info, Node: Status, Next: Account names, Prev: Dates, Up: FILE FORMAT
|
||||
|
||||
1.3 Account names
|
||||
1.4 Status
|
||||
==========
|
||||
|
||||
More about the status field: transactions, or individual postings within
|
||||
a transaction, can be in one of three states, represented by a single
|
||||
character:
|
||||
|
||||
* empty (no status character) = uncleared
|
||||
* '!' = pending (aka "tentatively cleared")
|
||||
* '*' = cleared
|
||||
|
||||
When reporting, you can filter by status using the '-C/--cleared' and
|
||||
'-U/--uncleared' flags or the 'status:' query.
|
||||
|
||||
This feature is optional, but can be helpful for reconciling with
|
||||
real-world accounts. What "uncleared", "pending", and "cleared"
|
||||
actually mean is up to you. My recommendation: use cleared ('*') to
|
||||
mark transactions that are "complete", ie:
|
||||
|
||||
* they have cleared with the bank, or the cash has been handed over
|
||||
* you are satisfied they are recorded accurately in the journal
|
||||
* the resulting account balance reported by hledger agrees exactly
|
||||
with the external source of truth, if any (eg the bank's online
|
||||
register or statement)
|
||||
|
||||
Then, with -cleared you'll see the current balance at your bank, with
|
||||
-uncleared you'll see things which will probably hit your bank soon (eg
|
||||
uncashed checks), and with neither flag (the default) you'll see the
|
||||
most up-to-date state of your finances.
|
||||
|
||||
I don't use pending ('!'), but perhaps it is useful in very tricky
|
||||
reconciliations, as a temporary marker for transactions matched so far,
|
||||
allowing you start over more easily.
|
||||
|
||||
Tip: some editor modes highlight entries differently based on their
|
||||
status. In Emacs ledger-mode, you can toggle transaction status with
|
||||
'C-c C-e', or posting status with 'C-c C-c'.
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Status, Up: FILE FORMAT
|
||||
|
||||
1.5 Account names
|
||||
=================
|
||||
|
||||
Account names typically have several parts separated by a full colon,
|
||||
@ -225,7 +288,7 @@ more spaces* (or newline).
|
||||
|
||||
File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT
|
||||
|
||||
1.4 Amounts
|
||||
1.6 Amounts
|
||||
===========
|
||||
|
||||
After the account name, there is usually an amount. Important: between
|
||||
@ -280,7 +343,7 @@ format with a commodity directive.
|
||||
|
||||
File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT
|
||||
|
||||
1.5 Virtual Postings
|
||||
1.7 Virtual Postings
|
||||
====================
|
||||
|
||||
When you parenthesise the account name in a posting, we call that a
|
||||
@ -315,7 +378,7 @@ is more correct and provides better error checking.
|
||||
|
||||
File: hledger_journal.5.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT
|
||||
|
||||
1.6 Balance Assertions
|
||||
1.8 Balance Assertions
|
||||
======================
|
||||
|
||||
hledger supports Ledger-style balance assertions in journal files.
|
||||
@ -349,7 +412,7 @@ or for reading Ledger files.
|
||||
|
||||
File: hledger_journal.5.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions
|
||||
|
||||
1.6.1 Assertions and ordering
|
||||
1.8.1 Assertions and ordering
|
||||
-----------------------------
|
||||
|
||||
hledger sorts an account's postings and assertions first by date and
|
||||
@ -368,7 +431,7 @@ can assert intra-day balances.
|
||||
|
||||
File: hledger_journal.5.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions
|
||||
|
||||
1.6.2 Assertions and included files
|
||||
1.8.2 Assertions and included files
|
||||
-----------------------------------
|
||||
|
||||
With included files, things are a little more complicated. Including
|
||||
@ -380,7 +443,7 @@ you'll have to put the assertion in the right file.
|
||||
|
||||
File: hledger_journal.5.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions
|
||||
|
||||
1.6.3 Assertions and multiple -f options
|
||||
1.8.3 Assertions and multiple -f options
|
||||
----------------------------------------
|
||||
|
||||
Balance assertions don't work well across files specified with multiple
|
||||
@ -389,7 +452,7 @@ Balance assertions don't work well across files specified with multiple
|
||||
|
||||
File: hledger_journal.5.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and multiple -f options, Up: Balance Assertions
|
||||
|
||||
1.6.4 Assertions and commodities
|
||||
1.8.4 Assertions and commodities
|
||||
--------------------------------
|
||||
|
||||
The asserted balance must be a simple single-commodity amount, and in
|
||||
@ -408,7 +471,7 @@ for this kind of total balance assertion if there's demand.)
|
||||
|
||||
File: hledger_journal.5.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions
|
||||
|
||||
1.6.5 Assertions and subaccounts
|
||||
1.8.5 Assertions and subaccounts
|
||||
--------------------------------
|
||||
|
||||
Balance assertions do not count the balance from subaccounts; they check
|
||||
@ -431,7 +494,7 @@ $ hledger bal checking --flat
|
||||
|
||||
File: hledger_journal.5.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions
|
||||
|
||||
1.6.6 Assertions and virtual postings
|
||||
1.8.6 Assertions and virtual postings
|
||||
-------------------------------------
|
||||
|
||||
Balance assertions are checked against all postings, both real and
|
||||
@ -441,7 +504,7 @@ query.
|
||||
|
||||
File: hledger_journal.5.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT
|
||||
|
||||
1.7 Balance Assignments
|
||||
1.9 Balance Assignments
|
||||
=======================
|
||||
|
||||
Ledger-style balance assignments are also supported. These are like
|
||||
@ -474,8 +537,8 @@ hledger or do the calculations yourself, instead of just reading it.
|
||||
|
||||
File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT
|
||||
|
||||
1.8 Prices
|
||||
==========
|
||||
1.10 Prices
|
||||
===========
|
||||
|
||||
* Menu:
|
||||
|
||||
@ -485,8 +548,8 @@ File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Ass
|
||||
|
||||
File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, Up: Prices
|
||||
|
||||
1.8.1 Transaction prices
|
||||
------------------------
|
||||
1.10.1 Transaction prices
|
||||
-------------------------
|
||||
|
||||
Within a transaction, you can note an amount's price in another
|
||||
commodity. This can be used to document the cost (in a purchase) or
|
||||
@ -546,8 +609,8 @@ $ hledger bal -N --flat -B
|
||||
|
||||
File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices
|
||||
|
||||
1.8.2 Market prices
|
||||
-------------------
|
||||
1.10.2 Market prices
|
||||
--------------------
|
||||
|
||||
Market prices are not tied to a particular transaction; they represent
|
||||
historical exchange rates between two commodities. (Ledger calls them
|
||||
@ -575,8 +638,8 @@ P 2010/1/1 € $1.40
|
||||
|
||||
File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT
|
||||
|
||||
1.9 Comments
|
||||
============
|
||||
1.11 Comments
|
||||
=============
|
||||
|
||||
Lines in the journal beginning with a semicolon (';') or hash ('#') or
|
||||
asterisk ('*') are comments, and will be ignored. (Asterisk comments
|
||||
@ -615,7 +678,7 @@ end comment
|
||||
|
||||
File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
|
||||
|
||||
1.10 Tags
|
||||
1.12 Tags
|
||||
=========
|
||||
|
||||
Tags are a way to add extra labels or labelled data to postings and
|
||||
@ -661,7 +724,7 @@ are simple strings.
|
||||
|
||||
File: hledger_journal.5.info, Node: Implicit tags, Up: Tags
|
||||
|
||||
1.10.1 Implicit tags
|
||||
1.12.1 Implicit tags
|
||||
--------------------
|
||||
|
||||
Some predefined "implicit" tags are also provided:
|
||||
@ -679,7 +742,7 @@ the same as 'description'.
|
||||
|
||||
File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
|
||||
|
||||
1.11 Directives
|
||||
1.13 Directives
|
||||
===============
|
||||
|
||||
* Menu:
|
||||
@ -696,7 +759,7 @@ File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
|
||||
|
||||
File: hledger_journal.5.info, Node: Account aliases, Next: account directive, Up: Directives
|
||||
|
||||
1.11.1 Account aliases
|
||||
1.13.1 Account aliases
|
||||
----------------------
|
||||
|
||||
You can define aliases which rewrite your account names (after reading
|
||||
@ -721,7 +784,7 @@ be useful for:
|
||||
|
||||
File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
|
||||
|
||||
1.11.1.1 Basic aliases
|
||||
1.13.1.1 Basic aliases
|
||||
......................
|
||||
|
||||
To set an account alias, use the 'alias' directive in your journal file.
|
||||
@ -744,7 +807,7 @@ alias checking = assets:bank:wells fargo:checking
|
||||
|
||||
File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
|
||||
|
||||
1.11.1.2 Regex aliases
|
||||
1.13.1.2 Regex aliases
|
||||
......................
|
||||
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
@ -767,7 +830,7 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
|
||||
|
||||
File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
|
||||
|
||||
1.11.1.3 Multiple aliases
|
||||
1.13.1.3 Multiple aliases
|
||||
.........................
|
||||
|
||||
You can define as many aliases as you like using directives or
|
||||
@ -783,7 +846,7 @@ following order:
|
||||
|
||||
File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
|
||||
|
||||
1.11.1.4 end aliases
|
||||
1.13.1.4 end aliases
|
||||
....................
|
||||
|
||||
You can clear (forget) all currently defined aliases with the 'end
|
||||
@ -794,7 +857,7 @@ end aliases
|
||||
|
||||
File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
|
||||
|
||||
1.11.2 account directive
|
||||
1.13.2 account directive
|
||||
------------------------
|
||||
|
||||
The 'account' directive predefines account names, as in Ledger and
|
||||
@ -815,7 +878,7 @@ account expenses:food
|
||||
|
||||
File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
|
||||
|
||||
1.11.3 apply account directive
|
||||
1.13.3 apply account directive
|
||||
------------------------------
|
||||
|
||||
You can specify a parent account which will be prepended to all accounts
|
||||
@ -851,7 +914,7 @@ supported.
|
||||
|
||||
File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
|
||||
|
||||
1.11.4 Multi-line comments
|
||||
1.13.4 Multi-line comments
|
||||
--------------------------
|
||||
|
||||
A line containing just 'comment' starts a multi-line comment, and a line
|
||||
@ -860,7 +923,7 @@ containing just 'end comment' ends it. See comments.
|
||||
|
||||
File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
|
||||
|
||||
1.11.5 commodity directive
|
||||
1.13.5 commodity directive
|
||||
--------------------------
|
||||
|
||||
The 'commodity' directive predefines commodities (currently this is just
|
||||
@ -892,7 +955,7 @@ commodity INR
|
||||
|
||||
File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
|
||||
|
||||
1.11.6 Default commodity
|
||||
1.13.6 Default commodity
|
||||
------------------------
|
||||
|
||||
The D directive sets a default commodity (and display format), to be
|
||||
@ -912,7 +975,7 @@ D $1,000.00
|
||||
|
||||
File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
|
||||
|
||||
1.11.7 Default year
|
||||
1.13.7 Default year
|
||||
-------------------
|
||||
|
||||
You can set a default year to be used for subsequent dates which don't
|
||||
@ -938,7 +1001,7 @@ Y2010 ; change default year to 2010
|
||||
|
||||
File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives
|
||||
|
||||
1.11.8 Including other files
|
||||
1.13.8 Including other files
|
||||
----------------------------
|
||||
|
||||
You can pull in the content of additional journal files by writing an
|
||||
@ -977,77 +1040,81 @@ Tag Table:
|
||||
Node: Top78
|
||||
Node: FILE FORMAT2292
|
||||
Ref: #file-format2418
|
||||
Node: Transactions2601
|
||||
Ref: #transactions2721
|
||||
Node: Dates3663
|
||||
Ref: #dates3791
|
||||
Node: Simple dates3856
|
||||
Ref: #simple-dates3984
|
||||
Node: Secondary dates4350
|
||||
Ref: #secondary-dates4506
|
||||
Node: Posting dates6069
|
||||
Ref: #posting-dates6200
|
||||
Node: Account names7574
|
||||
Ref: #account-names7713
|
||||
Node: Amounts8200
|
||||
Ref: #amounts8338
|
||||
Node: Virtual Postings10439
|
||||
Ref: #virtual-postings10600
|
||||
Node: Balance Assertions11820
|
||||
Ref: #balance-assertions11997
|
||||
Node: Assertions and ordering12893
|
||||
Ref: #assertions-and-ordering13081
|
||||
Node: Assertions and included files13781
|
||||
Ref: #assertions-and-included-files14024
|
||||
Node: Assertions and multiple -f options14357
|
||||
Ref: #assertions-and-multiple--f-options14613
|
||||
Node: Assertions and commodities14745
|
||||
Ref: #assertions-and-commodities14982
|
||||
Node: Assertions and subaccounts15678
|
||||
Ref: #assertions-and-subaccounts15912
|
||||
Node: Assertions and virtual postings16433
|
||||
Ref: #assertions-and-virtual-postings16642
|
||||
Node: Balance Assignments16784
|
||||
Ref: #balance-assignments16953
|
||||
Node: Prices18072
|
||||
Ref: #prices18205
|
||||
Node: Transaction prices18256
|
||||
Ref: #transaction-prices18401
|
||||
Node: Market prices20557
|
||||
Ref: #market-prices20692
|
||||
Node: Comments21652
|
||||
Ref: #comments21774
|
||||
Node: Tags22887
|
||||
Ref: #tags23007
|
||||
Node: Implicit tags24436
|
||||
Ref: #implicit-tags24544
|
||||
Node: Directives25061
|
||||
Ref: #directives25176
|
||||
Node: Account aliases25369
|
||||
Ref: #account-aliases25515
|
||||
Node: Basic aliases26119
|
||||
Ref: #basic-aliases26264
|
||||
Node: Regex aliases26954
|
||||
Ref: #regex-aliases27124
|
||||
Node: Multiple aliases27839
|
||||
Ref: #multiple-aliases28013
|
||||
Node: end aliases28511
|
||||
Ref: #end-aliases28653
|
||||
Node: account directive28754
|
||||
Ref: #account-directive28936
|
||||
Node: apply account directive29232
|
||||
Ref: #apply-account-directive29430
|
||||
Node: Multi-line comments30089
|
||||
Ref: #multi-line-comments30281
|
||||
Node: commodity directive30409
|
||||
Ref: #commodity-directive30595
|
||||
Node: Default commodity31467
|
||||
Ref: #default-commodity31642
|
||||
Node: Default year32179
|
||||
Ref: #default-year32346
|
||||
Node: Including other files32769
|
||||
Ref: #including-other-files32928
|
||||
Node: EDITOR SUPPORT33325
|
||||
Ref: #editor-support33445
|
||||
Node: Transactions2625
|
||||
Ref: #transactions2748
|
||||
Node: Postings3307
|
||||
Ref: #postings3436
|
||||
Node: Dates4431
|
||||
Ref: #dates4548
|
||||
Node: Simple dates4613
|
||||
Ref: #simple-dates4741
|
||||
Node: Secondary dates5107
|
||||
Ref: #secondary-dates5263
|
||||
Node: Posting dates6826
|
||||
Ref: #posting-dates6957
|
||||
Node: Status8331
|
||||
Ref: #status8455
|
||||
Node: Account names10018
|
||||
Ref: #account-names10158
|
||||
Node: Amounts10645
|
||||
Ref: #amounts10783
|
||||
Node: Virtual Postings12884
|
||||
Ref: #virtual-postings13045
|
||||
Node: Balance Assertions14265
|
||||
Ref: #balance-assertions14442
|
||||
Node: Assertions and ordering15338
|
||||
Ref: #assertions-and-ordering15526
|
||||
Node: Assertions and included files16226
|
||||
Ref: #assertions-and-included-files16469
|
||||
Node: Assertions and multiple -f options16802
|
||||
Ref: #assertions-and-multiple--f-options17058
|
||||
Node: Assertions and commodities17190
|
||||
Ref: #assertions-and-commodities17427
|
||||
Node: Assertions and subaccounts18123
|
||||
Ref: #assertions-and-subaccounts18357
|
||||
Node: Assertions and virtual postings18878
|
||||
Ref: #assertions-and-virtual-postings19087
|
||||
Node: Balance Assignments19229
|
||||
Ref: #balance-assignments19398
|
||||
Node: Prices20517
|
||||
Ref: #prices20652
|
||||
Node: Transaction prices20703
|
||||
Ref: #transaction-prices20850
|
||||
Node: Market prices23006
|
||||
Ref: #market-prices23143
|
||||
Node: Comments24103
|
||||
Ref: #comments24227
|
||||
Node: Tags25340
|
||||
Ref: #tags25460
|
||||
Node: Implicit tags26889
|
||||
Ref: #implicit-tags26997
|
||||
Node: Directives27514
|
||||
Ref: #directives27629
|
||||
Node: Account aliases27822
|
||||
Ref: #account-aliases27968
|
||||
Node: Basic aliases28572
|
||||
Ref: #basic-aliases28717
|
||||
Node: Regex aliases29407
|
||||
Ref: #regex-aliases29577
|
||||
Node: Multiple aliases30292
|
||||
Ref: #multiple-aliases30466
|
||||
Node: end aliases30964
|
||||
Ref: #end-aliases31106
|
||||
Node: account directive31207
|
||||
Ref: #account-directive31389
|
||||
Node: apply account directive31685
|
||||
Ref: #apply-account-directive31883
|
||||
Node: Multi-line comments32542
|
||||
Ref: #multi-line-comments32734
|
||||
Node: commodity directive32862
|
||||
Ref: #commodity-directive33048
|
||||
Node: Default commodity33920
|
||||
Ref: #default-commodity34095
|
||||
Node: Default year34632
|
||||
Ref: #default-year34799
|
||||
Node: Including other files35222
|
||||
Ref: #including-other-files35381
|
||||
Node: EDITOR SUPPORT35778
|
||||
Ref: #editor-support35898
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -65,27 +65,33 @@ Here's an example:
|
||||
|
||||
## Transactions
|
||||
|
||||
Transactions are represented by journal entries. Each begins with a
|
||||
[simple date](#simple-dates) in column 0, followed by three optional
|
||||
fields with spaces between them:
|
||||
Transactions are movements of some quantity of commodities between named accounts.
|
||||
Each transaction is represented by a journal entry beginning with a [simple date](#simple-dates) in column 0.
|
||||
This can be followed by any of the following, separated by spaces:
|
||||
|
||||
- a status flag, which can be empty or `!` or `*` (meaning "uncleared",
|
||||
"pending" and "cleared", or whatever you want)
|
||||
- a transaction code (eg a check number),
|
||||
- and/or a description
|
||||
- (optional) a [status](#status) character (empty, `!`, or `*`)
|
||||
- (optional) a transaction code (any short number or text, eg a check number)
|
||||
- (optional) a transaction description (any remaining text until end of line)
|
||||
|
||||
then some number of postings, of some amount to some account. Each
|
||||
posting is on its own line, consisting of:
|
||||
Then comes zero or more (but usually at least 2) indented lines representing...
|
||||
|
||||
- indentation of one or more spaces (or tabs)
|
||||
- optionally, a `!` or `*` status flag followed by a space
|
||||
- an account name, optionally containing single spaces
|
||||
- optionally, two or more spaces or tabs followed by an amount
|
||||
## Postings
|
||||
|
||||
Usually there are two or more postings, though one or none is also
|
||||
possible. The posting amounts within a transaction must always balance,
|
||||
ie add up to 0. Optionally one amount can be left blank, in which case
|
||||
it will be inferred.
|
||||
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:
|
||||
|
||||
- (optional) a [status](#status) character (empty, `!`, or `*`), followed by a space
|
||||
- (required) an [account name](#account-names) (any text, optionally containing **single spaces**, until end of line or a double space)
|
||||
- (optional) **two or more spaces** or tabs followed by an [amount](#amounts).
|
||||
|
||||
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 convenience, 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 spaces.
|
||||
But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name.
|
||||
|
||||
## Dates
|
||||
|
||||
@ -177,6 +183,36 @@ attempt to parse any square-bracketed sequence of the `0123456789/-.=`
|
||||
characters in this way. With this syntax, DATE infers its year from
|
||||
the transaction and DATE2 infers its year from DATE.
|
||||
|
||||
## Status
|
||||
|
||||
More about the status field: transactions, or individual postings within a transaction,
|
||||
can be in one of three states, represented by a single character:
|
||||
|
||||
- empty (no status character) = uncleared
|
||||
- `!` = pending (aka "tentatively cleared")
|
||||
- `*` = cleared
|
||||
|
||||
When reporting, you can filter by status using the `-C/--cleared` and `-U/--uncleared` flags
|
||||
or the `status:` query.
|
||||
|
||||
This feature is optional, but can be helpful for reconciling with real-world accounts.
|
||||
What "uncleared", "pending", and "cleared" actually mean is up to you.
|
||||
My recommendation: use cleared (`*`) to mark transactions that are "complete", ie:
|
||||
|
||||
- they have cleared with the bank, or the cash has been handed over
|
||||
- you are satisfied they are recorded accurately in the journal
|
||||
- the resulting account balance reported by hledger agrees exactly with the external source of truth, if any (eg the bank's online register or statement)
|
||||
|
||||
Then, with --cleared you'll see the current balance at your bank,
|
||||
with --uncleared you'll see things which will probably hit your bank soon (eg uncashed checks),
|
||||
and with neither flag (the default) you'll see the most up-to-date state of your finances.
|
||||
|
||||
I don't use pending (`!`), but perhaps it is useful in very tricky reconciliations,
|
||||
as a temporary marker for transactions matched so far, allowing you start over more easily.
|
||||
|
||||
Tip: some [editor modes](#editor-support) highlight entries differently based on their status.
|
||||
In Emacs ledger-mode, you can toggle transaction status with `C-c C-e`, or posting status with `C-c C-c`.
|
||||
|
||||
## Account names
|
||||
|
||||
Account names typically have several parts separated by a full colon, from
|
||||
|
||||
@ -53,32 +53,45 @@ DESCRIPTION
|
||||
|
||||
FILE FORMAT
|
||||
Transactions
|
||||
Transactions are represented by journal entries. Each begins with a
|
||||
simple date in column 0, followed by three optional fields with spaces
|
||||
between them:
|
||||
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:
|
||||
|
||||
o a status flag, which can be empty or ! or * (meaning "uncleared",
|
||||
"pending" and "cleared", or whatever you want)
|
||||
o (optional) a status character (empty, !, or *)
|
||||
|
||||
o a transaction code (eg a check number),
|
||||
o (optional) a transaction code (any short number or text, eg a check
|
||||
number)
|
||||
|
||||
o and/or a description
|
||||
o (optional) a transaction description (any remaining text until end of
|
||||
line)
|
||||
|
||||
then some number of postings, of some amount to some account. Each
|
||||
posting is on its own line, consisting of:
|
||||
Then comes zero or more (but usually at least 2) indented lines repre-
|
||||
senting...
|
||||
|
||||
o indentation of one or more spaces (or tabs)
|
||||
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 optionally, a ! or * status flag followed by a space
|
||||
o (optional) a status character (empty, !, or *), followed by a space
|
||||
|
||||
o an account name, optionally containing single spaces
|
||||
o (required) an account name (any text, optionally containing single
|
||||
spaces, until end of line or a double space)
|
||||
|
||||
o optionally, two or more spaces or tabs followed by an amount
|
||||
o (optional) two or more spaces or tabs followed by an amount.
|
||||
|
||||
Usually there are two or more postings, though one or none is also pos-
|
||||
sible. The posting amounts within a transaction must always balance,
|
||||
ie add up to 0. Optionally one amount can be left blank, in which case
|
||||
it will be inferred.
|
||||
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
|
||||
Simple dates
|
||||
@ -155,6 +168,46 @@ FILE FORMAT
|
||||
With this syntax, DATE infers its year from the transaction and DATE2
|
||||
infers its year from DATE.
|
||||
|
||||
Status
|
||||
More about the status field: transactions, or individual postings
|
||||
within a transaction, can be in one of three states, represented by a
|
||||
single character:
|
||||
|
||||
o empty (no status character) = uncleared
|
||||
|
||||
o ! = pending (aka "tentatively cleared")
|
||||
|
||||
o * = cleared
|
||||
|
||||
When reporting, you can filter by status using the -C/--cleared and
|
||||
-U/--uncleared flags or the status: query.
|
||||
|
||||
This feature is optional, but can be helpful for reconciling with
|
||||
real-world accounts. What "uncleared", "pending", and "cleared" actu-
|
||||
ally mean is up to you. My recommendation: use cleared (*) to mark
|
||||
transactions that are "complete", ie:
|
||||
|
||||
o they have cleared with the bank, or the cash has been handed over
|
||||
|
||||
o you are satisfied they are recorded accurately in the journal
|
||||
|
||||
o the resulting account balance reported by hledger agrees exactly with
|
||||
the external source of truth, if any (eg the bank's online register
|
||||
or statement)
|
||||
|
||||
Then, with --cleared you'll see the current balance at your bank, with
|
||||
--uncleared you'll see things which will probably hit your bank soon
|
||||
(eg uncashed checks), and with neither flag (the default) you'll see
|
||||
the most up-to-date state of your finances.
|
||||
|
||||
I don't use pending (!), but perhaps it is useful in very tricky recon-
|
||||
ciliations, as a temporary marker for transactions matched so far,
|
||||
allowing you start over more easily.
|
||||
|
||||
Tip: some editor modes highlight entries differently based on their
|
||||
status. In Emacs ledger-mode, you can toggle transaction status with
|
||||
C-c C-e, or posting status with C-c C-c.
|
||||
|
||||
Account names
|
||||
Account names typically have several parts separated by a full colon,
|
||||
from which hledger derives a hierarchical chart of accounts. They can
|
||||
@ -746,9 +799,9 @@ EDITOR SUPPORT
|
||||
ting-started
|
||||
Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub-
|
||||
lime-Text
|
||||
|
||||
Textmate https://github.com/ledger/ledger/wiki/Using-Text-
|
||||
Mate-2
|
||||
|
||||
Text Wrangler https://github.com/ledger/ledger/wiki/Edit-
|
||||
ing-Ledger-files-with-TextWrangler
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user