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

doc: update description/payee/note docs (#598, #608)

Browse Source
This commit is contained in:
Simon Michael 2017-09-05 11:44:02 -07:00
parent 9501b43471
commit 079e76a370
16 changed files with 756 additions and 733 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/lib.m4
View File

@ -92,8 +92,8 @@ m4_define({{_inputoptions_}}, {{
`--anon`
: anonymize accounts and payees
`--pivot TAGNAME`
: use some other field/tag for account names
`--pivot FIELDNAME`
: use some other field or tag for the account name
`-I --ignore-assertions`
: ignore any failing balance assertions

40
hledger-lib/doc/hledger_journal.5
View File

@ -77,7 +77,10 @@ This can be followed by any of the following, separated by spaces:
parentheses)
.IP \[bu] 2
(optional) a transaction description (any remaining text until end of
line)
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...
@ -300,6 +303,23 @@ 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, payee and note
.PP
As mentioned, a transaction\[aq]s description is the rest of the line
following the date and status mark (or, the rest of line until a comment
begins).
Sometimes called the "narration" in traditional bookkeeping, it can be
used for whatever you wish, or left blank.
The description can be queried, unlike comments.
.PP
Including a \f[C]|\f[] (pipe) character in the description will
subdivide it into a payee/payer name (on the left) and additional notes
(on the right).
This is entirely optional, but it can allow more precise
.PD 0
.P
.PD
querying and pivoting.
.SS Account names
.PP
Account names typically have several parts separated by a full colon,
@ -797,24 +817,6 @@ For example, the following transaction has three tags (\f[C]A\f[],
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are simple strings.
.SS Implicit tags
.PP
Some predefined "implicit" tags are also provided:
.IP \[bu] 2
\f[C]code\f[] \- the transaction\[aq]s code field
.IP \[bu] 2
\f[C]description\f[] \- the transaction\[aq]s description
.IP \[bu] 2
\f[C]payee\f[] \- the part of description before \f[C]|\f[], or all of
it
.IP \[bu] 2
\f[C]note\f[] \- the part of description after \f[C]|\f[], or all of it
.PP
\f[C]payee\f[] and \f[C]note\f[] support descriptions written in a
special \f[C]PAYEE\ |\ NOTE\f[] format, accessing the parts before and
after the pipe character respectively.
For descriptions not containing a pipe character they are the same as
\f[C]description\f[].
.SS Directives
.SS Account aliases
.PP

259
hledger-lib/doc/hledger_journal.5.info
View File

@ -71,6 +71,7 @@ File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev:
* Postings::
* Dates::
* Status::
* Description payee and note::
* Account names::
* Amounts::
* Virtual Postings::
@ -96,7 +97,9 @@ following, separated by spaces:
* (optional) a transaction code (any short number or text, enclosed
in parentheses)
* (optional) a transaction description (any remaining text until end
of line)
of line or a semicolon)
* (optional) a transaction comment (any remaining text following a
semicolon until end of line)
Then comes zero or more (but usually at least 2) indented lines
representing...
@ -231,7 +234,7 @@ 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: Status, Next: Account names, Prev: Dates, Up: FILE FORMAT
File: hledger_journal.5.info, Node: Status, Next: Description payee and note, Prev: Dates, Up: FILE FORMAT
1.4 Status
==========
@ -281,9 +284,26 @@ your bank, '-U' to see things which will probably hit your bank soon
your finances.

File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Status, Up: FILE FORMAT
File: hledger_journal.5.info, Node: Description payee and note, Next: Account names, Prev: Status, Up: FILE FORMAT
1.5 Account names
1.5 Description, payee and note
===============================
As mentioned, a transaction's description is the rest of the line
following the date and status mark (or, the rest of line until a comment
begins). Sometimes called the "narration" in traditional bookkeeping,
it can be used for whatever you wish, or left blank. The description
can be queried, unlike comments.
Including a '|' (pipe) character in the description will subdivide it
into a payee/payer name (on the left) and additional notes (on the
right). This is entirely optional, but it can allow more precise
querying and pivoting.

File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Description payee and note, Up: FILE FORMAT
1.6 Account names
=================
Account names typically have several parts separated by a full colon,
@ -301,7 +321,7 @@ more spaces* (or newline).

File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT
1.6 Amounts
1.7 Amounts
===========
After the account name, there is usually an amount. Important: between
@ -356,7 +376,7 @@ format with a commodity directive.

File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT
1.7 Virtual Postings
1.8 Virtual Postings
====================
When you parenthesise the account name in a posting, we call that a
@ -391,7 +411,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.8 Balance Assertions
1.9 Balance Assertions
======================
hledger supports Ledger-style balance assertions in journal files.
@ -425,7 +445,7 @@ or for reading Ledger files.

File: hledger_journal.5.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions
1.8.1 Assertions and ordering
1.9.1 Assertions and ordering
-----------------------------
hledger sorts an account's postings and assertions first by date and
@ -444,7 +464,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.8.2 Assertions and included files
1.9.2 Assertions and included files
-----------------------------------
With included files, things are a little more complicated. Including
@ -456,7 +476,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.8.3 Assertions and multiple -f options
1.9.3 Assertions and multiple -f options
----------------------------------------
Balance assertions don't work well across files specified with multiple
@ -465,7 +485,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.8.4 Assertions and commodities
1.9.4 Assertions and commodities
--------------------------------
The asserted balance must be a simple single-commodity amount, and in
@ -484,7 +504,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.8.5 Assertions and subaccounts
1.9.5 Assertions and subaccounts
--------------------------------
Balance assertions do not count the balance from subaccounts; they check
@ -507,7 +527,7 @@ $ hledger bal checking --flat

File: hledger_journal.5.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions
1.8.6 Assertions and virtual postings
1.9.6 Assertions and virtual postings
-------------------------------------
Balance assertions are checked against all postings, both real and
@ -517,8 +537,8 @@ query.

File: hledger_journal.5.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT
1.9 Balance Assignments
=======================
1.10 Balance Assignments
========================
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
@ -550,7 +570,7 @@ 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.10 Prices
1.11 Prices
===========
* Menu:
@ -561,7 +581,7 @@ 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.10.1 Transaction prices
1.11.1 Transaction prices
-------------------------
Within a transaction, you can note an amount's price in another
@ -622,7 +642,7 @@ $ hledger bal -N --flat -B

File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices
1.10.2 Market prices
1.11.2 Market prices
--------------------
Market prices are not tied to a particular transaction; they represent
@ -651,7 +671,7 @@ P 2010/1/1 € $1.40

File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT
1.11 Comments
1.12 Comments
=============
Lines in the journal beginning with a semicolon (';') or hash ('#') or
@ -691,7 +711,7 @@ end comment

File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
1.12 Tags
1.13 Tags
=========
Tags are a way to add extra labels or labelled data to postings and
@ -730,32 +750,11 @@ example, the following transaction has three tags ('A', 'TAG2',
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
* Menu:
* Implicit tags::

File: hledger_journal.5.info, Node: Implicit tags, Up: Tags
1.12.1 Implicit tags
--------------------
Some predefined "implicit" tags are also provided:
* 'code' - the transaction's code field
* 'description' - the transaction's description
* 'payee' - the part of description before '|', or all of it
* 'note' - the part of description after '|', or all of it
'payee' and 'note' support descriptions written in a special 'PAYEE |
NOTE' format, accessing the parts before and after the pipe character
respectively. For descriptions not containing a pipe character they are
the same as 'description'.

File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
1.13 Directives
1.14 Directives
===============
* Menu:
@ -772,7 +771,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.13.1 Account aliases
1.14.1 Account aliases
----------------------
You can define aliases which rewrite your account names (after reading
@ -797,7 +796,7 @@ be useful for:

File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
1.13.1.1 Basic aliases
1.14.1.1 Basic aliases
......................
To set an account alias, use the 'alias' directive in your journal file.
@ -820,7 +819,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.13.1.2 Regex aliases
1.14.1.2 Regex aliases
......................
There is also a more powerful variant that uses a regular expression,
@ -843,7 +842,7 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3

File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
1.13.1.3 Multiple aliases
1.14.1.3 Multiple aliases
.........................
You can define as many aliases as you like using directives or
@ -859,7 +858,7 @@ following order:

File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
1.13.1.4 end aliases
1.14.1.4 end aliases
....................
You can clear (forget) all currently defined aliases with the 'end
@ -870,7 +869,7 @@ end aliases

File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
1.13.2 account directive
1.14.2 account directive
------------------------
The 'account' directive predefines account names, as in Ledger and
@ -891,7 +890,7 @@ account expenses:food

File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
1.13.3 apply account directive
1.14.3 apply account directive
------------------------------
You can specify a parent account which will be prepended to all accounts
@ -927,7 +926,7 @@ supported.

File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
1.13.4 Multi-line comments
1.14.4 Multi-line comments
--------------------------
A line containing just 'comment' starts a multi-line comment, and a line
@ -936,7 +935,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.13.5 commodity directive
1.14.5 commodity directive
--------------------------
The 'commodity' directive predefines commodities (currently this is just
@ -968,7 +967,7 @@ commodity INR

File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
1.13.6 Default commodity
1.14.6 Default commodity
------------------------
The D directive sets a default commodity (and display format), to be
@ -988,7 +987,7 @@ D $1,000.00

File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
1.13.7 Default year
1.14.7 Default year
-------------------
You can set a default year to be used for subsequent dates which don't
@ -1014,7 +1013,7 @@ Y2010 ; change default year to 2010

File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives
1.13.8 Including other files
1.14.8 Including other files
----------------------------
You can pull in the content of additional journal files by writing an
@ -1055,81 +1054,81 @@ Tag Table:
Node: Top78
Node: FILE FORMAT2380
Ref: #file-format2506
Node: Transactions2713
Ref: #transactions2836
Node: Postings3401
Ref: #postings3530
Node: Dates4525
Ref: #dates4642
Node: Simple dates4707
Ref: #simple-dates4835
Node: Secondary dates5201
Ref: #secondary-dates5357
Node: Posting dates6920
Ref: #posting-dates7051
Node: Status8425
Ref: #status8549
Node: Account names10263
Ref: #account-names10403
Node: Amounts10890
Ref: #amounts11028
Node: Virtual Postings13129
Ref: #virtual-postings13290
Node: Balance Assertions14510
Ref: #balance-assertions14687
Node: Assertions and ordering15583
Ref: #assertions-and-ordering15771
Node: Assertions and included files16471
Ref: #assertions-and-included-files16714
Node: Assertions and multiple -f options17047
Ref: #assertions-and-multiple--f-options17303
Node: Assertions and commodities17435
Ref: #assertions-and-commodities17672
Node: Assertions and subaccounts18368
Ref: #assertions-and-subaccounts18602
Node: Assertions and virtual postings19123
Ref: #assertions-and-virtual-postings19332
Node: Balance Assignments19474
Ref: #balance-assignments19643
Node: Prices20762
Ref: #prices20897
Node: Transaction prices20948
Ref: #transaction-prices21095
Node: Market prices23251
Ref: #market-prices23388
Node: Comments24348
Ref: #comments24472
Node: Tags25585
Ref: #tags25705
Node: Implicit tags27134
Ref: #implicit-tags27242
Node: Directives27759
Ref: #directives27874
Node: Account aliases28067
Ref: #account-aliases28213
Node: Basic aliases28817
Ref: #basic-aliases28962
Node: Regex aliases29652
Ref: #regex-aliases29822
Node: Multiple aliases30537
Ref: #multiple-aliases30711
Node: end aliases31209
Ref: #end-aliases31351
Node: account directive31452
Ref: #account-directive31634
Node: apply account directive31930
Ref: #apply-account-directive32128
Node: Multi-line comments32787
Ref: #multi-line-comments32979
Node: commodity directive33107
Ref: #commodity-directive33293
Node: Default commodity34165
Ref: #default-commodity34340
Node: Default year34877
Ref: #default-year35044
Node: Including other files35467
Ref: #including-other-files35626
Node: EDITOR SUPPORT36023
Ref: #editor-support36143
Node: Transactions2744
Ref: #transactions2867
Node: Postings3551
Ref: #postings3680
Node: Dates4675
Ref: #dates4792
Node: Simple dates4857
Ref: #simple-dates4985
Node: Secondary dates5351
Ref: #secondary-dates5507
Node: Posting dates7070
Ref: #posting-dates7201
Node: Status8575
Ref: #status8712
Node: Description payee and note10426
Ref: #description-payee-and-note10613
Node: Account names11157
Ref: #account-names11317
Node: Amounts11804
Ref: #amounts11942
Node: Virtual Postings14043
Ref: #virtual-postings14204
Node: Balance Assertions15424
Ref: #balance-assertions15601
Node: Assertions and ordering16497
Ref: #assertions-and-ordering16685
Node: Assertions and included files17385
Ref: #assertions-and-included-files17628
Node: Assertions and multiple -f options17961
Ref: #assertions-and-multiple--f-options18217
Node: Assertions and commodities18349
Ref: #assertions-and-commodities18586
Node: Assertions and subaccounts19282
Ref: #assertions-and-subaccounts19516
Node: Assertions and virtual postings20037
Ref: #assertions-and-virtual-postings20246
Node: Balance Assignments20388
Ref: #balance-assignments20559
Node: Prices21678
Ref: #prices21813
Node: Transaction prices21864
Ref: #transaction-prices22011
Node: Market prices24167
Ref: #market-prices24304
Node: Comments25264
Ref: #comments25388
Node: Tags26501
Ref: #tags26621
Node: Directives28023
Ref: #directives28138
Node: Account aliases28331
Ref: #account-aliases28477
Node: Basic aliases29081
Ref: #basic-aliases29226
Node: Regex aliases29916
Ref: #regex-aliases30086
Node: Multiple aliases30801
Ref: #multiple-aliases30975
Node: end aliases31473
Ref: #end-aliases31615
Node: account directive31716
Ref: #account-directive31898
Node: apply account directive32194
Ref: #apply-account-directive32392
Node: Multi-line comments33051
Ref: #multi-line-comments33243
Node: commodity directive33371
Ref: #commodity-directive33557
Node: Default commodity34429
Ref: #default-commodity34604
Node: Default year35141
Ref: #default-year35308
Node: Including other files35731
Ref: #including-other-files35890
Node: EDITOR SUPPORT36287
Ref: #editor-support36407

End Tag Table

28
hledger-lib/doc/hledger_journal.5.m4.md
View File

@ -75,7 +75,8 @@ This can be followed by any of the following, separated by spaces:
- (optional) a [status](#status) character (empty, `!`, or `*`)
- (optional) a transaction code (any short number or text, enclosed in parentheses)
- (optional) a transaction description (any remaining text until end of line)
- (optional) a transaction description (any remaining text until end of line or a semicolon)
- (optional) a transaction comment (any remaining text following a semicolon until end of line)
Then comes zero or more (but usually at least 2) indented lines representing...
@ -228,6 +229,18 @@ With this scheme, you would use
`-U` 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.
## Description, payee and note
As mentioned, a transaction's description is the rest of the line following the date and status mark
(or, the rest of line until a comment begins).
Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you wish,
or left blank. The description can be queried, unlike [comments](#comments).
Including a `|` (pipe) character in the description will subdivide it
into a payee/payer name (on the left) and additional notes (on the right).
This is entirely optional, but it can allow more precise
[querying](/hledger.html#queries) and [pivoting](/hledger.html#pivoting).
## Account names
Account names typically have several parts separated by a full colon, from
@ -604,19 +617,6 @@ Tags are like Ledger's
[metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are simple strings.
### Implicit tags
Some predefined "implicit" tags are also provided:
- `code` - the transaction's code field
- `description` - the transaction's description
- `payee` - the part of description before `|`, or all of it
- `note` - the part of description after `|`, or all of it
`payee` and `note` support descriptions written in a special `PAYEE | NOTE` format,
accessing the parts before and after the pipe character respectively.
For descriptions not containing a pipe character they are the same as `description`.
## Directives
### Account aliases

325
hledger-lib/doc/hledger_journal.5.txt
View File

@ -68,59 +68,62 @@ FILE FORMAT
parentheses)
o (optional) a transaction description (any remaining text until end of
line)
line or a semicolon)
Then comes zero or more (but usually at least 2) indented lines repre-
o (optional) a transaction comment (any remaining text following a
semicolon until end of line)
Then comes zero or more (but usually at least 2) indented lines repre-
senting...
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
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
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
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
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
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
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: 2010/01/31, 1/31, 2010-01-31,
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: 2010/01/31, 1/31, 2010-01-31,
2010.1.31.
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
want to model this, eg for more accurate balances, you can specify
individual posting dates, which I recommend. Or, you can use the sec-
ondary dates (aka auxiliary/effective dates) feature, supported for
want to model this, eg for more accurate balances, you can specify
individual posting dates, which I recommend. Or, you can use the sec-
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
equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the --date2 flag is speci-
equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the --date2 flag is speci-
fied (--aux-date or --effective also work).
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
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg write the bank's clearing date as primary, and
when needed, the date the transaction was initiated as secondary.
Here's an example. Note that a secondary date will use the year of the
@ -136,18 +139,18 @@ FILE FORMAT
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort; you must use them consistently in
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
ibility, but posting dates are a more powerful and less confusing
alternative.
Posting dates
You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below)
You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below)
like date:DATE. 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
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:
2015/5/30
@ -160,22 +163,22 @@ FILE FORMAT
$ hledger -f t.j register checking
2015/06/01 assets:checking $-10 $-10
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. You can set the secondary date
similarly, with date2:DATE2. The date: or date2: tags must have a
valid simple date value if they are present, eg a date: tag with no
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. You can set the secondary date
similarly, with date2:DATE2. The date: or date2: tags must have a
valid simple date value if they are present, eg a date: tag with no
value is not allowed.
Ledger's earlier, more compact bracketed date syntax is also supported:
[DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
[DATE], [DATE=DATE2] or [=DATE2]. hledger will 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
With this syntax, DATE infers its year from the transaction and DATE2
infers its year from DATE.
Status
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,
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:
@ -185,47 +188,59 @@ FILE FORMAT
! pending
* cleared
When reporting, you can filter by status with the -U/--unmarked,
-P/--pending, and -C/--cleared flags; or the status:, status:!, and
When reporting, you can filter by status with the -U/--unmarked,
-P/--pending, and -C/--cleared flags; or the status:, status:!, and
status:* queries; or the U, P, C keys in hledger-ui.
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
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.
To replicate Ledger and old hledger's behaviour of also matching pend-
To replicate Ledger and old hledger's behaviour of also matching pend-
ing, combine -U and -P.
Status marks are optional, but can be helpful eg for reconciling with
Status marks are optional, but can be helpful eg for reconciling with
real-world accounts. Some editor modes provide highlighting and short-
cuts for working with status. Eg in Emacs ledger-mode, you can toggle
cuts 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.
What "uncleared", "pending", and "cleared" actually mean is up to you.
What "uncleared", "pending", and "cleared" actually mean is up to you.
Here's one suggestion:
status meaning
--------------------------------------------------------------------------
uncleared recorded but not yet reconciled; needs review
pending tentatively reconciled (if needed, eg during a big recon-
pending tentatively reconciled (if needed, eg during a big recon-
ciliation)
cleared complete, reconciled as far as possible, and considered
cleared complete, reconciled as far as possible, and considered
correct
With this scheme, you would use -PC to see the current balance at your
bank, -U to see things which will probably hit your bank soon (like
With this scheme, you would use -PC to see the current balance at your
bank, -U 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.
Account names
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: assets, liabilities, income, expenses, and equity.
Description, payee and note
As mentioned, a transaction's description is the rest of the line fol-
lowing the date and status mark (or, the rest of line until a comment
begins). Sometimes called the "narration" in traditional bookkeeping,
it can be used for whatever you wish, or left blank. The description
can be queried, unlike comments.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
Including a | (pipe) character in the description will subdivide it
into a payee/payer name (on the left) and additional notes (on the
right). This is entirely optional, but it can allow more precise
querying and pivoting.
Account names
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: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
spaces (or newline).
Account names can be aliased.
@ -234,7 +249,7 @@ FILE FORMAT
After the account name, there is usually an amount. Important: between
account name and amount, there must be two or more spaces.
Amounts consist of a number and (usually) a currency symbol or commod-
Amounts consist of a number and (usually) a currency symbol or commod-
ity name. Some examples:
2.00001
@ -247,53 +262,53 @@ FILE FORMAT
As you can see, the amount format is somewhat flexible:
o amounts are a number (the "quantity") and optionally a currency sym-
o amounts are a number (the "quantity") and optionally a currency sym-
bol/commodity name (the "commodity").
o the commodity is a symbol, word, or phrase, on the left or right,
with or without a separating space. If the commodity contains num-
bers, spaces or non-word punctuation it must be enclosed in double
o the commodity is a symbol, word, or phrase, on the left or right,
with or without a separating space. If the commodity contains num-
bers, spaces or non-word punctuation it must be enclosed in double
quotes.
o negative amounts with a commodity on the left can have the minus sign
before or after it
o digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods
o digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods
(in which case comma is used for decimal point)
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
o if there is a commodity directive specifying the format, that is used
o otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of decimal
o 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 commmod-
ity
o or if there are no such amounts in the journal, a default format is
o or if there are no such amounts in the journal, a default format is
used (like $1000.00).
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount,
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount,
or when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, set the desired
when -V is used.) If you find this causing problems, set the desired
format with a commodity directive.
Virtual Postings
When you parenthesise the account name in a posting, we call that a
When you parenthesise the account name in a posting, we call that a
virtual posting, which means:
o it is ignored when checking that the transaction is balanced
o it is excluded from reports when the --real/-R flag is used, or the
o it is excluded from reports when the --real/-R flag is used, or the
real:1 query.
You could use this, eg, to set an account's opening balance without
You could use this, eg, to set an account's opening balance without
needing to use the equity:opening balances account:
1/1 special unbalanced posting to set initial balance
@ -301,8 +316,8 @@ FILE FORMAT
When the account name is bracketed, we call it a balanced virtual post-
ing. This is like an ordinary virtual posting except the balanced vir-
tual postings in a transaction must balance to 0, like the real post-
ings (but separately from them). Balanced virtual postings are also
tual postings in a transaction must balance to 0, like the real post-
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
@ -312,13 +327,13 @@ FILE FORMAT
[assets:checking:budget:food] $-10
Virtual postings have some legitimate uses, but those are few. You can
usually find an equivalent journal entry using real postings, which is
usually find an equivalent journal entry using real postings, which is
more correct and provides better error checking.
Balance Assertions
hledger supports Ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b
hledger supports Ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b
after each posting:
2013/1/1
@ -330,31 +345,31 @@ FILE FORMAT
b $-1 =$-2
After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
--ignore-assertions flag, which can be useful for troubleshooting or
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files.
Assertions and ordering
hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif-
hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif-
ferent from Ledger, which sorts assertions only by parse order. (Also,
Ledger assertions do not see the accumulated effect of repeated post-
Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differ-
ently-dated transactions within the journal. But if you reorder
So, hledger balance assertions keep working if you reorder differ-
ently-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 con-
updating. This order dependence does bring an advantage: precise con-
trol over the order of postings and assertions within a day, so you can
assert intra-day balances.
Assertions and included files
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same
day, you'll have to put the assertion in the right file.
Assertions and multiple -f options
@ -362,21 +377,21 @@ FILE FORMAT
-f options. Use include or concatenate the files instead.
Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a par-
tial balance assertion. This is compatible with Ledger, and makes it
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a par-
tial balance assertion. This is compatible with Ledger, and makes it
possible to make assertions about accounts containing multiple commodi-
ties.
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)
Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they
Balance assertions do not count the balance from subaccounts; they
check the posted account's exclusive balance. For example:
1/1
@ -384,7 +399,7 @@ FILE FORMAT
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
equity
The balance report's flat mode shows these exclusive balances more
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
@ -398,10 +413,10 @@ FILE FORMAT
tual. They are not affected by the --real/-R flag or real: query.
Balance Assignments
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
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:
; starting a new journal, set asset account balances
@ -419,8 +434,8 @@ FILE FORMAT
expenses:misc
The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
ment). 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.
@ -428,12 +443,12 @@ FILE FORMAT
Prices
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
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.
Transaction prices are fixed, and do not change over time. (Ledger
users: Ledger uses a different syntax for fixed prices, {=UNITPRICE},
Transaction prices are fixed, and do not change over time. (Ledger
users: Ledger uses a different syntax for fixed prices, {=UNITPRICE},
which hledger currently ignores).
There are several ways to record a transaction price:
@ -457,9 +472,9 @@ FILE FORMAT
assets:euros 100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
Amounts with transaction prices can be displayed in the transaction
Amounts with transaction prices can be displayed in the transaction
price's commodity by using the -B/--cost flag (except for #551) ("B" is
from "cost Basis"). Eg for the above, here is how -B affects the bal-
from "cost Basis"). Eg for the above, here is how -B affects the bal-
ance report:
$ hledger bal -N --flat
@ -469,8 +484,8 @@ FILE FORMAT
$-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
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:
@ -483,41 +498,41 @@ FILE FORMAT
100 assets:euros
Market prices
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. (Ledger calls them
historical prices.) For example, the prices published by a stock
exchange or the foreign exchange market. hledger can use these prices
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. (Ledger calls them
historical prices.) For example, the prices published by a stock
exchange or the foreign exchange market. hledger can use these prices
to show the market value of things at a given date, see market value.
To record market prices, use P directives in the main journal or in an
To record market prices, use P directives in the main journal or in an
included file. Their format is:
P DATE COMMODITYBEINGPRICED UNITPRICE
DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of
the commodity being priced. UNITPRICE is an ordinary amount (symbol
and quantity) in a second commodity, specifying the unit price or con-
version rate for the first commodity in terms of the second, on the
DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of
the commodity being priced. UNITPRICE is an ordinary amount (symbol
and quantity) in a second commodity, specifying the unit price or con-
version rate for the first commodity in terms of the second, on the
given date.
For example, the following directives say that one euro was worth 1.35
For example, the following directives say that one euro was worth 1.35
US dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35
P 2010/1/1 $1.40
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
to the end of the file.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Some examples:
@ -542,20 +557,20 @@ FILE FORMAT
; a journal comment (because not indented)
Tags
Tags are a way to add extra labels or labelled data to postings and
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
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
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-
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:
@ -569,34 +584,18 @@ FILE FORMAT
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,
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
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Implicit tags
Some predefined "implicit" tags are also provided:
o code - the transaction's code field
o description - the transaction's description
o payee - the part of description before |, or all of it
o note - the part of description after |, or all of it
payee and note support descriptions written in a special PAYEE | NOTE
format, accessing the parts before and after the pipe character respec-
tively. For descriptions not containing a pipe character they are the
same as description.
Directives
Account aliases
You can define aliases which rewrite your account names (after reading
@ -809,8 +808,6 @@ 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-

4
hledger-ui/doc/hledger-ui.1
View File

@ -88,8 +88,8 @@ anonymize accounts and payees
.RS
.RE
.TP
.B \f[C]\-\-pivot\ TAGNAME\f[]
use some other field/tag for account names
.B \f[C]\-\-pivot\ FIELDNAME\f[]
use some other field or tag for the account name
.RS
.RE
.TP

28
hledger-ui/doc/hledger-ui.1.info
View File

@ -67,9 +67,9 @@ the data.
'--anon'
anonymize accounts and payees
'--pivot TAGNAME'
'--pivot FIELDNAME'
use some other field/tag for account names
use some other field or tag for the account name
'-I --ignore-assertions'
ignore any failing balance assertions
@ -358,17 +358,17 @@ Tag Table:
Node: Top73
Node: OPTIONS831
Ref: #options930
Node: KEYS3479
Ref: #keys3576
Node: SCREENS6372
Ref: #screens6459
Node: Accounts screen6549
Ref: #accounts-screen6679
Node: Register screen8909
Ref: #register-screen9066
Node: Transaction screen11140
Ref: #transaction-screen11300
Node: Error screen12170
Ref: #error-screen12294
Node: KEYS3487
Ref: #keys3584
Node: SCREENS6380
Ref: #screens6467
Node: Accounts screen6557
Ref: #accounts-screen6687
Node: Register screen8917
Ref: #register-screen9074
Node: Transaction screen11148
Ref: #transaction-screen11308
Node: Error screen12178
Ref: #error-screen12302

End Tag Table

4
hledger-ui/doc/hledger-ui.1.txt
View File

@ -65,8 +65,8 @@ OPTIONS
--anon anonymize accounts and payees
--pivot TAGNAME
use some other field/tag for account names
--pivot FIELDNAME
use some other field or tag for the account name
-I --ignore-assertions
ignore any failing balance assertions

4
hledger-web/doc/hledger-web.1
View File

@ -144,8 +144,8 @@ anonymize accounts and payees
.RS
.RE
.TP
.B \f[C]\-\-pivot\ TAGNAME\f[]
use some other field/tag for account names
.B \f[C]\-\-pivot\ FIELDNAME\f[]
use some other field or tag for the account name
.RS
.RE
.TP

4
hledger-web/doc/hledger-web.1.info
View File

@ -112,9 +112,9 @@ options as shown above.
'--anon'
anonymize accounts and payees
'--pivot TAGNAME'
'--pivot FIELDNAME'
use some other field/tag for account names
use some other field or tag for the account name
'-I --ignore-assertions'
ignore any failing balance assertions

4
hledger-web/doc/hledger-web.1.txt
View File

@ -110,8 +110,8 @@ OPTIONS
--anon anonymize accounts and payees
--pivot TAGNAME
use some other field/tag for account names
--pivot FIELDNAME
use some other field or tag for the account name
-I --ignore-assertions
ignore any failing balance assertions

36
hledger/doc/hledger.1
View File

@ -199,8 +199,8 @@ anonymize accounts and payees
.RS
.RE
.TP
.B \f[C]\-\-pivot\ TAGNAME\f[]
use some other field/tag for account names
.B \f[C]\-\-pivot\ FIELDNAME\f[]
use some other field or tag for the account name
.RS
.RE
.TP
@ -750,21 +750,17 @@ Use this when you want a summary with less detail.
.PP
Normally hledger sums amounts, and organizes them in a hierarchy, based
on account name.
The \f[C]\-\-pivot\ TAGNAME\f[] option causes it to sum and organize
hierarchy based on some other field instead.
.PP
TAGNAME is the full, case\-insensitive name of a tag you have defined,
or one of the built\-in implicit tags (like \f[C]code\f[] or
\f[C]payee\f[]).
As with account names, when tag values have
\f[C]multiple:colon\-separated:parts\f[] hledger will build hierarchy,
displayed in tree\-mode reports, summarisable with a depth limit, and so
on.
The \f[C]\-\-pivot\ FIELD\f[] option causes it to sum and organize
hierarchy based on the value of some other field instead.
FIELD can be: \f[C]code\f[], \f[C]description\f[], \f[C]payee\f[],
\f[C]note\f[], or the full name (case insensitive) of any tag.
As with account names, values containing \f[C]colon:separated:parts\f[]
will be displayed hierarchically in reports.
.PP
\f[C]\-\-pivot\f[] is a general option affecting all reports; you can
think of hledger transforming the journal before any other processing,
replacing every posting\[aq]s account name with the value of the
specified tag on that posting, inheriting it from the transaction or
specified field on that posting, inheriting it from the transaction or
using a blank value if it\[aq]s not present.
.PP
An example:
@ -1007,7 +1003,7 @@ quoting to hide it from the shell, so eg do:
.RE
.TP
.B \f[B]\f[C]desc:REGEX\f[]\f[]
match transaction descriptions
match transaction descriptions.
.RS
.RE
.TP
@ -1031,6 +1027,18 @@ match (or display, depending on command) accounts at or above this depth
.RS
.RE
.TP
.B \f[B]\f[C]note:REGEX\f[]\f[]
match transaction notes (part of description right of \f[C]|\f[], or
whole description when there\[aq]s no \f[C]|\f[])
.RS
.RE
.TP
.B \f[B]\f[C]payee:REGEX\f[]\f[]
match transaction payee/payer names (part of description left of
\f[C]|\f[], or whole description when there\[aq]s no \f[C]|\f[])
.RS
.RE
.TP
.B \f[B]\f[C]real:,\ real:0\f[]\f[]
match real or virtual postings respectively
.RS

269
hledger/doc/hledger.1.info
View File

@ -167,9 +167,9 @@ different, like git.)
'--anon'
anonymize accounts and payees
'--pivot TAGNAME'
'--pivot FIELDNAME'
use some other field/tag for account names
use some other field or tag for the account name
'-I --ignore-assertions'
ignore any failing balance assertions
@ -507,20 +507,17 @@ File: hledger.1.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up:
=============
Normally hledger sums amounts, and organizes them in a hierarchy, based
on account name. The '--pivot TAGNAME' option causes it to sum and
organize hierarchy based on some other field instead.
TAGNAME is the full, case-insensitive name of a tag you have defined,
or one of the built-in implicit tags (like 'code' or 'payee'). As with
account names, when tag values have 'multiple:colon-separated:parts'
hledger will build hierarchy, displayed in tree-mode reports,
summarisable with a depth limit, and so on.
on account name. The '--pivot FIELD' option causes it to sum and
organize hierarchy based on the value of some other field instead.
FIELD can be: 'code', 'description', 'payee', 'note', or the full name
(case insensitive) of any tag. As with account names, values containing
'colon:separated:parts' will be displayed hierarchically in reports.
'--pivot' is a general option affecting all reports; you can think of
hledger transforming the journal before any other processing, replacing
every posting's account name with the value of the specified tag on that
posting, inheriting it from the transaction or using a blank value if
it's not present.
every posting's account name with the value of the specified field on
that posting, inheriting it from the transaction or using a blank value
if it's not present.
An example:
@ -717,7 +714,7 @@ match (or negatively match)
print cur:'\$'' or 'hledger print cur:\\$'.
*'desc:REGEX'*
match transaction descriptions
match transaction descriptions.
*'date:PERIODEXPR'*
match dates within the specified period. PERIODEXPR is a period
@ -732,6 +729,14 @@ match (or negatively match)
match (or display, depending on command) accounts at or above this
depth
*'note:REGEX'*
match transaction notes (part of description right of '|', or whole
description when there's no '|')
*'payee:REGEX'*
match transaction payee/payer names (part of description left of
'|', or whole description when there's no '|')
*'real:, real:0'*
match real or virtual postings respectively
@ -2129,123 +2134,123 @@ Node: OPTIONS3640
Ref: #options3744
Node: General options4025
Ref: #general-options4152
Node: Command options6498
Ref: #command-options6651
Node: Command arguments7049
Ref: #command-arguments7209
Node: Special characters7330
Ref: #special-characters7488
Node: Input files8656
Ref: #input-files8794
Node: Smart dates10757
Ref: #smart-dates10900
Node: Report start & end date11879
Ref: #report-start-end-date12051
Node: Report intervals13117
Ref: #report-intervals13282
Node: Period expressions13683
Ref: #period-expressions13843
Node: Depth limiting16183
Ref: #depth-limiting16329
Node: Pivoting16530
Ref: #pivoting16650
Node: Cost18421
Ref: #cost18531
Node: Market value18649
Ref: #market-value18786
Node: Regular expressions20086
Ref: #regular-expressions20224
Node: QUERIES21585
Ref: #queries21689
Node: COMMANDS25354
Ref: #commands25468
Node: accounts26147
Ref: #accounts26247
Node: activity27229
Ref: #activity27341
Node: add27700
Ref: #add27801
Node: balance30459
Ref: #balance30572
Node: Flat mode33587
Ref: #flat-mode33714
Node: Depth limited balance reports34134
Ref: #depth-limited-balance-reports34337
Node: Multicolumn balance reports34757
Ref: #multicolumn-balance-reports34968
Node: Custom balance output39616
Ref: #custom-balance-output39800
Node: Colour support41893
Ref: #colour-support42054
Node: Output destination42227
Ref: #output-destination42385
Node: CSV output42655
Ref: #csv-output42774
Node: balancesheet43171
Ref: #balancesheet43309
Node: balancesheetequity45216
Ref: #balancesheetequity45367
Node: cashflow46156
Ref: #cashflow46279
Node: help48130
Ref: #help48242
Node: incomestatement49316
Ref: #incomestatement49447
Node: print51339
Ref: #print51456
Node: register55212
Ref: #register55325
Node: Custom register output59821
Ref: #custom-register-output59952
Node: stats61249
Ref: #stats61355
Node: test62236
Ref: #test62323
Node: ADD-ON COMMANDS62691
Ref: #add-on-commands62803
Node: Official add-ons64090
Ref: #official-add-ons64232
Node: api64319
Ref: #api64410
Node: ui64462
Ref: #ui64563
Node: web64621
Ref: #web64712
Node: Third party add-ons64758
Ref: #third-party-add-ons64935
Node: diff65070
Ref: #diff65169
Node: iadd65268
Ref: #iadd65384
Node: interest65467
Ref: #interest65590
Node: irr65685
Ref: #irr65785
Node: Experimental add-ons65863
Ref: #experimental-add-ons66017
Node: autosync66419
Ref: #autosync66533
Node: budget66772
Ref: #budget66896
Node: chart66962
Ref: #chart67081
Node: check67152
Ref: #check67276
Node: check-dates67343
Ref: #check-dates67485
Node: check-dupes67558
Ref: #check-dupes67701
Node: equity67778
Ref: #equity67906
Node: prices68025
Ref: #prices68154
Node: print-unique68209
Ref: #print-unique68358
Node: register-match68451
Ref: #register-match68607
Node: rewrite68705
Ref: #rewrite68839
Node: tags68917
Ref: #tags69022
Node: Command options6506
Ref: #command-options6659
Node: Command arguments7057
Ref: #command-arguments7217
Node: Special characters7338
Ref: #special-characters7496
Node: Input files8664
Ref: #input-files8802
Node: Smart dates10765
Ref: #smart-dates10908
Node: Report start & end date11887
Ref: #report-start-end-date12059
Node: Report intervals13125
Ref: #report-intervals13290
Node: Period expressions13691
Ref: #period-expressions13851
Node: Depth limiting16191
Ref: #depth-limiting16337
Node: Pivoting16538
Ref: #pivoting16658
Node: Cost18334
Ref: #cost18444
Node: Market value18562
Ref: #market-value18699
Node: Regular expressions19999
Ref: #regular-expressions20137
Node: QUERIES21498
Ref: #queries21602
Node: COMMANDS25534
Ref: #commands25648
Node: accounts26327
Ref: #accounts26427
Node: activity27409
Ref: #activity27521
Node: add27880
Ref: #add27981
Node: balance30639
Ref: #balance30752
Node: Flat mode33767
Ref: #flat-mode33894
Node: Depth limited balance reports34314
Ref: #depth-limited-balance-reports34517
Node: Multicolumn balance reports34937
Ref: #multicolumn-balance-reports35148
Node: Custom balance output39796
Ref: #custom-balance-output39980
Node: Colour support42073
Ref: #colour-support42234
Node: Output destination42407
Ref: #output-destination42565
Node: CSV output42835
Ref: #csv-output42954
Node: balancesheet43351
Ref: #balancesheet43489
Node: balancesheetequity45396
Ref: #balancesheetequity45547
Node: cashflow46336
Ref: #cashflow46459
Node: help48310
Ref: #help48422
Node: incomestatement49496
Ref: #incomestatement49627
Node: print51519
Ref: #print51636
Node: register55392
Ref: #register55505
Node: Custom register output60001
Ref: #custom-register-output60132
Node: stats61429
Ref: #stats61535
Node: test62416
Ref: #test62503
Node: ADD-ON COMMANDS62871
Ref: #add-on-commands62983
Node: Official add-ons64270
Ref: #official-add-ons64412
Node: api64499
Ref: #api64590
Node: ui64642
Ref: #ui64743
Node: web64801
Ref: #web64892
Node: Third party add-ons64938
Ref: #third-party-add-ons65115
Node: diff65250
Ref: #diff65349
Node: iadd65448
Ref: #iadd65564
Node: interest65647
Ref: #interest65770
Node: irr65865
Ref: #irr65965
Node: Experimental add-ons66043
Ref: #experimental-add-ons66197
Node: autosync66599
Ref: #autosync66713
Node: budget66952
Ref: #budget67076
Node: chart67142
Ref: #chart67261
Node: check67332
Ref: #check67456
Node: check-dates67523
Ref: #check-dates67665
Node: check-dupes67738
Ref: #check-dupes67881
Node: equity67958
Ref: #equity68086
Node: prices68205
Ref: #prices68334
Node: print-unique68389
Ref: #print-unique68538
Node: register-match68631
Ref: #register-match68787
Node: rewrite68885
Ref: #rewrite69019
Node: tags69097
Ref: #tags69202

End Tag Table

457
hledger/doc/hledger.1.txt
View File

File diff suppressed because it is too large Load Diff

13
hledger/doc/options.m4.md
View File

@ -265,16 +265,15 @@ tree, down to level N. Use this when you want a summary with less detail.
## Pivoting
Normally hledger sums amounts, and organizes them in a hierarchy, based on account name.
The `--pivot TAGNAME` option causes it to sum and organize hierarchy based on some other field instead.
TAGNAME is the full, case-insensitive name of a [tag](/journal.html#tags) you have defined,
or one of the built-in implicit tags (like `code` or `payee`).
As with account names, when tag values have `multiple:colon-separated:parts` hledger will build hierarchy,
displayed in tree-mode reports, summarisable with a depth limit, and so on.
The `--pivot FIELD` option causes it to sum and organize hierarchy based on the value of some other field instead.
FIELD can be:
`code`, `description`, `payee`, `note`,
or the full name (case insensitive) of any [tag](/journal.html#tags).
As with account names, values containing `colon:separated:parts` will be displayed hierarchically in reports.
`--pivot` is a general option affecting all reports; you can think of hledger transforming
the journal before any other processing, replacing every posting's account name with
the value of the specified tag on that posting, inheriting it from the transaction
the value of the specified field on that posting, inheriting it from the transaction
or using a blank value if it's not present.
An example:

10
hledger/doc/queries.m4.md
View File

@ -54,7 +54,7 @@ quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
or `hledger print cur:\\$`.
**`desc:REGEX`**
: match transaction descriptions
: match transaction [descriptions](/manual.html#description-payee-and-note).
**`date:PERIODEXPR`**
: match dates within the specified period.
@ -68,6 +68,14 @@ If the `--date2` command line flag is present, this matches [secondary dates](ma
**`depth:N`**
: match (or display, depending on command) accounts at or above this depth
**`note:REGEX`**
: match transaction [notes](/manual.html#description-payee-and-note)
(part of description right of `|`, or whole description when there's no `|`)
**`payee:REGEX`**
: match transaction [payee/payer names](/manual.html#description-payee-and-note)
(part of description left of `|`, or whole description when there's no `|`)
**`real:, real:0`**
: match real or virtual postings respectively