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

;regen manuals

Browse Source
This commit is contained in:
Simon Michael 2020-07-07 13:42:11 -07:00
parent 3ad313d8fa
commit ae4fce8077
6 changed files with 661 additions and 444 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
hledger-lib/hledger_csv.5
View File

@ -674,7 +674,18 @@ number, like \f[C]%date\f[R] or \f[C]%1\f[R].
.PP
A single matcher can be written on the same line as the \[dq]if\[dq]; or
multiple matchers can be written on the following lines, non-indented.
Multiple matchers are OR\[aq]d (any one of them can match).
Multiple matchers are OR\[aq]d (any one of them can match), unless one
begins with an \f[C]&\f[R] symbol, in which case it is AND\[aq]ed with
the previous matcher.
.IP
.nf
\f[C]
if
MATCHER
& MATCHER
RULE
\f[R]
.fi
.PP
After the patterns there should be one or more rules to apply, all
indented by at least one space.

77
hledger-lib/hledger_csv.info
View File

@ -642,7 +642,14 @@ is a percent sign followed by the field's name or column number, like
A single matcher can be written on the same line as the "if"; or
multiple matchers can be written on the following lines, non-indented.
Multiple matchers are OR'd (any one of them can match).
Multiple matchers are OR'd (any one of them can match), unless one
begins with an '&' symbol, in which case it is AND'ed with the previous
matcher.
if
MATCHER
& MATCHER
RULE
After the patterns there should be one or more rules to apply, all
indented by at least one space. Three kinds of rule are allowed in
@ -1141,40 +1148,40 @@ Node: separator21340
Ref: #separator21475
Node: if block21886
Ref: #if-block22011
Node: if table24167
Ref: #if-table24286
Node: end26024
Ref: #end26136
Node: date-format26360
Ref: #date-format26492
Node: newest-first27241
Ref: #newest-first27379
Node: include28062
Ref: #include28193
Node: balance-type28637
Ref: #balance-type28757
Node: TIPS29457
Ref: #tips29539
Node: Rapid feedback29795
Ref: #rapid-feedback29912
Node: Valid CSV30372
Ref: #valid-csv30502
Node: File Extension30694
Ref: #file-extension30846
Node: Reading multiple CSV files31256
Ref: #reading-multiple-csv-files31441
Node: Valid transactions31682
Ref: #valid-transactions31860
Node: Deduplicating importing32488
Ref: #deduplicating-importing32667
Node: Setting amounts33700
Ref: #setting-amounts33869
Node: Setting currency/commodity34856
Ref: #setting-currencycommodity35048
Node: Referencing other fields35851
Ref: #referencing-other-fields36051
Node: How CSV rules are evaluated36948
Ref: #how-csv-rules-are-evaluated37121
Node: if table24287
Ref: #if-table24406
Node: end26144
Ref: #end26256
Node: date-format26480
Ref: #date-format26612
Node: newest-first27361
Ref: #newest-first27499
Node: include28182
Ref: #include28313
Node: balance-type28757
Ref: #balance-type28877
Node: TIPS29577
Ref: #tips29659
Node: Rapid feedback29915
Ref: #rapid-feedback30032
Node: Valid CSV30492
Ref: #valid-csv30622
Node: File Extension30814
Ref: #file-extension30966
Node: Reading multiple CSV files31376
Ref: #reading-multiple-csv-files31561
Node: Valid transactions31802
Ref: #valid-transactions31980
Node: Deduplicating importing32608
Ref: #deduplicating-importing32787
Node: Setting amounts33820
Ref: #setting-amounts33989
Node: Setting currency/commodity34976
Ref: #setting-currencycommodity35168
Node: Referencing other fields35971
Ref: #referencing-other-fields36171
Node: How CSV rules are evaluated37068
Ref: #how-csv-rules-are-evaluated37241

End Tag Table

170
hledger-lib/hledger_csv.txt
View File

