mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-19 10:17:35 +03:00
;doc: update manuals
This commit is contained in:
parent
dbb1441402
commit
fc8fe8ee46
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{December 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{January 2023}})m4_dnl
|
||||
|
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{December 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{January 2023}})m4_dnl
|
||||
|
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-UI" "1" "December 2022" "hledger-ui-1.28.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-UI" "1" "January 2023" "hledger-ui-1.28.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
@ -18,10 +18,11 @@ hledger-ui - robust, friendly plain text accounting (TUI version)
|
||||
This manual is for hledger\[aq]s terminal interface, version 1.28.99.
|
||||
See also the hledger manual for common concepts and file formats.
|
||||
.PP
|
||||
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 compatible with ledger(1).
|
||||
hledger is a robust, user-friendly, 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 compatible with ledger(1), and
|
||||
largely interconvertible with beancount(1).
|
||||
.PP
|
||||
hledger-ui is hledger\[aq]s terminal interface, providing an efficient
|
||||
full-window text UI for viewing accounts and transactions, and some
|
||||
@ -29,10 +30,11 @@ limited data entry capability.
|
||||
It is easier than hledger\[aq]s command-line interface, and sometimes
|
||||
quicker and more convenient than the web interface.
|
||||
.PP
|
||||
Like hledger, it reads data from one or more files in hledger journal,
|
||||
timeclock, timedot, or CSV format specified with \f[V]-f\f[R], or
|
||||
\f[V]$LEDGER_FILE\f[R], or \f[V]$HOME/.hledger.journal\f[R] (on windows,
|
||||
perhaps \f[V]C:/Users/USER/.hledger.journal\f[R]).
|
||||
Like hledger, it reads data from one or more files in journal,
|
||||
timeclock, timedot, or CSV format.
|
||||
The default file is \f[V].hledger.journal\f[R] in your home directory;
|
||||
this can be overridden with one or more \f[V]-f FILE\f[R] options, or
|
||||
the \f[V]LEDGER_FILE\f[R] environment variable.
|
||||
For more about this see hledger(1), hledger_journal(5) etc.
|
||||
.PP
|
||||
Unlike hledger, hledger-ui hides all future-dated transactions by
|
||||
@ -618,10 +620,11 @@ Or, change it in settings: see
|
||||
https://www.java.com/en/download/help/path.html.
|
||||
.SH FILES
|
||||
.PP
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
timedot, or CSV format specified with \f[V]-f\f[R], or
|
||||
\f[V]$LEDGER_FILE\f[R], or \f[V]$HOME/.hledger.journal\f[R] (on windows,
|
||||
perhaps \f[V]C:/Users/USER/.hledger.journal\f[R]).
|
||||
Reads data from one or more files in journal, timeclock, timedot, or CSV
|
||||
format.
|
||||
The default file is \f[V].hledger.journal\f[R] in your home directory;
|
||||
this can be overridden with one or more \f[V]-f FILE\f[R] options, or
|
||||
the \f[V]LEDGER_FILE\f[R] environment variable.
|
||||
.SH BUGS
|
||||
.PP
|
||||
\f[V]-f-\f[R] doesn\[aq]t work (hledger-ui can\[aq]t read from stdin).
|
||||
|
@ -1,4 +1,4 @@
|
||||
This is hledger-ui.info, produced by makeinfo version 6.8 from stdin.
|
||||
This is hledger-ui.info, produced by makeinfo version 7.0.1 from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
@ -13,32 +13,33 @@ hledger-ui(1)
|
||||
|
||||
hledger-ui - robust, friendly plain text accounting (TUI version)
|
||||
|
||||
'hledger-ui [OPTIONS] [QUERYARGS]'
|
||||
'hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||
‘hledger-ui [OPTIONS] [QUERYARGS]’
|
||||
‘hledger ui -- [OPTIONS] [QUERYARGS]’
|
||||
|
||||
This manual is for hledger's terminal interface, version 1.28.99.
|
||||
This manual is for hledger’s terminal interface, version 1.28.99.
|
||||
See also the hledger manual for common concepts and file formats.
|
||||
|
||||
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
|
||||
compatible with ledger(1).
|
||||
hledger is a robust, user-friendly, 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 compatible with ledger(1), and largely interconvertible with
|
||||
beancount(1).
|
||||
|
||||
hledger-ui is hledger's terminal interface, providing an efficient
|
||||
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),
|
||||
hledger_journal(5) etc.
|
||||
Like hledger, it reads data from one or more files in journal,
|
||||
timeclock, timedot, or CSV format. The default file is
|
||||
‘.hledger.journal’ in your home directory; this can be overridden with
|
||||
one or more ‘-f FILE’ options, or the ‘LEDGER_FILE’ environment
|
||||
variable. 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
|
||||
transactions, by pressing the F key (or starting with -forecast) to
|
||||
transactions, by pressing the F key (or starting with –forecast) to
|
||||
enable "forecast mode".
|
||||
|
||||
* Menu:
|
||||
@ -58,173 +59,173 @@ 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
|
||||
'--menu'
|
||||
‘--menu’
|
||||
|
||||
start in the menu screen
|
||||
'--all'
|
||||
‘--all’
|
||||
|
||||
start in the all accounts screen
|
||||
'--bs'
|
||||
‘--bs’
|
||||
|
||||
start in the balance sheet accounts screen
|
||||
'--is'
|
||||
‘--is’
|
||||
|
||||
start in the income statement accounts screen
|
||||
'--register=ACCTREGEX'
|
||||
‘--register=ACCTREGEX’
|
||||
|
||||
start in the (first) matched account's register screen
|
||||
'--change'
|
||||
start in the (first) matched account’s register screen
|
||||
‘--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'
|
||||
‘-f FILE --file=FILE’
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
‘$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'
|
||||
Field separator to expect when reading CSV (default: ’,’)
|
||||
‘--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
|
||||
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
|
||||
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)'
|
||||
commodity. For example ’EUR1.000,00’.
|
||||
‘--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
|
||||
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
|
||||
NO_COLOR environment variable overrides this.
|
||||
'--pretty[=WHEN]'
|
||||
‘--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'.
|
||||
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 last one takes precedence.
|
||||
@ -233,25 +234,25 @@ 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.)
|
||||
this, insert a ‘--’ argument before.)
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
||||
@ -262,9 +263,9 @@ File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
||||
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) to go back.
|
||||
• Use mouse wheel or trackpad to scroll up and down
|
||||
• Click on list items to go deeper
|
||||
• Click on the left margin (column 0) to go back.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: MOUSE, Up: Top
|
||||
@ -274,88 +275,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' or 'ENTER' goes deeper, 'LEFT'
|
||||
returns to the previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END'
|
||||
The cursor keys navigate: ‘RIGHT’ or ‘ENTER’ 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') and VI-style ('k','j','l','h')
|
||||
(‘CTRL-p’/‘CTRL-n’/‘CTRL-f’/‘CTRL-b’) and VI-style (‘k’,‘j’,‘l’,‘h’)
|
||||
movement keys are also supported. 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, the karabiner app is one way to do that.)
|
||||
(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
|
||||
‘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-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.
|
||||
non-standard period, you can use ‘/’ and a ‘date:’ query.
|
||||
|
||||
'/' lets you set a general filter query limiting the data shown,
|
||||
‘/’ 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
|
||||
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
|
||||
(selections near the top won't be centered, since we don't scroll above
|
||||
‘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
|
||||
‘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
|
||||
‘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 cost's commodity
|
||||
(like toggling the '-B/--cost' flag).
|
||||
‘B’ toggles cost mode, showing amounts in their cost’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'
|
||||
‘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
|
||||
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.
|
||||
|
||||
'q' quits the application.
|
||||
‘q’ quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
@ -369,14 +370,14 @@ hledger-ui shows several different screens, described below. It shows
|
||||
the "Balance sheet accounts" screen to start with, except in the
|
||||
following situations:
|
||||
|
||||
* If no asset/liability/equity accounts can be detected, or if an
|
||||
• If no asset/liability/equity accounts can be detected, or if an
|
||||
account query has been given on the command line, it starts in the
|
||||
"All accounts" screen.
|
||||
|
||||
* If a starting screen is specified with -menu/-all/-bs/-is/-register
|
||||
• If a starting screen is specified with –menu/–all/–bs/–is/–register
|
||||
on the command line, it starts in that screen.
|
||||
|
||||
From any screen you can press 'LEFT' or 'ESC' to navigate back to the
|
||||
From any screen you can press ‘LEFT’ or ‘ESC’ to navigate back to the
|
||||
top level "Menu" screen.
|
||||
|
||||
* Menu:
|
||||
@ -406,8 +407,8 @@ File: hledger-ui.info, Node: All accounts, Next: Balance sheet accounts, Prev
|
||||
|
||||
This screen shows all accounts (possibly filtered by a query), and their
|
||||
end balances on the date shown in the title bar (or their balance
|
||||
changes in the period shown in the title bar, toggleable with 'H'). It
|
||||
is like the 'hledger balance' command.
|
||||
changes in the period shown in the title bar, toggleable with ‘H’). It
|
||||
is like the ‘hledger balance’ command.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Balance sheet accounts, Next: Income statement accounts, Prev: All accounts, Up: SCREENS
|
||||
@ -417,7 +418,7 @@ File: hledger-ui.info, Node: Balance sheet accounts, Next: Income statement ac
|
||||
|
||||
This screen shows asset, liability and equity accounts, if these can be
|
||||
detected (see account types). It always shows end balances. It is like
|
||||
the 'hledger balancesheetequity' command.
|
||||
the ‘hledger balancesheetequity’ command.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Income statement accounts, Next: Register, Prev: Balance sheet accounts, Up: SCREENS
|
||||
@ -426,7 +427,7 @@ File: hledger-ui.info, Node: Income statement accounts, Next: Register, Prev:
|
||||
=============================
|
||||
|
||||
This screen shows revenue and expense accounts. It always shows balance
|
||||
changes. It is like the 'hledger incomestatement' command.
|
||||
changes. It is like the ‘hledger incomestatement’ command.
|
||||
|
||||
All of these accounts screens work in much the same way:
|
||||
|
||||
@ -434,26 +435,26 @@ changes. It is like the 'hledger incomestatement' command.
|
||||
as accounts which have been declared with an account directive (except
|
||||
for empty parent accounts).
|
||||
|
||||
If you specify a query on the command line or with '/' in the app,
|
||||
If you specify a query on the command line or with ‘/’ in the app,
|
||||
they show just the matched accounts, and the balances from matched
|
||||
transactions.
|
||||
|
||||
hledger-ui shows accounts with zero balances by default (unlike
|
||||
command-line hledger). To hide these, press 'z' to toggle nonzero mode.
|
||||
command-line hledger). To hide these, press ‘z’ to toggle nonzero mode.
|
||||
|
||||
Account names are shown as a flat list by default; press 't' to
|
||||
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.
|
||||
|
||||
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 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'.
|
||||
or press ‘ESCAPE’.
|
||||
|
||||
'H' toggles between showing historical balances or period balances
|
||||
‘H’ toggles between showing historical balances or period balances
|
||||
(on the "All accounts" screen). 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),
|
||||
@ -464,16 +465,16 @@ 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.
|
||||
|
||||
Press 'RIGHT' to view an account's register screen, Or, 'LEFT' to see
|
||||
Press ‘RIGHT’ to view an account’s register screen, Or, ‘LEFT’ to see
|
||||
the menu screen.
|
||||
|
||||
|
||||
@ -485,42 +486,42 @@ File: hledger-ui.info, Node: Register, Next: Transaction, Prev: Income statem
|
||||
This screen shows the transactions affecting a particular account, like
|
||||
a check register. Each line represents one transaction and shows:
|
||||
|
||||
* the other account(s) involved, in abbreviated form. (If there are
|
||||
• 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
|
||||
• 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'.
|
||||
• 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.
|
||||
|
||||
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
|
||||
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.
|
||||
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'
|
||||
‘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, Next: Error, Prev: Register, Up: SCREENS
|
||||
@ -529,20 +530,20 @@ File: hledger-ui.info, Node: Transaction, Next: Error, Prev: Register, Up: S
|
||||
===============
|
||||
|
||||
This screen shows a single transaction, as a general journal entry,
|
||||
similar to hledger's print command and journal format
|
||||
similar to hledger’s print command and journal format
|
||||
(hledger_journal(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 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
|
||||
‘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
|
||||
preceding them is the transaction's position within the complete
|
||||
preceding them is the transaction’s position within the complete
|
||||
unfiltered journal, which is a more stable id (at least until the next
|
||||
reload).
|
||||
|
||||
@ -574,12 +575,12 @@ File: hledger-ui.info, Node: Watch mode, Next: Debug output, Up: TIPS
|
||||
5.1 Watch mode
|
||||
==============
|
||||
|
||||
One of hledger-ui's best features is the auto-reloading '-w/--watch'
|
||||
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
|
||||
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:
|
||||
|
||||
@ -594,16 +595,16 @@ history.
|
||||
Here are some current limitations to be aware of:
|
||||
|
||||
Changes might not be detected with certain editors, possibly
|
||||
including Jetbrains IDEs, 'gedit', other Gnome applications; or on
|
||||
including Jetbrains IDEs, ‘gedit’, other Gnome applications; or on
|
||||
certain unusual filesystems. (#1617, #911). To work around, reload
|
||||
manually by pressing 'g' in the hledger-ui window. (Or see #1617 for
|
||||
manually by pressing ‘g’ in the hledger-ui window. (Or see #1617 for
|
||||
another workaround, and let us know if it works for you.)
|
||||
|
||||
CPU and memory usage can sometimes gradually increase, if 'hledger-ui
|
||||
--watch' is left running for days. (Possibly correlated with certain
|
||||
CPU and memory usage can sometimes gradually increase, if ‘hledger-ui
|
||||
--watch’ is left running for days. (Possibly correlated with certain
|
||||
platforms, many transactions, and/or large numbers of other files
|
||||
present). To work around, 'q'uit and restart it, or (where supported)
|
||||
suspend ('CTRL-z') and restart it ('fg').
|
||||
present). To work around, ‘q’uit and restart it, or (where supported)
|
||||
suspend (‘CTRL-z’) and restart it (‘fg’).
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS
|
||||
@ -611,8 +612,8 @@ File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS
|
||||
5.2 Debug output
|
||||
================
|
||||
|
||||
You can add '--debug[=N]' to the command line to log debug output. This
|
||||
will be logged to the file 'hledger-ui.log' in the current directory. N
|
||||
You can add ‘--debug[=N]’ to the command line to log debug output. This
|
||||
will be logged to the file ‘hledger-ui.log’ in the current directory. N
|
||||
ranges from 1 (least output, the default) to 9 (maximum output).
|
||||
|
||||
|
||||
@ -623,33 +624,33 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
|
||||
|
||||
*COLUMNS* The screen width to use. Default: the full terminal width.
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
*LEDGER_FILE* The journal file path when not specified with ‘-f’.
|
||||
|
||||
On unix computers, the default value is: '~/.hledger.journal'.
|
||||
On unix computers, the default value is: ‘~/.hledger.journal’.
|
||||
|
||||
A more typical value is something like '~/finance/YYYY.journal',
|
||||
where '~/finance' is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, '~/finance/current.journal', where
|
||||
A more typical value is something like ‘~/finance/YYYY.journal’,
|
||||
where ‘~/finance’ is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, ‘~/finance/current.journal’, where
|
||||
current.journal is a symbolic link to YYYY.journal.
|
||||
|
||||
The usual way to set this permanently is to add a command to one of
|
||||
your shell's startup files (eg '~/.profile'):
|
||||
your shell’s startup files (eg ‘~/.profile’):
|
||||
|
||||
export LEDGER_FILE=~/finance/current.journal`
|
||||
|
||||
On some Mac computers, there is a more thorough way to set
|
||||
environment variables, that will also affect applications started from
|
||||
the GUI (eg, Emacs started from a dock icon): In
|
||||
'~/.MacOSX/environment.plist', add an entry like:
|
||||
‘~/.MacOSX/environment.plist’, add an entry like:
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
For this to take effect you might need to 'killall Dock', or reboot.
|
||||
For this to take effect you might need to ‘killall Dock’, or reboot.
|
||||
|
||||
On Windows computers, the default value is probably
|
||||
'C:\Users\YOURNAME\.hledger.journal'. You can change this by running a
|
||||
‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a
|
||||
command like this in a powershell window (let us know if you need to be
|
||||
an Administrator, and if this persists across a reboot):
|
||||
|
||||
@ -664,10 +665,10 @@ File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
7 FILES
|
||||
*******
|
||||
|
||||
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').
|
||||
Reads data from one or more files in journal, timeclock, timedot, or CSV
|
||||
format. The default file is ‘.hledger.journal’ in your home directory;
|
||||
this can be overridden with one or more ‘-f FILE’ options, or the
|
||||
‘LEDGER_FILE’ environment variable.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -675,15 +676,15 @@ File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
8 BUGS
|
||||
******
|
||||
|
||||
'-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
|
||||
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,
|
||||
@ -692,45 +693,45 @@ 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: OPTIONS1745
|
||||
Ref: #options1843
|
||||
Node: MOUSE6927
|
||||
Ref: #mouse7022
|
||||
Node: KEYS7259
|
||||
Ref: #keys7352
|
||||
Node: SCREENS11414
|
||||
Ref: #screens11512
|
||||
Node: Menu12198
|
||||
Ref: #menu12290
|
||||
Node: All accounts12367
|
||||
Ref: #all-accounts12506
|
||||
Node: Balance sheet accounts12757
|
||||
Ref: #balance-sheet-accounts12937
|
||||
Node: Income statement accounts13125
|
||||
Ref: #income-statement-accounts13307
|
||||
Node: Register15727
|
||||
Ref: #register15864
|
||||
Node: Transaction17848
|
||||
Ref: #transaction17971
|
||||
Node: Error18841
|
||||
Ref: #error18935
|
||||
Node: TIPS19179
|
||||
Ref: #tips19278
|
||||
Node: Watch mode19320
|
||||
Ref: #watch-mode19427
|
||||
Node: Debug output20883
|
||||
Ref: #debug-output20994
|
||||
Node: ENVIRONMENT21206
|
||||
Ref: #environment21317
|
||||
Node: FILES22702
|
||||
Ref: #files22801
|
||||
Node: BUGS23014
|
||||
Ref: #bugs23091
|
||||
Node: Top223
|
||||
Node: OPTIONS1871
|
||||
Ref: #options1969
|
||||
Node: MOUSE7336
|
||||
Ref: #mouse7431
|
||||
Node: KEYS7674
|
||||
Ref: #keys7767
|
||||
Node: SCREENS12061
|
||||
Ref: #screens12159
|
||||
Node: Menu12867
|
||||
Ref: #menu12959
|
||||
Node: All accounts13036
|
||||
Ref: #all-accounts13175
|
||||
Node: Balance sheet accounts13434
|
||||
Ref: #balance-sheet-accounts13614
|
||||
Node: Income statement accounts13806
|
||||
Ref: #income-statement-accounts13988
|
||||
Node: Register16482
|
||||
Ref: #register16619
|
||||
Node: Transaction18647
|
||||
Ref: #transaction18770
|
||||
Node: Error19654
|
||||
Ref: #error19748
|
||||
Node: TIPS19992
|
||||
Ref: #tips20091
|
||||
Node: Watch mode20133
|
||||
Ref: #watch-mode20240
|
||||
Node: Debug output21728
|
||||
Ref: #debug-output21839
|
||||
Node: ENVIRONMENT22059
|
||||
Ref: #environment22170
|
||||
Node: FILES23593
|
||||
Ref: #files23692
|
||||
Node: BUGS23952
|
||||
Ref: #bugs24029
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
@ -14,33 +14,34 @@ DESCRIPTION
|
||||
This manual is for hledger's terminal interface, version 1.28.99. See
|
||||
also the hledger manual for common concepts and file formats.
|
||||
|
||||
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
|
||||
compatible with ledger(1).
|
||||
hledger is a robust, user-friendly, 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 compatible with ledger(1), and largely interconvertible
|
||||
with beancount(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 interface, and sometimes quicker and more convenient than the web
|
||||
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 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),
|
||||
hledger_journal(5) etc.
|
||||
Like hledger, it reads data from one or more files in journal, time-
|
||||
clock, timedot, or CSV format. The default file is .hledger.journal in
|
||||
your home directory; this can be overridden with one or more -f FILE
|
||||
options, or the LEDGER_FILE environment variable. 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
|
||||
transactions, by pressing the F key (or starting with --forecast) to
|
||||
Unlike hledger, hledger-ui hides all future-dated transactions by
|
||||
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".
|
||||
|
||||
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
|
||||
Any QUERYARGS are interpreted as a hledger search query which filters
|
||||
the data.
|
||||
|
||||
-w --watch
|
||||
@ -61,7 +62,7 @@ OPTIONS
|
||||
start in the (first) matched account's register screen
|
||||
|
||||
--change
|
||||
show period balances (changes) at startup instead of historical
|
||||
show period balances (changes) at startup instead of historical
|
||||
balances
|
||||
|
||||
-l --flat
|
||||
@ -77,7 +78,7 @@ OPTIONS
|
||||
$LEDGER_FILE or $HOME/.hledger.journal)
|
||||
|
||||
--rules-file=RULESFILE
|
||||
Conversion rules file to use when reading CSV (default:
|
||||
Conversion rules file to use when reading CSV (default:
|
||||
FILE.rules)
|
||||
|
||||
--separator=CHAR
|
||||
@ -96,7 +97,7 @@ OPTIONS
|
||||
assignments)
|
||||
|
||||
-s --strict
|
||||
do extra error checking (check that all posted accounts are
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
@ -125,15 +126,15 @@ OPTIONS
|
||||
multiperiod/multicolumn report by year
|
||||
|
||||
-p --period=PERIODEXP
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
|
||||
--date2
|
||||
match the secondary date instead (see command help for other
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
|
||||
--today=DATE
|
||||
override today's date (affects relative smart dates, for
|
||||
override today's date (affects relative smart dates, for
|
||||
tests/examples)
|
||||
|
||||
-U --unmarked
|
||||
@ -152,49 +153,49 @@ OPTIONS
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
|
||||
-E --empty
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
|
||||
-B --cost
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
|
||||
-V --market
|
||||
convert amounts to their market value in default valuation com-
|
||||
convert amounts to their market value in default valuation com-
|
||||
modities
|
||||
|
||||
-X --exchange=COMM
|
||||
convert amounts to their market value in commodity COMM
|
||||
|
||||
--value
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
|
||||
--infer-market-prices
|
||||
use transaction prices (recorded with @ or @@) as additional
|
||||
use transaction prices (recorded with @ or @@) as additional
|
||||
market prices, as if they were P directives
|
||||
|
||||
--auto apply automated posting rules to modify transactions.
|
||||
|
||||
--forecast
|
||||
generate future transactions from periodic transaction rules,
|
||||
for the next 6 months or till report end date. In hledger-ui,
|
||||
generate future transactions from periodic transaction rules,
|
||||
for the next 6 months or till report end date. In hledger-ui,
|
||||
also make ordinary future transactions visible.
|
||||
|
||||
--commodity-style
|
||||
Override the commodity style in the output for the specified
|
||||
Override the commodity style in the output for the specified
|
||||
commodity. For example 'EUR1.000,00'.
|
||||
|
||||
--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
|
||||
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
|
||||
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
|
||||
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
|
||||
@ -218,11 +219,11 @@ OPTIONS
|
||||
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,
|
||||
contain one command line option/argument per line. (To prevent this,
|
||||
insert a -- argument before.)
|
||||
|
||||
MOUSE
|
||||
In most modern terminals, you can navigate through the screens with a
|
||||
In most modern terminals, you can navigate through the screens with a
|
||||
mouse or touchpad:
|
||||
|
||||
o Use mouse wheel or trackpad to scroll up and down
|
||||
@ -234,83 +235,83 @@ MOUSE
|
||||
KEYS
|
||||
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 most
|
||||
? 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 or ENTER goes deeper, LEFT returns to
|
||||
The cursor keys navigate: RIGHT or ENTER 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) and VI-style
|
||||
(k,j,l,h) movement keys are also supported. 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, the karabiner app is one way to do
|
||||
through lists. Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style
|
||||
(k,j,l,h) movement keys are also supported. 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, 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 "current" period (the cur-
|
||||
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 "current" period (the cur-
|
||||
rent day, week, month, quarter, or year), the period will move automat-
|
||||
ically to track the current date. To set a non-standard period, you
|
||||
ically 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
|
||||
/ 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 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.
|
||||
|
||||
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-
|
||||
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.
|
||||
|
||||
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
|
||||
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 (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).
|
||||
|
||||
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
|
||||
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 installed in
|
||||
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 cursor
|
||||
will be positioned at the current transaction when invoked from the
|
||||
register and transaction screens, and at the error location (if possi-
|
||||
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 possi-
|
||||
ble) when invoked from the error screen.
|
||||
|
||||
B toggles cost mode, showing amounts in their cost's commodity (like
|
||||
B toggles cost mode, showing amounts in their cost'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 transaction
|
||||
as it was valued on july 30, go to the accounts or register screen,
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
q quits the application.
|
||||
@ -318,186 +319,186 @@ KEYS
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
SCREENS
|
||||
hledger-ui shows several different screens, described below. It shows
|
||||
the "Balance sheet accounts" screen to start with, except in the fol-
|
||||
hledger-ui shows several different screens, described below. It shows
|
||||
the "Balance sheet accounts" screen to start with, except in the fol-
|
||||
lowing situations:
|
||||
|
||||
o If no asset/liability/equity accounts can be detected, or if an
|
||||
account query has been given on the command line, it starts in the
|
||||
o If no asset/liability/equity accounts can be detected, or if an
|
||||
account query has been given on the command line, it starts in the
|
||||
"All accounts" screen.
|
||||
|
||||
o If a starting screen is specified with --menu/--all/--bs/--is/--reg-
|
||||
o If a starting screen is specified with --menu/--all/--bs/--is/--reg-
|
||||
ister on the command line, it starts in that screen.
|
||||
|
||||
From any screen you can press LEFT or ESC to navigate back to the top
|
||||
From any screen you can press LEFT or ESC to navigate back to the top
|
||||
level "Menu" screen.
|
||||
|
||||
Menu
|
||||
The top-most screen. From here you can navigate to three accounts
|
||||
The top-most screen. From here you can navigate to three accounts
|
||||
screens:
|
||||
|
||||
All accounts
|
||||
This screen shows all accounts (possibly filtered by a query), and
|
||||
This screen shows all accounts (possibly filtered by a query), and
|
||||
their end balances on the date shown in the title bar (or their balance
|
||||
changes in the period shown in the title bar, toggleable with H). It
|
||||
changes in the period shown in the title bar, toggleable with H). It
|
||||
is like the hledger balance command.
|
||||
|
||||
Balance sheet accounts
|
||||
This screen shows asset, liability and equity accounts, if these can be
|
||||
detected (see account types). It always shows end balances. It is
|
||||
detected (see account types). It always shows end balances. It is
|
||||
like the hledger balancesheetequity command.
|
||||
|
||||
Income statement accounts
|
||||
This screen shows revenue and expense accounts. It always shows bal-
|
||||
This screen shows revenue and expense accounts. It always shows bal-
|
||||
ance changes. It is like the hledger incomestatement command.
|
||||
|
||||
All of these accounts screens work in much the same way:
|
||||
|
||||
They show accounts which have been posted to by transactions, as well
|
||||
as accounts which have been declared with an account directive (except
|
||||
They show accounts which have been posted to by transactions, as well
|
||||
as accounts which have been declared with an account directive (except
|
||||
for empty parent accounts).
|
||||
|
||||
If you specify a query on the command line or with / in the app, they
|
||||
show just the matched accounts, and the balances from matched transac-
|
||||
If you specify a query on the command line or with / in the app, they
|
||||
show just the matched accounts, and the balances from matched transac-
|
||||
tions.
|
||||
|
||||
hledger-ui shows accounts with zero balances by default (unlike com-
|
||||
hledger-ui shows accounts with zero balances by default (unlike com-
|
||||
mand-line hledger). To hide these, press z to toggle nonzero mode.
|
||||
|
||||
Account names are shown as a flat list by default; press t to toggle
|
||||
tree mode. In list mode, account balances are exclusive of subac-
|
||||
counts, except where subaccounts are hidden by a depth limit (see
|
||||
below). In tree mode, all account balances are inclusive of subac-
|
||||
Account names are shown as a flat list by default; press t to toggle
|
||||
tree mode. In list mode, account balances are exclusive of subac-
|
||||
counts, except where subaccounts are hidden by a depth limit (see
|
||||
below). In tree mode, all account balances are inclusive of subac-
|
||||
counts.
|
||||
|
||||
To see less detail, press a number key, 1 to 9, to set a depth limit.
|
||||
To see less detail, press a number key, 1 to 9, to set a depth limit.
|
||||
Or use - to decrease and +/= to increase the depth limit. 0 shows even
|
||||
less detail, collapsing all accounts to a single total. To remove the
|
||||
depth limit, set it higher than the maximum account depth, or press
|
||||
less detail, collapsing all accounts to a single total. To remove the
|
||||
depth limit, set it higher than the maximum account depth, or press
|
||||
ESCAPE.
|
||||
|
||||
H toggles between showing historical balances or period balances (on
|
||||
H toggles between showing historical balances or period balances (on
|
||||
the "All accounts" screen). Historical balances (the default) are end-
|
||||
ing balances at the end of the report period, taking into account all
|
||||
transactions before that date (filtered by the filter query if any),
|
||||
ing 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
|
||||
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
|
||||
ignore transactions before the report start date, so they show the
|
||||
change in balance during the report period. They are more useful eg
|
||||
when viewing a time log.
|
||||
|
||||
U toggles filtering by unmarked status, including or excluding unmarked
|
||||
postings in the balances. Similarly, P toggles pending postings, and C
|
||||
toggles cleared postings. (By default, balances include all postings;
|
||||
if you activate one or two status filters, only those postings are
|
||||
toggles cleared postings. (By default, balances include all postings;
|
||||
if you activate one or two status filters, only those postings are
|
||||
included; and if you activate all three, the filter is removed.)
|
||||
|
||||
R toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
Press RIGHT to view an account's register screen, Or, LEFT to see the
|
||||
Press RIGHT to view an account's register screen, Or, LEFT to see the
|
||||
menu screen.
|
||||
|
||||
Register
|
||||
This screen shows the transactions affecting a particular account, like
|
||||
a check register. Each line represents one transaction and shows:
|
||||
|
||||
o the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
o the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
by real postings.)
|
||||
|
||||
o the overall change to the current account's balance; positive for an
|
||||
o the overall change to the current account's balance; positive for an
|
||||
inflow to this account, negative for an outflow.
|
||||
|
||||
o the running historical total or period total for the current account,
|
||||
after the transaction. This can be toggled with H. Similar to the
|
||||
accounts screen, the historical total is affected by transactions
|
||||
(filtered by the filter query) before the report start date, while
|
||||
after the transaction. This can be toggled with H. Similar to the
|
||||
accounts screen, the historical total is affected by transactions
|
||||
(filtered by the filter query) before the report start date, while
|
||||
the period total is not. If the historical total is not disturbed by
|
||||
a filter query, it will be the running historical balance you would
|
||||
a filter query, it will be the running historical balance you would
|
||||
see on a bank register for the current account.
|
||||
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
the register if the accounts screen is in tree mode, or if it's in list
|
||||
mode but this account has subaccounts which are not shown due to a
|
||||
depth limit. In other words, the register always shows the transac-
|
||||
tions contributing to the balance shown on the accounts screen. Tree
|
||||
mode but this account has subaccounts which are not shown due to a
|
||||
depth limit. In other words, the register always shows the transac-
|
||||
tions contributing to the balance shown on the accounts screen. Tree
|
||||
mode/list mode can be toggled with t here also.
|
||||
|
||||
U toggles filtering by unmarked status, showing or hiding unmarked
|
||||
U toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, P toggles pending transactions, and C toggles
|
||||
cleared transactions. (By default, transactions with all statuses are
|
||||
shown; if you activate one or two status filters, only those transac-
|
||||
cleared transactions. (By default, transactions with all statuses are
|
||||
shown; if you activate one or two status filters, only those transac-
|
||||
tions are shown; and if you activate all three, the filter is removed.)
|
||||
|
||||
R toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
z toggles nonzero mode, in which only transactions posting a nonzero
|
||||
change are shown (hledger-ui shows zero items by default, unlike com-
|
||||
z toggles nonzero mode, in which only transactions posting a nonzero
|
||||
change are shown (hledger-ui shows zero items by default, unlike com-
|
||||
mand-line hledger).
|
||||
|
||||
Press RIGHT to view the selected transaction in detail.
|
||||
|
||||
Transaction
|
||||
This screen shows a single transaction, as a general journal entry,
|
||||
similar to hledger's print command and journal format (hledger_jour-
|
||||
This screen shows a single transaction, as a general journal entry,
|
||||
similar to hledger's print command and journal format (hledger_jour-
|
||||
nal(5)).
|
||||
|
||||
The transaction's date(s) and any cleared flag, transaction code,
|
||||
description, comments, along with all of its account postings are
|
||||
shown. Simple transactions have two postings, but there can be more
|
||||
The transaction's date(s) and any cleared flag, transaction code,
|
||||
description, comments, along with all of its account postings are
|
||||
shown. Simple transactions have two postings, but there can be more
|
||||
(or in certain cases, fewer).
|
||||
|
||||
UP and DOWN will step through all transactions listed in the previous
|
||||
account register screen. In the title bar, the numbers in parentheses
|
||||
show your position within that account register. They will vary
|
||||
UP and DOWN will step through all transactions listed in the previous
|
||||
account register screen. In the title bar, the numbers in parentheses
|
||||
show your position within that account register. They will vary
|
||||
depending on which account register you came from (remember most trans-
|
||||
actions appear in multiple account registers). The #N number preceding
|
||||
them is the transaction's position within the complete unfiltered jour-
|
||||
nal, which is a more stable id (at least until the next reload).
|
||||
|
||||
Error
|
||||
This screen will appear if there is a problem, such as a parse error,
|
||||
when you press g to reload. Once you have fixed the problem, press g
|
||||
This screen will appear if there is a problem, such as a parse error,
|
||||
when you press g to reload. Once you have fixed the problem, press g
|
||||
again to reload and resume normal operation. (Or, you can press escape
|
||||
to cancel the reload attempt.)
|
||||
|
||||
TIPS
|
||||
Watch mode
|
||||
One of hledger-ui's best features is the auto-reloading -w/--watch
|
||||
mode. With this flag, it will update the display automatically when-
|
||||
One of hledger-ui's best features is the auto-reloading -w/--watch
|
||||
mode. With this flag, it will update the display automatically when-
|
||||
ever changes are saved to the data files.
|
||||
|
||||
This is very useful when reconciling. A good workflow is to have your
|
||||
bank's online register open in a browser window, for reference; the
|
||||
journal file open in an editor window; and hledger-ui in watch mode in
|
||||
This is very useful when reconciling. A good workflow is to have your
|
||||
bank's online register open in a browser window, for reference; the
|
||||
journal file open in an editor window; and hledger-ui in watch mode in
|
||||
a terminal window, eg:
|
||||
|
||||
$ hledger-ui --watch --register checking -C
|
||||
|
||||
As you mark things cleared in the editor, you can see the effect imme-
|
||||
diately without having to context switch. This leaves more mental
|
||||
bandwidth for your accounting. Of course you can still interact with
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
As you mark things cleared in the editor, you can see the effect imme-
|
||||
diately without having to context switch. This leaves more mental
|
||||
bandwidth for your accounting. Of course you can still interact with
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
history.
|
||||
|
||||
Here are some current limitations to be aware of:
|
||||
|
||||
Changes might not be detected with certain editors, possibly including
|
||||
Jetbrains IDEs, gedit, other Gnome applications; or on certain unusual
|
||||
Changes might not be detected with certain editors, possibly including
|
||||
Jetbrains IDEs, gedit, other Gnome applications; or on certain unusual
|
||||
filesystems. (#1617, #911). To work around, reload manually by press-
|
||||
ing g in the hledger-ui window. (Or see #1617 for another workaround,
|
||||
ing g in the hledger-ui window. (Or see #1617 for another workaround,
|
||||
and let us know if it works for you.)
|
||||
|
||||
CPU and memory usage can sometimes gradually increase, if hledger-ui
|
||||
--watch is left running for days. (Possibly correlated with certain
|
||||
platforms, many transactions, and/or large numbers of other files
|
||||
present). To work around, quit and restart it, or (where supported)
|
||||
CPU and memory usage can sometimes gradually increase, if hledger-ui
|
||||
--watch is left running for days. (Possibly correlated with certain
|
||||
platforms, many transactions, and/or large numbers of other files
|
||||
present). To work around, quit and restart it, or (where supported)
|
||||
suspend (CTRL-z) and restart it (fg).
|
||||
|
||||
Debug output
|
||||
You can add --debug[=N] to the command line to log debug output. This
|
||||
will be logged to the file hledger-ui.log in the current directory. N
|
||||
You can add --debug[=N] to the command line to log debug output. This
|
||||
will be logged to the file hledger-ui.log in the current directory. N
|
||||
ranges from 1 (least output, the default) to 9 (maximum output).
|
||||
|
||||
ENVIRONMENT
|
||||
@ -507,17 +508,17 @@ ENVIRONMENT
|
||||
|
||||
On unix computers, the default value is: ~/.hledger.journal.
|
||||
|
||||
A more typical value is something like ~/finance/YYYY.journal, where
|
||||
~/finance is a version-controlled finance directory and YYYY is the
|
||||
current year. Or, ~/finance/current.journal, where current.journal is
|
||||
A more typical value is something like ~/finance/YYYY.journal, where
|
||||
~/finance is a version-controlled finance directory and YYYY is the
|
||||
current year. Or, ~/finance/current.journal, where current.journal is
|
||||
a symbolic link to YYYY.journal.
|
||||
|
||||
The usual way to set this permanently is to add a command to one of
|
||||
The usual way to set this permanently is to add a command to one of
|
||||
your shell's startup files (eg ~/.profile):
|
||||
|
||||
export LEDGER_FILE=~/finance/current.journal`
|
||||
|
||||
On some Mac computers, there is a more thorough way to set environment
|
||||
On some Mac computers, there is a more thorough way to set environment
|
||||
variables, that will also affect applications started from the GUI (eg,
|
||||
Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an
|
||||
entry like:
|
||||
@ -528,21 +529,21 @@ ENVIRONMENT
|
||||
|
||||
For this to take effect you might need to killall Dock, or reboot.
|
||||
|
||||
On Windows computers, the default value is probably C:\Users\YOUR-
|
||||
NAME\.hledger.journal. You can change this by running a command like
|
||||
this in a powershell window (let us know if you need to be an Adminis-
|
||||
On Windows computers, the default value is probably C:\Users\YOUR-
|
||||
NAME\.hledger.journal. You can change this by running a command like
|
||||
this in a powershell window (let us know if you need to be an Adminis-
|
||||
trator, and if this persists across a reboot):
|
||||
|
||||
> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
|
||||
|
||||
Or, change it in settings: see https://www.java.com/en/down-
|
||||
Or, change it in settings: see https://www.java.com/en/down-
|
||||
load/help/path.html.
|
||||
|
||||
FILES
|
||||
Reads data from one or more files in hledger journal, timeclock, time-
|
||||
dot, or CSV format specified with -f, or $LEDGER_FILE, or
|
||||
$HOME/.hledger.journal (on windows, perhaps
|
||||
C:/Users/USER/.hledger.journal).
|
||||
Reads data from one or more files in journal, timeclock, timedot, or
|
||||
CSV format. The default file is .hledger.journal in your home direc-
|
||||
tory; this can be overridden with one or more -f FILE options, or the
|
||||
LEDGER_FILE environment variable.
|
||||
|
||||
BUGS
|
||||
-f- doesn't work (hledger-ui can't read from stdin).
|
||||
@ -550,13 +551,13 @@ BUGS
|
||||
-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 there is no
|
||||
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, 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. Symp-
|
||||
toms include: unresponsive UI, periodic resetting of the cursor posi-
|
||||
--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. Symp-
|
||||
toms include: unresponsive UI, periodic resetting of the cursor posi-
|
||||
tion, momentary display of parse errors, high CPU usage eventually sub-
|
||||
siding, and possibly a small but persistent build-up of CPU usage until
|
||||
the program is restarted.
|
||||
@ -567,7 +568,7 @@ BUGS
|
||||
|
||||
|
||||
REPORTING BUGS
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger chat or
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger chat or
|
||||
hledger mail list)
|
||||
|
||||
|
||||
@ -589,4 +590,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-ui-1.28.99 December 2022 HLEDGER-UI(1)
|
||||
hledger-ui-1.28.99 January 2023 HLEDGER-UI(1)
|
||||
|
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{December 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{January 2023}})m4_dnl
|
||||
|
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-WEB" "1" "December 2022" "hledger-web-1.28.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-WEB" "1" "January 2023" "hledger-web-1.28.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
@ -26,10 +26,11 @@ hledger-web - robust, friendly plain text accounting (Web version)
|
||||
This manual is for hledger\[aq]s web interface, version 1.28.99.
|
||||
See also the hledger manual for common concepts and file formats.
|
||||
.PP
|
||||
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 compatible with ledger(1).
|
||||
hledger is a robust, user-friendly, 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 compatible with ledger(1), and
|
||||
largely interconvertible with beancount(1).
|
||||
.PP
|
||||
hledger-web is a simple web application for browsing and adding
|
||||
transactions.
|
||||
@ -46,10 +47,11 @@ 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.
|
||||
.PP
|
||||
Like hledger, it reads data from one or more files in hledger journal,
|
||||
timeclock, timedot, or CSV format specified with \f[V]-f\f[R], or
|
||||
\f[V]$LEDGER_FILE\f[R], or \f[V]$HOME/.hledger.journal\f[R] (on windows,
|
||||
perhaps \f[V]C:/Users/USER/.hledger.journal\f[R]).
|
||||
Like hledger, it reads data from one or more files in journal,
|
||||
timeclock, timedot, or CSV format.
|
||||
The default file is \f[V].hledger.journal\f[R] in your home directory;
|
||||
this can be overridden with one or more \f[V]-f FILE\f[R] options, or
|
||||
the \f[V]LEDGER_FILE\f[R] environment variable.
|
||||
For more about this see hledger(1).
|
||||
.PP
|
||||
hledger-web can be run in three modes:
|
||||
@ -661,10 +663,11 @@ Or, change it in settings: see
|
||||
https://www.java.com/en/download/help/path.html.
|
||||
.SH FILES
|
||||
.PP
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
timedot, or CSV format specified with \f[V]-f\f[R], or
|
||||
\f[V]$LEDGER_FILE\f[R], or \f[V]$HOME/.hledger.journal\f[R] (on windows,
|
||||
perhaps \f[V]C:/Users/USER/.hledger.journal\f[R]).
|
||||
Reads data from one or more files in journal, timeclock, timedot, or CSV
|
||||
format.
|
||||
The default file is \f[V].hledger.journal\f[R] in your home directory;
|
||||
this can be overridden with one or more \f[V]-f FILE\f[R] options, or
|
||||
the \f[V]LEDGER_FILE\f[R] environment variable.
|
||||
.SH BUGS
|
||||
.PP
|
||||
\f[V]-f-\f[R] doesn\[aq]t work (hledger-web can\[aq]t read from stdin).
|
||||
|
@ -1,4 +1,4 @@
|
||||
This is hledger-web.info, produced by makeinfo version 6.8 from stdin.
|
||||
This is hledger-web.info, produced by makeinfo version 7.0.1 from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
@ -13,18 +13,19 @@ hledger-web(1)
|
||||
|
||||
hledger-web - robust, friendly plain text accounting (Web version)
|
||||
|
||||
'hledger-web [OPTIONS] # run temporarily & browse'
|
||||
'hledger-web --serve [OPTIONS] # run without stopping'
|
||||
'hledger-web --serve-api [OPTIONS] # run JSON server only'
|
||||
'hledger web -- [OPTIONS] [QUERYARGS]' # start from hledger
|
||||
‘hledger-web [OPTIONS] # run temporarily & browse’
|
||||
‘hledger-web --serve [OPTIONS] # run without stopping’
|
||||
‘hledger-web --serve-api [OPTIONS] # run JSON server only’
|
||||
‘hledger web -- [OPTIONS] [QUERYARGS]’ # start from hledger
|
||||
|
||||
This manual is for hledger's web interface, version 1.28.99. See
|
||||
This manual is for hledger’s web interface, version 1.28.99. See
|
||||
also the hledger manual for common concepts and file formats.
|
||||
|
||||
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
|
||||
compatible with ledger(1).
|
||||
hledger is a robust, user-friendly, 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 compatible with ledger(1), and largely interconvertible with
|
||||
beancount(1).
|
||||
|
||||
hledger-web is a simple web application for browsing and adding
|
||||
transactions. It provides a more user-friendly UI than the hledger CLI
|
||||
@ -38,22 +39,23 @@ 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).
|
||||
Like hledger, it reads data from one or more files in journal,
|
||||
timeclock, timedot, or CSV format. The default file is
|
||||
‘.hledger.journal’ in your home directory; this can be overridden with
|
||||
one or more ‘-f FILE’ options, or the ‘LEDGER_FILE’ environment
|
||||
variable. For more about this see hledger(1).
|
||||
|
||||
hledger-web can be run in three modes:
|
||||
|
||||
* Transient mode (the default): your default web browser will be
|
||||
• Transient mode (the default): your default web browser will be
|
||||
opened to show the app if possible, and the app exits automatically
|
||||
after two minutes of inactivity (no requests received and no open
|
||||
browser windows viewing it).
|
||||
|
||||
* With '--serve': the app runs without stopping, and without opening
|
||||
• With ‘--serve’: the app runs without stopping, and without opening
|
||||
a browser.
|
||||
|
||||
* With '--serve-api': only the JSON API is served.
|
||||
• With ‘--serve-api’: only the JSON API is served.
|
||||
|
||||
In all cases hledger-web runs as a foreground process, logging
|
||||
requests to stdout.
|
||||
@ -80,180 +82,180 @@ 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
|
||||
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 after timeout
|
||||
'--serve-api'
|
||||
serve and log requests, don’t browse or auto-exit after timeout
|
||||
‘--serve-api’
|
||||
|
||||
like -serve, but serve only the JSON web API, without the
|
||||
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
|
||||
TCP socket. Implies ‘--serve’. It can only be used if the
|
||||
operating system can provide this type of socket.
|
||||
'--base-url=URL'
|
||||
‘--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'
|
||||
‘--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..]'
|
||||
‘--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'
|
||||
‘--test’
|
||||
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
follow a -, eg: hledger-web -test - -help
|
||||
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'
|
||||
‘-f FILE --file=FILE’
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
‘$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'
|
||||
Field separator to expect when reading CSV (default: ’,’)
|
||||
‘--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
|
||||
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
|
||||
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)'
|
||||
commodity. For example ’EUR1.000,00’.
|
||||
‘--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
|
||||
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
|
||||
NO_COLOR environment variable overrides this.
|
||||
'--pretty[=WHEN]'
|
||||
‘--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'.
|
||||
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 last one takes precedence.
|
||||
@ -262,53 +264,53 @@ 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.)
|
||||
this, insert a ‘--’ argument before.)
|
||||
|
||||
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
|
||||
0.0.0.0' to listen on all configured addresses.
|
||||
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
|
||||
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
|
||||
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’ 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.
|
||||
|
||||
@ -323,28 +325,28 @@ 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
|
||||
• 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,
|
||||
• 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
|
||||
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
|
||||
• 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
|
||||
@ -352,7 +354,7 @@ 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
|
||||
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.
|
||||
@ -363,7 +365,7 @@ 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,
|
||||
currently; if you use one, you'll have to arrange to commit the changes
|
||||
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
|
||||
@ -393,7 +395,7 @@ File: hledger-web.info, Node: JSON API, Next: DEBUG OUTPUT, 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:
|
||||
only, you can use the ‘--serve-api’ flag. Eg:
|
||||
|
||||
$ hledger-web -f examples/sample.journal --serve-api
|
||||
...
|
||||
@ -409,7 +411,7 @@ $ hledger-web -f examples/sample.journal --serve-api
|
||||
/accounttransactions/ACCOUNTNAME
|
||||
|
||||
Eg, all account names in the journal (similar to the accounts
|
||||
command). (hledger-web's JSON does not include newlines, here we use
|
||||
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
|
||||
@ -450,7 +452,7 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
"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
|
||||
on the various data types, eg Transaction. And for a higher level
|
||||
understanding, see the journal docs.
|
||||
@ -458,25 +460,25 @@ understanding, see the journal docs.
|
||||
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
|
||||
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
|
||||
‘/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
|
||||
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)
|
||||
>>> :q
|
||||
|
||||
Here's how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger's Transaction and related data types):
|
||||
Here’s how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger’s Transaction and related data types):
|
||||
|
||||
{
|
||||
"tcomment": "",
|
||||
@ -564,7 +566,7 @@ 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
|
||||
@ -585,13 +587,13 @@ File: hledger-web.info, Node: Debug output, Up: DEBUG OUTPUT
|
||||
6.1 Debug output
|
||||
================
|
||||
|
||||
You can add '--debug[=N]' to the command line to log debug output. N
|
||||
You can add ‘--debug[=N]’ to the command line to log debug output. N
|
||||
ranges from 1 (least output, the default) to 9 (maximum output).
|
||||
Typically you would start with 1 and increase until you are seeing
|
||||
enough. Debug output goes to stderr, interleaved with the requests
|
||||
logged on stdout. To capture debug output in a log file instead, you
|
||||
can usually redirect stderr, eg:
|
||||
'hledger-web --debug=3 2>hledger-web.log'.
|
||||
‘hledger-web --debug=3 2>hledger-web.log’.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: DEBUG OUTPUT, Up: Top
|
||||
@ -599,33 +601,33 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: DEBUG OUTPUT,
|
||||
7 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
*LEDGER_FILE* The journal file path when not specified with ‘-f’.
|
||||
|
||||
On unix computers, the default value is: '~/.hledger.journal'.
|
||||
On unix computers, the default value is: ‘~/.hledger.journal’.
|
||||
|
||||
A more typical value is something like '~/finance/YYYY.journal',
|
||||
where '~/finance' is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, '~/finance/current.journal', where
|
||||
A more typical value is something like ‘~/finance/YYYY.journal’,
|
||||
where ‘~/finance’ is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, ‘~/finance/current.journal’, where
|
||||
current.journal is a symbolic link to YYYY.journal.
|
||||
|
||||
The usual way to set this permanently is to add a command to one of
|
||||
your shell's startup files (eg '~/.profile'):
|
||||
your shell’s startup files (eg ‘~/.profile’):
|
||||
|
||||
export LEDGER_FILE=~/finance/current.journal`
|
||||
|
||||
On some Mac computers, there is a more thorough way to set
|
||||
environment variables, that will also affect applications started from
|
||||
the GUI (eg, Emacs started from a dock icon): In
|
||||
'~/.MacOSX/environment.plist', add an entry like:
|
||||
‘~/.MacOSX/environment.plist’, add an entry like:
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
For this to take effect you might need to 'killall Dock', or reboot.
|
||||
For this to take effect you might need to ‘killall Dock’, or reboot.
|
||||
|
||||
On Windows computers, the default value is probably
|
||||
'C:\Users\YOURNAME\.hledger.journal'. You can change this by running a
|
||||
‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a
|
||||
command like this in a powershell window (let us know if you need to be
|
||||
an Administrator, and if this persists across a reboot):
|
||||
|
||||
@ -640,10 +642,10 @@ File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
8 FILES
|
||||
*******
|
||||
|
||||
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').
|
||||
Reads data from one or more files in journal, timeclock, timedot, or CSV
|
||||
format. The default file is ‘.hledger.journal’ in your home directory;
|
||||
this can be overridden with one or more ‘-f FILE’ options, or the
|
||||
‘LEDGER_FILE’ environment variable.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -651,7 +653,7 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
9 BUGS
|
||||
******
|
||||
|
||||
'-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.
|
||||
|
||||
@ -661,27 +663,27 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top223
|
||||
Node: OPTIONS2585
|
||||
Ref: #options2690
|
||||
Node: PERMISSIONS10089
|
||||
Ref: #permissions10228
|
||||
Node: EDITING UPLOADING DOWNLOADING11440
|
||||
Ref: #editing-uploading-downloading11621
|
||||
Node: RELOADING12455
|
||||
Ref: #reloading12589
|
||||
Node: JSON API13022
|
||||
Ref: #json-api13137
|
||||
Node: DEBUG OUTPUT18625
|
||||
Ref: #debug-output18750
|
||||
Node: Debug output18777
|
||||
Ref: #debug-output-118878
|
||||
Node: ENVIRONMENT19295
|
||||
Ref: #environment19415
|
||||
Node: FILES20726
|
||||
Ref: #files20826
|
||||
Node: BUGS21039
|
||||
Ref: #bugs21117
|
||||
Node: Top225
|
||||
Node: OPTIONS2727
|
||||
Ref: #options2832
|
||||
Node: PERMISSIONS10588
|
||||
Ref: #permissions10727
|
||||
Node: EDITING UPLOADING DOWNLOADING11985
|
||||
Ref: #editing-uploading-downloading12166
|
||||
Node: RELOADING13008
|
||||
Ref: #reloading13142
|
||||
Node: JSON API13575
|
||||
Ref: #json-api13690
|
||||
Node: DEBUG OUTPUT19222
|
||||
Ref: #debug-output19347
|
||||
Node: Debug output19374
|
||||
Ref: #debug-output-119475
|
||||
Node: ENVIRONMENT19900
|
||||
Ref: #environment20020
|
||||
Node: FILES21369
|
||||
Ref: #files21469
|
||||
Node: BUGS21729
|
||||
Ref: #bugs21807
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
@ -16,27 +16,29 @@ DESCRIPTION
|
||||
This manual is for hledger's web interface, version 1.28.99. See also
|
||||
the hledger manual for common concepts and file formats.
|
||||
|
||||
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
|
||||
compatible with ledger(1).
|
||||
hledger is a robust, user-friendly, 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 compatible with ledger(1), and largely interconvertible
|
||||
with beancount(1).
|
||||
|
||||
hledger-web is a simple web application for browsing and adding trans-
|
||||
actions. It provides a more user-friendly UI than the hledger CLI or
|
||||
hledger-ui TUI, showing more at once (accounts, the current account
|
||||
hledger-web is a simple web application for browsing and adding trans-
|
||||
actions. It provides a more user-friendly UI than the hledger CLI or
|
||||
hledger-ui TUI, showing more at once (accounts, the current account
|
||||
register, balance charts) and allowing history-aware data entry, inter-
|
||||
active searching, and bookmarking.
|
||||
|
||||
hledger-web also lets you share a journal 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
|
||||
hledger-web also lets you share a journal 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.
|
||||
|
||||
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).
|
||||
Like hledger, it reads data from one or more files in journal, time-
|
||||
clock, timedot, or CSV format. The default file is .hledger.journal in
|
||||
your home directory; this can be overridden with one or more -f FILE
|
||||
options, or the LEDGER_FILE environment variable. For more about this
|
||||
see hledger(1).
|
||||
|
||||
hledger-web can be run in three modes:
|
||||
|
||||
@ -567,10 +569,10 @@ ENVIRONMENT
|
||||
load/help/path.html.
|
||||
|
||||
FILES
|
||||
Reads data from one or more files in hledger journal, timeclock, time-
|
||||
dot, or CSV format specified with -f, or $LEDGER_FILE, or
|
||||
$HOME/.hledger.journal (on windows, perhaps
|
||||
C:/Users/USER/.hledger.journal).
|
||||
Reads data from one or more files in journal, timeclock, timedot, or
|
||||
CSV format. The default file is .hledger.journal in your home direc-
|
||||
tory; this can be overridden with one or more -f FILE options, or the
|
||||
LEDGER_FILE environment variable.
|
||||
|
||||
BUGS
|
||||
-f- doesn't work (hledger-web can't read from stdin).
|
||||
@ -606,4 +608,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-web-1.28.99 December 2022 HLEDGER-WEB(1)
|
||||
hledger-web-1.28.99 January 2023 HLEDGER-WEB(1)
|
||||
|
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{December 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{January 2023}})m4_dnl
|
||||
|
1710
hledger/hledger.1
1710
hledger/hledger.1
File diff suppressed because it is too large
Load Diff
6043
hledger/hledger.info
6043
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
3351
hledger/hledger.txt
3351
hledger/hledger.txt
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user