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

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-09-24 18:09:45 -10:00
parent fdee9d93cf
commit 60a1c0b861
6 changed files with 789 additions and 713 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
hledger-ui/hledger-ui.1
View File

@ -406,14 +406,6 @@ until the next reload).
On this screen (and the register screen), the \f[CR]E\f[R] key will open On this screen (and the register screen), the \f[CR]E\f[R] key will open
your text editor with the cursor positioned at the current transaction your text editor with the cursor positioned at the current transaction
if possible. if possible.
.PP
This screen has a limitation with showing file updates: it will not show
them until you exit and re\-enter it.
So eg to see the effect of using the \f[CR]E\f[R] key, currently you
must: \- press \f[CR]E\f[R], edit and save the file, then exit the
editor, returning to hledger\-ui \- press \f[CR]g\f[R] to reload the
file (or use \f[CR]\-w/\-\-watch\f[R] mode) \- press \f[CR]LEFT\f[R]
then \f[CR]RIGHT\f[R] to exit and re\-enter the transaction screen.
.SS Error screen .SS Error screen
This screen will appear if there is a problem, such as a parse error, This screen will appear if there is a problem, such as a parse error,
when you press g to reload. when you press g to reload.
@ -495,10 +487,6 @@ stdin).
\f[CR]\-\-watch\f[R] is not robust, especially with large files (see \f[CR]\-\-watch\f[R] is not robust, especially with large files (see
WATCH MODE above). WATCH MODE above).
.PP .PP
The Transaction screen does not update after file changes, even if you
press \f[CR]g\f[R], until you exit and re\-enter it.
(#2288)
.PP
If you press \f[CR]g\f[R] with large files, there could be a noticeable If you press \f[CR]g\f[R] with large files, there could be a noticeable
pause with the UI unresponsive. pause with the UI unresponsive.

20
hledger-ui/hledger-ui.info
View File

@ -453,13 +453,6 @@ reload).
text editor with the cursor positioned at the current transaction if text editor with the cursor positioned at the current transaction if
possible. possible.
This screen has a limitation with showing file updates: it will not
show them until you exit and re-enter it. So eg to see the effect of
using the 'E' key, currently you must: - press 'E', edit and save the
file, then exit the editor, returning to hledger-ui - press 'g' to
reload the file (or use '-w/--watch' mode) - press 'LEFT' then 'RIGHT'
to exit and re-enter the transaction screen.
 