@ -506,10 +506,16 @@ CSV RULES
A single matcher can be written on the same line as the "if"; or multi-
ple matchers can be written on the following lines, non-indented. Mul-
tiple matchers are OR'd (any one of them can match).
tiple matchers are OR'd (any one of them can match), unless one begins
with an & symbol, in which case it is AND'ed with the previous matcher.
After the patterns there should be one or more rules to apply, all in-
dented by at least one space. Three kinds of rule are allowed in con-
if
MATCHER
& MATCHER
RULE
After the patterns there should be one or more rules to apply, all in-
dented by at least one space. Three kinds of rule are allowed in con-
ditional blocks:
o field assignments (to set a hledger field)
@ -539,11 +545,11 @@ CSV RULES
MATCHER3,VALUE31,VALUE32,...,VALUE3n
<empty line>
Conditional tables ("if tables") are a different syntax to specify
field assignments that will be applied only to CSV records which match
Conditional tables ("if tables") are a different syntax to specify
field assignments that will be applied only to CSV records which match
certain patterns.
MATCHER could be either field or record matcher, as described above.
MATCHER could be either field or record matcher, as described above.
When MATCHER matches, values from that row would be assigned to the CSV
fields named on the if line, in the same order.
@ -567,17 +573,17 @@ CSV RULES
...
CSVFIELDNAMEn VALUE3n
Each line starting with MATCHER should contain enough (possibly empty)
Each line starting with MATCHER should contain enough (possibly empty)
values for all the listed fields.
Rules would be checked and applied in the order they are listed in the
Rules would be checked and applied in the order they are listed in the
table and, like with if blocks, later rules (in the same or another ta-
ble) or if blocks could override the effect of any rule.
Instead of ',' you can use a variety of other non-alphanumeric charac-
Instead of ',' you can use a variety of other non-alphanumeric charac-
ters as a separator. First character after if is taken to be the sepa-
rator for the rest of the table. It is the responsibility of the user
to ensure that separator does not occur inside MATCHERs and values -
rator for the rest of the table. It is the responsibility of the user
to ensure that separator does not occur inside MATCHERs and values -
there is no way to escape separator.
Example:
@ -588,7 +594,7 @@ CSV RULES
2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
end
This rule can be used inside if blocks (only), to make hledger stop
This rule can be used inside if blocks (only), to make hledger stop
reading this CSV file and move on to the next input file, or to command
execution. Eg:
@ -599,10 +605,10 @@ CSV RULES
date-format
date-format DATEFMT
This is a helper for the date (and date2) fields. If your CSV dates
are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
need to add a date-format rule describing them with a strptime date
parsing pattern, which must parse the CSV date value completely. Some
This is a helper for the date (and date2) fields. If your CSV dates
are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
need to add a date-format rule describing them with a strptime date
parsing pattern, which must parse the CSV date value completely. Some
examples:
# MM/DD/YY
@ -624,15 +630,15 @@ CSV RULES
mat.html#v:formatTime
newest-first
hledger always sorts the generated transactions by date. Transactions
on the same date should appear in the same order as their CSV records,
as hledger can usually auto-detect whether the CSV's normal order is
hledger always sorts the generated transactions by date. Transactions
on the same date should appear in the same order as their CSV records,
as hledger can usually auto-detect whether the CSV's normal order is
oldest first or newest first. But if all of the following are true:
o the CSV might sometimes contain just one day of data (all records
o the CSV might sometimes contain just one day of data (all records
having the same date)
o the CSV records are normally in reverse chronological order (newest
o the CSV records are normally in reverse chronological order (newest
at the top)
o and you care about preserving the order of same-day transactions
@ -645,9 +651,9 @@ CSV RULES
include
include RULESFILE
This includes the contents of another CSV rules file at this point.
RULESFILE is an absolute file path or a path relative to the current
file's directory. This can be useful for sharing common rules between
This includes the contents of another CSV rules file at this point.
RULESFILE is an absolute file path or a path relative to the current
file's directory. This can be useful for sharing common rules between
several rules files, eg:
# someaccount.csv.rules
@ -662,10 +668,10 @@ CSV RULES
balance-type
Balance assertions generated by assigning to balanceN are of the simple
= type by default, which is a single-commodity, subaccount-excluding
= type by default, which is a single-commodity, subaccount-excluding
assertion. You may find the subaccount-including variants more useful,
eg if you have created some virtual subaccounts of checking to help
with budgeting. You can select a different type of assertion with the
eg if you have created some virtual subaccounts of checking to help
with budgeting. You can select a different type of assertion with the
balance-type rule:
# balance assertions will consider all commodities and all subaccounts
@ -680,19 +686,19 @@ CSV RULES
TIPS
Rapid feedback
It's a good idea to get rapid feedback while creating/troubleshooting
It's a good idea to get rapid feedback while creating/troubleshooting
CSV rules. Here's a good way, using entr from http://eradman.com/entr-
project :
$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
A desc: query (eg) is used to select just one, or a few, transactions
of interest. "bash -c" is used to run multiple commands, so we can
echo a separator each time the command re-runs, making it easier to
A desc: query (eg) is used to select just one, or a few, transactions
of interest. "bash -c" is used to run multiple commands, so we can
echo a separator each time the command re-runs, making it easier to
read the output.
Valid CSV
hledger accepts CSV conforming to RFC 4180. When CSV values are en-
hledger accepts CSV conforming to RFC 4180. When CSV values are en-
closed in quotes, note:
o they must be double quotes (not single quotes)
@ -700,9 +706,9 @@ TIPS
o spaces outside the quotes are not allowed
File Extension
CSV ("Character Separated Values") files should be named with one of
these filename extensions: .csv, .ssv, .tsv. Or, the file path should
be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify
CSV ("Character Separated Values") files should be named with one of
these filename extensions: .csv, .ssv, .tsv. Or, the file path should
be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify
the format and show the right error messages. For example:
$ hledger -f foo.ssv print
@ -714,44 +720,44 @@ TIPS
More about this: Input files in the hledger manual.
Reading multiple CSV files
If you use multiple -f options to read multiple CSV files at once,
hledger will look for a correspondingly-named rules file for each CSV
file. But if you use the --rules-file option, that rules file will be
If you use multiple -f options to read multiple CSV files at once,
hledger will look for a correspondingly-named rules file for each CSV
file. But if you use the --rules-file option, that rules file will be
used for all the CSV files.
Valid transactions
After reading a CSV file, hledger post-processes and validates the gen-
erated journal entries as it would for a journal file - balancing them,
applying balance assignments, and canonicalising amount styles. Any
errors at this stage will be reported in the usual way, displaying the
applying balance assignments, and canonicalising amount styles. Any
errors at this stage will be reported in the usual way, displaying the
problem entry.
There is one exception: balance assertions, if you have generated them,
will not be checked, since normally these will work only when the CSV
data is part of the main journal. If you do need to check balance as-
will not be checked, since normally these will work only when the CSV
data is part of the main journal. If you do need to check balance as-
sertions generated from CSV right away, pipe into another hledger:
$ hledger -f file.csv print | hledger -f- print
Deduplicating, importing
When you download a CSV file periodically, eg to get your latest bank
transactions, the new file may overlap with the old one, containing
When you download a CSV file periodically, eg to get your latest bank
transactions, the new file may overlap with the old one, containing
some of the same records.
The import command will (a) detect the new transactions, and (b) append
just those transactions to your main journal. It is idempotent, so you
don't have to remember how many times you ran it or with which version
of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
don't have to remember how many times you ran it or with which version
of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
is the easiest way to import CSV data. Eg:
# download the latest CSV files, then run this command.
# Note, no -f flags needed here.
$ hledger import *.csv [--dry]
This method works for most CSV files. (Where records have a stable
This method works for most CSV files. (Where records have a stable
chronological order, and new records appear only at the new end.)
A number of other tools and workflows, hledger-specific and otherwise,
A number of other tools and workflows, hledger-specific and otherwise,
exist for converting, deduplicating, classifying and managing CSV data.
See:
@ -762,43 +768,43 @@ TIPS
Setting amounts
A posting amount can be set in one of these ways:
o by assigning (with a fields list or field assignment) to amountN
o by assigning (with a fields list or field assignment) to amountN
(posting N's amount) or amount (posting 1's amount)
o by assigning to amountN-in and amountN-out (or amount-in and amount-
out). For each CSV record, whichever of these has a non-zero value
will be used, with appropriate sign. If both contain a non-zero
o by assigning to amountN-in and amountN-out (or amount-in and amount-
out). For each CSV record, whichever of these has a non-zero value
will be used, with appropriate sign. If both contain a non-zero
value, this may not work.
o by assigning to balanceN (or balance) instead of the above, setting
the amount indirectly via a balance assignment. If you do this the
o by assigning to balanceN (or balance) instead of the above, setting
the amount indirectly via a balance assignment. If you do this the
default account name may be wrong, so you should set that explicitly.
There is some special handling for an amount's sign:
o If an amount value is parenthesised, it will be de-parenthesised and
o If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped.
o If an amount value begins with a double minus sign, those cancel out
o If an amount value begins with a double minus sign, those cancel out
and are removed.
o If an amount value begins with a plus sign, that will be removed
Setting currency/commodity
If the currency/commodity symbol is included in the CSV's amount
If the currency/commodity symbol is included in the CSV's amount
field(s), you don't have to do anything special.
If the currency is provided as a separate CSV field, you can either:
o assign that to currency, which adds it to all posting amounts. The
symbol will prepended to the amount quantity (on the left side). If
you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
o assign that to currency, which adds it to all posting amounts. The
symbol will prepended to the amount quantity (on the left side). If
you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
stripping).
o or assign it to currencyN which adds it to posting N's amount only.
o or for more control, construct the amount from symbol and quantity
o or for more control, construct the amount from symbol and quantity
using field assignment, eg:
fields date,description,currency,quantity
@ -806,9 +812,9 @@ TIPS
amount %quantity %currency
Referencing other fields
In field assignments, you can interpolate only CSV fields, not hledger
fields. In the example below, there's both a CSV field and a hledger
field named amount1, but %amount1 always means the CSV field, not the
In field assignments, you can interpolate only CSV fields, not hledger
fields. In the example below, there's both a CSV field and a hledger
field named amount1, but %amount1 always means the CSV field, not the
hledger field:
# Name the third CSV field "amount1"
@ -820,7 +826,7 @@ TIPS
# Set comment to the CSV amount1 (not the amount1 assigned above)
comment %amount1
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
eral "amount1":
fields date,description,csvamount
@ -828,7 +834,7 @@ TIPS
# Can't interpolate amount1 here
comment %amount1
When there are multiple field assignments to the same hledger field,
When there are multiple field assignments to the same hledger field,
only the last one takes effect. Here, comment's value will be be B, or
C if "something" is matched, but never A:
@ -838,14 +844,14 @@ TIPS
comment C
How CSV rules are evaluated
Here's how to think of CSV rules being evaluated (if you really need
Here's how to think of CSV rules being evaluated (if you really need
to). First,
o include - all includes are inlined, from top to bottom, depth first.
(At each include point the file is inlined and scanned for further
o include - all includes are inlined, from top to bottom, depth first.
(At each include point the file is inlined and scanned for further
includes, recursively, before proceeding.)
Then "global" rules are evaluated, top to bottom. If a rule is re-
Then "global" rules are evaluated, top to bottom. If a rule is re-
peated, the last one wins:
o skip (at top level)
@ -859,30 +865,30 @@ TIPS
Then for each CSV record in turn:
o test all if blocks. If any of them contain a end rule, skip all re-
maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip
o test all if blocks. If any of them contain a end rule, skip all re-
maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip
rules, the first one wins.
o collect all field assignments at top level and in matched if blocks.
When there are multiple assignments for a field, keep only the last
o collect all field assignments at top level and in matched if blocks.
When there are multiple assignments for a field, keep only the last
one.
o compute a value for each hledger field - either the one that was as-
o compute a value for each hledger field - either the one that was as-
signed to it (and interpolate the %CSVFIELDNAME references), or a de-
fault
o generate a synthetic hledger transaction from these values.
This is all part of the CSV reader, one of several readers hledger can
use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the
This is all part of the CSV reader, one of several readers hledger can
use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the
user specified.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -896,7 +902,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

98
hledger/hledger.1
View File

@ -3429,6 +3429,64 @@ Here\[aq]s one way to resolve that:
assets:checking
\f[R]
.fi
.SS codes
.PP
codes
.PD 0
.P
.PD
List the codes seen in transactions, in the order parsed.
.PP
This command prints the value of each transaction\[aq]s code field, in
the order transactions were parsed.
The transaction code is an optional value written in parentheses between
the date and description, often used to store a cheque number, order
number or similar.
.PP
Transactions aren\[aq]t required to have a code, and missing or empty
codes will not be shown by default.
With the \f[C]-E\f[R]/\f[C]--empty\f[R] flag, they will be printed as
blank lines.
.PP
You can add a query to select a subset of transactions.
.PP
Examples:
.IP
.nf
\f[C]
1/1 (123)
(a) 1
1/1 ()
(a) 1
1/1
(a) 1
1/1 (126)
(a) 1
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger codes
123
124
126
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger codes -E
123
124
126
\f[R]
.fi
.SS commodities
.PP
commodities
@ -3438,11 +3496,17 @@ commodities
List all commodity/currency symbols used or declared in the journal.
.SS descriptions
.PP
descriptions Show descriptions.
descriptions
.PD 0
.P
.PD
List the unique descriptions that appear in transactions.
.PP
This command lists all descriptions that appear in transactions.
This command lists the unique descriptions that appear in transactions,
in alphabetic order.
You can add a query to select a subset of transactions.
.PP
Examples:
Example:
.IP
.nf
\f[C]
@ -3652,11 +3716,19 @@ options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
\f[C]html\f[R], and (experimental) \f[C]json\f[R].
.SS notes
.PP
notes Show notes.
notes
.PD 0
.P
.PD
List the unique notes that appear in transactions.
.PP
This command lists all notes that appear in transactions.
This command lists the unique notes that appear in transactions, in
alphabetic order.
You can add a query to select a subset of transactions.
The note is the part of the transaction description after a | character
(or if there is no |, the whole description).
.PP
Examples:
Example:
.IP
.nf
\f[C]
@ -3667,11 +3739,19 @@ Snacks
.fi
.SS payees
.PP
payees Show payee names.
payees
.PD 0
.P
.PD
List the unique payee/payer names that appear in transactions.
.PP
This command lists all payee names that appear in transactions.
This command lists the unique payee/payer names that appear in
transactions, in alphabetic order.
You can add a query to select a subset of transactions.
The payee/payer is the part of the transaction description before a |
character (or if there is no |, the whole description).
.PP
Examples:
Example:
.IP
.nf
\f[C]

355
hledger/hledger.info
View File

@ -1903,6 +1903,7 @@ detailed command help.
* check-dates::
* check-dupes::
* close::
* codes::
* commodities::
* descriptions::
* diff::
@ -2776,7 +2777,7 @@ the default journal file, or another specified as an argument.
An example: http://stefanorodighiero.net/software/hledger-dupes.html

File: hledger.info, Node: close, Next: commodities, Prev: check-dupes, Up: COMMANDS
File: hledger.info, Node: close, Next: codes, Prev: check-dupes, Up: COMMANDS
3.10 close
==========
@ -2887,9 +2888,55 @@ breaking balance assertions:
assets:checking

File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up: COMMANDS
File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS
3.11 commodities
3.11 codes
==========
codes
List the codes seen in transactions, in the order parsed.
This command prints the value of each transaction's code field, in
the order transactions were parsed. The transaction code is an optional
value written in parentheses between the date and description, often
used to store a cheque number, order number or similar.
Transactions aren't required to have a code, and missing or empty
codes will not be shown by default. With the '-E'/'--empty' flag, they
will be printed as blank lines.
You can add a query to select a subset of transactions.
Examples:
1/1 (123)
(a) 1
1/1 ()
(a) 1
1/1
(a) 1
1/1 (126)
(a) 1
$ hledger codes
123
124
126
$ hledger codes -E
123
124
126

File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS
3.12 commodities
================
commodities
@ -2898,14 +2945,17 @@ List all commodity/currency symbols used or declared in the journal.

File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS
3.12 descriptions
3.13 descriptions
=================
descriptions Show descriptions.
descriptions
List the unique descriptions that appear in transactions.
This command lists all descriptions that appear in transactions.
This command lists the unique descriptions that appear in
transactions, in alphabetic order. You can add a query to select a
subset of transactions.
Examples:
Example:
$ hledger descriptions
Store Name
@ -2915,7 +2965,7 @@ Person A

File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS
3.13 diff
3.14 diff
=========
diff
@ -2950,7 +3000,7 @@ These transactions are in the second file only:

File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS
3.14 files
3.15 files
==========
files
@ -2960,7 +3010,7 @@ file names matching the regular expression (case sensitive) are shown.

File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS
3.15 help
3.16 help
=========
help
@ -3000,7 +3050,7 @@ DESCRIPTION

File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS
3.16 import
3.17 import
===========
import
@ -3029,7 +3079,7 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions

File: hledger.info, Node: Importing balance assignments, Up: import
3.16.1 Importing balance assignments
3.17.1 Importing balance assignments
------------------------------------
Entries added by import will have their posting amounts made explicit
@ -3048,7 +3098,7 @@ please test it and send a pull request.)

File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS
3.17 incomestatement
3.18 incomestatement
====================
incomestatement, is
@ -3097,14 +3147,18 @@ options The output formats supported are 'txt', 'csv', 'html', and

File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS
3.18 notes
3.19 notes
==========
notes Show notes.
notes
List the unique notes that appear in transactions.
This command lists all notes that appear in transactions.
This command lists the unique notes that appear in transactions, in
alphabetic order. You can add a query to select a subset of
transactions. The note is the part of the transaction description after
a | character (or if there is no |, the whole description).
Examples:
Example:
$ hledger notes
Petrol
@ -3113,14 +3167,19 @@ Snacks

File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS
3.19 payees
3.20 payees
===========
payees Show payee names.
payees
List the unique payee/payer names that appear in transactions.
This command lists all payee names that appear in transactions.
This command lists the unique payee/payer names that appear in
transactions, in alphabetic order. You can add a query to select a
subset of transactions. The payee/payer is the part of the transaction
description before a | character (or if there is no |, the whole
description).
Examples:
Example:
$ hledger payees
Store Name
@ -3130,7 +3189,7 @@ Person A

File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS
3.20 prices
3.21 prices
===========
prices
@ -3143,7 +3202,7 @@ Price amounts are always displayed with their full precision.

File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS
3.21 print
3.22 print
==========
print, txns, p
@ -3252,7 +3311,7 @@ $ hledger print -Ocsv

File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS
3.22 print-unique
3.23 print-unique
=================
print-unique
@ -3273,7 +3332,7 @@ $ LEDGER_FILE=unique.journal hledger print-unique

File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS
3.23 register
3.24 register
=============
register, reg, r
@ -3363,7 +3422,7 @@ length and comparable to the others in the report.

File: hledger.info, Node: Custom register output, Up: register
3.23.1 Custom register output
3.24.1 Custom register output
-----------------------------
register uses the full terminal width by default, except on windows.
@ -3395,7 +3454,7 @@ options The output formats supported are 'txt', 'csv', and

File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
3.24 register-match
3.25 register-match
===================
register-match
@ -3408,7 +3467,7 @@ ledger-autosync detect already-seen transactions when importing.

File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS
3.25 rewrite
3.26 rewrite
============
rewrite
@ -3460,7 +3519,7 @@ commodity.

File: hledger.info, Node: Re-write rules in a file, Up: rewrite
3.25.1 Re-write rules in a file
3.26.1 Re-write rules in a file
-------------------------------
During the run this tool will execute so called "Automated Transactions"
@ -3503,7 +3562,7 @@ postings.

File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file
3.25.1.1 Diff output format
3.26.1.1 Diff output format
...........................
To use this tool for batch modification of your journal files you may
@ -3544,7 +3603,7 @@ output from 'hledger print'.

File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file
3.25.1.2 rewrite vs. print -auto
3.26.1.2 rewrite vs. print -auto
................................
This command predates print -auto, and currently does much the same
@ -3564,7 +3623,7 @@ thing, but with these differences:

File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS
3.26 roi
3.27 roi
========
roi
@ -3592,7 +3651,7 @@ regardless of the length of reporting interval.

File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS
3.27 stats
3.28 stats
==========
stats
@ -3623,7 +3682,7 @@ selection.

File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS
3.28 tags
3.29 tags
=========
tags
@ -3636,7 +3695,7 @@ instead.

File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS
3.29 test
3.30 test
=========
test
@ -3663,7 +3722,7 @@ $ hledger test -- -pData.Amount --color=never

File: hledger.info, Node: Add-on commands, Prev: test, Up: COMMANDS
3.30 Add-on commands
3.31 Add-on commands
====================
hledger also searches for external add-on commands, and will include
@ -3704,7 +3763,7 @@ interfaces. These are maintained and released along with hledger:

File: hledger.info, Node: ui, Next: web, Up: Add-on commands
3.30.1 ui
3.31.1 ui
---------
hledger-ui provides an efficient terminal interface.
@ -3712,7 +3771,7 @@ hledger-ui provides an efficient terminal interface.

File: hledger.info, Node: web, Next: iadd, Prev: ui, Up: Add-on commands
3.30.2 web
3.31.2 web
----------
hledger-web provides a simple web interface.
@ -3722,7 +3781,7 @@ hledger-web provides a simple web interface.

File: hledger.info, Node: iadd, Next: interest, Prev: web, Up: Add-on commands
3.30.3 iadd
3.31.3 iadd
-----------
hledger-iadd is a more interactive, terminal UI replacement for the add
@ -3731,7 +3790,7 @@ command.

File: hledger.info, Node: interest, Prev: iadd, Up: Add-on commands
3.30.4 interest
3.31.4 interest
---------------
hledger-interest generates interest transactions for an account
@ -3968,113 +4027,115 @@ Node: Effect of valuation on reports58740
Ref: #effect-of-valuation-on-reports58928
Node: COMMANDS64449
Ref: #commands64557
Node: accounts65641
Ref: #accounts65739
Node: activity66438
Ref: #activity66548
Node: add66931
Ref: #add67030
Node: balance69823
Ref: #balance69934
Node: Classic balance report71392
Ref: #classic-balance-report71565
Node: Customising the classic balance report72999
Ref: #customising-the-classic-balance-report73227
Node: Colour support75303
Ref: #colour-support75470
Node: Flat mode75643
Ref: #flat-mode75791
Node: Depth limited balance reports76204
Ref: #depth-limited-balance-reports76389
Node: Percentages76845
Ref: #percentages77011
Node: Multicolumn balance report78148
Ref: #multicolumn-balance-report78328
Node: Budget report84066
Ref: #budget-report84209
Node: Nested budgets89475
Ref: #nested-budgets89587
Ref: #output-format-193068
Node: balancesheet93265
Ref: #balancesheet93401
Node: balancesheetequity94867
Ref: #balancesheetequity95016
Node: cashflow95739
Ref: #cashflow95867
Node: check-dates97046
Ref: #check-dates97173
Node: check-dupes97452
Ref: #check-dupes97576
Node: close97869
Ref: #close97983
Node: close usage99505
Ref: #close-usage99598
Node: commodities102411
Ref: #commodities102538
Node: descriptions102620
Ref: #descriptions102748
Node: diff102929
Ref: #diff103035
Node: files104082
Ref: #files104182
Node: help104329
Ref: #help104429
Node: import105510
Ref: #import105624
Node: Importing balance assignments106517
Ref: #importing-balance-assignments106665
Node: incomestatement107314
Ref: #incomestatement107447
Node: notes108934
Ref: #notes109047
Node: payees109173
Ref: #payees109279
Node: prices109437
Ref: #prices109543
Node: print109884
Ref: #print109994
Node: print-unique114790
Ref: #print-unique114916
Node: register115201
Ref: #register115328
Node: Custom register output119500
Ref: #custom-register-output119629
Node: register-match120966
Ref: #register-match121100
Node: rewrite121451
Ref: #rewrite121566
Node: Re-write rules in a file123421
Ref: #re-write-rules-in-a-file123555
Node: Diff output format124765
Ref: #diff-output-format124934
Node: rewrite vs print --auto126026
Ref: #rewrite-vs.-print---auto126205
Node: roi126761
Ref: #roi126859
Node: stats127871
Ref: #stats127970
Node: tags128758
Ref: #tags128856
Node: test129150
Ref: #test129258
Node: Add-on commands130005
Ref: #add-on-commands130122
Node: ui131465
Ref: #ui131553
Node: web131607
Ref: #web131710
Node: iadd131826
Ref: #iadd131937
Node: interest132019
Ref: #interest132126
Node: ENVIRONMENT132366
Ref: #environment132478
Node: FILES133307
Ref: #files-1133410
Node: LIMITATIONS133623
Ref: #limitations133742
Node: TROUBLESHOOTING134484
Ref: #troubleshooting134597
Node: accounts65651
Ref: #accounts65749
Node: activity66448
Ref: #activity66558
Node: add66941
Ref: #add67040
Node: balance69833
Ref: #balance69944
Node: Classic balance report71402
Ref: #classic-balance-report71575
Node: Customising the classic balance report73009
Ref: #customising-the-classic-balance-report73237
Node: Colour support75313
Ref: #colour-support75480
Node: Flat mode75653
Ref: #flat-mode75801
Node: Depth limited balance reports76214
Ref: #depth-limited-balance-reports76399
Node: Percentages76855
Ref: #percentages77021
Node: Multicolumn balance report78158
Ref: #multicolumn-balance-report78338
Node: Budget report84076
Ref: #budget-report84219
Node: Nested budgets89485
Ref: #nested-budgets89597
Ref: #output-format-193078
Node: balancesheet93275
Ref: #balancesheet93411
Node: balancesheetequity94877
Ref: #balancesheetequity95026
Node: cashflow95749
Ref: #cashflow95877
Node: check-dates97056
Ref: #check-dates97183
Node: check-dupes97462
Ref: #check-dupes97586
Node: close97879
Ref: #close97987
Node: close usage99509
Ref: #close-usage99602
Node: codes102415
Ref: #codes102523
Node: commodities103235
Ref: #commodities103362
Node: descriptions103444
Ref: #descriptions103572
Node: diff103876
Ref: #diff103982
Node: files105029
Ref: #files105129
Node: help105276
Ref: #help105376
Node: import106457
Ref: #import106571
Node: Importing balance assignments107464
Ref: #importing-balance-assignments107612
Node: incomestatement108261
Ref: #incomestatement108394
Node: notes109881
Ref: #notes109994
Node: payees110362
Ref: #payees110468
Node: prices110888
Ref: #prices110994
Node: print111335
Ref: #print111445
Node: print-unique116241
Ref: #print-unique116367
Node: register116652
Ref: #register116779
Node: Custom register output120951
Ref: #custom-register-output121080
Node: register-match122417
Ref: #register-match122551
Node: rewrite122902
Ref: #rewrite123017
Node: Re-write rules in a file124872
Ref: #re-write-rules-in-a-file125006
Node: Diff output format126216
Ref: #diff-output-format126385
Node: rewrite vs print --auto127477
Ref: #rewrite-vs.-print---auto127656
Node: roi128212
Ref: #roi128310
Node: stats129322
Ref: #stats129421
Node: tags130209
Ref: #tags130307
Node: test130601
Ref: #test130709
Node: Add-on commands131456
Ref: #add-on-commands131573
Node: ui132916
Ref: #ui133004
Node: web133058
Ref: #web133161
Node: iadd133277
Ref: #iadd133388
Node: interest133470
Ref: #interest133577
Node: ENVIRONMENT133817
Ref: #environment133929
Node: FILES134758
Ref: #files-1134861
Node: LIMITATIONS135074
Ref: #limitations135193
Node: TROUBLESHOOTING135935
Ref: #troubleshooting136048

End Tag Table

392
hledger/hledger.txt
View File

@ -2479,16 +2479,60 @@ COMMANDS
liabilities:pending 5 = 0
assets:checking
codes
codes
List the codes seen in transactions, in the order parsed.
This command prints the value of each transaction's code field, in the
order transactions were parsed. The transaction code is an optional
value written in parentheses between the date and description, often
used to store a cheque number, order number or similar.
Transactions aren't required to have a code, and missing or empty codes
will not be shown by default. With the -E/--empty flag, they will be
printed as blank lines.
You can add a query to select a subset of transactions.
Examples:
1/1 (123)
(a) 1
1/1 ()
(a) 1
1/1
(a) 1
1/1 (126)
(a) 1
$ hledger codes
123
124
126
$ hledger codes -E
123
124
126
commodities
commodities
List all commodity/currency symbols used or declared in the journal.
descriptions
descriptions Show descriptions.
descriptions
List the unique descriptions that appear in transactions.
This command lists all descriptions that appear in transactions.
This command lists the unique descriptions that appear in transactions,
in alphabetic order. You can add a query to select a subset of trans-
actions.
Examples:
Example:
$ hledger descriptions
Store Name
@ -2497,18 +2541,18 @@ COMMANDS
diff
diff
Compares a particular account's transactions in two input files. It
Compares a particular account's transactions in two input files. It
shows any transactions to this account which are in one file but not in
the other.
More precisely, for each posting affecting this account in either file,
it looks for a corresponding posting in the other file which posts the
same amount to the same account (ignoring date, description, etc.)
it looks for a corresponding posting in the other file which posts the
same amount to the same account (ignoring date, description, etc.)
Since postings not transactions are compared, this also works when mul-
tiple bank transactions have been combined into a single journal entry.
This is useful eg if you have downloaded an account's transactions from
your bank (eg as CSV data). When hledger and your bank disagree about
your bank (eg as CSV data). When hledger and your bank disagree about
the account balance, you can compare the bank data with your journal to
find out the cause.
@ -2526,20 +2570,20 @@ COMMANDS
files
files
List all files included in the journal. With a REGEX argument, only
List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown.
help
help
Show any of the hledger manuals.
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one.
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags.
Examples:
@ -2566,9 +2610,9 @@ COMMANDS
import
import
Read new transactions added to each FILE since last run, and add them
to the main journal file. Or with --dry-run, just print the transac-
tions that would be added. Or with --catchup, just mark all of the
Read new transactions added to each FILE since last run, and add them
to the main journal file. Or with --dry-run, just print the transac-
tions that would be added. Or with --catchup, just mark all of the
FILEs' transactions as imported, without actually importing any.
The input files are specified as arguments - no need to write -f before
@ -2579,36 +2623,36 @@ COMMANDS
ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files.
The --dry-run output is in journal format, so you can filter it, eg to
The --dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
Importing balance assignments
Entries added by import will have their posting amounts made explicit
(like hledger print -x). This means that any balance assignments in
imported files must be evaluated; but, imported files don't get to see
the main file's account balances. As a result, importing entries with
Entries added by import will have their posting amounts made explicit
(like hledger print -x). This means that any balance assignments in
imported files must be evaluated; but, imported files don't get to see
the main file's account balances. As a result, importing entries with
balance assignments (eg from an institution that provides only balances
and not posting amounts) will probably generate incorrect posting
and not posting amounts) will probably generate incorrect posting
amounts. To avoid this problem, use print instead of import:
$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
(If you think import should leave amounts implicit like print does,
(If you think import should leave amounts implicit like print does,
please test it and send a pull request.)
incomestatement
incomestatement, is
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements, un-
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements, un-
like balance/print/register) (experimental).
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@ -2633,32 +2677,40 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical. Instead of abso-
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical. Instead of abso-
lute values percentages can be displayed with -%.
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, html, and (experimen-
tions The output formats supported are txt, csv, html, and (experimen-
tal) json.
notes
notes Show notes.
notes
List the unique notes that appear in transactions.
This command lists all notes that appear in transactions.
This command lists the unique notes that appear in transactions, in al-
phabetic order. You can add a query to select a subset of transac-
tions. The note is the part of the transaction description after a |
character (or if there is no |, the whole description).
Examples:
Example:
$ hledger notes
Petrol
Snacks
payees
payees Show payee names.
payees
List the unique payee/payer names that appear in transactions.
This command lists all payee names that appear in transactions.
This command lists the unique payee/payer names that appear in transac-
tions, in alphabetic order. You can add a query to select a subset of
transactions. The payee/payer is the part of the transaction descrip-
tion before a | character (or if there is no |, the whole description).
Examples:
Example:
$ hledger payees
Store Name
@ -2667,10 +2719,10 @@ COMMANDS
prices
prices
Print market price directives from the journal. With --costs, also
print synthetic market prices based on transaction prices. With --in-
verted-costs, also print inverse prices based on transaction prices.
Prices (and postings providing prices) can be filtered by a query.
Print market price directives from the journal. With --costs, also
print synthetic market prices based on transaction prices. With --in-
verted-costs, also print inverse prices based on transaction prices.
Prices (and postings providing prices) can be filtered by a query.
Price amounts are always displayed with their full precision.
print
@ -2678,11 +2730,11 @@ COMMANDS
Show transaction journal entries, sorted by date.
The print command displays full journal entries (transactions) from the
journal file in date order, tidily formatted. With --date2, transac-
journal file in date order, tidily formatted. With --date2, transac-
tions are sorted by secondary date instead.
print's output is always a valid hledger journal.
It preserves all transaction information, but it does not preserve di-
It preserves all transaction information, but it does not preserve di-
rectives or inter-transaction comments
$ hledger print
@ -2709,43 +2761,43 @@ COMMANDS
Normally, the journal entry's explicit or implicit amount style is pre-
served. For example, when an amount is omitted in the journal, it will
not appear in the output. Similarly, when a transaction price is im-
plied but not written, it will not appear in the output. You can use
the -x/--explicit flag to make all amounts and transaction prices ex-
plicit, which can be useful for troubleshooting or for making your
not appear in the output. Similarly, when a transaction price is im-
plied but not written, it will not appear in the output. You can use
the -x/--explicit flag to make all amounts and transaction prices ex-
plicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors. -x is also
implied by using any of -B,-V,-X,--value.
Note, -x/--explicit will cause postings with a multi-commodity amount
(these can arise when a multi-commodity transaction has an implicit
amount) to be split into multiple single-commodity postings, keeping
Note, -x/--explicit will cause postings with a multi-commodity amount
(these can arise when a multi-commodity transaction has an implicit
amount) to be split into multiple single-commodity postings, keeping
the output parseable.
With -B/--cost, amounts with transaction prices are converted to cost
With -B/--cost, amounts with transaction prices are converted to cost
using that price. This can be used for troubleshooting.
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is
no similar-enough match, no transaction will be shown.
With --new, for each FILE being read, hledger reads (and writes) a spe-
cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for ig-
noring already-seen entries in import data, such as downloaded CSV
cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for ig-
noring already-seen entries in import data, such as downloaded CSV
files. Eg:
$ hledger -f bank1.csv print --new
(shows transactions added since last print --new on this file)
This assumes that transactions added to FILE always have same or in-
creasing dates, and that transactions on the same day do not get re-
This assumes that transactions added to FILE always have same or in-
creasing dates, and that transactions on the same day do not get re-
ordered. See also the import command.
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, and (experimental)
tions The output formats supported are txt, csv, and (experimental)
json and sql.
Here's an example of print's CSV output:
@ -2764,20 +2816,20 @@ COMMANDS
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
o There is one CSV record per posting, with the parent transaction's
o There is one CSV record per posting, with the parent transaction's
fields repeated.
o The "txnidx" (transaction index) field shows which postings belong to
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
order, etc.)
o The amount is separated into "commodity" (the symbol) and "amount"
o The amount is separated into "commodity" (the symbol) and "amount"
(numeric quantity) fields.
o The numeric amount is repeated in either the "credit" or "debit" col-
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
greater amounts under debit.)
print-unique
@ -2801,7 +2853,7 @@ COMMANDS
Show postings and their running total.
The register command displays postings in date order, one per line, and
their running total. This is typically used with a query selecting a
their running total. This is typically used with a query selecting a
particular account, to see that account's activity:
$ hledger register checking
@ -2812,8 +2864,8 @@ COMMANDS
With --date2, it shows and sorts by secondary date instead.
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical
@ -2823,18 +2875,18 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead
The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one ac-
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one ac-
count and one commodity.
The --related/-r flag shows the other postings in the transactions of
The --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown.
The --invert flag negates all amounts. For example, it can be used on
The --invert flag negates all amounts. For example, it can be used on
an income account where amounts are normally displayed as negative num-
bers. It's also useful to show postings on the checking account to-
bers. It's also useful to show postings on the checking account to-
gether with the related account:
$ hledger register --related --invert assets:checking
@ -2846,7 +2898,7 @@ COMMANDS
2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are
Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E
@ -2863,7 +2915,7 @@ COMMANDS
2008/11 0 $-2
2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth op-
Often, you'll want to see just one line per interval. The --depth op-
tion helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@ -2871,17 +2923,17 @@ COMMANDS
2008/06 assets $-1 0
2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of in-
tervals. This ensures that the first and last intervals are full
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of in-
tervals. This ensures that the first and last intervals are full
length and comparable to the others in the report.
Custom register output
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a de-
scription width as part of --width's argument, comma-separated: --width
W,D . Here's a diagram (won't display correctly in --help):
@ -2900,27 +2952,27 @@ COMMANDS
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, and (experimental)
tions The output formats supported are txt, csv, and (experimental)
json.
register-match
register-match
Print the one posting whose transaction description is closest to DESC,
in the style of the register command. If there are multiple equally
good matches, it shows the most recent. Query options (options, not
arguments) can be used to restrict the search space. Helps ledger-au-
in the style of the register command. If there are multiple equally
good matches, it shows the most recent. Query options (options, not
arguments) can be used to restrict the search space. Helps ledger-au-
tosync detect already-seen transactions when importing.
rewrite
rewrite
Print all transactions, rewriting the postings of matched transactions.
For now the only rewrite available is adding new postings, like print
For now the only rewrite available is adding new postings, like print
--auto.
This is a start at a generic rewriter of transaction entries. It reads
the default journal and prints the transactions, like print, but adds
the default journal and prints the transactions, like print, but adds
one or more specified postings to any transactions matching QUERY. The
posting amounts can be fixed, or a multiplier of the existing transac-
posting amounts can be fixed, or a multiplier of the existing transac-
tion's first posting amount.
Examples:
@ -2936,7 +2988,7 @@ COMMANDS
(reserve:grocery) *0.25 ; reserve 25% for grocery
(reserve:) *0.25 ; reserve 25% for grocery
Note the single quotes to protect the dollar sign from bash, and the
Note the single quotes to protect the dollar sign from bash, and the
two spaces between account and amount.
More:
@ -2946,16 +2998,16 @@ COMMANDS
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
Argument for --add-posting option is a usual posting of transaction
with an exception for amount specification. More precisely, you can
Argument for --add-posting option is a usual posting of transaction
with an exception for amount specification. More precisely, you can
use '*' (star symbol) before the amount to indicate that that this is a
factor for an amount of original matched posting. If the amount in-
factor for an amount of original matched posting. If the amount in-
cludes a commodity name, the new posting amount will be in the new com-
modity; otherwise, it will be in the matched posting amount's commod-
modity; otherwise, it will be in the matched posting amount's commod-
ity.
Re-write rules in a file
During the run this tool will execute so called "Automated Transac-
During the run this tool will execute so called "Automated Transac-
tions" found in any journal it process. I.e instead of specifying this
operations in command line you can put them in a journal file.
@ -2970,7 +3022,7 @@ COMMANDS
budget:gifts *-1
assets:budget *1
Note that '=' (equality symbol) that is used instead of date in trans-
Note that '=' (equality symbol) that is used instead of date in trans-
actions you usually write. It indicates the query by which you want to
match the posting to add new ones.
@ -2983,12 +3035,12 @@ COMMANDS
--add-posting 'assets:budget *1' \
> rewritten-tidy-output.journal
It is important to understand that relative order of such entries in
journal is important. You can re-use result of previously added post-
It is important to understand that relative order of such entries in
journal is important. You can re-use result of previously added post-
ings.
Diff output format
To use this tool for batch modification of your journal files you may
To use this tool for batch modification of your journal files you may
find useful output in form of unified diff.
$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
@ -3012,10 +3064,10 @@ COMMANDS
If you'll pass this through patch tool you'll get transactions contain-
ing the posting that matches your query be updated. Note that multiple
files might be update according to list of input files specified via
files might be update according to list of input files specified via
--file options and include directives inside of these files.
Be careful. Whole transaction being re-formatted in a style of output
Be careful. Whole transaction being re-formatted in a style of output
from hledger print.
See also:
@ -3023,48 +3075,48 @@ COMMANDS
https://github.com/simonmichael/hledger/issues/99
rewrite vs. print --auto
This command predates print --auto, and currently does much the same
This command predates print --auto, and currently does much the same
thing, but with these differences:
o with multiple files, rewrite lets rules in any file affect all other
files. print --auto uses standard directive scoping; rules affect
o with multiple files, rewrite lets rules in any file affect all other
files. print --auto uses standard directive scoping; rules affect
only child files.
o rewrite's query limits which transactions can be rewritten; all are
o rewrite's query limits which transactions can be rewritten; all are
printed. print --auto's query limits which transactions are printed.
o rewrite applies rules specified on command line or in the journal.
o rewrite applies rules specified on command line or in the journal.
print --auto applies rules specified in the journal.
roi
roi
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
on your investments.
This command assumes that you have account(s) that hold nothing but
This command assumes that you have account(s) that hold nothing but
your investments and whenever you record current appraisal/valuation of
these investments you offset unrealized profit and loss into account(s)
that, again, hold nothing but unrealized profit and loss.
Any transactions affecting balance of investment account(s) and not
originating from unrealized profit and loss account(s) are assumed to
Any transactions affecting balance of investment account(s) and not
originating from unrealized profit and loss account(s) are assumed to
be your investments or withdrawals.
At a minimum, you need to supply a query (which could be just an ac-
At a minimum, you need to supply a query (which could be just an ac-
count name) to select your investments with --inv, and another query to
identify your profit and loss transactions with --pnl.
It will compute and display the internalized rate of return (IRR) and
time-weighted rate of return (TWR) for your investments for the time
period requested. Both rates of return are annualized before display,
It will compute and display the internalized rate of return (IRR) and
time-weighted rate of return (TWR) for your investments for the time
period requested. Both rates of return are annualized before display,
regardless of the length of reporting interval.
stats
stats
Show some journal statistics.
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
Example:
@ -3082,14 +3134,14 @@ COMMANDS
Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
tags
tags
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are
considered. With --values flag, the tags' unique values are listed in-
stead.
@ -3097,13 +3149,13 @@ COMMANDS
test
Run built-in unit tests.
This command runs the unit tests built in to hledger and hledger-lib,
printing the results on stdout. If any test fails, the exit code will
This command runs the unit tests built in to hledger and hledger-lib,
printing the results on stdout. If any test fails, the exit code will
be non-zero.
This is mainly used by hledger developers, but you can also use it to
sanity-check the installed hledger executable on your platform. All
tests are expected to pass - if you ever see a failure, please report
This is mainly used by hledger developers, but you can also use it to
sanity-check the installed hledger executable on your platform. All
tests are expected to pass - if you ever see a failure, please report
as a bug!
This command also accepts tasty test runner options, written after a --
@ -3112,35 +3164,35 @@ COMMANDS
$ hledger test -- -pData.Amount --color=never
For help on these, see https://github.com/feuerbach/tasty#options (--
For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them).
Add-on commands
hledger also searches for external add-on commands, and will include
hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten-
whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
Add-ons can be invoked like any hledger command, but there are a few
Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred: hledger-web --serve
--port 9000.
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Two important add-ons are the hledger-ui and hledger-web user inter-
Two important add-ons are the hledger-ui and hledger-web user inter-
faces. These are maintained and released along with hledger:
ui
@ -3159,23 +3211,23 @@ COMMANDS
hledger-interest generates interest transactions for an account accord-
ing to various schemes.
A few more experimental or old add-ons can be found in hledger's bin/
A few more experimental or old add-ons can be found in hledger's bin/
directory. These are typically prototypes and not guaranteed to work.
ENVIRONMENT
COLUMNS The screen width used by the register command. Default: the
COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing
@ -3186,13 +3238,13 @@ ENVIRONMENT
To see the effect you may need to killall Dock, or reboot.
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
LIMITATIONS
The need to precede addon command options with -- when invoked from
The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@ -3208,36 +3260,36 @@ LIMITATIONS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
Not all of Ledger's journal file syntax is supported. See file format
Not all of Ledger's journal file syntax is supported. See file format
differences.
On large data files, hledger is slower and uses more memory than
On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
Here are some issues you might encounter when you run hledger (and re-
member you can also seek help from the IRC channel, mail list or bug
Here are some issues you might encounter when you run hledger (and re-
member you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command 'hledger' found"
stack and cabal install binaries into a special directory, which should
be added to your PATH environment variable. Eg on unix-like systems,
be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
Getting errors like "Illegal byte sequence" or "Invalid or incomplete
multibyte or wide character" or "commitAndReleaseBuffer: invalid argu-
Getting errors like "Illegal byte sequence" or "Invalid or incomplete
multibyte or wide character" or "commitAndReleaseBuffer: invalid argu-
ment (invalid character)"
Programs compiled with GHC (hledger, haskell build tools, etc.) need to
have a UTF-8-aware locale configured in the environment, otherwise they
will fail with these kinds of errors when they encounter non-ascii
will fail with these kinds of errors when they encounter non-ascii
characters.
To fix it, set the LANG environment variable to some locale which sup-
To fix it, set the LANG environment variable to some locale which sup-
ports UTF-8. The locale you choose must be installed on your system.
Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
@ -3252,8 +3304,8 @@ TROUBLESHOOTING
POSIX
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
If available, C.UTF-8 will also work. If your preferred locale isn't
listed by locale -a, you might need to install it. Eg on Ubuntu/De-
If available, C.UTF-8 will also work. If your preferred locale isn't
listed by locale -a, you might need to install it. Eg on Ubuntu/De-
bian:
$ apt-get install language-pack-fr
@ -3273,8 +3325,8 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.utf8" >>~/.bash_profile
$ bash --login
Exact spelling and capitalisation may be important. Note the differ-
ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
Exact spelling and capitalisation may be important. Note the differ-
ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
variant spellings, but others (eg macos) require it to be exact:
$ locale -a | grep -iE en_us.*utf
@ -3284,7 +3336,7 @@ TROUBLESHOOTING
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -3298,7 +3350,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)