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 .PP
A single matcher can be written on the same line as the \[dq]if\[dq]; or 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 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 .PP
After the patterns there should be one or more rules to apply, all After the patterns there should be one or more rules to apply, all
indented by at least one space. 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 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 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 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 indented by at least one space. Three kinds of rule are allowed in
@ -1141,40 +1148,40 @@ Node: separator21340
Ref: #separator21475 Ref: #separator21475
Node: if block21886 Node: if block21886
Ref: #if-block22011 Ref: #if-block22011
Node: if table24167 Node: if table24287
Ref: #if-table24286 Ref: #if-table24406
Node: end26024 Node: end26144
Ref: #end26136 Ref: #end26256
Node: date-format26360 Node: date-format26480
Ref: #date-format26492 Ref: #date-format26612
Node: newest-first27241 Node: newest-first27361
Ref: #newest-first27379 Ref: #newest-first27499
Node: include28062 Node: include28182
Ref: #include28193 Ref: #include28313
Node: balance-type28637 Node: balance-type28757
Ref: #balance-type28757 Ref: #balance-type28877
Node: TIPS29457 Node: TIPS29577
Ref: #tips29539 Ref: #tips29659
Node: Rapid feedback29795 Node: Rapid feedback29915
Ref: #rapid-feedback29912 Ref: #rapid-feedback30032
Node: Valid CSV30372 Node: Valid CSV30492
Ref: #valid-csv30502 Ref: #valid-csv30622
Node: File Extension30694 Node: File Extension30814
Ref: #file-extension30846 Ref: #file-extension30966
Node: Reading multiple CSV files31256 Node: Reading multiple CSV files31376
Ref: #reading-multiple-csv-files31441 Ref: #reading-multiple-csv-files31561
Node: Valid transactions31682 Node: Valid transactions31802
Ref: #valid-transactions31860 Ref: #valid-transactions31980
Node: Deduplicating importing32488 Node: Deduplicating importing32608
Ref: #deduplicating-importing32667 Ref: #deduplicating-importing32787
Node: Setting amounts33700 Node: Setting amounts33820
Ref: #setting-amounts33869 Ref: #setting-amounts33989
Node: Setting currency/commodity34856 Node: Setting currency/commodity34976
Ref: #setting-currencycommodity35048 Ref: #setting-currencycommodity35168
Node: Referencing other fields35851 Node: Referencing other fields35971
Ref: #referencing-other-fields36051 Ref: #referencing-other-fields36171
Node: How CSV rules are evaluated36948 Node: How CSV rules are evaluated37068
Ref: #how-csv-rules-are-evaluated37121 Ref: #how-csv-rules-are-evaluated37241
 
