mirror of
https://github.com/simonmichael/hledger.git
synced 2024-11-08 07:09:28 +03:00
;doc: update manuals
This commit is contained in:
Simon Michael
parent
55f5aa9238
commit
1d3f7a2aad
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{November 2021}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{December 2021}})m4_dnl
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{November 2021}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{December 2021}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-UI" "1" "November 2021" "hledger-ui-1.23.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-UI" "1" "December 2021" "hledger-ui-1.23.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,4 +1,5 @@
|
||||
This is hledger-ui.info, produced by makeinfo version 6.8 from stdin.
|
||||
This is hledger-ui/hledger-ui.info, produced by makeinfo version 4.8
|
||||
from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
@ -6,36 +7,36 @@ START-INFO-DIR-ENTRY
|
||||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
|
||||
File: hledger-ui.info, Node: Top, Up: (dir)
|
||||
|
||||
hledger-ui(1)
|
||||
*************
|
||||
|
||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||
tool. This manual is for hledger-ui 1.23.99.
|
||||
tool. This manual is for hledger-ui 1.23.99.
|
||||
|
||||
'hledger-ui [OPTIONS] [QUERYARGS]'
|
||||
'hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||
`hledger-ui [OPTIONS] [QUERYARGS]'
|
||||
`hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||
|
||||
hledger is a reliable, cross-platform set of programs for tracking
|
||||
money, time, or any other commodity, using double-entry accounting and a
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
compatible with ledger(1).
|
||||
|
||||
hledger-ui is hledger's terminal interface, providing an efficient
|
||||
full-window text UI for viewing accounts and transactions, and some
|
||||
limited data entry capability. It is easier than hledger's command-line
|
||||
limited data entry capability. It is easier than hledger's command-line
|
||||
interface, and sometimes quicker and more convenient than the web
|
||||
interface.
|
||||
|
||||
Like hledger, it reads data from one or more files in hledger
|
||||
journal, timeclock, timedot, or CSV format specified with '-f', or
|
||||
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
|
||||
journal, timeclock, timedot, or CSV format specified with `-f', or
|
||||
`$LEDGER_FILE', or `$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
|
||||
hledger_journal(5) etc.
|
||||
|
||||
Unlike hledger, hledger-ui hides all future-dated transactions by
|
||||
default. They can be revealed, along with any rule-generated periodic
|
||||
default. They can be revealed, along with any rule-generated periodic
|
||||
transactions, by pressing the F key (or starting with -forecast) to
|
||||
enable "forecast mode".
|
||||
|
||||
@ -56,158 +57,155 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top
|
||||
1 OPTIONS
|
||||
*********
|
||||
|
||||
Note: if invoking hledger-ui as a hledger subcommand, write '--' before
|
||||
Note: if invoking hledger-ui as a hledger subcommand, write `--' before
|
||||
options as shown above.
|
||||
|
||||
Any QUERYARGS are interpreted as a hledger search query which filters
|
||||
the data.
|
||||
|
||||
'-w --watch'
|
||||
|
||||
`-w --watch'
|
||||
watch for data and date changes and reload automatically
|
||||
'--theme=default|terminal|greenterm'
|
||||
|
||||
`--theme=default|terminal|greenterm'
|
||||
use this custom display theme
|
||||
'--register=ACCTREGEX'
|
||||
|
||||
`--register=ACCTREGEX'
|
||||
start in the (first) matched account's register screen
|
||||
'--change'
|
||||
|
||||
`--change'
|
||||
show period balances (changes) at startup instead of historical
|
||||
balances
|
||||
'-l --flat'
|
||||
|
||||
`-l --flat'
|
||||
show accounts as a flat list (default)
|
||||
'-t --tree'
|
||||
|
||||
`-t --tree'
|
||||
show accounts as a tree
|
||||
|
||||
hledger input options:
|
||||
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
`-f FILE --file=FILE'
|
||||
use a different input file. For stdin, use - (default:
|
||||
`$LEDGER_FILE' or `$HOME/.hledger.journal')
|
||||
|
||||
`--rules-file=RULESFILE'
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
'--separator=CHAR'
|
||||
|
||||
`--separator=CHAR'
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
`--alias=OLD=NEW'
|
||||
rename accounts named OLD to NEW
|
||||
'--anon'
|
||||
|
||||
`--anon'
|
||||
anonymize accounts and payees
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
`--pivot FIELDNAME'
|
||||
use some other field or tag for the account name
|
||||
'-I --ignore-assertions'
|
||||
|
||||
`-I --ignore-assertions'
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
'-s --strict'
|
||||
|
||||
`-s --strict'
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
'-b --begin=DATE'
|
||||
|
||||
`-b --begin=DATE'
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
'-e --end=DATE'
|
||||
|
||||
`-e --end=DATE'
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
'-D --daily'
|
||||
|
||||
`-D --daily'
|
||||
multiperiod/multicolumn report by day
|
||||
'-W --weekly'
|
||||
|
||||
`-W --weekly'
|
||||
multiperiod/multicolumn report by week
|
||||
'-M --monthly'
|
||||
|
||||
`-M --monthly'
|
||||
multiperiod/multicolumn report by month
|
||||
'-Q --quarterly'
|
||||
|
||||
`-Q --quarterly'
|
||||
multiperiod/multicolumn report by quarter
|
||||
'-Y --yearly'
|
||||
|
||||
`-Y --yearly'
|
||||
multiperiod/multicolumn report by year
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
`-p --period=PERIODEXP'
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
'--date2'
|
||||
|
||||
`--date2'
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
'--today=DATE'
|
||||
|
||||
`--today=DATE'
|
||||
override today's date (affects relative smart dates, for
|
||||
tests/examples)
|
||||
'-U --unmarked'
|
||||
|
||||
`-U --unmarked'
|
||||
include only unmarked postings/txns (can combine with -P or -C)
|
||||
'-P --pending'
|
||||
|
||||
`-P --pending'
|
||||
include only pending postings/txns
|
||||
'-C --cleared'
|
||||
|
||||
`-C --cleared'
|
||||
include only cleared postings/txns
|
||||
'-R --real'
|
||||
|
||||
`-R --real'
|
||||
include only non-virtual postings
|
||||
'-NUM --depth=NUM'
|
||||
|
||||
`-NUM --depth=NUM'
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
'-E --empty'
|
||||
|
||||
`-E --empty'
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
'-B --cost'
|
||||
|
||||
`-B --cost'
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
'-V --market'
|
||||
|
||||
`-V --market'
|
||||
convert amounts to their market value in default valuation
|
||||
commodities
|
||||
'-X --exchange=COMM'
|
||||
|
||||
`-X --exchange=COMM'
|
||||
convert amounts to their market value in commodity COMM
|
||||
'--value'
|
||||
|
||||
`--value'
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
'--infer-market-prices'
|
||||
|
||||
`--infer-market-prices'
|
||||
use transaction prices (recorded with @ or @@) as additional market
|
||||
prices, as if they were P directives
|
||||
'--auto'
|
||||
|
||||
`--auto'
|
||||
apply automated posting rules to modify transactions.
|
||||
'--forecast'
|
||||
|
||||
`--forecast'
|
||||
generate future transactions from periodic transaction rules, for
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
make ordinary future transactions visible.
|
||||
'--commodity-style'
|
||||
|
||||
`--commodity-style'
|
||||
Override the commodity style in the output for the specified
|
||||
commodity. For example 'EUR1.000,00'.
|
||||
'--color=WHEN (or --colour=WHEN)'
|
||||
|
||||
`--color=WHEN (or --colour=WHEN)'
|
||||
Should color-supporting commands use ANSI color codes in text
|
||||
output. 'auto' (default): whenever stdout seems to be a
|
||||
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.
|
||||
'--pretty[=WHEN]'
|
||||
|
||||
Show prettier output, e.g. using unicode box-drawing characters.
|
||||
`--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'.
|
||||
@ -219,25 +217,24 @@ the last one takes precedence.
|
||||
|
||||
hledger help options:
|
||||
|
||||
'-h --help'
|
||||
|
||||
`-h --help'
|
||||
show general or COMMAND help
|
||||
'--man'
|
||||
|
||||
`--man'
|
||||
show general or COMMAND user manual with man
|
||||
'--info'
|
||||
|
||||
`--info'
|
||||
show general or COMMAND user manual with info
|
||||
'--version'
|
||||
|
||||
`--version'
|
||||
show general or ADDONCMD version
|
||||
'--debug[=N]'
|
||||
|
||||
`--debug[=N]'
|
||||
show debug output (levels 1-9, default: 1)
|
||||
|
||||
A @FILE argument will be expanded to the contents of FILE, which
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a '--' argument before.)
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a `--' argument before.)
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
||||
@ -249,7 +246,9 @@ In most modern terminals, you can navigate through the screens with a
|
||||
mouse or touchpad:
|
||||
|
||||
* Use mouse wheel or trackpad to scroll up and down
|
||||
|
||||
* Click on list items to go deeper
|
||||
|
||||
* Click on the left margin (column 0), or the blank area at bottom of
|
||||
screen, to go back.
|
||||
|
||||
@ -261,88 +260,88 @@ File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: MOUSE, Up: Top
|
||||
|
||||
Keyboard gives more control.
|
||||
|
||||
'?' 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', or 'LEFT', or 'q') to close it. The following keys work on
|
||||
`?' 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', or `LEFT', or `q') to close it. The following keys work on
|
||||
most screens:
|
||||
|
||||
The cursor keys navigate: 'RIGHT' goes deeper, 'LEFT' returns to the
|
||||
previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END' move up and down
|
||||
through lists. Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b')
|
||||
The cursor keys navigate: `RIGHT' goes deeper, `LEFT' returns to the
|
||||
previous screen, `UP'/`DOWN'/`PGUP'/`PGDN'/`HOME'/`END' move up and
|
||||
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, sorry!). A tip: movement speed is limited by your
|
||||
keyboard repeat rate, to move faster you may want to adjust it. (If
|
||||
keyboard repeat 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.)
|
||||
|
||||
With shift pressed, the cursor keys adjust the report period,
|
||||
limiting the transactions to be shown (by default, all are shown).
|
||||
'SHIFT-DOWN/UP' steps downward and upward through these standard report
|
||||
period durations: year, quarter, month, week, day. Then,
|
||||
'SHIFT-LEFT/RIGHT' moves to the previous/next period. 'T' sets the
|
||||
report period to today. With the '-w/--watch' option, when viewing a
|
||||
`SHIFT-DOWN/UP' steps downward and upward through these standard report
|
||||
period durations: year, quarter, month, week, day. Then,
|
||||
`SHIFT-LEFT/RIGHT' moves to the previous/next period. `T' sets the
|
||||
report period to today. With the `-w/--watch' option, when viewing a
|
||||
"current" period (the current 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 '/' and a 'date:' query.
|
||||
period will move automatically to track the current date. To set a
|
||||
non-standard period, you can use `/' and a `date:' query.
|
||||
|
||||
'/' 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 query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to
|
||||
set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting
|
||||
`/' 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 query, you can use CTRL-a/e/d/k, BS, cursor keys; press `ENTER' to
|
||||
set it, or `ESCAPE'to cancel. There are also keys for quickly adjusting
|
||||
some common filters like account depth and transaction status (see
|
||||
below). 'BACKSPACE' or 'DELETE' removes all filters, showing all
|
||||
below). `BACKSPACE' or `DELETE' removes all filters, showing all
|
||||
transactions.
|
||||
|
||||
As mentioned above, by default hledger-ui hides future transactions -
|
||||
both ordinary transactions recorded in the journal, and periodic
|
||||
transactions generated by rule. 'F' toggles forecast mode, in which
|
||||
transactions generated by rule. `F' toggles forecast mode, in which
|
||||
future/forecasted transactions are shown.
|
||||
|
||||
'ESCAPE' resets the UI state and jumps back to the top screen,
|
||||
restoring the app's initial state at startup. Or, it cancels minibuffer
|
||||
`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 entry or the help dialog.
|
||||
|
||||
'CTRL-l' redraws the screen and centers the selection if possible
|
||||
`CTRL-l' redraws the screen and centers the selection if possible
|
||||
(selections near the top won't be centered, since we don't scroll above
|
||||
the top).
|
||||
|
||||
'g' reloads from the data file(s) and updates the current screen and
|
||||
any previous screens. (With large files, this could cause a noticeable
|
||||
`g' reloads from the data file(s) and updates the current screen and
|
||||
any previous screens. (With large files, this could cause a noticeable
|
||||
pause.)
|
||||
|
||||
'I' toggles balance assertion checking. Disabling balance assertions
|
||||
`I' toggles balance assertion checking. Disabling balance assertions
|
||||
temporarily can be useful for troubleshooting.
|
||||
|
||||
'a' runs command-line hledger's add command, and reloads the updated
|
||||
file. This allows some basic data entry.
|
||||
`a' runs command-line hledger's add command, and reloads the updated
|
||||
file. This allows some basic data entry.
|
||||
|
||||
'A' is like 'a', but runs the hledger-iadd tool, which provides a
|
||||
terminal interface. This key will be available if 'hledger-iadd' is
|
||||
`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 $path.
|
||||
|
||||
'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient
|
||||
-a "" -nw') on the journal file. With some editors (emacs, vi), the
|
||||
`E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (`emacsclient
|
||||
-a "" -nw') on the journal file. With some editors (emacs, vi), the
|
||||
cursor will be positioned at the current transaction when invoked from
|
||||
the register and transaction screens, and at the error location (if
|
||||
possible) when invoked from the error screen.
|
||||
|
||||
'B' toggles cost mode, showing amounts in their transaction price's
|
||||
commodity (like toggling the '-B/--cost' flag).
|
||||
`B' toggles cost mode, showing amounts in their transaction price's
|
||||
commodity (like toggling the `-B/--cost' flag).
|
||||
|
||||
'V' toggles value mode, showing amounts' current market value in
|
||||
their default valuation commodity (like toggling the '-V/--market'
|
||||
flag). 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 temporarily set that as the report end date. Eg: to see a
|
||||
`V' toggles value mode, showing amounts' current market value in
|
||||
their default valuation commodity (like toggling the `-V/--market'
|
||||
flag). 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 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, press '/', and add 'date:-7/30' to the query.
|
||||
screen, press `/', and add `date:-7/30' to the query.
|
||||
|
||||
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; for now pressing 'b' 'b' 'v' should reliably reset to normal
|
||||
active; for now pressing `b' `b' `v' should reliably reset to normal
|
||||
mode.
|
||||
|
||||
'q' quits the application.
|
||||
`q' quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
@ -365,50 +364,49 @@ File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCRE
|
||||
4.1 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). Accounts which have been declared with an account
|
||||
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). Accounts which have been declared with an account
|
||||
directive are also listed, even if not yet used (except for empty parent
|
||||
accounts). If you specify a query on the command line, it shows just
|
||||
the matched accounts and the balances from matched transactions.
|
||||
accounts). 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
|
||||
Account names are shown as a flat list by default; press `t' to
|
||||
toggle tree mode. In list mode, account balances are exclusive of
|
||||
subaccounts, except where subaccounts are hidden by a depth limit (see
|
||||
below). In tree mode, all account balances are inclusive of
|
||||
subaccounts.
|
||||
below). In tree mode, all account balances are inclusive of subaccounts.
|
||||
|
||||
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 'ESCAPE'.
|
||||
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 `ESCAPE'.
|
||||
|
||||
'H' toggles between showing historical balances or period balances.
|
||||
`H' toggles between showing historical balances or period balances.
|
||||
Historical 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.
|
||||
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
|
||||
`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 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
|
||||
`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' to view an account's transactions register.
|
||||
Press `RIGHT' to view an account's transactions register.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS
|
||||
@ -417,44 +415,46 @@ File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev:
|
||||
===================
|
||||
|
||||
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:
|
||||
|
||||
* 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.)
|
||||
* 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.)
|
||||
|
||||
* the overall change to the current account's balance; positive for
|
||||
an inflow to this account, negative for an outflow.
|
||||
|
||||
* 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 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 see on a bank register for the current account.
|
||||
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 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 see on a bank register for the
|
||||
current account.
|
||||
|
||||
|
||||
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 transactions
|
||||
contributing to the balance shown on the accounts screen. Tree
|
||||
mode/list mode can be toggled with 't' here also.
|
||||
limit. In other words, the register always shows the transactions
|
||||
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
|
||||
transactions. Similarly, 'P' toggles pending transactions, and 'C'
|
||||
toggles cleared transactions. (By default, transactions with all
|
||||
`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 transactions 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
|
||||
`z' toggles nonzero mode, in which only transactions posting a
|
||||
nonzero change are shown (hledger-ui shows zero items by default, unlike
|
||||
command-line hledger).
|
||||
|
||||
Press 'RIGHT' to view the selected transaction in detail.
|
||||
Press `RIGHT' to view the selected transaction in detail.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS
|
||||
@ -471,11 +471,11 @@ 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
|
||||
`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
|
||||
transactions appear in multiple account registers). The #N number
|
||||
transactions appear in multiple account registers). The #N number
|
||||
preceding them is the transaction's position within the complete
|
||||
unfiltered journal, which is a more stable id (at least until the next
|
||||
reload).
|
||||
@ -487,8 +487,8 @@ File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCRE
|
||||
================
|
||||
|
||||
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
|
||||
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.)
|
||||
|
||||
|
||||
@ -508,20 +508,21 @@ File: hledger-ui.info, Node: Watch mode, Next: Watch mode limitations, Up: TI
|
||||
5.1 Watch mode
|
||||
==============
|
||||
|
||||
One of hledger-ui's best features is the auto-reloading '-w/--watch'
|
||||
mode. With this flag, it will update the display automatically whenever
|
||||
One of hledger-ui's best features is the auto-reloading `-w/--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
|
||||
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
|
||||
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.
|
||||
|
||||
@ -532,28 +533,29 @@ File: hledger-ui.info, Node: Watch mode limitations, Prev: Watch mode, Up: TI
|
||||
==========================
|
||||
|
||||
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:
|
||||
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
|
||||
* 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
|
||||
* 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
|
||||
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
|
||||
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.
|
||||
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.
|
||||
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
|
||||
@ -561,27 +563,28 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
|
||||
6 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: '~/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
*LEDGER_FILE* The journal file path when not specified with `-f'.
|
||||
Default: `~/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
|
||||
A typical value is '~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
'~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
A typical value is `~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
`~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
YYYY.journal.
|
||||
|
||||
On Mac computers, you can set this and other environment variables in
|
||||
a more thorough way that also affects applications started from the GUI
|
||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
'~/.MacOSX/environment.plist' file containing
|
||||
On Mac computers, you can set this and other environment variables
|
||||
in a more thorough way that also affects applications started from the
|
||||
GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
`~/.MacOSX/environment.plist' file containing
|
||||
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
To see the effect you may need to 'killall Dock', or reboot.
|
||||
To see the effect you may need to `killall Dock', or reboot.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
@ -590,9 +593,9 @@ File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
*******
|
||||
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or
|
||||
'$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
|
||||
`$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -600,18 +603,18 @@ File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
8 BUGS
|
||||
******
|
||||
|
||||
The need to precede options with '--' when invoked from hledger is
|
||||
The need to precede options with `--' when invoked from hledger is
|
||||
awkward.
|
||||
|
||||
'-f-' doesn't work (hledger-ui can't read from stdin).
|
||||
`-f-' doesn't work (hledger-ui can't read from stdin).
|
||||
|
||||
'-V' affects only the accounts screen.
|
||||
`-V' affects only the accounts screen.
|
||||
|
||||
When you press 'g', the current and all previous screens are
|
||||
regenerated, which may cause a noticeable pause with large files. Also
|
||||
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 visual indication that this is in progress.
|
||||
|
||||
'--watch' is not yet fully robust. It works well for normal usage,
|
||||
`--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
|
||||
times with an editor macro) can cause problems at least on OSX. Symptoms
|
||||
include: unresponsive UI, periodic resetting of the cursor position,
|
||||
@ -620,43 +623,39 @@ and possibly a small but persistent build-up of CPU usage until the
|
||||
program is restarted.
|
||||
|
||||
Also, if you are viewing files mounted from another machine,
|
||||
'-w/--watch' requires that both machine clocks are roughly in step.
|
||||
`-w/--watch' requires that both machine clocks are roughly in step.
|
||||
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top221
|
||||
Node: OPTIONS1657
|
||||
Ref: #options1755
|
||||
Node: MOUSE6637
|
||||
Ref: #mouse6732
|
||||
Node: KEYS7014
|
||||
Ref: #keys7107
|
||||
Node: SCREENS11193
|
||||
Ref: #screens11291
|
||||
Node: Accounts screen11381
|
||||
Ref: #accounts-screen11509
|
||||
Node: Register screen13848
|
||||
Ref: #register-screen14003
|
||||
Node: Transaction screen15987
|
||||
Ref: #transaction-screen16145
|
||||
Node: Error screen17015
|
||||
Ref: #error-screen17137
|
||||
Node: TIPS17381
|
||||
Ref: #tips17480
|
||||
Node: Watch mode17532
|
||||
Ref: #watch-mode17649
|
||||
Node: Watch mode limitations18399
|
||||
Ref: #watch-mode-limitations18540
|
||||
Node: ENVIRONMENT19676
|
||||
Ref: #environment19787
|
||||
Node: FILES20594
|
||||
Ref: #files20693
|
||||
Node: BUGS20906
|
||||
Ref: #bugs20983
|
||||
Node: Top232
|
||||
Node: OPTIONS1647
|
||||
Ref: #options1745
|
||||
Node: MOUSE6620
|
||||
Ref: #mouse6715
|
||||
Node: KEYS6999
|
||||
Ref: #keys7092
|
||||
Node: SCREENS11156
|
||||
Ref: #screens11254
|
||||
Node: Accounts screen11344
|
||||
Ref: #accounts-screen11472
|
||||
Node: Register screen13799
|
||||
Ref: #register-screen13954
|
||||
Node: Transaction screen15936
|
||||
Ref: #transaction-screen16094
|
||||
Node: Error screen16961
|
||||
Ref: #error-screen17083
|
||||
Node: TIPS17325
|
||||
Ref: #tips17424
|
||||
Node: Watch mode17476
|
||||
Ref: #watch-mode17593
|
||||
Node: Watch mode limitations18340
|
||||
Ref: #watch-mode-limitations18481
|
||||
Node: ENVIRONMENT19614
|
||||
Ref: #environment19725
|
||||
Node: FILES20530
|
||||
Ref: #files20629
|
||||
Node: BUGS20842
|
||||
Ref: #bugs20919
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
Local Variables:
|
||||
coding: utf-8
|
||||
End:
|
||||
|
||||
@ -533,4 +533,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-ui-1.23.99 November 2021 HLEDGER-UI(1)
|
||||
hledger-ui-1.23.99 December 2021 HLEDGER-UI(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{November 2021}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{December 2021}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-WEB" "1" "November 2021" "hledger-web-1.23.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-WEB" "1" "December 2021" "hledger-web-1.23.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,4 +1,5 @@
|
||||
This is hledger-web.info, produced by makeinfo version 6.8 from stdin.
|
||||
This is hledger-web/hledger-web.info, produced by makeinfo version 4.8
|
||||
from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
@ -6,7 +7,7 @@ START-INFO-DIR-ENTRY
|
||||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
|
||||
File: hledger-web.info, Node: Top, Up: (dir)
|
||||
|
||||
hledger-web(1)
|
||||
**************
|
||||
@ -14,32 +15,31 @@ hledger-web(1)
|
||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||
This manual is for hledger-web 1.23.99.
|
||||
|
||||
'hledger-web [OPTIONS]'
|
||||
'hledger web -- [OPTIONS]'
|
||||
`hledger-web [OPTIONS]'
|
||||
`hledger web -- [OPTIONS]'
|
||||
|
||||
hledger is a reliable, cross-platform set of programs for tracking
|
||||
money, time, or any other commodity, using double-entry accounting and a
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
compatible with ledger(1).
|
||||
|
||||
hledger-web is hledger's web interface. It starts a simple web
|
||||
hledger-web is hledger's web interface. It starts a simple web
|
||||
application for browsing and adding transactions, and optionally opens
|
||||
it in a web browser window if possible. It provides a more
|
||||
user-friendly UI than the hledger CLI or hledger-ui interface, showing
|
||||
more at once (accounts, the current account register, balance charts)
|
||||
and allowing history-aware data entry, interactive searching, and
|
||||
bookmarking.
|
||||
it in a web browser window if possible. It provides a more user-friendly
|
||||
UI than the hledger CLI or hledger-ui interface, showing more at once
|
||||
(accounts, the current account register, balance charts) and allowing
|
||||
history-aware data entry, interactive searching, and bookmarking.
|
||||
|
||||
hledger-web also lets you share a ledger with multiple users, or even
|
||||
the public web. There is no access control, so if you need that you
|
||||
should put it behind a suitable web proxy. As a small protection
|
||||
against data loss when running an unprotected instance, it writes a
|
||||
numbered backup of the main journal file (only ?) on every edit.
|
||||
the public web. There is no access control, so if you need that you
|
||||
should put it behind a suitable web proxy. As a small protection against
|
||||
data loss when running an unprotected instance, it writes a numbered
|
||||
backup of the main journal file (only ?) on every edit.
|
||||
|
||||
Like hledger, it reads data from one or more files in hledger
|
||||
journal, timeclock, timedot, or CSV format specified with '-f', or
|
||||
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1).
|
||||
journal, timeclock, timedot, or CSV format specified with `-f', or
|
||||
`$LEDGER_FILE', or `$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal'). For more about this see hledger(1).
|
||||
|
||||
* Menu:
|
||||
|
||||
@ -59,180 +59,177 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
|
||||
*********
|
||||
|
||||
Command-line options and arguments may be used to set an initial filter
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
will be applied in addition to any search query entered there.
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write '--'
|
||||
Note: if invoking hledger-web as a hledger subcommand, write `--'
|
||||
before options, as shown in the synopsis above.
|
||||
|
||||
'--serve'
|
||||
|
||||
`--serve'
|
||||
serve and log requests, don't browse or auto-exit
|
||||
'--serve-api'
|
||||
|
||||
`--serve-api'
|
||||
like -serve, but serve only the JSON web API, without the
|
||||
server-side web UI
|
||||
'--host=IPADDR'
|
||||
|
||||
`--host=IPADDR'
|
||||
listen on this IP address (default: 127.0.0.1)
|
||||
'--port=PORT'
|
||||
|
||||
`--port=PORT'
|
||||
listen on this TCP port (default: 5000)
|
||||
'--socket=SOCKETFILE'
|
||||
|
||||
`--socket=SOCKETFILE'
|
||||
use a unix domain socket file to listen for requests instead of a
|
||||
TCP socket. Implies '--serve'. It can only be used if the
|
||||
operating system can provide this type of socket.
|
||||
'--base-url=URL'
|
||||
TCP socket. Implies `--serve'. It can only be used if the operating
|
||||
system can provide this type of socket.
|
||||
|
||||
`--base-url=URL'
|
||||
set the base url (default: http://IPADDR:PORT). You would change
|
||||
this when sharing over the network, or integrating within a larger
|
||||
website.
|
||||
'--file-url=URL'
|
||||
|
||||
set the static files url (default: BASEURL/static). hledger-web
|
||||
`--file-url=URL'
|
||||
set the static files url (default: BASEURL/static). hledger-web
|
||||
normally serves static files itself, but if you wanted to serve
|
||||
them from another server for efficiency, you would set the url with
|
||||
this.
|
||||
'--capabilities=CAP[,CAP..]'
|
||||
them from another server for efficiency, you would set the url
|
||||
with this.
|
||||
|
||||
`--capabilities=CAP[,CAP..]'
|
||||
enable the view, add, and/or manage capabilities (default:
|
||||
view,add)
|
||||
'--capabilities-header=HTTPHEADER'
|
||||
|
||||
`--capabilities-header=HTTPHEADER'
|
||||
read capabilities to enable from a HTTP header, like
|
||||
X-Sandstorm-Permissions (default: disabled)
|
||||
'--test'
|
||||
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
`--test'
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
follow a -, eg: hledger-web -test - -help
|
||||
|
||||
hledger input options:
|
||||
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
`-f FILE --file=FILE'
|
||||
use a different input file. For stdin, use - (default:
|
||||
`$LEDGER_FILE' or `$HOME/.hledger.journal')
|
||||
|
||||
`--rules-file=RULESFILE'
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
'--separator=CHAR'
|
||||
|
||||
`--separator=CHAR'
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
`--alias=OLD=NEW'
|
||||
rename accounts named OLD to NEW
|
||||
'--anon'
|
||||
|
||||
`--anon'
|
||||
anonymize accounts and payees
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
`--pivot FIELDNAME'
|
||||
use some other field or tag for the account name
|
||||
'-I --ignore-assertions'
|
||||
|
||||
`-I --ignore-assertions'
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
'-s --strict'
|
||||
|
||||
`-s --strict'
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
'-b --begin=DATE'
|
||||
|
||||
`-b --begin=DATE'
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
'-e --end=DATE'
|
||||
|
||||
`-e --end=DATE'
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
'-D --daily'
|
||||
|
||||
`-D --daily'
|
||||
multiperiod/multicolumn report by day
|
||||
'-W --weekly'
|
||||
|
||||
`-W --weekly'
|
||||
multiperiod/multicolumn report by week
|
||||
'-M --monthly'
|
||||
|
||||
`-M --monthly'
|
||||
multiperiod/multicolumn report by month
|
||||
'-Q --quarterly'
|
||||
|
||||
`-Q --quarterly'
|
||||
multiperiod/multicolumn report by quarter
|
||||
'-Y --yearly'
|
||||
|
||||
`-Y --yearly'
|
||||
multiperiod/multicolumn report by year
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
`-p --period=PERIODEXP'
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
'--date2'
|
||||
|
||||
`--date2'
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
'--today=DATE'
|
||||
|
||||
`--today=DATE'
|
||||
override today's date (affects relative smart dates, for
|
||||
tests/examples)
|
||||
'-U --unmarked'
|
||||
|
||||
`-U --unmarked'
|
||||
include only unmarked postings/txns (can combine with -P or -C)
|
||||
'-P --pending'
|
||||
|
||||
`-P --pending'
|
||||
include only pending postings/txns
|
||||
'-C --cleared'
|
||||
|
||||
`-C --cleared'
|
||||
include only cleared postings/txns
|
||||
'-R --real'
|
||||
|
||||
`-R --real'
|
||||
include only non-virtual postings
|
||||
'-NUM --depth=NUM'
|
||||
|
||||
`-NUM --depth=NUM'
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
'-E --empty'
|
||||
|
||||
`-E --empty'
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
'-B --cost'
|
||||
|
||||
`-B --cost'
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
'-V --market'
|
||||
|
||||
`-V --market'
|
||||
convert amounts to their market value in default valuation
|
||||
commodities
|
||||
'-X --exchange=COMM'
|
||||
|
||||
`-X --exchange=COMM'
|
||||
convert amounts to their market value in commodity COMM
|
||||
'--value'
|
||||
|
||||
`--value'
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
'--infer-market-prices'
|
||||
|
||||
`--infer-market-prices'
|
||||
use transaction prices (recorded with @ or @@) as additional market
|
||||
prices, as if they were P directives
|
||||
'--auto'
|
||||
|
||||
`--auto'
|
||||
apply automated posting rules to modify transactions.
|
||||
'--forecast'
|
||||
|
||||
`--forecast'
|
||||
generate future transactions from periodic transaction rules, for
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
make ordinary future transactions visible.
|
||||
'--commodity-style'
|
||||
|
||||
`--commodity-style'
|
||||
Override the commodity style in the output for the specified
|
||||
commodity. For example 'EUR1.000,00'.
|
||||
'--color=WHEN (or --colour=WHEN)'
|
||||
|
||||
`--color=WHEN (or --colour=WHEN)'
|
||||
Should color-supporting commands use ANSI color codes in text
|
||||
output. 'auto' (default): whenever stdout seems to be a
|
||||
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.
|
||||
'--pretty[=WHEN]'
|
||||
|
||||
Show prettier output, e.g. using unicode box-drawing characters.
|
||||
`--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'.
|
||||
@ -244,62 +241,62 @@ the last one takes precedence.
|
||||
|
||||
hledger help options:
|
||||
|
||||
'-h --help'
|
||||
|
||||
`-h --help'
|
||||
show general or COMMAND help
|
||||
'--man'
|
||||
|
||||
`--man'
|
||||
show general or COMMAND user manual with man
|
||||
'--info'
|
||||
|
||||
`--info'
|
||||
show general or COMMAND user manual with info
|
||||
'--version'
|
||||
|
||||
`--version'
|
||||
show general or ADDONCMD version
|
||||
'--debug[=N]'
|
||||
|
||||
`--debug[=N]'
|
||||
show debug output (levels 1-9, default: 1)
|
||||
|
||||
A @FILE argument will be expanded to the contents of FILE, which
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a '--' argument before.)
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a `--' argument before.)
|
||||
|
||||
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
|
||||
also 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
|
||||
window, and will exit after two minutes of inactivity (no requests and
|
||||
no browser windows viewing it). With '--serve', it just runs the web
|
||||
app without exiting, and logs requests to the console. With
|
||||
'--serve-api', only the JSON web api (see below) is served, with the
|
||||
no browser windows viewing it). With `--serve', it just runs the web
|
||||
app without exiting, and logs requests to the console. With
|
||||
`--serve-api', only the JSON web api (see below) is served, with the
|
||||
usual HTML server-side web UI disabled.
|
||||
|
||||
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
|
||||
only to local requests. You can use `--host' to change this, eg `--host
|
||||
0.0.0.0' to listen on all configured addresses.
|
||||
|
||||
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
||||
Similarly, use `--port' to set a TCP port other than 5000, eg if you
|
||||
are running multiple hledger-web instances.
|
||||
|
||||
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 for communication. This is an alternative way of running multiple
|
||||
hledger-web instances behind a reverse proxy that handles authentication
|
||||
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
|
||||
reverse proxy can use the variable '$remote_user' to derive a path from
|
||||
the username used in a HTTP basic authentication. The following
|
||||
'proxy_pass' directive allows access to all 'hledger-web' instances that
|
||||
created a socket in '/tmp/hledger/':
|
||||
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 for communication. This is an alternative way of running multiple
|
||||
hledger-web instances behind a reverse proxy that handles
|
||||
authentication 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 reverse proxy can use the variable `$remote_user'
|
||||
to derive a path from the username used in a HTTP basic authentication.
|
||||
The following `proxy_pass' directive allows access to all `hledger-web'
|
||||
instances that created a socket in `/tmp/hledger/':
|
||||
|
||||
|
||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||
|
||||
You can use '--base-url' to change the protocol, hostname, port and
|
||||
You can use `--base-url' to change the protocol, hostname, port and
|
||||
path that appear in hyperlinks, useful eg for integrating hledger-web
|
||||
within a larger website. The default is 'http://HOST:PORT/' using the
|
||||
server's configured host address and TCP port (or 'http://HOST' if PORT
|
||||
within 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).
|
||||
|
||||
With '--file-url' you can set a different base url for static files,
|
||||
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.
|
||||
|
||||
@ -314,28 +311,32 @@ journal and to add new transactions, but not to change existing data.
|
||||
|
||||
You can restrict who can reach it by
|
||||
|
||||
* setting the IP address it listens on (see '--host' above). By
|
||||
* 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 machine.
|
||||
|
||||
* putting it behind an authenticating proxy, using eg apache or nginx
|
||||
|
||||
* custom firewall rules
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
|
||||
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is 'view,add':
|
||||
* 'view' - allows viewing the journal file and all included
|
||||
* using the `--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is `view,add':
|
||||
* `view' - allows viewing the journal file and all included
|
||||
files
|
||||
* 'add' - allows adding new transactions to the main journal
|
||||
|
||||
* `add' - allows adding new transactions to the main journal
|
||||
file
|
||||
* 'manage' - allows editing, uploading or downloading the main
|
||||
|
||||
* `manage' - allows editing, uploading or downloading the main
|
||||
or included files
|
||||
|
||||
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
* using the `--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
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.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
|
||||
@ -343,8 +344,8 @@ File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING,
|
||||
3 EDITING, UPLOADING, DOWNLOADING
|
||||
*********************************
|
||||
|
||||
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
|
||||
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
|
||||
let you edit, upload, or download the journal file or any files it
|
||||
includes.
|
||||
|
||||
@ -353,13 +354,13 @@ visitor) can alter or wipe the data files.
|
||||
|
||||
Normally whenever a file is changed in this way, hledger-web saves a
|
||||
numbered backup (assuming file permissions allow it, the disk is not
|
||||
full, etc.) hledger-web is not aware of version control systems,
|
||||
full, etc.) hledger-web is not aware of version control systems,
|
||||
currently; 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).
|
||||
|
||||
Changes which would leave the journal file(s) unparseable or
|
||||
non-valid (eg with failing balance assertions) are prevented.
|
||||
(Probably. This needs re-testing.)
|
||||
(Probably. This needs re-testing.)
|
||||
|
||||
|
||||
File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOADING DOWNLOADING, Up: Top
|
||||
@ -369,7 +370,7 @@ File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOAD
|
||||
|
||||
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 data
|
||||
when you reload the page or navigate to a new page. If a change makes a
|
||||
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 until the
|
||||
file has been fixed.
|
||||
|
||||
@ -383,14 +384,16 @@ File: hledger-web.info, Node: JSON API, Next: ENVIRONMENT, Prev: RELOADING,
|
||||
**********
|
||||
|
||||
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
|
||||
only, you can use the '--serve-api' flag. Eg:
|
||||
be used to get data or add new transactions. If you want the JSON API
|
||||
only, you can use the `--serve-api' flag. Eg:
|
||||
|
||||
|
||||
$ hledger-web -f examples/sample.journal --serve-api
|
||||
...
|
||||
|
||||
You can get JSON data from these routes:
|
||||
|
||||
|
||||
/version
|
||||
/accountnames
|
||||
/transactions
|
||||
@ -403,6 +406,7 @@ $ hledger-web -f examples/sample.journal --serve-api
|
||||
command). (hledger-web's JSON does not include newlines, here we use
|
||||
python to prettify it):
|
||||
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||
[
|
||||
"assets",
|
||||
@ -422,6 +426,7 @@ $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||
|
||||
Or all transactions:
|
||||
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
[
|
||||
{
|
||||
@ -443,24 +448,25 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
at the source for the appropriate handler to see what it returns. Eg
|
||||
for '/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"'accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
To 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 for `/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"`accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
can see that /accounttransactions returns an AccountTransactionsReport,
|
||||
which consists of a report title and a list of
|
||||
AccountTransactionsReportItem (etc).
|
||||
|
||||
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
|
||||
default). The payload must be the full, exact JSON representation of a
|
||||
hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's '/transactions' or '/accounttransactions', or you can
|
||||
export it with hledger-lib, eg like so:
|
||||
`/add', if hledger-web was started with the `add' capability (enabled
|
||||
by default). The payload must be the full, exact JSON representation of
|
||||
a hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's `/transactions' or `/accounttransactions', or you
|
||||
can export it with hledger-lib, eg like so:
|
||||
|
||||
|
||||
.../hledger$ stack ghci hledger-lib
|
||||
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
|
||||
@ -469,6 +475,7 @@ export it with hledger-lib, eg like so:
|
||||
Here's how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger's Transaction and related data types):
|
||||
|
||||
|
||||
{
|
||||
"tcomment": "",
|
||||
"tpostings": [
|
||||
@ -555,9 +562,10 @@ corresponds to hledger's Transaction and related data types):
|
||||
"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:
|
||||
|
||||
|
||||
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
|
||||
|
||||
|
||||
@ -566,25 +574,26 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up:
|
||||
6 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
Default: '~/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
*LEDGER_FILE* The journal file path when not specified with `-f'.
|
||||
Default: `~/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
|
||||
A typical value is '~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
'~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
A typical value is `~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
`~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
YYYY.journal.
|
||||
|
||||
On Mac computers, you can set this and other environment variables in
|
||||
a more thorough way that also affects applications started from the GUI
|
||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
'~/.MacOSX/environment.plist' file containing
|
||||
On Mac computers, you can set this and other environment variables
|
||||
in a more thorough way that also affects applications started from the
|
||||
GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
`~/.MacOSX/environment.plist' file containing
|
||||
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
To see the effect you may need to 'killall Dock', or reboot.
|
||||
To see the effect you may need to `killall Dock', or reboot.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
@ -593,9 +602,9 @@ File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
*******
|
||||
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or
|
||||
'$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
|
||||
`$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
|
||||
|
||||
File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -603,10 +612,10 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
8 BUGS
|
||||
******
|
||||
|
||||
The need to precede options with '--' when invoked from hledger is
|
||||
The need to precede options with `--' when invoked from hledger is
|
||||
awkward.
|
||||
|
||||
'-f-' doesn't work (hledger-web can't read from stdin).
|
||||
`-f-' doesn't work (hledger-web can't read from stdin).
|
||||
|
||||
Query arguments and some hledger options are ignored.
|
||||
|
||||
@ -614,29 +623,25 @@ awkward.
|
||||
|
||||
Does not work well on small screens.
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top223
|
||||
Node: OPTIONS1889
|
||||
Ref: #options1994
|
||||
Node: PERMISSIONS9905
|
||||
Ref: #permissions10044
|
||||
Node: EDITING UPLOADING DOWNLOADING11256
|
||||
Ref: #editing-uploading-downloading11437
|
||||
Node: RELOADING12271
|
||||
Ref: #reloading12405
|
||||
Node: JSON API12838
|
||||
Ref: #json-api12952
|
||||
Node: ENVIRONMENT18442
|
||||
Ref: #environment18558
|
||||
Node: FILES19291
|
||||
Ref: #files19391
|
||||
Node: BUGS19604
|
||||
Ref: #bugs19682
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
Local Variables:
|
||||
coding: utf-8
|
||||
End:
|
||||
Tag Table:
|
||||
Node: Top235
|
||||
Node: OPTIONS1878
|
||||
Ref: #options1983
|
||||
Node: PERMISSIONS9873
|
||||
Ref: #permissions10012
|
||||
Node: EDITING UPLOADING DOWNLOADING11224
|
||||
Ref: #editing-uploading-downloading11405
|
||||
Node: RELOADING12236
|
||||
Ref: #reloading12370
|
||||
Node: JSON API12802
|
||||
Ref: #json-api12916
|
||||
Node: ENVIRONMENT18405
|
||||
Ref: #environment18521
|
||||
Node: FILES19253
|
||||
Ref: #files19353
|
||||
Node: BUGS19566
|
||||
Ref: #bugs19644
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -570,4 +570,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-web-1.23.99 November 2021 HLEDGER-WEB(1)
|
||||
hledger-web-1.23.99 December 2021 HLEDGER-WEB(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{November 2021}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{December 2021}})m4_dnl
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
.\"t
|
||||
|
||||
.TH "HLEDGER" "1" "November 2021" "hledger-1.23.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER" "1" "December 2021" "hledger-1.23.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
5357
hledger/hledger.info
5357
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
@ -7522,4 +7522,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-1.23.99 November 2021 HLEDGER(1)
|
||||
hledger-1.23.99 December 2021 HLEDGER(1)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user