doc: update manuals
This commit is contained in:
Simon Michael
parent
1126b4b0dd
commit
416555b65a
@ -1,5 +1,5 @@
|
|||||||
|
|
||||||
.TH "HLEDGER-UI" "1" "September 2021" "hledger-ui-1.22.99 " "hledger User Manuals"
|
.TH "HLEDGER-UI" "1" "September 2021" "hledger-ui-1.23 " "hledger User Manuals"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -7,7 +7,7 @@
|
|||||||
.PP
|
.PP
|
||||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||||
tool.
|
tool.
|
||||||
This manual is for hledger-ui 1.22.99.
|
This manual is for hledger-ui 1.23.
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.PP
|
.PP
|
||||||
\f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
|
\f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
|
||||||
@ -185,6 +185,14 @@ terminal.
|
|||||||
into \[aq]less -R\[aq].
|
into \[aq]less -R\[aq].
|
||||||
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
||||||
A NO_COLOR environment variable overrides this.
|
A NO_COLOR environment variable overrides this.
|
||||||
|
.TP
|
||||||
|
\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R]
|
||||||
|
Show prettier output, e.g.
|
||||||
|
using unicode box-drawing characters.
|
||||||
|
Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],
|
||||||
|
\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).
|
||||||
|
If you provide an argument you must use \[aq]=\[aq], e.g.
|
||||||
|
\[aq]--pretty=yes\[aq].
|
||||||
.PP
|
.PP
|
||||||
When a reporting option appears more than once in the command line, the
|
When a reporting option appears more than once in the command line, the
|
||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
|
|||||||
@ -12,7 +12,7 @@ hledger-ui(1)
|
|||||||
*************
|
*************
|
||||||
|
|
||||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||||
tool. This manual is for hledger-ui 1.22.99.
|
tool. This manual is for hledger-ui 1.23.
|
||||||
|
|
||||||
'hledger-ui [OPTIONS] [QUERYARGS]'
|
'hledger-ui [OPTIONS] [QUERYARGS]'
|
||||||
'hledger ui -- [OPTIONS] [QUERYARGS]'
|
'hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||||
@ -204,6 +204,12 @@ the data.
|
|||||||
color-supporting terminal. 'always' or 'yes': always, useful eg
|
color-supporting terminal. 'always' or 'yes': always, useful eg
|
||||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||||
NO_COLOR environment variable overrides this.
|
NO_COLOR environment variable overrides this.
|
||||||
|
'--pretty[=WHEN]'
|
||||||
|
|
||||||
|
Show prettier output, e.g. using unicode box-drawing characters.
|
||||||
|
Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'
|
||||||
|
also work). If you provide an argument you must use '=', e.g.
|
||||||
|
'-pretty=yes'.
|
||||||
|
|
||||||
When a reporting option appears more than once in the command line,
|
When a reporting option appears more than once in the command line,
|
||||||
the last one takes precedence.
|
the last one takes precedence.
|
||||||
@ -602,32 +608,32 @@ program is restarted.
|
|||||||
|
|
||||||
Tag Table:
|
Tag Table:
|
||||||
Node: Top221
|
Node: Top221
|
||||||
Node: OPTIONS1647
|
Node: OPTIONS1644
|
||||||
Ref: #options1744
|
Ref: #options1741
|
||||||
Node: KEYS6375
|
Node: KEYS6620
|
||||||
Ref: #keys6470
|
Ref: #keys6715
|
||||||
Node: SCREENS10541
|
Node: SCREENS10786
|
||||||
Ref: #screens10639
|
Ref: #screens10884
|
||||||
Node: Accounts screen10729
|
Node: Accounts screen10974
|
||||||
Ref: #accounts-screen10857
|
Ref: #accounts-screen11102
|
||||||
Node: Register screen13072
|
Node: Register screen13317
|
||||||
Ref: #register-screen13227
|
Ref: #register-screen13472
|
||||||
Node: Transaction screen15224
|
Node: Transaction screen15469
|
||||||
Ref: #transaction-screen15382
|
Ref: #transaction-screen15627
|
||||||
Node: Error screen16252
|
Node: Error screen16497
|
||||||
Ref: #error-screen16374
|
Ref: #error-screen16619
|
||||||
Node: TIPS16618
|
Node: TIPS16863
|
||||||
Ref: #tips16717
|
Ref: #tips16962
|
||||||
Node: Watch mode16769
|
Node: Watch mode17014
|
||||||
Ref: #watch-mode16886
|
Ref: #watch-mode17131
|
||||||
Node: Watch mode limitations17632
|
Node: Watch mode limitations17877
|
||||||
Ref: #watch-mode-limitations17773
|
Ref: #watch-mode-limitations18018
|
||||||
Node: ENVIRONMENT18909
|
Node: ENVIRONMENT19154
|
||||||
Ref: #environment19020
|
Ref: #environment19265
|
||||||
Node: FILES19827
|
Node: FILES20072
|
||||||
Ref: #files19926
|
Ref: #files20171
|
||||||
Node: BUGS20139
|
Node: BUGS20384
|
||||||
Ref: #bugs20216
|
Ref: #bugs20461
|
||||||
|
|
||||||
End Tag Table
|
End Tag Table
|
||||||
|
|
||||||
|
|||||||
@ -5,7 +5,7 @@ HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1)
|
|||||||
|
|
||||||
NAME
|
NAME
|
||||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||||
tool. This manual is for hledger-ui 1.22.99.
|
tool. This manual is for hledger-ui 1.23.
|
||||||
|
|
||||||
SYNOPSIS
|
SYNOPSIS
|
||||||
hledger-ui [OPTIONS] [QUERYARGS]
|
hledger-ui [OPTIONS] [QUERYARGS]
|
||||||
@ -181,6 +181,12 @@ OPTIONS
|
|||||||
piping output into 'less -R'. 'never' or 'no': never. A
|
piping output into 'less -R'. 'never' or 'no': never. A
|
||||||
NO_COLOR environment variable overrides this.
|
NO_COLOR environment variable overrides this.
|
||||||
|
|
||||||
|
--pretty[=WHEN]
|
||||||
|
Show prettier output, e.g. using unicode box-drawing charac-
|
||||||
|
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
|
||||||
|
'never' also work). If you provide an argument you must use
|
||||||
|
'=', e.g. '--pretty=yes'.
|
||||||
|
|
||||||
When a reporting option appears more than once in the command line, the
|
When a reporting option appears more than once in the command line, the
|
||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
|
|
||||||
@ -202,86 +208,86 @@ OPTIONS
|
|||||||
show debug output (levels 1-9, default: 1)
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
A @FILE argument will be expanded to the contents of FILE, which should
|
A @FILE argument will be expanded to the contents of FILE, which should
|
||||||
contain one command line option/argument per line. (To prevent this,
|
contain one command line option/argument per line. (To prevent this,
|
||||||
insert a -- argument before.)
|
insert a -- argument before.)
|
||||||
|
|
||||||
KEYS
|
KEYS
|
||||||
? shows a help dialog listing all keys. (Some of these also appear in
|
? shows a help dialog listing all keys. (Some of these also appear in
|
||||||
the quick help at the bottom of each screen.) Press ? again (or ESCAPE,
|
the quick help at the bottom of each screen.) Press ? again (or ESCAPE,
|
||||||
or LEFT, or q) to close it. The following keys work on most screens:
|
or LEFT, or q) to close it. The following keys work on most screens:
|
||||||
|
|
||||||
The cursor keys navigate: right (or enter) goes deeper, left returns to
|
The cursor keys navigate: right (or enter) goes deeper, left returns to
|
||||||
the previous screen, up/down/page up/page down/home/end move up and
|
the previous screen, up/down/page up/page down/home/end move up and
|
||||||
down through lists. Emacs-style (ctrl-p/ctrl-n/ctrl-f/ctrl-b) movement
|
down through lists. Emacs-style (ctrl-p/ctrl-n/ctrl-f/ctrl-b) movement
|
||||||
keys are also supported (but not vi-style keys, since hledger-1.19,
|
keys are also supported (but not vi-style keys, since hledger-1.19,
|
||||||
sorry!). A tip: movement speed is limited by your keyboard repeat
|
sorry!). A tip: movement speed is limited by your keyboard repeat
|
||||||
rate, to move faster you may want to adjust it. (If you're on a mac,
|
rate, to move faster you may want to adjust it. (If you're on a mac,
|
||||||
the karabiner app is one way to do that.)
|
the karabiner app is one way to do that.)
|
||||||
|
|
||||||
With shift pressed, the cursor keys adjust the report period, limiting
|
With shift pressed, the cursor keys adjust the report period, limiting
|
||||||
the transactions to be shown (by default, all are shown). shift-
|
the transactions to be shown (by default, all are shown). shift-
|
||||||
down/up steps downward and upward through these standard report period
|
down/up steps downward and upward through these standard report period
|
||||||
durations: year, quarter, month, week, day. Then, shift-left/right
|
durations: year, quarter, month, week, day. Then, shift-left/right
|
||||||
moves to the previous/next period. T sets the report period to today.
|
moves to the previous/next period. T sets the report period to today.
|
||||||
With the --watch option, when viewing a "current" period (the current
|
With the --watch option, when viewing a "current" period (the current
|
||||||
day, week, month, quarter, or year), the period will move automatically
|
day, week, month, quarter, or year), the period will move automatically
|
||||||
to track the current date. To set a non-standard period, you can use /
|
to track the current date. To set a non-standard period, you can use /
|
||||||
and a date: query.
|
and a date: query.
|
||||||
|
|
||||||
/ lets you set a general filter query limiting the data shown, using
|
/ lets you set a general filter query limiting the data shown, using
|
||||||
the same query terms as in hledger and hledger-web. While editing the
|
the same query terms as in hledger and hledger-web. While editing the
|
||||||
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
|
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
|
||||||
it, or ESCAPEto cancel. There are also keys for quickly adjusting some
|
it, or ESCAPEto cancel. There are also keys for quickly adjusting some
|
||||||
common filters like account depth and transaction status (see below).
|
common filters like account depth and transaction status (see below).
|
||||||
BACKSPACE or DELETE removes all filters, showing all transactions.
|
BACKSPACE or DELETE removes all filters, showing all transactions.
|
||||||
|
|
||||||
As mentioned above, by default hledger-ui hides future transactions -
|
As mentioned above, by default hledger-ui hides future transactions -
|
||||||
both ordinary transactions recorded in the journal, and periodic trans-
|
both ordinary transactions recorded in the journal, and periodic trans-
|
||||||
actions generated by rule. F toggles forecast mode, in which
|
actions generated by rule. F toggles forecast mode, in which
|
||||||
future/forecasted transactions are shown.
|
future/forecasted transactions are shown.
|
||||||
|
|
||||||
ESCAPE resets the UI state and jumps back to the top screen, restoring
|
ESCAPE resets the UI state and jumps back to the top screen, restoring
|
||||||
the app's initial state at startup. Or, it cancels minibuffer data
|
the app's initial state at startup. Or, it cancels minibuffer data
|
||||||
entry or the help dialog.
|
entry or the help dialog.
|
||||||
|
|
||||||
CTRL-l redraws the screen and centers the selection if possible (selec-
|
CTRL-l redraws the screen and centers the selection if possible (selec-
|
||||||
tions near the top won't be centered, since we don't scroll above the
|
tions near the top won't be centered, since we don't scroll above the
|
||||||
top).
|
top).
|
||||||
|
|
||||||
g reloads from the data file(s) and updates the current screen and any
|
g reloads from the data file(s) and updates the current screen and any
|
||||||
previous screens. (With large files, this could cause a noticeable
|
previous screens. (With large files, this could cause a noticeable
|
||||||
pause.)
|
pause.)
|
||||||
|
|
||||||
I toggles balance assertion checking. Disabling balance assertions
|
I toggles balance assertion checking. Disabling balance assertions
|
||||||
temporarily can be useful for troubleshooting.
|
temporarily can be useful for troubleshooting.
|
||||||
|
|
||||||
a runs command-line hledger's add command, and reloads the updated
|
a runs command-line hledger's add command, and reloads the updated
|
||||||
file. This allows some basic data entry.
|
file. This allows some basic data entry.
|
||||||
|
|
||||||
A is like a, but runs the hledger-iadd tool, which provides a terminal
|
A is like a, but runs the hledger-iadd tool, which provides a terminal
|
||||||
interface. This key will be available if hledger-iadd is installed in
|
interface. This key will be available if hledger-iadd is installed in
|
||||||
$path.
|
$path.
|
||||||
|
|
||||||
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
|
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
|
||||||
-nw) on the journal file. With some editors (emacs, vi), the cursor
|
-nw) on the journal file. With some editors (emacs, vi), the cursor
|
||||||
will be positioned at the current transaction when invoked from the
|
will be positioned at the current transaction when invoked from the
|
||||||
register and transaction screens, and at the error location (if possi-
|
register and transaction screens, and at the error location (if possi-
|
||||||
ble) when invoked from the error screen.
|
ble) when invoked from the error screen.
|
||||||
|
|
||||||
B toggles cost mode, showing amounts in their transaction price's com-
|
B toggles cost mode, showing amounts in their transaction price's com-
|
||||||
modity (like toggling the -B/--cost flag).
|
modity (like toggling the -B/--cost flag).
|
||||||
|
|
||||||
V toggles value mode, showing amounts' current market value in their
|
V toggles value mode, showing amounts' current market value in their
|
||||||
default valuation commodity (like toggling the -V/--market flag).
|
default valuation commodity (like toggling the -V/--market flag).
|
||||||
Note, "current market value" means the value on the report end date if
|
Note, "current market value" means the value on the report end date if
|
||||||
specified, otherwise today. To see the value on another date, you can
|
specified, otherwise today. To see the value on another date, you can
|
||||||
temporarily set that as the report end date. Eg: to see a transaction
|
temporarily set that as the report end date. Eg: to see a transaction
|
||||||
as it was valued on july 30, go to the accounts or register screen,
|
as it was valued on july 30, go to the accounts or register screen,
|
||||||
press /, and add date:-7/30 to the query.
|
press /, and add date:-7/30 to the query.
|
||||||
|
|
||||||
At most one of cost or value mode can be active at once.
|
At most one of cost or value mode can be active at once.
|
||||||
|
|
||||||
There's not yet any visual reminder when cost or value mode is active;
|
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.
|
for now pressing b b v should reliably reset to normal mode.
|
||||||
|
|
||||||
q quits the application.
|
q quits the application.
|
||||||
@ -290,44 +296,44 @@ KEYS
|
|||||||
|
|
||||||
SCREENS
|
SCREENS
|
||||||
Accounts screen
|
Accounts screen
|
||||||
This is normally the first screen displayed. It lists accounts and
|
This is normally the first screen displayed. It lists accounts and
|
||||||
their balances, like hledger's balance command. By default, it shows
|
their balances, like hledger's balance command. By default, it shows
|
||||||
all accounts and their latest ending balances (including the balances
|
all accounts and their latest ending balances (including the balances
|
||||||
of subaccounts). If you specify a query on the command line, it shows
|
of subaccounts). If you specify a query on the command line, it shows
|
||||||
just the matched accounts and the balances from matched transactions.
|
just the matched accounts and the balances from matched transactions.
|
||||||
|
|
||||||
Account names are shown as a flat list by default; press t to toggle
|
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-
|
tree mode. In list mode, account balances are exclusive of subac-
|
||||||
counts, except where subaccounts are hidden by a depth limit (see
|
counts, except where subaccounts are hidden by a depth limit (see
|
||||||
below). In tree mode, all account balances are inclusive of subac-
|
below). In tree mode, all account balances are inclusive of subac-
|
||||||
counts.
|
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
|
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
|
less detail, collapsing all accounts to a single total. To remove the
|
||||||
depth limit, set it higher than the maximum account depth, or press
|
depth limit, set it higher than the maximum account depth, or press
|
||||||
ESCAPE.
|
ESCAPE.
|
||||||
|
|
||||||
H toggles between showing historical balances or period balances. His-
|
H toggles between showing historical balances or period balances. His-
|
||||||
torical balances (the default) are ending balances at the end of the
|
torical balances (the default) are ending balances at the end of the
|
||||||
report period, taking into account all transactions before that date
|
report period, taking into account all transactions before that date
|
||||||
(filtered by the filter query if any), including transactions before
|
(filtered by the filter query if any), including transactions before
|
||||||
the start of the report period. In other words, historical balances
|
the start of the report period. In other words, historical balances
|
||||||
are what you would see on a bank statement for that account (unless
|
are what you would see on a bank statement for that account (unless
|
||||||
disturbed by a filter query). Period balances ignore transactions
|
disturbed by a filter query). Period balances ignore transactions
|
||||||
before the report start date, so they show the change in balance during
|
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.
|
the report period. They are more useful eg when viewing a time log.
|
||||||
|
|
||||||
U toggles filtering by unmarked status, including or excluding unmarked
|
U toggles filtering by unmarked status, including or excluding unmarked
|
||||||
postings in the balances. Similarly, P toggles pending postings, and C
|
postings in the balances. Similarly, P toggles pending postings, and C
|
||||||
toggles cleared postings. (By default, balances include all postings;
|
toggles cleared postings. (By default, balances include all postings;
|
||||||
if you activate one or two status filters, only those postings are
|
if you activate one or two status filters, only those postings are
|
||||||
included; and if you activate all three, the filter is removed.)
|
included; and if you activate all three, the filter is removed.)
|
||||||
|
|
||||||
R toggles real mode, in which virtual postings are ignored.
|
R toggles real mode, in which virtual postings are ignored.
|
||||||
|
|
||||||
Z toggles nonzero mode, in which only accounts with nonzero balances
|
Z toggles nonzero mode, in which only accounts with nonzero balances
|
||||||
are shown (hledger-ui shows zero items by default, unlike command-line
|
are shown (hledger-ui shows zero items by default, unlike command-line
|
||||||
hledger).
|
hledger).
|
||||||
|
|
||||||
Press right or enter to view an account's transactions register.
|
Press right or enter to view an account's transactions register.
|
||||||
@ -336,124 +342,124 @@ SCREENS
|
|||||||
This screen shows the transactions affecting a particular account, like
|
This screen shows the transactions affecting a particular account, like
|
||||||
a check register. Each line represents one transaction and shows:
|
a check register. Each line represents one transaction and shows:
|
||||||
|
|
||||||
o the other account(s) involved, in abbreviated form. (If there are
|
o the other account(s) involved, in abbreviated form. (If there are
|
||||||
both real and virtual postings, it shows only the accounts affected
|
both real and virtual postings, it shows only the accounts affected
|
||||||
by real postings.)
|
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.
|
inflow to this account, negative for an outflow.
|
||||||
|
|
||||||
o the running historical total or period total for the current account,
|
o the running historical total or period total for the current account,
|
||||||
after the transaction. This can be toggled with H. Similar to the
|
after the transaction. This can be toggled with H. Similar to the
|
||||||
accounts screen, the historical total is affected by transactions
|
accounts screen, the historical total is affected by transactions
|
||||||
(filtered by the filter query) before the report start date, while
|
(filtered by the filter query) before the report start date, while
|
||||||
the period total is not. If the historical total is not disturbed by
|
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.
|
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
|
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
|
mode but this account has subaccounts which are not shown due to a
|
||||||
depth limit. In other words, the register always shows the transac-
|
depth limit. In other words, the register always shows the transac-
|
||||||
tions contributing to the balance shown on the accounts screen. Tree
|
tions contributing to the balance shown on the accounts screen. Tree
|
||||||
mode/list mode can be toggled with t here also.
|
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
|
transactions. Similarly, P toggles pending transactions, and C toggles
|
||||||
cleared transactions. (By default, transactions with all statuses are
|
cleared transactions. (By default, transactions with all statuses are
|
||||||
shown; if you activate one or two status filters, only those transac-
|
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.)
|
tions are shown; and if you activate all three, the filter is removed.)
|
||||||
|
|
||||||
R toggles real mode, in which virtual postings are ignored.
|
R toggles real mode, in which virtual postings are ignored.
|
||||||
|
|
||||||
Z toggles nonzero mode, in which only transactions posting a nonzero
|
Z toggles nonzero mode, in which only transactions posting a nonzero
|
||||||
change are shown (hledger-ui shows zero items by default, unlike com-
|
change are shown (hledger-ui shows zero items by default, unlike com-
|
||||||
mand-line hledger).
|
mand-line hledger).
|
||||||
|
|
||||||
Press right (or enter) to view the selected transaction in detail.
|
Press right (or enter) to view the selected transaction in detail.
|
||||||
|
|
||||||
Transaction screen
|
Transaction screen
|
||||||
This screen shows a single transaction, as a general journal entry,
|
This screen shows a single transaction, as a general journal entry,
|
||||||
similar to hledger's print command and journal format (hledger_jour-
|
similar to hledger's print command and journal format (hledger_jour-
|
||||||
nal(5)).
|
nal(5)).
|
||||||
|
|
||||||
The transaction's date(s) and any cleared flag, transaction code,
|
The transaction's date(s) and any cleared flag, transaction code,
|
||||||
description, comments, along with all of its account postings are
|
description, comments, along with all of its account postings are
|
||||||
shown. Simple transactions have two postings, but there can be more
|
shown. Simple transactions have two postings, but there can be more
|
||||||
(or in certain cases, fewer).
|
(or in certain cases, fewer).
|
||||||
|
|
||||||
up and down will step through all transactions listed in the previous
|
up and down will step through all transactions listed in the previous
|
||||||
account register screen. In the title bar, the numbers in parentheses
|
account register screen. In the title bar, the numbers in parentheses
|
||||||
show your position within that account register. They will vary
|
show your position within that account register. They will vary
|
||||||
depending on which account register you came from (remember most trans-
|
depending on which account register you came from (remember most trans-
|
||||||
actions appear in multiple account registers). The #N number preceding
|
actions appear in multiple account registers). The #N number preceding
|
||||||
them is the transaction's position within the complete unfiltered jour-
|
them is the transaction's position within the complete unfiltered jour-
|
||||||
nal, which is a more stable id (at least until the next reload).
|
nal, which is a more stable id (at least until the next reload).
|
||||||
|
|
||||||
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
|
||||||
again to reload and resume normal operation. (Or, you can press escape
|
again to reload and resume normal operation. (Or, you can press escape
|
||||||
to cancel the reload attempt.)
|
to cancel the reload attempt.)
|
||||||
|
|
||||||
TIPS
|
TIPS
|
||||||
Watch mode
|
Watch mode
|
||||||
One of hledger-ui's best features is the auto-reloading --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
|
With this flag, it will update the display automatically whenever
|
||||||
changes are saved to the data files.
|
changes are saved to the data files.
|
||||||
|
|
||||||
This is very useful when reconciling. A good workflow is to have your
|
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
|
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
|
journal file open in an editor window; and hledger-ui in watch mode in
|
||||||
a terminal window, eg:
|
a terminal window, eg:
|
||||||
|
|
||||||
$ hledger-ui --watch --register checking -C
|
$ hledger-ui --watch --register checking -C
|
||||||
|
|
||||||
As you mark things cleared in the editor, you can see the effect imme-
|
As you mark things cleared in the editor, you can see the effect imme-
|
||||||
diately without having to context switch. This leaves more mental
|
diately without having to context switch. This leaves more mental
|
||||||
bandwidth for your accounting. Of course you can still interact with
|
bandwidth for your accounting. Of course you can still interact with
|
||||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||||
history.
|
history.
|
||||||
|
|
||||||
Watch mode limitations
|
Watch mode limitations
|
||||||
There are situations in which it won't work, ie the display will not
|
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
|
update when you save a change (because the underlying inotify library
|
||||||
does not support it). Here are some that we know of:
|
does not support it). Here are some that we know of:
|
||||||
|
|
||||||
o Certain editors: saving with gedit, and perhaps any Gnome applica-
|
o Certain editors: saving with gedit, and perhaps any Gnome applica-
|
||||||
tion, won't be detected (#1617). Jetbrains IDEs, such as IDEA, also
|
tion, won't be detected (#1617). Jetbrains IDEs, such as IDEA, also
|
||||||
may not work (#911).
|
may not work (#911).
|
||||||
|
|
||||||
o Certain unusual filesystems might not be supported. (All the usual
|
o Certain unusual filesystems might not be supported. (All the usual
|
||||||
ones on unix, mac and windows are supported.)
|
ones on unix, mac and windows are supported.)
|
||||||
|
|
||||||
In such cases, the workaround is to switch to the hledger-ui window and
|
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
|
press g each time you want it to reload. (Actually, see #1617 for
|
||||||
another workaround, and let us know if it works for you.)
|
another workaround, and let us know if it works for you.)
|
||||||
|
|
||||||
If you leave hledger-ui --watch running for days, on certain platforms
|
If you leave hledger-ui --watch running for days, on certain platforms
|
||||||
(?), perhaps with many transactions in your journal (?), perhaps with
|
(?), perhaps with many transactions in your journal (?), perhaps with
|
||||||
large numbers of other files present (?), you may see it gradually
|
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-
|
using more and more memory and CPU over time, as seen in top or Activ-
|
||||||
ity Monitor or Task Manager.
|
ity Monitor or Task Manager.
|
||||||
|
|
||||||
A workaround is to quit and restart it, or to suspend it (CTRL-z) and
|
A workaround is to quit and restart it, or to suspend it (CTRL-z) and
|
||||||
restart it (fg) if your shell supports that.
|
restart it (fg) if your shell supports that.
|
||||||
|
|
||||||
ENVIRONMENT
|
ENVIRONMENT
|
||||||
COLUMNS The screen width to use. Default: the full terminal width.
|
COLUMNS The screen width to use. Default: the full terminal width.
|
||||||
|
|
||||||
LEDGER_FILE The journal file path when not specified with -f. Default:
|
LEDGER_FILE The journal file path when not specified with -f. Default:
|
||||||
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
|
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
|
||||||
nal).
|
nal).
|
||||||
|
|
||||||
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
|
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
|
||||||
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
|
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
|
||||||
rent.journal, where current.journal is a symbolic link to YYYY.journal.
|
rent.journal, where current.journal is a symbolic link to YYYY.journal.
|
||||||
|
|
||||||
On Mac computers, you can set this and other environment variables in a
|
On Mac computers, you can set this and other environment variables in a
|
||||||
more thorough way that also affects applications started from the GUI
|
more thorough way that also affects applications started from the GUI
|
||||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||||
~/.MacOSX/environment.plist file containing
|
~/.MacOSX/environment.plist file containing
|
||||||
|
|
||||||
{
|
{
|
||||||
@ -463,13 +469,13 @@ ENVIRONMENT
|
|||||||
To see the effect you may need to killall Dock, or reboot.
|
To see the effect you may need to killall Dock, or reboot.
|
||||||
|
|
||||||
FILES
|
FILES
|
||||||
Reads data from one or more files in hledger journal, timeclock, time-
|
Reads data from one or more files in hledger journal, timeclock, time-
|
||||||
dot, or CSV format specified with -f, or $LEDGER_FILE, or
|
dot, or CSV format specified with -f, or $LEDGER_FILE, or
|
||||||
$HOME/.hledger.journal (on windows, perhaps
|
$HOME/.hledger.journal (on windows, perhaps
|
||||||
C:/Users/USER/.hledger.journal).
|
C:/Users/USER/.hledger.journal).
|
||||||
|
|
||||||
BUGS
|
BUGS
|
||||||
The need to precede options with -- when invoked from hledger is awk-
|
The need to precede options with -- when invoked from hledger is awk-
|
||||||
ward.
|
ward.
|
||||||
|
|
||||||
-f- doesn't work (hledger-ui can't read from stdin).
|
-f- doesn't work (hledger-ui can't read from stdin).
|
||||||
@ -477,24 +483,24 @@ BUGS
|
|||||||
-V affects only the accounts screen.
|
-V affects only the accounts screen.
|
||||||
|
|
||||||
When you press g, the current and all previous screens are regenerated,
|
When you press g, the current and all previous screens are regenerated,
|
||||||
which may cause a noticeable pause with large files. Also there is no
|
which may cause a noticeable pause with large files. Also there is no
|
||||||
visual indication that this is in progress.
|
visual indication that this is in progress.
|
||||||
|
|
||||||
--watch is not yet fully robust. It works well for normal usage, but
|
--watch is not yet fully robust. It works well for normal usage, but
|
||||||
many file changes in a short time (eg saving the file thousands of
|
many file changes in a short time (eg saving the file thousands of
|
||||||
times with an editor macro) can cause problems at least on OSX. Symp-
|
times with an editor macro) can cause problems at least on OSX. Symp-
|
||||||
toms include: unresponsive UI, periodic resetting of the cursor posi-
|
toms include: unresponsive UI, periodic resetting of the cursor posi-
|
||||||
tion, momentary display of parse errors, high CPU usage eventually sub-
|
tion, momentary display of parse errors, high CPU usage eventually sub-
|
||||||
siding, and possibly a small but persistent build-up of CPU usage until
|
siding, and possibly a small but persistent build-up of CPU usage until
|
||||||
the program is restarted.
|
the program is restarted.
|
||||||
|
|
||||||
Also, if you are viewing files mounted from another machine, --watch
|
Also, if you are viewing files mounted from another machine, --watch
|
||||||
requires that both machine clocks are roughly in step.
|
requires that both machine clocks are roughly in step.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
REPORTING BUGS
|
REPORTING BUGS
|
||||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||||
or hledger mail list)
|
or hledger mail list)
|
||||||
|
|
||||||
|
|
||||||
@ -512,4 +518,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger-ui-1.22.99 September 2021 HLEDGER-UI(1)
|
hledger-ui-1.23 September 2021 HLEDGER-UI(1)
|
||||||
|
|||||||
@ -1,12 +1,12 @@
|
|||||||
|
|
||||||
.TH "HLEDGER-WEB" "1" "September 2021" "hledger-web-1.22.99 " "hledger User Manuals"
|
.TH "HLEDGER-WEB" "1" "September 2021" "hledger-web-1.23 " "hledger User Manuals"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.SH NAME
|
.SH NAME
|
||||||
.PP
|
.PP
|
||||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||||
This manual is for hledger-web 1.22.99.
|
This manual is for hledger-web 1.23.
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.PP
|
.PP
|
||||||
\f[C]hledger-web [OPTIONS]\f[R]
|
\f[C]hledger-web [OPTIONS]\f[R]
|
||||||
@ -214,6 +214,14 @@ terminal.
|
|||||||
into \[aq]less -R\[aq].
|
into \[aq]less -R\[aq].
|
||||||
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
||||||
A NO_COLOR environment variable overrides this.
|
A NO_COLOR environment variable overrides this.
|
||||||
|
.TP
|
||||||
|
\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R]
|
||||||
|
Show prettier output, e.g.
|
||||||
|
using unicode box-drawing characters.
|
||||||
|
Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],
|
||||||
|
\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).
|
||||||
|
If you provide an argument you must use \[aq]=\[aq], e.g.
|
||||||
|
\[aq]--pretty=yes\[aq].
|
||||||
.PP
|
.PP
|
||||||
When a reporting option appears more than once in the command line, the
|
When a reporting option appears more than once in the command line, the
|
||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
|
|||||||
@ -12,7 +12,7 @@ hledger-web(1)
|
|||||||
**************
|
**************
|
||||||
|
|
||||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||||
This manual is for hledger-web 1.22.99.
|
This manual is for hledger-web 1.23.
|
||||||
|
|
||||||
'hledger-web [OPTIONS]'
|
'hledger-web [OPTIONS]'
|
||||||
'hledger web -- [OPTIONS]'
|
'hledger web -- [OPTIONS]'
|
||||||
@ -230,6 +230,12 @@ before options, as shown in the synopsis above.
|
|||||||
color-supporting terminal. 'always' or 'yes': always, useful eg
|
color-supporting terminal. 'always' or 'yes': always, useful eg
|
||||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||||
NO_COLOR environment variable overrides this.
|
NO_COLOR environment variable overrides this.
|
||||||
|
'--pretty[=WHEN]'
|
||||||
|
|
||||||
|
Show prettier output, e.g. using unicode box-drawing characters.
|
||||||
|
Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'
|
||||||
|
also work). If you provide an argument you must use '=', e.g.
|
||||||
|
'-pretty=yes'.
|
||||||
|
|
||||||
When a reporting option appears more than once in the command line,
|
When a reporting option appears more than once in the command line,
|
||||||
the last one takes precedence.
|
the last one takes precedence.
|
||||||
@ -611,22 +617,22 @@ awkward.
|
|||||||
|
|
||||||
Tag Table:
|
Tag Table:
|
||||||
Node: Top223
|
Node: Top223
|
||||||
Node: OPTIONS1889
|
Node: OPTIONS1886
|
||||||
Ref: #options1994
|
Ref: #options1991
|
||||||
Node: PERMISSIONS9657
|
Node: PERMISSIONS9902
|
||||||
Ref: #permissions9796
|
Ref: #permissions10041
|
||||||
Node: EDITING UPLOADING DOWNLOADING11008
|
Node: EDITING UPLOADING DOWNLOADING11253
|
||||||
Ref: #editing-uploading-downloading11189
|
Ref: #editing-uploading-downloading11434
|
||||||
Node: RELOADING12023
|
Node: RELOADING12268
|
||||||
Ref: #reloading12157
|
Ref: #reloading12402
|
||||||
Node: JSON API12590
|
Node: JSON API12835
|
||||||
Ref: #json-api12704
|
Ref: #json-api12949
|
||||||
Node: ENVIRONMENT18194
|
Node: ENVIRONMENT18439
|
||||||
Ref: #environment18310
|
Ref: #environment18555
|
||||||
Node: FILES19043
|
Node: FILES19288
|
||||||
Ref: #files19143
|
Ref: #files19388
|
||||||
Node: BUGS19356
|
Node: BUGS19601
|
||||||
Ref: #bugs19434
|
Ref: #bugs19679
|
||||||
|
|
||||||
End Tag Table
|
End Tag Table
|
||||||
|
|
||||||
|
|||||||
@ -5,7 +5,7 @@ HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1)
|
|||||||
|
|
||||||
NAME
|
NAME
|
||||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||||
This manual is for hledger-web 1.22.99.
|
This manual is for hledger-web 1.23.
|
||||||
|
|
||||||
SYNOPSIS
|
SYNOPSIS
|
||||||
hledger-web [OPTIONS]
|
hledger-web [OPTIONS]
|
||||||
@ -204,6 +204,12 @@ OPTIONS
|
|||||||
piping output into 'less -R'. 'never' or 'no': never. A
|
piping output into 'less -R'. 'never' or 'no': never. A
|
||||||
NO_COLOR environment variable overrides this.
|
NO_COLOR environment variable overrides this.
|
||||||
|
|
||||||
|
--pretty[=WHEN]
|
||||||
|
Show prettier output, e.g. using unicode box-drawing charac-
|
||||||
|
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
|
||||||
|
'never' also work). If you provide an argument you must use
|
||||||
|
'=', e.g. '--pretty=yes'.
|
||||||
|
|
||||||
When a reporting option appears more than once in the command line, the
|
When a reporting option appears more than once in the command line, the
|
||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
|
|
||||||
@ -225,54 +231,54 @@ OPTIONS
|
|||||||
show debug output (levels 1-9, default: 1)
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
A @FILE argument will be expanded to the contents of FILE, which should
|
A @FILE argument will be expanded to the contents of FILE, which should
|
||||||
contain one command line option/argument per line. (To prevent this,
|
contain one command line option/argument per line. (To prevent this,
|
||||||
insert a -- argument before.)
|
insert a -- argument before.)
|
||||||
|
|
||||||
By default, hledger-web starts the web app in "transient mode" and also
|
By default, hledger-web starts the web app in "transient mode" and also
|
||||||
opens it in your default web browser if possible. In this mode the web
|
opens it in your default web browser if possible. In this mode the web
|
||||||
app will keep running for as long as you have it open in a browser win-
|
app will keep running for as long as you have it open in a browser win-
|
||||||
dow, and will exit after two minutes of inactivity (no requests and no
|
dow, and will exit after two minutes of inactivity (no requests and no
|
||||||
browser windows viewing it). With --serve, it just runs the web app
|
browser windows viewing it). With --serve, it just runs the web app
|
||||||
without exiting, and logs requests to the console. With --serve-api,
|
without exiting, and logs requests to the console. With --serve-api,
|
||||||
only the JSON web api (see below) is served, with the usual HTML
|
only the JSON web api (see below) is served, with the usual HTML
|
||||||
server-side web UI disabled.
|
server-side web UI disabled.
|
||||||
|
|
||||||
By default the server listens on IP address 127.0.0.1, accessible only
|
By default the server listens on IP address 127.0.0.1, accessible only
|
||||||
to local requests. You can use --host to change this, eg --host
|
to local requests. You can use --host to change this, eg --host
|
||||||
0.0.0.0 to listen on all configured addresses.
|
0.0.0.0 to listen on all configured addresses.
|
||||||
|
|
||||||
Similarly, use --port to set a TCP port other than 5000, eg if you are
|
Similarly, use --port to set a TCP port other than 5000, eg if you are
|
||||||
running multiple hledger-web instances.
|
running multiple hledger-web instances.
|
||||||
|
|
||||||
Both of these options are ignored when --socket is used. In this case,
|
Both of these options are ignored when --socket is used. In this case,
|
||||||
it creates an AF_UNIX socket file at the supplied path and uses that
|
it creates an AF_UNIX socket file at the supplied path and uses that
|
||||||
for communication. This is an alternative way of running multiple
|
for communication. This is an alternative way of running multiple
|
||||||
hledger-web instances behind a reverse proxy that handles authentica-
|
hledger-web instances behind a reverse proxy that handles authentica-
|
||||||
tion for different users. The path can be derived in a predictable
|
tion for different users. The path can be derived in a predictable
|
||||||
way, eg by using the username within the path. As an example, nginx as
|
way, eg by using the username within the path. As an example, nginx as
|
||||||
reverse proxy can use the variable $remote_user to derive a path from
|
reverse proxy can use the variable $remote_user to derive a path from
|
||||||
the username used in a HTTP basic authentication. The following
|
the username used in a HTTP basic authentication. The following
|
||||||
proxy_pass directive allows access to all hledger-web instances that
|
proxy_pass directive allows access to all hledger-web instances that
|
||||||
created a socket in /tmp/hledger/:
|
created a socket in /tmp/hledger/:
|
||||||
|
|
||||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||||
|
|
||||||
You can use --base-url to change the protocol, hostname, port and path
|
You can use --base-url to change the protocol, hostname, port and path
|
||||||
that appear in hyperlinks, useful eg for integrating hledger-web within
|
that appear in hyperlinks, useful eg for integrating hledger-web within
|
||||||
a larger website. The default is http://HOST:PORT/ using the server's
|
a larger website. The default is http://HOST:PORT/ using the server's
|
||||||
configured host address and TCP port (or http://HOST if PORT is 80).
|
configured host address and TCP port (or http://HOST if PORT is 80).
|
||||||
|
|
||||||
With --file-url you can set a different base url for static files, eg
|
With --file-url you can set a different base url for static files, eg
|
||||||
for better caching or cookie-less serving on high performance websites.
|
for better caching or cookie-less serving on high performance websites.
|
||||||
|
|
||||||
PERMISSIONS
|
PERMISSIONS
|
||||||
By default, hledger-web allows anyone who can reach it to view the
|
By default, hledger-web allows anyone who can reach it to view the
|
||||||
journal and to add new transactions, but not to change existing data.
|
journal and to add new transactions, but not to change existing data.
|
||||||
|
|
||||||
You can restrict who can reach it by
|
You can restrict who can reach it by
|
||||||
|
|
||||||
o setting the IP address it listens on (see --host above). By default
|
o setting the IP address it listens on (see --host above). By default
|
||||||
it listens on 127.0.0.1, accessible to all users on the local
|
it listens on 127.0.0.1, accessible to all users on the local
|
||||||
machine.
|
machine.
|
||||||
|
|
||||||
o putting it behind an authenticating proxy, using eg apache or nginx
|
o putting it behind an authenticating proxy, using eg apache or nginx
|
||||||
@ -282,53 +288,53 @@ PERMISSIONS
|
|||||||
You can restrict what the users who reach it can do, by
|
You can restrict what the users who reach it can do, by
|
||||||
|
|
||||||
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
|
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
|
||||||
one or more of the following capabilities. The default value is
|
one or more of the following capabilities. The default value is
|
||||||
view,add:
|
view,add:
|
||||||
|
|
||||||
o view - allows viewing the journal file and all included files
|
o view - allows viewing the journal file and all included files
|
||||||
|
|
||||||
o add - allows adding new transactions to the main journal file
|
o add - allows adding new transactions to the main journal file
|
||||||
|
|
||||||
o manage - allows editing, uploading or downloading the main or
|
o manage - allows editing, uploading or downloading the main or
|
||||||
included files
|
included files
|
||||||
|
|
||||||
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
|
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
|
||||||
header from which it will read capabilities to enable. hledger-web
|
header from which it will read capabilities to enable. hledger-web
|
||||||
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
||||||
with Sandstorm's permissions. This is disabled by default.
|
with Sandstorm's permissions. This is disabled by default.
|
||||||
|
|
||||||
EDITING, UPLOADING, DOWNLOADING
|
EDITING, UPLOADING, DOWNLOADING
|
||||||
If you enable the manage capability mentioned above, you'll see a new
|
If you enable the manage capability mentioned above, you'll see a new
|
||||||
"spanner" button to the right of the search form. Clicking this will
|
"spanner" button to the right of the search form. Clicking this will
|
||||||
let you edit, upload, or download the journal file or any files it
|
let you edit, upload, or download the journal file or any files it
|
||||||
includes.
|
includes.
|
||||||
|
|
||||||
Note, unlike any other hledger command, in this mode you (or any visi-
|
Note, unlike any other hledger command, in this mode you (or any visi-
|
||||||
tor) can alter or wipe the data files.
|
tor) can alter or wipe the data files.
|
||||||
|
|
||||||
Normally whenever a file is changed in this way, hledger-web saves a
|
Normally whenever a file is changed in this way, hledger-web saves a
|
||||||
numbered backup (assuming file permissions allow it, the disk is not
|
numbered backup (assuming file permissions allow it, the disk is not
|
||||||
full, etc.) hledger-web is not aware of version control systems, cur-
|
full, etc.) hledger-web is not aware of version control systems, cur-
|
||||||
rently; if you use one, you'll have to arrange to commit the changes
|
rently; if you use one, you'll have to arrange to commit the changes
|
||||||
yourself (eg with a cron job or a file watcher like entr).
|
yourself (eg with a cron job or a file watcher like entr).
|
||||||
|
|
||||||
Changes which would leave the journal file(s) unparseable or non-valid
|
Changes which would leave the journal file(s) unparseable or non-valid
|
||||||
(eg with failing balance assertions) are prevented. (Probably. This
|
(eg with failing balance assertions) are prevented. (Probably. This
|
||||||
needs re-testing.)
|
needs re-testing.)
|
||||||
|
|
||||||
RELOADING
|
RELOADING
|
||||||
hledger-web detects changes made to the files by other means (eg if you
|
hledger-web detects changes made to the files by other means (eg if you
|
||||||
edit it directly, outside of hledger-web), and it will show the new
|
edit it directly, outside of hledger-web), and it will show the new
|
||||||
data when you reload the page or navigate to a new page. If a change
|
data when you reload the page or navigate to a new page. If a change
|
||||||
makes a file unparseable, hledger-web will display an error message
|
makes a file unparseable, hledger-web will display an error message
|
||||||
until the file has been fixed.
|
until the file has been fixed.
|
||||||
|
|
||||||
(Note: if you are viewing files mounted from another machine, make sure
|
(Note: if you are viewing files mounted from another machine, make sure
|
||||||
that both machine clocks are roughly in step.)
|
that both machine clocks are roughly in step.)
|
||||||
|
|
||||||
JSON API
|
JSON API
|
||||||
In addition to the web UI, hledger-web also serves a JSON API that can
|
In addition to the web UI, hledger-web also serves a JSON API that can
|
||||||
be used to get data or add new transactions. If you want the JSON API
|
be used to get data or add new transactions. If you want the JSON API
|
||||||
only, you can use the --serve-api flag. Eg:
|
only, you can use the --serve-api flag. Eg:
|
||||||
|
|
||||||
$ hledger-web -f examples/sample.journal --serve-api
|
$ hledger-web -f examples/sample.journal --serve-api
|
||||||
@ -345,7 +351,7 @@ JSON API
|
|||||||
/accounttransactions/ACCOUNTNAME
|
/accounttransactions/ACCOUNTNAME
|
||||||
|
|
||||||
Eg, all account names in the journal (similar to the accounts command).
|
Eg, all account names in the journal (similar to the accounts command).
|
||||||
(hledger-web's JSON does not include newlines, here we use python to
|
(hledger-web's JSON does not include newlines, here we use python to
|
||||||
prettify it):
|
prettify it):
|
||||||
|
|
||||||
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||||
@ -386,25 +392,25 @@ JSON API
|
|||||||
"aprice": null,
|
"aprice": null,
|
||||||
...
|
...
|
||||||
|
|
||||||
Most of the JSON corresponds to hledger's data types; for details of
|
Most of the JSON corresponds to hledger's data types; for details of
|
||||||
what the fields mean, see the Hledger.Data.Json haddock docs and click
|
what the fields mean, see the Hledger.Data.Json haddock docs and click
|
||||||
on the various data types, eg Transaction. And for a higher level
|
on the various data types, eg Transaction. And for a higher level
|
||||||
understanding, see the journal manual.
|
understanding, see the journal manual.
|
||||||
|
|
||||||
In some cases there is outer JSON corresponding to a "Report" type. To
|
In some cases there is outer JSON corresponding to a "Report" type. To
|
||||||
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
|
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
|
||||||
at the source for the appropriate handler to see what it returns. Eg
|
at the source for the appropriate handler to see what it returns. Eg
|
||||||
for /accounttransactions it's getAccounttransactionsR, returning a
|
for /accounttransactions it's getAccounttransactionsR, returning a
|
||||||
"accountTransactionsReport ...". Looking up the haddock for that we
|
"accountTransactionsReport ...". Looking up the haddock for that we
|
||||||
can see that /accounttransactions returns an AccountTransactionsReport,
|
can see that /accounttransactions returns an AccountTransactionsReport,
|
||||||
which consists of a report title and a list of AccountTransactionsRe-
|
which consists of a report title and a list of AccountTransactionsRe-
|
||||||
portItem (etc).
|
portItem (etc).
|
||||||
|
|
||||||
You can add a new transaction to the journal with a PUT request to
|
You can add a new transaction to the journal with a PUT request to
|
||||||
/add, if hledger-web was started with the add capability (enabled by
|
/add, if hledger-web was started with the add capability (enabled by
|
||||||
default). The payload must be the full, exact JSON representation of a
|
default). The payload must be the full, exact JSON representation of a
|
||||||
hledger transaction (partial data won't do). You can get sample JSON
|
hledger transaction (partial data won't do). You can get sample JSON
|
||||||
from hledger-web's /transactions or /accounttransactions, or you can
|
from hledger-web's /transactions or /accounttransactions, or you can
|
||||||
export it with hledger-lib, eg like so:
|
export it with hledger-lib, eg like so:
|
||||||
|
|
||||||
.../hledger$ stack ghci hledger-lib
|
.../hledger$ stack ghci hledger-lib
|
||||||
@ -500,23 +506,23 @@ JSON API
|
|||||||
"tstatus": "Unmarked"
|
"tstatus": "Unmarked"
|
||||||
}
|
}
|
||||||
|
|
||||||
And here's how to test adding it with curl. This should add a new
|
And here's how to test adding it with curl. This should add a new
|
||||||
entry to your journal:
|
entry to your journal:
|
||||||
|
|
||||||
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
|
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
|
||||||
|
|
||||||
ENVIRONMENT
|
ENVIRONMENT
|
||||||
LEDGER_FILE The journal file path when not specified with -f. Default:
|
LEDGER_FILE The journal file path when not specified with -f. Default:
|
||||||
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
|
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
|
||||||
nal).
|
nal).
|
||||||
|
|
||||||
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
|
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
|
||||||
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
|
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
|
||||||
rent.journal, where current.journal is a symbolic link to YYYY.journal.
|
rent.journal, where current.journal is a symbolic link to YYYY.journal.
|
||||||
|
|
||||||
On Mac computers, you can set this and other environment variables in a
|
On Mac computers, you can set this and other environment variables in a
|
||||||
more thorough way that also affects applications started from the GUI
|
more thorough way that also affects applications started from the GUI
|
||||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||||
~/.MacOSX/environment.plist file containing
|
~/.MacOSX/environment.plist file containing
|
||||||
|
|
||||||
{
|
{
|
||||||
@ -526,13 +532,13 @@ ENVIRONMENT
|
|||||||
To see the effect you may need to killall Dock, or reboot.
|
To see the effect you may need to killall Dock, or reboot.
|
||||||
|
|
||||||
FILES
|
FILES
|
||||||
Reads data from one or more files in hledger journal, timeclock, time-
|
Reads data from one or more files in hledger journal, timeclock, time-
|
||||||
dot, or CSV format specified with -f, or $LEDGER_FILE, or
|
dot, or CSV format specified with -f, or $LEDGER_FILE, or
|
||||||
$HOME/.hledger.journal (on windows, perhaps
|
$HOME/.hledger.journal (on windows, perhaps
|
||||||
C:/Users/USER/.hledger.journal).
|
C:/Users/USER/.hledger.journal).
|
||||||
|
|
||||||
BUGS
|
BUGS
|
||||||
The need to precede options with -- when invoked from hledger is awk-
|
The need to precede options with -- when invoked from hledger is awk-
|
||||||
ward.
|
ward.
|
||||||
|
|
||||||
-f- doesn't work (hledger-web can't read from stdin).
|
-f- doesn't work (hledger-web can't read from stdin).
|
||||||
@ -546,7 +552,7 @@ BUGS
|
|||||||
|
|
||||||
|
|
||||||
REPORTING BUGS
|
REPORTING BUGS
|
||||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||||
or hledger mail list)
|
or hledger mail list)
|
||||||
|
|
||||||
|
|
||||||
@ -564,4 +570,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger-web-1.22.99 September 2021 HLEDGER-WEB(1)
|
hledger-web-1.23 September 2021 HLEDGER-WEB(1)
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
.\"t
|
.\"t
|
||||||
|
|
||||||
.TH "HLEDGER" "1" "September 2021" "hledger-1.22.99 " "hledger User Manuals"
|
.TH "HLEDGER" "1" "September 2021" "hledger-1.23 " "hledger User Manuals"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -9,7 +9,7 @@
|
|||||||
This is the command-line interface (CLI) for the hledger accounting
|
This is the command-line interface (CLI) for the hledger accounting
|
||||||
tool.
|
tool.
|
||||||
Here we also describe hledger\[aq]s concepts and file formats.
|
Here we also describe hledger\[aq]s concepts and file formats.
|
||||||
This manual is for hledger 1.22.99.
|
This manual is for hledger 1.23.
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.PP
|
.PP
|
||||||
\f[C]hledger\f[R]
|
\f[C]hledger\f[R]
|
||||||
@ -207,6 +207,14 @@ terminal.
|
|||||||
into \[aq]less -R\[aq].
|
into \[aq]less -R\[aq].
|
||||||
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
||||||
A NO_COLOR environment variable overrides this.
|
A NO_COLOR environment variable overrides this.
|
||||||
|
.TP
|
||||||
|
\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R]
|
||||||
|
Show prettier output, e.g.
|
||||||
|
using unicode box-drawing characters.
|
||||||
|
Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],
|
||||||
|
\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).
|
||||||
|
If you provide an argument you must use \[aq]=\[aq], e.g.
|
||||||
|
\[aq]--pretty=yes\[aq].
|
||||||
.PP
|
.PP
|
||||||
When a reporting option appears more than once in the command line, the
|
When a reporting option appears more than once in the command line, the
|
||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
@ -528,7 +536,7 @@ Default: the full terminal width.
|
|||||||
.PP
|
.PP
|
||||||
\f[B]NO_COLOR\f[R] If this variable exists with any value, hledger will
|
\f[B]NO_COLOR\f[R] If this variable exists with any value, hledger will
|
||||||
not use ANSI color codes in terminal output.
|
not use ANSI color codes in terminal output.
|
||||||
This overrides the --color/--colour option.
|
This is overriden by the --color/--colour option.
|
||||||
.SH DATA FILES
|
.SH DATA FILES
|
||||||
.PP
|
.PP
|
||||||
hledger reads transactions from one or more data files.
|
hledger reads transactions from one or more data files.
|
||||||
@ -2308,6 +2316,24 @@ hledger can optionally produce debug output (if enabled with
|
|||||||
\f[C]-o/--output-file\f[R].
|
\f[C]-o/--output-file\f[R].
|
||||||
If you need to capture it, use shell redirects, eg:
|
If you need to capture it, use shell redirects, eg:
|
||||||
\f[C]hledger bal --debug=3 >file 2>&1\f[R].
|
\f[C]hledger bal --debug=3 >file 2>&1\f[R].
|
||||||
|
.SS Output styling
|
||||||
|
.PP
|
||||||
|
hledger commands can produce colour output when the terminal supports
|
||||||
|
it.
|
||||||
|
This is controlled by the \f[C]--color/--colour\f[R] option: - if the
|
||||||
|
\f[C]--color/--colour\f[R] option is given a value of \f[C]yes\f[R] or
|
||||||
|
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), colour will (or
|
||||||
|
will not) be used; - otherwise, if the \f[C]NO_COLOR\f[R] environment
|
||||||
|
variable is set, colour will not be used; - otherwise, colour will be
|
||||||
|
used if the output (terminal or file) supports it.
|
||||||
|
.PP
|
||||||
|
hledger commands can also use unicode box-drawing characters to produce
|
||||||
|
prettier tables and output.
|
||||||
|
This is controlled by the \f[C]--pretty\f[R] option: - if the
|
||||||
|
\f[C]--pretty\f[R] option is given a value of \f[C]yes\f[R] or
|
||||||
|
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), unicode
|
||||||
|
characters will (or will not) be used; - otherwise, unicode characters
|
||||||
|
will not be used.
|
||||||
.SS Output format
|
.SS Output format
|
||||||
.PP
|
.PP
|
||||||
Some commands (print, register, the balance commands) offer a choice of
|
Some commands (print, register, the balance commands) offer a choice of
|
||||||
|
|||||||
1053
hledger/hledger.info
1053
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