End Tag Table 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- 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- 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- if
dented by at least one space. Three kinds of rule are allowed in con- 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: ditional blocks:
o field assignments (to set a hledger field) o field assignments (to set a hledger field)
@ -539,11 +545,11 @@ CSV RULES
MATCHER3,VALUE31,VALUE32,...,VALUE3n MATCHER3,VALUE31,VALUE32,...,VALUE3n
<empty line> <empty line>
Conditional tables ("if tables") are a different syntax to specify Conditional tables ("if tables") are a different syntax to specify
field assignments that will be applied only to CSV records which match field assignments that will be applied only to CSV records which match
certain patterns. 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 When MATCHER matches, values from that row would be assigned to the CSV
fields named on the if line, in the same order. fields named on the if line, in the same order.
@ -567,17 +573,17 @@ CSV RULES
... ...
CSVFIELDNAMEn VALUE3n 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. 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- 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. 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- 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 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 - to ensure that separator does not occur inside MATCHERs and values -
there is no way to escape separator. there is no way to escape separator.
Example: Example:
@ -588,7 +594,7 @@ CSV RULES
2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
end 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 reading this CSV file and move on to the next input file, or to command
execution. Eg: execution. Eg:
@ -599,10 +605,10 @@ CSV RULES
date-format date-format
date-format DATEFMT date-format DATEFMT
This is a helper for the date (and date2) fields. If your CSV dates 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 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 need to add a date-format rule describing them with a strptime date
parsing pattern, which must parse the CSV date value completely. Some parsing pattern, which must parse the CSV date value completely. Some
examples: examples:
# MM/DD/YY # MM/DD/YY
@ -624,15 +630,15 @@ CSV RULES
mat.html#v:formatTime mat.html#v:formatTime
newest-first newest-first
hledger always sorts the generated transactions by date. Transactions hledger always sorts the generated transactions by date. Transactions
on the same date should appear in the same order as their CSV records, 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 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: 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) 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) at the top)
o and you care about preserving the order of same-day transactions o and you care about preserving the order of same-day transactions
@ -645,9 +651,9 @@ CSV RULES
include include
include RULESFILE include RULESFILE
This includes the contents of another CSV rules file at this point. 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 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 file's directory. This can be useful for sharing common rules between
several rules files, eg: several rules files, eg:
# someaccount.csv.rules # someaccount.csv.rules
@ -662,10 +668,10 @@ CSV RULES
balance-type balance-type
Balance assertions generated by assigning to balanceN are of the simple 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, assertion. You may find the subaccount-including variants more useful,
eg if you have created some virtual subaccounts of checking to help eg if you have created some virtual subaccounts of checking to help
with budgeting. You can select a different type of assertion with the with budgeting. You can select a different type of assertion with the
balance-type rule: balance-type rule:
# balance assertions will consider all commodities and all subaccounts # balance assertions will consider all commodities and all subaccounts
@ -680,19 +686,19 @@ CSV RULES
TIPS TIPS
Rapid feedback 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- CSV rules. Here's a good way, using entr from http://eradman.com/entr-
project : project :
$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' $ 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 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 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 echo a separator each time the command re-runs, making it easier to
read the output. read the output.
Valid CSV 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: closed in quotes, note:
o they must be double quotes (not single quotes) o they must be double quotes (not single quotes)
@ -700,9 +706,9 @@ TIPS
o spaces outside the quotes are not allowed o spaces outside the quotes are not allowed
File Extension File Extension
CSV ("Character Separated Values") files should be named with one of CSV ("Character Separated Values") files should be named with one of
these filename extensions: .csv, .ssv, .tsv. Or, the file path should these filename extensions: .csv, .ssv, .tsv. Or, the file path should
be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify
the format and show the right error messages. For example: the format and show the right error messages. For example:
$ hledger -f foo.ssv print $ hledger -f foo.ssv print
@ -714,44 +720,44 @@ TIPS
More about this: Input files in the hledger manual. More about this: Input files in the hledger manual.
Reading multiple CSV files Reading multiple CSV files
If you use multiple -f options to read multiple CSV files at once, 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 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 file. But if you use the --rules-file option, that rules file will be
used for all the CSV files. used for all the CSV files.
Valid transactions Valid transactions
After reading a CSV file, hledger post-processes and validates the gen- After reading a CSV file, hledger post-processes and validates the gen-
erated journal entries as it would for a journal file - balancing them, erated journal entries as it would for a journal file - balancing them,
applying balance assignments, and canonicalising amount styles. Any applying balance assignments, and canonicalising amount styles. Any
errors at this stage will be reported in the usual way, displaying the errors at this stage will be reported in the usual way, displaying the
problem entry. problem entry.
There is one exception: balance assertions, if you have generated them, There is one exception: balance assertions, if you have generated them,
will not be checked, since normally these will work only when the CSV 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- 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: sertions generated from CSV right away, pipe into another hledger:
$ hledger -f file.csv print | hledger -f- print $ hledger -f file.csv print | hledger -f- print
Deduplicating, importing Deduplicating, importing
When you download a CSV file periodically, eg to get your latest bank When you download a CSV file periodically, eg to get your latest bank
transactions, the new file may overlap with the old one, containing transactions, the new file may overlap with the old one, containing
some of the same records. some of the same records.
The import command will (a) detect the new transactions, and (b) append The import command will (a) detect the new transactions, and (b) append
just those transactions to your main journal. It is idempotent, so you 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 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 of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
is the easiest way to import CSV data. Eg: is the easiest way to import CSV data. Eg:
# download the latest CSV files, then run this command. # download the latest CSV files, then run this command.
# Note, no -f flags needed here. # Note, no -f flags needed here.
$ hledger import *.csv [--dry] $ 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.) 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. exist for converting, deduplicating, classifying and managing CSV data.
See: See:
@ -762,43 +768,43 @@ TIPS
Setting amounts Setting amounts
A posting amount can be set in one of these ways: 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) (posting N's amount) or amount (posting 1's amount)
o by assigning to amountN-in and amountN-out (or amount-in and 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 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 will be used, with appropriate sign. If both contain a non-zero
value, this may not work. value, this may not work.
o by assigning to balanceN (or balance) instead of the above, setting o by assigning to balanceN (or balance) instead of the above, setting
the amount indirectly via a balance assignment. If you do this the the amount indirectly via a balance assignment. If you do this the
default account name may be wrong, so you should set that explicitly. default account name may be wrong, so you should set that explicitly.
There is some special handling for an amount's sign: 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. 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. and are removed.
o If an amount value begins with a plus sign, that will be removed o If an amount value begins with a plus sign, that will be removed
Setting currency/commodity 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. field(s), you don't have to do anything special.
If the currency is provided as a separate CSV field, you can either: 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 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 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 you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace between symbol and amount (an exception to the usual whitespace
stripping). stripping).
o or assign it to currencyN which adds it to posting N's amount only. 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: using field assignment, eg:
fields date,description,currency,quantity fields date,description,currency,quantity
@ -806,9 +812,9 @@ TIPS
amount %quantity %currency amount %quantity %currency
Referencing other fields Referencing other fields
In field assignments, you can interpolate only CSV fields, not hledger 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 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 field named amount1, but %amount1 always means the CSV field, not the
hledger field: hledger field:
# Name the third CSV field "amount1" # Name the third CSV field "amount1"
@ -820,7 +826,7 @@ TIPS
# Set comment to the CSV amount1 (not the amount1 assigned above) # Set comment to the CSV amount1 (not the amount1 assigned above)
comment %amount1 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": eral "amount1":
fields date,description,csvamount fields date,description,csvamount
@ -828,7 +834,7 @@ TIPS
# Can't interpolate amount1 here # Can't interpolate amount1 here
comment %amount1 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 only the last one takes effect. Here, comment's value will be be B, or
C if "something" is matched, but never A: C if "something" is matched, but never A:
@ -838,14 +844,14 @@ TIPS
comment C comment C
How CSV rules are evaluated 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, to). First,
o include - all includes are inlined, from top to bottom, depth 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 (At each include point the file is inlined and scanned for further
includes, recursively, before proceeding.) 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: peated, the last one wins:
o skip (at top level) o skip (at top level)
@ -859,30 +865,30 @@ TIPS
Then for each CSV record in turn: Then for each CSV record in turn:
o test all if blocks. If any of them contain a end rule, skip all re- 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, maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip skip that many CSV records. If there are multiple matched skip
rules, the first one wins. rules, the first one wins.
o collect all field assignments at top level and in matched if blocks. 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 When there are multiple assignments for a field, keep only the last
one. 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- signed to it (and interpolate the %CSVFIELDNAME references), or a de-
fault fault
o generate a synthetic hledger transaction from these values. o generate a synthetic hledger transaction from these values.
This is all part of the CSV reader, one of several readers hledger can 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, use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the the transactions are passed as input to whichever hledger command the
user specified. user specified.
REPORTING BUGS 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) or hledger mail list)
@ -896,7 +902,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)

