mirror of
https://github.com/simonmichael/hledger.git
synced 2024-07-08 19:36:27 +03:00
;dev: doc: update manuals
This commit is contained in:
Simon Michael
parent
31de526872
commit
b8f0900edb
8
dir
8
dir
|
|
@ -15,8 +15,6 @@ File: dir, Node: Top This is the top of the INFO tree
|
|||
* Menu:
|
||||
|
||||
User Applications
|
||||
* hledger: (hledger/hledger). Command-line plain text accounting tool.
|
||||
* hledger-ui: (hledger-ui/hledger-ui).
|
||||
Terminal UI for the hledger accounting tool.
|
||||
* hledger-web: (hledger-web/hledger-web).
|
||||
Web UI/API for the hledger accounting tool.
|
||||
* hledger: (hledger/hledger). Command-line plain text accounting tool.
|
||||
* hledger-ui: (hledger-ui/hledger-ui). Terminal UI for the hledger accounting tool.
|
||||
* hledger-web: (hledger-web/hledger-web). Web UI/API for the hledger accounting tool.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
This is hledger-ui.info, produced by makeinfo version 6.7 from stdin.
|
||||
This is hledger-ui/hledger-ui.info, produced by makeinfo version 4.8
|
||||
from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
|
|
@ -6,36 +7,36 @@ START-INFO-DIR-ENTRY
|
|||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
|
||||
File: hledger-ui.info, Node: Top, Up: (dir)
|
||||
|
||||
hledger-ui(1)
|
||||
*************
|
||||
|
||||
hledger-ui is a terminal interface (TUI) for the hledger accounting
|
||||
tool. This manual is for hledger-ui 1.22.
|
||||
tool. This manual is for hledger-ui 1.22.
|
||||
|
||||
'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".
|
||||
|
||||
|
|
@ -54,146 +55,143 @@ 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')
|
||||
'--rules-file=RULESFILE'
|
||||
`-f FILE --file=FILE'
|
||||
use a different input file. For stdin, use - (default:
|
||||
`$LEDGER_FILE' or `$HOME/.hledger.journal')
|
||||
|
||||
`--rules-file=RULESFILE'
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
'--separator=CHAR'
|
||||
|
||||
`--separator=CHAR'
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
`--alias=OLD=NEW'
|
||||
rename accounts named OLD to NEW
|
||||
'--anon'
|
||||
|
||||
`--anon'
|
||||
anonymize accounts and payees
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
`--pivot FIELDNAME'
|
||||
use some other field or tag for the account name
|
||||
'-I --ignore-assertions'
|
||||
|
||||
`-I --ignore-assertions'
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
'-s --strict'
|
||||
|
||||
`-s --strict'
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
'-b --begin=DATE'
|
||||
|
||||
`-b --begin=DATE'
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
'-e --end=DATE'
|
||||
|
||||
`-e --end=DATE'
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
'-D --daily'
|
||||
|
||||
`-D --daily'
|
||||
multiperiod/multicolumn report by day
|
||||
'-W --weekly'
|
||||
|
||||
`-W --weekly'
|
||||
multiperiod/multicolumn report by week
|
||||
'-M --monthly'
|
||||
|
||||
`-M --monthly'
|
||||
multiperiod/multicolumn report by month
|
||||
'-Q --quarterly'
|
||||
|
||||
`-Q --quarterly'
|
||||
multiperiod/multicolumn report by quarter
|
||||
'-Y --yearly'
|
||||
|
||||
`-Y --yearly'
|
||||
multiperiod/multicolumn report by year
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
`-p --period=PERIODEXP'
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
'--date2'
|
||||
|
||||
`--date2'
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
'-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,
|
||||
|
|
@ -203,25 +201,24 @@ the last one takes precedence.
|
|||
|
||||
hledger help options:
|
||||
|
||||
'-h --help'
|
||||
|
||||
`-h --help'
|
||||
show general or COMMAND help
|
||||
'--man'
|
||||
|
||||
`--man'
|
||||
show general or COMMAND user manual with man
|
||||
'--info'
|
||||
|
||||
`--info'
|
||||
show general or COMMAND user manual with info
|
||||
'--version'
|
||||
|
||||
`--version'
|
||||
show general or ADDONCMD version
|
||||
'--debug[=N]'
|
||||
|
||||
`--debug[=N]'
|
||||
show debug output (levels 1-9, default: 1)
|
||||
|
||||
A @FILE argument will be expanded to the contents of FILE, which
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a '--' argument before.)
|
||||
should contain one command line option/argument per line. (To prevent
|
||||
this, insert a `--' argument before.)
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top
|
||||
|
|
@ -229,94 +226,94 @@ 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.
|
||||
|
||||
With '--watch' active, if you save an edit to the journal file while
|
||||
viewing the transaction screen in cost or value mode, the 'B'/'V' keys
|
||||
will stop working. To work around, press 'g' to force a manual reload,
|
||||
With `--watch' active, if you save an edit to the journal file while
|
||||
viewing the transaction screen in cost or value mode, the `B'/`V' keys
|
||||
will stop working. To work around, press `g' to force a manual reload,
|
||||
or exit the transaction screen.
|
||||
|
||||
'q' quits the application.
|
||||
`q' quits the application.
|
||||
|
||||
Additional screen-specific keys are described below.
|
||||
|
||||
|
|
@ -339,48 +336,47 @@ 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
|
||||
|
|
@ -389,44 +385,46 @@ File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev:
|
|||
===================
|
||||
|
||||
This screen shows the transactions affecting a particular account, like
|
||||
a check register. Each line represents one transaction and shows:
|
||||
a check register. Each line represents one transaction and shows:
|
||||
|
||||
* the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts affected
|
||||
by real postings.)
|
||||
* the other account(s) involved, in abbreviated form. (If there are
|
||||
both real and virtual postings, it shows only the accounts
|
||||
affected by real postings.)
|
||||
|
||||
* the overall change to the current account's balance; positive for
|
||||
an inflow to this account, negative for an outflow.
|
||||
|
||||
* the running historical total or period total for the current
|
||||
account, after the transaction. This can be toggled with 'H'.
|
||||
Similar to the accounts screen, the historical total is affected by
|
||||
transactions (filtered by the filter query) before the report start
|
||||
date, while the period total is not. If the historical total is
|
||||
not disturbed by a filter query, it will be the running historical
|
||||
balance you would see on a bank register for the current account.
|
||||
account, after the transaction. This can be toggled with `H'.
|
||||
Similar to the accounts screen, the historical total is affected
|
||||
by transactions (filtered by the filter query) before the report
|
||||
start date, while the period total is not. If the historical total
|
||||
is not disturbed by a filter query, it will be the running
|
||||
historical balance you would see on a bank register for the
|
||||
current account.
|
||||
|
||||
|
||||
Transactions affecting this account's subaccounts will be included in
|
||||
the register if the accounts screen is in tree mode, or if it's in list
|
||||
mode but this account has subaccounts which are not shown due to a depth
|
||||
limit. In other words, the register always shows the transactions
|
||||
contributing to the balance shown on the accounts screen. Tree
|
||||
mode/list mode can be toggled with 't' here also.
|
||||
limit. In other words, the register always shows the transactions
|
||||
contributing to the balance shown on the accounts screen. Tree mode/list
|
||||
mode can be toggled with `t' here also.
|
||||
|
||||
'U' toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, 'P' toggles pending transactions, and 'C'
|
||||
toggles cleared transactions. (By default, transactions with all
|
||||
`U' toggles filtering by unmarked status, showing or hiding unmarked
|
||||
transactions. Similarly, `P' toggles pending transactions, and `C'
|
||||
toggles cleared transactions. (By default, transactions with all
|
||||
statuses are shown; if you activate one or two status filters, only
|
||||
those transactions are shown; and if you activate all three, the filter
|
||||
is removed.)
|
||||
|
||||
'R' toggles real mode, in which virtual postings are ignored.
|
||||
`R' toggles real mode, in which virtual postings are ignored.
|
||||
|
||||
'Z' toggles nonzero mode, in which only transactions posting a
|
||||
`Z' toggles nonzero mode, in which only transactions posting a
|
||||
nonzero change are shown (hledger-ui shows zero items by default, unlike
|
||||
command-line hledger).
|
||||
|
||||
Press 'right' (or 'enter') to view the selected transaction in
|
||||
Press `right' (or `enter') to view the selected transaction in
|
||||
detail.
|
||||
|
||||
|
||||
|
|
@ -444,11 +442,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).
|
||||
|
|
@ -460,8 +458,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.)
|
||||
|
||||
|
||||
|
|
@ -470,27 +468,28 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: SCREENS, Up: To
|
|||
4 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
|
||||
|
|
@ -499,9 +498,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
|
||||
|
|
@ -509,18 +508,18 @@ File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
|
|||
6 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,
|
||||
|
|
@ -529,30 +528,31 @@ 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: OPTIONS1646
|
||||
Ref: #options1743
|
||||
Node: KEYS6144
|
||||
Ref: #keys6239
|
||||
Node: SCREENS10558
|
||||
Ref: #screens10663
|
||||
Node: Accounts screen10753
|
||||
Ref: #accounts-screen10881
|
||||
Node: Register screen13096
|
||||
Ref: #register-screen13251
|
||||
Node: Transaction screen15248
|
||||
Ref: #transaction-screen15406
|
||||
Node: Error screen16276
|
||||
Ref: #error-screen16398
|
||||
Node: ENVIRONMENT16642
|
||||
Ref: #environment16756
|
||||
Node: FILES17563
|
||||
Ref: #files17662
|
||||
Node: BUGS17875
|
||||
Ref: #bugs17952
|
||||
Node: Top243
|
||||
Node: OPTIONS1636
|
||||
Ref: #options1733
|
||||
Node: KEYS6128
|
||||
Ref: #keys6223
|
||||
Node: SCREENS10519
|
||||
Ref: #screens10624
|
||||
Node: Accounts screen10714
|
||||
Ref: #accounts-screen10842
|
||||
Node: Register screen13046
|
||||
Ref: #register-screen13201
|
||||
Node: Transaction screen15196
|
||||
Ref: #transaction-screen15354
|
||||
Node: Error screen16221
|
||||
Ref: #error-screen16343
|
||||
Node: ENVIRONMENT16585
|
||||
Ref: #environment16699
|
||||
Node: FILES17504
|
||||
Ref: #files17603
|
||||
Node: BUGS17816
|
||||
Ref: #bugs17893
|
||||
|
||||
End Tag Table
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
This is hledger-web.info, produced by makeinfo version 6.7 from stdin.
|
||||
This is hledger-web/hledger-web.info, produced by makeinfo version 4.8
|
||||
from stdin.
|
||||
|
||||
INFO-DIR-SECTION User Applications
|
||||
START-INFO-DIR-ENTRY
|
||||
|
|
@ -6,7 +7,7 @@ START-INFO-DIR-ENTRY
|
|||
END-INFO-DIR-ENTRY
|
||||
|
||||
|
||||
File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
|
||||
File: hledger-web.info, Node: Top, Up: (dir)
|
||||
|
||||
hledger-web(1)
|
||||
**************
|
||||
|
|
@ -14,32 +15,31 @@ hledger-web(1)
|
|||
hledger-web is a web interface (WUI) for the hledger accounting tool.
|
||||
This manual is for hledger-web 1.22.
|
||||
|
||||
'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,168 +59,165 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
|
|||
*********
|
||||
|
||||
Command-line options and arguments may be used to set an initial filter
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
on the data. These filter options are not shown in the web UI, but it
|
||||
will be applied in addition to any search query entered there.
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write '--'
|
||||
Note: if invoking hledger-web as a hledger subcommand, write `--'
|
||||
before options, as shown in the synopsis above.
|
||||
|
||||
'--serve'
|
||||
|
||||
`--serve'
|
||||
serve and log requests, don't browse or auto-exit
|
||||
'--serve-api'
|
||||
|
||||
`--serve-api'
|
||||
like -serve, but serve only the JSON web API, without the
|
||||
server-side web UI
|
||||
'--host=IPADDR'
|
||||
|
||||
`--host=IPADDR'
|
||||
listen on this IP address (default: 127.0.0.1)
|
||||
'--port=PORT'
|
||||
|
||||
`--port=PORT'
|
||||
listen on this TCP port (default: 5000)
|
||||
'--socket=SOCKETFILE'
|
||||
|
||||
`--socket=SOCKETFILE'
|
||||
use a unix domain socket file to listen for requests instead of a
|
||||
TCP socket. Implies '--serve'. It can only be used if the
|
||||
operating system can provide this type of socket.
|
||||
'--base-url=URL'
|
||||
TCP socket. Implies `--serve'. It can only be used if the operating
|
||||
system can provide this type of socket.
|
||||
|
||||
`--base-url=URL'
|
||||
set the base url (default: http://IPADDR:PORT). You would change
|
||||
this when sharing over the network, or integrating within a larger
|
||||
website.
|
||||
'--file-url=URL'
|
||||
|
||||
set the static files url (default: BASEURL/static). hledger-web
|
||||
`--file-url=URL'
|
||||
set the static files url (default: BASEURL/static). hledger-web
|
||||
normally serves static files itself, but if you wanted to serve
|
||||
them from another server for efficiency, you would set the url with
|
||||
this.
|
||||
'--capabilities=CAP[,CAP..]'
|
||||
them from another server for efficiency, you would set the url
|
||||
with this.
|
||||
|
||||
`--capabilities=CAP[,CAP..]'
|
||||
enable the view, add, and/or manage capabilities (default:
|
||||
view,add)
|
||||
'--capabilities-header=HTTPHEADER'
|
||||
|
||||
`--capabilities-header=HTTPHEADER'
|
||||
read capabilities to enable from a HTTP header, like
|
||||
X-Sandstorm-Permissions (default: disabled)
|
||||
'--test'
|
||||
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
`--test'
|
||||
run hledger-web's tests and exit. hspec test runner args may
|
||||
follow a -, eg: hledger-web -test - -help
|
||||
|
||||
hledger input options:
|
||||
|
||||
'-f FILE --file=FILE'
|
||||
|
||||
use a different input file. For stdin, use - (default:
|
||||
'$LEDGER_FILE' or '$HOME/.hledger.journal')
|
||||
'--rules-file=RULESFILE'
|
||||
`-f FILE --file=FILE'
|
||||
use a different input file. For stdin, use - (default:
|
||||
`$LEDGER_FILE' or `$HOME/.hledger.journal')
|
||||
|
||||
`--rules-file=RULESFILE'
|
||||
Conversion rules file to use when reading CSV (default: FILE.rules)
|
||||
'--separator=CHAR'
|
||||
|
||||
`--separator=CHAR'
|
||||
Field separator to expect when reading CSV (default: ',')
|
||||
'--alias=OLD=NEW'
|
||||
|
||||
`--alias=OLD=NEW'
|
||||
rename accounts named OLD to NEW
|
||||
'--anon'
|
||||
|
||||
`--anon'
|
||||
anonymize accounts and payees
|
||||
'--pivot FIELDNAME'
|
||||
|
||||
`--pivot FIELDNAME'
|
||||
use some other field or tag for the account name
|
||||
'-I --ignore-assertions'
|
||||
|
||||
`-I --ignore-assertions'
|
||||
disable balance assertion checks (note: does not disable balance
|
||||
assignments)
|
||||
'-s --strict'
|
||||
|
||||
`-s --strict'
|
||||
do extra error checking (check that all posted accounts are
|
||||
declared)
|
||||
|
||||
hledger reporting options:
|
||||
|
||||
'-b --begin=DATE'
|
||||
|
||||
`-b --begin=DATE'
|
||||
include postings/txns on or after this date (will be adjusted to
|
||||
preceding subperiod start when using a report interval)
|
||||
'-e --end=DATE'
|
||||
|
||||
`-e --end=DATE'
|
||||
include postings/txns before this date (will be adjusted to
|
||||
following subperiod end when using a report interval)
|
||||
'-D --daily'
|
||||
|
||||
`-D --daily'
|
||||
multiperiod/multicolumn report by day
|
||||
'-W --weekly'
|
||||
|
||||
`-W --weekly'
|
||||
multiperiod/multicolumn report by week
|
||||
'-M --monthly'
|
||||
|
||||
`-M --monthly'
|
||||
multiperiod/multicolumn report by month
|
||||
'-Q --quarterly'
|
||||
|
||||
`-Q --quarterly'
|
||||
multiperiod/multicolumn report by quarter
|
||||
'-Y --yearly'
|
||||
|
||||
`-Y --yearly'
|
||||
multiperiod/multicolumn report by year
|
||||
'-p --period=PERIODEXP'
|
||||
|
||||
`-p --period=PERIODEXP'
|
||||
set start date, end date, and/or reporting interval all at once
|
||||
using period expressions syntax
|
||||
'--date2'
|
||||
|
||||
`--date2'
|
||||
match the secondary date instead (see command help for other
|
||||
effects)
|
||||
'-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,
|
||||
|
|
@ -230,62 +227,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.
|
||||
|
||||
|
|
@ -300,28 +297,32 @@ journal and to add new transactions, but not to change existing data.
|
|||
|
||||
You can restrict who can reach it by
|
||||
|
||||
* setting the IP address it listens on (see '--host' above). By
|
||||
* setting the IP address it listens on (see `--host' above). By
|
||||
default it listens on 127.0.0.1, accessible to all users on the
|
||||
local machine.
|
||||
|
||||
* putting it behind an authenticating proxy, using eg apache or nginx
|
||||
|
||||
* custom firewall rules
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
|
||||
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is 'view,add':
|
||||
* 'view' - allows viewing the journal file and all included
|
||||
* using the `--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is `view,add':
|
||||
* `view' - allows viewing the journal file and all included
|
||||
files
|
||||
* 'add' - allows adding new transactions to the main journal
|
||||
|
||||
* `add' - allows adding new transactions to the main journal
|
||||
file
|
||||
* 'manage' - allows editing, uploading or downloading the main
|
||||
|
||||
* `manage' - allows editing, uploading or downloading the main
|
||||
or included files
|
||||
|
||||
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
* using the `--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
|
||||
|
|
@ -329,8 +330,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.
|
||||
|
||||
|
|
@ -339,13 +340,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
|
||||
|
|
@ -355,7 +356,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.
|
||||
|
||||
|
|
@ -369,14 +370,16 @@ File: hledger-web.info, Node: JSON API, Next: ENVIRONMENT, Prev: RELOADING,
|
|||
**********
|
||||
|
||||
In addition to the web UI, hledger-web also serves a JSON API that can
|
||||
be used to get data or add new transactions. If you want the JSON API
|
||||
only, you can use the '--serve-api' flag. Eg:
|
||||
be used to get data or add new transactions. If you want the JSON API
|
||||
only, you can use the `--serve-api' flag. Eg:
|
||||
|
||||
|
||||
$ hledger-web -f examples/sample.journal --serve-api
|
||||
...
|
||||
|
||||
You can get JSON data from these routes:
|
||||
|
||||
|
||||
/version
|
||||
/accountnames
|
||||
/transactions
|
||||
|
|
@ -389,6 +392,7 @@ $ hledger-web -f examples/sample.journal --serve-api
|
|||
command). (hledger-web's JSON does not include newlines, here we use
|
||||
python to prettify it):
|
||||
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
||||
[
|
||||
"assets",
|
||||
|
|
@ -408,6 +412,7 @@ $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
|
|||
|
||||
Or all transactions:
|
||||
|
||||
|
||||
$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
||||
[
|
||||
{
|
||||
|
|
@ -429,24 +434,25 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
|
|||
|
||||
Most of the JSON corresponds to hledger's data types; for details of
|
||||
what the fields mean, see the Hledger.Data.Json haddock docs and click
|
||||
on the various data types, eg Transaction. And for a higher level
|
||||
on the various data types, eg Transaction. And for a higher level
|
||||
understanding, see the journal manual.
|
||||
|
||||
In some cases there is outer JSON corresponding to a "Report" type.
|
||||
To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
|
||||
at the source for the appropriate handler to see what it returns. Eg
|
||||
for '/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"'accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
To understand that, go to the Hledger.Web.Handler.MiscR haddock and
|
||||
look at the source for the appropriate handler to see what it returns.
|
||||
Eg for `/accounttransactions' it's getAccounttransactionsR, returning a
|
||||
"`accountTransactionsReport ...'". Looking up the haddock for that we
|
||||
can see that /accounttransactions returns an AccountTransactionsReport,
|
||||
which consists of a report title and a list of
|
||||
AccountTransactionsReportItem (etc).
|
||||
|
||||
You can add a new transaction to the journal with a PUT request to
|
||||
'/add', if hledger-web was started with the 'add' capability (enabled by
|
||||
default). The payload must be the full, exact JSON representation of a
|
||||
hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's '/transactions' or '/accounttransactions', or you can
|
||||
export it with hledger-lib, eg like so:
|
||||
`/add', if hledger-web was started with the `add' capability (enabled
|
||||
by default). The payload must be the full, exact JSON representation of
|
||||
a hledger transaction (partial data won't do). You can get sample JSON
|
||||
from hledger-web's `/transactions' or `/accounttransactions', or you
|
||||
can export it with hledger-lib, eg like so:
|
||||
|
||||
|
||||
.../hledger$ stack ghci hledger-lib
|
||||
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
|
||||
|
|
@ -455,6 +461,7 @@ export it with hledger-lib, eg like so:
|
|||
Here's how it looks as of hledger-1.17 (remember, this JSON
|
||||
corresponds to hledger's Transaction and related data types):
|
||||
|
||||
|
||||
{
|
||||
"tcomment": "",
|
||||
"tpostings": [
|
||||
|
|
@ -541,9 +548,10 @@ corresponds to hledger's Transaction and related data types):
|
|||
"tstatus": "Unmarked"
|
||||
}
|
||||
|
||||
And here's how to test adding it with curl. This should add a new
|
||||
And here's how to test adding it with curl. This should add a new
|
||||
entry to your journal:
|
||||
|
||||
|
||||
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
|
||||
|
||||
|
||||
|
|
@ -552,25 +560,26 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up:
|
|||
6 ENVIRONMENT
|
||||
*************
|
||||
|
||||
*LEDGER_FILE* The journal file path when not specified with '-f'.
|
||||
Default: '~/.hledger.journal' (on windows, perhaps
|
||||
'C:/Users/USER/.hledger.journal').
|
||||
*LEDGER_FILE* The journal file path when not specified with `-f'.
|
||||
Default: `~/.hledger.journal' (on windows, perhaps
|
||||
`C:/Users/USER/.hledger.journal').
|
||||
|
||||
A typical value is '~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
'~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
A typical value is `~/DIR/YYYY.journal', where DIR is a
|
||||
version-controlled finance directory and YYYY is the current year. Or
|
||||
`~/DIR/current.journal', where current.journal is a symbolic link to
|
||||
YYYY.journal.
|
||||
|
||||
On Mac computers, you can set this and other environment variables in
|
||||
a more thorough way that also affects applications started from the GUI
|
||||
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
'~/.MacOSX/environment.plist' file containing
|
||||
On Mac computers, you can set this and other environment variables
|
||||
in a more thorough way that also affects applications started from the
|
||||
GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
|
||||
`~/.MacOSX/environment.plist' file containing
|
||||
|
||||
|
||||
{
|
||||
"LEDGER_FILE" : "~/finance/current.journal"
|
||||
}
|
||||
|
||||
To see the effect you may need to 'killall Dock', or reboot.
|
||||
To see the effect you may need to `killall Dock', or reboot.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
|
|
@ -579,9 +588,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
|
||||
|
|
@ -589,10 +598,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.
|
||||
|
||||
|
|
@ -600,24 +609,25 @@ awkward.
|
|||
|
||||
Does not work well on small screens.
|
||||
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top235
|
||||
Node: OPTIONS1898
|
||||
Ref: #options2003
|
||||
Node: PERMISSIONS9436
|
||||
Ref: #permissions9575
|
||||
Node: EDITING UPLOADING DOWNLOADING10787
|
||||
Ref: #editing-uploading-downloading10968
|
||||
Node: RELOADING11802
|
||||
Ref: #reloading11936
|
||||
Node: JSON API12369
|
||||
Ref: #json-api12483
|
||||
Node: ENVIRONMENT17973
|
||||
Ref: #environment18089
|
||||
Node: FILES18822
|
||||
Ref: #files18922
|
||||
Node: BUGS19135
|
||||
Ref: #bugs19213
|
||||
Node: Top247
|
||||
Node: OPTIONS1887
|
||||
Ref: #options1992
|
||||
Node: PERMISSIONS9405
|
||||
Ref: #permissions9544
|
||||
Node: EDITING UPLOADING DOWNLOADING10756
|
||||
Ref: #editing-uploading-downloading10937
|
||||
Node: RELOADING11768
|
||||
Ref: #reloading11902
|
||||
Node: JSON API12334
|
||||
Ref: #json-api12448
|
||||
Node: ENVIRONMENT17937
|
||||
Ref: #environment18053
|
||||
Node: FILES18785
|
||||
Ref: #files18885
|
||||
Node: BUGS19098
|
||||
Ref: #bugs19176
|
||||
|
||||
End Tag Table
|
||||
|
|
|
|||
|
|
@ -3676,124 +3676,259 @@ close, equity
|
|||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
Prints a \[dq]closing balances\[dq] transaction and an \[dq]opening
|
||||
balances\[dq] transaction that bring account balances to and from zero,
|
||||
respectively.
|
||||
These can be added to your journal file(s), eg to bring asset/liability
|
||||
balances forward into a new journal file, or to close out
|
||||
revenues/expenses to retained earnings at the end of a period.
|
||||
Prints a sample \[dq]closing\[dq] transaction bringing specified account
|
||||
balances to zero, and an inverse \[dq]opening\[dq] transaction restoring
|
||||
the same account balances.
|
||||
.PP
|
||||
You can print just one of these transactions by using the
|
||||
\f[C]--close\f[R] or \f[C]--open\f[R] flag.
|
||||
You can customise their descriptions with the \f[C]--close-desc\f[R] and
|
||||
\f[C]--open-desc\f[R] options.
|
||||
If like most people you split your journal files by time, eg by year: at
|
||||
the end of the year you can use this command to \[dq]close out\[dq] your
|
||||
asset and liability (and perhaps equity) balances in the old file, and
|
||||
reinitialise them in the new file.
|
||||
This helps ensure that report balances remain correct whether you are
|
||||
including old files or not.
|
||||
(Because all closing/opening transactions except the very first will
|
||||
cancel out - see example below.)
|
||||
.PP
|
||||
One amountless posting to \[dq]equity:opening/closing balances\[dq] is
|
||||
added to balance the transactions, by default.
|
||||
You can customise this account name with \f[C]--close-acct\f[R] and
|
||||
\f[C]--open-acct\f[R]; if you specify only one of these, it will be used
|
||||
for both.
|
||||
Some people also use this command to close out revenue and expense
|
||||
balances at the end of an accounting period.
|
||||
This properly records the period\[aq]s profit/loss as \[dq]retained
|
||||
earnings\[dq] (part of equity), and allows the accounting equation
|
||||
(A-L=E) to balance, which you could then check by the bse report\[aq]s
|
||||
zero total.
|
||||
.PP
|
||||
You can print just the closing transaction by using the
|
||||
\f[C]--close\f[R] flag, or just the opening transaction with the
|
||||
\f[C]--open\f[R] flag.
|
||||
.PP
|
||||
Their descriptions are \f[C]closing balances\f[R] and
|
||||
\f[C]opening balances\f[R] by default; you can customise these with the
|
||||
\f[C]--close-desc\f[R] and \f[C]--open-desc\f[R] options.
|
||||
.PP
|
||||
Just one balancing equity posting is used by default, with the amount
|
||||
left implicit.
|
||||
The default account name is \f[C]equity:opening/closing balances\f[R].
|
||||
You can customise the account name(s) with \f[C]--close-acct\f[R] and
|
||||
\f[C]--open-acct\f[R].
|
||||
(If you specify only one of these, it will be used for both.)
|
||||
.PP
|
||||
With \f[C]--x/--explicit\f[R], the equity posting\[aq]s amount will be
|
||||
shown.
|
||||
And if it involves multiple commodities, a posting for each commodity
|
||||
will be shown, as with the print command.
|
||||
shown explicitly, and if it involves multiple commodities, there will be
|
||||
a separate equity posting for each commodity (as in the print command).
|
||||
.PP
|
||||
With \f[C]--interleaved\f[R], the equity postings are shown next to the
|
||||
postings they balance, which makes troubleshooting easier.
|
||||
With \f[C]--interleaved\f[R], each equity posting is shown next to the
|
||||
posting it balances (good for troubleshooting).
|
||||
.SS close and prices
|
||||
.PP
|
||||
By default, transaction prices in the journal are ignored when
|
||||
generating the closing/opening transactions.
|
||||
With \f[C]--show-costs\f[R], this cost information is preserved
|
||||
(\f[C]balance -B\f[R] reports will be unchanged after the transition).
|
||||
Separate postings are generated for each cost in each commodity.
|
||||
Note this can generate very large journal entries, if you have many
|
||||
foreign currency or investment transactions.
|
||||
.SS close usage
|
||||
Transaction prices are ignored (and discarded) by closing/opening
|
||||
transactions, by default.
|
||||
With \f[C]--show-costs\f[R], they are preserved; there will be a
|
||||
separate equity posting for each cost in each commodity.
|
||||
This means \f[C]balance -B\f[R] reports will look the same after the
|
||||
transition.
|
||||
Note if you have many foreign currency or investment transactions, this
|
||||
will generate very large journal entries.
|
||||
.SS close date
|
||||
.PP
|
||||
If you split your journal files by time (eg yearly), you will typically
|
||||
run this command at the end of the year, and save the closing
|
||||
transaction as last entry of the old file, and the opening transaction
|
||||
as the first entry of the new file.
|
||||
This makes the files self contained, so that correct balances are
|
||||
reported no matter which of them are loaded.
|
||||
Ie, if you load just one file, the balances are initialised correctly;
|
||||
or if you load several files, the redundant closing/opening transactions
|
||||
cancel each other out.
|
||||
(They will show up in print or register reports; you can exclude them
|
||||
with a query like
|
||||
\f[C]not:desc:\[aq](opening|closing) balances\[aq]\f[R].)
|
||||
The default closing date is yesterday, or the journal\[aq]s end date,
|
||||
whichever is later.
|
||||
.PP
|
||||
If you\[aq]re running a business, you might also use this command to
|
||||
\[dq]close the books\[dq] at the end of an accounting period,
|
||||
transferring income statement account balances to retained earnings.
|
||||
(You may want to change the equity account name to something like
|
||||
\[dq]equity:retained earnings\[dq].)
|
||||
Unless you are running \f[C]close\f[R] on exactly the first day of the
|
||||
new period, you\[aq]ll want to override the closing date.
|
||||
This is done by specifying a report period, where \[dq]last day of the
|
||||
report period\[dq] will be the closing date.
|
||||
The opening date is always the following day.
|
||||
So to close on 2020-12-31 and open on 2021-01-01, any of these work
|
||||
.IP \[bu] 2
|
||||
\f[C]-p 2020\f[R]
|
||||
.IP \[bu] 2
|
||||
\f[C]date:2020\f[R]
|
||||
.IP \[bu] 2
|
||||
\f[C]-e 2021-01-01\f[R] (remember \f[C]-e\f[R] specifies an exclusive
|
||||
end date)
|
||||
.IP \[bu] 2
|
||||
\f[C]-e 2021\f[R]
|
||||
.SS Example: close asset/liability accounts for file transition
|
||||
.PP
|
||||
By default, the closing transaction is dated yesterday, the balances are
|
||||
calculated as of end of yesterday, and the opening transaction is dated
|
||||
today.
|
||||
To close on some other date, use:
|
||||
\f[C]hledger close -e OPENINGDATE\f[R].
|
||||
Eg, to close/open on the 2018/2019 boundary, use \f[C]-e 2019\f[R].
|
||||
You can also use -p or \f[C]date:PERIOD\f[R] (any starting date is
|
||||
ignored).
|
||||
Carrying asset/liability balances from 2020.journal into a new file for
|
||||
2021:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger close -f 2020.journal -p 2020 assets liabilities
|
||||
# copy/paste the closing transaction to the end of 2020.journal
|
||||
# copy/paste the opening transaction to the start of 2021.journal
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Or:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021\[aq]s first transaction
|
||||
$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020\[aq]s last transaction
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Now,
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger bs -f 2021.journal # just new file - balances correct
|
||||
$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct
|
||||
$ hledger bs -f 2020.journal # just old files - balances are zero ?
|
||||
# (exclude final closing txn, see below)
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Hiding opening/closing transactions
|
||||
.PP
|
||||
Although the closing/opening transactions cancel out, they will be
|
||||
visible in reports like \f[C]print\f[R] and \f[C]register\f[R], creating
|
||||
some visual clutter.
|
||||
You can exclude them all with a query, like:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger print not:desc:\[aq]opening|closing\[aq] # less typing
|
||||
$ hledger print not:\[aq]equity:opening/closing balances\[aq] # more precise
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
But when reporting on multiple files, this can get a bit tricky; you may
|
||||
need to keep the earliest opening balances, for a historical register
|
||||
report; or you may need to suppress a closing transaction, to see
|
||||
year-end balances.
|
||||
If you find yourself needing more precise queries, here\[aq]s one
|
||||
solution: add more easily-matched tags to opening/closing transactions,
|
||||
like this:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
; 2019.journal
|
||||
2019-01-01 opening balances ; earliest opening txn, no tag here
|
||||
\&...
|
||||
2019-12-31 closing balances ; close:2019
|
||||
\&...
|
||||
\f[R]
|
||||
.fi
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
; 2020.journal
|
||||
2020-01-01 opening balances ; open:2020
|
||||
\&...
|
||||
2020-12-31 closing balances ; close:2020
|
||||
\&...
|
||||
\f[R]
|
||||
.fi
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
; 2021.journal
|
||||
2021-01-01 opening balances ; open:2021
|
||||
\&...
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Now with
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
; all.journal
|
||||
include 2019.journal
|
||||
include 2020.journal
|
||||
include 2021.journal
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
you could do eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger -f all.journal reg -H checking not:tag:\[aq]open|close\[aq]
|
||||
# all years checking register, hiding non-essential opening/closing txns
|
||||
|
||||
$ hledger -f all.journal bs -p 2020 not:tag:close=2020
|
||||
# 2020 year end balances, suppressing 2020 closing txn
|
||||
|
||||
$ hledger -f 2020.journal bs not:tag:close
|
||||
# 2020 year end balances, easier case
|
||||
\f[R]
|
||||
.fi
|
||||
.SS close and balance assertions
|
||||
.PP
|
||||
The closing and opening transactions will include balance assertions,
|
||||
verifying that the accounts have first been reset to zero and then
|
||||
restored to their previous balance.
|
||||
These provide valuable error checking, alerting you when things get out
|
||||
of line, but you can ignore them temporarily with \f[C]-I\f[R] or just
|
||||
remove them if you prefer.
|
||||
.PP
|
||||
Both transactions will include balance assertions for the
|
||||
closed/reopened accounts.
|
||||
You probably shouldn\[aq]t use status or realness filters (like -C or -R
|
||||
or \f[C]status:\f[R]) with this command, or the generated balance
|
||||
or \f[C]status:\f[R]) with \f[C]close\f[R], or the generated balance
|
||||
assertions will depend on these flags.
|
||||
Likewise, if you run this command with --auto, the balance assertions
|
||||
will probably always require --auto.
|
||||
Likewise, if you run this command with \f[C]--auto\f[R], the balance
|
||||
assertions would probably always require \f[C]--auto\f[R].
|
||||
.PP
|
||||
Examples:
|
||||
.PP
|
||||
Carrying asset/liability balances into a new file for 2019:
|
||||
Multi-day transactions (where some postings have a different date) break
|
||||
the balance assertions, because the money is temporarily
|
||||
\[dq]invisible\[dq] while in transit:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger close -f 2018.journal -e 2019 assets liabilities --open
|
||||
# (copy/paste the output to the start of your 2019 journal file)
|
||||
$ hledger close -f 2018.journal -e 2019 assets liabilities --close
|
||||
# (copy/paste the output to the end of your 2018 journal file)
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Now:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger bs -f 2019.journal # one file - balances are correct
|
||||
$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct
|
||||
$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Transactions spanning the closing date can complicate matters, breaking
|
||||
balance assertions:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2018/12/30 a purchase made in 2018, clearing the following year
|
||||
2020/12/30 a purchase made in december, cleared in the next year
|
||||
expenses:food 5
|
||||
assets:bank:checking -5 ; [2019/1/2]
|
||||
assets:bank:checking -5 ; date: 2021/1/2
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Here\[aq]s one way to resolve that:
|
||||
To fix the assertions, you can add a temporary account to track such
|
||||
in-transit money (splitting the multi-day transaction into two
|
||||
single-day transactions):
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
; in 2018.journal:
|
||||
2018/12/30 a purchase made in 2018, clearing the following year
|
||||
; in 2020.journal:
|
||||
2020/12/30 a purchase made in december, cleared in the next year
|
||||
expenses:food 5
|
||||
liabilities:pending
|
||||
|
||||
; in 2019.journal:
|
||||
2019/1/2 clearance of last year\[aq]s pending transactions
|
||||
; in 2021.journal:
|
||||
2021/1/2 clearance of last year\[aq]s pending transactions
|
||||
liabilities:pending 5 = 0
|
||||
assets:checking
|
||||
assets:bank:checking
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Example: close revenue/expense accounts to retained earnings
|
||||
.PP
|
||||
Here, the opening transaction is supressed with \f[C]--close\f[R], as
|
||||
it\[aq]s probably not needed.
|
||||
Also you\[aq]ll want to use a different equity account name:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger close -f 2021.journal -p 2021Q1 --close --close-acct=\[aq]equity:retained earnings\[aq] revenues expenses >> 2021.journal
|
||||
# close 2021 first quarter revenues/expenses
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Or, operating on the default journal:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger close -p Q1 --close --close-acct=\[aq]equity:retained earnings\[aq] revenues expenses >> $LEDGER_FILE
|
||||
# close current year\[aq]s first quarter revenues/expenses
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Now, eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger bse -p Q1
|
||||
# Q1 full balance sheet, total should be zero
|
||||
|
||||
$ hledger is -p Q1 not:\[aq]retained earnings\[aq]
|
||||
# Q1 income statement, must suppress the closing txn
|
||||
\f[R]
|
||||
.fi
|
||||
.SS codes
|
||||
|
|
@ -6016,8 +6151,6 @@ versions).
|
|||
Directives\[aq] behaviour and interactions can get a little bit complex,
|
||||
so here is a table summarising the directives and their effects, with
|
||||
links to more detailed docs.
|
||||
Note part of this table is hidden when viewed in a web browser - scroll
|
||||
it sideways to see more.
|
||||
.PP
|
||||
.TS
|
||||
tab(@);
|
||||
|
|
@ -6082,8 +6215,8 @@ T}@T{
|
|||
T}@T{
|
||||
declare a commodity and its number notation & display style
|
||||
T}@T{
|
||||
number notation: following entries in that commodity in all files ;
|
||||
display style: amounts of that commodity in reports
|
||||
number notation: following entries until end of current file; display
|
||||
style: amounts of that commodity in reports
|
||||
T}
|
||||
T{
|
||||
\f[C]D\f[R]
|
||||
|
|
@ -6107,7 +6240,7 @@ T}@T{
|
|||
what the included directives affect
|
||||
T}
|
||||
T{
|
||||
[\f[C]payee\f[R]]
|
||||
\f[C]payee\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
|
|
|
|||
5076
hledger/hledger.info
5076
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
1063
hledger/hledger.txt
1063
hledger/hledger.txt
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user