File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS
@ -556,9 +549,6 @@ We welcome bug reports in the hledger issue tracker
'--watch' is not robust, especially with large files (see WATCH MODE '--watch' is not robust, especially with large files (see WATCH MODE
above). above).
The Transaction screen does not update after file changes, even if
you press 'g', until you exit and re-enter it. (#2288)
If you press 'g' with large files, there could be a noticeable pause If you press 'g' with large files, there could be a noticeable pause
with the UI unresponsive. with the UI unresponsive.
@ -576,11 +566,11 @@ Node: Income statement accounts screen15844
Node: All accounts screen16229 Node: All accounts screen16229
Node: Register screen16592 Node: Register screen16592
Node: Transaction screen19035 Node: Transaction screen19035
Node: Error screen20610 Node: Error screen20215
Node: WATCH MODE20976 Node: WATCH MODE20581
Node: --watch problems21874 Node: --watch problems21479
Node: ENVIRONMENT23227 Node: ENVIRONMENT22832
Node: BUGS23460 Node: BUGS23065
 
End Tag Table End Tag Table

10
hledger-ui/hledger-ui.txt
View File

@ -366,13 +366,6 @@ SCREENS
editor with the cursor positioned at the current transaction if possi- editor with the cursor positioned at the current transaction if possi-
ble. ble.
This screen has a limitation with showing file updates: it will not
show them until you exit and re-enter it. So eg to see the effect of
using the E key, currently you must: - press E, edit and save the file,
then exit the editor, returning to hledger-ui - press g to reload the
file (or use -w/--watch mode) - press LEFT then RIGHT to exit and
re-enter the transaction screen.
Error screen Error screen
This screen will appear if there is a problem, such as a parse error, This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g when you press g to reload. Once you have fixed the problem, press g
@ -447,9 +440,6 @@ BUGS
--watch is not robust, especially with large files (see WATCH MODE --watch is not robust, especially with large files (see WATCH MODE
above). above).
The Transaction screen does not update after file changes, even if you
press g, until you exit and re-enter it. (#2288)
If you press g with large files, there could be a noticeable pause with If you press g with large files, there could be a noticeable pause with
the UI unresponsive. the UI unresponsive.

214
hledger/hledger.1
View File

@ -829,7 +829,7 @@ Here\[aq]s a small example:
\f[I]# Options following a \[ga][COMMAND]\[ga] heading are used with that hledger command only.\f[R] \f[I]# Options following a \[ga][COMMAND]\[ga] heading are used with that hledger command only.\f[R]
\f[B][print]\f[R] \f[B][print]\f[R]
\-\-explicit \-\-show\-costs \-\-explicit \-\-infer\-costs
.EE .EE
.PP .PP
To use a config file, specify it with the \f[CR]\-\-conf\f[R] option. To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.
@ -1413,7 +1413,7 @@ Editor add\-ons such as ledger\-mode or hledger\-mode for Emacs,
vim\-ledger for Vim, and hledger\-vscode for Visual Studio Code, make vim\-ledger for Vim, and hledger\-vscode for Visual Studio Code, make
this easier, adding colour, formatting, tab completion, and useful this easier, adding colour, formatting, tab completion, and useful
commands. commands.
See Editor configuration at hledger.org for the full list. See Editors at hledger.org for the full list.
.PP .PP
A hledger journal file can contain three kinds of thing: comment lines, A hledger journal file can contain three kinds of thing: comment lines,
transactions, and/or directives (including periodic transaction rules transactions, and/or directives (including periodic transaction rules
@ -1630,7 +1630,10 @@ dates documented in the hledger manual.)
.SS Posting dates .SS Posting dates
You can give individual postings a different date from their parent You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below) transaction, by adding a posting comment containing a tag (see below)
like \f[CR]date:DATE\f[R]. like \f[CR]; date:DATE\f[R].
(There\[aq]s also a Ledger\-compatible syntax, \f[CR]; [DATE]\f[R],
which can be convenient.)
.PP
This is probably the best way to control posting dates precisely. This is probably the best way to control posting dates precisely.
Eg in this example the expense should appear in May reports, and the Eg in this example the expense should appear in May reports, and the
deduction from checking should be reported on 6/1 for easy bank deduction from checking should be reported on 6/1 for easy bank
@ -1807,10 +1810,15 @@ is common), followed by:
(optional) a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R]), (optional) a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R]),
followed by a space followed by a space
.IP \[bu] 2 .IP \[bu] 2
(required) an account name (any text, optionally containing \f[B]single (required) an account name (any text, optionally including single
spaces\f[R], until end of line or a double space) spaces.
If anything follows the account name on the same line, the account name
must be ended by \f[B]two or more spaces\f[R].)
.IP \[bu] 2 .IP \[bu] 2
(optional) \f[B]two or more spaces\f[R] (or tabs) followed by an amount. (optional) an amount
.IP \[bu] 2
(optional) a same\-line posting comment, beginning with a semicolon
(\f[CR];\f[R]).
.PP .PP
If the amount is positive, it is being added to the account; if If the amount is positive, it is being added to the account; if
negative, it is being removed from the account. negative, it is being removed from the account.
@ -1818,14 +1826,15 @@ negative, it is being removed from the account.
The posting amounts in a transaction must sum up to zero, indicating The posting amounts in a transaction must sum up to zero, indicating
that the inflows and outflows are equal. that the inflows and outflows are equal.
We call this a balanced transaction. We call this a balanced transaction.
(You can read more about the nitty\-gritty details of \[dq]sum up to (You can read more about the details of transaction balancing below.)
zero\[dq] in Transaction balancing below.)
.PP .PP
As a convenience, you can optionally leave one amount blank; hledger If no amount is written, it will be calculated automatically from the
will infer what it should be so as to balance the transaction. other postings in the transaction, so as to balance the transaction.
In other words, in any transaction you can leave one posting amountless
to save typing.
.SS Debits and credits .SS Debits and credits
The traditional accounting concepts of debit and credit of course exist The traditional accounting concepts of debit and credit of course exist
in hledger, but we represent them with numeric sign, as described above. in hledger, but we represent them with numeric sign.
Positive and negative posting amounts represent debits and credits Positive and negative posting amounts represent debits and credits
respectively. respectively.
.PP .PP
@ -1838,33 +1847,66 @@ handy mnemonic:
.P .P
.PD .PD
\f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R] \f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R]
.SS The two space delimiter
Be sure to notice the unusual separator between the account name and the
following amount.
Because hledger allows account names with spaces in them, you must
separate the account name and amount (if any) by \f[B]two or more
spaces\f[R] (or tabs).
It\[aq]s easy to forget at first.
If you ever see the amount being treated as part of the account name,
you\[aq]ll know you probably need to add another space between them.
.SS Account names .SS Account names
Accounts are the main way of categorising things in hledger. Accounts are the main way of categorising things in hledger.
As in Double Entry Bookkeeping, they can represent real world accounts As in Double Entry Bookkeeping, they can represent real world accounts
(such as a bank account), or more abstract categories such as \[dq]money (such as a bank account), or more abstract categories such as \[dq]money
borrowed from Frank\[dq] or \[dq]money spent on electricity\[dq]. spent on food\[dq] or \[dq]money borrowed from Frank\[dq].
.PP
Account names are flexible.
They may be capitalised or not; they may contain letters, numbers,
punctuation, symbols, or single spaces; they may be in any language.
.PP
Typically we use the five traditional accounting categories as the
starting point for account names.
In english they are:
.PP .PP
You can use any account names you like, but we usually start with the
traditional accounting categories, which in english are
\f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R], \f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R],
\f[CR]revenues\f[R], \f[CR]expenses\f[R]. \f[CR]revenues\f[R], \f[CR]expenses\f[R]
(You might see these referred to as A, L, E, R, X for short.)
.PP .PP
For more precise reporting, we usually divide the top level accounts These will be discussed more in Account types below.
into more detailed subaccounts, by writing a full colon between account In hledger docs you may see them referred to as A, L, E, R, X for short.
name parts. .SS The two space delimiter
For example, from the account names \f[CR]assets:bank:checking\f[R] and Note the \f[B]two or more spaces\f[R] delimiter that\[aq]s sometimes
\f[CR]expenses:food\f[R], hledger will infer this hierarchy of five required after account names.
accounts: \ hledger\[aq]s account names, inherited from Ledger, are very
permissive; they may contain pretty much any kind of text, including
single spaces and semicolons.
Because of this, they must be terminated by \f[B]two or more spaces\f[R]
if there is anything following them on the same line.
For example, if an amount, balance assignment, or same\-line comment
follows an account name, they must be preceded by two or more spaces,
else they would be considered part of the account name:
.IP
.EX
bad: assets:accounts receivable $10 ; <\- too close!
good: assets:accounts receivable $10
.EE
.IP
.EX
bad: assets:accounts receivable =$1000 ; <\- too close!
good: assets:accounts receivable =$1000
.EE
.IP
.EX
bad: assets:accounts receivable ; comment. <\- too close!
good: assets:accounts receivable ; comment
.EE
.PP
This two\-space delimiter appears in a few places in hledger, such as
after account names in postings or account directives; also after the
period expression in periodic transaction rules.
When you are starting out, expect it to catch you out at least once.
It\[aq]s annoying sometimes, but it lets us use expressive account names
while still keeping the syntax light.
.SS Account hierarchy
For more precise reporting, we usually divide accounts into more
detailed subaccounts, subsubaccounts, and so on, by writing a full colon
between account name parts.
For example, instead of writing \f[CR]assets\f[R] and
\f[CR]expenses\f[R], we might write \f[CR]assets:bank:checking\f[R] and
\f[CR]expenses:food\f[R].
From these names hledger will infer this hierarchy of five accounts:
.IP .IP
.EX .EX
assets assets
@ -1874,7 +1916,7 @@ expenses
expenses:food expenses:food
.EE .EE
.PP .PP
Shown as an outline, the hierarchical tree structure is more clear: Or as an outline:
.IP .IP
.EX .EX
assets assets
@ -1885,21 +1927,16 @@ expenses
.EE .EE
.PP .PP
hledger reports can summarise the account tree to any depth, so you can hledger reports can summarise the account tree to any depth, so you can
go as deep as you like with subcategories, but keeping your account make your subcategories as detailed as you like.
names relatively simple may be best when starting out. But don\[aq]t go overboard, especially when getting started; simpler
categories can be less work.
.SS Other account name features
Enclosing the account name in parentheses or brackets, like
\f[CR](expenses:food)\f[R], enables a non\-standard bookkeeping feature:
virtual postings.
.PP .PP
Account names may be capitalised or not; they may contain letters, Account names can be rewritten and restructured, temporarily or
numbers, symbols, or single spaces. permanently, by account aliases.
Note, when an account name and an amount are written on the same line,
they must be separated by \f[B]two or more spaces\f[R] (or tabs).
.PP
Parentheses or brackets enclosing the full account name indicate virtual
postings, described below.
Parentheses or brackets internal to the account name have no special
meaning.
.PP
Account names can be altered temporarily or permanently by account
aliases.
.SS Amounts .SS Amounts
After the account name, there is usually an amount. After the account name, there is usually an amount.
(Remember: between account name and amount, there must be two or more (Remember: between account name and amount, there must be two or more
@ -6694,46 +6731,37 @@ With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]),
reports will show accounts only to the specified depth, hiding deeper reports will show accounts only to the specified depth, hiding deeper
subaccounts. subaccounts.
Use this when you want a summary with less detail. Use this when you want a summary with less detail.
This flag has the same effect as a \f[CR]depth:\f[R] query argument: This flag has the same effect as a \f[CR]depth:\f[R] query argument.
\f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R] or \f[CR]\-2\f[R] are So all of these are equivalent: \f[CR]depth:2\f[R],
equivalent. \f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R].
.PP .PP
In place of a single number which limits the depth for all accounts, you In place of a single number which limits the depth for all accounts, you
can also provide separate depth limits for different accounts using can also provide depth limits for specific accounts, by providing a
regular expressions \f[I](since 1.41)\f[R]. \f[CR]REGEX=DEPTH\f[R] argument instead of just a \f[CR]DEPTH\f[R]
.PP \f[I](since 1.41)\f[R].
For example, \f[CR]\-\-depth assets=2\f[R] (or, equivalently: For example, \f[CR]\-\-depth assets=2\f[R] (or
\f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular \f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular
expression \f[CR]assets\f[R] to depth 2. expression \[dq]assets\[dq] to depth 2.
So \f[CR]assets:bank:savings\f[R] would be collapsed to So \f[CR]assets:bank:savings\f[R] would be collapsed to
\f[CR]assets:bank\f[R], while \f[CR]liabilities:bank:credit card\f[R] \f[CR]assets:bank\f[R], but \f[CR]liabilities:bank:credit card\f[R]
would not be affected. would not be affected.
This can be combined with a flat depth to collapse other accounts not
matching the regular expression, so
\f[CR]\-\-depth assets=2 \-\-depth 1\f[R] would collapse
\f[CR]assets:bank:savings\f[R] to \f[CR]assets:bank\f[R] and
\f[CR]liabilities:bank:credit card\f[R] to \f[CR]liabilities\f[R].
.PP .PP
You can supply multiple depth arguments and they will all be applied, so (If REGEX contains spaces or other special characters, enclose it in
\f[CR]\-\-depth assets=2 \-\-depth liabilities=3 \-\-depth 1\f[R] would quotes in the usual way.
collapse: Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R])
.IP \[bu] 2 .PP
accounts matching \f[CR]assets\f[R] to depth 2, Specific depth options and a general depth option can be combined.
.IP \[bu] 2 Eg \f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would
accounts matching \f[CR]liabilities\f[R] to depth 3, collapse accounts containing \[dq]assets\[dq] to depth 3, accounts
.IP \[bu] 2 containing \[dq]expenses\[dq] to depth 2, and all other accounts to
all other accounts to depth 1. depth 1.
.PP .PP
If an account is matched by more than one regular expression depth If an account is matched by more than one regular expression depth
argument then the more specific one will be used. argument, the most specific (deepest) match will be used.
For example, if For example, with \f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R],
\f[CR]\-\-depth assets=1 \-\-depth assets:bank:savings=2\f[R] is \f[CR]assets:bank:savings\f[R] will be collapsed to depth 2, not depth 1
provided, then \f[CR]assets:bank:savings\f[R] will be collapsed to depth (because \[dq]savings\[dq] matches a deeper part of it than
2 rather than depth 1. \[dq]assets\[dq] does).
This is because \f[CR]assets:bank:savings\f[R] matches at level 3 in the
account name, while \f[CR]assets\f[R] matches at level 1.
The same would be true with the argument
\f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R].
.SH Queries .SH Queries
Many hledger commands accept query arguments, which restrict their scope Many hledger commands accept query arguments, which restrict their scope
and let you report on a precise subset of your data. and let you report on a precise subset of your data.
@ -8265,7 +8293,6 @@ Related: #1625
.SS Effect of valuation on reports .SS Effect of valuation on reports
Here is a reference for how valuation is supposed to affect each part of Here is a reference for how valuation is supposed to affect each part of
hledger\[aq]s reports. hledger\[aq]s reports.
(It\[aq]s wide, you may need to scroll sideways.)
It may be useful when troubleshooting. It may be useful when troubleshooting.
If you find problems, please report them, ideally with a reproducible If you find problems, please report them, ideally with a reproducible
example. example.
@ -9709,8 +9736,16 @@ Show full journal entries, representing transactions.
.EX .EX
Flags: Flags:
\-x \-\-explicit show all amounts explicitly \-x \-\-explicit show all amounts explicitly
\-\-show\-costs show transaction prices even with conversion \-\-invert display all amounts with reversed sign
postings \-\-location add tags showing file paths and line numbers
\-m \-\-match=DESC fuzzy search for one recent transaction with
description closest to DESC
\-\-new show only newer\-dated transactions added in each
file since last run
\-\-no\-lots remove lot subaccounts and their balance
assertions
\-\-no\-lots2 remove lot subaccounts and their costs and
balance assertions (can produce unbalanced entries)
\-\-round=TYPE how much rounding or padding should be done when \-\-round=TYPE how much rounding or padding should be done when
displaying amounts ? displaying amounts ?
none \- show original decimal digits, none \- show original decimal digits,
@ -9721,15 +9756,9 @@ Flags:
(can unbalance transactions) (can unbalance transactions)
all \- also round cost amounts to precision all \- also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
\-\-invert display all amounts with reversed sign
\-\-new show only newer\-dated transactions added in each
file since last run
\-m \-\-match=DESC fuzzy search for one recent transaction with
description closest to DESC
\-\-base\-url=URLPREFIX in html output, generate links to hledger\-web, \-\-base\-url=URLPREFIX in html output, generate links to hledger\-web,
with this prefix. (Usually the base url shown by with this prefix. (Usually the base url shown by
hledger\-web; can also be relative.) hledger\-web; can also be relative.)
\-\-location add tags showing file paths and line numbers
\-O \-\-output\-format=FMT select the output format. Supported formats: \-O \-\-output\-format=FMT select the output format. Supported formats:
txt, beancount, csv, tsv, html, fods, json, sql. txt, beancount, csv, tsv, html, fods, json, sql.
\-o \-\-output\-file=FILE write output to FILE. A file extension matching \-o \-\-output\-file=FILE write output to FILE. A file extension matching
@ -10191,7 +10220,7 @@ The \f[CR]\-\-depth\f[R] option helps with this, causing subaccounts to
be aggregated: be aggregated:
.IP .IP
.EX .EX
$ hledger register \-\-monthly assets \-\-depth 1h $ hledger register \-\-monthly assets \-\-depth 1
2008/01 assets $1 $1 2008/01 assets $1 $1
2008/06 assets $\-1 0 2008/06 assets $\-1 0
2008/12 assets $\-1 $\-1 2008/12 assets $\-1 $\-1
@ -13214,13 +13243,16 @@ We welcome bug reports in the hledger issue tracker
.PP .PP
Some known issues and limitations: Some known issues and limitations:
.PP .PP
A system locale with a suitable text encoding must be configured to work hledger uses the system\[aq]s text encoding when reading non\-ascii
with non\-ascii data. text.
If no system encoding is configured, or if the data\[aq]s encoding is
different, hledger will give an error.
(See Text encoding, Troubleshooting.) (See Text encoding, Troubleshooting.)
.PP .PP
On Microsoft Windows, depending what kind of terminal window you use, On Microsoft Windows, depending what kind of terminal window you use,
non\-ascii characters, ANSI text formatting, and/or the add non\-ascii characters, ANSI text formatting, and/or the add
command\[aq]s TAB key for completion, may not be supported. command\[aq]s TAB key, may not be fully supported.
(For best results, try a powershell window.)
.PP .PP
When processing large data files, hledger uses more memory than Ledger. When processing large data files, hledger uses more memory than Ledger.
.SS Troubleshooting .SS Troubleshooting

