mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-18 17:57:11 +03:00
fix: doc: update manuals; regenerate all info manuals (fix #2023)
This commit is contained in:
Simon Michael
parent
270a92292f
commit
1c5dee2339
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2023}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{April 2023}})m4_dnl
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2023}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{April 2023}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-UI" "1" "March 2023" "hledger-ui-1.29.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-UI" "1" "April 2023" "hledger-ui-1.29.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
@ -13,10 +13,10 @@ hledger-ui(1)
|
||||
|
||||
hledger-ui - robust, friendly plain text accounting (TUI version)
|
||||
|
||||
‘hledger-ui [OPTIONS] [QUERYARGS]’
|
||||
‘hledger ui -- [OPTIONS] [QUERYARGS]’
|
||||
'hledger-ui [OPTIONS] [QUERYARGS]'
|
||||
'hledger ui -- [OPTIONS] [QUERYARGS]'
|
||||
|
||||
This manual is for hledger’s terminal interface, version 1.29.99.
|
||||
This manual is for hledger's terminal interface, version 1.29.99.
|
||||
See also the hledger manual for common concepts and file formats.
|
||||
|
||||
hledger is a robust, user-friendly, cross-platform set of programs
|
||||
@ -25,21 +25,21 @@ accounting and a simple, editable file format. hledger is inspired by
|
||||
and largely compatible with ledger(1), and largely interconvertible with
|
||||
beancount(1).
|
||||
|
||||
hledger-ui is hledger’s terminal interface, providing an efficient
|
||||
hledger-ui is hledger's terminal interface, providing an efficient
|
||||
full-window text UI for viewing accounts and transactions, and some
|
||||
limited data entry capability. It is easier than hledger’s command-line
|
||||
limited data entry capability. It is easier than hledger's command-line
|
||||
interface, and sometimes quicker and more convenient than the web
|
||||
interface.
|
||||
|
||||
Like hledger, it reads data from one or more files in journal,
|
||||
timeclock, timedot, or CSV format. The default file is
|
||||
‘.hledger.journal’ in your home directory; this can be overridden with
|
||||
one or more ‘-f FILE’ options, or the ‘LEDGER_FILE’ environment
|
||||
'.hledger.journal' in your home directory; this can be overridden with
|
||||
one or more '-f FILE' options, or the 'LEDGER_FILE' environment
|
||||
variable. For more about this see hledger(1), hledger_journal(5) etc.
|
||||
|
||||
Unlike hledger, hledger-ui hides all future-dated transactions by
|
||||
default. They can be revealed, along with any rule-generated periodic
|
||||
transactions, by pressing the F key (or starting with –forecast) to
|
||||
transactions, by pressing the F key (or starting with -forecast) to
|
||||
enable "forecast mode".
|
||||
|
||||
* Menu:
|
||||
@ -59,176 +59,176 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top
|
||||
1 OPTIONS
|
||||
*********
|
||||
|
||||
Note: if invoking hledger-ui as a hledger subcommand, write ‘--’ before
|
||||
Note: if invoking hledger-ui as a hledger subcommand, write '--' before
|
||||
options as shown above.
|
||||
|
||||
Any QUERYARGS are interpreted as a hledger search query which filters
|
||||
the data.
|
||||
|
||||
‘-w --watch’
|
||||
'-w --watch'
|
||||
|
||||
watch for data and date changes and reload automatically
|
||||
‘--theme=default|terminal|greenterm’
|
||||
'--theme=default|terminal|greenterm'
|
||||
|
||||
use this custom display theme
|
||||
‘--menu’
|
||||
'--menu'
|
||||
|
||||
start in the menu screen
|
||||
‘--cash’
|
||||
'--cash'
|
||||
|
||||
start in the cash accounts screen
|
||||
‘--bs’
|
||||
'--bs'
|
||||
|
||||
start in the balance sheet accounts screen
|
||||
‘--is’
|
||||
'--is'
|
||||
|
||||
start in the income statement accounts screen
|
||||
‘--all’
|
||||
'--all'
|
||||
|
||||
start in the all accounts screen
|
||||
‘--register=ACCTREGEX’
|
||||
'--register=ACCTREGEX'
|
||||
|
||||
start in the (first) matched account’s register screen
|
||||
‘--change’
|
||||
start in the (first) matched account's register screen
|
||||
'--change'
|
||||
|
||||
show period balances (changes) at startup instead of historical
|
||||
balances
|
||||
‘-l --flat’
|
||||
'-l --flat'
|
||||
|
||||
show accounts as a flat list (default)
|
||||
‘-t --tree’
|
||||
'-t --tree'
|
||||
|
||||
show accounts as a tree
|
||||
|
||||
hledger input options:
|
||||
|
||||
‘-f FILE --file=FILE’
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)
|
||||
‘--rules-file=RULESFILE’
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
‘--separator=CHAR’
|
||||
'--separator=CHAR'
|
||||
|
||||
Field separator to expect when reading CSV (default: ’,’)
|
||||
‘--alias=OLD=NEW’
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
rename accounts named OLD to NEW
|
||||
‘--anon’
|
||||
'--anon'
|
||||
|
||||
anonymize accounts and payees
|
||||
‘--pivot FIELDNAME’
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
use some other field or tag for the account name
|
||||
‘-I --ignore-assertions’
|
||||
'-I --ignore-assertions'
|
||||
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
‘-s --strict’
|
||||
'-s --strict'
|
||||
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
‘-b --begin=DATE’
|
||||
'-b --begin=DATE'
|
||||
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
‘-e --end=DATE’
|
||||
'-e --end=DATE'
|
||||
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
‘-D --daily’
|
||||
'-D --daily'
|
||||
|
||||
multiperiod/multicolumn report by day
|
||||
‘-W --weekly’
|
||||
'-W --weekly'
|
||||
|
||||
multiperiod/multicolumn report by week
|
||||
‘-M --monthly’
|
||||
'-M --monthly'
|
||||
|
||||
multiperiod/multicolumn report by month
|
||||
‘-Q --quarterly’
|
||||
'-Q --quarterly'
|
||||
|
||||
multiperiod/multicolumn report by quarter
|
||||
‘-Y --yearly’
|
||||
'-Y --yearly'
|
||||
|
||||
multiperiod/multicolumn report by year
|
||||
‘-p --period=PERIODEXP’
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
‘--date2’
|
||||
'--date2'
|
||||
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
‘--today=DATE’
|
||||
'--today=DATE'
|
||||
|
||||
override today’s date (affects relative smart dates, for
|
||||
override today's date (affects relative smart dates, for
|
||||
tests/examples)
|
||||
‘-U --unmarked’
|
||||
'-U --unmarked'
|
||||
|
||||
include only unmarked postings/txns (can combine with -P or -C)
|
||||
‘-P --pending’
|
||||
'-P --pending'
|
||||
|
||||
include only pending postings/txns
|
||||
‘-C --cleared’
|
||||
'-C --cleared'
|
||||
|
||||
include only cleared postings/txns
|
||||
‘-R --real’
|
||||
'-R --real'
|
||||
|
||||
include only non-virtual postings
|
||||
‘-NUM --depth=NUM’
|
||||
'-NUM --depth=NUM'
|
||||
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
‘-E --empty’
|
||||
'-E --empty'
|
||||
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
‘-B --cost’
|
||||
'-B --cost'
|
||||
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
‘-V --market’
|
||||
'-V --market'
|
||||
|
||||
convert amounts to their market value in default valuation
|
||||
commodities
|
||||
‘-X --exchange=COMM’
|
||||
'-X --exchange=COMM'
|
||||
|
||||
convert amounts to their market value in commodity COMM
|
||||
‘--value’
|
||||
'--value'
|
||||
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
‘--infer-market-prices’
|
||||
'--infer-market-prices'
|
||||
|
||||
use transaction prices (recorded with @ or @@) as additional market
|
||||
prices, as if they were P directives
|
||||
‘--auto’
|
||||
'--auto'
|
||||
|
||||
apply automated posting rules to modify transactions.
|
||||
‘--forecast’
|
||||
'--forecast'
|
||||
|
||||
generate future transactions from periodic transaction rules, for
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
make ordinary future transactions visible.
|
||||
‘--commodity-style’
|
||||
'--commodity-style'
|
||||
|
||||
Override the commodity style in the output for the specified
|
||||
commodity. For example ’EUR1.000,00’.
|
||||
‘--color=WHEN (or --colour=WHEN)’
|
||||
commodity. For example 'EUR1.000,00'.
|
||||
'--color=WHEN (or --colour=WHEN)'
|
||||
|
||||
Should color-supporting commands use ANSI color codes in text
|
||||
output. ’auto’ (default): whenever stdout seems to be a
|
||||
color-supporting terminal. ’always’ or ’yes’: always, useful eg
|
||||
when piping output into ’less -R’. ’never’ or ’no’: never. A
|
||||
output. 'auto' (default): whenever stdout seems to be a
|
||||
color-supporting terminal. 'always' or 'yes': always, useful eg
|
||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||
NO_COLOR environment variable overrides this.
|
||||
‘--pretty[=WHEN]’
|
||||
'--pretty[=WHEN]'
|
||||
|
||||
Show prettier output, e.g. using unicode box-drawing characters.
|
||||
Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’
|
||||
also work). If you provide an argument you must use ’=’, e.g.
|
||||
’–pretty=yes’.
|
||||
Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'
|
||||
also work). If you provide an argument you must use '=', e.g.
|
||||
'-pretty=yes'.
|
||||
|
||||
When a reporting option appears more than once in the command line,
|
||||
the last one takes precedence.
|
||||
@ -237,25 +237,25 @@ the last one takes precedence.
|
||||
|
||||
hledger help options:
|
||||
|
||||
‘-h --help’
|
||||
'-h --help'
|
||||
|
||||
show general or COMMAND help
|
||||
‘--man’
|
||||
'--man'
|
||||
|
||||
show general or COMMAND user manual with man
|
||||
‘--info’
|
||||
'--info'
|
||||
|
||||
show general or COMMAND user manual with info
|
||||
‘--version’
|
||||
'--version'
|
||||
|
||||
show general or ADDONCMD version
|
||||
‘--debug[=N]’
|
||||
'--debug[=N]'
|
||||
|
||||
show debug output (levels 1-9, default: 1)
|
||||
|
||||
A @FILE argument will be expanded to the contents of FILE, which
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a ‘--’ argument before.)
|
||||
this, insert a '--' argument before.)
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
||||
@ -266,9 +266,9 @@ File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
||||
In most modern terminals, you can navigate through the screens with a
|
||||
mouse or touchpad:
|
||||
|
||||
• Use mouse wheel or trackpad to scroll up and down
|
||||
• Click on list items to go deeper
|
||||
• Click on the left margin (column 0) to go back.
|
||||
* Use mouse wheel or trackpad to scroll up and down
|
||||
* Click on list items to go deeper
|
||||
* Click on the left margin (column 0) to go back.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: MOUSE, Up: Top
|
||||
@ -278,96 +278,96 @@ File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: MOUSE, Up: Top
|
||||
|
||||
Keyboard gives more control.
|
||||
|
||||
‘?’ shows a help dialog listing all keys. (Some of these also appear
|
||||
in the quick help at the bottom of each screen.) Press ‘?’ again (or
|
||||
‘ESCAPE’, or ‘LEFT’, or ‘q’) to close it. The following keys work on
|
||||
'?' shows a help dialog listing all keys. (Some of these also appear
|
||||
in the quick help at the bottom of each screen.) Press '?' again (or
|
||||
'ESCAPE', or 'LEFT', or 'q') to close it. The following keys work on
|
||||
most screens:
|
||||
|
||||
The cursor keys navigate: ‘RIGHT’ or ‘ENTER’ goes deeper, ‘LEFT’
|
||||
returns to the previous screen, ‘UP’/‘DOWN’/‘PGUP’/‘PGDN’/‘HOME’/‘END’
|
||||
The cursor keys navigate: 'RIGHT' or 'ENTER' goes deeper, 'LEFT'
|
||||
returns to the previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END'
|
||||
move up and down through lists. Emacs-style
|
||||
(‘CTRL-p’/‘CTRL-n’/‘CTRL-f’/‘CTRL-b’) and VI-style (‘k’,‘j’,‘l’,‘h’)
|
||||
('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') and VI-style ('k','j','l','h')
|
||||
movement keys are also supported. A tip: movement speed is limited by
|
||||
your keyboard repeat rate, to move faster you may want to adjust it.
|
||||
(If you’re on a mac, the karabiner app is one way to do that.)
|
||||
(If you're on a mac, the karabiner app is one way to do that.)
|
||||
|
||||
With shift pressed, the cursor keys adjust the report period,
|
||||
limiting the transactions to be shown (by default, all are shown).
|
||||
‘SHIFT-DOWN/UP’ steps downward and upward through these standard report
|
||||
'SHIFT-DOWN/UP' steps downward and upward through these standard report
|
||||
period durations: year, quarter, month, week, day. Then,
|
||||
‘SHIFT-LEFT/RIGHT’ moves to the previous/next period. ‘T’ sets the
|
||||
report period to today. With the ‘-w/--watch’ option, when viewing a
|
||||
'SHIFT-LEFT/RIGHT' moves to the previous/next period. 'T' sets the
|
||||
report period to today. With the '-w/--watch' option, when viewing a
|
||||
"current" period (the current day, week, month, quarter, or year), the
|
||||
period will move automatically to track the current date. To set a
|
||||
non-standard period, you can use ‘/’ and a ‘date:’ query.
|
||||
non-standard period, you can use '/' and a 'date:' query.
|
||||
|
||||
(Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as
|
||||
of MacOS Monterey. You can configure them as follows: open Terminal,
|
||||
press CMD-comma to open preferences, click Profiles, select your current
|
||||
terminal profile on the left, click Keyboard on the right, click + and
|
||||
add this for Shift-Down: ‘\033[1;2B’, click + and add this for Shift-Up:
|
||||
‘\033[1;2A’. Press the Escape key to enter the ‘\033’ part, you can’t
|
||||
add this for Shift-Down: '\033[1;2B', click + and add this for Shift-Up:
|
||||
'\033[1;2A'. Press the Escape key to enter the '\033' part, you can't
|
||||
type it directly.)
|
||||
|
||||
‘/’ lets you set a general filter query limiting the data shown,
|
||||
'/' lets you set a general filter query limiting the data shown,
|
||||
using the same query terms as in hledger and hledger-web. While editing
|
||||
the query, you can use CTRL-a/e/d/k, BS, cursor keys; press ‘ENTER’ to
|
||||
set it, or ‘ESCAPE’to cancel. There are also keys for quickly adjusting
|
||||
the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to
|
||||
set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting
|
||||
some common filters like account depth and transaction status (see
|
||||
below). ‘BACKSPACE’ or ‘DELETE’ removes all filters, showing all
|
||||
below). 'BACKSPACE' or 'DELETE' removes all filters, showing all
|
||||
transactions.
|
||||
|
||||
As mentioned above, by default hledger-ui hides future transactions -
|
||||
both ordinary transactions recorded in the journal, and periodic
|
||||
transactions generated by rule. ‘F’ toggles forecast mode, in which
|
||||
transactions generated by rule. 'F' toggles forecast mode, in which
|
||||
future/forecasted transactions are shown.
|
||||
|
||||
‘ESCAPE’ resets the UI state and jumps back to the top screen,
|
||||
restoring the app’s initial state at startup. Or, it cancels minibuffer
|
||||
'ESCAPE' resets the UI state and jumps back to the top screen,
|
||||
restoring the app's initial state at startup. Or, it cancels minibuffer
|
||||
data entry or the help dialog.
|
||||
|
||||
‘CTRL-l’ redraws the screen and centers the selection if possible
|
||||
(selections near the top won’t be centered, since we don’t scroll above
|
||||
'CTRL-l' redraws the screen and centers the selection if possible
|
||||
(selections near the top won't be centered, since we don't scroll above
|
||||
the top).
|
||||
|
||||
‘g’ reloads from the data file(s) and updates the current screen and
|
||||
'g' reloads from the data file(s) and updates the current screen and
|
||||
any previous screens. (With large files, this could cause a noticeable
|
||||
pause.)
|
||||
|
||||
‘I’ toggles balance assertion checking. Disabling balance assertions
|
||||
'I' toggles balance assertion checking. Disabling balance assertions
|
||||
temporarily can be useful for troubleshooting.
|
||||
|
||||
‘a’ runs command-line hledger’s add command, and reloads the updated
|
||||
'a' runs command-line hledger's add command, and reloads the updated
|
||||
file. This allows some basic data entry.
|
||||
|
||||
‘A’ is like ‘a’, but runs the hledger-iadd tool, which provides a
|
||||
terminal interface. This key will be available if ‘hledger-iadd’ is
|
||||
'A' is like 'a', but runs the hledger-iadd tool, which provides a
|
||||
terminal interface. This key will be available if 'hledger-iadd' is
|
||||
installed in $path.
|
||||
|
||||
‘E’ runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (‘emacsclient
|
||||
-a "" -nw’) on the journal file. With some editors (emacs, vi), the
|
||||
'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient
|
||||
-a "" -nw') on the journal file. With some editors (emacs, vi), the
|
||||
cursor will be positioned at the current transaction when invoked from
|
||||
the register and transaction screens, and at the error location (if
|
||||
possible) when invoked from the error screen.
|
||||
|
||||
‘B’ toggles cost mode, showing amounts in their cost’s commodity
|
||||
(like toggling the ‘-B/--cost’ flag).
|
||||
'B' toggles cost mode, showing amounts in their cost's commodity
|
||||
(like toggling the '-B/--cost' flag).
|
||||
|
||||
‘V’ toggles value mode, showing amounts’ current market value in
|
||||
their default valuation commodity (like toggling the ‘-V/--market’
|
||||
'V' toggles value mode, showing amounts' current market value in
|
||||
their default valuation commodity (like toggling the '-V/--market'
|
||||
flag). Note, "current market value" means the value on the report end
|
||||
date if specified, otherwise today. To see the value on another date,
|
||||
you can temporarily set that as the report end date. Eg: to see a
|
||||
transaction as it was valued on july 30, go to the accounts or register
|
||||
screen, press ‘/’, and add ‘date:-7/30’ to the query.
|
||||
screen, press '/', and add 'date:-7/30' to the query.
|
||||
|
||||
At most one of cost or value mode can be active at once.
|
||||
|
||||
There’s not yet any visual reminder when cost or value mode is
|
||||
active; for now pressing ‘b’ ‘b’ ‘v’ should reliably reset to normal
|
||||
There's not yet any visual reminder when cost or value mode is
|
||||
active; for now pressing 'b' 'b' 'v' should reliably reset to normal
|
||||
mode.
|
||||
|
||||
‘q’ quits the application.
|
||||
'q' quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
@ -378,13 +378,13 @@ File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top
|
||||
*********
|
||||
|
||||
At startup, hledger-ui shows a menu screen by default. From here you
|
||||
can navigate to other screens using the cursor keys: ‘UP’/‘DOWN’ to
|
||||
select, ‘RIGHT’ to move to the selected screen, ‘LEFT’ to return to the
|
||||
previous screen. Or you can use ‘ESC’ to return directly to the top
|
||||
can navigate to other screens using the cursor keys: 'UP'/'DOWN' to
|
||||
select, 'RIGHT' to move to the selected screen, 'LEFT' to return to the
|
||||
previous screen. Or you can use 'ESC' to return directly to the top
|
||||
menu screen.
|
||||
|
||||
You can also use a command line flag to specific a different startup
|
||||
screen (‘--cs’, ‘--bs’, ‘--is’, ‘--all’, or ‘--register=ACCT’).
|
||||
screen ('--cs', '--bs', '--is', '--all', or '--register=ACCT').
|
||||
|
||||
* Menu:
|
||||
|
||||
@ -413,8 +413,8 @@ File: hledger-ui.info, Node: Cash accounts, Next: Balance sheet accounts, Pre
|
||||
4.2 Cash accounts
|
||||
=================
|
||||
|
||||
This screen shows "cash" (ie, liquid asset) accounts (like ‘hledger
|
||||
balancesheet type:c’). It always shows balances (historical ending
|
||||
This screen shows "cash" (ie, liquid asset) accounts (like 'hledger
|
||||
balancesheet type:c'). It always shows balances (historical ending
|
||||
balances on the date shown in the title line).
|
||||
|
||||
|
||||
@ -423,8 +423,8 @@ File: hledger-ui.info, Node: Balance sheet accounts, Next: Income statement ac
|
||||
4.3 Balance sheet accounts
|
||||
==========================
|
||||
|
||||
This screen shows asset, liability and equity accounts (like ‘hledger
|
||||
balancesheetequity’). It always shows balances.
|
||||
This screen shows asset, liability and equity accounts (like 'hledger
|
||||
balancesheetequity'). It always shows balances.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Income statement accounts, Next: All accounts, Prev: Balance sheet accounts, Up: SCREENS
|
||||
@ -432,8 +432,8 @@ File: hledger-ui.info, Node: Income statement accounts, Next: All accounts, P
|
||||
4.4 Income statement accounts
|
||||
=============================
|
||||
|
||||
This screen shows revenue and expense accounts (like ‘hledger
|
||||
incomestatement’). It always shows changes (balance changes in the
|
||||
This screen shows revenue and expense accounts (like 'hledger
|
||||
incomestatement'). It always shows changes (balance changes in the
|
||||
period shown in the title line).
|
||||
|
||||
|
||||
@ -443,8 +443,8 @@ File: hledger-ui.info, Node: All accounts, Next: Register, Prev: Income state
|
||||
================
|
||||
|
||||
This screen shows all accounts in your journal (unless filtered by a
|
||||
query; like ‘hledger balance’). It shows balances by default; you can
|
||||
toggle showing changes with the ‘H’ key.
|
||||
query; like 'hledger balance'). It shows balances by default; you can
|
||||
toggle showing changes with the 'H' key.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Register, Next: Transaction, Prev: All accounts, Up: SCREENS
|
||||
@ -455,45 +455,45 @@ File: hledger-ui.info, Node: Register, Next: Transaction, Prev: All accounts,
|
||||
This screen shows the transactions affecting a particular account. Each
|
||||
line represents one transaction, and shows:
|
||||
|
||||
• the other account(s) involved, in abbreviated form. (If there are
|
||||
* the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
by real postings.)
|
||||
|
||||
• the overall change to the current account’s balance; positive for
|
||||
* the overall change to the current account's balance; positive for
|
||||
an inflow to this account, negative for an outflow.
|
||||
|
||||
• the running total after the transaction. With the ‘H’ key you can
|
||||
* the running total after the transaction. With the 'H' key you can
|
||||
toggle between
|
||||
|
||||
• the period total, which is from just the transactions
|
||||
* the period total, which is from just the transactions
|
||||
displayed
|
||||
• or the historical total, which includes any undisplayed
|
||||
* or the historical total, which includes any undisplayed
|
||||
transactions before the start of the report period (and
|
||||
matching the filter query if any). This will be the running
|
||||
historical balance (what you would see on a bank’s website,
|
||||
historical balance (what you would see on a bank's website,
|
||||
eg) if not disturbed by a query.
|
||||
|
||||
Transactions affecting this account’s subaccounts will be included in
|
||||
the register if the accounts screen is in tree mode, or if it’s in list
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
the register if the accounts screen is in tree mode, or if it's in list
|
||||
mode but this account has subaccounts which are not shown due to a depth
|
||||
limit. In other words, the register always shows the transactions
|
||||
contributing to the balance shown on the accounts screen. Tree
|
||||
mode/list mode can be toggled with ‘t’ here also.
|
||||
mode/list mode can be toggled with 't' here also.
|
||||
|
||||
‘U’ toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, ‘P’ toggles pending transactions, and ‘C’
|
||||
'U' toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, 'P' toggles pending transactions, and 'C'
|
||||
toggles cleared transactions. (By default, transactions with all
|
||||
statuses are shown; if you activate one or two status filters, only
|
||||
those transactions are shown; and if you activate all three, the filter
|
||||
is removed.)
|
||||
|
||||
‘R’ toggles real mode, in which virtual postings are ignored.
|
||||
'R' toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
‘z’ toggles nonzero mode, in which only transactions posting a
|
||||
'z' toggles nonzero mode, in which only transactions posting a
|
||||
nonzero change are shown (hledger-ui shows zero items by default, unlike
|
||||
command-line hledger).
|
||||
|
||||
Press ‘RIGHT’ to view the selected transaction in detail.
|
||||
Press 'RIGHT' to view the selected transaction in detail.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Transaction, Next: Error, Prev: Register, Up: SCREENS
|
||||
@ -502,32 +502,32 @@ File: hledger-ui.info, Node: Transaction, Next: Error, Prev: Register, Up: S
|
||||
===============
|
||||
|
||||
This screen shows a single transaction, as a general journal entry,
|
||||
similar to hledger’s print command and journal format
|
||||
similar to hledger's print command and journal format
|
||||
(hledger_journal(5)).
|
||||
|
||||
The transaction’s date(s) and any cleared flag, transaction code,
|
||||
The transaction's date(s) and any cleared flag, transaction code,
|
||||
description, comments, along with all of its account postings are shown.
|
||||
Simple transactions have two postings, but there can be more (or in
|
||||
certain cases, fewer).
|
||||
|
||||
‘UP’ and ‘DOWN’ will step through all transactions listed in the
|
||||
'UP' and 'DOWN' will step through all transactions listed in the
|
||||
previous account register screen. In the title bar, the numbers in
|
||||
parentheses show your position within that account register. They will
|
||||
vary depending on which account register you came from (remember most
|
||||
transactions appear in multiple account registers). The #N number
|
||||
preceding them is the transaction’s position within the complete
|
||||
preceding them is the transaction's position within the complete
|
||||
unfiltered journal, which is a more stable id (at least until the next
|
||||
reload).
|
||||
|
||||
On this screen (and the register screen), the ‘E’ key will open your
|
||||
On this screen (and the register screen), the 'E' key will open your
|
||||
text editor with the cursor positioned at the current transaction if
|
||||
possible.
|
||||
|
||||
This screen has a limitation with showing file updates: it will not
|
||||
show them until you exit and re-enter it. So eg to see the effect of
|
||||
using the ‘E’ key, currently you must: - press ‘E’, edit and save the
|
||||
file, then exit the editor, returning to hledger-ui - press ‘g’ to
|
||||
reload the file (or use ‘-w/--watch’ mode) - press ‘LEFT’ then ‘RIGHT’
|
||||
using the 'E' key, currently you must: - press 'E', edit and save the
|
||||
file, then exit the editor, returning to hledger-ui - press 'g' to
|
||||
reload the file (or use '-w/--watch' mode) - press 'LEFT' then 'RIGHT'
|
||||
to exit and re-enter the transaction screen.
|
||||
|
||||
|
||||
@ -558,12 +558,12 @@ File: hledger-ui.info, Node: Watch mode, Next: Debug output, Up: TIPS
|
||||
5.1 Watch mode
|
||||
==============
|
||||
|
||||
One of hledger-ui’s best features is the auto-reloading ‘-w/--watch’
|
||||
One of hledger-ui's best features is the auto-reloading '-w/--watch'
|
||||
mode. With this flag, it will update the display automatically whenever
|
||||
changes are saved to the data files.
|
||||
|
||||
This is very useful when reconciling. A good workflow is to have
|
||||
your bank’s online register open in a browser window, for reference; the
|
||||
your bank's online register open in a browser window, for reference; the
|
||||
journal file open in an editor window; and hledger-ui in watch mode in a
|
||||
terminal window, eg:
|
||||
|
||||
@ -578,16 +578,16 @@ history.
|
||||
Here are some current limitations to be aware of:
|
||||
|
||||
Changes might not be detected with certain editors, possibly
|
||||
including Jetbrains IDEs, ‘gedit’, other Gnome applications; or on
|
||||
including Jetbrains IDEs, 'gedit', other Gnome applications; or on
|
||||
certain unusual filesystems. (#1617, #911). To work around, reload
|
||||
manually by pressing ‘g’ in the hledger-ui window. (Or see #1617 for
|
||||
manually by pressing 'g' in the hledger-ui window. (Or see #1617 for
|
||||
another workaround, and let us know if it works for you.)
|
||||
|
||||
CPU and memory usage can sometimes gradually increase, if ‘hledger-ui
|
||||
--watch’ is left running for days. (Possibly correlated with certain
|
||||
CPU and memory usage can sometimes gradually increase, if 'hledger-ui
|
||||
--watch' is left running for days. (Possibly correlated with certain
|
||||
platforms, many transactions, and/or large numbers of other files
|
||||
present). To work around, ‘q’uit and restart it, or (where supported)
|
||||
suspend (‘CTRL-z’) and restart it (‘fg’).
|
||||
present). To work around, 'q'uit and restart it, or (where supported)
|
||||
suspend ('CTRL-z') and restart it ('fg').
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS
|
||||
@ -595,8 +595,8 @@ File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS
|
||||
5.2 Debug output
|
||||
================
|
||||
|
||||
You can add ‘--debug[=N]’ to the command line to log debug output. This
|
||||
will be logged to the file ‘hledger-ui.log’ in the current directory. N
|
||||
You can add '--debug[=N]' to the command line to log debug output. This
|
||||
will be logged to the file 'hledger-ui.log' in the current directory. N
|
||||
ranges from 1 (least output, the default) to 9 (maximum output).
|
||||
|
||||
|
||||
@ -607,33 +607,33 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
|
||||
|
||||
*COLUMNS* The screen width to use. Default: the full terminal width.
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with ‘-f’.
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
|
||||
On unix computers, the default value is: ‘~/.hledger.journal’.
|
||||
On unix computers, the default value is: '~/.hledger.journal'.
|
||||
|
||||
A more typical value is something like ‘~/finance/YYYY.journal’,
|
||||
where ‘~/finance’ is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, ‘~/finance/current.journal’, where
|
||||
A more typical value is something like '~/finance/YYYY.journal',
|
||||
where '~/finance' is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, '~/finance/current.journal', where
|
||||
current.journal is a symbolic link to YYYY.journal.
|
||||
|
||||
The usual way to set this permanently is to add a command to one of
|
||||
your shell’s startup files (eg ‘~/.profile’):
|
||||
your shell's startup files (eg '~/.profile'):
|
||||
|
||||
export LEDGER_FILE=~/finance/current.journal`
|
||||
|
||||
On some Mac computers, there is a more thorough way to set
|
||||
environment variables, that will also affect applications started from
|
||||
the GUI (eg, Emacs started from a dock icon): In
|
||||
‘~/.MacOSX/environment.plist’, add an entry like:
|
||||
'~/.MacOSX/environment.plist', add an entry like:
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
For this to take effect you might need to ‘killall Dock’, or reboot.
|
||||
For this to take effect you might need to 'killall Dock', or reboot.
|
||||
|
||||
On Windows computers, the default value is probably
|
||||
‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a
|
||||
'C:\Users\YOURNAME\.hledger.journal'. You can change this by running a
|
||||
command like this in a powershell window (let us know if you need to be
|
||||
an Administrator, and if this persists across a reboot):
|
||||
|
||||
@ -649,9 +649,9 @@ File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
*******
|
||||
|
||||
Reads data from one or more files in journal, timeclock, timedot, or CSV
|
||||
format. The default file is ‘.hledger.journal’ in your home directory;
|
||||
this can be overridden with one or more ‘-f FILE’ options, or the
|
||||
‘LEDGER_FILE’ environment variable.
|
||||
format. The default file is '.hledger.journal' in your home directory;
|
||||
this can be overridden with one or more '-f FILE' options, or the
|
||||
'LEDGER_FILE' environment variable.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -659,15 +659,15 @@ File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
8 BUGS
|
||||
******
|
||||
|
||||
‘-f-’ doesn’t work (hledger-ui can’t read from stdin).
|
||||
'-f-' doesn't work (hledger-ui can't read from stdin).
|
||||
|
||||
‘-V’ affects only the accounts screen.
|
||||
'-V' affects only the accounts screen.
|
||||
|
||||
When you press ‘g’, the current and all previous screens are
|
||||
When you press 'g', the current and all previous screens are
|
||||
regenerated, which may cause a noticeable pause with large files. Also
|
||||
there is no visual indication that this is in progress.
|
||||
|
||||
‘--watch’ is not yet fully robust. It works well for normal usage,
|
||||
'--watch' is not yet fully robust. It works well for normal usage,
|
||||
but many file changes in a short time (eg saving the file thousands of
|
||||
times with an editor macro) can cause problems at least on OSX. Symptoms
|
||||
include: unresponsive UI, periodic resetting of the cursor position,
|
||||
@ -676,47 +676,47 @@ and possibly a small but persistent build-up of CPU usage until the
|
||||
program is restarted.
|
||||
|
||||
Also, if you are viewing files mounted from another machine,
|
||||
‘-w/--watch’ requires that both machine clocks are roughly in step.
|
||||
'-w/--watch' requires that both machine clocks are roughly in step.
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top223
|
||||
Node: OPTIONS1871
|
||||
Ref: #options1969
|
||||
Node: MOUSE7389
|
||||
Ref: #mouse7484
|
||||
Node: KEYS7727
|
||||
Ref: #keys7820
|
||||
Node: SCREENS12579
|
||||
Ref: #screens12677
|
||||
Node: Menu13297
|
||||
Ref: #menu13390
|
||||
Node: Cash accounts13585
|
||||
Ref: #cash-accounts13727
|
||||
Node: Balance sheet accounts13915
|
||||
Ref: #balance-sheet-accounts14096
|
||||
Node: Income statement accounts14220
|
||||
Ref: #income-statement-accounts14406
|
||||
Node: All accounts14574
|
||||
Ref: #all-accounts14720
|
||||
Node: Register14910
|
||||
Ref: #register15034
|
||||
Node: Transaction17046
|
||||
Ref: #transaction17169
|
||||
Node: Error18628
|
||||
Ref: #error18722
|
||||
Node: TIPS18966
|
||||
Ref: #tips19065
|
||||
Node: Watch mode19107
|
||||
Ref: #watch-mode19214
|
||||
Node: Debug output20702
|
||||
Ref: #debug-output20813
|
||||
Node: ENVIRONMENT21033
|
||||
Ref: #environment21144
|
||||
Node: FILES22567
|
||||
Ref: #files22666
|
||||
Node: BUGS22926
|
||||
Ref: #bugs23003
|
||||
Node: OPTIONS1843
|
||||
Ref: #options1941
|
||||
Node: MOUSE7074
|
||||
Ref: #mouse7169
|
||||
Node: KEYS7406
|
||||
Ref: #keys7499
|
||||
Node: SCREENS12012
|
||||
Ref: #screens12110
|
||||
Node: Menu12690
|
||||
Ref: #menu12783
|
||||
Node: Cash accounts12978
|
||||
Ref: #cash-accounts13120
|
||||
Node: Balance sheet accounts13304
|
||||
Ref: #balance-sheet-accounts13485
|
||||
Node: Income statement accounts13605
|
||||
Ref: #income-statement-accounts13791
|
||||
Node: All accounts13955
|
||||
Ref: #all-accounts14101
|
||||
Node: Register14283
|
||||
Ref: #register14407
|
||||
Node: Transaction16369
|
||||
Ref: #transaction16492
|
||||
Node: Error17909
|
||||
Ref: #error18003
|
||||
Node: TIPS18247
|
||||
Ref: #tips18346
|
||||
Node: Watch mode18388
|
||||
Ref: #watch-mode18495
|
||||
Node: Debug output19951
|
||||
Ref: #debug-output20062
|
||||
Node: ENVIRONMENT20274
|
||||
Ref: #environment20385
|
||||
Node: FILES21770
|
||||
Ref: #files21869
|
||||
Node: BUGS22117
|
||||
Ref: #bugs22194
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
@ -566,4 +566,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-ui-1.29.99 March 2023 HLEDGER-UI(1)
|
||||
hledger-ui-1.29.99 April 2023 HLEDGER-UI(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2023}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{April 2023}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-WEB" "1" "March 2023" "hledger-web-1.29.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-WEB" "1" "April 2023" "hledger-web-1.29.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
@ -13,12 +13,12 @@ hledger-web(1)
|
||||
|
||||
hledger-web - robust, friendly plain text accounting (Web version)
|
||||
|
||||
‘hledger-web [OPTIONS] # run temporarily & browse’
|
||||
‘hledger-web --serve [OPTIONS] # run without stopping’
|
||||
‘hledger-web --serve-api [OPTIONS] # run JSON server only’
|
||||
‘hledger web -- [OPTIONS] [QUERYARGS]’ # start from hledger
|
||||
'hledger-web [OPTIONS] # run temporarily & browse'
|
||||
'hledger-web --serve [OPTIONS] # run without stopping'
|
||||
'hledger-web --serve-api [OPTIONS] # run JSON server only'
|
||||
'hledger web -- [OPTIONS] [QUERYARGS]' # start from hledger
|
||||
|
||||
This manual is for hledger’s web interface, version 1.29.99. See
|
||||
This manual is for hledger's web interface, version 1.29.99. See
|
||||
also the hledger manual for common concepts and file formats.
|
||||
|
||||
hledger is a robust, user-friendly, cross-platform set of programs
|
||||
@ -41,21 +41,21 @@ numbered backup of the main journal file (only) on every edit.
|
||||
|
||||
Like hledger, it reads data from one or more files in journal,
|
||||
timeclock, timedot, or CSV format. The default file is
|
||||
‘.hledger.journal’ in your home directory; this can be overridden with
|
||||
one or more ‘-f FILE’ options, or the ‘LEDGER_FILE’ environment
|
||||
'.hledger.journal' in your home directory; this can be overridden with
|
||||
one or more '-f FILE' options, or the 'LEDGER_FILE' environment
|
||||
variable. For more about this see hledger(1).
|
||||
|
||||
hledger-web can be run in three modes:
|
||||
|
||||
• Transient mode (the default): your default web browser will be
|
||||
* Transient mode (the default): your default web browser will be
|
||||
opened to show the app if possible, and the app exits automatically
|
||||
after two minutes of inactivity (no requests received and no open
|
||||
browser windows viewing it).
|
||||
|
||||
• With ‘--serve’: the app runs without stopping, and without opening
|
||||
* With '--serve': the app runs without stopping, and without opening
|
||||
a browser.
|
||||
|
||||
• With ‘--serve-api’: only the JSON API is served.
|
||||
* With '--serve-api': only the JSON API is served.
|
||||
|
||||
In all cases hledger-web runs as a foreground process, logging
|
||||
requests to stdout.
|
||||
@ -82,180 +82,180 @@ Command-line options and arguments may be used to set an initial filter
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
will be applied in addition to any search query entered there.
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write ‘--’
|
||||
Note: if invoking hledger-web as a hledger subcommand, write '--'
|
||||
before options, as shown in the synopsis above.
|
||||
|
||||
‘--serve’
|
||||
'--serve'
|
||||
|
||||
serve and log requests, don’t browse or auto-exit after timeout
|
||||
‘--serve-api’
|
||||
serve and log requests, don't browse or auto-exit after timeout
|
||||
'--serve-api'
|
||||
|
||||
like –serve, but serve only the JSON web API, without the
|
||||
like -serve, but serve only the JSON web API, without the
|
||||
server-side web UI
|
||||
‘--host=IPADDR’
|
||||
'--host=IPADDR'
|
||||
|
||||
listen on this IP address (default: 127.0.0.1)
|
||||
‘--port=PORT’
|
||||
'--port=PORT'
|
||||
|
||||
listen on this TCP port (default: 5000)
|
||||
‘--socket=SOCKETFILE’
|
||||
'--socket=SOCKETFILE'
|
||||
|
||||
use a unix domain socket file to listen for requests instead of a
|
||||
TCP socket. Implies ‘--serve’. It can only be used if the
|
||||
TCP socket. Implies '--serve'. It can only be used if the
|
||||
operating system can provide this type of socket.
|
||||
‘--base-url=URL’
|
||||
'--base-url=URL'
|
||||
|
||||
set the base url (default: http://IPADDR:PORT). Note: affects url
|
||||
generation but not route parsing. Can be useful if running behind
|
||||
a reverse web proxy that does path rewriting.
|
||||
‘--file-url=URL’
|
||||
'--file-url=URL'
|
||||
|
||||
set the static files url (default: BASEURL/static). hledger-web
|
||||
normally serves static files itself, but if you wanted to serve
|
||||
them from another server for efficiency, you would set the url with
|
||||
this.
|
||||
‘--capabilities=CAP[,CAP..]’
|
||||
'--capabilities=CAP[,CAP..]'
|
||||
|
||||
enable the view, add, and/or manage capabilities (default:
|
||||
view,add)
|
||||
‘--capabilities-header=HTTPHEADER’
|
||||
'--capabilities-header=HTTPHEADER'
|
||||
|
||||
read capabilities to enable from a HTTP header, like
|
||||
X-Sandstorm-Permissions (default: disabled)
|
||||
‘--test’
|
||||
'--test'
|
||||
|
||||
run hledger-web’s tests and exit. hspec test runner args may
|
||||
follow a –, eg: hledger-web –test – –help
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
follow a -, eg: hledger-web -test - -help
|
||||
|
||||
hledger input options:
|
||||
|
||||
‘-f FILE --file=FILE’
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)
|
||||
‘--rules-file=RULESFILE’
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
‘--separator=CHAR’
|
||||
'--separator=CHAR'
|
||||
|
||||
Field separator to expect when reading CSV (default: ’,’)
|
||||
‘--alias=OLD=NEW’
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
rename accounts named OLD to NEW
|
||||
‘--anon’
|
||||
'--anon'
|
||||
|
||||
anonymize accounts and payees
|
||||
‘--pivot FIELDNAME’
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
use some other field or tag for the account name
|
||||
‘-I --ignore-assertions’
|
||||
'-I --ignore-assertions'
|
||||
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
‘-s --strict’
|
||||
'-s --strict'
|
||||
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
‘-b --begin=DATE’
|
||||
'-b --begin=DATE'
|
||||
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
‘-e --end=DATE’
|
||||
'-e --end=DATE'
|
||||
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
‘-D --daily’
|
||||
'-D --daily'
|
||||
|
||||
multiperiod/multicolumn report by day
|
||||
‘-W --weekly’
|
||||
'-W --weekly'
|
||||
|
||||
multiperiod/multicolumn report by week
|
||||
‘-M --monthly’
|
||||
'-M --monthly'
|
||||
|
||||
multiperiod/multicolumn report by month
|
||||
‘-Q --quarterly’
|
||||
'-Q --quarterly'
|
||||
|
||||
multiperiod/multicolumn report by quarter
|
||||
‘-Y --yearly’
|
||||
'-Y --yearly'
|
||||
|
||||
multiperiod/multicolumn report by year
|
||||
‘-p --period=PERIODEXP’
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
‘--date2’
|
||||
'--date2'
|
||||
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
‘--today=DATE’
|
||||
'--today=DATE'
|
||||
|
||||
override today’s date (affects relative smart dates, for
|
||||
override today's date (affects relative smart dates, for
|
||||
tests/examples)
|
||||
‘-U --unmarked’
|
||||
'-U --unmarked'
|
||||
|
||||
include only unmarked postings/txns (can combine with -P or -C)
|
||||
‘-P --pending’
|
||||
'-P --pending'
|
||||
|
||||
include only pending postings/txns
|
||||
‘-C --cleared’
|
||||
'-C --cleared'
|
||||
|
||||
include only cleared postings/txns
|
||||
‘-R --real’
|
||||
'-R --real'
|
||||
|
||||
include only non-virtual postings
|
||||
‘-NUM --depth=NUM’
|
||||
'-NUM --depth=NUM'
|
||||
|
||||
hide/aggregate accounts or postings more than NUM levels deep
|
||||
‘-E --empty’
|
||||
'-E --empty'
|
||||
|
||||
show items with zero amount, normally hidden (and vice-versa in
|
||||
hledger-ui/hledger-web)
|
||||
‘-B --cost’
|
||||
'-B --cost'
|
||||
|
||||
convert amounts to their cost/selling amount at transaction time
|
||||
‘-V --market’
|
||||
'-V --market'
|
||||
|
||||
convert amounts to their market value in default valuation
|
||||
commodities
|
||||
‘-X --exchange=COMM’
|
||||
'-X --exchange=COMM'
|
||||
|
||||
convert amounts to their market value in commodity COMM
|
||||
‘--value’
|
||||
'--value'
|
||||
|
||||
convert amounts to cost or market value, more flexibly than
|
||||
-B/-V/-X
|
||||
‘--infer-market-prices’
|
||||
'--infer-market-prices'
|
||||
|
||||
use transaction prices (recorded with @ or @@) as additional market
|
||||
prices, as if they were P directives
|
||||
‘--auto’
|
||||
'--auto'
|
||||
|
||||
apply automated posting rules to modify transactions.
|
||||
‘--forecast’
|
||||
'--forecast'
|
||||
|
||||
generate future transactions from periodic transaction rules, for
|
||||
the next 6 months or till report end date. In hledger-ui, also
|
||||
make ordinary future transactions visible.
|
||||
‘--commodity-style’
|
||||
'--commodity-style'
|
||||
|
||||
Override the commodity style in the output for the specified
|
||||
commodity. For example ’EUR1.000,00’.
|
||||
‘--color=WHEN (or --colour=WHEN)’
|
||||
commodity. For example 'EUR1.000,00'.
|
||||
'--color=WHEN (or --colour=WHEN)'
|
||||
|
||||
Should color-supporting commands use ANSI color codes in text
|
||||
output. ’auto’ (default): whenever stdout seems to be a
|
||||
color-supporting terminal. ’always’ or ’yes’: always, useful eg
|
||||
when piping output into ’less -R’. ’never’ or ’no’: never. A
|
||||
output. 'auto' (default): whenever stdout seems to be a
|
||||
color-supporting terminal. 'always' or 'yes': always, useful eg
|
||||
when piping output into 'less -R'. 'never' or 'no': never. A
|
||||
NO_COLOR environment variable overrides this.
|
||||
‘--pretty[=WHEN]’
|
||||
'--pretty[=WHEN]'
|
||||
|
||||
Show prettier output, e.g. using unicode box-drawing characters.
|
||||
Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’
|
||||
also work). If you provide an argument you must use ’=’, e.g.
|
||||
’–pretty=yes’.
|
||||
Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'
|
||||
also work). If you provide an argument you must use '=', e.g.
|
||||
'-pretty=yes'.
|
||||
|
||||
When a reporting option appears more than once in the command line,
|
||||
the last one takes precedence.
|
||||
@ -264,53 +264,53 @@ the last one takes precedence.
|
||||
|
||||
hledger help options:
|
||||
|
||||
‘-h --help’
|
||||
'-h --help'
|
||||
|
||||
show general or COMMAND help
|
||||
‘--man’
|
||||
'--man'
|
||||
|
||||
show general or COMMAND user manual with man
|
||||
‘--info’
|
||||
'--info'
|
||||
|
||||
show general or COMMAND user manual with info
|
||||
‘--version’
|
||||
'--version'
|
||||
|
||||
show general or ADDONCMD version
|
||||
‘--debug[=N]’
|
||||
'--debug[=N]'
|
||||
|
||||
show debug output (levels 1-9, default: 1)
|
||||
|
||||
A @FILE argument will be expanded to the contents of FILE, which
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a ‘--’ argument before.)
|
||||
this, insert a '--' argument before.)
|
||||
|
||||
By default the server listens on IP address 127.0.0.1, accessible
|
||||
only to local requests. You can use ‘--host’ to change this, eg ‘--host
|
||||
0.0.0.0’ to listen on all configured addresses.
|
||||
only to local requests. You can use '--host' to change this, eg '--host
|
||||
0.0.0.0' to listen on all configured addresses.
|
||||
|
||||
Similarly, use ‘--port’ to set a TCP port other than 5000, eg if you
|
||||
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
||||
are running multiple hledger-web instances.
|
||||
|
||||
Both of these options are ignored when ‘--socket’ is used. In this
|
||||
case, it creates an ‘AF_UNIX’ socket file at the supplied path and uses
|
||||
Both of these options are ignored when '--socket' is used. In this
|
||||
case, it creates an 'AF_UNIX' socket file at the supplied path and uses
|
||||
that for communication. This is an alternative way of running multiple
|
||||
hledger-web instances behind a reverse proxy that handles authentication
|
||||
for different users. The path can be derived in a predictable way, eg
|
||||
by using the username within the path. As an example, ‘nginx’ as
|
||||
reverse proxy can use the variable ‘$remote_user’ to derive a path from
|
||||
by using the username within the path. As an example, 'nginx' as
|
||||
reverse proxy can use the variable '$remote_user' to derive a path from
|
||||
the username used in a HTTP basic authentication. The following
|
||||
‘proxy_pass’ directive allows access to all ‘hledger-web’ instances that
|
||||
created a socket in ‘/tmp/hledger/’:
|
||||
'proxy_pass' directive allows access to all 'hledger-web' instances that
|
||||
created a socket in '/tmp/hledger/':
|
||||
|
||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||
|
||||
You can use ‘--base-url’ to change the protocol, hostname, port and
|
||||
You can use '--base-url' to change the protocol, hostname, port and
|
||||
path that appear in hyperlinks, useful eg for integrating hledger-web
|
||||
within a larger website. The default is ‘http://HOST:PORT/’ using the
|
||||
server’s configured host address and TCP port (or ‘http://HOST’ if PORT
|
||||
within a larger website. The default is 'http://HOST:PORT/' using the
|
||||
server's configured host address and TCP port (or 'http://HOST' if PORT
|
||||
is 80).
|
||||
|
||||
With ‘--file-url’ you can set a different base url for static files,
|
||||
With '--file-url' you can set a different base url for static files,
|
||||
eg for better caching or cookie-less serving on high performance
|
||||
websites.
|
||||
|
||||
@ -325,28 +325,28 @@ journal and to add new transactions, but not to change existing data.
|
||||
|
||||
You can restrict who can reach it by
|
||||
|
||||
• setting the IP address it listens on (see ‘--host’ above). By
|
||||
* setting the IP address it listens on (see '--host' above). By
|
||||
default it listens on 127.0.0.1, accessible to all users on the
|
||||
local machine.
|
||||
• putting it behind an authenticating proxy, using eg apache or nginx
|
||||
• custom firewall rules
|
||||
* putting it behind an authenticating proxy, using eg apache or nginx
|
||||
* custom firewall rules
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
|
||||
• using the ‘--capabilities=CAP[,CAP..]’ flag when you start it,
|
||||
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is ‘view,add’:
|
||||
• ‘view’ - allows viewing the journal file and all included
|
||||
value is 'view,add':
|
||||
* 'view' - allows viewing the journal file and all included
|
||||
files
|
||||
• ‘add’ - allows adding new transactions to the main journal
|
||||
* 'add' - allows adding new transactions to the main journal
|
||||
file
|
||||
• ‘manage’ - allows editing, uploading or downloading the main
|
||||
* 'manage' - allows editing, uploading or downloading the main
|
||||
or included files
|
||||
|
||||
• using the ‘--capabilities-header=HTTPHEADER’ flag to specify a HTTP
|
||||
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
||||
with Sandstorm’s permissions. This is disabled by default.
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
|
||||
@ -354,7 +354,7 @@ File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING,
|
||||
3 EDITING, UPLOADING, DOWNLOADING
|
||||
*********************************
|
||||
|
||||
If you enable the ‘manage’ capability mentioned above, you’ll see a new
|
||||
If you enable the 'manage' capability mentioned above, you'll see a new
|
||||
"spanner" button to the right of the search form. Clicking this will
|
||||
let you edit, upload, or download the journal file or any files it
|
||||
includes.
|
||||
@ -365,7 +365,7 @@ visitor) can alter or wipe the data files.
|
||||
Normally whenever a file is changed in this way, hledger-web saves a
|
||||
numbered backup (assuming file permissions allow it, the disk is not
|
||||
full, etc.) hledger-web is not aware of version control systems,
|
||||
currently; if you use one, you’ll have to arrange to commit the changes
|
||||
currently; if you use one, you'll have to arrange to commit the changes
|
||||
yourself (eg with a cron job or a file watcher like entr).
|
||||
|
||||
Changes which would leave the journal file(s) unparseable or
|
||||
@ -395,7 +395,7 @@ File: hledger-web.info, Node: JSON API, Next: DEBUG OUTPUT, Prev: RELOADING,
|
||||
|
||||
In addition to the web UI, hledger-web also serves a JSON API that can
|
||||
be used to get data or add new transactions. If you want the JSON API
|
||||
only, you can use the ‘--serve-api’ flag. Eg:
|
||||
only, you can use the '--serve-api' flag. Eg:
|
||||
|
||||
$ hledger-web -f examples/sample.journal --serve-api
|
||||
...
|
||||
@ -411,7 +411,7 @@ $ hledger-web -f examples/sample.journal --serve-api
|
||||
/accounttransactions/ACCOUNTNAME
|
||||
|
||||
Eg, all account names in the journal (similar to the accounts
|
||||
command). (hledger-web’s JSON does not include newlines, here we use
|
||||
command). (hledger-web's JSON does not include newlines, here we use
|
||||
python to prettify it):
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||
@ -452,7 +452,7 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
"aprice": null,
|
||||
...
|
||||
|
||||
Most of the JSON corresponds to hledger’s data types; for details of
|
||||
Most of the JSON corresponds to hledger's data types; for details of
|
||||
what the fields mean, see the Hledger.Data.Json haddock docs and click
|
||||
on the various data types, eg Transaction. And for a higher level
|
||||
understanding, see the journal docs.
|
||||
@ -460,25 +460,25 @@ understanding, see the journal docs.
|
||||
In some cases there is outer JSON corresponding to a "Report" type.
|
||||
To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
|
||||
at the source for the appropriate handler to see what it returns. Eg
|
||||
for ‘/accounttransactions’ it’s getAccounttransactionsR, returning a
|
||||
"‘accountTransactionsReport ...’". Looking up the haddock for that we
|
||||
for '/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"'accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
can see that /accounttransactions returns an AccountTransactionsReport,
|
||||
which consists of a report title and a list of
|
||||
AccountTransactionsReportItem (etc).
|
||||
|
||||
You can add a new transaction to the journal with a PUT request to
|
||||
‘/add’, if hledger-web was started with the ‘add’ capability (enabled by
|
||||
'/add', if hledger-web was started with the 'add' capability (enabled by
|
||||
default). The payload must be the full, exact JSON representation of a
|
||||
hledger transaction (partial data won’t do). You can get sample JSON
|
||||
from hledger-web’s ‘/transactions’ or ‘/accounttransactions’, or you can
|
||||
hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's '/transactions' or '/accounttransactions', or you can
|
||||
export it with hledger-lib, eg like so:
|
||||
|
||||
.../hledger$ stack ghci hledger-lib
|
||||
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
|
||||
>>> :q
|
||||
|
||||
Here’s how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger’s Transaction and related data types):
|
||||
Here's how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger's Transaction and related data types):
|
||||
|
||||
{
|
||||
"tcomment": "",
|
||||
@ -566,7 +566,7 @@ corresponds to hledger’s Transaction and related data types):
|
||||
"tstatus": "Unmarked"
|
||||
}
|
||||
|
||||
And here’s how to test adding it with curl. This should add a new
|
||||
And here's how to test adding it with curl. This should add a new
|
||||
entry to your journal:
|
||||
|
||||
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
|
||||
@ -587,13 +587,13 @@ File: hledger-web.info, Node: Debug output, Up: DEBUG OUTPUT
|
||||
6.1 Debug output
|
||||
================
|
||||
|
||||
You can add ‘--debug[=N]’ to the command line to log debug output. N
|
||||
You can add '--debug[=N]' to the command line to log debug output. N
|
||||
ranges from 1 (least output, the default) to 9 (maximum output).
|
||||
Typically you would start with 1 and increase until you are seeing
|
||||
enough. Debug output goes to stderr, interleaved with the requests
|
||||
logged on stdout. To capture debug output in a log file instead, you
|
||||
can usually redirect stderr, eg:
|
||||
‘hledger-web --debug=3 2>hledger-web.log’.
|
||||
'hledger-web --debug=3 2>hledger-web.log'.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: DEBUG OUTPUT, Up: Top
|
||||
@ -601,33 +601,33 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: DEBUG OUTPUT,
|
||||
7 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with ‘-f’.
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
|
||||
On unix computers, the default value is: ‘~/.hledger.journal’.
|
||||
On unix computers, the default value is: '~/.hledger.journal'.
|
||||
|
||||
A more typical value is something like ‘~/finance/YYYY.journal’,
|
||||
where ‘~/finance’ is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, ‘~/finance/current.journal’, where
|
||||
A more typical value is something like '~/finance/YYYY.journal',
|
||||
where '~/finance' is a version-controlled finance directory and YYYY is
|
||||
the current year. Or, '~/finance/current.journal', where
|
||||
current.journal is a symbolic link to YYYY.journal.
|
||||
|
||||
The usual way to set this permanently is to add a command to one of
|
||||
your shell’s startup files (eg ‘~/.profile’):
|
||||
your shell's startup files (eg '~/.profile'):
|
||||
|
||||
export LEDGER_FILE=~/finance/current.journal`
|
||||
|
||||
On some Mac computers, there is a more thorough way to set
|
||||
environment variables, that will also affect applications started from
|
||||
the GUI (eg, Emacs started from a dock icon): In
|
||||
‘~/.MacOSX/environment.plist’, add an entry like:
|
||||
'~/.MacOSX/environment.plist', add an entry like:
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
For this to take effect you might need to ‘killall Dock’, or reboot.
|
||||
For this to take effect you might need to 'killall Dock', or reboot.
|
||||
|
||||
On Windows computers, the default value is probably
|
||||
‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a
|
||||
'C:\Users\YOURNAME\.hledger.journal'. You can change this by running a
|
||||
command like this in a powershell window (let us know if you need to be
|
||||
an Administrator, and if this persists across a reboot):
|
||||
|
||||
@ -643,9 +643,9 @@ File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
*******
|
||||
|
||||
Reads data from one or more files in journal, timeclock, timedot, or CSV
|
||||
format. The default file is ‘.hledger.journal’ in your home directory;
|
||||
this can be overridden with one or more ‘-f FILE’ options, or the
|
||||
‘LEDGER_FILE’ environment variable.
|
||||
format. The default file is '.hledger.journal' in your home directory;
|
||||
this can be overridden with one or more '-f FILE' options, or the
|
||||
'LEDGER_FILE' environment variable.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
@ -653,7 +653,7 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
9 BUGS
|
||||
******
|
||||
|
||||
‘-f-’ doesn’t work (hledger-web can’t read from stdin).
|
||||
'-f-' doesn't work (hledger-web can't read from stdin).
|
||||
|
||||
Query arguments and some hledger options are ignored.
|
||||
|
||||
@ -664,26 +664,26 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top
|
||||
|
||||
Tag Table:
|
||||
Node: Top225
|
||||
Node: OPTIONS2727
|
||||
Ref: #options2832
|
||||
Node: PERMISSIONS10626
|
||||
Ref: #permissions10765
|
||||
Node: EDITING UPLOADING DOWNLOADING12023
|
||||
Ref: #editing-uploading-downloading12204
|
||||
Node: RELOADING13046
|
||||
Ref: #reloading13180
|
||||
Node: JSON API13613
|
||||
Ref: #json-api13728
|
||||
Node: DEBUG OUTPUT19260
|
||||
Ref: #debug-output19385
|
||||
Node: Debug output19412
|
||||
Ref: #debug-output-119513
|
||||
Node: ENVIRONMENT19938
|
||||
Ref: #environment20058
|
||||
Node: FILES21407
|
||||
Ref: #files21507
|
||||
Node: BUGS21767
|
||||
Ref: #bugs21845
|
||||
Node: OPTIONS2683
|
||||
Ref: #options2788
|
||||
Node: PERMISSIONS10225
|
||||
Ref: #permissions10364
|
||||
Node: EDITING UPLOADING DOWNLOADING11576
|
||||
Ref: #editing-uploading-downloading11757
|
||||
Node: RELOADING12591
|
||||
Ref: #reloading12725
|
||||
Node: JSON API13158
|
||||
Ref: #json-api13273
|
||||
Node: DEBUG OUTPUT18761
|
||||
Ref: #debug-output18886
|
||||
Node: Debug output18913
|
||||
Ref: #debug-output-119014
|
||||
Node: ENVIRONMENT19431
|
||||
Ref: #environment19551
|
||||
Node: FILES20862
|
||||
Ref: #files20962
|
||||
Node: BUGS21210
|
||||
Ref: #bugs21288
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
@ -608,4 +608,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-web-1.29.99 March 2023 HLEDGER-WEB(1)
|
||||
hledger-web-1.29.99 April 2023 HLEDGER-WEB(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2023}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{April 2023}})m4_dnl
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
.\"t
|
||||
|
||||
.TH "HLEDGER" "1" "March 2023" "hledger-1.29.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER" "1" "April 2023" "hledger-1.29.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
@ -1038,7 +1038,19 @@ otherwise, please let us know.
|
||||
.IP \[bu] 2
|
||||
This is not yet much used; real-world feedback is welcome.
|
||||
.IP \[bu] 2
|
||||
SQL output is expected to work with sqlite, MySQL and PostgreSQL
|
||||
SQL output is expected to work at least with SQLite, MySQL and Postgres.
|
||||
.IP \[bu] 2
|
||||
For SQLite, it will be more useful if you modify the generated
|
||||
\f[V]id\f[R] field to be a PRIMARY KEY.
|
||||
Eg:
|
||||
.RS 2
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger print -O sql | sed \[aq]s/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g\[aq] | ...
|
||||
\f[R]
|
||||
.fi
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
SQL output is structured with the expectations that statements will be
|
||||
executed in the empty database.
|
||||
@ -1091,6 +1103,32 @@ if the \f[V]--pretty\f[R] option is given a value of \f[V]yes\f[R] or
|
||||
characters will (or will not) be used;
|
||||
.IP \[bu] 2
|
||||
otherwise, unicode characters will not be used.
|
||||
.SS Paging
|
||||
.PP
|
||||
When showing long output in the terminal, hledger will try to use the
|
||||
pager specified by the \f[V]PAGER\f[R] environment variable, or
|
||||
\f[V]less\f[R], or \f[V]more\f[R].
|
||||
(A pager is a helper program that shows one page at a time rather than
|
||||
scrolling everything off screen).
|
||||
Currently it does this only for help output, not for reports;
|
||||
specifically,
|
||||
.IP \[bu] 2
|
||||
when listing commands, with \f[V]hledger\f[R]
|
||||
.IP \[bu] 2
|
||||
when showing help with \f[V]hledger [CMD] --help\f[R],
|
||||
.IP \[bu] 2
|
||||
when viewing manuals with \f[V]hledger help\f[R] or
|
||||
\f[V]hledger --man\f[R].
|
||||
.PP
|
||||
Note the pager is expected to handle ANSI codes, which hledger uses eg
|
||||
for bold emphasis.
|
||||
For the common pager \f[V]less\f[R] (and its \f[V]more\f[R]
|
||||
compatibility mode), we add \f[V]R\f[R] to the \f[V]LESS\f[R] and
|
||||
\f[V]MORE\f[R] environment variables to make this work.
|
||||
If you use a different pager, you might need to configure it similarly,
|
||||
to avoid seeing junk on screen (let us know).
|
||||
Otherwise, you can set the \f[V]NO_COLOR\f[R] environment variable to 1
|
||||
to disable all ANSI output (see Colour).
|
||||
.SS Debug output
|
||||
.PP
|
||||
We intend hledger to be relatively easy to troubleshoot, introspect and
|
||||
@ -6067,41 +6105,25 @@ More complex intervals can be specified using \f[V]-p/--period\f[R],
|
||||
described below.
|
||||
.SS Date adjustment
|
||||
.PP
|
||||
With a report interval (other than daily), report start / end dates
|
||||
which have not been specified explicitly and in full (eg not
|
||||
\f[V]-b 2023-01-01\f[R], but \f[V]-b 2023-01\f[R] or \f[V]-b 2023\f[R]
|
||||
or unspecified) are considered flexible:
|
||||
When there is a report interval (other than daily), report start/end
|
||||
dates which have been inferred, eg from the journal, are automatically
|
||||
adjusted to natural period boundaries.
|
||||
This is convenient for producing simple periodic reports.
|
||||
More precisely:
|
||||
.IP \[bu] 2
|
||||
A flexible start date will be automatically adjusted earlier if needed
|
||||
to fall on a natural interval boundary.
|
||||
an inferred start date will be adjusted earlier if needed to fall on a
|
||||
natural period boundary
|
||||
.IP \[bu] 2
|
||||
Similarly, a flexible end date will be adjusted later if needed to make
|
||||
the last period a whole interval (the same length as the others).
|
||||
an inferred end date will be adjusted later if needed to make the last
|
||||
period the same length as the others.
|
||||
.PP
|
||||
This is convenient for producing clean periodic reports (this is
|
||||
traditional hledger behaviour).
|
||||
By contrast, fully-specified exact dates will not be adjusted (this is
|
||||
new in hledger 1.29).
|
||||
.PP
|
||||
An example: with a journal whose first date is 2023-01-10 and last date
|
||||
is 2023-03-20:
|
||||
.IP \[bu] 2
|
||||
\f[V]hledger bal -M -b 2023/1/15 -e 2023/3/10\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
The report periods will begin on the 15th day of each month, starting
|
||||
from 2023-01-15, and the last period\[aq]s last day will be 2023-03-09.
|
||||
(Exact start and end dates, neither is adjusted.)
|
||||
.IP \[bu] 2
|
||||
\f[V]hledger bal -M -b 2023-01 -e 2023-04\f[R] or
|
||||
\f[V]hledger bal -M\f[R]
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
The report periods will begin on the 1st of each month, starting from
|
||||
2023-01-01, and the last period\[aq]s last day will be 2023-03-31.
|
||||
(Flexible start and end dates, both are adjusted.)
|
||||
By contrast, start/end dates which have been specified explicitly, with
|
||||
\f[V]-b\f[R], \f[V]-e\f[R], \f[V]-p\f[R] or \f[V]date:\f[R], will not be
|
||||
adjusted (since hledger 1.29).
|
||||
This makes it possible to specify non-standard report periods, but it
|
||||
also means that if you are specifying a start date, you should pick one
|
||||
that\[aq]s on a period boundary if you want to see simple report period
|
||||
headings.
|
||||
.SS Period expressions
|
||||
.PP
|
||||
The \f[V]-p/--period\f[R] option specifies a period expression, which is
|
||||
@ -9935,51 +9957,73 @@ use the manual-review-and-mark-cleared phase as a reminder to check the
|
||||
latest assertions against real-world balances.
|
||||
.SS close
|
||||
.PP
|
||||
\f[V]close [--retain | --migrate | --open] [QUERY]\f[R]
|
||||
(equity)
|
||||
.PP
|
||||
By default: prints a transaction that zeroes out (\[dq]closes\[dq]) all
|
||||
accounts, transferring their balances to an equity account.
|
||||
Query arguments can be added to override the accounts selection.
|
||||
Three other modes are supported:
|
||||
Generate transactions which transfer account balances to and/or from
|
||||
another account (typically equity).
|
||||
This can be useful for migrating balances to a new journal file, or for
|
||||
merging earnings into equity at end of accounting period.
|
||||
.PP
|
||||
\f[V]--retain\f[R]: prints a transaction closing revenue and expense
|
||||
balances.
|
||||
This is traditionally done by businesses at the end of each accounting
|
||||
period; it is less necessary in personal and computer-based accounting,
|
||||
but it can help balance the accounting equation A=L+E.
|
||||
By default, it prints a transaction that zeroes out ALE accounts (asset,
|
||||
liability, equity accounts; this requires account types to be
|
||||
configured); or if ACCTQUERY is provided, the accounts matched by that.
|
||||
.PP
|
||||
\f[V]--migrate\f[R]: prints a transaction to close asset, liability and
|
||||
most equity balances, and another transaction to re-open them.
|
||||
This can be useful when starting a new file (for performance or data
|
||||
protection).
|
||||
Adding the closing transaction to the old file allows old and new files
|
||||
to be combined.
|
||||
\f[I](experimental)\f[R]
|
||||
.PP
|
||||
\f[V]--open\f[R]: as above, but prints just the opening transaction.
|
||||
This can be useful for starting a new file, leaving the old file
|
||||
unchanged.
|
||||
Similar to Ledger\[aq]s equity command.
|
||||
This command has four main modes, corresponding to the most common use
|
||||
cases:
|
||||
.IP "1." 3
|
||||
With \f[V]--close\f[R] (default), it prints a \[dq]closing balances\[dq]
|
||||
transaction that zeroes out ALE (asset, liability, equity) accounts by
|
||||
default (this requires account types to be inferred or declared); or,
|
||||
the accounts matched by the provided ACCTQUERY arguments.
|
||||
.IP "2." 3
|
||||
With \f[V]--open\f[R], it prints an opposite \[dq]opening balances\[dq]
|
||||
transaction that restores those balances from zero.
|
||||
This is similar to Ledger\[aq]s equity command.
|
||||
.IP "3." 3
|
||||
With \f[V]--migrate\f[R], it prints both the closing and opening
|
||||
transactions.
|
||||
This is the preferred way to migrate balances to a new file: run
|
||||
\f[V]hledger close --migrate\f[R], add the closing transaction at the
|
||||
end of the old file, and add the opening transaction at the start of the
|
||||
new file.
|
||||
The matching closing/opening transactions cancel each other out,
|
||||
preserving correct balances during multi-file reporting.
|
||||
.IP "4." 3
|
||||
With \f[V]--retain\f[R], it prints a \[dq]retain earnings\[dq]
|
||||
transaction that transfers RX (revenue and expense) balances to
|
||||
\f[V]equity:retained earnings\f[R].
|
||||
Businesses traditionally do this at the end of each accounting period;
|
||||
it is less necessary with computer-based accounting, but it could still
|
||||
be useful if you want to see the accounting equation (A=L+E) satisfied.
|
||||
.PP
|
||||
You can change the equity account name with \f[V]--close-acct ACCT\f[R].
|
||||
It defaults to \f[V]equity:retained earnings\f[R] with
|
||||
\f[V]--retain\f[R], or \f[V]equity:opening/closing balances\f[R]
|
||||
otherwise.
|
||||
In all modes, the defaults can be overridden:
|
||||
.IP \[bu] 2
|
||||
the transaction descriptions can be changed with
|
||||
\f[V]--close-desc=DESC\f[R] and \f[V]--open-desc=DESC\f[R]
|
||||
.IP \[bu] 2
|
||||
the account to transfer to/from can be changed with
|
||||
\f[V]--close-acct=ACCT\f[R] and \f[V]--open-acct=ACCT\f[R]
|
||||
.IP \[bu] 2
|
||||
the accounts to be closed/opened can be changed with \f[V]ACCTQUERY\f[R]
|
||||
(account query arguments).
|
||||
.PP
|
||||
You can change the transaction description(s) with
|
||||
\f[V]--close-desc \[aq]DESC\[aq]\f[R] and
|
||||
\f[V]--open-desc \[aq]DESC\[aq]\f[R].
|
||||
It defaults to \f[V]retain earnings\f[R] with \f[V]--retain\f[R], or
|
||||
\f[V]closing balances\f[R] and \f[V]opening balances\f[R] otherwise.
|
||||
.PP
|
||||
Just one posting to the equity account will be used by default, with an
|
||||
implicit amount.
|
||||
.PP
|
||||
With \f[V]--x/--explicit\f[R] the amount will be shown explicitly, and
|
||||
By default just one destination/source posting will be used, with its
|
||||
amount left implicit.
|
||||
With \f[V]--x/--explicit\f[R], the amount will be shown explicitly, and
|
||||
if it involves multiple commodities, a separate posting will be
|
||||
generated for each commodity.
|
||||
generated for each of them (similar to \f[V]print -x\f[R]).
|
||||
.PP
|
||||
With \f[V]--interleaved\f[R], each equity posting is shown next to the
|
||||
corresponding source/destination posting.
|
||||
With \f[V]--show-costs\f[R], any amount costs are shown, with separate
|
||||
postings for each cost.
|
||||
This is currently the best way to view investment lots.
|
||||
If you have many currency conversion or investment transactions, it can
|
||||
generate very large journal entries.
|
||||
.PP
|
||||
With \f[V]--interleaved\f[R], each individual transfer is shown with
|
||||
source and destination postings next to each other.
|
||||
This could be useful for troubleshooting.
|
||||
.PP
|
||||
The default closing date is yesterday, or the journal\[aq]s end date,
|
||||
whichever is later.
|
||||
@ -9988,14 +10032,6 @@ date does not matter.)
|
||||
The last day of the report period will be the closing date; eg
|
||||
\f[V]-e 2022\f[R] means \[dq]close on 2022-12-31\[dq].
|
||||
The opening date is always the day after the closing date.
|
||||
.SS close and costs
|
||||
.PP
|
||||
With \f[V]--show-costs\f[R], any amount costs are shown, with separate
|
||||
postings for each cost.
|
||||
(This currently the best way to view investment assets, showing lots and
|
||||
cost bases.)
|
||||
If you have many currency conversion or investment transactions, it can
|
||||
generate very large journal entries.
|
||||
.SS close and balance assertions
|
||||
.PP
|
||||
Balance assertions will be generated, verifying that the accounts have
|
||||
@ -10049,9 +10085,9 @@ $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Now 2022\[aq]s income statement will show only zeroes.
|
||||
To see it again, exclude the retain transaction.
|
||||
Eg:
|
||||
Note 2022\[aq]s income statement will now show only zeroes, because
|
||||
revenues and expenses have been moved entirely to equity.
|
||||
To see them again, you could exclude the retain transaction:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
@ -10075,8 +10111,8 @@ Now 2022\[aq]s balance sheet will show only zeroes, indicating a
|
||||
balanced accounting equation.
|
||||
(Unless you are using \[at]/\[at]\[at] notation - in that case, try
|
||||
adding --infer-equity.)
|
||||
To see it again, exclude the closing transaction.
|
||||
Eg:
|
||||
To see the end-of-year balances again, you could exclude the closing
|
||||
transaction:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
@ -10086,13 +10122,16 @@ $ hledger -f 2022.journal bs not:desc:\[aq]closing balances\[aq]
|
||||
.SS Example: excluding closing/opening transactions
|
||||
.PP
|
||||
When combining many files for multi-year reports, the closing/opening
|
||||
transactions cause some noise in reports like \f[V]print\f[R] and
|
||||
\f[V]register\f[R].
|
||||
You can exclude them as shown above, but \f[V]not:desc:...\f[R] could be
|
||||
fragile, and also you will need to avoid excluding the very first
|
||||
opening transaction, which can be awkward.
|
||||
Here is a way to do it, using tags: add \f[V]clopen:\f[R] tags to all
|
||||
opening/closing balances transactions except the first, like this:
|
||||
transactions cause some noise in transaction-oriented reports like
|
||||
\f[V]print\f[R] and \f[V]register\f[R].
|
||||
You can exclude them as shown above, but \f[V]not:desc:...\f[R] is not
|
||||
ideal as it depends on consistent descriptions; also you will want to
|
||||
avoid excluding the very first opening transaction, which could be
|
||||
awkward.
|
||||
Here is one alternative, using tags:
|
||||
.PP
|
||||
Add \f[V]clopen:\f[R] tags to all opening/closing balances transactions
|
||||
except the first, like this:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
|
||||
4869
hledger/hledger.info
4869
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
1831
hledger/hledger.txt
1831
hledger/hledger.txt
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user