98
hledger/hledger.1
View File

@ -3429,6 +3429,64 @@ Here\[aq]s one way to resolve that:
assets:checking assets:checking
\f[R] \f[R]
.fi .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 .SS commodities
.PP .PP
commodities commodities
@ -3438,11 +3496,17 @@ commodities
List all commodity/currency symbols used or declared in the journal. List all commodity/currency symbols used or declared in the journal.
.SS descriptions .SS descriptions
.PP .PP
descriptions Show descriptions. descriptions
.PD 0
.P
.PD
List the unique descriptions that appear in transactions.
.PP .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 .PP
Examples: Example:
.IP .IP
.nf .nf
\f[C] \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]. \f[C]html\f[R], and (experimental) \f[C]json\f[R].
.SS notes .SS notes
.PP .PP
notes Show notes. notes
.PD 0
.P
.PD
List the unique notes that appear in transactions.
.PP .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 .PP
Examples: Example:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -3667,11 +3739,19 @@ Snacks
.fi .fi
.SS payees .SS payees
.PP .PP
payees Show payee names. payees
.PD 0
.P
.PD
List the unique payee/payer names that appear in transactions.
.PP .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 .PP
Examples: Example:
.IP .IP
.nf .nf
\f[C] \f[C]

355
hledger/hledger.info
View File

@ -1903,6 +1903,7 @@ detailed command help.
* check-dates:: * check-dates::
* check-dupes:: * check-dupes::
* close:: * close::
* codes::
* commodities:: * commodities::
* descriptions:: * descriptions::
* diff:: * diff::
@ -2776,7 +2777,7 @@ the default journal file, or another specified as an argument.
An example: http://stefanorodighiero.net/software/hledger-dupes.html 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 3.10 close
========== ==========
@ -2887,9 +2888,55 @@ breaking balance assertions:
assets:checking 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 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 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 $ hledger descriptions
Store Name Store Name
@ -2915,7 +2965,7 @@ Person A
 
