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
04812682e8
commit
d06d4ca080
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-UI" "1" "July 2021" "hledger-ui-1.22 " "hledger User Manuals"
|
||||
.TH "HLEDGER-UI" "1" "August 2021" "hledger-ui-1.22.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@
|
||||
.PP
|
||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||
tool.
|
||||
This manual is for hledger-ui 1.22.
|
||||
This manual is for hledger-ui 1.22.99.
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
\f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
|
||||
|
@ -1,5 +1,4 @@
|
||||
This is hledger-ui/hledger-ui.info, produced by makeinfo version 4.8
|
||||
from stdin.
|
||||
This is hledger-ui.info, produced by makeinfo version 6.8 from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
@ -7,36 +6,36 @@ START-INFO-DIR-ENTRY
|
||||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Top, Up: (dir)
|
||||
File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
|
||||
|
||||
hledger-ui(1)
|
||||
*************
|
||||
|
||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||
tool. This manual is for hledger-ui 1.22.
|
||||
tool. This manual is for hledger-ui 1.22.99.
|
||||
|
||||
`hledger-ui [OPTIONS] [QUERYARGS]'
|
||||
`hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||
'hledger-ui [OPTIONS] [QUERYARGS]'
|
||||
'hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||
|
||||
hledger is a reliable, cross-platform set of programs for tracking
|
||||
money, time, or any other commodity, using double-entry accounting and a
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
compatible with ledger(1).
|
||||
|
||||
hledger-ui is hledger's terminal interface, providing an efficient
|
||||
full-window text UI for viewing accounts and transactions, and some
|
||||
limited data entry capability. It is easier than hledger's command-line
|
||||
limited data entry capability. It is easier than hledger's command-line
|
||||
interface, and sometimes quicker and more convenient than the web
|
||||
interface.
|
||||
|
||||
Like hledger, it reads data from one or more files in hledger
|
||||
journal, timeclock, timedot, or CSV format specified with `-f', or
|
||||
`$LEDGER_FILE', or `$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
|
||||
journal, timeclock, timedot, or CSV format specified with '-f', or
|
||||
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
|
||||
hledger_journal(5) etc.
|
||||
|
||||
Unlike hledger, hledger-ui hides all future-dated transactions by
|
||||
default. They can be revealed, along with any rule-generated periodic
|
||||
default. They can be revealed, along with any rule-generated periodic
|
||||
transactions, by pressing the F key (or starting with -forecast) to
|
||||
enable "forecast mode".
|
||||
|
||||
@ -56,143 +55,146 @@ File: hledger-ui.info, Node: OPTIONS, Next: KEYS, 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.
|
||||
|
||||
`--watch'
|
||||
'--watch'
|
||||
|
||||
watch for data and date changes and reload automatically
|
||||
'--theme=default|terminal|greenterm'
|
||||
|
||||
`--theme=default|terminal|greenterm'
|
||||
use this custom display theme
|
||||
'--register=ACCTREGEX'
|
||||
|
||||
`--register=ACCTREGEX'
|
||||
start in the (first) matched account's register screen
|
||||
'--change'
|
||||
|
||||
`--change'
|
||||
show period balances (changes) at startup instead of historical
|
||||
balances
|
||||
'-l --flat'
|
||||
|
||||
`-l --flat'
|
||||
show accounts as a flat list (default)
|
||||
'-t --tree'
|
||||
|
||||
`-t --tree'
|
||||
show accounts as a tree
|
||||
|
||||
hledger input options:
|
||||
|
||||
`-f FILE --file=FILE'
|
||||
use a different input file. For stdin, use - (default:
|
||||
`$LEDGER_FILE' or `$HOME/.hledger.journal')
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
|
||||
`--rules-file=RULESFILE'
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
'--separator=CHAR'
|
||||
|
||||
`--separator=CHAR'
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
`--alias=OLD=NEW'
|
||||
rename accounts named OLD to NEW
|
||||
'--anon'
|
||||
|
||||
`--anon'
|
||||
anonymize accounts and payees
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
`--pivot FIELDNAME'
|
||||
use some other field or tag for the account name
|
||||
'-I --ignore-assertions'
|
||||
|
||||
`-I --ignore-assertions'
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
'-s --strict'
|
||||
|
||||
`-s --strict'
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
`-b --begin=DATE'
|
||||
'-b --begin=DATE'
|
||||
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
'-e --end=DATE'
|
||||
|
||||
`-e --end=DATE'
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
'-D --daily'
|
||||
|
||||
`-D --daily'
|
||||
multiperiod/multicolumn report by day
|
||||
'-W --weekly'
|
||||
|
||||
`-W --weekly'
|
||||
multiperiod/multicolumn report by week
|
||||
'-M --monthly'
|
||||
|
||||
`-M --monthly'
|
||||
multiperiod/multicolumn report by month
|
||||
'-Q --quarterly'
|
||||
|
||||
`-Q --quarterly'
|
||||
multiperiod/multicolumn report by quarter
|
||||
'-Y --yearly'
|
||||
|
||||
`-Y --yearly'
|
||||
multiperiod/multicolumn report by year
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
`-p --period=PERIODEXP'
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
'--date2'
|
||||
|
||||
`--date2'
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
'-U --unmarked'
|
||||
|
||||
`-U --unmarked'
|
||||
include only unmarked postings/txns (can combine with -P or -C)
|
||||
'-P --pending'
|
||||
|
||||
`-P --pending'
|
||||
include only pending postings/txns
|
||||
'-C --cleared'
|
||||
|
||||
`-C --cleared'
|
||||
include only cleared postings/txns
|
||||
'-R --real'
|
||||
|
||||
`-R --real'
|
||||
include only non-virtual postings
|
||||
'-NUM --depth=NUM'
|
||||
|
||||
`-NUM --depth=NUM'
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
'-E --empty'
|
||||
|
||||
`-E --empty'
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
'-B --cost'
|
||||
|
||||
`-B --cost'
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
'-V --market'
|
||||
|
||||
`-V --market'
|
||||
convert amounts to their market value in default valuation
|
||||
commodities
|
||||
'-X --exchange=COMM'
|
||||
|
||||
`-X --exchange=COMM'
|
||||
convert amounts to their market value in commodity COMM
|
||||
'--value'
|
||||
|
||||
`--value'
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
'--infer-market-prices'
|
||||
|
||||
`--infer-market-prices'
|
||||
use transaction prices (recorded with @ or @@) as additional market
|
||||
prices, as if they were P directives
|
||||
'--auto'
|
||||
|
||||
`--auto'
|
||||
apply automated posting rules to modify transactions.
|
||||
'--forecast'
|
||||
|
||||
`--forecast'
|
||||
generate future transactions from periodic transaction rules, for
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
make ordinary future transactions visible.
|
||||
'--color=WHEN (or --colour=WHEN)'
|
||||
|
||||
`--color=WHEN (or --colour=WHEN)'
|
||||
Should color-supporting commands use ANSI color codes in text
|
||||
output. 'auto' (default): whenever stdout seems to be a
|
||||
color-supporting terminal. 'always' or 'yes': always, useful eg
|
||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||
NO_COLOR environment variable overrides this.
|
||||
|
||||
When a reporting option appears more than once in the command line,
|
||||
@ -202,24 +204,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.)
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a '--' argument before.)
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top
|
||||
@ -227,89 +230,89 @@ File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top
|
||||
2 KEYS
|
||||
******
|
||||
|
||||
`?' 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'/`page up'/`page
|
||||
down'/`home'/`end' move up and down through lists. Emacs-style
|
||||
(`ctrl-p'/`ctrl-n'/`ctrl-f'/`ctrl-b') movement keys are also supported
|
||||
The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left'
|
||||
returns to the previous screen, 'up'/'down'/'page up'/'page
|
||||
down'/'home'/'end' move up and down through lists. Emacs-style
|
||||
('ctrl-p'/'ctrl-n'/'ctrl-f'/'ctrl-b') movement keys are also supported
|
||||
(but not vi-style keys, since hledger-1.19, sorry!). A tip: movement
|
||||
speed is limited by your keyboard repeat rate, to move faster you may
|
||||
want to adjust it. (If you're on a mac, the karabiner app is one way to
|
||||
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 `--watch' option, when viewing a
|
||||
'shift-down/up' steps downward and upward through these standard report
|
||||
period durations: year, quarter, month, week, day. Then,
|
||||
'shift-left/right' moves to the previous/next period. 'T' sets the
|
||||
report period to today. With the '--watch' option, when viewing a
|
||||
"current" period (the current day, week, month, quarter, or year), the
|
||||
period will move automatically to track the current date. To set a
|
||||
non-standard period, you can use `/' and a `date:' query.
|
||||
period will move automatically to track the current date. To set a
|
||||
non-standard period, you can use '/' and a 'date:' query.
|
||||
|
||||
`/' lets you set a general filter query limiting the data shown,
|
||||
using the same query terms as in hledger and hledger-web. While editing
|
||||
the query, you can use CTRL-a/e/d/k, BS, cursor keys; press `ENTER' to
|
||||
set it, or `ESCAPE'to cancel. There are also keys for quickly adjusting
|
||||
'/' lets you set a general filter query limiting the data shown,
|
||||
using the same query terms as in hledger and hledger-web. While editing
|
||||
the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to
|
||||
set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting
|
||||
some common filters like account depth and transaction status (see
|
||||
below). `BACKSPACE' or `DELETE' removes all filters, showing all
|
||||
below). 'BACKSPACE' or 'DELETE' removes all filters, showing all
|
||||
transactions.
|
||||
|
||||
As mentioned above, by default hledger-ui hides future transactions -
|
||||
both ordinary transactions recorded in the journal, and periodic
|
||||
transactions generated by rule. `F' toggles forecast mode, in which
|
||||
transactions generated by rule. 'F' toggles forecast mode, in which
|
||||
future/forecasted transactions are shown.
|
||||
|
||||
`ESCAPE' resets the UI state and jumps back to the top screen,
|
||||
restoring the app's initial state at startup. Or, it cancels minibuffer
|
||||
'ESCAPE' resets the UI state and jumps back to the top screen,
|
||||
restoring the app's initial state at startup. Or, it cancels minibuffer
|
||||
data entry or the help dialog.
|
||||
|
||||
`CTRL-l' redraws the screen and centers the selection if possible
|
||||
'CTRL-l' redraws the screen and centers the selection if possible
|
||||
(selections near the top won't be centered, since we don't scroll above
|
||||
the top).
|
||||
|
||||
`g' reloads from the data file(s) and updates the current screen and
|
||||
any previous screens. (With large files, this could cause a noticeable
|
||||
'g' reloads from the data file(s) and updates the current screen and
|
||||
any previous screens. (With large files, this could cause a noticeable
|
||||
pause.)
|
||||
|
||||
`I' toggles balance assertion checking. Disabling balance assertions
|
||||
'I' toggles balance assertion checking. Disabling balance assertions
|
||||
temporarily can be useful for troubleshooting.
|
||||
|
||||
`a' runs command-line hledger's add command, and reloads the updated
|
||||
file. This allows some basic data entry.
|
||||
'a' runs command-line hledger's add command, and reloads the updated
|
||||
file. This allows some basic data entry.
|
||||
|
||||
`A' is like `a', but runs the hledger-iadd tool, which provides a
|
||||
terminal interface. This key will be available if `hledger-iadd' is
|
||||
'A' is like 'a', but runs the hledger-iadd tool, which provides a
|
||||
terminal interface. This key will be available if 'hledger-iadd' is
|
||||
installed in $path.
|
||||
|
||||
`E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (`emacsclient
|
||||
-a "" -nw') on the journal file. With some editors (emacs, vi), the
|
||||
'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient
|
||||
-a "" -nw') on the journal file. With some editors (emacs, vi), the
|
||||
cursor will be positioned at the current transaction when invoked from
|
||||
the register and transaction screens, and at the error location (if
|
||||
possible) when invoked from the error screen.
|
||||
|
||||
`B' toggles cost mode, showing amounts in their transaction price's
|
||||
commodity (like toggling the `-B/--cost' flag).
|
||||
'B' toggles cost mode, showing amounts in their transaction price's
|
||||
commodity (like toggling the '-B/--cost' flag).
|
||||
|
||||
`V' toggles value mode, showing amounts' current market value in
|
||||
their default valuation commodity (like toggling the `-V/--market'
|
||||
flag). Note, "current market value" means the value on the report end
|
||||
date if specified, otherwise today. To see the value on another date,
|
||||
you can temporarily set that as the report end date. Eg: to see a
|
||||
'V' toggles value mode, showing amounts' current market value in
|
||||
their default valuation commodity (like toggling the '-V/--market'
|
||||
flag). Note, "current market value" means the value on the report end
|
||||
date if specified, otherwise today. To see the value on another date,
|
||||
you can temporarily set that as the report end date. Eg: to see a
|
||||
transaction as it was valued on july 30, go to the accounts or register
|
||||
screen, press `/', and add `date:-7/30' to the query.
|
||||
screen, press '/', and add 'date:-7/30' to the query.
|
||||
|
||||
At most one of cost or value mode can be active at once.
|
||||
|
||||
There's not yet any visual reminder when cost or value mode is
|
||||
active; for now pressing `b' `b' `v' should reliably reset to normal
|
||||
active; for now pressing 'b' 'b' 'v' should reliably reset to normal
|
||||
mode.
|
||||
|
||||
`q' quits the application.
|
||||
'q' quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
@ -332,47 +335,48 @@ File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCRE
|
||||
3.1 Accounts screen
|
||||
===================
|
||||
|
||||
This is normally the first screen displayed. It lists accounts and their
|
||||
balances, like hledger's balance command. By default, it shows all
|
||||
accounts and their latest ending balances (including the balances of
|
||||
subaccounts). If you specify a query on the command line, it shows just
|
||||
This is normally the first screen displayed. It lists accounts and
|
||||
their balances, like hledger's balance command. By default, it shows
|
||||
all accounts and their latest ending balances (including the balances of
|
||||
subaccounts). If you specify a query on the command line, it shows just
|
||||
the matched accounts and the balances from matched transactions.
|
||||
|
||||
Account names are shown as a flat list by default; press `t' to
|
||||
toggle tree mode. In list mode, account balances are exclusive of
|
||||
Account names are shown as a flat list by default; press 't' to
|
||||
toggle tree mode. In list mode, account balances are exclusive of
|
||||
subaccounts, except where subaccounts are hidden by a depth limit (see
|
||||
below). In tree mode, all account balances are inclusive of subaccounts.
|
||||
below). In tree mode, all account balances are inclusive of
|
||||
subaccounts.
|
||||
|
||||
To see less detail, press a number key, `1' to `9', to set a depth
|
||||
limit. Or use `-' to decrease and `+'/`=' to increase the depth limit.
|
||||
`0' shows even less detail, collapsing all accounts to a single total.
|
||||
To remove the depth limit, set it higher than the maximum account
|
||||
depth, or press `ESCAPE'.
|
||||
To see less detail, press a number key, '1' to '9', to set a depth
|
||||
limit. Or use '-' to decrease and '+'/'=' to increase the depth limit.
|
||||
'0' shows even less detail, collapsing all accounts to a single total.
|
||||
To remove the depth limit, set it higher than the maximum account depth,
|
||||
or press 'ESCAPE'.
|
||||
|
||||
`H' toggles between showing historical balances or period balances.
|
||||
'H' toggles between showing historical balances or period balances.
|
||||
Historical balances (the default) are ending balances at the end of the
|
||||
report period, taking into account all transactions before that date
|
||||
(filtered by the filter query if any), including transactions before the
|
||||
start of the report period. In other words, historical balances are what
|
||||
you would see on a bank statement for that account (unless disturbed by
|
||||
a filter query). Period balances ignore transactions before the report
|
||||
start date, so they show the change in balance during the report period.
|
||||
They are more useful eg when viewing a time log.
|
||||
start of the report period. In other words, historical balances are
|
||||
what you would see on a bank statement for that account (unless
|
||||
disturbed by a filter query). Period balances ignore transactions
|
||||
before the report start date, so they show the change in balance during
|
||||
the report period. They are more useful eg when viewing a time log.
|
||||
|
||||
`U' toggles filtering by unmarked status, including or excluding
|
||||
unmarked postings in the balances. Similarly, `P' toggles pending
|
||||
postings, and `C' toggles cleared postings. (By default, balances
|
||||
'U' toggles filtering by unmarked status, including or excluding
|
||||
unmarked postings in the balances. Similarly, 'P' toggles pending
|
||||
postings, and 'C' toggles cleared postings. (By default, balances
|
||||
include all postings; if you activate one or two status filters, only
|
||||
those postings are included; and if you activate all three, the filter
|
||||
is removed.)
|
||||
|
||||
`R' toggles real mode, in which virtual postings are ignored.
|
||||
'R' toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
`Z' toggles nonzero mode, in which only accounts with nonzero
|
||||
'Z' toggles nonzero mode, in which only accounts with nonzero
|
||||
balances are shown (hledger-ui shows zero items by default, unlike
|
||||
command-line hledger).
|
||||
|
||||
Press `right' or `enter' to view an account's transactions register.
|
||||
Press 'right' or 'enter' to view an account's transactions register.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS
|
||||
@ -381,46 +385,44 @@ File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev:
|
||||
===================
|
||||
|
||||
This screen shows the transactions affecting a particular account, like
|
||||
a check register. Each line represents one transaction and shows:
|
||||
a check register. Each line represents one transaction and shows:
|
||||
|
||||
* the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts
|
||||
affected by real postings.)
|
||||
* the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
by real postings.)
|
||||
|
||||
* the overall change to the current account's balance; positive for
|
||||
an inflow to this account, negative for an outflow.
|
||||
|
||||
* the running historical total or period total for the current
|
||||
account, after the transaction. This can be toggled with `H'.
|
||||
Similar to the accounts screen, the historical total is affected
|
||||
by transactions (filtered by the filter query) before the report
|
||||
start date, while the period total is not. If the historical total
|
||||
is not disturbed by a filter query, it will be the running
|
||||
historical balance you would see on a bank register for the
|
||||
current account.
|
||||
|
||||
account, after the transaction. This can be toggled with 'H'.
|
||||
Similar to the accounts screen, the historical total is affected by
|
||||
transactions (filtered by the filter query) before the report start
|
||||
date, while the period total is not. If the historical total is
|
||||
not disturbed by a filter query, it will be the running historical
|
||||
balance you would see on a bank register for the current account.
|
||||
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
the register if the accounts screen is in tree mode, or if it's in list
|
||||
mode but this account has subaccounts which are not shown due to a depth
|
||||
limit. In other words, the register always shows the transactions
|
||||
contributing to the balance shown on the accounts screen. Tree mode/list
|
||||
mode can be toggled with `t' here also.
|
||||
limit. In other words, the register always shows the transactions
|
||||
contributing to the balance shown on the accounts screen. Tree
|
||||
mode/list mode can be toggled with 't' here also.
|
||||
|
||||
`U' toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, `P' toggles pending transactions, and `C'
|
||||
toggles cleared transactions. (By default, transactions with all
|
||||
'U' toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, 'P' toggles pending transactions, and 'C'
|
||||
toggles cleared transactions. (By default, transactions with all
|
||||
statuses are shown; if you activate one or two status filters, only
|
||||
those transactions are shown; and if you activate all three, the filter
|
||||
is removed.)
|
||||
|
||||
`R' toggles real mode, in which virtual postings are ignored.
|
||||
'R' toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
`Z' toggles nonzero mode, in which only transactions posting a
|
||||
'Z' toggles nonzero mode, in which only transactions posting a
|
||||
nonzero change are shown (hledger-ui shows zero items by default, unlike
|
||||
command-line hledger).
|
||||
|
||||
Press `right' (or `enter') to view the selected transaction in
|
||||
Press 'right' (or 'enter') to view the selected transaction in
|
||||
detail.
|
||||
|
||||
|
||||
@ -438,11 +440,11 @@ description, comments, along with all of its account postings are shown.
|
||||
Simple transactions have two postings, but there can be more (or in
|
||||
certain cases, fewer).
|
||||
|
||||
`up' and `down' will step through all transactions listed in the
|
||||
previous account register screen. In the title bar, the numbers in
|
||||
parentheses show your position within that account register. They will
|
||||
'up' and 'down' will step through all transactions listed in the
|
||||
previous account register screen. In the title bar, the numbers in
|
||||
parentheses show your position within that account register. They will
|
||||
vary depending on which account register you came from (remember most
|
||||
transactions appear in multiple account registers). The #N number
|
||||
transactions appear in multiple account registers). The #N number
|
||||
preceding them is the transaction's position within the complete
|
||||
unfiltered journal, which is a more stable id (at least until the next
|
||||
reload).
|
||||
@ -454,8 +456,8 @@ File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCRE
|
||||
================
|
||||
|
||||
This screen will appear if there is a problem, such as a parse error,
|
||||
when you press g to reload. Once you have fixed the problem, press g
|
||||
again to reload and resume normal operation. (Or, you can press escape
|
||||
when you press g to reload. Once you have fixed the problem, press g
|
||||
again to reload and resume normal operation. (Or, you can press escape
|
||||
to cancel the reload attempt.)
|
||||
|
||||
|
||||
@ -475,21 +477,20 @@ File: hledger-ui.info, Node: Watch mode, Next: Watch mode limitations, Up: TI
|
||||
4.1 Watch mode
|
||||
==============
|
||||
|
||||
One of hledger-ui's best features is the auto-reloading `--watch' mode.
|
||||
One of hledger-ui's best features is the auto-reloading '--watch' mode.
|
||||
With this flag, it will update the display automatically whenever
|
||||
changes are saved to the data files.
|
||||
|
||||
This is very useful when reconciling. A good workflow is to have your
|
||||
bank's online register open in a browser window, for reference; the
|
||||
This is very useful when reconciling. A good workflow is to have
|
||||
your bank's online register open in a browser window, for reference; the
|
||||
journal file open in an editor window; and hledger-ui in watch mode in a
|
||||
terminal window, eg:
|
||||
|
||||
|
||||
$ hledger-ui --watch --register checking -C
|
||||
|
||||
As you mark things cleared in the editor, you can see the effect
|
||||
immediately without having to context switch. This leaves more mental
|
||||
bandwidth for your accounting. Of course you can still interact with
|
||||
immediately without having to context switch. This leaves more mental
|
||||
bandwidth for your accounting. Of course you can still interact with
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
history.
|
||||
|
||||
@ -500,29 +501,28 @@ File: hledger-ui.info, Node: Watch mode limitations, Prev: Watch mode, Up: TI
|
||||
==========================
|
||||
|
||||
There are situations in which it won't work, ie the display will not
|
||||
update when you save a change (because the underlying `inotify' library
|
||||
does not support it). Here are some that we know of:
|
||||
update when you save a change (because the underlying 'inotify' library
|
||||
does not support it). Here are some that we know of:
|
||||
|
||||
* Certain editors: saving with `gedit', and perhaps any Gnome
|
||||
application, won't be detected (#1617). Jetbrains IDEs, such as
|
||||
* Certain editors: saving with 'gedit', and perhaps any Gnome
|
||||
application, won't be detected (#1617). Jetbrains IDEs, such as
|
||||
IDEA, also may not work (#911).
|
||||
|
||||
* Certain unusual filesystems might not be supported. (All the usual
|
||||
* Certain unusual filesystems might not be supported. (All the usual
|
||||
ones on unix, mac and windows are supported.)
|
||||
|
||||
|
||||
In such cases, the workaround is to switch to the hledger-ui window
|
||||
and press `g' each time you want it to reload. (Actually, see #1617 for
|
||||
and press 'g' each time you want it to reload. (Actually, see #1617 for
|
||||
another workaround, and let us know if it works for you.)
|
||||
|
||||
If you leave `hledger-ui --watch' running for days, on certain
|
||||
If you leave 'hledger-ui --watch' running for days, on certain
|
||||
platforms (?), perhaps with many transactions in your journal (?),
|
||||
perhaps with large numbers of other files present (?), you may see it
|
||||
gradually using more and more memory and CPU over time, as seen in
|
||||
`top' or Activity Monitor or Task Manager.
|
||||
gradually using more and more memory and CPU over time, as seen in 'top'
|
||||
or Activity Monitor or Task Manager.
|
||||
|
||||
A workaround is to `q'uit and restart it, or to suspend it
|
||||
(`CTRL-z') and restart it (`fg') if your shell supports that.
|
||||
A workaround is to 'q'uit and restart it, or to suspend it ('CTRL-z')
|
||||
and restart it ('fg') if your shell supports that.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
|
||||
@ -530,28 +530,27 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
|
||||
5 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*COLUMNS* The screen width to use. Default: the full terminal width.
|
||||
*COLUMNS* The screen width to use. Default: the full terminal width.
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with `-f'.
|
||||
Default: `~/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
Default: '~/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
|
||||
A typical value is `~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
`~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
A typical value is '~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
'~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
YYYY.journal.
|
||||
|
||||
On Mac computers, you can set this and other environment variables
|
||||
in a more thorough way that also affects applications started from the
|
||||
GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
`~/.MacOSX/environment.plist' file containing
|
||||
|
||||
On Mac computers, you can set this and other environment variables in
|
||||
a more thorough way that also affects applications started from the GUI
|
||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
'~/.MacOSX/environment.plist' file containing
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
To see the effect you may need to `killall Dock', or reboot.
|
||||
To see the effect you may need to 'killall Dock', or reboot.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
@ -560,9 +559,9 @@ File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
*******
|
||||
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
|
||||
`$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or
|
||||
'$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -570,18 +569,18 @@ File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
7 BUGS
|
||||
******
|
||||
|
||||
The need to precede options with `--' when invoked from hledger is
|
||||
The need to precede options with '--' when invoked from hledger is
|
||||
awkward.
|
||||
|
||||
`-f-' doesn't work (hledger-ui can't read from stdin).
|
||||
'-f-' doesn't work (hledger-ui can't read from stdin).
|
||||
|
||||
`-V' affects only the accounts screen.
|
||||
'-V' affects only the accounts screen.
|
||||
|
||||
When you press `g', the current and all previous screens are
|
||||
regenerated, which may cause a noticeable pause with large files. Also
|
||||
When you press 'g', the current and all previous screens are
|
||||
regenerated, which may cause a noticeable pause with large files. Also
|
||||
there is no visual indication that this is in progress.
|
||||
|
||||
`--watch' is not yet fully robust. It works well for normal usage,
|
||||
'--watch' is not yet fully robust. It works well for normal usage,
|
||||
but many file changes in a short time (eg saving the file thousands of
|
||||
times with an editor macro) can cause problems at least on OSX. Symptoms
|
||||
include: unresponsive UI, periodic resetting of the cursor position,
|
||||
@ -590,37 +589,41 @@ 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,
|
||||
`--watch' requires that both machine clocks are roughly in step.
|
||||
|
||||
'--watch' requires that both machine clocks are roughly in step.
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top232
|
||||
Node: OPTIONS1634
|
||||
Ref: #options1731
|
||||
Node: KEYS6126
|
||||
Ref: #keys6221
|
||||
Node: SCREENS10270
|
||||
Ref: #screens10368
|
||||
Node: Accounts screen10458
|
||||
Ref: #accounts-screen10586
|
||||
Node: Register screen12790
|
||||
Ref: #register-screen12945
|
||||
Node: Transaction screen14940
|
||||
Ref: #transaction-screen15098
|
||||
Node: Error screen15965
|
||||
Ref: #error-screen16087
|
||||
Node: TIPS16329
|
||||
Ref: #tips16428
|
||||
Node: Watch mode16480
|
||||
Ref: #watch-mode16597
|
||||
Node: Watch mode limitations17341
|
||||
Ref: #watch-mode-limitations17482
|
||||
Node: ENVIRONMENT18615
|
||||
Ref: #environment18726
|
||||
Node: FILES19531
|
||||
Ref: #files19630
|
||||
Node: BUGS19843
|
||||
Ref: #bugs19920
|
||||
Node: Top221
|
||||
Node: OPTIONS1647
|
||||
Ref: #options1744
|
||||
Node: KEYS6145
|
||||
Ref: #keys6240
|
||||
Node: SCREENS10311
|
||||
Ref: #screens10409
|
||||
Node: Accounts screen10499
|
||||
Ref: #accounts-screen10627
|
||||
Node: Register screen12842
|
||||
Ref: #register-screen12997
|
||||
Node: Transaction screen14994
|
||||
Ref: #transaction-screen15152
|
||||
Node: Error screen16022
|
||||
Ref: #error-screen16144
|
||||
Node: TIPS16388
|
||||
Ref: #tips16487
|
||||
Node: Watch mode16539
|
||||
Ref: #watch-mode16656
|
||||
Node: Watch mode limitations17402
|
||||
Ref: #watch-mode-limitations17543
|
||||
Node: ENVIRONMENT18679
|
||||
Ref: #environment18790
|
||||
Node: FILES19597
|
||||
Ref: #files19696
|
||||
Node: BUGS19909
|
||||
Ref: #bugs19986
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
Local Variables:
|
||||
coding: utf-8
|
||||
End:
|
||||
|
@ -5,7 +5,7 @@ HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1)
|
||||
|
||||
NAME
|
||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||
tool. This manual is for hledger-ui 1.22.
|
||||
tool. This manual is for hledger-ui 1.22.99.
|
||||
|
||||
SYNOPSIS
|
||||
hledger-ui [OPTIONS] [QUERYARGS]
|
||||
@ -504,4 +504,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-ui-1.22 July 2021 HLEDGER-UI(1)
|
||||
hledger-ui-1.22.99 August 2021 HLEDGER-UI(1)
|
||||
|
@ -1,12 +1,12 @@
|
||||
|
||||
.TH "HLEDGER-WEB" "1" "July 2021" "hledger-web-1.22 " "hledger User Manuals"
|
||||
.TH "HLEDGER-WEB" "1" "August 2021" "hledger-web-1.22.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
.SH NAME
|
||||
.PP
|
||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||
This manual is for hledger-web 1.22.
|
||||
This manual is for hledger-web 1.22.99.
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
\f[C]hledger-web [OPTIONS]\f[R]
|
||||
|
@ -1,5 +1,4 @@
|
||||
This is hledger-web/hledger-web.info, produced by makeinfo version 4.8
|
||||
from stdin.
|
||||
This is hledger-web.info, produced by makeinfo version 6.8 from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
@ -7,39 +6,40 @@ START-INFO-DIR-ENTRY
|
||||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
File: hledger-web.info, Node: Top, Up: (dir)
|
||||
File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
|
||||
|
||||
hledger-web(1)
|
||||
**************
|
||||
|
||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||
This manual is for hledger-web 1.22.
|
||||
This manual is for hledger-web 1.22.99.
|
||||
|
||||
`hledger-web [OPTIONS]'
|
||||
`hledger web -- [OPTIONS]'
|
||||
'hledger-web [OPTIONS]'
|
||||
'hledger web -- [OPTIONS]'
|
||||
|
||||
hledger is a reliable, cross-platform set of programs for tracking
|
||||
money, time, or any other commodity, using double-entry accounting and a
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
simple, editable file format. hledger is inspired by and largely
|
||||
compatible with ledger(1).
|
||||
|
||||
hledger-web is hledger's web interface. It starts a simple web
|
||||
hledger-web is hledger's web interface. It starts a simple web
|
||||
application for browsing and adding transactions, and optionally opens
|
||||
it in a web browser window if possible. It provides a more user-friendly
|
||||
UI than the hledger CLI or hledger-ui interface, showing more at once
|
||||
(accounts, the current account register, balance charts) and allowing
|
||||
history-aware data entry, interactive searching, and bookmarking.
|
||||
it in a web browser window if possible. It provides a more
|
||||
user-friendly UI than the hledger CLI or hledger-ui interface, showing
|
||||
more at once (accounts, the current account register, balance charts)
|
||||
and allowing history-aware data entry, interactive searching, and
|
||||
bookmarking.
|
||||
|
||||
hledger-web also lets you share a ledger with multiple users, or even
|
||||
the public web. There is no access control, so if you need that you
|
||||
should put it behind a suitable web proxy. As a small protection against
|
||||
data loss when running an unprotected instance, it writes a numbered
|
||||
backup of the main journal file (only ?) on every edit.
|
||||
the public web. There is no access control, so if you need that you
|
||||
should put it behind a suitable web proxy. As a small protection
|
||||
against data loss when running an unprotected instance, it writes a
|
||||
numbered backup of the main journal file (only ?) on every edit.
|
||||
|
||||
Like hledger, it reads data from one or more files in hledger
|
||||
journal, timeclock, timedot, or CSV format specified with `-f', or
|
||||
`$LEDGER_FILE', or `$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal'). For more about this see hledger(1).
|
||||
journal, timeclock, timedot, or CSV format specified with '-f', or
|
||||
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1).
|
||||
|
||||
* Menu:
|
||||
|
||||
@ -59,165 +59,168 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
|
||||
*********
|
||||
|
||||
Command-line options and arguments may be used to set an initial filter
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
will be applied in addition to any search query entered there.
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write `--'
|
||||
Note: if invoking hledger-web as a hledger subcommand, write '--'
|
||||
before options, as shown in the synopsis above.
|
||||
|
||||
`--serve'
|
||||
serve and log requests, don't browse or auto-exit
|
||||
'--serve'
|
||||
|
||||
serve and log requests, don't browse or auto-exit
|
||||
'--serve-api'
|
||||
|
||||
`--serve-api'
|
||||
like -serve, but serve only the JSON web API, without the
|
||||
server-side web UI
|
||||
'--host=IPADDR'
|
||||
|
||||
`--host=IPADDR'
|
||||
listen on this IP address (default: 127.0.0.1)
|
||||
'--port=PORT'
|
||||
|
||||
`--port=PORT'
|
||||
listen on this TCP port (default: 5000)
|
||||
'--socket=SOCKETFILE'
|
||||
|
||||
`--socket=SOCKETFILE'
|
||||
use a unix domain socket file to listen for requests instead of a
|
||||
TCP socket. Implies `--serve'. It can only be used if the operating
|
||||
system can provide this type of socket.
|
||||
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
|
||||
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.
|
||||
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
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
follow a -, eg: hledger-web -test - -help
|
||||
|
||||
hledger input options:
|
||||
|
||||
`-f FILE --file=FILE'
|
||||
use a different input file. For stdin, use - (default:
|
||||
`$LEDGER_FILE' or `$HOME/.hledger.journal')
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
|
||||
`--rules-file=RULESFILE'
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
'--separator=CHAR'
|
||||
|
||||
`--separator=CHAR'
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
`--alias=OLD=NEW'
|
||||
rename accounts named OLD to NEW
|
||||
'--anon'
|
||||
|
||||
`--anon'
|
||||
anonymize accounts and payees
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
`--pivot FIELDNAME'
|
||||
use some other field or tag for the account name
|
||||
'-I --ignore-assertions'
|
||||
|
||||
`-I --ignore-assertions'
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
'-s --strict'
|
||||
|
||||
`-s --strict'
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
`-b --begin=DATE'
|
||||
'-b --begin=DATE'
|
||||
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
'-e --end=DATE'
|
||||
|
||||
`-e --end=DATE'
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
'-D --daily'
|
||||
|
||||
`-D --daily'
|
||||
multiperiod/multicolumn report by day
|
||||
'-W --weekly'
|
||||
|
||||
`-W --weekly'
|
||||
multiperiod/multicolumn report by week
|
||||
'-M --monthly'
|
||||
|
||||
`-M --monthly'
|
||||
multiperiod/multicolumn report by month
|
||||
'-Q --quarterly'
|
||||
|
||||
`-Q --quarterly'
|
||||
multiperiod/multicolumn report by quarter
|
||||
'-Y --yearly'
|
||||
|
||||
`-Y --yearly'
|
||||
multiperiod/multicolumn report by year
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
`-p --period=PERIODEXP'
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
'--date2'
|
||||
|
||||
`--date2'
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
'-U --unmarked'
|
||||
|
||||
`-U --unmarked'
|
||||
include only unmarked postings/txns (can combine with -P or -C)
|
||||
'-P --pending'
|
||||
|
||||
`-P --pending'
|
||||
include only pending postings/txns
|
||||
'-C --cleared'
|
||||
|
||||
`-C --cleared'
|
||||
include only cleared postings/txns
|
||||
'-R --real'
|
||||
|
||||
`-R --real'
|
||||
include only non-virtual postings
|
||||
'-NUM --depth=NUM'
|
||||
|
||||
`-NUM --depth=NUM'
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
'-E --empty'
|
||||
|
||||
`-E --empty'
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
'-B --cost'
|
||||
|
||||
`-B --cost'
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
'-V --market'
|
||||
|
||||
`-V --market'
|
||||
convert amounts to their market value in default valuation
|
||||
commodities
|
||||
'-X --exchange=COMM'
|
||||
|
||||
`-X --exchange=COMM'
|
||||
convert amounts to their market value in commodity COMM
|
||||
'--value'
|
||||
|
||||
`--value'
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
'--infer-market-prices'
|
||||
|
||||
`--infer-market-prices'
|
||||
use transaction prices (recorded with @ or @@) as additional market
|
||||
prices, as if they were P directives
|
||||
'--auto'
|
||||
|
||||
`--auto'
|
||||
apply automated posting rules to modify transactions.
|
||||
'--forecast'
|
||||
|
||||
`--forecast'
|
||||
generate future transactions from periodic transaction rules, for
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
make ordinary future transactions visible.
|
||||
'--color=WHEN (or --colour=WHEN)'
|
||||
|
||||
`--color=WHEN (or --colour=WHEN)'
|
||||
Should color-supporting commands use ANSI color codes in text
|
||||
output. 'auto' (default): whenever stdout seems to be a
|
||||
color-supporting terminal. 'always' or 'yes': always, useful eg
|
||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||
NO_COLOR environment variable overrides this.
|
||||
|
||||
When a reporting option appears more than once in the command line,
|
||||
@ -227,62 +230,62 @@ the last one takes precedence.
|
||||
|
||||
hledger help options:
|
||||
|
||||
`-h --help'
|
||||
'-h --help'
|
||||
|
||||
show general or COMMAND help
|
||||
'--man'
|
||||
|
||||
`--man'
|
||||
show general or COMMAND user manual with man
|
||||
'--info'
|
||||
|
||||
`--info'
|
||||
show general or COMMAND user manual with info
|
||||
'--version'
|
||||
|
||||
`--version'
|
||||
show general or ADDONCMD version
|
||||
'--debug[=N]'
|
||||
|
||||
`--debug[=N]'
|
||||
show debug output (levels 1-9, default: 1)
|
||||
|
||||
A @FILE argument will be expanded to the contents of FILE, which
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a `--' argument before.)
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a '--' argument before.)
|
||||
|
||||
By default, hledger-web starts the web app in "transient mode" and
|
||||
also opens it in your default web browser if possible. In this mode the
|
||||
also opens it in your default web browser if possible. In this mode the
|
||||
web app will keep running for as long as you have it open in a browser
|
||||
window, and will exit after two minutes of inactivity (no requests and
|
||||
no browser windows viewing it). With `--serve', it just runs the web
|
||||
app without exiting, and logs requests to the console. With
|
||||
`--serve-api', only the JSON web api (see below) is served, with the
|
||||
no browser windows viewing it). With '--serve', it just runs the web
|
||||
app without exiting, and logs requests to the console. With
|
||||
'--serve-api', only the JSON web api (see below) is served, with the
|
||||
usual HTML server-side web UI disabled.
|
||||
|
||||
By default the server listens on IP address 127.0.0.1, accessible
|
||||
only to local requests. You can use `--host' to change this, eg `--host
|
||||
only to local requests. You can use '--host' to change this, eg '--host
|
||||
0.0.0.0' to listen on all configured addresses.
|
||||
|
||||
Similarly, use `--port' to set a TCP port other than 5000, eg if you
|
||||
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
||||
are running multiple hledger-web instances.
|
||||
|
||||
Both of these options are ignored when `--socket' is used. In this
|
||||
case, it creates an `AF_UNIX' socket file at the supplied path and uses
|
||||
that for communication. This is an alternative way of running multiple
|
||||
hledger-web instances behind a reverse proxy that handles
|
||||
authentication for different users. The path can be derived in a
|
||||
predictable way, eg by using the username within the path. As an
|
||||
example, `nginx' as reverse proxy can use the variable `$remote_user'
|
||||
to derive a path from the username used in a HTTP basic authentication.
|
||||
The following `proxy_pass' directive allows access to all `hledger-web'
|
||||
instances that created a socket in `/tmp/hledger/':
|
||||
|
||||
Both of these options are ignored when '--socket' is used. In this
|
||||
case, it creates an 'AF_UNIX' socket file at the supplied path and uses
|
||||
that for communication. This is an alternative way of running multiple
|
||||
hledger-web instances behind a reverse proxy that handles authentication
|
||||
for different users. The path can be derived in a predictable way, eg
|
||||
by using the username within the path. As an example, 'nginx' as
|
||||
reverse proxy can use the variable '$remote_user' to derive a path from
|
||||
the username used in a HTTP basic authentication. The following
|
||||
'proxy_pass' directive allows access to all 'hledger-web' instances that
|
||||
created a socket in '/tmp/hledger/':
|
||||
|
||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||
|
||||
You can use `--base-url' to change the protocol, hostname, port and
|
||||
You can use '--base-url' to change the protocol, hostname, port and
|
||||
path that appear in hyperlinks, useful eg for integrating hledger-web
|
||||
within a larger website. The default is `http://HOST:PORT/' using the
|
||||
server's configured host address and TCP port (or `http://HOST' if PORT
|
||||
within a larger website. The default is 'http://HOST:PORT/' using the
|
||||
server's configured host address and TCP port (or 'http://HOST' if PORT
|
||||
is 80).
|
||||
|
||||
With `--file-url' you can set a different base url for static files,
|
||||
With '--file-url' you can set a different base url for static files,
|
||||
eg for better caching or cookie-less serving on high performance
|
||||
websites.
|
||||
|
||||
@ -297,32 +300,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
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
|
||||
* using the `--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is `view,add':
|
||||
* `view' - allows viewing the journal file and all included
|
||||
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is 'view,add':
|
||||
* 'view' - allows viewing the journal file and all included
|
||||
files
|
||||
|
||||
* `add' - allows adding new transactions to the main journal
|
||||
* 'add' - allows adding new transactions to the main journal
|
||||
file
|
||||
|
||||
* `manage' - allows editing, uploading or downloading the main
|
||||
* 'manage' - allows editing, uploading or downloading the main
|
||||
or included files
|
||||
|
||||
* using the `--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
|
||||
@ -330,8 +329,8 @@ File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING,
|
||||
3 EDITING, UPLOADING, DOWNLOADING
|
||||
*********************************
|
||||
|
||||
If you enable the `manage' capability mentioned above, you'll see a new
|
||||
"spanner" button to the right of the search form. Clicking this will
|
||||
If you enable the 'manage' capability mentioned above, you'll see a new
|
||||
"spanner" button to the right of the search form. Clicking this will
|
||||
let you edit, upload, or download the journal file or any files it
|
||||
includes.
|
||||
|
||||
@ -340,13 +339,13 @@ visitor) can alter or wipe the data files.
|
||||
|
||||
Normally whenever a file is changed in this way, hledger-web saves a
|
||||
numbered backup (assuming file permissions allow it, the disk is not
|
||||
full, etc.) hledger-web is not aware of version control systems,
|
||||
full, etc.) hledger-web is not aware of version control systems,
|
||||
currently; if you use one, you'll have to arrange to commit the changes
|
||||
yourself (eg with a cron job or a file watcher like entr).
|
||||
|
||||
Changes which would leave the journal file(s) unparseable or
|
||||
non-valid (eg with failing balance assertions) are prevented.
|
||||
(Probably. This needs re-testing.)
|
||||
(Probably. This needs re-testing.)
|
||||
|
||||
|
||||
File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOADING DOWNLOADING, Up: Top
|
||||
@ -356,7 +355,7 @@ File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOAD
|
||||
|
||||
hledger-web detects changes made to the files by other means (eg if you
|
||||
edit it directly, outside of hledger-web), and it will show the new data
|
||||
when you reload the page or navigate to a new page. If a change makes a
|
||||
when you reload the page or navigate to a new page. If a change makes a
|
||||
file unparseable, hledger-web will display an error message until the
|
||||
file has been fixed.
|
||||
|
||||
@ -370,16 +369,14 @@ File: hledger-web.info, Node: JSON API, Next: ENVIRONMENT, Prev: RELOADING,
|
||||
**********
|
||||
|
||||
In addition to the web UI, hledger-web also serves a JSON API that can
|
||||
be used to get data or add new transactions. If you want the JSON API
|
||||
only, you can use the `--serve-api' flag. Eg:
|
||||
|
||||
be used to get data or add new transactions. If you want the JSON API
|
||||
only, you can use the '--serve-api' flag. Eg:
|
||||
|
||||
$ hledger-web -f examples/sample.journal --serve-api
|
||||
...
|
||||
|
||||
You can get JSON data from these routes:
|
||||
|
||||
|
||||
/version
|
||||
/accountnames
|
||||
/transactions
|
||||
@ -392,7 +389,6 @@ $ hledger-web -f examples/sample.journal --serve-api
|
||||
command). (hledger-web's JSON does not include newlines, here we use
|
||||
python to prettify it):
|
||||
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||
[
|
||||
"assets",
|
||||
@ -412,7 +408,6 @@ $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||
|
||||
Or all transactions:
|
||||
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
[
|
||||
{
|
||||
@ -434,25 +429,24 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
|
||||
Most of the JSON corresponds to hledger's data types; for details of
|
||||
what the fields mean, see the Hledger.Data.Json haddock docs and click
|
||||
on the various data types, eg Transaction. And for a higher level
|
||||
on the various data types, eg Transaction. And for a higher level
|
||||
understanding, see the journal manual.
|
||||
|
||||
In some cases there is outer JSON corresponding to a "Report" type.
|
||||
To understand that, go to the Hledger.Web.Handler.MiscR haddock and
|
||||
look at the source for the appropriate handler to see what it returns.
|
||||
Eg for `/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"`accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
|
||||
at the source for the appropriate handler to see what it returns. Eg
|
||||
for '/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"'accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
can see that /accounttransactions returns an AccountTransactionsReport,
|
||||
which consists of a report title and a list of
|
||||
AccountTransactionsReportItem (etc).
|
||||
|
||||
You can add a new transaction to the journal with a PUT request to
|
||||
`/add', if hledger-web was started with the `add' capability (enabled
|
||||
by default). The payload must be the full, exact JSON representation of
|
||||
a hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's `/transactions' or `/accounttransactions', or you
|
||||
can export it with hledger-lib, eg like so:
|
||||
|
||||
'/add', if hledger-web was started with the 'add' capability (enabled by
|
||||
default). The payload must be the full, exact JSON representation of a
|
||||
hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's '/transactions' or '/accounttransactions', or you can
|
||||
export it with hledger-lib, eg like so:
|
||||
|
||||
.../hledger$ stack ghci hledger-lib
|
||||
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
|
||||
@ -461,7 +455,6 @@ can export it with hledger-lib, eg like so:
|
||||
Here's how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger's Transaction and related data types):
|
||||
|
||||
|
||||
{
|
||||
"tcomment": "",
|
||||
"tpostings": [
|
||||
@ -548,10 +541,9 @@ 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
|
||||
|
||||
|
||||
@ -560,26 +552,25 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up:
|
||||
6 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with `-f'.
|
||||
Default: `~/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
Default: '~/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
|
||||
A typical value is `~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
`~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
A typical value is '~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
'~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
YYYY.journal.
|
||||
|
||||
On Mac computers, you can set this and other environment variables
|
||||
in a more thorough way that also affects applications started from the
|
||||
GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
`~/.MacOSX/environment.plist' file containing
|
||||
|
||||
On Mac computers, you can set this and other environment variables in
|
||||
a more thorough way that also affects applications started from the GUI
|
||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
'~/.MacOSX/environment.plist' file containing
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
To see the effect you may need to `killall Dock', or reboot.
|
||||
To see the effect you may need to 'killall Dock', or reboot.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
@ -588,9 +579,9 @@ File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
*******
|
||||
|
||||
Reads data from one or more files in hledger journal, timeclock,
|
||||
timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
|
||||
`$HOME/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or
|
||||
'$HOME/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
|
||||
|
||||
File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -598,10 +589,10 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
8 BUGS
|
||||
******
|
||||
|
||||
The need to precede options with `--' when invoked from hledger is
|
||||
The need to precede options with '--' when invoked from hledger is
|
||||
awkward.
|
||||
|
||||
`-f-' doesn't work (hledger-web can't read from stdin).
|
||||
'-f-' doesn't work (hledger-web can't read from stdin).
|
||||
|
||||
Query arguments and some hledger options are ignored.
|
||||
|
||||
@ -609,25 +600,29 @@ awkward.
|
||||
|
||||
Does not work well on small screens.
|
||||
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top235
|
||||
Node: OPTIONS1875
|
||||
Ref: #options1980
|
||||
Node: PERMISSIONS9393
|
||||
Ref: #permissions9532
|
||||
Node: EDITING UPLOADING DOWNLOADING10744
|
||||
Ref: #editing-uploading-downloading10925
|
||||
Node: RELOADING11756
|
||||
Ref: #reloading11890
|
||||
Node: JSON API12322
|
||||
Ref: #json-api12436
|
||||
Node: ENVIRONMENT17925
|
||||
Ref: #environment18041
|
||||
Node: FILES18773
|
||||
Ref: #files18873
|
||||
Node: BUGS19086
|
||||
Ref: #bugs19164
|
||||
Node: Top223
|
||||
Node: OPTIONS1889
|
||||
Ref: #options1994
|
||||
Node: PERMISSIONS9427
|
||||
Ref: #permissions9566
|
||||
Node: EDITING UPLOADING DOWNLOADING10778
|
||||
Ref: #editing-uploading-downloading10959
|
||||
Node: RELOADING11793
|
||||
Ref: #reloading11927
|
||||
Node: JSON API12360
|
||||
Ref: #json-api12474
|
||||
Node: ENVIRONMENT17964
|
||||
Ref: #environment18080
|
||||
Node: FILES18813
|
||||
Ref: #files18913
|
||||
Node: BUGS19126
|
||||
Ref: #bugs19204
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
Local Variables:
|
||||
coding: utf-8
|
||||
End:
|
||||
|
@ -5,7 +5,7 @@ HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1)
|
||||
|
||||
NAME
|
||||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||
This manual is for hledger-web 1.22.
|
||||
This manual is for hledger-web 1.22.99.
|
||||
|
||||
SYNOPSIS
|
||||
hledger-web [OPTIONS]
|
||||
@ -556,4 +556,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-web-1.22 July 2021 HLEDGER-WEB(1)
|
||||
hledger-web-1.22.99 August 2021 HLEDGER-WEB(1)
|
||||
|
@ -1,6 +1,6 @@
|
||||
.\"t
|
||||
|
||||
.TH "HLEDGER" "1" "July 2021" "hledger-1.22 " "hledger User Manuals"
|
||||
.TH "HLEDGER" "1" "August 2021" "hledger-1.22.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@
|
||||
This is the command-line interface (CLI) for the hledger accounting
|
||||
tool.
|
||||
Here we also describe hledger\[aq]s concepts and file formats.
|
||||
This manual is for hledger 1.22.
|
||||
This manual is for hledger 1.22.99.
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
\f[C]hledger\f[R]
|
||||
@ -2511,30 +2511,23 @@ aregister, areg
|
||||
.P
|
||||
.PD
|
||||
.PP
|
||||
Show the transactions and running historical balance in an account, with
|
||||
each line item representing one transaction.
|
||||
Show the transactions and running historical balance of a single
|
||||
account, with each transaction displayed as one line.
|
||||
.PP
|
||||
\f[C]aregister\f[R] shows the transactions affecting a particular
|
||||
account and its subaccounts, with each line item representing a whole
|
||||
transaction - as in bank statements, hledger-ui, hledger-web and other
|
||||
accounting apps.
|
||||
\f[C]aregister\f[R] shows the overall transactions affecting a
|
||||
particular account (and any subaccounts).
|
||||
Each report line represents one transaction in this account.
|
||||
Transactions before the report start date are always included in the
|
||||
running balance (\f[C]--historical\f[R] mode is always on).
|
||||
.PP
|
||||
Note this is unlike the \f[C]register\f[R] command, which shows
|
||||
individual postings and does not always show a single account or a
|
||||
historical balance.
|
||||
This is a more \[dq]real world\[dq], bank-like view than the
|
||||
\f[C]register\f[R] command (which shows individual postings, possibly
|
||||
from multiple accounts, not necessarily in historical mode).
|
||||
As a quick rule of thumb: - use \f[C]aregister\f[R] for reviewing and
|
||||
reconciling real-world asset/liability accounts - use \f[C]register\f[R]
|
||||
for reviewing detailed revenues/expenses.
|
||||
.PP
|
||||
A reminder, \[dq]historical\[dq] balances include any balance from
|
||||
transactions before the report start date, so (if opening balances are
|
||||
recorded correctly) \f[C]aregister\f[R] will show the real-world
|
||||
balances of an account, as you would see in a bank statement.
|
||||
.PP
|
||||
As a quick rule of thumb, use \f[C]aregister\f[R] for reconciling
|
||||
real-world asset/liability accounts and \f[C]register\f[R] for reviewing
|
||||
detailed revenues/expenses.
|
||||
.PP
|
||||
\f[C]aregister\f[R] shows the register for just one account (and its
|
||||
subaccounts).
|
||||
This account must be specified as the first argument.
|
||||
\f[C]aregister\f[R] requires one argument: the account to report on.
|
||||
You can write either the full account name, or a case-insensitive
|
||||
regular expression which will select the alphabetically first matched
|
||||
account.
|
||||
@ -2542,8 +2535,24 @@ account.
|
||||
\f[C]assets:bbb:checking\f[R] accounts, \f[C]hledger areg checking\f[R]
|
||||
would select \f[C]assets:aaa:checking\f[R].)
|
||||
.PP
|
||||
Transactions involving subaccounts of this account will also be shown.
|
||||
\f[C]aregister\f[R] ignores depth limits, so its final total will always
|
||||
match a balance report with similar arguments.
|
||||
.PP
|
||||
Any additional arguments form a query which will filter the transactions
|
||||
shown.
|
||||
Note some queries will disturb the running balance, causing it to be
|
||||
different from the account\[aq]s real-world running balance.
|
||||
.PP
|
||||
An example: this shows the transactions and historical running balance
|
||||
during july, in the first account whose name contains
|
||||
\[dq]checking\[dq]:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger areg checking date:jul
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Each \f[C]aregister\f[R] line item shows:
|
||||
.IP \[bu] 2
|
||||
@ -2560,12 +2569,10 @@ the account\[aq]s historical running balance after this transaction.
|
||||
Transactions making a net change of zero are not shown by default; add
|
||||
the \f[C]-E/--empty\f[R] flag to show them.
|
||||
.PP
|
||||
\f[C]aregister\f[R] ignores a depth limit, so its final total will
|
||||
always match a balance report with similar arguments.
|
||||
.PP
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
|
||||
and \f[C]json\f[R].
|
||||
options.
|
||||
The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], and
|
||||
\f[C]json\f[R].
|
||||
.SS aregister and custom posting dates
|
||||
.PP
|
||||
Transactions whose date is outside the report period can still be shown,
|
||||
@ -2579,26 +2586,6 @@ To filter strictly by transaction date instead, add the
|
||||
\f[C]--txn-dates\f[R] flag.
|
||||
If you use this flag and some of your postings have custom dates,
|
||||
it\[aq]s probably best to assume the running balance is wrong.
|
||||
.PP
|
||||
Examples:
|
||||
.PP
|
||||
Show all transactions and historical running balance in the first
|
||||
account whose name contains \[dq]checking\[dq]:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger areg checking
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Show transactions and historical running balance in all asset accounts
|
||||
during july:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger areg assets date:jul
|
||||
\f[R]
|
||||
.fi
|
||||
.SS balance
|
||||
.PP
|
||||
balance, bal
|
||||
@ -2680,6 +2667,9 @@ another field used as account name (\f[C]--pivot\f[R])
|
||||
.IP \[bu] 2
|
||||
custom-formatted line items (single-period reports only)
|
||||
(\f[C]--format\f[R])
|
||||
.IP \[bu] 2
|
||||
commodities shown in a separate column, one per row
|
||||
(\f[C]--commodity-column\f[R])
|
||||
.PP
|
||||
This command supports the output destination and output format options,
|
||||
with output formats \f[C]txt\f[R], \f[C]csv\f[R], \f[C]json\f[R], and
|
||||
@ -2898,6 +2888,68 @@ Output as CSV and use a CSV viewer like visidata
|
||||
.IP \[bu] 2
|
||||
Output as HTML and view with a browser:
|
||||
\f[C]hledger bal -D -o a.html && open a.html\f[R]
|
||||
.SS Commodity column
|
||||
.PP
|
||||
With \f[C]--commodity-column\f[R], commodity symbols are displayed in a
|
||||
separate column, and amounts are displayed as bare numbers.
|
||||
In this mode, each report row will show amounts for a single commodity,
|
||||
using extra rows when necessary.
|
||||
It can be useful for a cleaner display of reports with many commodities:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger bal -T -Y
|
||||
Balance changes in 2012-01-01..2014-12-31:
|
||||
|
||||
|| 2012 2013 2014 Total
|
||||
==================++=============================================================================================================================
|
||||
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
|
||||
------------------++-----------------------------------------------------------------------------------------------------------------------------
|
||||
total || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
|
||||
|
||||
$ hledger bal -T -Y --commodity-column
|
||||
Balance changes in 2012-01-01..2014-12-31:
|
||||
|
||||
|| Commodity 2012 2013 2014 Total
|
||||
==================++=============================================
|
||||
Assets:US:ETrade || GLD 0 70.00 0 70.00
|
||||
Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
|
||||
Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
|
||||
Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
|
||||
Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
|
||||
------------------++---------------------------------------------
|
||||
|| GLD 0 70.00 0 70.00
|
||||
|| ITOT 10.00 18.00 -11.00 17.00
|
||||
|| USD 337.18 -98.12 4881.44 5120.50
|
||||
|| VEA 12.00 10.00 14.00 36.00
|
||||
|| VHT 106.00 18.00 170.00 294.00
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
This flag also affects CSV output, which is useful for producing data
|
||||
that is easier to consume, eg when making charts:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger bal -T -O csv
|
||||
\[dq]account\[dq],\[dq]balance\[dq]
|
||||
\[dq]Assets:US:ETrade\[dq],\[dq]70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT\[dq]
|
||||
\[dq]total\[dq],\[dq]70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT\[dq]
|
||||
|
||||
$ hledger bal -T -O csv --commodity-column
|
||||
\[dq]account\[dq],\[dq]commodity\[dq],\[dq]balance\[dq]
|
||||
\[dq]Assets:US:ETrade\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]
|
||||
\[dq]Assets:US:ETrade\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]
|
||||
\[dq]Assets:US:ETrade\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]
|
||||
\[dq]Assets:US:ETrade\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]
|
||||
\[dq]Assets:US:ETrade\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]
|
||||
\[dq]total\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]
|
||||
\[dq]total\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]
|
||||
\[dq]total\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]
|
||||
\[dq]total\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]
|
||||
\[dq]total\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Sorting by amount
|
||||
.PP
|
||||
With \f[C]-S/--sort-amount\f[R], accounts with the largest (most
|
||||
@ -9017,70 +9069,111 @@ These rely on a \[dq]timeclock\[dq] executable which I think is just the
|
||||
ledger 2 executable renamed.
|
||||
.SH TIMEDOT FORMAT
|
||||
.PP
|
||||
hledger\[aq]s human-friendly time logging format.
|
||||
.PP
|
||||
Timedot is a plain text format for logging dated, categorised quantities
|
||||
(of time, usually), supported by hledger.
|
||||
It is convenient for approximate and retroactive time logging, eg when
|
||||
the real-time clock-in/out required with a timeclock file is too precise
|
||||
or too interruptive.
|
||||
It can be formatted like a bar chart, making clear at a glance where
|
||||
time was spent.
|
||||
.PP
|
||||
Though called \[dq]timedot\[dq], this format is read by hledger as
|
||||
commodityless quantities, so it could be used to represent dated
|
||||
quantities other than time.
|
||||
In the docs below we\[aq]ll assume it\[aq]s time.
|
||||
.PP
|
||||
A timedot file contains a series of day entries.
|
||||
A day entry begins with a non-indented hledger-style simple date (Y-M-D,
|
||||
Y/M/D, Y.M.D..) Any additional text on the same line is used as a
|
||||
transaction description for this day.
|
||||
.PP
|
||||
This is followed by optionally-indented timelog items for that day, one
|
||||
per line.
|
||||
Each timelog item is a note, usually a hledger:style:account:name
|
||||
representing a time category, followed by two or more spaces, and a
|
||||
quantity.
|
||||
Each timelog item generates a hledger transaction.
|
||||
.PP
|
||||
Quantities can be written as:
|
||||
\f[C]timedot\f[R] format is hledger\[aq]s human-friendly time logging
|
||||
format.
|
||||
Compared to \f[C]timeclock\f[R] format, it is
|
||||
.IP \[bu] 2
|
||||
dots: a sequence of dots (.) representing quarter hours.
|
||||
Spaces may optionally be used for grouping.
|
||||
Eg: ....
|
||||
\&..
|
||||
convenient for quick, approximate, and retroactive time logging
|
||||
.IP \[bu] 2
|
||||
an integral or decimal number, representing hours.
|
||||
Eg: 1.5
|
||||
.IP \[bu] 2
|
||||
an integral or decimal number immediately followed by a unit symbol
|
||||
\f[C]s\f[R], \f[C]m\f[R], \f[C]h\f[R], \f[C]d\f[R], \f[C]w\f[R],
|
||||
\f[C]mo\f[R], or \f[C]y\f[R], representing seconds, minutes, hours, days
|
||||
weeks, months or years respectively.
|
||||
Eg: 90m.
|
||||
The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m,
|
||||
1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
|
||||
readable: you can see at a glance where time was spent.
|
||||
.PP
|
||||
There is some flexibility allowing notes and todo lists to be kept right
|
||||
in the time log, if needed:
|
||||
A timedot file contains a series of day entries, which might look like
|
||||
this:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2021-08-04
|
||||
hom:errands .... ....
|
||||
fos:hledger:timedot .. ; docs
|
||||
per:admin:finance
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
hledger reads this as three time transactions on this day, with each dot
|
||||
representing a quarter-hour spent:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger -f a.timedot print # .timedot file extension activates the timedot reader
|
||||
2021-08-04 *
|
||||
(hom:errands) 2.00
|
||||
|
||||
2021-08-04 *
|
||||
(fos:hledger:timedot) 0.50
|
||||
|
||||
2021-08-04 *
|
||||
(per:admin:finance) 0
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
A day entry begins with a date line:
|
||||
.IP \[bu] 2
|
||||
Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are
|
||||
a non-indented \f[B]simple date\f[R] (Y-M-D, Y/M/D, or Y.M.D).
|
||||
.PP
|
||||
Optionally this can be followed on the same line by
|
||||
.IP \[bu] 2
|
||||
a common \f[B]transaction description\f[R] for this day
|
||||
.IP \[bu] 2
|
||||
a common \f[B]transaction comment\f[R] for this day, after a semicolon
|
||||
(\f[C];\f[R]).
|
||||
.PP
|
||||
After the date line are zero or more optionally-indented time
|
||||
transaction lines, consisting of:
|
||||
.IP \[bu] 2
|
||||
an \f[B]account name\f[R] - any word or phrase, usually a hledger-style
|
||||
account name.
|
||||
.IP \[bu] 2
|
||||
\f[B]two or more spaces\f[R] - a field separator, required if there is
|
||||
an amount (as in journal format).
|
||||
.IP \[bu] 2
|
||||
a \f[B]timedot amount\f[R] - dots representing quarter hours, or a
|
||||
number representing hours.
|
||||
.IP \[bu] 2
|
||||
an optional \f[B]comment\f[R] beginning with semicolon.
|
||||
This is ignored.
|
||||
.PP
|
||||
In more detail, timedot amounts can be:
|
||||
.IP \[bu] 2
|
||||
\f[B]dots\f[R]: zero or more period characters, each representing one
|
||||
quarter-hour.
|
||||
Spaces are ignored and can be used for grouping.
|
||||
Eg: \f[C].... ..\f[R]
|
||||
.IP \[bu] 2
|
||||
a \f[B]number\f[R], representing hours.
|
||||
Eg: \f[C]1.5\f[R]
|
||||
.IP \[bu] 2
|
||||
a \f[B]number immediately followed by a unit symbol\f[R] \f[C]s\f[R],
|
||||
\f[C]m\f[R], \f[C]h\f[R], \f[C]d\f[R], \f[C]w\f[R], \f[C]mo\f[R], or
|
||||
\f[C]y\f[R], representing seconds, minutes, hours, days weeks, months or
|
||||
years.
|
||||
Eg \f[C]1.5h\f[R] or \f[C]90m\f[R].
|
||||
The following equivalencies are assumed:
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
\f[C]60s\f[R] = \f[C]1m\f[R], \f[C]60m\f[R] = \f[C]1h\f[R],
|
||||
\f[C]24h\f[R] = \f[C]1d\f[R], \f[C]7d\f[R] = \f[C]1w\f[R], \f[C]30d\f[R]
|
||||
= \f[C]1mo\f[R], \f[C]365d\f[R] = \f[C]1y\f[R].
|
||||
(This unit will not be visible in the generated transaction amount,
|
||||
which is always in hours.)
|
||||
.PP
|
||||
There is some added flexibility to help with keeping time log data in
|
||||
the same file as your notes, todo lists, etc.:
|
||||
.IP \[bu] 2
|
||||
Lines beginning with \f[C]#\f[R] or \f[C];\f[R], and blank lines, are
|
||||
ignored.
|
||||
.IP \[bu] 2
|
||||
Lines not ending with a double-space and quantity are parsed as items
|
||||
taking no time, which will not appear in balance reports by default.
|
||||
(Add -E to see them.)
|
||||
Lines not ending with a double-space and amount are parsed as
|
||||
transactions with zero amount.
|
||||
(Most hledger reports hide these by default; add -E to see them.)
|
||||
.IP \[bu] 2
|
||||
Org mode headlines (lines beginning with one or more \f[C]*\f[R]
|
||||
followed by a space) can be used as date lines or timelog items (the
|
||||
stars are ignored).
|
||||
Also all org headlines before the first date line are ignored.
|
||||
This means org users can manage their timelog as an org outline (eg
|
||||
using org-mode/orgstruct-mode in Emacs), for organisation, faster
|
||||
navigation, controlling visibility etc.
|
||||
One or more stars (\f[C]*\f[R]) followed by a space, at the start of a
|
||||
line, is ignored.
|
||||
So date lines or time transaction lines can also be Org-mode headlines.
|
||||
.IP \[bu] 2
|
||||
All Org-mode headlines before the first date line are ignored.
|
||||
.PP
|
||||
Examples:
|
||||
More examples:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
@ -9138,7 +9231,7 @@ Reporting:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger -f t.timedot print date:2016/2/2
|
||||
$ hledger -f a.timedot print date:2016/2/2
|
||||
2016-02-02 *
|
||||
(inc:client1) 2.00
|
||||
|
||||
@ -9149,7 +9242,7 @@ $ hledger -f t.timedot print date:2016/2/2
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger -f t.timedot bal --daily --tree
|
||||
$ hledger -f a.timedot bal --daily --tree
|
||||
Balance changes in 2016-02-01-2016-02-03:
|
||||
|
||||
|| 2016-02-01d 2016-02-02d 2016-02-03d
|
||||
@ -9166,8 +9259,7 @@ Balance changes in 2016-02-01-2016-02-03:
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
I prefer to use period for separating account components.
|
||||
We can make this work with an account alias:
|
||||
Using period instead of colon as account name separator:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
@ -9179,7 +9271,7 @@ fos.ledger ..
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger -f t.timedot --alias /\[rs]\[rs]./=: bal date:2016/2/4 --tree
|
||||
$ hledger -f a.timedot --alias /\[rs]\[rs]./=: bal --tree
|
||||
4.50 fos
|
||||
4.00 hledger:timedot
|
||||
0.50 ledger
|
||||
@ -9188,7 +9280,7 @@ $ hledger -f t.timedot --alias /\[rs]\[rs]./=: bal date:2016/2/4 --tree
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Here is a sample.timedot.
|
||||
A sample.timedot file.
|
||||
.SH COMMON TASKS
|
||||
.PP
|
||||
Here are some quick examples of how to do some basic tasks with hledger.
|
||||
|
5173
hledger/hledger.info
5173
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
2386
hledger/hledger.txt
2386
hledger/hledger.txt
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user