;doc: update manuals
This commit is contained in:
Simon Michael
parent
085b7d4b88
commit
4451d68a63
@ -302,12 +302,6 @@ There\[aq]s not yet any visual reminder when cost or value mode is
|
||||
active; for now pressing \f[C]b\f[R] \f[C]b\f[R] \f[C]v\f[R] should
|
||||
reliably reset to normal mode.
|
||||
.PP
|
||||
With \f[C]--watch\f[R] active, if you save an edit to the journal file
|
||||
while viewing the transaction screen in cost or value mode, the
|
||||
\f[C]B\f[R]/\f[C]V\f[R] keys will stop working.
|
||||
To work around, press \f[C]g\f[R] to force a manual reload, or exit the
|
||||
transaction screen.
|
||||
.PP
|
||||
\f[C]q\f[R] quits the application.
|
||||
.PP
|
||||
Additional screen-specific keys are described below.
|
||||
@ -439,6 +433,58 @@ when you press g to reload.
|
||||
Once you have fixed the problem, press g again to reload and resume
|
||||
normal operation.
|
||||
(Or, you can press escape to cancel the reload attempt.)
|
||||
.SH TIPS
|
||||
.SS Watch mode
|
||||
.PP
|
||||
One of hledger-ui\[aq]s best features is the auto-reloading
|
||||
\f[C]--watch\f[R] mode.
|
||||
With this flag, it will update the display automatically whenever
|
||||
changes are saved to the data files.
|
||||
.PP
|
||||
This is very useful when reconciling.
|
||||
A good workflow is to have your bank\[aq]s online register open in a
|
||||
browser window, for reference; the journal file open in an editor
|
||||
window; and hledger-ui in watch mode in a terminal window, eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger-ui --watch --register checking -C
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
As you mark things cleared in the editor, you can see the effect
|
||||
immediately without having to context switch.
|
||||
This leaves more mental bandwidth for your accounting.
|
||||
Of course you can still interact with hledger-ui when needed, eg to
|
||||
toggle cleared mode, or to explore the history.
|
||||
.SS Watch mode limitations
|
||||
.PP
|
||||
There are situations in which it won\[aq]t work, ie the display will not
|
||||
update when you save a change (because the underlying \f[C]inotify\f[R]
|
||||
library does not support it).
|
||||
Here are some that we know of:
|
||||
.IP \[bu] 2
|
||||
Certain editors: saving with \f[C]gedit\f[R], and perhaps any Gnome
|
||||
application, won\[aq]t be detected (#1617).
|
||||
Jetbrains IDEs, such as IDEA, also may not work (#911).
|
||||
.IP \[bu] 2
|
||||
Certain unusual filesystems might not be supported.
|
||||
(All the usual ones on unix, mac and windows are supported.)
|
||||
.PP
|
||||
In such cases, the workaround is to switch to the hledger-ui window and
|
||||
press \f[C]g\f[R] each time you want it to reload.
|
||||
(Actually, see #1617 for another workaround, and let us know if it works
|
||||
for you.)
|
||||
.PP
|
||||
If you leave \f[C]hledger-ui --watch\f[R] running for days, on certain
|
||||
platforms (?), perhaps with many transactions in your journal (?),
|
||||
perhaps with large numbers of other files present (?), you may see it
|
||||
gradually using more and more memory and CPU over time, as seen in
|
||||
\f[C]top\f[R] or Activity Monitor or Task Manager.
|
||||
.PP
|
||||
A workaround is to \f[C]q\f[R]uit and restart it, or to suspend it
|
||||
(\f[C]CTRL-z\f[R]) and restart it (\f[C]fg\f[R]) if your shell supports
|
||||
that.
|
||||
.SH ENVIRONMENT
|
||||
.PP
|
||||
\f[B]COLUMNS\f[R] The screen width to use.
|
||||
|
||||
@ -3,7 +3,7 @@ from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
* hledger-ui: (hledger-ui/hledger-ui). Terminal UI for the hledger accounting tool.
|
||||
* hledger-ui: (hledger-ui). Terminal UI for the hledger accounting tool.
|
||||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
@ -45,6 +45,7 @@ enable "forecast mode".
|
||||
* OPTIONS::
|
||||
* KEYS::
|
||||
* SCREENS::
|
||||
* TIPS::
|
||||
* ENVIRONMENT::
|
||||
* FILES::
|
||||
* BUGS::
|
||||
@ -308,17 +309,12 @@ screen, press `/', and add `date:-7/30' to the query.
|
||||
active; for now pressing `b' `b' `v' should reliably reset to normal
|
||||
mode.
|
||||
|
||||
With `--watch' active, if you save an edit to the journal file while
|
||||
viewing the transaction screen in cost or value mode, the `B'/`V' keys
|
||||
will stop working. To work around, press `g' to force a manual reload,
|
||||
or exit the transaction screen.
|
||||
|
||||
`q' quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: SCREENS, Next: ENVIRONMENT, Prev: KEYS, Up: Top
|
||||
File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top
|
||||
|
||||
3 SCREENS
|
||||
*********
|
||||
@ -463,9 +459,75 @@ again to reload and resume normal operation. (Or, you can press escape
|
||||
to cancel the reload attempt.)
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: SCREENS, Up: Top
|
||||
File: hledger-ui.info, Node: TIPS, Next: ENVIRONMENT, Prev: SCREENS, Up: Top
|
||||
|
||||
4 ENVIRONMENT
|
||||
4 TIPS
|
||||
******
|
||||
|
||||
* Menu:
|
||||
|
||||
* Watch mode::
|
||||
* Watch mode limitations::
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Watch mode, Next: Watch mode limitations, Up: TIPS
|
||||
|
||||
4.1 Watch mode
|
||||
==============
|
||||
|
||||
One of hledger-ui's best features is the auto-reloading `--watch' mode.
|
||||
With this flag, it will update the display automatically whenever
|
||||
changes are saved to the data files.
|
||||
|
||||
This is very useful when reconciling. A good workflow is to have your
|
||||
bank's online register open in a browser window, for reference; the
|
||||
journal file open in an editor window; and hledger-ui in watch mode in a
|
||||
terminal window, eg:
|
||||
|
||||
|
||||
$ hledger-ui --watch --register checking -C
|
||||
|
||||
As you mark things cleared in the editor, you can see the effect
|
||||
immediately without having to context switch. This leaves more mental
|
||||
bandwidth for your accounting. Of course you can still interact with
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
history.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Watch mode limitations, Prev: Watch mode, Up: TIPS
|
||||
|
||||
4.2 Watch mode limitations
|
||||
==========================
|
||||
|
||||
There are situations in which it won't work, ie the display will not
|
||||
update when you save a change (because the underlying `inotify' library
|
||||
does not support it). Here are some that we know of:
|
||||
|
||||
* Certain editors: saving with `gedit', and perhaps any Gnome
|
||||
application, won't be detected (#1617). Jetbrains IDEs, such as
|
||||
IDEA, also may not work (#911).
|
||||
|
||||
* Certain unusual filesystems might not be supported. (All the usual
|
||||
ones on unix, mac and windows are supported.)
|
||||
|
||||
|
||||
In such cases, the workaround is to switch to the hledger-ui window
|
||||
and press `g' each time you want it to reload. (Actually, see #1617 for
|
||||
another workaround, and let us know if it works for you.)
|
||||
|
||||
If you leave `hledger-ui --watch' running for days, on certain
|
||||
platforms (?), perhaps with many transactions in your journal (?),
|
||||
perhaps with large numbers of other files present (?), you may see it
|
||||
gradually using more and more memory and CPU over time, as seen in
|
||||
`top' or Activity Monitor or Task Manager.
|
||||
|
||||
A workaround is to `q'uit and restart it, or to suspend it
|
||||
(`CTRL-z') and restart it (`fg') if your shell supports that.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
|
||||
|
||||
5 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*COLUMNS* The screen width to use. Default: the full terminal width.
|
||||
@ -494,7 +556,7 @@ GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
|
||||
File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
|
||||
5 FILES
|
||||
6 FILES
|
||||
*******
|
||||
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
@ -505,7 +567,7 @@ timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
|
||||
|
||||
File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
|
||||
6 BUGS
|
||||
7 BUGS
|
||||
******
|
||||
|
||||
The need to precede options with `--' when invoked from hledger is
|
||||
@ -533,26 +595,32 @@ program is restarted.
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top243
|
||||
Node: OPTIONS1636
|
||||
Ref: #options1733
|
||||
Node: KEYS6128
|
||||
Ref: #keys6223
|
||||
Node: SCREENS10519
|
||||
Ref: #screens10624
|
||||
Node: Accounts screen10714
|
||||
Ref: #accounts-screen10842
|
||||
Node: Register screen13046
|
||||
Ref: #register-screen13201
|
||||
Node: Transaction screen15196
|
||||
Ref: #transaction-screen15354
|
||||
Node: Error screen16221
|
||||
Ref: #error-screen16343
|
||||
Node: ENVIRONMENT16585
|
||||
Ref: #environment16699
|
||||
Node: FILES17504
|
||||
Ref: #files17603
|
||||
Node: BUGS17816
|
||||
Ref: #bugs17893
|
||||
Node: Top232
|
||||
Node: OPTIONS1634
|
||||
Ref: #options1731
|
||||
Node: KEYS6126
|
||||
Ref: #keys6221
|
||||
Node: SCREENS10270
|
||||
Ref: #screens10368
|
||||
Node: Accounts screen10458
|
||||
Ref: #accounts-screen10586
|
||||
Node: Register screen12790
|
||||
Ref: #register-screen12945
|
||||
Node: Transaction screen14940
|
||||
Ref: #transaction-screen15098
|
||||
Node: Error screen15965
|
||||
Ref: #error-screen16087
|
||||
Node: TIPS16329
|
||||
Ref: #tips16428
|
||||
Node: Watch mode16480
|
||||
Ref: #watch-mode16597
|
||||
Node: Watch mode limitations17341
|
||||
Ref: #watch-mode-limitations17482
|
||||
Node: ENVIRONMENT18615
|
||||
Ref: #environment18726
|
||||
Node: FILES19531
|
||||
Ref: #files19630
|
||||
Node: BUGS19843
|
||||
Ref: #bugs19920
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -276,55 +276,50 @@ KEYS
|
||||
There's not yet any visual reminder when cost or value mode is active;
|
||||
for now pressing b b v should reliably reset to normal mode.
|
||||
|
||||
With --watch active, if you save an edit to the journal file while
|
||||
viewing the transaction screen in cost or value mode, the B/V keys will
|
||||
stop working. To work around, press g to force a manual reload, or
|
||||
exit the transaction screen.
|
||||
|
||||
q quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
SCREENS
|
||||
Accounts screen
|
||||
This is normally the first screen displayed. It lists accounts and
|
||||
their balances, like hledger's balance command. By default, it shows
|
||||
all accounts and their latest ending balances (including the balances
|
||||
of subaccounts). If you specify a query on the command line, it shows
|
||||
This is normally the first screen displayed. It lists accounts and
|
||||
their balances, like hledger's balance command. By default, it shows
|
||||
all accounts and their latest ending balances (including the balances
|
||||
of subaccounts). If you specify a query on the command line, it shows
|
||||
just the matched accounts and the balances from matched transactions.
|
||||
|
||||
Account names are shown as a flat list by default; press t to toggle
|
||||
tree mode. In list mode, account balances are exclusive of subac-
|
||||
counts, except where subaccounts are hidden by a depth limit (see
|
||||
below). In tree mode, all account balances are inclusive of subac-
|
||||
Account names are shown as a flat list by default; press t to toggle
|
||||
tree mode. In list mode, account balances are exclusive of subac-
|
||||
counts, except where subaccounts are hidden by a depth limit (see
|
||||
below). In tree mode, all account balances are inclusive of subac-
|
||||
counts.
|
||||
|
||||
To see less detail, press a number key, 1 to 9, to set a depth limit.
|
||||
To see less detail, press a number key, 1 to 9, to set a depth limit.
|
||||
Or use - to decrease and +/= to increase the depth limit. 0 shows even
|
||||
less detail, collapsing all accounts to a single total. To remove the
|
||||
depth limit, set it higher than the maximum account depth, or press
|
||||
less detail, collapsing all accounts to a single total. To remove the
|
||||
depth limit, set it higher than the maximum account depth, or press
|
||||
ESCAPE.
|
||||
|
||||
H toggles between showing historical balances or period balances. His-
|
||||
torical balances (the default) are ending balances at the end of the
|
||||
report period, taking into account all transactions before that date
|
||||
(filtered by the filter query if any), including transactions before
|
||||
the start of the report period. In other words, historical balances
|
||||
are what you would see on a bank statement for that account (unless
|
||||
disturbed by a filter query). Period balances ignore transactions
|
||||
torical balances (the default) are ending balances at the end of the
|
||||
report period, taking into account all transactions before that date
|
||||
(filtered by the filter query if any), including transactions before
|
||||
the start of the report period. In other words, historical balances
|
||||
are what you would see on a bank statement for that account (unless
|
||||
disturbed by a filter query). Period balances ignore transactions
|
||||
before the report start date, so they show the change in balance during
|
||||
the report period. They are more useful eg when viewing a time log.
|
||||
|
||||
U toggles filtering by unmarked status, including or excluding unmarked
|
||||
postings in the balances. Similarly, P toggles pending postings, and C
|
||||
toggles cleared postings. (By default, balances include all postings;
|
||||
if you activate one or two status filters, only those postings are
|
||||
toggles cleared postings. (By default, balances include all postings;
|
||||
if you activate one or two status filters, only those postings are
|
||||
included; and if you activate all three, the filter is removed.)
|
||||
|
||||
R toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
Z toggles nonzero mode, in which only accounts with nonzero balances
|
||||
are shown (hledger-ui shows zero items by default, unlike command-line
|
||||
Z toggles nonzero mode, in which only accounts with nonzero balances
|
||||
are shown (hledger-ui shows zero items by default, unlike command-line
|
||||
hledger).
|
||||
|
||||
Press right or enter to view an account's transactions register.
|
||||
@ -333,66 +328,110 @@ SCREENS
|
||||
This screen shows the transactions affecting a particular account, like
|
||||
a check register. Each line represents one transaction and shows:
|
||||
|
||||
o the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
o the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
by real postings.)
|
||||
|
||||
o the overall change to the current account's balance; positive for an
|
||||
o the overall change to the current account's balance; positive for an
|
||||
inflow to this account, negative for an outflow.
|
||||
|
||||
o the running historical total or period total for the current account,
|
||||
after the transaction. This can be toggled with H. Similar to the
|
||||
accounts screen, the historical total is affected by transactions
|
||||
(filtered by the filter query) before the report start date, while
|
||||
after the transaction. This can be toggled with H. Similar to the
|
||||
accounts screen, the historical total is affected by transactions
|
||||
(filtered by the filter query) before the report start date, while
|
||||
the period total is not. If the historical total is not disturbed by
|
||||
a filter query, it will be the running historical balance you would
|
||||
a filter query, it will be the running historical balance you would
|
||||
see on a bank register for the current account.
|
||||
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
the register if the accounts screen is in tree mode, or if it's in list
|
||||
mode but this account has subaccounts which are not shown due to a
|
||||
depth limit. In other words, the register always shows the transac-
|
||||
tions contributing to the balance shown on the accounts screen. Tree
|
||||
mode but this account has subaccounts which are not shown due to a
|
||||
depth limit. In other words, the register always shows the transac-
|
||||
tions contributing to the balance shown on the accounts screen. Tree
|
||||
mode/list mode can be toggled with t here also.
|
||||
|
||||
U toggles filtering by unmarked status, showing or hiding unmarked
|
||||
U toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, P toggles pending transactions, and C toggles
|
||||
cleared transactions. (By default, transactions with all statuses are
|
||||
shown; if you activate one or two status filters, only those transac-
|
||||
cleared transactions. (By default, transactions with all statuses are
|
||||
shown; if you activate one or two status filters, only those transac-
|
||||
tions are shown; and if you activate all three, the filter is removed.)
|
||||
|
||||
R toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
Z toggles nonzero mode, in which only transactions posting a nonzero
|
||||
change are shown (hledger-ui shows zero items by default, unlike com-
|
||||
Z toggles nonzero mode, in which only transactions posting a nonzero
|
||||
change are shown (hledger-ui shows zero items by default, unlike com-
|
||||
mand-line hledger).
|
||||
|
||||
Press right (or enter) to view the selected transaction in detail.
|
||||
|
||||
Transaction screen
|
||||
This screen shows a single transaction, as a general journal entry,
|
||||
similar to hledger's print command and journal format (hledger_jour-
|
||||
This screen shows a single transaction, as a general journal entry,
|
||||
similar to hledger's print command and journal format (hledger_jour-
|
||||
nal(5)).
|
||||
|
||||
The transaction's date(s) and any cleared flag, transaction code,
|
||||
description, comments, along with all of its account postings are
|
||||
shown. Simple transactions have two postings, but there can be more
|
||||
The transaction's date(s) and any cleared flag, transaction code,
|
||||
description, comments, along with all of its account postings are
|
||||
shown. Simple transactions have two postings, but there can be more
|
||||
(or in certain cases, fewer).
|
||||
|
||||
up and down will step through all transactions listed in the previous
|
||||
account register screen. In the title bar, the numbers in parentheses
|
||||
show your position within that account register. They will vary
|
||||
up and down will step through all transactions listed in the previous
|
||||
account register screen. In the title bar, the numbers in parentheses
|
||||
show your position within that account register. They will vary
|
||||
depending on which account register you came from (remember most trans-
|
||||
actions appear in multiple account registers). The #N number preceding
|
||||
them is the transaction's position within the complete unfiltered jour-
|
||||
nal, which is a more stable id (at least until the next reload).
|
||||
|
||||
Error screen
|
||||
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
|
||||
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
|
||||
again to reload and resume normal operation. (Or, you can press escape
|
||||
to cancel the reload attempt.)
|
||||
|
||||
TIPS
|
||||
Watch mode
|
||||
One of hledger-ui's best features is the auto-reloading --watch mode.
|
||||
With this flag, it will update the display automatically whenever
|
||||
changes are saved to the data files.
|
||||
|
||||
This is very useful when reconciling. A good workflow is to have your
|
||||
bank's online register open in a browser window, for reference; the
|
||||
journal file open in an editor window; and hledger-ui in watch mode in
|
||||
a terminal window, eg:
|
||||
|
||||
$ hledger-ui --watch --register checking -C
|
||||
|
||||
As you mark things cleared in the editor, you can see the effect imme-
|
||||
diately without having to context switch. This leaves more mental
|
||||
bandwidth for your accounting. Of course you can still interact with
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
history.
|
||||
|
||||
Watch mode limitations
|
||||
There are situations in which it won't work, ie the display will not
|
||||
update when you save a change (because the underlying inotify library
|
||||
does not support it). Here are some that we know of:
|
||||
|
||||
o Certain editors: saving with gedit, and perhaps any Gnome applica-
|
||||
tion, won't be detected (#1617). Jetbrains IDEs, such as IDEA, also
|
||||
may not work (#911).
|
||||
|
||||
o Certain unusual filesystems might not be supported. (All the usual
|
||||
ones on unix, mac and windows are supported.)
|
||||
|
||||
In such cases, the workaround is to switch to the hledger-ui window and
|
||||
press g each time you want it to reload. (Actually, see #1617 for
|
||||
another workaround, and let us know if it works for you.)
|
||||
|
||||
If you leave hledger-ui --watch running for days, on certain platforms
|
||||
(?), perhaps with many transactions in your journal (?), perhaps with
|
||||
large numbers of other files present (?), you may see it gradually
|
||||
using more and more memory and CPU over time, as seen in top or Activ-
|
||||
ity Monitor or Task Manager.
|
||||
|
||||
A workaround is to quit and restart it, or to suspend it (CTRL-z) and
|
||||
restart it (fg) if your shell supports that.
|
||||
|
||||
ENVIRONMENT
|
||||
COLUMNS The screen width to use. Default: the full terminal width.
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
* hledger-web: (hledger-web/hledger-web). Web UI/API for the hledger accounting tool.
|
||||
* hledger-web: (hledger-web). Web UI/API for the hledger accounting tool.
|
||||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
@ -612,22 +612,22 @@ awkward.
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top247
|
||||
Node: OPTIONS1887
|
||||
Ref: #options1992
|
||||
Node: PERMISSIONS9405
|
||||
Ref: #permissions9544
|
||||
Node: EDITING UPLOADING DOWNLOADING10756
|
||||
Ref: #editing-uploading-downloading10937
|
||||
Node: RELOADING11768
|
||||
Ref: #reloading11902
|
||||
Node: JSON API12334
|
||||
Ref: #json-api12448
|
||||
Node: ENVIRONMENT17937
|
||||
Ref: #environment18053
|
||||
Node: FILES18785
|
||||
Ref: #files18885
|
||||
Node: BUGS19098
|
||||
Ref: #bugs19176
|
||||
Node: Top235
|
||||
Node: OPTIONS1875
|
||||
Ref: #options1980
|
||||
Node: PERMISSIONS9393
|
||||
Ref: #permissions9532
|
||||
Node: EDITING UPLOADING DOWNLOADING10744
|
||||
Ref: #editing-uploading-downloading10925
|
||||
Node: RELOADING11756
|
||||
Ref: #reloading11890
|
||||
Node: JSON API12322
|
||||
Ref: #json-api12436
|
||||
Node: ENVIRONMENT17925
|
||||
Ref: #environment18041
|
||||
Node: FILES18773
|
||||
Ref: #files18873
|
||||
Node: BUGS19086
|
||||
Ref: #bugs19164
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -296,6 +296,11 @@ or:
|
||||
$ hledger register credit\[rs] card
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Windows users should keep in mind that \f[C]cmd\f[R] treats single quote
|
||||
as a regular character, so you should be using double quotes
|
||||
exclusively.
|
||||
PowerShell treats both single and double quotes as quotes.
|
||||
.SS Double escaping (regular expression metacharacters)
|
||||
.PP
|
||||
Characters significant in regular expressions (described below) - such
|
||||
@ -657,6 +662,8 @@ Are all accounts posted to, declared with an \f[C]account\f[R] directive
|
||||
.IP \[bu] 2
|
||||
Are all commodities declared with a \f[C]commodity\f[R] directive ?
|
||||
(Commodity error checking)
|
||||
.IP \[bu] 2
|
||||
Are all commodity conversions declared explicitly ?
|
||||
.PP
|
||||
You can also use the check command to run these and some additional
|
||||
checks.
|
||||
@ -754,6 +761,7 @@ T}@T{
|
||||
9+ digits beginning with a valid YYYYMMDD gives an error
|
||||
T}
|
||||
.TE
|
||||
.PP
|
||||
.SS Report start & end date
|
||||
.PP
|
||||
By default, most hledger reports will show the full span of time
|
||||
@ -1140,18 +1148,171 @@ This flag has the same effect as a \f[C]depth:\f[R] query argument (so
|
||||
\f[C]-2\f[R], \f[C]--depth=2\f[R] or \f[C]depth:2\f[R] are equivalent).
|
||||
.SH QUERIES
|
||||
.PP
|
||||
One of hledger\[aq]s strengths is being able to quickly report on
|
||||
precise subsets of your data.
|
||||
Most commands accept an optional query expression, written as arguments
|
||||
after the command name, to filter the data by date, account name or
|
||||
other criteria.
|
||||
The syntax is similar to a web search: one or more space-separated
|
||||
search terms, quotes to enclose whitespace, prefixes to match specific
|
||||
fields, a not: prefix to negate the match.
|
||||
One of hledger\[aq]s strengths is being able to quickly report on a
|
||||
precise subset of your data.
|
||||
Most hledger commands accept optional query arguments to restrict their
|
||||
scope.
|
||||
The syntax is as follows:
|
||||
.IP \[bu] 2
|
||||
Zero or more space-separated query terms.
|
||||
These are most often account name substrings:
|
||||
.RS 2
|
||||
.PP
|
||||
We do not yet support arbitrary boolean combinations of search terms;
|
||||
instead most commands show transactions/postings/accounts which match
|
||||
(or negatively match):
|
||||
\f[C]utilities food:groceries\f[R]
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
Terms with spaces or other special characters should be enclosed in
|
||||
quotes:
|
||||
.RS 2
|
||||
.PP
|
||||
\f[C]\[dq]personal care\[dq]\f[R]
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
Regular expressions are also supported:
|
||||
.RS 2
|
||||
.PP
|
||||
\f[C]\[dq]\[ha]expenses\[rs]b\[dq] \[dq]accounts (payable|receivable)\[dq]\f[R]
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
Add a query type prefix to match other parts of the data:
|
||||
.RS 2
|
||||
.PP
|
||||
\f[C]date:202012- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R]
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
Add a \f[C]not:\f[R] prefix to negate a term:
|
||||
.RS 2
|
||||
.PP
|
||||
\f[C]not:cur:USD\f[R]
|
||||
.RE
|
||||
.SS Query types
|
||||
.PP
|
||||
Here are the types of query term available.
|
||||
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R] to
|
||||
convert them into a negative match.
|
||||
.PP
|
||||
\f[B]\f[CB]acct:REGEX\f[B], \f[CB]REGEX\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match account names containing this (case insensitive) regular
|
||||
expression.
|
||||
This is the default query type when there is no prefix, and regular
|
||||
expression syntax is typically not needed, so usually we just write an
|
||||
account name substring, like \f[C]expenses\f[R] or \f[C]food\f[R].
|
||||
.PP
|
||||
\f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match postings with a single-commodity amount equal to, less than, or
|
||||
greater than N.
|
||||
(Postings with multi-commodity amounts are not tested and will always
|
||||
match.) The comparison has two modes: if N is preceded by a + or - sign
|
||||
(or is 0), the two signed numbers are compared.
|
||||
Otherwise, the absolute magnitudes are compared, ignoring sign.
|
||||
.PP
|
||||
\f[B]\f[CB]code:REGEX\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match by transaction code (eg check number).
|
||||
.PP
|
||||
\f[B]\f[CB]cur:REGEX\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match postings or transactions including any amounts whose
|
||||
currency/commodity symbol is fully matched by REGEX.
|
||||
(For a partial match, use \f[C].*REGEX.*\f[R]).
|
||||
Note, to match special characters which are regex-significant, you need
|
||||
to escape them with \f[C]\[rs]\f[R].
|
||||
And for characters which are significant to your shell you may need one
|
||||
more level of escaping.
|
||||
So eg to match the dollar sign:
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
|
||||
.PP
|
||||
\f[B]\f[CB]desc:REGEX\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match transaction descriptions.
|
||||
.PP
|
||||
\f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match dates (or with the \f[C]--date2\f[R] flag, secondary dates) within
|
||||
the specified period.
|
||||
PERIODEXPR is a period expression with no report interval.
|
||||
Examples:
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
\f[C]date:2016\f[R], \f[C]date:thismonth\f[R], \f[C]date:2/1-2/15\f[R],
|
||||
\f[C]date:2021-07-27..nextquarter\f[R].
|
||||
.PP
|
||||
\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match secondary dates within the specified period (independent of the
|
||||
\f[C]--date2\f[R] flag).
|
||||
.PP
|
||||
\f[B]\f[CB]depth:N\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match (or display, depending on command) accounts at or above this
|
||||
depth.
|
||||
.PP
|
||||
\f[B]\f[CB]note:REGEX\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match transaction notes (the part of the description right of
|
||||
\f[C]|\f[R], or the whole description if there\[aq]s no \f[C]|\f[R]).
|
||||
.PP
|
||||
\f[B]\f[CB]payee:REGEX\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match transaction payee/payer names (the part of the description left of
|
||||
\f[C]|\f[R], or the whole description if there\[aq]s no \f[C]|\f[R]).
|
||||
.PP
|
||||
\f[B]\f[CB]real:, real:0\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match real or virtual postings respectively.
|
||||
.PP
|
||||
\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match unmarked, pending, or cleared transactions respectively.
|
||||
.PP
|
||||
\f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Match by tag name, and optionally also by tag value.
|
||||
(To match only by value, use \f[C]tag:.=REGEX\f[R].) Note that postings
|
||||
also inherit tags from their transaction, and transactions also acquire
|
||||
tags from their postings, when querying.
|
||||
.PP
|
||||
(\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
A special query term used automatically in hledger-web only: tells
|
||||
hledger-web to show the transaction register for an account.)
|
||||
.SS Combining query terms
|
||||
.PP
|
||||
Most commands select things which match:
|
||||
.IP \[bu] 2
|
||||
any of the description terms AND
|
||||
.IP \[bu] 2
|
||||
@ -1161,7 +1322,7 @@ any of the status terms AND
|
||||
.IP \[bu] 2
|
||||
all the other terms.
|
||||
.PP
|
||||
The print command instead shows transactions which:
|
||||
while the print command shows transactions which:
|
||||
.IP \[bu] 2
|
||||
match any of the description terms AND
|
||||
.IP \[bu] 2
|
||||
@ -1171,89 +1332,49 @@ have no postings matching any of the negative account terms AND
|
||||
.IP \[bu] 2
|
||||
match all the other terms.
|
||||
.PP
|
||||
The following kinds of search terms can be used.
|
||||
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg
|
||||
to exclude a particular subaccount.
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R]
|
||||
match account names by this regular expression.
|
||||
(With no prefix, \f[C]acct:\f[R] is assumed.)
|
||||
same as above
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[R]\f[B]\f[R]
|
||||
match postings with a single-commodity amount that is equal to, less
|
||||
than, or greater than N.
|
||||
(Multi-commodity amounts are not tested, and will always match.) The
|
||||
comparison has two modes: if N is preceded by a + or - sign (or is 0),
|
||||
the two signed numbers are compared.
|
||||
Otherwise, the absolute magnitudes are compared, ignoring sign.
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R]
|
||||
match by transaction code (eg check number)
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R]
|
||||
match postings or transactions including any amounts whose
|
||||
currency/commodity symbol is fully matched by REGEX.
|
||||
(For a partial match, use \f[C].*REGEX.*\f[R]).
|
||||
Note, to match characters which are regex-significant, like the dollar
|
||||
sign (\f[C]$\f[R]), you need to prepend \f[C]\[rs]\f[R].
|
||||
And when using the command line you need to add one more level of
|
||||
quoting to hide it from the shell, so eg do:
|
||||
\f[C]hledger print cur:\[aq]\[rs]$\[aq]\f[R] or
|
||||
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R]
|
||||
match transaction descriptions.
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R]
|
||||
match dates within the specified period.
|
||||
PERIODEXPR is a period expression (with no report interval).
|
||||
Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
|
||||
\f[C]date:2000/2/1-2/15\f[R], \f[C]date:lastweek-\f[R].
|
||||
If the \f[C]--date2\f[R] command line flag is present, this matches
|
||||
secondary dates instead.
|
||||
(Report intervals will adjust start/end dates to preceding/following
|
||||
subperiod boundaries.)
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R]
|
||||
match secondary dates within the specified period.
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R]
|
||||
match (or display, depending on command) accounts at or above this depth
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R]
|
||||
match transaction notes (part of description right of \f[C]|\f[R], or
|
||||
whole description when there\[aq]s no \f[C]|\f[R])
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R]
|
||||
match transaction payee/payer names (part of description left of
|
||||
\f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R])
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R]
|
||||
match real or virtual postings respectively
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R]
|
||||
match unmarked, pending, or cleared transactions respectively
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R]
|
||||
match by tag name, and optionally also by tag value.
|
||||
Note a tag: query is considered to match a transaction if it matches any
|
||||
of the postings.
|
||||
Also remember that postings inherit the tags of their parent
|
||||
transaction.
|
||||
You can do more powerful queries (such as AND-ing two like terms) by
|
||||
running a first query with \f[C]print\f[R], and piping the result into a
|
||||
second hledger command.
|
||||
Eg: how much of food expenses was paid with cash ?
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger print assets:cash | hledger f- -I balance expenses:food
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
The following special search term is used automatically in hledger-web,
|
||||
only:
|
||||
.TP
|
||||
\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R]
|
||||
tells hledger-web to show the transaction register for this account.
|
||||
Can be filtered further with \f[C]acct\f[R] etc.
|
||||
If you are interested in full boolean expressions for queries, see #203.
|
||||
.SS Queries and command options
|
||||
.PP
|
||||
Some of these can also be expressed as command-line options (eg
|
||||
\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R]).
|
||||
Generally you can mix options and query arguments, and the resulting
|
||||
query will be their intersection (perhaps excluding the
|
||||
\f[C]-p/--period\f[R] option).
|
||||
Some queries can also be expressed as command-line options:
|
||||
\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R],
|
||||
\f[C]date:2020\f[R] is equivalent to \f[C]-p 2020\f[R], etc.
|
||||
When you mix command options and query arguments, generally the
|
||||
resulting query is their intersection.
|
||||
.SS Queries and account aliases
|
||||
.PP
|
||||
When account names are rewritten with \f[C]--alias\f[R] or
|
||||
\f[C]alias\f[R], \f[C]acct:\f[R] will match either the old or the new
|
||||
account name.
|
||||
.SS Queries and valuation
|
||||
.PP
|
||||
When amounts are converted to other commodities in cost or value
|
||||
reports, \f[C]cur:\f[R] and \f[C]amt:\f[R] match the old commodity
|
||||
symbol and the old amount quantity, not the new ones (except in hledger
|
||||
1.22.0 where it\[aq]s reversed, see #1625).
|
||||
.SS Querying with account aliases
|
||||
.PP
|
||||
When account names are rewritten with \f[C]--alias\f[R] or
|
||||
\f[C]alias\f[R], note that \f[C]acct:\f[R] will match either the old or
|
||||
the new account name.
|
||||
.SS Querying with cost or value
|
||||
.PP
|
||||
When amounts are converted to other commodities in cost or value
|
||||
reports, note that \f[C]cur:\f[R] matches the new commodity symbol, and
|
||||
not the old one, and \f[C]amt:\f[R] matches the new quantity, and not
|
||||
the old one.
|
||||
Note: this changed in hledger 1.22, previously it was the reverse, see
|
||||
the discussion at #1625.
|
||||
.SH COSTING
|
||||
.PP
|
||||
The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale
|
||||
@ -2783,6 +2904,9 @@ With \f[C]-S/--sort-amount\f[R], accounts with the largest (most
|
||||
positive) balances are shown first.
|
||||
Eg: \f[C]hledger bal expenses -MAS\f[R] shows your biggest averaged
|
||||
monthly expenses first.
|
||||
When more than one commodity is present, they will be sorted by the
|
||||
alphabetically earliest commodity first, and then by subsequent
|
||||
commodities (if an amount is missing a commodity, it is treated as 0).
|
||||
.PP
|
||||
Revenues and liability balances are typically negative, however, so
|
||||
\f[C]-S\f[R] shows these in reverse order.
|
||||
@ -3255,7 +3379,7 @@ Budget performance in 2020-01-01..2020-01-15:
|
||||
|| $400 [80% of $500]
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Nested budgets
|
||||
.SS Budgets and subaccounts
|
||||
.PP
|
||||
You can add budgets to any account in your account hierarchy.
|
||||
If you have budgets on both parent account and some of its children,
|
||||
@ -3357,6 +3481,34 @@ Budget performance in 2019/01:
|
||||
|| 0 [ 0]
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Selecting budget goals
|
||||
.PP
|
||||
The budget report evaluates periodic transaction rules to generate
|
||||
special \[dq]goal transactions\[dq], which generate the goal amounts for
|
||||
each account in each report subperiod.
|
||||
When troubleshooting, you can use the print command to show these as
|
||||
forecasted transactions:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
By default, the budget report uses all available periodic transaction
|
||||
rules to generate goals.
|
||||
This includes rules with a different report interval from your report.
|
||||
Eg if you have daily, weekly and monthly periodic rules, all of these
|
||||
will contribute to the goals in a monthly budget report.
|
||||
.PP
|
||||
You can select a subset of periodic rules by providing an argument to
|
||||
the \f[C]--budget\f[R] flag.
|
||||
\f[C]--budget=DESCPAT\f[R] will match all periodic rules whose
|
||||
description contains DESCPAT, a case-insensitive substring (not a
|
||||
regular expression or query).
|
||||
This means you can give your periodic rules descriptions (remember that
|
||||
two spaces are needed), and then select from multiple budgets defined in
|
||||
your journal.
|
||||
.SS Customising single-period balance reports
|
||||
.PP
|
||||
For single-period balance reports displayed in the terminal (only), you
|
||||
@ -4871,6 +5023,28 @@ Using roi to compute total return of investment in stocks:
|
||||
https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger
|
||||
.IP \[bu] 2
|
||||
Cookbook -> Return on Investment
|
||||
.SS Spaces and special characters in \f[C]--inv\f[R] and \f[C]--pnl\f[R]
|
||||
.PP
|
||||
Note that \f[C]--inv\f[R] and \f[C]--pnl\f[R]\[aq]s argument is a query,
|
||||
and queries could have several space-separated terms (see QUERIES).
|
||||
.PP
|
||||
To indicate that all search terms form single command-line argument, you
|
||||
will need to put them in quotes (see Special characters):
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger roi --inv \[aq]term1 term2 term3 ...\[aq]
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
If any query terms contain spaces themselves, you will need an extra
|
||||
level of nested quoting, eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger roi --inv=\[dq]\[aq]Assets:Test 1\[aq]\[dq] --pnl=\[dq]\[aq]Equity:Unrealized Profit and Loss\[aq]\[dq]
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Semantics of \f[C]--inv\f[R] and \f[C]--pnl\f[R]
|
||||
.PP
|
||||
Query supplied to \f[C]--inv\f[R] has to match all transactions that are
|
||||
|
||||
1288
hledger/hledger.info
1288
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user