File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS
3.13 diff 3.14 diff
========= =========
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 File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS
3.14 files 3.15 files
========== ==========
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 File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS
3.15 help 3.16 help
========= =========
help help
@ -3000,7 +3050,7 @@ DESCRIPTION
 
File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS
3.16 import 3.17 import
=========== ===========
import import
@ -3029,7 +3079,7 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
 
File: hledger.info, Node: Importing balance assignments, Up: import 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 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 File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS
3.17 incomestatement 3.18 incomestatement
==================== ====================
incomestatement, is 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 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 $ hledger notes
Petrol Petrol
@ -3113,14 +3167,19 @@ Snacks
 
File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS 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 $ hledger payees
Store Name Store Name
@ -3130,7 +3189,7 @@ Person A
 
File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS
3.20 prices 3.21 prices
=========== ===========
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 File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS
3.21 print 3.22 print
========== ==========
print, txns, p print, txns, p
@ -3252,7 +3311,7 @@ $ hledger print -Ocsv
 
File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS
3.22 print-unique 3.23 print-unique
================= =================
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 File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS
3.23 register 3.24 register
============= =============
register, reg, r 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 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. 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 File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
3.24 register-match 3.25 register-match
=================== ===================
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 File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS
3.25 rewrite 3.26 rewrite
============ ============
rewrite rewrite
@ -3460,7 +3519,7 @@ commodity.
 
File: hledger.info, Node: Re-write rules in a file, Up: rewrite 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" 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 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 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 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 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 File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS
3.26 roi 3.27 roi
======== ========
roi roi
@ -3592,7 +3651,7 @@ regardless of the length of reporting interval.
 
File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS
3.27 stats 3.28 stats
========== ==========
stats stats
@ -3623,7 +3682,7 @@ selection.
 
File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS
3.28 tags 3.29 tags
========= =========
tags tags
@ -3636,7 +3695,7 @@ instead.
 
File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS
3.29 test 3.30 test
========= =========
test test
@ -3663,7 +3722,7 @@ $ hledger test -- -pData.Amount --color=never
 
