mirror of
https://github.com/simonmichael/hledger.git
synced 2024-12-26 20:02:27 +03:00
666 lines
23 KiB
Groff
666 lines
23 KiB
Groff
|
|
.TH "HLEDGER-UI" "1" "December 2022" "hledger-ui-1.28.99 " "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
hledger-ui - robust, friendly plain text accounting (TUI version)
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[V]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[V]hledger ui -- [OPTIONS] [QUERYARGS]\f[R]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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).
|
|
.PP
|
|
hledger-ui is hledger\[aq]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\[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]).
|
|
For more about this see hledger(1), hledger_journal(5) etc.
|
|
.PP
|
|
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 \[dq]forecast mode\[dq].
|
|
.SH OPTIONS
|
|
.PP
|
|
Note: if invoking hledger-ui as a hledger subcommand, write \f[V]--\f[R]
|
|
before options as shown above.
|
|
.PP
|
|
Any QUERYARGS are interpreted as a hledger search query which filters
|
|
the data.
|
|
.TP
|
|
\f[V]-w --watch\f[R]
|
|
watch for data and date changes and reload automatically
|
|
.TP
|
|
\f[V]--theme=default|terminal|greenterm\f[R]
|
|
use this custom display theme
|
|
.TP
|
|
\f[V]--menu\f[R]
|
|
start in the menu screen
|
|
.TP
|
|
\f[V]--all\f[R]
|
|
start in the all accounts screen
|
|
.TP
|
|
\f[V]--bs\f[R]
|
|
start in the balance sheet accounts screen
|
|
.TP
|
|
\f[V]--is\f[R]
|
|
start in the income statement accounts screen
|
|
.TP
|
|
\f[V]--register=ACCTREGEX\f[R]
|
|
start in the (first) matched account\[aq]s register screen
|
|
.TP
|
|
\f[V]--change\f[R]
|
|
show period balances (changes) at startup instead of historical balances
|
|
.TP
|
|
\f[V]-l --flat\f[R]
|
|
show accounts as a flat list (default)
|
|
.TP
|
|
\f[V]-t --tree\f[R]
|
|
show accounts as a tree
|
|
.PP
|
|
hledger input options:
|
|
.TP
|
|
\f[V]-f FILE --file=FILE\f[R]
|
|
use a different input file.
|
|
For stdin, use - (default: \f[V]$LEDGER_FILE\f[R] or
|
|
\f[V]$HOME/.hledger.journal\f[R])
|
|
.TP
|
|
\f[V]--rules-file=RULESFILE\f[R]
|
|
Conversion rules file to use when reading CSV (default: FILE.rules)
|
|
.TP
|
|
\f[V]--separator=CHAR\f[R]
|
|
Field separator to expect when reading CSV (default: \[aq],\[aq])
|
|
.TP
|
|
\f[V]--alias=OLD=NEW\f[R]
|
|
rename accounts named OLD to NEW
|
|
.TP
|
|
\f[V]--anon\f[R]
|
|
anonymize accounts and payees
|
|
.TP
|
|
\f[V]--pivot FIELDNAME\f[R]
|
|
use some other field or tag for the account name
|
|
.TP
|
|
\f[V]-I --ignore-assertions\f[R]
|
|
disable balance assertion checks (note: does not disable balance
|
|
assignments)
|
|
.TP
|
|
\f[V]-s --strict\f[R]
|
|
do extra error checking (check that all posted accounts are declared)
|
|
.PP
|
|
hledger reporting options:
|
|
.TP
|
|
\f[V]-b --begin=DATE\f[R]
|
|
include postings/txns on or after this date (will be adjusted to
|
|
preceding subperiod start when using a report interval)
|
|
.TP
|
|
\f[V]-e --end=DATE\f[R]
|
|
include postings/txns before this date (will be adjusted to following
|
|
subperiod end when using a report interval)
|
|
.TP
|
|
\f[V]-D --daily\f[R]
|
|
multiperiod/multicolumn report by day
|
|
.TP
|
|
\f[V]-W --weekly\f[R]
|
|
multiperiod/multicolumn report by week
|
|
.TP
|
|
\f[V]-M --monthly\f[R]
|
|
multiperiod/multicolumn report by month
|
|
.TP
|
|
\f[V]-Q --quarterly\f[R]
|
|
multiperiod/multicolumn report by quarter
|
|
.TP
|
|
\f[V]-Y --yearly\f[R]
|
|
multiperiod/multicolumn report by year
|
|
.TP
|
|
\f[V]-p --period=PERIODEXP\f[R]
|
|
set start date, end date, and/or reporting interval all at once using
|
|
period expressions syntax
|
|
.TP
|
|
\f[V]--date2\f[R]
|
|
match the secondary date instead (see command help for other effects)
|
|
.TP
|
|
\f[V]--today=DATE\f[R]
|
|
override today\[aq]s date (affects relative smart dates, for
|
|
tests/examples)
|
|
.TP
|
|
\f[V]-U --unmarked\f[R]
|
|
include only unmarked postings/txns (can combine with -P or -C)
|
|
.TP
|
|
\f[V]-P --pending\f[R]
|
|
include only pending postings/txns
|
|
.TP
|
|
\f[V]-C --cleared\f[R]
|
|
include only cleared postings/txns
|
|
.TP
|
|
\f[V]-R --real\f[R]
|
|
include only non-virtual postings
|
|
.TP
|
|
\f[V]-NUM --depth=NUM\f[R]
|
|
hide/aggregate accounts or postings more than NUM levels deep
|
|
.TP
|
|
\f[V]-E --empty\f[R]
|
|
show items with zero amount, normally hidden (and vice-versa in
|
|
hledger-ui/hledger-web)
|
|
.TP
|
|
\f[V]-B --cost\f[R]
|
|
convert amounts to their cost/selling amount at transaction time
|
|
.TP
|
|
\f[V]-V --market\f[R]
|
|
convert amounts to their market value in default valuation commodities
|
|
.TP
|
|
\f[V]-X --exchange=COMM\f[R]
|
|
convert amounts to their market value in commodity COMM
|
|
.TP
|
|
\f[V]--value\f[R]
|
|
convert amounts to cost or market value, more flexibly than -B/-V/-X
|
|
.TP
|
|
\f[V]--infer-market-prices\f[R]
|
|
use transaction prices (recorded with \[at] or \[at]\[at]) as additional
|
|
market prices, as if they were P directives
|
|
.TP
|
|
\f[V]--auto\f[R]
|
|
apply automated posting rules to modify transactions.
|
|
.TP
|
|
\f[V]--forecast\f[R]
|
|
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.
|
|
.TP
|
|
\f[V]--commodity-style\f[R]
|
|
Override the commodity style in the output for the specified commodity.
|
|
For example \[aq]EUR1.000,00\[aq].
|
|
.TP
|
|
\f[V]--color=WHEN (or --colour=WHEN)\f[R]
|
|
Should color-supporting commands use ANSI color codes in text output.
|
|
\[aq]auto\[aq] (default): whenever stdout seems to be a color-supporting
|
|
terminal.
|
|
\[aq]always\[aq] or \[aq]yes\[aq]: always, useful eg when piping output
|
|
into \[aq]less -R\[aq].
|
|
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
|
A NO_COLOR environment variable overrides this.
|
|
.TP
|
|
\f[V]--pretty[=WHEN]\f[R]
|
|
Show prettier output, e.g.
|
|
using unicode box-drawing characters.
|
|
Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],
|
|
\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).
|
|
If you provide an argument you must use \[aq]=\[aq], e.g.
|
|
\[aq]--pretty=yes\[aq].
|
|
.PP
|
|
When a reporting option appears more than once in the command line, the
|
|
last one takes precedence.
|
|
.PP
|
|
Some reporting options can also be written as query arguments.
|
|
.PP
|
|
hledger help options:
|
|
.TP
|
|
\f[V]-h --help\f[R]
|
|
show general or COMMAND help
|
|
.TP
|
|
\f[V]--man\f[R]
|
|
show general or COMMAND user manual with man
|
|
.TP
|
|
\f[V]--info\f[R]
|
|
show general or COMMAND user manual with info
|
|
.TP
|
|
\f[V]--version\f[R]
|
|
show general or ADDONCMD version
|
|
.TP
|
|
\f[V]--debug[=N]\f[R]
|
|
show debug output (levels 1-9, default: 1)
|
|
.PP
|
|
A \[at]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 \f[V]--\f[R] argument before.)
|
|
.SH MOUSE
|
|
.PP
|
|
In most modern terminals, you can navigate through the screens with a
|
|
mouse or touchpad:
|
|
.IP \[bu] 2
|
|
Use mouse wheel or trackpad to scroll up and down
|
|
.IP \[bu] 2
|
|
Click on list items to go deeper
|
|
.IP \[bu] 2
|
|
Click on the left margin (column 0) to go back.
|
|
.SH KEYS
|
|
.PP
|
|
Keyboard gives more control.
|
|
.PP
|
|
\f[V]?\f[R] shows a help dialog listing all keys.
|
|
(Some of these also appear in the quick help at the bottom of each
|
|
screen.)
|
|
Press \f[V]?\f[R] again (or \f[V]ESCAPE\f[R], or \f[V]LEFT\f[R], or
|
|
\f[V]q\f[R]) to close it.
|
|
The following keys work on most screens:
|
|
.PP
|
|
The cursor keys navigate: \f[V]RIGHT\f[R] or \f[V]ENTER\f[R] goes
|
|
deeper, \f[V]LEFT\f[R] returns to the previous screen,
|
|
\f[V]UP\f[R]/\f[V]DOWN\f[R]/\f[V]PGUP\f[R]/\f[V]PGDN\f[R]/\f[V]HOME\f[R]/\f[V]END\f[R]
|
|
move up and down through lists.
|
|
Emacs-style
|
|
(\f[V]CTRL-p\f[R]/\f[V]CTRL-n\f[R]/\f[V]CTRL-f\f[R]/\f[V]CTRL-b\f[R])
|
|
and VI-style (\f[V]k\f[R],\f[V]j\f[R],\f[V]l\f[R],\f[V]h\f[R]) 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\[aq]re on a mac, the karabiner app is one way to do that.)
|
|
.PP
|
|
With shift pressed, the cursor keys adjust the report period, limiting
|
|
the transactions to be shown (by default, all are shown).
|
|
\f[V]SHIFT-DOWN/UP\f[R] steps downward and upward through these standard
|
|
report period durations: year, quarter, month, week, day.
|
|
Then, \f[V]SHIFT-LEFT/RIGHT\f[R] moves to the previous/next period.
|
|
\f[V]T\f[R] sets the report period to today.
|
|
With the \f[V]-w/--watch\f[R] option, when viewing a \[dq]current\[dq]
|
|
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 \f[V]/\f[R] and a
|
|
\f[V]date:\f[R] query.
|
|
.PP
|
|
\f[V]/\f[R] 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 \f[V]ENTER\f[R] to set it, or \f[V]ESCAPE\f[R]to cancel.
|
|
There are also keys for quickly adjusting some common filters like
|
|
account depth and transaction status (see below).
|
|
\f[V]BACKSPACE\f[R] or \f[V]DELETE\f[R] removes all filters, showing all
|
|
transactions.
|
|
.PP
|
|
As mentioned above, by default hledger-ui hides future transactions -
|
|
both ordinary transactions recorded in the journal, and periodic
|
|
transactions generated by rule.
|
|
\f[V]F\f[R] toggles forecast mode, in which future/forecasted
|
|
transactions are shown.
|
|
.PP
|
|
\f[V]ESCAPE\f[R] resets the UI state and jumps back to the top screen,
|
|
restoring the app\[aq]s initial state at startup.
|
|
Or, it cancels minibuffer data entry or the help dialog.
|
|
.PP
|
|
\f[V]CTRL-l\f[R] redraws the screen and centers the selection if
|
|
possible (selections near the top won\[aq]t be centered, since we
|
|
don\[aq]t scroll above the top).
|
|
.PP
|
|
\f[V]g\f[R] reloads from the data file(s) and updates the current screen
|
|
and any previous screens.
|
|
(With large files, this could cause a noticeable pause.)
|
|
.PP
|
|
\f[V]I\f[R] toggles balance assertion checking.
|
|
Disabling balance assertions temporarily can be useful for
|
|
troubleshooting.
|
|
.PP
|
|
\f[V]a\f[R] runs command-line hledger\[aq]s add command, and reloads the
|
|
updated file.
|
|
This allows some basic data entry.
|
|
.PP
|
|
\f[V]A\f[R] is like \f[V]a\f[R], but runs the hledger-iadd tool, which
|
|
provides a terminal interface.
|
|
This key will be available if \f[V]hledger-iadd\f[R] is installed in
|
|
$path.
|
|
.PP
|
|
\f[V]E\f[R] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default
|
|
(\f[V]emacsclient -a \[dq]\[dq] -nw\f[R]) 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.
|
|
.PP
|
|
\f[V]B\f[R] toggles cost mode, showing amounts in their cost\[aq]s
|
|
commodity (like toggling the \f[V]-B/--cost\f[R] flag).
|
|
.PP
|
|
\f[V]V\f[R] toggles value mode, showing amounts\[aq] current market
|
|
value in their default valuation commodity (like toggling the
|
|
\f[V]-V/--market\f[R] flag).
|
|
Note, \[dq]current market value\[dq] 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 \f[V]/\f[R], and add \f[V]date:-7/30\f[R] to
|
|
the query.
|
|
.PP
|
|
At most one of cost or value mode can be active at once.
|
|
.PP
|
|
There\[aq]s not yet any visual reminder when cost or value mode is
|
|
active; for now pressing \f[V]b\f[R] \f[V]b\f[R] \f[V]v\f[R] should
|
|
reliably reset to normal mode.
|
|
.PP
|
|
\f[V]q\f[R] quits the application.
|
|
.PP
|
|
Additional screen-specific keys are described below.
|
|
.SH SCREENS
|
|
.PP
|
|
hledger-ui shows several different screens, described below.
|
|
It shows the \[dq]Balance sheet accounts\[dq] screen to start with,
|
|
except in the following situations:
|
|
.IP \[bu] 2
|
|
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 \[dq]All
|
|
accounts\[dq] screen.
|
|
.IP \[bu] 2
|
|
If a starting screen is specified with --menu/--all/--bs/--is/--register
|
|
on the command line, it starts in that screen.
|
|
.PP
|
|
From any screen you can press \f[V]LEFT\f[R] or \f[V]ESC\f[R] to
|
|
navigate back to the top level \[dq]Menu\[dq] screen.
|
|
.SS Menu
|
|
.PP
|
|
The top-most screen.
|
|
From here you can navigate to three accounts screens:
|
|
.SS All accounts
|
|
.PP
|
|
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
|
|
\f[V]H\f[R]).
|
|
It is like the \f[V]hledger balance\f[R] command.
|
|
.SS Balance sheet accounts
|
|
.PP
|
|
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 \f[V]hledger balancesheetequity\f[R] command.
|
|
.SS Income statement accounts
|
|
.PP
|
|
This screen shows revenue and expense accounts.
|
|
It always shows balance changes.
|
|
It is like the \f[V]hledger incomestatement\f[R] command.
|
|
.PP
|
|
All of these accounts screens work in much the same way:
|
|
.PP
|
|
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).
|
|
.PP
|
|
If you specify a query on the command line or with \f[V]/\f[R] in the
|
|
app, they show just the matched accounts, and the balances from matched
|
|
transactions.
|
|
.PP
|
|
hledger-ui shows accounts with zero balances by default (unlike
|
|
command-line hledger).
|
|
To hide these, press \f[V]z\f[R] to toggle nonzero mode.
|
|
.PP
|
|
Account names are shown as a flat list by default; press \f[V]t\f[R] 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.
|
|
.PP
|
|
To see less detail, press a number key, \f[V]1\f[R] to \f[V]9\f[R], to
|
|
set a depth limit.
|
|
Or use \f[V]-\f[R] to decrease and \f[V]+\f[R]/\f[V]=\f[R] to increase
|
|
the depth limit.
|
|
\f[V]0\f[R] 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 \f[V]ESCAPE\f[R].
|
|
.PP
|
|
\f[V]H\f[R] toggles between showing historical balances or period
|
|
balances (on the \[dq]All accounts\[dq] 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), including transactions before the
|
|
start of the report period.
|
|
In other words, historical balances are what you would see on a bank
|
|
statement for that account (unless disturbed by a filter query).
|
|
Period balances ignore transactions before the report start date, so
|
|
they show the change in balance during the report period.
|
|
They are more useful eg when viewing a time log.
|
|
.PP
|
|
\f[V]U\f[R] toggles filtering by unmarked status, including or excluding
|
|
unmarked postings in the balances.
|
|
Similarly, \f[V]P\f[R] toggles pending postings, and \f[V]C\f[R] 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.)
|
|
.PP
|
|
\f[V]R\f[R] toggles real mode, in which virtual postings are ignored.
|
|
.PP
|
|
Press \f[V]RIGHT\f[R] to view an account\[aq]s register screen, Or,
|
|
\f[V]LEFT\f[R] to see the menu screen.
|
|
.SS Register
|
|
.PP
|
|
This screen shows the transactions affecting a particular account, like
|
|
a check register.
|
|
Each line represents one transaction and shows:
|
|
.IP \[bu] 2
|
|
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.)
|
|
.IP \[bu] 2
|
|
the overall change to the current account\[aq]s balance; positive for an
|
|
inflow to this account, negative for an outflow.
|
|
.IP \[bu] 2
|
|
the running historical total or period total for the current account,
|
|
after the transaction.
|
|
This can be toggled with \f[V]H\f[R].
|
|
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.
|
|
.PP
|
|
Transactions affecting this account\[aq]s subaccounts will be included
|
|
in the register if the accounts screen is in tree mode, or if it\[aq]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 \f[V]t\f[R] here also.
|
|
.PP
|
|
\f[V]U\f[R] toggles filtering by unmarked status, showing or hiding
|
|
unmarked transactions.
|
|
Similarly, \f[V]P\f[R] toggles pending transactions, and \f[V]C\f[R]
|
|
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.)
|
|
.PP
|
|
\f[V]R\f[R] toggles real mode, in which virtual postings are ignored.
|
|
.PP
|
|
\f[V]z\f[R] toggles nonzero mode, in which only transactions posting a
|
|
nonzero change are shown (hledger-ui shows zero items by default, unlike
|
|
command-line hledger).
|
|
.PP
|
|
Press \f[V]RIGHT\f[R] to view the selected transaction in detail.
|
|
.SS Transaction
|
|
.PP
|
|
This screen shows a single transaction, as a general journal entry,
|
|
similar to hledger\[aq]s print command and journal format
|
|
(hledger_journal(5)).
|
|
.PP
|
|
The transaction\[aq]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).
|
|
.PP
|
|
\f[V]UP\f[R] and \f[V]DOWN\f[R] 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\[aq]s position within
|
|
the complete unfiltered journal, which is a more stable id (at least
|
|
until the next reload).
|
|
.SS Error
|
|
.PP
|
|
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.)
|
|
.SH TIPS
|
|
.SS Watch mode
|
|
.PP
|
|
One of hledger-ui\[aq]s best features is the auto-reloading
|
|
\f[V]-w/--watch\f[R] mode.
|
|
With this flag, it will update the display automatically whenever
|
|
changes are saved to the data files.
|
|
.PP
|
|
This is very useful when reconciling.
|
|
A good workflow is to have your bank\[aq]s online register open in a
|
|
browser window, for reference; the journal file open in an editor
|
|
window; and hledger-ui in watch mode in a terminal window, eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$ hledger-ui --watch --register checking -C
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
As you mark things cleared in the editor, you can see the effect
|
|
immediately without having to context switch.
|
|
This leaves more mental bandwidth for your accounting.
|
|
Of course you can still interact with hledger-ui when needed, eg to
|
|
toggle cleared mode, or to explore the history.
|
|
.PP
|
|
Here are some current limitations to be aware of:
|
|
.PP
|
|
Changes might not be detected with certain editors, possibly including
|
|
Jetbrains IDEs, \f[V]gedit\f[R], other Gnome applications; or on certain
|
|
unusual filesystems.
|
|
(#1617, #911).
|
|
To work around, reload manually by pressing \f[V]g\f[R] in the
|
|
hledger-ui window.
|
|
(Or see #1617 for another workaround, and let us know if it works for
|
|
you.)
|
|
.PP
|
|
CPU and memory usage can sometimes gradually increase, if
|
|
\f[V]hledger-ui --watch\f[R] is left running for days.
|
|
(Possibly correlated with certain platforms, many transactions, and/or
|
|
large numbers of other files present).
|
|
To work around, \f[V]q\f[R]uit and restart it, or (where supported)
|
|
suspend (\f[V]CTRL-z\f[R]) and restart it (\f[V]fg\f[R]).
|
|
.SS Debug output
|
|
.PP
|
|
You can add \f[V]--debug[=N]\f[R] to the command line to log debug
|
|
output.
|
|
This will be logged to the file \f[V]hledger-ui.log\f[R] in the current
|
|
directory.
|
|
N ranges from 1 (least output, the default) to 9 (maximum output).
|
|
.SH ENVIRONMENT
|
|
.PP
|
|
\f[B]COLUMNS\f[R] The screen width to use.
|
|
Default: the full terminal width.
|
|
.PP
|
|
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with
|
|
\f[V]-f\f[R].
|
|
.PP
|
|
On unix computers, the default value is:
|
|
\f[V]\[ti]/.hledger.journal\f[R].
|
|
.PP
|
|
A more typical value is something like
|
|
\f[V]\[ti]/finance/YYYY.journal\f[R], where \f[V]\[ti]/finance\f[R] is a
|
|
version-controlled finance directory and YYYY is the current year.
|
|
Or, \f[V]\[ti]/finance/current.journal\f[R], where current.journal is a
|
|
symbolic link to YYYY.journal.
|
|
.PP
|
|
The usual way to set this permanently is to add a command to one of your
|
|
shell\[aq]s startup files (eg \f[V]\[ti]/.profile\f[R]):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
export LEDGER_FILE=\[ti]/finance/current.journal\[ga]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
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
|
|
\f[V]\[ti]/.MacOSX/environment.plist\f[R], add an entry like:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
{
|
|
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/current.journal\[dq]
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
For this to take effect you might need to \f[V]killall Dock\f[R], or
|
|
reboot.
|
|
.PP
|
|
On Windows computers, the default value is probably
|
|
\f[V]C:\[rs]Users\[rs]YOURNAME\[rs].hledger.journal\f[R].
|
|
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):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
> setx LEDGER_FILE \[dq]C:\[rs]Users\[rs]MyUserName\[rs]finance\[rs]2021.journal\[dq]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
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]).
|
|
.SH BUGS
|
|
.PP
|
|
\f[V]-f-\f[R] doesn\[aq]t work (hledger-ui can\[aq]t read from stdin).
|
|
.PP
|
|
\f[V]-V\f[R] affects only the accounts screen.
|
|
.PP
|
|
When you press \f[V]g\f[R], 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.
|
|
.PP
|
|
\f[V]--watch\f[R] 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, momentary display of parse errors, high CPU usage eventually
|
|
subsiding, and possibly a small but persistent build-up of CPU usage
|
|
until the program is restarted.
|
|
.PP
|
|
Also, if you are viewing files mounted from another machine,
|
|
\f[V]-w/--watch\f[R] requires that both machine clocks are roughly in
|
|
step.
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger chat or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors.
|
|
.br
|
|
See http://hledger.org/CREDITS.html
|
|
|
|
.SH COPYRIGHT
|
|
Copyright 2007-2023 Simon Michael and contributors.
|
|
|
|
.SH LICENSE
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
|