|
|
|
|
@ -97,18 +97,17 @@ Input
|
|
|
|
|
Usually the data file is in hledger's journal format, but it can be in
|
|
|
|
|
any of the supported file formats, which currently are:
|
|
|
|
|
|
|
|
|
|
Reader: Reads: Used for file exten-
|
|
|
|
|
sions:
|
|
|
|
|
Reader: Reads: Used for file extensions:
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
|
journal hledger journal files and some Ledger .journal .j .hledger
|
|
|
|
|
journals, for transactions .ledger
|
|
|
|
|
time- timeclock files, for precise time log- .timeclock
|
|
|
|
|
clock ging
|
|
|
|
|
timedot timedot files, for approximate time .timedot
|
|
|
|
|
logging
|
|
|
|
|
csv CSV/SSV/TSV/character-separated values, .csv .ssv .tsv
|
|
|
|
|
for data import .csv.rules .ssv.rules
|
|
|
|
|
.tsv.rules
|
|
|
|
|
journal hledger journal files and some .journal .j .hledger .ledger
|
|
|
|
|
Ledger journals, for transac-
|
|
|
|
|
tions
|
|
|
|
|
timeclock timeclock files, for precise .timeclock
|
|
|
|
|
time logging
|
|
|
|
|
timedot timedot files, for approximate .timedot
|
|
|
|
|
time logging
|
|
|
|
|
csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules
|
|
|
|
|
rated values, for data import .ssv.rules .tsv.rules
|
|
|
|
|
|
|
|
|
|
These formats are described in more detail below.
|
|
|
|
|
|
|
|
|
|
@ -494,16 +493,71 @@ Command line tips
|
|
|
|
|
and vice versa. (See eg #961).
|
|
|
|
|
|
|
|
|
|
Regular expressions
|
|
|
|
|
hledger uses regular expressions in a number of places:
|
|
|
|
|
A regular expression (regexp) is a small piece of text where certain
|
|
|
|
|
characters (like ., ^, $, +, *, (), |, [], \) have special meanings,
|
|
|
|
|
forming a tiny language for matching text precisely - very useful in
|
|
|
|
|
hledger and elsewhere. To learn all about them, visit regular-expres-
|
|
|
|
|
sions.info.
|
|
|
|
|
|
|
|
|
|
o query terms, on the command line and in the hledger-web search form:
|
|
|
|
|
REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
|
|
|
|
|
hledger supports regexps whenever you are entering a pattern to match
|
|
|
|
|
something, eg in query arguments, account aliases, CSV if rules,
|
|
|
|
|
hledger-web's search form, hledger-ui's / search, etc. You may need to
|
|
|
|
|
wrap them in quotes, especially at the command line (see Special char-
|
|
|
|
|
acters above). Here are some examples:
|
|
|
|
|
|
|
|
|
|
o CSV rules conditional blocks: if REGEX ...
|
|
|
|
|
Account name queries (quoted for command line use):
|
|
|
|
|
|
|
|
|
|
o account alias directive and --alias option: alias /REGEX/ = REPLACE-
|
|
|
|
|
MENT, --alias /REGEX/=REPLACEMENT
|
|
|
|
|
Regular expression: Matches:
|
|
|
|
|
------------------- ------------------------------------------------------------
|
|
|
|
|
bank assets:bank, assets:bank:savings, expenses:art:banksy, ...
|
|
|
|
|
:bank assets:bank:savings, expenses:art:banksy
|
|
|
|
|
:bank: assets:bank:savings
|
|
|
|
|
'^bank' none of those ( ^ matches beginning of text )
|
|
|
|
|
'bank$' assets:bank ( $ matches end of text )
|
|
|
|
|
'big \$ bank' big $ bank ( \ disables following character's special meaning )
|
|
|
|
|
'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries )
|
|
|
|
|
'(sav|check)ing' saving or checking ( (|) matches either alternative )
|
|
|
|
|
'saving|checking' saving or checking ( outer parentheses are not needed )
|
|
|
|
|
'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing )
|
|
|
|
|
'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing )
|
|
|
|
|
'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing )
|
|
|
|
|
'b.nk' bank, bonk, b nk, ... ( . matches any character )
|
|
|
|
|
|
|
|
|
|
Some other queries:
|
|
|
|
|
|
|
|
|
|
desc:'amazon|amzn|audible' Amazon transactions
|
|
|
|
|
cur:EUR amounts with commodity symbol containing EUR
|
|
|
|
|
cur:'\$' amounts with commodity symbol containing $
|
|
|
|
|
cur:'^\$$' only $ amounts, not eg AU$ or CA$
|
|
|
|
|
cur:....? amounts with 4-or-more-character symbols
|
|
|
|
|
tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023
|
|
|
|
|
|
|
|
|
|
Account name aliases: accept . instead of : as account separator:
|
|
|
|
|
|
|
|
|
|
alias /\./=: replaces all periods in account names with colons
|
|
|
|
|
|
|
|
|
|
Show multiple top-level accounts combined as one:
|
|
|
|
|
|
|
|
|
|
--alias='/^[^:]+/=combined' ( [^:] matches any character other than : )
|
|
|
|
|
|
|
|
|
|
Show accounts with the second-level part removed:
|
|
|
|
|
|
|
|
|
|
--alias '/^([^:]+):[^:]+/ = \1'
|
|
|
|
|
match a top-level account and a second-level account
|
|
|
|
|
and replace those with just the top-level account
|
|
|
|
|
( \1 in the replacement text means "whatever was matched
|
|
|
|
|
by the first parenthesised part of the regexp"
|
|
|
|
|
|
|
|
|
|
CSV rules: match CSV records containing dining-related MCC codes:
|
|
|
|
|
|
|
|
|
|
if \?MCC581[124]
|
|
|
|
|
|
|
|
|
|
Match CSV records with a specific amount around the end/start of month:
|
|
|
|
|
|
|
|
|
|
if %amount \b3\.99
|
|
|
|
|
& %date (29|30|31|01|02|03)$
|
|
|
|
|
|
|
|
|
|
hledger's regular expressions
|
|
|
|
|
hledger's regular expressions come from the regex-tdfa library. If
|
|
|
|
|
they're not doing what you expect, it's important to know exactly what
|
|
|
|
|
they support:
|
|
|
|
|
@ -517,10 +571,10 @@ Command line tips
|
|
|
|
|
|
|
|
|
|
4. they also support GNU word boundaries (\b, \B, \<, \>)
|
|
|
|
|
|
|
|
|
|
5. they do not support backreferences; if you write \1, it will match
|
|
|
|
|
the digit 1. Except when doing text replacement, eg in account
|
|
|
|
|
aliases, where backreferences can be used in the replacement string
|
|
|
|
|
to reference capturing groups in the search regexp.
|
|
|
|
|
5. backreferences are supported when doing text replacement in account
|
|
|
|
|
aliases or CSV rules, where backreferences can be used in the re-
|
|
|
|
|
placement string to reference capturing groups in the search regexp.
|
|
|
|
|
Otherwise, if you write \1, it will match the digit 1.
|
|
|
|
|
|
|
|
|
|
6. they do not support mode modifiers ((?s)), character classes (\w,
|
|
|
|
|
\d), or anything else not mentioned above.
|
|
|
|
|
@ -568,7 +622,7 @@ Output
|
|
|
|
|
Some commands offer other kinds of output, not just text on the termi-
|
|
|
|
|
nal. Here are those commands and the formats currently supported:
|
|
|
|
|
|
|
|
|
|
- txt csv html json sql
|
|
|
|
|
- txt csv/tsv html json sql
|
|
|
|
|
--------------------------------------------------------------------------------------
|
|
|
|
|
aregister Y Y Y Y
|
|
|
|
|
balance Y 1 Y 1 Y 1,2 Y
|
|
|
|
|
@ -1132,7 +1186,7 @@ Journal
|
|
|
|
|
A decimal mark can be written as a period or a comma:
|
|
|
|
|
|
|
|
|
|
1.23
|
|
|
|
|
1,23456780000009
|
|
|
|
|
1,23
|
|
|
|
|
|
|
|
|
|
In the integer part of the quantity (left of the decimal mark), groups
|
|
|
|
|
of digits can optionally be separated by a digit group mark - a space,
|
|
|
|
|
@ -1143,21 +1197,15 @@ Journal
|
|
|
|
|
INR 9,99,99,999.00
|
|
|
|
|
1 000 000.9455
|
|
|
|
|
|
|
|
|
|
Note, a number containing a single digit group mark and no decimal mark
|
|
|
|
|
is ambiguous. Are these digit group marks or decimal marks ?
|
|
|
|
|
hledger is not biased towards period or comma decimal marks, so a num-
|
|
|
|
|
ber containing just one period or comma, like 1,000 or 1.000, is am-
|
|
|
|
|
biguous. In such cases hledger assumes it is a decimal mark, parsing
|
|
|
|
|
both of these as 1.
|
|
|
|
|
|
|
|
|
|
1,000
|
|
|
|
|
1.000
|
|
|
|
|
|
|
|
|
|
If you don't tell it otherwise, hledger will assume both of the above
|
|
|
|
|
are decimal marks, parsing both numbers as 1.
|
|
|
|
|
|
|
|
|
|
To prevent confusing parsing mistakes and undetected typos, especially
|
|
|
|
|
if your data contains digit group marks (eg, thousands separators), we
|
|
|
|
|
recommend explicitly declaring the decimal mark character in each jour-
|
|
|
|
|
nal file, using a directive at the top of the file. The decimal-mark
|
|
|
|
|
directive is best, otherwise commodity directives will also work.
|
|
|
|
|
These are described below.
|
|
|
|
|
To disambiguate these and ensure accurate number parsing, especially if
|
|
|
|
|
you use digit group marks, we recommend declaring the decimal mark.
|
|
|
|
|
You can declare it for each file with decimal-mark directives, or for
|
|
|
|
|
each commodity with commodity directives (described below).
|
|
|
|
|
|
|
|
|
|
Commodity
|
|
|
|
|
Amounts in hledger have both a "quantity", which is a signed decimal
|
|
|
|
|
@ -1196,66 +1244,45 @@ Journal
|
|
|
|
|
|
|
|
|
|
Commodity display style
|
|
|
|
|
For the amounts in each commodity, hledger chooses a consistent display
|
|
|
|
|
style to use in most reports. (Exceptions: price amounts, and all
|
|
|
|
|
amounts displayed by the print command, are displayed with all of their
|
|
|
|
|
decimal digits visible.)
|
|
|
|
|
style (symbol placement, decimal mark and digit group marks, number of
|
|
|
|
|
decimal digits) to use in most reports. This is inferred as follows:
|
|
|
|
|
|
|
|
|
|
A commodity's display style is inferred as follows.
|
|
|
|
|
First, if there's a D directive declaring a default commodity, that
|
|
|
|
|
commodity symbol and amount format is applied to all no-symbol amounts
|
|
|
|
|
in the journal.
|
|
|
|
|
|
|
|
|
|
First, if a default commodity is declared with D, this commodity and
|
|
|
|
|
its style is applied to any no-symbol amounts in the journal.
|
|
|
|
|
Then each commodity's display style is determined from its commodity
|
|
|
|
|
directive. We recommend always declaring commodities with commodity
|
|
|
|
|
directives, since they help ensure consistent display styles and preci-
|
|
|
|
|
sions, and bring other benefits such as error checking for commodity
|
|
|
|
|
symbols.
|
|
|
|
|
|
|
|
|
|
Then each commodity's style is inferred from one of the following, in
|
|
|
|
|
order of preference:
|
|
|
|
|
But if a commodity directive is not present, hledger infers a commod-
|
|
|
|
|
ity's display styles from its amounts as they are written in the jour-
|
|
|
|
|
nal (excluding cost amounts and amounts in periodic transaction rules
|
|
|
|
|
or auto posting rules). It uses
|
|
|
|
|
|
|
|
|
|
o The commodity directive for that commodity (including the no-symbol
|
|
|
|
|
commodity), if any.
|
|
|
|
|
o the symbol placement and decimal mark of the first amount seen
|
|
|
|
|
|
|
|
|
|
o The amounts in that commodity seen in the journal's transactions.
|
|
|
|
|
(Posting amounts only; prices and periodic or auto rules are ignored,
|
|
|
|
|
currently.)
|
|
|
|
|
o the digit group marks of the first amount with digit group marks
|
|
|
|
|
|
|
|
|
|
o The built-in fallback style, which looks like this: $1000.00. (Sym-
|
|
|
|
|
bol on the left, period decimal mark, two decimal places.)
|
|
|
|
|
o and the maximum number of decimal digits seen across all amounts.
|
|
|
|
|
|
|
|
|
|
A style is inferred from journal amounts as follows:
|
|
|
|
|
And as fallback if no applicable amounts are found, it would use a de-
|
|
|
|
|
fault style, like $1000.00 (symbol on the left with no space, period as
|
|
|
|
|
decimal mark, and two decimal digits).
|
|
|
|
|
|
|
|
|
|
o Use the general style (decimal mark, symbol placement) of the first
|
|
|
|
|
amount
|
|
|
|
|
|
|
|
|
|
o Use the first-seen digit group style (digit group mark, digit group
|
|
|
|
|
sizes), if any
|
|
|
|
|
|
|
|
|
|
o Use the maximum number of decimal places of all.
|
|
|
|
|
|
|
|
|
|
Cost amounts don't affect the commodity display style directly, but oc-
|
|
|
|
|
casionally they can do so indirectly (eg when a posting's amount is in-
|
|
|
|
|
ferred using a cost). If you find this causing problems, use a commod-
|
|
|
|
|
ity directive to fix the display style.
|
|
|
|
|
|
|
|
|
|
To summarise: each commodity's amounts will be normalised to (a) the
|
|
|
|
|
style declared by a commodity directive, or (b) the style of the first
|
|
|
|
|
posting amount in the journal, with the first-seen digit group style
|
|
|
|
|
and the maximum-seen number of decimal places. So if your reports are
|
|
|
|
|
showing amounts in a way you don't like, eg with too many decimal
|
|
|
|
|
places, use a commodity directive. Some examples:
|
|
|
|
|
|
|
|
|
|
# declare euro, dollar, bitcoin and no-symbol commodities and set their
|
|
|
|
|
# input number formats and output display styles:
|
|
|
|
|
commodity EUR 1.000,
|
|
|
|
|
commodity $1000.00
|
|
|
|
|
commodity 1000.00000000 BTC
|
|
|
|
|
commodity 1 000.
|
|
|
|
|
|
|
|
|
|
The inferred commodity style can be overridden by supplying a command
|
|
|
|
|
line option.
|
|
|
|
|
Finally, commodity styles can be overridden by the -c/--commodity-style
|
|
|
|
|
command line option.
|
|
|
|
|
|
|
|
|
|
Rounding
|
|
|
|
|
Amounts are stored internally as decimal numbers with up to 255 decimal
|
|
|
|
|
places, and displayed with the number of decimal places specified by
|
|
|
|
|
the commodity display style. Note, hledger uses banker's rounding: it
|
|
|
|
|
rounds to the nearest even number, eg 0.5 displayed with zero decimal
|
|
|
|
|
places is "0").
|
|
|
|
|
places. They are displayed with their original journal precisions by
|
|
|
|
|
print and print-like reports, and rounded to their display precision
|
|
|
|
|
(the number of decimal digits specified by the commodity display style)
|
|
|
|
|
by other reports. When rounding, hledger uses banker's rounding (it
|
|
|
|
|
rounds to the nearest even digit). So eg 0.5 displayed with zero deci-
|
|
|
|
|
mal digits appears as "0".
|
|
|
|
|
|
|
|
|
|
Costs
|
|
|
|
|
After a posting amount, you can note its cost (when buying) or selling
|
|
|
|
|
@ -2084,84 +2111,76 @@ Journal
|
|
|
|
|
$ hledger accounts --alias assets=bassetts type:a
|
|
|
|
|
|
|
|
|
|
commodity directive
|
|
|
|
|
You can use commodity directives to declare your commodities. In fact
|
|
|
|
|
the commodity directive performs several functions at once:
|
|
|
|
|
The commodity directive performs several functions:
|
|
|
|
|
|
|
|
|
|
1. It declares commodities which may be used in the journal. This can
|
|
|
|
|
optionally be enforced, providing useful error checking. (Cf Com-
|
|
|
|
|
modity error checking)
|
|
|
|
|
1. It declares which commodity symbols may be used in the journal, en-
|
|
|
|
|
abling useful error checking with strict mode or the check command.
|
|
|
|
|
(See Commodity error checking below.)
|
|
|
|
|
|
|
|
|
|
2. It declares which decimal mark character (period or comma), to ex-
|
|
|
|
|
pect when parsing input - useful to disambiguate international num-
|
|
|
|
|
ber formats in your data. Without this, hledger will parse both
|
|
|
|
|
1,000 and 1.000 as 1. (Cf Amounts)
|
|
|
|
|
2. It declares the precision with which this commodity's amounts should
|
|
|
|
|
be compared when checking for balanced transactions.
|
|
|
|
|
|
|
|
|
|
3. It declares how to render the commodity's amounts when displaying
|
|
|
|
|
output - the decimal mark, any digit group marks, the number of dec-
|
|
|
|
|
imal places, symbol placement and so on. (Cf Commodity display
|
|
|
|
|
style)
|
|
|
|
|
3. It declares how this commodity's amounts should be displayed, eg
|
|
|
|
|
their symbol placement, digit group mark if any, digit group sizes,
|
|
|
|
|
decimal mark (period or comma), and the number of decimal places.
|
|
|
|
|
(See Commodity display style above.)
|
|
|
|
|
|
|
|
|
|
You will run into one of the problems solved by commodity directives
|
|
|
|
|
sooner or later, so we recommend using them, for robust and predictable
|
|
|
|
|
parsing and display.
|
|
|
|
|
4. It sets which decimal mark (period or comma) to expect when parsing
|
|
|
|
|
subsequent amounts in this commodity (if there is no decimal-mark
|
|
|
|
|
directive in effect. See Decimal marks, digit group marks above.
|
|
|
|
|
For related dev discussion, see #793.)
|
|
|
|
|
|
|
|
|
|
Generally you should put them at the top of your journal file (since
|
|
|
|
|
for function 2, they affect only following amounts, cf #793).
|
|
|
|
|
Declaring commodities solves several common parsing/display problems,
|
|
|
|
|
so we recommend it. Generally you should put commodity directives at
|
|
|
|
|
the top of your journal file (because function 4 is position-sensi-
|
|
|
|
|
tive).
|
|
|
|
|
|
|
|
|
|
A commodity directive is just the word commodity followed by a sample
|
|
|
|
|
amount, like this:
|
|
|
|
|
|
|
|
|
|
;commodity SAMPLEAMOUNT
|
|
|
|
|
Commodity directive syntax
|
|
|
|
|
A commodity directive is normally the word commodity followed by a sam-
|
|
|
|
|
ple amount (and optionally a comment). Only the amount's symbol and
|
|
|
|
|
format is significant. Eg:
|
|
|
|
|
|
|
|
|
|
commodity $1000.00
|
|
|
|
|
commodity 1,000.0000 AAAA ; optional same-line comment
|
|
|
|
|
commodity 1.000,00 EUR
|
|
|
|
|
commodity 1 000 000.0000 ; the no-symbol commodity
|
|
|
|
|
|
|
|
|
|
It may also be written on multiple lines, and use the format subdirec-
|
|
|
|
|
tive, as in Ledger. Note in this case the commodity symbol appears
|
|
|
|
|
twice; it must be the same in both places:
|
|
|
|
|
A commodity directive's sample amount must always include a period or
|
|
|
|
|
comma decimal mark (this rule helps disambiguate decimal marks and
|
|
|
|
|
digit group marks). If you don't want to show any decimal digits,
|
|
|
|
|
write the decimal mark at the end:
|
|
|
|
|
|
|
|
|
|
;commodity SYMBOL
|
|
|
|
|
; format SAMPLEAMOUNT
|
|
|
|
|
commodity 1000. AAAA ; show AAAA with no decimals
|
|
|
|
|
|
|
|
|
|
Commodity symbols containing spaces, numbers, or punctuation must be
|
|
|
|
|
enclosed in double quotes, as usual:
|
|
|
|
|
|
|
|
|
|
commodity 1.0000 "AAAA 2023"
|
|
|
|
|
|
|
|
|
|
Commodity directives normally include a sample amount, but can declare
|
|
|
|
|
only a symbol (ie, just function 1 above):
|
|
|
|
|
|
|
|
|
|
commodity $
|
|
|
|
|
commodity INR
|
|
|
|
|
commodity "AAAA 2023"
|
|
|
|
|
commodity "" ; the no-symbol commodity
|
|
|
|
|
|
|
|
|
|
Commodity directives may also be written with an indented format subdi-
|
|
|
|
|
rective, as in Ledger. The symbol is repeated and must be the same in
|
|
|
|
|
both places. Other subdirectives are currently ignored:
|
|
|
|
|
|
|
|
|
|
; display indian rupees with currency name on the left,
|
|
|
|
|
; thousands, lakhs and crores comma-separated,
|
|
|
|
|
; period as decimal point, and two decimal places.
|
|
|
|
|
commodity INR
|
|
|
|
|
format INR 1,00,00,000.00
|
|
|
|
|
|
|
|
|
|
Other indented subdirectives are currently ignored.
|
|
|
|
|
|
|
|
|
|
Remember that if the commodity symbol contains spaces, numbers, or
|
|
|
|
|
punctuation, it must be enclosed in double quotes (cf Commodity).
|
|
|
|
|
|
|
|
|
|
The amount's quantity does not matter; only the format is significant.
|
|
|
|
|
It must include a decimal mark - either a period or a comma - followed
|
|
|
|
|
by 0 or more decimal digits.
|
|
|
|
|
|
|
|
|
|
A few more examples:
|
|
|
|
|
|
|
|
|
|
# number formats for $, EUR, INR and the no-symbol commodity:
|
|
|
|
|
commodity $1,000.00
|
|
|
|
|
commodity EUR 1.000,00
|
|
|
|
|
commodity INR 9,99,99,999.0
|
|
|
|
|
commodity 1 000 000.
|
|
|
|
|
|
|
|
|
|
Note hledger normally uses banker's rounding, so 0.5 displayed with
|
|
|
|
|
zero decimal digits is "0". (More at Commodity display style.)
|
|
|
|
|
|
|
|
|
|
Even in the presence of commodity directives, the commodity display
|
|
|
|
|
style can still be overridden by supplying a command line option.
|
|
|
|
|
an unsupported subdirective ; ignored by hledger
|
|
|
|
|
|
|
|
|
|
Commodity error checking
|
|
|
|
|
In strict mode, enabled with the -s/--strict flag, hledger will report
|
|
|
|
|
an error if a commodity symbol is used that has not been declared by a
|
|
|
|
|
commodity directive. This works similarly to account error checking,
|
|
|
|
|
see the notes there for more details.
|
|
|
|
|
|
|
|
|
|
Note, this disallows amounts without a commodity symbol, because cur-
|
|
|
|
|
rently it's not possible (?) to declare the "no-symbol" commodity with
|
|
|
|
|
a directive. This is one exception for convenience: zero amounts are
|
|
|
|
|
always allowed to have no commodity symbol.
|
|
|
|
|
In strict mode (-s/--strict) (or when you run hledger check commodi-
|
|
|
|
|
ties), hledger will report an error if an undeclared commodity symbol
|
|
|
|
|
is used. (With one exception: zero amounts are always allowed to have
|
|
|
|
|
no commodity symbol.) It works like account error checking (described
|
|
|
|
|
above).
|
|
|
|
|
|
|
|
|
|
decimal-mark directive
|
|
|
|
|
You can use a decimal-mark directive - usually one per file, at the top
|
|
|
|
|
@ -3012,9 +3031,9 @@ CSV
|
|
|
|
|
To assign a value to a hledger field, write the field name (any of the
|
|
|
|
|
standard hledger field/pseudo-field names, defined below), a space,
|
|
|
|
|
followed by a text value on the same line. This text value may inter-
|
|
|
|
|
polate CSV fields, referenced by their 1-based position in the CSV
|
|
|
|
|
record (%N), or by the name they were given in the fields list (%CSV-
|
|
|
|
|
FIELD).
|
|
|
|
|
polate CSV fields, referenced either by their 1-based position in the
|
|
|
|
|
CSV record (%N) or by the name they were given in the fields list
|
|
|
|
|
(%CSVFIELD), and regular expression match groups (\N).
|
|
|
|
|
|
|
|
|
|
Some examples:
|
|
|
|
|
|
|
|
|
|
@ -3264,7 +3283,29 @@ CSV
|
|
|
|
|
o When a matcher is preceded by ampersand (&) it will be AND'ed with
|
|
|
|
|
the previous matcher (both of them must match).
|
|
|
|
|
|
|
|
|
|
There's not yet an easy syntax to negate a matcher.
|
|
|
|
|
When a matcher is preceded by an exclamation mark (!), the matcher will
|
|
|
|
|
be negated, ie it will exclude CSV records that match.
|
|
|
|
|
|
|
|
|
|
Match groups
|
|
|
|
|
Matchers can define match groups: parenthesised portions of the regular
|
|
|
|
|
expression which are available for reference in field assignments.
|
|
|
|
|
Groups are enclosed in regular parentheses (( and )) and can be nested.
|
|
|
|
|
Each group is available in field assignments using the token \N, where
|
|
|
|
|
N is an index into the match groups for this conditional block (e.g.
|
|
|
|
|
\1, \2, etc.).
|
|
|
|
|
|
|
|
|
|
Example: Warp credit card payment postings to the beginning of the
|
|
|
|
|
billing period (Month start), to match how they are presented in state-
|
|
|
|
|
ments, using posting dates:
|
|
|
|
|
|
|
|
|
|
if %date (....-..)-..
|
|
|
|
|
comment2 date:\1-01
|
|
|
|
|
|
|
|
|
|
Another example: Read the expense account from the CSV field, but throw
|
|
|
|
|
away a prefix:
|
|
|
|
|
|
|
|
|
|
if %account1 liabilities:family:(expenses:.*)
|
|
|
|
|
account1 \1
|
|
|
|
|
|
|
|
|
|
if table
|
|
|
|
|
"if tables" are an alternative to if blocks; they can express many
|
|
|
|
|
@ -3277,18 +3318,21 @@ CSV
|
|
|
|
|
MATCHERC,VALUE1,VALUE2,...
|
|
|
|
|
<empty line>
|
|
|
|
|
|
|
|
|
|
The first character after if is taken to be the separator for the rest
|
|
|
|
|
of the table. It should be a non-alphanumeric character like , or |
|
|
|
|
|
that does not appear anywhere else in the table. (Note: it is unre-
|
|
|
|
|
lated to the CSV file's separator.) Whitespace can be used in the
|
|
|
|
|
matcher lines for readability, but not in the if line currently. The
|
|
|
|
|
table must be terminated by an empty line (or end of file). Each line
|
|
|
|
|
must contain the same number of separators; empty values are allowed.
|
|
|
|
|
The first character after if is taken to be this if table's field sepa-
|
|
|
|
|
rator. It is unrelated to the separator used in the CSV file. It
|
|
|
|
|
should be a non-alphanumeric character like , or | that does not appear
|
|
|
|
|
anywhere else in the table (it should not be used in field names or
|
|
|
|
|
matchers or values, and it cannot be escaped with a backslash).
|
|
|
|
|
|
|
|
|
|
The above means: try all of the matchers; whenever a matcher succeeds,
|
|
|
|
|
assign all of the values on that line to the corresponding hledger
|
|
|
|
|
fields; later lines can overrider earlier ones. It is equivalent to
|
|
|
|
|
this sequence of if blocks:
|
|
|
|
|
Each line must contain the same number of separators; empty values are
|
|
|
|
|
allowed. Whitespace can be used in the matcher lines for readability
|
|
|
|
|
(but not in the if line, currently). The table must be terminated by
|
|
|
|
|
an empty line (or end of file).
|
|
|
|
|
|
|
|
|
|
An if table like the above is interpreted as follows: try all of the
|
|
|
|
|
matchers; whenever a matcher succeeds, assign all of the values on that
|
|
|
|
|
line to the corresponding hledger fields; later lines can overrider
|
|
|
|
|
earlier ones. It is equivalent to this sequence of if blocks:
|
|
|
|
|
|
|
|
|
|
if MATCHERA
|
|
|
|
|
HLEDGERFIELD1 VALUE1
|
|
|
|
|
@ -4165,6 +4209,53 @@ Timedot
|
|
|
|
|
A sample.timedot file.
|
|
|
|
|
|
|
|
|
|
PART 3: REPORTING CONCEPTS
|
|
|
|
|
Amount formatting, parseability
|
|
|
|
|
If you're wondering why your print report sometimes shows trailing dec-
|
|
|
|
|
imal marks, even when there are no decimal digits; it does this to dis-
|
|
|
|
|
ambiguate ambiguous amounts (amounts which have one digit group mark
|
|
|
|
|
and no decimal digits), allowing them to be re-parsed reliably.
|
|
|
|
|
|
|
|
|
|
More generally: hledger output falls into three rough categories, which
|
|
|
|
|
format amounts a little bit differently to suit different consumers:
|
|
|
|
|
|
|
|
|
|
1. "hledger-readable output" - should be readable by hledger (and by
|
|
|
|
|
humans)
|
|
|
|
|
|
|
|
|
|
o This is produced by reports that show full journal entries: print,
|
|
|
|
|
import, close, rewrite etc.
|
|
|
|
|
|
|
|
|
|
o It shows amounts with their original journal precisions, which may
|
|
|
|
|
not be consistent.
|
|
|
|
|
|
|
|
|
|
o It adds a trailing decimal mark when needed to avoid showing ambigu-
|
|
|
|
|
ous amounts.
|
|
|
|
|
|
|
|
|
|
o It can be parsed reliably (by hledger and ledger2beancount at least,
|
|
|
|
|
but perhaps not by Ledger..)
|
|
|
|
|
|
|
|
|
|
2. "human-readable output" - usually for humans
|
|
|
|
|
|
|
|
|
|
o This is produced by all other reports.
|
|
|
|
|
|
|
|
|
|
o It shows amounts with standard display precisions, which will be con-
|
|
|
|
|
sistent within each commodity.
|
|
|
|
|
|
|
|
|
|
o It shows ambiguous amounts unmodified.
|
|
|
|
|
|
|
|
|
|
o It can be parsed reliably in the context of a known report (when you
|
|
|
|
|
know decimals are consistently not being shown, you can assume a sin-
|
|
|
|
|
gle mark is a digit group mark).
|
|
|
|
|
|
|
|
|
|
3. "machine-readable output" - usually for other software
|
|
|
|
|
|
|
|
|
|
o This is produced by all reports when an output format like csv, tsv,
|
|
|
|
|
json, or sql is selected.
|
|
|
|
|
|
|
|
|
|
o It shows amounts as 1 or 2 do, but without digit group marks.
|
|
|
|
|
|
|
|
|
|
o It can be parsed reliably (if needed, the decimal mark can be changed
|
|
|
|
|
with -c/--commodity-style).
|
|
|
|
|
|
|
|
|
|
Time periods
|
|
|
|
|
Report start & end date
|
|
|
|
|
By default, most hledger reports will show the full span of time repre-
|
|
|
|
|
@ -5127,21 +5218,29 @@ Value reporting
|
|
|
|
|
that.
|
|
|
|
|
|
|
|
|
|
Valuation date
|
|
|
|
|
Since market prices can change from day to day, market value reports
|
|
|
|
|
have a valuation date (or more than one), which determines which market
|
|
|
|
|
prices will be used.
|
|
|
|
|
Market prices can change from day to day. hledger will use the prices
|
|
|
|
|
on a particular valuation date (or on more than one date). By default
|
|
|
|
|
hledger uses "end" dates for valuation. More specifically:
|
|
|
|
|
|
|
|
|
|
For single period reports, if an explicit report end date is specified,
|
|
|
|
|
that will be used as the valuation date; otherwise the valuation date
|
|
|
|
|
is the journal's end date.
|
|
|
|
|
o For single period reports (including normal print and register re-
|
|
|
|
|
ports):
|
|
|
|
|
|
|
|
|
|
For multiperiod reports, each column/period is valued on the last day
|
|
|
|
|
of the period, by default.
|
|
|
|
|
o If an explicit report end date is specified, that is used
|
|
|
|
|
|
|
|
|
|
o Otherwise the latest transaction date or P directive date is used
|
|
|
|
|
(even if it's in the future)
|
|
|
|
|
|
|
|
|
|
o For multiperiod reports, each period is valued on its last day.
|
|
|
|
|
|
|
|
|
|
This can be customised with the --value option described below, which
|
|
|
|
|
can select either "then", "end", "now", or "custom" dates. (Note, this
|
|
|
|
|
has a bug in hledger-ui <=1.31: turning on valuation with the V key al-
|
|
|
|
|
ways resets it to "end".)
|
|
|
|
|
|
|
|
|
|
Finding market price
|
|
|
|
|
To convert a commodity A to its market value in another commodity B,
|
|
|
|
|
hledger looks for a suitable market price (exchange rate) as follows,
|
|
|
|
|
in this order of preference :
|
|
|
|
|
in this order of preference:
|
|
|
|
|
|
|
|
|
|
1. A declared market price or inferred market price: A's latest market
|
|
|
|
|
price in B on or before the valuation date as declared by a P direc-
|
|
|
|
|
@ -5422,38 +5521,6 @@ Value reporting
|
|
|
|
|
2000-03-01
|
|
|
|
|
(a) 1 B
|
|
|
|
|
|
|
|
|
|
You may need to explicitly set a commodity's display style, when re-
|
|
|
|
|
verse prices are used. Eg this output might be surprising:
|
|
|
|
|
|
|
|
|
|
P 2000-01-01 A 2B
|
|
|
|
|
|
|
|
|
|
2000-01-01
|
|
|
|
|
a 1B
|
|
|
|
|
b
|
|
|
|
|
|
|
|
|
|
$ hledger print -x -X A
|
|
|
|
|
2000-01-01
|
|
|
|
|
a 0
|
|
|
|
|
b 0
|
|
|
|
|
|
|
|
|
|
Explanation: because there's no amount or commodity directive specify-
|
|
|
|
|
ing a display style for A, 0.5A gets the default style, which shows no
|
|
|
|
|
decimal digits. Because the displayed amount looks like zero, the com-
|
|
|
|
|
modity symbol and minus sign are not displayed either. Adding a com-
|
|
|
|
|
modity directive sets a more useful display style for A:
|
|
|
|
|
|
|
|
|
|
P 2000-01-01 A 2B
|
|
|
|
|
commodity 0.00A
|
|
|
|
|
|
|
|
|
|
2000-01-01
|
|
|
|
|
a 1B
|
|
|
|
|
b
|
|
|
|
|
|
|
|
|
|
$ hledger print -X A
|
|
|
|
|
2000-01-01
|
|
|
|
|
a 0.50A
|
|
|
|
|
b -0.50A
|
|
|
|
|
|
|
|
|
|
Interaction of valuation and queries
|
|
|
|
|
When matching postings based on queries in the presence of valuation,
|
|
|
|
|
the following happens.
|
|
|
|
|
@ -5901,18 +5968,22 @@ PART 4: COMMANDS
|
|
|
|
|
--align-all flag.
|
|
|
|
|
|
|
|
|
|
This command also supports the output destination and output format op-
|
|
|
|
|
tions. The output formats supported are txt, csv, and json.
|
|
|
|
|
tions. The output formats supported are txt, csv, tsv, and json.
|
|
|
|
|
|
|
|
|
|
aregister and custom posting dates
|
|
|
|
|
Transactions whose date is outside the report period can still be
|
|
|
|
|
shown, if they have a posting to this account dated inside the report
|
|
|
|
|
period. (And in this case it's the posting date that is shown.) This
|
|
|
|
|
ensures that aregister can show an accurate historical running balance,
|
|
|
|
|
matching the one shown by register -H with the same arguments.
|
|
|
|
|
aregister and posting dates
|
|
|
|
|
aregister always shows one line (and date and amount) per transaction.
|
|
|
|
|
But sometimes transactions have postings with different dates. Also,
|
|
|
|
|
not all of a transaction's postings may be within the report period.
|
|
|
|
|
To resolve this, aregister shows the earliest of the transaction's date
|
|
|
|
|
and posting dates that is in-period, and the sum of the in-period post-
|
|
|
|
|
ings. In other words it will show a combined line item with just the
|
|
|
|
|
earliest date, and the running balance will (temporarily, until the
|
|
|
|
|
transaction's last posting) be inaccurate. Use register -H if you need
|
|
|
|
|
to see the individual postings.
|
|
|
|
|
|
|
|
|
|
To filter strictly by transaction date instead, add the --txn-dates
|
|
|
|
|
flag. If you use this flag and some of your postings have custom
|
|
|
|
|
dates, it's probably best to assume the running balance is wrong.
|
|
|
|
|
There is also a --txn-dates flag, which filters strictly by transaction
|
|
|
|
|
date, ignoring posting dates. This too can cause an inaccurate running
|
|
|
|
|
balance.
|
|
|
|
|
|
|
|
|
|
balance
|
|
|
|
|
(bal)
|
|
|
|
|
@ -5996,9 +6067,9 @@ PART 4: COMMANDS
|
|
|
|
|
o commodities displayed on the same line or multiple lines (--layout)
|
|
|
|
|
|
|
|
|
|
This command supports the output destination and output format options,
|
|
|
|
|
with output formats txt, csv, json, and (multi-period reports only:)
|
|
|
|
|
html. In txt output in a colour-supporting terminal, negative amounts
|
|
|
|
|
are shown in red.
|
|
|
|
|
with output formats txt, csv, tsv, json, and (multi-period reports
|
|
|
|
|
only:) html. In txt output in a colour-supporting terminal, negative
|
|
|
|
|
amounts are shown in red.
|
|
|
|
|
|
|
|
|
|
The --related/-r flag shows the balance of the other postings in the
|
|
|
|
|
transactions of the postings which would normally be shown.
|
|
|
|
|
@ -6970,8 +7041,8 @@ PART 4: COMMANDS
|
|
|
|
|
flipped.
|
|
|
|
|
|
|
|
|
|
This command also supports the output destination and output format op-
|
|
|
|
|
tions The output formats supported are txt, csv, html, and (experimen-
|
|
|
|
|
tal) json.
|
|
|
|
|
tions The output formats supported are txt, csv, tsv, html, and (exper-
|
|
|
|
|
imental) json.
|
|
|
|
|
|
|
|
|
|
balancesheetequity
|
|
|
|
|
(bse)
|
|
|
|
|
@ -7018,8 +7089,8 @@ PART 4: COMMANDS
|
|
|
|
|
sign flipped.
|
|
|
|
|
|
|
|
|
|
This command also supports the output destination and output format op-
|
|
|
|
|
tions The output formats supported are txt, csv, html, and (experimen-
|
|
|
|
|
tal) json.
|
|
|
|
|
tions The output formats supported are txt, csv, tsv, html, and (exper-
|
|
|
|
|
imental) json.
|
|
|
|
|
|
|
|
|
|
cashflow
|
|
|
|
|
(cf)
|
|
|
|
|
@ -7066,8 +7137,8 @@ PART 4: COMMANDS
|
|
|
|
|
not:receivable, but with smarter account detection.
|
|
|
|
|
|
|
|
|
|
This command also supports the output destination and output format op-
|
|
|
|
|
tions The output formats supported are txt, csv, html, and (experimen-
|
|
|
|
|
tal) json.
|
|
|
|
|
tions The output formats supported are txt, csv, tsv, html, and (exper-
|
|
|
|
|
imental) json.
|
|
|
|
|
|
|
|
|
|
check
|
|
|
|
|
Check for various kinds of errors in your data.
|
|
|
|
|
@ -7481,10 +7552,10 @@ PART 4: COMMANDS
|
|
|
|
|
$ hledger help -m journal # show it with man, even if info is installed
|
|
|
|
|
|
|
|
|
|
import
|
|
|
|
|
Read new transactions added to each FILE since last run, and add them
|
|
|
|
|
to the journal. Or with --dry-run, just print the transactions that
|
|
|
|
|
would be added. Or with --catchup, just mark all of the FILEs' trans-
|
|
|
|
|
actions as imported, without actually importing any.
|
|
|
|
|
Read new transactions added to each FILE provided as arguments since
|
|
|
|
|
last run, and add them to the journal. Or with --dry-run, just print
|
|
|
|
|
the transactions that would be added. Or with --catchup, just mark all
|
|
|
|
|
of the FILEs' current transactions as imported, without importing them.
|
|
|
|
|
|
|
|
|
|
This command may append new transactions to the main journal file
|
|
|
|
|
(which should be in journal format). Existing transactions are not
|
|
|
|
|
@ -7501,14 +7572,14 @@ PART 4: COMMANDS
|
|
|
|
|
common import source, and these docs focus on that case.
|
|
|
|
|
|
|
|
|
|
Deduplication
|
|
|
|
|
As a convenience import does deduplication while reading transactions.
|
|
|
|
|
This does not mean "ignore transactions that look the same", but rather
|
|
|
|
|
"ignore transactions that have been seen before". This is intended for
|
|
|
|
|
when you are periodically importing foreign data which may contain al-
|
|
|
|
|
ready-imported transactions. So eg, if every day you download bank CSV
|
|
|
|
|
files containing redundant data, you can safely run hledger import
|
|
|
|
|
bank.csv and only new transactions will be imported. (import is idem-
|
|
|
|
|
potent.)
|
|
|
|
|
import does time-based deduplication, to detect only the new transac-
|
|
|
|
|
tions since the last successful import. (This does not mean "ignore
|
|
|
|
|
transactions that look the same", but rather "ignore transactions that
|
|
|
|
|
have been seen before".) This is intended for when you are periodi-
|
|
|
|
|
cally importing downloaded data, which may overlap with previous down-
|
|
|
|
|
loads. Eg if every week (or every day) you download a bank's last
|
|
|
|
|
three months of CSV data, you can safely run hledger import thebank.csv
|
|
|
|
|
each time and only new transactions will be imported.
|
|
|
|
|
|
|
|
|
|
Since the items being read (CSV records, eg) often do not come with
|
|
|
|
|
unique identifiers, hledger detects new transactions by date, assuming
|
|
|
|
|
@ -7528,10 +7599,12 @@ PART 4: COMMANDS
|
|
|
|
|
be the ones affected).
|
|
|
|
|
|
|
|
|
|
hledger remembers the latest date processed in each input file by sav-
|
|
|
|
|
ing a hidden ".latest" state file in the same directory. Eg when read-
|
|
|
|
|
ing finance/bank.csv, it will look for and update the finance/.lat-
|
|
|
|
|
est.bank.csv state file. The format is simple: one or more lines con-
|
|
|
|
|
taining the same ISO-format date (YYYY-MM-DD), meaning "I have
|
|
|
|
|
ing a hidden ".latest.FILE" file in FILE's directory (after a succesful
|
|
|
|
|
import).
|
|
|
|
|
|
|
|
|
|
Eg when reading finance/bank.csv, it will look for and update the fi-
|
|
|
|
|
nance/.latest.bank.csv state file. The format is simple: one or more
|
|
|
|
|
lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have
|
|
|
|
|
processed transactions up to this date, and this many of them on that
|
|
|
|
|
date." Normally you won't see or manipulate these state files yourself.
|
|
|
|
|
But if needed, you can delete them to reset the state (making all
|
|
|
|
|
@ -7622,8 +7695,8 @@ PART 4: COMMANDS
|
|
|
|
|
sign flipped.
|
|
|
|
|
|
|
|
|
|
This command also supports the output destination and output format op-
|
|
|
|
|
tions The output formats supported are txt, csv, html, and (experimen-
|
|
|
|
|
tal) json.
|
|
|
|
|
tions The output formats supported are txt, csv, tsv, html, and (exper-
|
|
|
|
|
imental) json.
|
|
|
|
|
|
|
|
|
|
notes
|
|
|
|
|
List the unique notes that appear in transactions.
|
|
|
|
|
@ -7660,11 +7733,20 @@ PART 4: COMMANDS
|
|
|
|
|
Person A
|
|
|
|
|
|
|
|
|
|
prices
|
|
|
|
|
Print market price directives from the journal. With --infer-market-
|
|
|
|
|
prices, generate additional market prices from costs. With --infer-re-
|
|
|
|
|
verse-prices, also generate market prices by inverting known prices.
|
|
|
|
|
Prices can be filtered by a query. Price amounts are displayed with
|
|
|
|
|
their full precision.
|
|
|
|
|
Print the market prices declared with P directives. With --infer-mar-
|
|
|
|
|
ket-prices, also show any additional prices inferred from costs. With
|
|
|
|
|
--show-reverse, also show additional prices inferred by reversing known
|
|
|
|
|
prices.
|
|
|
|
|
|
|
|
|
|
Price amounts are always displayed with their full precision, except
|
|
|
|
|
for reverse prices which are limited to 8 decimal digits.
|
|
|
|
|
|
|
|
|
|
Prices can be filtered by a date:, cur: or amt: query.
|
|
|
|
|
|
|
|
|
|
Generally if you run this command with --infer-market-prices --show-re-
|
|
|
|
|
verse, it will show the same prices used internally to calculate value
|
|
|
|
|
reports. But if in doubt, you can inspect those directly by running
|
|
|
|
|
the value report with --debug=2.
|
|
|
|
|
|
|
|
|
|
print
|
|
|
|
|
Show transaction journal entries, sorted by date.
|
|
|
|
|
@ -7672,26 +7754,14 @@ PART 4: COMMANDS
|
|
|
|
|
The print command displays full journal entries (transactions) from the
|
|
|
|
|
journal file, sorted by date (or with --date2, by secondary date).
|
|
|
|
|
|
|
|
|
|
Amounts are shown mostly normalised to commodity display style, eg the
|
|
|
|
|
placement of commodity symbols will be consistent. All of their deci-
|
|
|
|
|
mal places are shown, as in the original journal entry (with one alter-
|
|
|
|
|
ation: in some cases trailing zeroes are added.)
|
|
|
|
|
|
|
|
|
|
Amounts are shown right-aligned within each transaction (but not across
|
|
|
|
|
all transactions).
|
|
|
|
|
|
|
|
|
|
Directives and inter-transaction comments are not shown, currently.
|
|
|
|
|
This means the print command is somewhat lossy, and if you are using it
|
|
|
|
|
to reformat your journal you should take care to also copy over the di-
|
|
|
|
|
rectives and file-level comments.
|
|
|
|
|
to reformat/regenerate your journal you should take care to also copy
|
|
|
|
|
over the directives and inter-transaction comments.
|
|
|
|
|
|
|
|
|
|
Eg:
|
|
|
|
|
|
|
|
|
|
$ hledger print
|
|
|
|
|
2008/01/01 income
|
|
|
|
|
assets:bank:checking $1
|
|
|
|
|
income:salary $-1
|
|
|
|
|
|
|
|
|
|
$ hledger print -f examples/sample.journal date:200806
|
|
|
|
|
2008/06/01 gift
|
|
|
|
|
assets:bank:checking $1
|
|
|
|
|
income:gifts $-1
|
|
|
|
|
@ -7705,13 +7775,56 @@ PART 4: COMMANDS
|
|
|
|
|
expenses:supplies $1
|
|
|
|
|
assets:cash $-2
|
|
|
|
|
|
|
|
|
|
2008/12/31 * pay off
|
|
|
|
|
liabilities:debts $1
|
|
|
|
|
assets:bank:checking $-1
|
|
|
|
|
print explicitness
|
|
|
|
|
Normally, whether posting amounts are implicit or explicit is pre-
|
|
|
|
|
served. For example, when an amount is omitted in the journal, it will
|
|
|
|
|
not appear in the output. Similarly, if a conversion cost is implied
|
|
|
|
|
but not written, it will not appear in the output.
|
|
|
|
|
|
|
|
|
|
You can use the -x/--explicit flag to force explicit display of all
|
|
|
|
|
amounts and costs. This can be useful for troubleshooting or for mak-
|
|
|
|
|
ing your journal more readable and robust against data entry errors.
|
|
|
|
|
-x is also implied by using any of -B,-V,-X,--value.
|
|
|
|
|
|
|
|
|
|
The -x/--explicit flag will cause any postings with a multi-commodity
|
|
|
|
|
amount (which can arise when a multi-commodity transaction has an im-
|
|
|
|
|
plicit amount) to be split into multiple single-commodity postings,
|
|
|
|
|
keeping the output parseable.
|
|
|
|
|
|
|
|
|
|
print amount style
|
|
|
|
|
Amounts are shown right-aligned within each transaction (but not
|
|
|
|
|
aligned across all transactions; you can do that with ledger-mode in
|
|
|
|
|
Emacs).
|
|
|
|
|
|
|
|
|
|
Amounts will be (mostly) normalised to their commodity display style:
|
|
|
|
|
their symbol placement, decimal mark, and digit group marks will be
|
|
|
|
|
made consistent. By default, decimal digits are shown as they are
|
|
|
|
|
written in the journal.
|
|
|
|
|
|
|
|
|
|
With the --round option, print will try increasingly hard to display
|
|
|
|
|
decimal digits according to the commodity display styles:
|
|
|
|
|
|
|
|
|
|
o --round=none show amounts with original precisions (default)
|
|
|
|
|
|
|
|
|
|
o --round=soft add/remove decimal zeros in amounts (except costs)
|
|
|
|
|
|
|
|
|
|
o --round=hard round amounts (except costs), possibly hiding signifi-
|
|
|
|
|
cant digits
|
|
|
|
|
|
|
|
|
|
o --round=all round all amounts and costs
|
|
|
|
|
|
|
|
|
|
soft is good for non-lossy cleanup, formatting amounts more consis-
|
|
|
|
|
tently where it's safe to do so.
|
|
|
|
|
|
|
|
|
|
hard and all can cause print to show invalid unbalanced journal en-
|
|
|
|
|
tries; they may be useful eg for stronger cleanup, with manual fixups
|
|
|
|
|
when needed.
|
|
|
|
|
|
|
|
|
|
print parseability
|
|
|
|
|
print's output is usually a valid hledger journal, and you can process
|
|
|
|
|
it again with a second hledger command. This can be useful for certain
|
|
|
|
|
kinds of search, eg:
|
|
|
|
|
kinds of search (though the same can be achieved with expr: queries
|
|
|
|
|
now):
|
|
|
|
|
|
|
|
|
|
# Show running total of food expenses paid from cash.
|
|
|
|
|
# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
|
|
|
|
|
@ -7726,36 +7839,41 @@ PART 4: COMMANDS
|
|
|
|
|
|
|
|
|
|
o Account aliases can generate bad account names.
|
|
|
|
|
|
|
|
|
|
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 cost is implied but not
|
|
|
|
|
written, it will not appear in the output. You can use the -x/--ex-
|
|
|
|
|
plicit flag to make all amounts and costs explicit, 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.
|
|
|
|
|
print, other features
|
|
|
|
|
With -B/--cost, amounts with costs are shown converted to cost.
|
|
|
|
|
|
|
|
|
|
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 --new, print shows only transactions it has not seen on a previous
|
|
|
|
|
run. This uses the same deduplication system as the import command.
|
|
|
|
|
(See import's docs for details.)
|
|
|
|
|
|
|
|
|
|
With -B/--cost, amounts with costs are converted to cost using that
|
|
|
|
|
price. This can be used for troubleshooting.
|
|
|
|
|
|
|
|
|
|
With -m DESC/--match=DESC, print does a fuzzy search for one recent
|
|
|
|
|
transaction whose description is most similar to DESC. DESC should
|
|
|
|
|
contain at least two characters. If there is no similar-enough match,
|
|
|
|
|
no transaction will be shown and the program exit code will be non-
|
|
|
|
|
zero.
|
|
|
|
|
|
|
|
|
|
With --new, hledger prints only transactions it has not seen on a pre-
|
|
|
|
|
vious run. This uses the same deduplication system as the import com-
|
|
|
|
|
mand. (See import's docs for details.)
|
|
|
|
|
With -m DESC/--match=DESC, print shows one recent transaction whose de-
|
|
|
|
|
scription is most similar to DESC. DESC should contain at least two
|
|
|
|
|
characters. If there is no similar-enough match, no transaction will
|
|
|
|
|
be shown and the program exit code will be non-zero.
|
|
|
|
|
|
|
|
|
|
print output format
|
|
|
|
|
This command also supports the output destination and output format op-
|
|
|
|
|
tions The output formats supported are txt, csv, and (experimental)
|
|
|
|
|
json and sql.
|
|
|
|
|
tions The output formats supported are txt, beancount, csv, tsv, json
|
|
|
|
|
and sql.
|
|
|
|
|
|
|
|
|
|
Experimental: The beancount format tries to produce Beancount-compati-
|
|
|
|
|
ble output. It is very basic and may require additional manual fixups:
|
|
|
|
|
|
|
|
|
|
o Transaction and postings with unmarked status are converted to
|
|
|
|
|
cleared (`*``) status.
|
|
|
|
|
|
|
|
|
|
o Transactions' payee and or note are wrapped in double quotes.
|
|
|
|
|
|
|
|
|
|
o Transaction tags are copied to Beancount #tag format.
|
|
|
|
|
|
|
|
|
|
o Account name parts are capitalised, and if the first account name
|
|
|
|
|
part is not one of Assets, Liabilities, Equity, Income, or Expenses,
|
|
|
|
|
"Equity:" is prepended.
|
|
|
|
|
|
|
|
|
|
o The $ commodity symbol is converted to USD.
|
|
|
|
|
|
|
|
|
|
o An open directive is generated for each account used, on the earliest
|
|
|
|
|
transaction date.
|
|
|
|
|
|
|
|
|
|
Here's an example of print's CSV output:
|
|
|
|
|
|
|
|
|
|
@ -7912,8 +8030,8 @@ PART 4: 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)
|
|
|
|
|
json.
|
|
|
|
|
tions The output formats supported are txt, csv, tsv, and (experimen-
|
|
|
|
|
tal) json.
|
|
|
|
|
|
|
|
|
|
rewrite
|
|
|
|
|
Print all transactions, rewriting the postings of matched transactions.
|
|
|
|
|
@ -8372,7 +8490,7 @@ PART 5: COMMON TASKS
|
|
|
|
|
On unix and mac, running these commands in the terminal will work for
|
|
|
|
|
many people; adapt as needed:
|
|
|
|
|
|
|
|
|
|
$ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile
|
|
|
|
|
$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
|
|
|
|
|
$ source ~/.profile
|
|
|
|
|
|
|
|
|
|
When correctly configured, in a new terminal window env | grep
|
|
|
|
|
@ -8759,6 +8877,12 @@ BUGS
|
|
|
|
|
$ echo "export LANG=en_US.utf8" >>~/.profile
|
|
|
|
|
# close and re-open terminal window
|
|
|
|
|
|
|
|
|
|
If you are using Nix (not NixOS) for GHC and Hledger, you might need to
|
|
|
|
|
set the LOCALE_ARCHIVE variable:
|
|
|
|
|
|
|
|
|
|
$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile
|
|
|
|
|
# close and re-open terminal window
|
|
|
|
|
|
|
|
|
|
COMPATIBILITY ISSUES: hledger gives an error with my Ledger file
|
|
|
|
|
Not all of Ledger's journal file syntax or feature set is supported.
|
|
|
|
|
See hledger and Ledger for full details.
|
|
|
|
|
@ -8781,4 +8905,4 @@ LICENSE
|
|
|
|
|
SEE ALSO
|
|
|
|
|
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
|
|
|
|
|
|
|
|
|
|
hledger-1.31.99 September 2023 HLEDGER(1)
|
|
|
|
|
hledger-1.31.99 November 2023 HLEDGER(1)
|
|
|
|
|
|
Simon Michael