File: hledger.info, Node: Add-on commands, Prev: test, Up: COMMANDS 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 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 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. 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 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. 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 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 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 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 hledger-interest generates interest transactions for an account
@ -3968,113 +4027,115 @@ Node: Effect of valuation on reports58740
Ref: #effect-of-valuation-on-reports58928 Ref: #effect-of-valuation-on-reports58928
Node: COMMANDS64449 Node: COMMANDS64449
Ref: #commands64557 Ref: #commands64557
Node: accounts65641 Node: accounts65651
Ref: #accounts65739 Ref: #accounts65749
Node: activity66438 Node: activity66448
Ref: #activity66548 Ref: #activity66558
Node: add66931 Node: add66941
Ref: #add67030 Ref: #add67040
Node: balance69823 Node: balance69833
Ref: #balance69934 Ref: #balance69944
Node: Classic balance report71392 Node: Classic balance report71402
Ref: #classic-balance-report71565 Ref: #classic-balance-report71575
Node: Customising the classic balance report72999 Node: Customising the classic balance report73009
Ref: #customising-the-classic-balance-report73227 Ref: #customising-the-classic-balance-report73237
Node: Colour support75303 Node: Colour support75313
Ref: #colour-support75470 Ref: #colour-support75480
Node: Flat mode75643 Node: Flat mode75653
Ref: #flat-mode75791 Ref: #flat-mode75801
Node: Depth limited balance reports76204 Node: Depth limited balance reports76214
Ref: #depth-limited-balance-reports76389 Ref: #depth-limited-balance-reports76399
Node: Percentages76845 Node: Percentages76855
Ref: #percentages77011 Ref: #percentages77021
Node: Multicolumn balance report78148 Node: Multicolumn balance report78158
Ref: #multicolumn-balance-report78328 Ref: #multicolumn-balance-report78338
Node: Budget report84066 Node: Budget report84076
Ref: #budget-report84209 Ref: #budget-report84219
Node: Nested budgets89475 Node: Nested budgets89485
Ref: #nested-budgets89587 Ref: #nested-budgets89597
Ref: #output-format-193068 Ref: #output-format-193078
Node: balancesheet93265 Node: balancesheet93275
Ref: #balancesheet93401 Ref: #balancesheet93411
Node: balancesheetequity94867 Node: balancesheetequity94877
Ref: #balancesheetequity95016 Ref: #balancesheetequity95026
Node: cashflow95739 Node: cashflow95749
Ref: #cashflow95867 Ref: #cashflow95877
Node: check-dates97046 Node: check-dates97056
Ref: #check-dates97173 Ref: #check-dates97183
Node: check-dupes97452 Node: check-dupes97462
Ref: #check-dupes97576 Ref: #check-dupes97586
Node: close97869 Node: close97879
Ref: #close97983 Ref: #close97987
Node: close usage99505 Node: close usage99509
Ref: #close-usage99598 Ref: #close-usage99602
Node: commodities102411 Node: codes102415
Ref: #commodities102538 Ref: #codes102523
Node: descriptions102620 Node: commodities103235
Ref: #descriptions102748 Ref: #commodities103362
Node: diff102929 Node: descriptions103444
Ref: #diff103035 Ref: #descriptions103572
Node: files104082 Node: diff103876
Ref: #files104182 Ref: #diff103982
Node: help104329 Node: files105029
Ref: #help104429 Ref: #files105129
Node: import105510 Node: help105276
Ref: #import105624 Ref: #help105376
Node: Importing balance assignments106517 Node: import106457
Ref: #importing-balance-assignments106665 Ref: #import106571
Node: incomestatement107314 Node: Importing balance assignments107464
Ref: #incomestatement107447 Ref: #importing-balance-assignments107612
Node: notes108934 Node: incomestatement108261
Ref: #notes109047 Ref: #incomestatement108394
Node: payees109173 Node: notes109881
Ref: #payees109279 Ref: #notes109994
Node: prices109437 Node: payees110362
Ref: #prices109543 Ref: #payees110468
Node: print109884 Node: prices110888
Ref: #print109994 Ref: #prices110994
Node: print-unique114790 Node: print111335
Ref: #print-unique114916 Ref: #print111445
Node: register115201 Node: print-unique116241
Ref: #register115328 Ref: #print-unique116367
Node: Custom register output119500 Node: register116652
Ref: #custom-register-output119629 Ref: #register116779
Node: register-match120966 Node: Custom register output120951
Ref: #register-match121100 Ref: #custom-register-output121080
Node: rewrite121451 Node: register-match122417
Ref: #rewrite121566 Ref: #register-match122551
Node: Re-write rules in a file123421 Node: rewrite122902
Ref: #re-write-rules-in-a-file123555 Ref: #rewrite123017
Node: Diff output format124765 Node: Re-write rules in a file124872
Ref: #diff-output-format124934 Ref: #re-write-rules-in-a-file125006
Node: rewrite vs print --auto126026 Node: Diff output format126216
Ref: #rewrite-vs.-print---auto126205 Ref: #diff-output-format126385
Node: roi126761 Node: rewrite vs print --auto127477
Ref: #roi126859 Ref: #rewrite-vs.-print---auto127656
Node: stats127871 Node: roi128212
Ref: #stats127970 Ref: #roi128310
Node: tags128758 Node: stats129322
Ref: #tags128856 Ref: #stats129421
Node: test129150 Node: tags130209
Ref: #test129258 Ref: #tags130307
Node: Add-on commands130005 Node: test130601
Ref: #add-on-commands130122 Ref: #test130709
Node: ui131465 Node: Add-on commands131456
Ref: #ui131553 Ref: #add-on-commands131573
Node: web131607 Node: ui132916
Ref: #web131710 Ref: #ui133004
Node: iadd131826 Node: web133058
Ref: #iadd131937 Ref: #web133161
Node: interest132019 Node: iadd133277
Ref: #interest132126 Ref: #iadd133388
Node: ENVIRONMENT132366 Node: interest133470
Ref: #environment132478 Ref: #interest133577
Node: FILES133307 Node: ENVIRONMENT133817
Ref: #files-1133410 Ref: #environment133929
Node: LIMITATIONS133623 Node: FILES134758
Ref: #limitations133742 Ref: #files-1134861
Node: TROUBLESHOOTING134484 Node: LIMITATIONS135074
Ref: #troubleshooting134597 Ref: #limitations135193
Node: TROUBLESHOOTING135935
Ref: #troubleshooting136048
 
End Tag Table End Tag Table

392
hledger/hledger.txt
View File

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