978
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

268
hledger/hledger.txt
View File

@ -646,7 +646,7 @@ Options
# Options following a `[COMMAND]` heading are used with that hledger command only. # Options following a `[COMMAND]` heading are used with that hledger command only.
[print] [print]
--explicit --show-costs --explicit --infer-costs
To use a config file, specify it with the --conf option. Its options To use a config file, specify it with the --conf option. Its options
will be inserted near the start of your command line, so you can over- will be inserted near the start of your command line, so you can over-
@ -1046,14 +1046,14 @@ Journal
changes with a version control system such as git. Editor add-ons such changes with a version control system such as git. Editor add-ons such
as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
hledger-vscode for Visual Studio Code, make this easier, adding colour, hledger-vscode for Visual Studio Code, make this easier, adding colour,
formatting, tab completion, and useful commands. See Editor configura- formatting, tab completion, and useful commands. See Editors at
tion at hledger.org for the full list. hledger.org for the full list.
A hledger journal file can contain three kinds of thing: comment lines, A hledger journal file can contain three kinds of thing: comment lines,
transactions, and/or directives (including periodic transaction rules transactions, and/or directives (including periodic transaction rules
and auto posting rules). Understanding the journal file format will and auto posting rules). Understanding the journal file format will
also give you a good understanding of hledger's data model. Here's a also give you a good understanding of hledger's data model. Here's a
quick cheatsheet/overview, followed by detailed descriptions of each quick cheatsheet/overview, followed by detailed descriptions of each
part. part.
Journal cheatsheet Journal cheatsheet
@ -1188,7 +1188,7 @@ Journal
Comments Comments
Lines in the journal will be ignored if they begin with a hash (#) or a Lines in the journal will be ignored if they begin with a hash (#) or a
semicolon (;). (See also Other syntax.) hledger will also ignore re- semicolon (;). (See also Other syntax.) hledger will also ignore re-
gions beginning with a comment line and ending with an end comment line gions beginning with a comment line and ending with an end comment line
(or file end). Here's a suggestion for choosing between them: (or file end). Here's a suggestion for choosing between them:
@ -1210,15 +1210,15 @@ Journal
end comment end comment
Some hledger entries can have same-line comments attached to them, from Some hledger entries can have same-line comments attached to them, from
; (semicolon) to end of line. See Transaction comments, Posting com- ; (semicolon) to end of line. See Transaction comments, Posting com-
ments, and Account comments below. ments, and Account comments below.
Transactions Transactions
Transactions are the main unit of information in a journal file. They Transactions are the main unit of information in a journal file. They
represent events, typically a movement of some quantity of commodities represent events, typically a movement of some quantity of commodities
between two or more named accounts. between two or more named accounts.
Each transaction is recorded as a journal entry, beginning with a sim- Each transaction is recorded as a journal entry, beginning with a sim-
ple date in column 0. This can be followed by any of the following op- ple date in column 0. This can be followed by any of the following op-
tional fields, separated by spaces: tional fields, separated by spaces:
@ -1228,11 +1228,11 @@ Journal
o a description (any remaining text until end of line or a semicolon) o a description (any remaining text until end of line or a semicolon)
o a comment (any remaining text following a semicolon until end of o a comment (any remaining text following a semicolon until end of
line, and any following indented lines beginning with a semicolon) line, and any following indented lines beginning with a semicolon)
o 0 or more indented posting lines, describing what was transferred and o 0 or more indented posting lines, describing what was transferred and
the accounts involved (indented comment lines are also allowed, but the accounts involved (indented comment lines are also allowed, but
not blank lines or non-indented lines). not blank lines or non-indented lines).
Here's a simple journal file containing one transaction: Here's a simple journal file containing one transaction:
@ -1243,23 +1243,26 @@ Journal
Dates Dates
Simple dates Simple dates
Dates in the journal file use simple dates format: YYYY-MM-DD or Dates in the journal file use simple dates format: YYYY-MM-DD or
YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
omitted, in which case it will be inferred from the context: the cur- omitted, in which case it will be inferred from the context: the cur-
rent transaction, the default year set with a Y directive, or the cur- rent transaction, the default year set with a Y directive, or the cur-
rent date when the command is run. Some examples: 2010-01-31, rent date when the command is run. Some examples: 2010-01-31,
2010/01/31, 2010.1.31, 1/31. 2010/01/31, 2010.1.31, 1/31.
(The UI also accepts simple dates, as well as the more flexible smart (The UI also accepts simple dates, as well as the more flexible smart
dates documented in the hledger manual.) dates documented in the hledger manual.)
Posting dates Posting dates
You can give individual postings a different date from their parent You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below) transaction, by adding a posting comment containing a tag (see below)
like date:DATE. This is probably the best way to control posting dates like ; date:DATE. (There's also a Ledger-compatible syntax, ; [DATE],
precisely. Eg in this example the expense should appear in May re- which can be convenient.)
ports, and the deduction from checking should be reported on 6/1 for
easy bank reconciliation: This is probably the best way to control posting dates precisely. Eg
in this example the expense should appear in May reports, and the de-
duction from checking should be reported on 6/1 for easy bank reconcil-
iation:
2015/5/30 2015/5/30
expenses:food $10 ; food purchased on saturday 5/30 expenses:food $10 ; food purchased on saturday 5/30
@ -1375,27 +1378,32 @@ Journal
o (optional) a status character (empty, !, or *), followed by a space o (optional) a status character (empty, !, or *), followed by a space
o (required) an account name (any text, optionally containing single o (required) an account name (any text, optionally including single
spaces, until end of line or a double space) spaces. If anything follows the account name on the same line, the
account name must be ended by two or more spaces.)
o (optional) two or more spaces (or tabs) followed by an amount. o (optional) an amount
o (optional) a same-line posting comment, beginning with a semicolon
(;).
If the amount is positive, it is being added to the account; if nega- If the amount is positive, it is being added to the account; if nega-
tive, it is being removed from the account. tive, it is being removed from the account.
The posting amounts in a transaction must sum up to zero, indicating The posting amounts in a transaction must sum up to zero, indicating
that the inflows and outflows are equal. We call this a balanced that the inflows and outflows are equal. We call this a balanced
transaction. (You can read more about the nitty-gritty details of "sum transaction. (You can read more about the details of transaction bal-
up to zero" in Transaction balancing below.) ancing below.)
As a convenience, you can optionally leave one amount blank; hledger If no amount is written, it will be calculated automatically from the
will infer what it should be so as to balance the transaction. other postings in the transaction, so as to balance the transaction.
In other words, in any transaction you can leave one posting amountless
to save typing.
Debits and credits Debits and credits
The traditional accounting concepts of debit and credit of course exist The traditional accounting concepts of debit and credit of course exist
in hledger, but we represent them with numeric sign, as described in hledger, but we represent them with numeric sign. Positive and neg-
above. Positive and negative posting amounts represent debits and ative posting amounts represent debits and credits respectively.
credits respectively.
You don't need to remember that, but if you would like to - eg for You don't need to remember that, but if you would like to - eg for
helping newcomers or for talking with your accountant - here's a handy helping newcomers or for talking with your accountant - here's a handy
@ -1404,29 +1412,56 @@ Journal
debit / plus / left / short words debit / plus / left / short words
credit / minus / right / longer words credit / minus / right / longer words
The two space delimiter
Be sure to notice the unusual separator between the account name and
the following amount. Because hledger allows account names with spaces
in them, you must separate the account name and amount (if any) by two
or more spaces (or tabs). It's easy to forget at first. If you ever
see the amount being treated as part of the account name, you'll know
you probably need to add another space between them.
Account names Account names
Accounts are the main way of categorising things in hledger. As in Accounts are the main way of categorising things in hledger. As in
Double Entry Bookkeeping, they can represent real world accounts (such Double Entry Bookkeeping, they can represent real world accounts (such
as a bank account), or more abstract categories such as "money borrowed as a bank account), or more abstract categories such as "money spent on
from Frank" or "money spent on electricity". food" or "money borrowed from Frank".
You can use any account names you like, but we usually start with the Account names are flexible. They may be capitalised or not; they may
traditional accounting categories, which in english are assets, liabil- contain letters, numbers, punctuation, symbols, or single spaces; they
ities, equity, revenues, expenses. (You might see these referred to as may be in any language.
A, L, E, R, X for short.)
For more precise reporting, we usually divide the top level accounts Typically we use the five traditional accounting categories as the
into more detailed subaccounts, by writing a full colon between account starting point for account names. In english they are:
name parts. For example, from the account names assets:bank:checking
and expenses:food, hledger will infer this hierarchy of five accounts: assets, liabilities, equity, revenues, expenses
These will be discussed more in Account types below. In hledger docs
you may see them referred to as A, L, E, R, X for short.
The two space delimiter
Note the two or more spaces delimiter that's sometimes required after
account names. hledger's account names, inherited from Ledger, are
very permissive; they may contain pretty much any kind of text, includ-
ing single spaces and semicolons. Because of this, they must be termi-
nated by two or more spaces if there is anything following them on the
same line. For example, if an amount, balance assignment, or same-line
comment follows an account name, they must be preceded by two or more
spaces, else they would be considered part of the account name:
bad: assets:accounts receivable $10 ; <- too close!
good: assets:accounts receivable $10
bad: assets:accounts receivable =$1000 ; <- too close!
good: assets:accounts receivable =$1000
bad: assets:accounts receivable ; comment. <- too close!
good: assets:accounts receivable ; comment
This two-space delimiter appears in a few places in hledger, such as
after account names in postings or account directives; also after the
period expression in periodic transaction rules. When you are starting
out, expect it to catch you out at least once. It's annoying some-
times, but it lets us use expressive account names while still keeping
the syntax light.
Account hierarchy
For more precise reporting, we usually divide accounts into more de-
tailed subaccounts, subsubaccounts, and so on, by writing a full colon
between account name parts. For example, instead of writing assets and
expenses, we might write assets:bank:checking and expenses:food. From
these names hledger will infer this hierarchy of five accounts:
assets assets
assets:bank assets:bank
@ -1434,7 +1469,7 @@ Journal
expenses expenses
expenses:food expenses:food
Shown as an outline, the hierarchical tree structure is more clear: Or as an outline:
assets assets
bank bank
@ -1443,20 +1478,17 @@ Journal
food food
hledger reports can summarise the account tree to any depth, so you can hledger reports can summarise the account tree to any depth, so you can
go as deep as you like with subcategories, but keeping your account make your subcategories as detailed as you like. But don't go over-
names relatively simple may be best when starting out. board, especially when getting started; simpler categories can be less
work.
Account names may be capitalised or not; they may contain letters, num- Other account name features
bers, symbols, or single spaces. Note, when an account name and an Enclosing the account name in parentheses or brackets, like (ex-
amount are written on the same line, they must be separated by two or penses:food), enables a non-standard bookkeeping feature: virtual post-
more spaces (or tabs). ings.
Parentheses or brackets enclosing the full account name indicate vir- Account names can be rewritten and restructured, temporarily or perma-
tual postings, described below. Parentheses or brackets internal to nently, by account aliases.
the account name have no special meaning.
Account names can be altered temporarily or permanently by account
aliases.
Amounts Amounts
After the account name, there is usually an amount. (Remember: between After the account name, there is usually an amount. (Remember: between
@ -5225,38 +5257,30 @@ Depth
With the --depth NUM option (short form: -NUM), reports will show ac- With the --depth NUM option (short form: -NUM), reports will show ac-
counts only to the specified depth, hiding deeper subaccounts. Use counts only to the specified depth, hiding deeper subaccounts. Use
this when you want a summary with less detail. This flag has the same this when you want a summary with less detail. This flag has the same
effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- effect as a depth: query argument. So all of these are equivalent:
lent. depth:2, --depth=2, -2.
In place of a single number which limits the depth for all accounts, In place of a single number which limits the depth for all accounts,
you can also provide separate depth limits for different accounts using you can also provide depth limits for specific accounts, by providing a
regular expressions (since 1.41). REGEX=DEPTH argument instead of just a DEPTH (since 1.41). For exam-
ple, --depth assets=2 (or depth:assets=2) will collapse accounts match-
ing the regular expression "assets" to depth 2. So assets:bank:savings
would be collapsed to assets:bank, but liabilities:bank:credit card
would not be affected.
For example, --depth assets=2 (or, equivalently: depth:assets=2) will (If REGEX contains spaces or other special characters, enclose it in
collapse accounts matching the regular expression assets to depth 2. quotes in the usual way. Eg: --depth 'credit card=2')
So assets:bank:savings would be collapsed to assets:bank, while liabil-
ities:bank:credit card would not be affected. This can be combined
with a flat depth to collapse other accounts not matching the regular
expression, so --depth assets=2 --depth 1 would collapse as-
sets:bank:savings to assets:bank and liabilities:bank:credit card to
liabilities.
You can supply multiple depth arguments and they will all be applied, Specific depth options and a general depth option can be combined. Eg
so --depth assets=2 --depth liabilities=3 --depth 1 would collapse: --depth assets=3 --depth expenses=2 --depth 1 would collapse accounts
containing "assets" to depth 3, accounts containing "expenses" to depth
2, and all other accounts to depth 1.
o accounts matching assets to depth 2, If an account is matched by more than one regular expression depth ar-
gument, the most specific (deepest) match will be used. For example,
o accounts matching liabilities to depth 3, with --depth assets=1 --depth savings=2, assets:bank:savings will be
collapsed to depth 2, not depth 1 (because "savings" matches a deeper
o all other accounts to depth 1. part of it than "assets" does).
If an account is matched by more than one regular expression depth ar-
gument then the more specific one will be used. For example, if
--depth assets=1 --depth assets:bank:savings=2 is provided, then as-
sets:bank:savings will be collapsed to depth 2 rather than depth 1.
This is because assets:bank:savings matches at level 3 in the account
name, while assets matches at level 1. The same would be true with the
argument --depth assets=1 --depth savings=2.
Queries Queries
Many hledger commands accept query arguments, which restrict their Many hledger commands accept query arguments, which restrict their
@ -6489,10 +6513,9 @@ Value reporting
Effect of valuation on reports Effect of valuation on reports
Here is a reference for how valuation is supposed to affect each part Here is a reference for how valuation is supposed to affect each part
of hledger's reports. (It's wide, you may need to scroll sideways.) of hledger's reports. It may be useful when troubleshooting. If you
It may be useful when troubleshooting. If you find problems, please find problems, please report them, ideally with a reproducible example.
report them, ideally with a reproducible example. Related: #329, Related: #329, #1083.
#1083.
First, a quick glossary: First, a quick glossary:
@ -7590,8 +7613,16 @@ Standard report commands
Flags: Flags:
-x --explicit show all amounts explicitly -x --explicit show all amounts explicitly
--show-costs show transaction prices even with conversion --invert display all amounts with reversed sign
postings --location add tags showing file paths and line numbers
-m --match=DESC fuzzy search for one recent transaction with
description closest to DESC
--new show only newer-dated transactions added in each
file since last run
--no-lots remove lot subaccounts and their balance
assertions
--no-lots2 remove lot subaccounts and their costs and
balance assertions (can produce unbalanced entries)
--round=TYPE how much rounding or padding should be done when --round=TYPE how much rounding or padding should be done when
displaying amounts ? displaying amounts ?
none - show original decimal digits, none - show original decimal digits,
@ -7602,15 +7633,9 @@ Standard report commands
(can unbalance transactions) (can unbalance transactions)
all - also round cost amounts to precision all - also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
--invert display all amounts with reversed sign
--new show only newer-dated transactions added in each
file since last run
-m --match=DESC fuzzy search for one recent transaction with
description closest to DESC
--base-url=URLPREFIX in html output, generate links to hledger-web, --base-url=URLPREFIX in html output, generate links to hledger-web,
with this prefix. (Usually the base url shown by with this prefix. (Usually the base url shown by
hledger-web; can also be relative.) hledger-web; can also be relative.)
--location add tags showing file paths and line numbers
-O --output-format=FMT select the output format. Supported formats: -O --output-format=FMT select the output format. Supported formats:
txt, beancount, csv, tsv, html, fods, json, sql. txt, beancount, csv, tsv, html, fods, json, sql.
-o --output-file=FILE write output to FILE. A file extension matching -o --output-file=FILE write output to FILE. A file extension matching
@ -8018,7 +8043,7 @@ Standard report commands
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 1
2008/01 assets $1 $1 2008/01 assets $1 $1
2008/06 assets $-1 0 2008/06 assets $-1 0
2008/12 assets $-1 $-1 2008/12 assets $-1 $-1
@ -10626,45 +10651,48 @@ BUGS
Some known issues and limitations: Some known issues and limitations:
A system locale with a suitable text encoding must be configured to hledger uses the system's text encoding when reading non-ascii text.
work with non-ascii data. (See Text encoding, Troubleshooting.) If no system encoding is configured, or if the data's encoding is dif-
ferent, hledger will give an error. (See Text encoding, Troubleshoot-
ing.)
On Microsoft Windows, depending what kind of terminal window you use, On Microsoft Windows, depending what kind of terminal window you use,
non-ascii characters, ANSI text formatting, and/or the add command's non-ascii characters, ANSI text formatting, and/or the add command's
TAB key for completion, may not be supported. TAB key, may not be fully supported. (For best results, try a power-
shell window.)
When processing large data files, hledger uses more memory than Ledger. When processing large data files, hledger uses more memory than Ledger.
Troubleshooting Troubleshooting
Here are some common issues you might encounter when you run hledger, Here are some common issues you might encounter when you run hledger,
and how to resolve them (and remember also you can usually get quick and how to resolve them (and remember also you can usually get quick
Support): Support):
PATH issues: I get an error like "No command 'hledger' found" PATH issues: I get an error like "No command 'hledger' found"
Depending how you installed hledger, the executables may not be in your Depending how you installed hledger, the executables may not be in your
shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo-
cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one
of these directories to your shell's PATH, and/or open a new terminal of these directories to your shell's PATH, and/or open a new terminal
window. window.
LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using
it it
o LEDGER_FILE should be a real environment variable, not just a shell o LEDGER_FILE should be a real environment variable, not just a shell
variable. Eg on unix, the command env | grep LEDGER_FILE should show variable. Eg on unix, the command env | grep LEDGER_FILE should show
it. You may need to use export (see https://stackover- it. You may need to use export (see https://stackover-
flow.com/a/7411509). On Windows, $env:LEDGER_FILE should show it. flow.com/a/7411509). On Windows, $env:LEDGER_FILE should show it.
o You may need to force your shell to see the new configuration. A o You may need to force your shell to see the new configuration. A
simple way is to close your terminal window and open a new one. simple way is to close your terminal window and open a new one.
Text decoding issues: I get errors like "Illegal byte sequence" or "In- Text decoding issues: I get errors like "Illegal byte sequence" or "In-
valid or incomplete multibyte or wide character" or "commitAndRelease- valid or incomplete multibyte or wide character" or "commitAndRelease-
Buffer: invalid argument (invalid character)" Buffer: invalid argument (invalid character)"
hledger usually needs its input to be decodable with the system lo- hledger usually needs its input to be decodable with the system lo-
cale's text encoding. See Text encoding and Install: Text encoding. cale's text encoding. See Text encoding and Install: Text encoding.
COMPATIBILITY ISSUES: hledger gives an error with my Ledger file COMPATIBILITY ISSUES: hledger gives an error with my Ledger file
Not all of Ledger's journal file syntax or feature set is supported. Not all of Ledger's journal file syntax or feature set is supported.
See hledger and Ledger for full details. See hledger and Ledger for full details.