simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-24 19:02:46 +03:00
Code Issues Projects Releases Wiki Activity

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-06-01 13:11:39 -10:00
parent 5b9f942cf3
commit 7a83578ecf
13 changed files with 1794 additions and 1861 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{May 2024}})m4_dnl
m4_define({{_monthyear_}}, {{June 2024}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{May 2024}})m4_dnl
m4_define({{_monthyear_}}, {{June 2024}})m4_dnl

81
hledger-ui/hledger-ui.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "May 2024" "hledger-ui-1.34 " "hledger User Manuals"
.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34 " "hledger User Manuals"
@ -11,6 +11,10 @@ robust, friendly plain text accounting app.
.PD 0
.P
.PD
or
.PD 0
.P
.PD
\f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.34.
@ -42,47 +46,27 @@ They can be revealed, along with any rule\-generated periodic
transactions, by pressing the F key (or starting with \-\-forecast) to
enable \[dq]forecast mode\[dq].
.SH OPTIONS
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
.PP
Any arguments are interpreted as a hledger query which filters the data.
hledger\-ui provides the following options:
.TP
\f[CR]\-w \-\-watch\f[R]
watch for data and date changes and reload automatically
.TP
\f[CR]\-\-theme=default|terminal|greenterm|dark\f[R]
use this custom display theme
.TP
\f[CR]\-\-menu\f[R]
start in the menu screen
.TP
\f[CR]\-\-cash\f[R]
start in the cash accounts screen
.TP
\f[CR]\-\-bs\f[R]
start in the balance sheet accounts screen
.TP
\f[CR]\-\-is\f[R]
start in the income statement accounts screen
.TP
\f[CR]\-\-all\f[R]
start in the all accounts screen
.TP
\f[CR]\-\-register=ACCTREGEX\f[R]
start in the (first) matched account\[aq]s register screen
.TP
\f[CR]\-\-change\f[R]
show period balances (changes) at startup instead of historical balances
.TP
\f[CR]\-l \-\-flat\f[R]
show accounts as a flat list (default)
.TP
\f[CR]\-t \-\-tree\f[R]
show accounts as a tree
.IP
.EX
Flags:
\-w \-\-watch watch for data and date changes and reload
automatically
\-\-theme=THEME use this custom display theme (default,
greenterm, terminal, dark)
\-\-cash start in the cash accounts screen
\-\-bs start in the balance sheet accounts screen
\-\-is start in the income statement accounts screen
\-\-all start in the all accounts screen
\-\-register=ACCTREGEX start in the (first matched) account\[aq]s register
\-\-change show period balances (changes) at startup instead
of historical balances
\-l \-\-flat show accounts as a flat list (default)
\-t \-\-tree show accounts as a tree
.EE
.PP
hledger\-ui also supports many of hledger\[aq]s general options (and the
hledger manual\[aq]s command line tips also apply here):
.SS General options
and also supports many of hledger\[aq]s general options:
.IP
.EX
General input/data transformation flags:
@ -151,7 +135,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
(A NO_COLOR environment variable overrides this.)
\-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required.
@ -160,10 +143,13 @@ General output/reporting flags (supported by some commands):
General help flags:
\-h \-\-help show command line help
\-\-tldr show command examples with tldr
\-\-info show the hledger manual with info
\-\-man show the hledger manual with man
\-\-info show the manual with info
\-\-man show the manual with man
\-\-version show version information
.EE
.PP
With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to
a \f[CR]hledger\-ui.log\f[R] file in the current directory.
.SH MOUSE
In most modern terminals, you can navigate through the screens with a
mouse or touchpad:
@ -417,8 +403,7 @@ when you press g to reload.
Once you have fixed the problem, press g again to reload and resume
normal operation.
(Or, you can press escape to cancel the reload attempt.)
.SH TIPS
.SS Watch mode
.SH WATCH MODE
One of hledger\-ui\[aq]s best features is the auto\-reloading
\f[CR]\-w/\-\-watch\f[R] mode.
With this flag, it will update the display automatically whenever
@ -458,12 +443,6 @@ know.)
.PP
If you are viewing files mounted from another machine, the system clocks
on both machines should be roughly in agreement.
.SS Debug output
You can add \f[CR]\-\-debug[=N]\f[R] to the command line to log debug
output.
This will be logged to the file \f[CR]hledger\-ui.log\f[R] in the
current directory.
N ranges from 1 (least output, the default) to 9 (maximum output).
.SH ENVIRONMENT
\f[B]COLUMNS\f[R] The screen width to use.
Default: the full terminal width.

175
hledger-ui/hledger-ui.info
View File

@ -15,6 +15,7 @@ hledger-ui - terminal interface (TUI) for 'hledger', a robust, friendly
plain text accounting app.
'hledger-ui [OPTS] [QUERYARGS]'
or
'hledger ui -- [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.34. See
@ -49,7 +50,7 @@ enable "forecast mode".
* MOUSE::
* KEYS::
* SCREENS::
* TIPS::
* WATCH MODE::
* ENVIRONMENT::
* BUGS::
@ -59,58 +60,25 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top
1 OPTIONS
*********
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
Any arguments are interpreted as a hledger query which filters the data.
hledger-ui provides the following options:
hledger-ui provides the following options:
Flags:
-w --watch watch for data and date changes and reload
automatically
--theme=THEME use this custom display theme (default,
greenterm, terminal, dark)
--cash start in the cash accounts screen
--bs start in the balance sheet accounts screen
--is start in the income statement accounts screen
--all start in the all accounts screen
--register=ACCTREGEX start in the (first matched) account's register
--change show period balances (changes) at startup instead
of historical balances
-l --flat show accounts as a flat list (default)
-t --tree show accounts as a tree
'-w --watch'
watch for data and date changes and reload automatically
'--theme=default|terminal|greenterm|dark'
use this custom display theme
'--menu'
start in the menu screen
'--cash'
start in the cash accounts screen
'--bs'
start in the balance sheet accounts screen
'--is'
start in the income statement accounts screen
'--all'
start in the all accounts screen
'--register=ACCTREGEX'
start in the (first) matched account's register screen
'--change'
show period balances (changes) at startup instead of historical
balances
'-l --flat'
show accounts as a flat list (default)
'-t --tree'
show accounts as a tree
hledger-ui also supports many of hledger's general options (and the
hledger manual's command line tips also apply here):
* Menu:
* General options::

File: hledger-ui.info, Node: General options, Up: OPTIONS
1.1 General options
===================
and also supports many of hledger's general options:
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
@ -178,7 +146,6 @@ General output/reporting flags (supported by some commands):
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -187,10 +154,13 @@ General output/reporting flags (supported by some commands):
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
With hledger-ui, the '--debug' option sends debug output to a
'hledger-ui.log' file in the current directory.

File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
@ -309,7 +279,7 @@ amount values.
Additional screen-specific keys are described below.

File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top
File: hledger-ui.info, Node: SCREENS, Next: WATCH MODE, Prev: KEYS, Up: Top
4 SCREENS
*********
@ -485,21 +455,10 @@ again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)

File: hledger-ui.info, Node: TIPS, Next: ENVIRONMENT, Prev: SCREENS, Up: Top
File: hledger-ui.info, Node: WATCH MODE, Next: ENVIRONMENT, Prev: SCREENS, Up: Top
5 TIPS
******
* Menu:
* Watch mode::
* Debug output::

File: hledger-ui.info, Node: Watch mode, Next: Debug output, Up: TIPS
5.1 Watch mode
==============
5 WATCH MODE
************
One of hledger-ui's best features is the auto-reloading '-w/--watch'
mode. With this flag, it will update the display automatically whenever
@ -536,17 +495,7 @@ work around, press 'g' to reload manually, or try #1617's
clocks on both machines should be roughly in agreement.

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
ranges from 1 (least output, the default) to 9 (maximum output).

File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: TIPS, Up: Top
File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top
6 ENVIRONMENT
*************
@ -581,42 +530,36 @@ above).

Tag Table:
Node: Top221
Node: OPTIONS1861
Ref: #options1959
Node: General options2926
Ref: #general-options3030
Node: MOUSE8180
Ref: #mouse8275
Node: KEYS8512
Ref: #keys8605
Node: SCREENS13260
Ref: #screens13358
Node: Menu screen13994
Ref: #menu-screen14115
Node: Cash accounts screen14310
Ref: #cash-accounts-screen14487
Node: Balance sheet accounts screen14671
Ref: #balance-sheet-accounts-screen14887
Node: Income statement accounts screen15007
Ref: #income-statement-accounts-screen15228
Node: All accounts screen15392
Ref: #all-accounts-screen15573
Node: Register screen15755
Ref: #register-screen15914
Node: Transaction screen18198
Ref: #transaction-screen18356
Node: Error screen19773
Ref: #error-screen19895
Node: TIPS20139
Ref: #tips20238
Node: Watch mode20280
Ref: #watch-mode20387
Node: Debug output21846
Ref: #debug-output21957
Node: ENVIRONMENT22169
Ref: #environment22279
Node: BUGS22470
Ref: #bugs22553
Node: OPTIONS1870
Ref: #options1968
Node: MOUSE8148
Ref: #mouse8243
Node: KEYS8480
Ref: #keys8573
Node: SCREENS13228
Ref: #screens13332
Node: Menu screen13968
Ref: #menu-screen14089
Node: Cash accounts screen14284
Ref: #cash-accounts-screen14461
Node: Balance sheet accounts screen14645
Ref: #balance-sheet-accounts-screen14861
Node: Income statement accounts screen14981
Ref: #income-statement-accounts-screen15202
Node: All accounts screen15366
Ref: #all-accounts-screen15547
Node: Register screen15729
Ref: #register-screen15888
Node: Transaction screen18172
Ref: #transaction-screen18330
Node: Error screen19747
Ref: #error-screen19869
Node: WATCH MODE20113
Ref: #watch-mode20230
Node: ENVIRONMENT21689
Ref: #environment21805
Node: BUGS21996
Ref: #bugs22079

End Tag Table

301
hledger-ui/hledger-ui.txt
View File

@ -7,6 +7,7 @@ NAME
SYNOPSIS
hledger-ui [OPTS] [QUERYARGS]
or
hledger ui -- [OPTS] [QUERYARGS]
DESCRIPTION
@ -37,44 +38,26 @@ DESCRIPTION
enable "forecast mode".
OPTIONS
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
Any arguments are interpreted as a hledger query which filters the
data. hledger-ui provides the following options:
hledger-ui provides the following options:
Flags:
-w --watch watch for data and date changes and reload
automatically
--theme=THEME use this custom display theme (default,
greenterm, terminal, dark)
--cash start in the cash accounts screen
--bs start in the balance sheet accounts screen
--is start in the income statement accounts screen
--all start in the all accounts screen
--register=ACCTREGEX start in the (first matched) account's register
--change show period balances (changes) at startup instead
of historical balances
-l --flat show accounts as a flat list (default)
-t --tree show accounts as a tree
-w --watch
watch for data and date changes and reload automatically
and also supports many of hledger's general options:
--theme=default|terminal|greenterm|dark
use this custom display theme
--menu start in the menu screen
--cash start in the cash accounts screen
--bs start in the balance sheet accounts screen
--is start in the income statement accounts screen
--all start in the all accounts screen
--register=ACCTREGEX
start in the (first) matched account's register screen
--change
show period balances (changes) at startup instead of historical
balances
-l --flat
show accounts as a flat list (default)
-t --tree
show accounts as a tree
hledger-ui also supports many of hledger's general options (and the
hledger manual's command line tips also apply here):
General options
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
specified more than once. If not specified, reads
@ -141,7 +124,6 @@ OPTIONS
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -150,12 +132,15 @@ OPTIONS
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
With hledger-ui, the --debug option sends debug output to a
hledger-ui.log file in the current directory.
MOUSE
In most modern terminals, you can navigate through the screens with a
In most modern terminals, you can navigate through the screens with a
mouse or touchpad:
o Use mouse wheel or trackpad to scroll up and down
@ -167,95 +152,95 @@ MOUSE
KEYS
Keyboard gives more control.
? shows a help dialog listing all keys. (Some of these also appear in
the quick help at the bottom of each screen.) Press ? again (or ES-
CAPE, or LEFT, or q) to close it. The following keys work on most
? shows a help dialog listing all keys. (Some of these also appear in
the quick help at the bottom of each screen.) Press ? again (or ES-
CAPE, or LEFT, or q) to close it. The following keys work on most
screens:
The cursor keys navigate: RIGHT or ENTER goes deeper, LEFT returns to
The cursor keys navigate: RIGHT or ENTER goes deeper, LEFT returns to
the previous screen, UP/DOWN/PGUP/PGDN/HOME/END move up and down
through lists. Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style
(k,j,l,h) movement keys are also supported. A tip: movement speed is
limited by your keyboard repeat rate, to move faster you may want to
adjust it. (If you're on a mac, the karabiner app is one way to do
through lists. Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style
(k,j,l,h) movement keys are also supported. A tip: movement speed is
limited by your keyboard repeat rate, to move faster you may want to
adjust it. (If you're on a mac, the karabiner app is one way to do
that.)
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
SHIFT-DOWN/UP steps downward and upward through these standard report
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
SHIFT-DOWN/UP steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then,
SHIFT-LEFT/RIGHT moves to the previous/next period. T sets the report
period to today. With the -w/--watch option, when viewing a "current"
period (the current day, week, month, quarter, or year), the period
will move automatically to track the current date. To set a non-stan-
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-stan-
dard 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 cur-
(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 cur-
rent 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
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 type it directly.)
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
it, or ESCAPEto cancel. There are also keys for quickly adjusting some
common filters like account depth and transaction status (see below).
common filters like account depth and transaction status (see below).
BACKSPACE or DELETE removes all filters, showing all transactions.
As mentioned above, by default hledger-ui hides future transactions -
As mentioned above, by default hledger-ui hides future transactions -
both ordinary transactions recorded in the journal, and periodic trans-
actions generated by rule. F toggles forecast mode, in which fu-
actions generated by rule. F toggles forecast mode, in which fu-
ture/forecasted transactions are shown.
ESCAPE resets the UI state and jumps back to the top screen, restoring
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 en-
try or the help dialog.
CTRL-l redraws the screen and centers the selection if possible (selec-
tions near the top won't be centered, since we don't scroll above the
tions near the top won't be centered, since we don't scroll above the
top).
g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable
g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable
pause.)
I toggles balance assertion checking. Disabling balance assertions
I toggles balance assertion checking. Disabling balance assertions
temporarily can be useful for troubleshooting.
a runs command-line hledger's add command, and reloads the updated
a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a terminal
interface. This key will be available if hledger-iadd is installed in
A is like a, but runs the hledger-iadd tool, which provides a terminal
interface. This key will be available if hledger-iadd is installed in
$path.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor
will be positioned at the current transaction when invoked from the
register and transaction screens, and at the error location (if possi-
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor
will be positioned at the current transaction when invoked from the
register and transaction screens, and at the error location (if possi-
ble) when invoked from the error screen.
B toggles cost mode, showing amounts converted to their cost's commod-
B toggles cost mode, showing amounts converted to their cost's commod-
ity (see hledger manual > Cost reporting.
V toggles value mode, showing amounts converted to their market value
V toggles value mode, showing amounts converted to their market value
(see hledger manual > Valuation flag). More specifically,
1. By default, the V key toggles showing end value (--value=end) on or
off. The valuation date will be the report end date if specified,
1. By default, the V key toggles showing end value (--value=end) on or
off. The valuation date will be the report end date if specified,
otherwise today.
2. If you started hledger-ui with some other valuation (such as
2. If you started hledger-ui with some other valuation (such as
--value=then,EUR), the V key toggles that off or on.
Cost/value tips: - When showing end value, you can change the report
end date without restarting, by pressing / and adding a query like
date:..YYYY-MM-DD. - Either cost mode, or value mode, can be active,
but not both at once. Cost mode takes precedence. - There's not yet
any visual indicator that cost or value mode is active, other than the
Cost/value tips: - When showing end value, you can change the report
end date without restarting, by pressing / and adding a query like
date:..YYYY-MM-DD. - Either cost mode, or value mode, can be active,
but not both at once. Cost mode takes precedence. - There's not yet
any visual indicator that cost or value mode is active, other than the
amount values.
q quits the application.
@ -263,47 +248,47 @@ KEYS
Additional screen-specific keys are described below.
SCREENS
At startup, hledger-ui shows a menu screen by default. From here you
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
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
You can also use a command line flag to specific a different startup
screen (--cs, --bs, --is, --all, or --register=ACCT).
Menu screen
This is the top-most screen. From here you can navigate to several
screens listing accounts of various types. Note some of these may not
This is the top-most screen. From here you can navigate to several
screens listing accounts of various types. Note some of these may not
show anything until you have configured account types.
Cash accounts screen
This screen shows "cash" (ie, liquid asset) accounts (like hledger bal-
ancesheet type:c). It always shows balances (historical ending bal-
ancesheet type:c). It always shows balances (historical ending bal-
ances on the date shown in the title line).
Balance sheet accounts screen
This screen shows asset, liability and equity accounts (like hledger
This screen shows asset, liability and equity accounts (like hledger
balancesheetequity). It always shows balances.
Income statement accounts screen
This screen shows revenue and expense accounts (like hledger incomes-
tatement). It always shows changes (balance changes in the period
This screen shows revenue and expense accounts (like hledger incomes-
tatement). It always shows changes (balance changes in the period
shown in the title line).
All accounts screen
This screen shows all accounts in your journal (unless filtered by a
query; like hledger balance). It shows balances by default; you can
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.
Register screen
This screen shows the transactions affecting a particular account.
This screen shows the transactions affecting a particular account.
Each line represents one transaction, and shows:
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
by real postings.)
o the overall change to the current account's balance; positive for an
o the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow.
o the running total after the transaction. With the H key you can tog-
@ -311,91 +296,90 @@ SCREENS
o the period total, which is from just the transactions displayed
o or the historical total, which includes any undisplayed transac-
tions before the start of the report period (and matching the fil-
ter query if any). This will be the running historical balance
(what you would see on a bank's website, eg) if not disturbed by a
o or the historical total, which includes any undisplayed transac-
tions before the start of the report period (and matching the fil-
ter query if any). This will be the running historical balance
(what you would see on a bank's website, eg) if not disturbed by a
query.
Note, this screen combines each transaction's in-period postings to a
single line item, dated with the earliest in-period transaction or
posting date (like hledger's aregister). So custom posting dates can
cause the running balance to be temporarily inaccurate. (See hledger
Note, this screen combines each transaction's in-period postings to a
single line item, dated with the earliest in-period transaction or
posting date (like hledger's aregister). So custom posting dates can
cause the running balance to be temporarily inaccurate. (See hledger
manual > aregister and posting dates.)
Transactions affecting this account's subaccounts will be included in
Transactions affecting this account's subaccounts will be included in
the register if the accounts screen is in tree mode, or if it's in list
mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac-
tions contributing to the balance shown on the accounts screen. Tree
mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac-
tions contributing to the balance shown on the accounts screen. Tree
mode/list mode can be toggled with t here also.
U toggles filtering by unmarked status, showing or hiding unmarked
U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com-
z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com-
mand-line hledger).
Press RIGHT to view the selected transaction in detail.
Transaction screen
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour-
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour-
nal(5)).
The transaction's date(s) and any cleared flag, transaction code, de-
scription, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
The transaction's date(s) and any cleared flag, transaction code, de-
scription, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
certain cases, fewer).
UP and DOWN will step through all transactions listed in the previous
account register screen. In the title bar, the numbers in parentheses
show your position within that account register. They will vary de-
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 de-
pending on which account register you came from (remember most transac-
tions appear in multiple account registers). The #N number preceding
tions appear in multiple account registers). The #N number preceding
them is the transaction's position within the complete unfiltered jour-
nal, which is a more stable id (at least until the next reload).
On this screen (and the register screen), the E key will open your text
editor with the cursor positioned at the current transaction if possi-
editor with the cursor positioned at the current transaction if possi-
ble.
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
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 to exit and
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.
Error screen
This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g
This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g
again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)
TIPS
Watch mode
One of hledger-ui's best features is the auto-reloading -w/--watch
mode. With this flag, it will update the display automatically when-
WATCH MODE
One of hledger-ui's best features is the auto-reloading -w/--watch
mode. With this flag, it will update the display automatically when-
ever changes are saved to the data files.
This is very useful when reconciling. A good workflow is to have your
bank's online register open in a browser window, for reference; the
journal file open in an editor window; and hledger-ui in watch mode in
This is very useful when reconciling. A good workflow is to have your
bank's online register open in a browser window, for reference; the
journal file open in an editor window; and hledger-ui in watch mode in
a terminal window, eg:
$ hledger-ui --watch --register checking -C
As you mark things cleared in the editor, you can see the effect imme-
diately without having to context switch. This leaves more mental
bandwidth for your accounting. Of course you can still interact with
hledger-ui when needed, eg to toggle cleared mode, or to explore the
As you mark things cleared in the editor, you can see the effect imme-
diately without having to context switch. This leaves more mental
bandwidth for your accounting. Of course you can still interact with
hledger-ui when needed, eg to toggle cleared mode, or to explore the
history.
There are currently some limitations with --watch:
@ -403,32 +387,27 @@ TIPS
It may not work correctly for you, depending on platform or system con-
figuration. (Eg #836.)
At least on mac, there can be a slow build-up of CPU usage over time,
until the program is restarted (or, suspending and restarting with
At least on mac, there can be a slow build-up of CPU usage over time,
until the program is restarted (or, suspending and restarting with
CTRL-z fg may be enough).
It will not detect file changes made by certain editors, such as Jet-
brains IDEs or gedit, or on certain less common filesystems. (To work
around, press g to reload manually, or try #1617's fs.ino-
It will not detect file changes made by certain editors, such as Jet-
brains IDEs or gedit, or on certain less common filesystems. (To work
around, press g to reload manually, or try #1617's fs.ino-
tify.max_user_watches workaround and let us know.)
If you are viewing files mounted from another machine, the system
If you are viewing files mounted from another machine, the system
clocks on both machines should be roughly in agreement.
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
ranges from 1 (least output, the default) to 9 (maximum output).
ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width.
LEDGER_FILE The main journal file to use when not specified with
LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal.
BUGS
We welcome bug reports in the hledger issue tracker (shortcut:
http://bugs.hledger.org), or on the #hledger chat or hledger mail list
http://bugs.hledger.org), or on the #hledger chat or hledger mail list
(https://hledger.org/support).
Some known issues:
@ -440,7 +419,7 @@ BUGS
The Transaction screen does not update from file changes until you exit
and re-endter it (see SCREENS > Transaction above).
--watch is not yet fully robust on all platforms (see Watch mode
--watch is not yet fully robust on all platforms (see Watch mode
above).
@ -461,4 +440,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.34 May 2024 HLEDGER-UI(1)
hledger-ui-1.34 June 2024 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{May 2024}})m4_dnl
m4_define({{_monthyear_}}, {{June 2024}})m4_dnl

113
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "May 2024" "hledger-web-1.34 " "hledger User Manuals"
.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34 " "hledger User Manuals"
@ -7,11 +7,15 @@
hledger\-web \- web interface and API for \f[CR]hledger\f[R], a robust,
friendly plain text accounting app.
.SH SYNOPSIS
\f[CR]hledger\-web [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]
\f[CR]hledger\-web [OPTS] [QUERY]\f[R]
.PD 0
.P
.PD
\f[CR]hledger web \-\- [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]
or
.PD 0
.P
.PD
\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.34.
See also the hledger manual for common concepts and file formats.
@ -61,45 +65,41 @@ In all cases hledger\-web runs as a foreground process, logging requests
to stdout.
.SH OPTIONS
hledger\-web provides the following options:
.TP
\f[CR]\-\-serve\f[R]
serve and log requests, don\[aq]t browse or auto\-exit after timeout
.TP
\f[CR]\-\-serve\-api\f[R]
like \-\-serve, but serve only the JSON web API, not the web UI
.TP
\f[CR]\-\-allow=view|add|edit\f[R]
set the user\[aq]s access level for changing data (default:
\f[CR]add\f[R]).
It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads
permissions from the \f[CR]X\-Sandstorm\-Permissions\f[R] request
header).
.TP
\f[CR]\-\-cors=ORIGIN\f[R]
allow cross\-origin requests from the specified origin; setting ORIGIN
to \[dq]*\[dq] allows requests from any origin
.TP
\f[CR]\-\-host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1)
.IP
.EX
Flags:
\-\-serve \-\-server serve and log requests, don\[aq]t browse or auto\-exit
\-\-serve\-api like \-\-serve, but serve only the JSON web API,
not the web UI
\-\-allow=view|add|edit set the user\[aq]s access level for changing data
(default: \[ga]add\[ga]). It also accepts \[ga]sandstorm\[ga] for
use on that platform (reads permissions from the
\[ga]X\-Sandstorm\-Permissions\[ga] request header).
\-\-cors=ORIGIN allow cross\-origin requests from the specified
origin; setting ORIGIN to \[dq]*\[dq] allows requests from
any origin
\-\-host=IPADDR listen on this IP address (default: 127.0.0.1)
\-\-port=PORT listen on this TCP port (default: 5000)
\-\-socket=SOCKET listen on the given unix socket instead of an IP
address and port (unix only; implies \-\-serve)
\-\-base\-url=BASEURL set the base url (default: http://IPADDR:PORT)
\-\-test run hledger\-web\[aq]s tests and exit. hspec test
runner args may follow a \-\-, eg: hledger\-web \-\-test
\-\- \-\-help
.EE
.PP
By default the server listens on IP address \f[CR]127.0.0.1\f[R], which
is accessible only to requests from the local machine..
You can use \f[CR]\-\-host\f[R] to listen on a different address
configured on the machine, eg to allow access from other machines.
The special address \f[CR]0.0.0.0\f[R] causes it to listen on all
addresses configured on the machine.
.TP
\f[CR]\-\-port=PORT\f[R]
listen on this TCP port (default: 5000)
By default hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R],
which be accessed only from the local machine.
.PP
To allow access from elsewhere, use \f[CR]\-\-host\f[R] to specify an
externally accessible address configured on this machine, The special
address \f[CR]0.0.0.0\f[R] causes it to listen on all of this
machine\[aq]s addresses.
.PP
Similarly, you can use \f[CR]\-\-port\f[R] to listen on a TCP port other
than 5000.
This is useful if you want to run multiple hledger\-web instances on a
machine.
.TP
\f[CR]\-\-socket=SOCKETFILE\f[R]
listen on the given unix socket instead of an IP address and port (unix
only; implies \-\-serve)
.PP
When \f[CR]\-\-socket\f[R] is used, hledger\-web creates and
communicates via a socket file instead of a TCP port.
@ -108,9 +108,6 @@ certain use cases easier, such as running per\-user instances behind an
nginx reverse proxy.
(Eg:
\f[CR]proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;\f[R].)
.TP
\f[CR]\-\-base\-url=URL\f[R]
set the base url (default: http://IPADDR:PORT).
.PP
You can use \f[CR]\-\-base\-url\f[R] to change the protocol, hostname,
port and path that appear in hledger\-web\[aq]s hyperlinks.
@ -119,26 +116,8 @@ The default is \f[CR]http://HOST:PORT/\f[R] using the server\[aq]s
configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT
is 80).
Note this affects url generation but not route parsing.
.TP
\f[CR]\-\-test\f[R]
run hledger\-web\[aq]s tests and exit.
hspec test runner args may follow a \-\-, eg: hledger\-web \-\-test \-\-
\-\-help
.PP
hledger\-web also supports many of hledger\[aq]s general options.
Query options and arguments may be used to set an initial filter, which
although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
.PP
Note that hledger\-web shows accounts with zero balances by default,
like \f[CR]hledger\-ui\f[R] (and unlike \f[CR]hledger\f[R]).
Using the \f[CR]\-E/\-\-empty\f[R] flag at startup will hide them.
.PP
If you see accounts which appear to have a zero balance, but cannot be
hidden with \f[CR]\-E\f[R]: these have a mixed\-cost balance which looks
like zero when costs are hidden.
Currently hledger\-web does not show costs at all.
.SS General options
hledger\-web also supports many of hledger\[aq]s general options:
.IP
.EX
General input/data transformation flags:
@ -207,7 +186,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
(A NO_COLOR environment variable overrides this.)
\-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required.
@ -216,10 +194,22 @@ General output/reporting flags (supported by some commands):
General help flags:
\-h \-\-help show command line help
\-\-tldr show command examples with tldr
\-\-info show the hledger manual with info
\-\-man show the hledger manual with man
\-\-info show the manual with info
\-\-man show the manual with man
\-\-version show version information
.EE
.PP
hledger\-web shows accounts with zero balances by default (like
\f[CR]hledger\-ui\f[R], and unlike \f[CR]hledger\f[R]).
Using the \f[CR]\-E/\-\-empty\f[R] flag will reverse this behaviour.
If you see accounts which appear to have a zero balance, but cannot be
hidden with \f[CR]\-E\f[R], it\[aq]s because they have a mixed\-cost
balance, which looks like zero when costs are hidden.
(hledger\-web does not show costs.)
.PP
Reporting options and/or query arguments can be used to set an initial
query, which although not shown in the UI, will restrict the data shown
(in addition to any search query entered in the UI).
.SH PERMISSIONS
By default, hledger\-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
@ -360,6 +350,7 @@ Most of the JSON corresponds to hledger\[aq]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.
There is also a basic OpenAPI specification.
.PP
In some cases there is outer JSON corresponding to a \[dq]Report\[dq]
type.

150
hledger-web/hledger-web.info
View File

@ -14,8 +14,9 @@ hledger-web(1)
hledger-web - web interface and API for 'hledger', a robust, friendly
plain text accounting app.
'hledger-web [--serve|--serve-api] [OPTS] [ARGS]'
'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]'
'hledger-web [OPTS] [QUERY]'
or
'hledger web -- [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.34. See also
the hledger manual for common concepts and file formats.
@ -78,54 +79,43 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
hledger-web provides the following options:
'--serve'
Flags:
--serve --server serve and log requests, don't browse or auto-exit
--serve-api like --serve, but serve only the JSON web API,
not the web UI
--allow=view|add|edit set the user's access level for changing data
(default: `add`). It also accepts `sandstorm` for
use on that platform (reads permissions from the
`X-Sandstorm-Permissions` request header).
--cors=ORIGIN allow cross-origin requests from the specified
origin; setting ORIGIN to "*" allows requests from
any origin
--host=IPADDR listen on this IP address (default: 127.0.0.1)
--port=PORT listen on this TCP port (default: 5000)
--socket=SOCKET listen on the given unix socket instead of an IP
address and port (unix only; implies --serve)
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
--test run hledger-web's tests and exit. hspec test
runner args may follow a --, eg: hledger-web --test
-- --help
serve and log requests, don't browse or auto-exit after timeout
'--serve-api'
By default hledger-web listens only on IP address '127.0.0.1', which
be accessed only from the local machine.
like -serve, but serve only the JSON web API, not the web UI
'--allow=view|add|edit'
set the user's access level for changing data (default: 'add'). It
also accepts 'sandstorm' for use on that platform (reads
permissions from the 'X-Sandstorm-Permissions' request header).
'--cors=ORIGIN'
allow cross-origin requests from the specified origin; setting
ORIGIN to "*" allows requests from any origin
'--host=IPADDR'
listen on this IP address (default: 127.0.0.1)
By default the server listens on IP address '127.0.0.1', which is
accessible only to requests from the local machine.. You can use
'--host' to listen on a different address configured on the machine, eg
to allow access from other machines. The special address '0.0.0.0'
causes it to listen on all addresses configured on the machine.
'--port=PORT'
listen on this TCP port (default: 5000)
To allow access from elsewhere, use '--host' to specify an externally
accessible address configured on this machine, The special address
'0.0.0.0' causes it to listen on all of this machine's addresses.
Similarly, you can use '--port' to listen on a TCP port other than
5000. This is useful if you want to run multiple hledger-web instances
on a machine.
'--socket=SOCKETFILE'
listen on the given unix socket instead of an IP address and port
(unix only; implies -serve)
When '--socket' is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as
running per-user instances behind an nginx reverse proxy. (Eg:
'proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;'.)
'--base-url=URL'
set the base url (default: http://IPADDR:PORT).
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hledger-web's hyperlinks. This is useful eg when
integrating hledger-web within a larger website. The default is
@ -133,34 +123,7 @@ integrating hledger-web within a larger website. The default is
port (or 'http://HOST' if PORT is 80). Note this affects url generation
but not route parsing.
'--test'
run hledger-web's tests and exit. hspec test runner args may
follow a -, eg: hledger-web -test - -help
hledger-web also supports many of hledger's general options. Query
options and arguments may be used to set an initial filter, which
although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
Note that hledger-web shows accounts with zero balances by default,
like 'hledger-ui' (and unlike 'hledger'). Using the '-E/--empty' flag
at startup will hide them.
If you see accounts which appear to have a zero balance, but cannot
be hidden with '-E': these have a mixed-cost balance which looks like
zero when costs are hidden. Currently hledger-web does not show costs
at all.
* Menu:
* General options::

File: hledger-web.info, Node: General options, Up: OPTIONS
1.1 General options
===================
hledger-web also supports many of hledger's general options:
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
@ -228,7 +191,6 @@ General output/reporting flags (supported by some commands):
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -237,10 +199,21 @@ General output/reporting flags (supported by some commands):
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
hledger-web shows accounts with zero balances by default (like
'hledger-ui', and unlike 'hledger'). Using the '-E/--empty' flag will
reverse this behaviour. If you see accounts which appear to have a zero
balance, but cannot be hidden with '-E', it's because they have a
mixed-cost balance, which looks like zero when costs are hidden.
(hledger-web does not show costs.)
Reporting options and/or query arguments can be used to set an
initial query, which although not shown in the UI, will restrict the
data shown (in addition to any search query entered in the UI).

File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
@ -382,7 +355,8 @@ $ 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
understanding, see the journal docs.
understanding, see the journal docs. There is also a basic OpenAPI
specification.
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
@ -548,26 +522,24 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list

Tag Table:
Node: Top223
Node: OPTIONS2605
Ref: #options2710
Node: General options5614
Ref: #general-options5719
Node: PERMISSIONS10869
Ref: #permissions11008
Node: EDITING UPLOADING DOWNLOADING12220
Ref: #editing-uploading-downloading12401
Node: RELOADING13235
Ref: #reloading13369
Node: JSON API13802
Ref: #json-api13917
Node: DEBUG OUTPUT19405
Ref: #debug-output19530
Node: Debug output19557
Ref: #debug-output-119658
Node: ENVIRONMENT20075
Ref: #environment20194
Node: BUGS20311
Ref: #bugs20395
Node: OPTIONS2566
Ref: #options2671
Node: PERMISSIONS10859
Ref: #permissions10998
Node: EDITING UPLOADING DOWNLOADING12210
Ref: #editing-uploading-downloading12391
Node: RELOADING13225
Ref: #reloading13359
Node: JSON API13792
Ref: #json-api13907
Node: DEBUG OUTPUT19441
Ref: #debug-output19566
Node: Debug output19593
Ref: #debug-output-119694
Node: ENVIRONMENT20111
Ref: #environment20230
Node: BUGS20347
Ref: #bugs20431

End Tag Table

103
hledger-web/hledger-web.txt
View File

@ -6,8 +6,9 @@ NAME
plain text accounting app.
SYNOPSIS
hledger-web [--serve|--serve-api] [OPTS] [ARGS]
hledger web -- [--serve|--serve-api] [OPTS] [ARGS]
hledger-web [OPTS] [QUERY]
or
hledger web -- [OPTS] [QUERY]
DESCRIPTION
This manual is for hledger's web interface, version 1.34. See also the
@ -55,50 +56,43 @@ DESCRIPTION
OPTIONS
hledger-web provides the following options:
--serve
serve and log requests, don't browse or auto-exit after timeout
Flags:
--serve --server serve and log requests, don't browse or auto-exit
--serve-api like --serve, but serve only the JSON web API,
not the web UI
--allow=view|add|edit set the user's access level for changing data
(default: `add`). It also accepts `sandstorm` for
use on that platform (reads permissions from the
`X-Sandstorm-Permissions` request header).
--cors=ORIGIN allow cross-origin requests from the specified
origin; setting ORIGIN to "*" allows requests from
any origin
--host=IPADDR listen on this IP address (default: 127.0.0.1)
--port=PORT listen on this TCP port (default: 5000)
--socket=SOCKET listen on the given unix socket instead of an IP
address and port (unix only; implies --serve)
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
--test run hledger-web's tests and exit. hspec test
runner args may follow a --, eg: hledger-web --test
-- --help
--serve-api
like --serve, but serve only the JSON web API, not the web UI
By default hledger-web listens only on IP address 127.0.0.1, which be
accessed only from the local machine.
--allow=view|add|edit
set the user's access level for changing data (default: add).
It also accepts sandstorm for use on that platform (reads per-
missions from the X-Sandstorm-Permissions request header).
To allow access from elsewhere, use --host to specify an externally ac-
cessible address configured on this machine, The special address
0.0.0.0 causes it to listen on all of this machine's addresses.
--cors=ORIGIN
allow cross-origin requests from the specified origin; setting
ORIGIN to "*" allows requests from any origin
--host=IPADDR
listen on this IP address (default: 127.0.0.1)
By default the server listens on IP address 127.0.0.1, which is acces-
sible only to requests from the local machine.. You can use --host to
listen on a different address configured on the machine, eg to allow
access from other machines. The special address 0.0.0.0 causes it to
listen on all addresses configured on the machine.
--port=PORT
listen on this TCP port (default: 5000)
Similarly, you can use --port to listen on a TCP port other than 5000.
This is useful if you want to run multiple hledger-web instances on a
Similarly, you can use --port to listen on a TCP port other than 5000.
This is useful if you want to run multiple hledger-web instances on a
machine.
--socket=SOCKETFILE
listen on the given unix socket instead of an IP address and
port (unix only; implies --serve)
When --socket is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as run-
ning per-user instances behind an nginx reverse proxy. (Eg: proxy_pass
http://unix:/tmp/hledger/${remote_user}.socket;.)
--base-url=URL
set the base url (default: http://IPADDR:PORT).
You can use --base-url to change the protocol, hostname, port and path
that appear in hledger-web's hyperlinks. This is useful eg when inte-
grating hledger-web within a larger website. The default is
@ -106,24 +100,8 @@ OPTIONS
port (or http://HOST if PORT is 80). Note this affects url generation
but not route parsing.
--test run hledger-web's tests and exit. hspec test runner args may
follow a --, eg: hledger-web --test -- --help
hledger-web also supports many of hledger's general options:
hledger-web also supports many of hledger's general options. Query op-
tions and arguments may be used to set an initial filter, which al-
though not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
Note that hledger-web shows accounts with zero balances by default,
like hledger-ui (and unlike hledger). Using the -E/--empty flag at
startup will hide them.
If you see accounts which appear to have a zero balance, but cannot be
hidden with -E: these have a mixed-cost balance which looks like zero
when costs are hidden. Currently hledger-web does not show costs at
all.
General options
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
specified more than once. If not specified, reads
@ -190,7 +168,6 @@ OPTIONS
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -199,10 +176,21 @@ OPTIONS
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
hledger-web shows accounts with zero balances by default (like
hledger-ui, and unlike hledger). Using the -E/--empty flag will re-
verse this behaviour. If you see accounts which appear to have a zero
balance, but cannot be hidden with -E, it's because they have a
mixed-cost balance, which looks like zero when costs are hidden.
(hledger-web does not show costs.)
Reporting options and/or query arguments can be used to set an initial
query, which although not shown in the UI, will restrict the data shown
(in addition to any search query entered in the UI).
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
@ -327,7 +315,8 @@ JSON API
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 un-
derstanding, see the journal docs.
derstanding, see the journal docs. There is also a basic OpenAPI spec-
ification.
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
@ -484,4 +473,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.34 May 2024 HLEDGER-WEB(1)
hledger-web-1.34 June 2024 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{May 2024}})m4_dnl
m4_define({{_monthyear_}}, {{June 2024}})m4_dnl

173
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "HLEDGER" "1" "May 2024" "hledger-1.34 " "hledger User Manuals"
.TH "HLEDGER" "1" "June 2024" "hledger-1.34 " "hledger User Manuals"
@ -12,11 +12,19 @@ version).
.PD 0
.P
.PD
\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R]
or
.PD 0
.P
.PD
\f[CR]hledger ADDONCMD \-\- [OPTS] [ARGS]\f[R]
\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R]
.PD 0
.P
.PD
or
.PD 0
.P
.PD
\f[CR]hledger ADDONCMD [OPTS] \-\- [ADDONOPTS] [ADDONARGS]\f[R]
.SH DESCRIPTION
hledger is a robust, user\-friendly, cross\-platform set of programs for
tracking money, time, or any other commodity, using double\-entry
@ -226,8 +234,8 @@ The file name \f[CR]\-\f[R] means standard input:
$ cat FILE | hledger \-f\- print
.EE
.PP
If reading non\-journal data in this way, you\[aq]ll need to add a file
format prefix, like:
If reading non\-journal data in this way, you\[aq]ll need to write the
format as a prefix, like \f[CR]timeclock:\f[R] here:
.IP
.EX
$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\-
@ -328,9 +336,9 @@ If this causes difficulty, you can always run the add\-on directly,
without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or
\f[CR]hledger\-web \-\-serve\f[R].
.SH Options
Run \f[CR]hledger \-h\f[R] to see general command line help, and general
options which are common to most hledger commands.
These options can be written anywhere on the command line:
Run \f[CR]hledger \-h\f[R] to see general command line help.
The following general options are common to most hledger commands.
General options can be written either before or after the command name.
.IP
.EX
General input/data transformation flags:
@ -399,7 +407,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
(A NO_COLOR environment variable overrides this.)
\-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required.
@ -408,19 +415,24 @@ General output/reporting flags (supported by some commands):
General help flags:
\-h \-\-help show command line help
\-\-tldr show command examples with tldr
\-\-info show the hledger manual with info
\-\-man show the hledger manual with man
\-\-info show the manual with info
\-\-man show the manual with man
\-\-version show version information
.EE
.PP
Some reporting options can also be written as query arguments.
.SH Command line tips
Here are some details useful to know about for hledger command lines
(and elsewhere).
Feel free to skip this section until you need it.
.SS Option repetition
If options are repeated in a command line, hledger will generally use
the last (right\-most) occurence.
Usually hledger accepts any unambiguous flag prefix, eg you can write
\f[CR]\-\-tl\f[R] instead of \f[CR]\-\-tldr\f[R] or \f[CR]\-\-dry\f[R]
instead of \f[CR]\-\-dry\-run\f[R].
.PP
If the same option appears more than once in a command, usually the last
(right\-most) wins.
.PP
With most commands, arguments are interpreted as a hledger query which
filter the data.
Some queries can be expressed either with options or with arguments.
.PP
Below are more tips for using the command line interface \- feel free to
skip these until you need them.
.SS Special characters
.SS Single escaping (shell metacharacters)
In shell command lines, characters significant to your shell \- such as
@ -885,6 +897,7 @@ representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are
mostly in
https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs.
hledger\-web\[aq]s OpenAPI specification may also be relevant.
.IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals.
@ -1017,9 +1030,10 @@ If not set, they will try to use the available terminal width.
with \f[CR]\-f/\-\-file\f[R].
Default: \f[CR]$HOME/.hledger.journal\f[R].
.PP
\f[B]NO_COLOR\f[R] If this environment variable is set (with any value),
hledger will not use ANSI color codes in terminal output, unless
overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option.
\f[B]NO_COLOR\f[R] If this environment variable exists (with any value,
including empty), hledger will not use ANSI color codes in terminal
output, unless overridden by an explicit
\f[CR]\-\-color=y\f[R]/\f[CR]\-\-colour=y\f[R] option.
.SH PART 2: DATA FORMATS
.SH Journal
hledger\[aq]s usual data source is a plain text file containing journal
@ -3410,24 +3424,39 @@ when evaluating a region of the journal in your editor.
A missing Y directive makes reports dependent on today\[aq]s date.
.SS Secondary dates
A secondary date is written after the primary date, following an equals
sign.
sign: \f[CR]DATE1=DATE2\f[R].
If the year is omitted, the primary date\[aq]s year is assumed.
When running reports, the primary (left) date is used by default, but
with the \f[CR]\-\-date2\f[R] flag (or \f[CR]\-\-aux\-date\f[R] or
\f[CR]\-\-effective\f[R]), the secondary (right) date will be used
instead.
When running reports, the primary (left side) date is used by default,
but with the \f[CR]\-\-date2\f[R] flag (\f[CR]\-\-aux\-date\f[R]
or\f[CR]\-\-effective\f[R] also work, for Ledger users), the secondary
(right side) date will be used instead.
.PP
The meaning of secondary dates is up to you, but it\[aq]s best to follow
a consistent rule.
Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the
transaction was initiated, if different\[dq].
The meaning of secondary dates is up to you.
Eg it could be \[dq]primary is the bank\[aq]s clearing date, secondary
is the date the transaction was initiated, if different\[dq].
.PP
Downsides: makes your financial data more complicated, less portable,
and less trustworthy in an audit.
Keeping the meaning of the two dates consistent requires discipline, and
you have to remember which reporting mode is appropriate for a given
report.
Posting dates are simpler and better.
In practice, this feature usually adds confusion:
.IP \[bu] 2
You have to remember the primary and secondary dates\[aq] meaning, and
follow that consistently.
.IP \[bu] 2
It splits your bookkeeping into two modes, and you have to remember
which mode is appropriate for a given report.
.IP \[bu] 2
Usually your balance assertions will work with only one of these modes.
.IP \[bu] 2
It makes your financial data more complicated, less portable, and less
clear in an audit.
.IP \[bu] 2
It interacts with every feature, creating an ongoing cost for
implementors.
.IP \[bu] 2
It distracts new users and supporters.
.IP \[bu] 2
Posting dates are simpler and work better.
.PP
So secondary dates are officially deprecated in hledger, remaining only
as a Ledger compatibility aid; we recommend using posting dates instead.
.SS Star comments
Lines beginning with \f[CR]*\f[R] (star/asterisk) are also comment
lines.
@ -6334,42 +6363,52 @@ $ hledger balance Income:Dues \-\-pivot kind:member
\-2 EUR
.EE
.SH Generating data
hledger has several features for generating data, such as:
hledger can enrich the data provided to it, or generate new data, in a
number of ways.
Mostly, this is done only if you request it:
.IP \[bu] 2
Periodic transaction rules can generate single or repeating transactions
following a template.
These are usually dated in the future, eg to help with forecasting.
They are activated by the \f[CR]\-\-forecast\f[R] option.
.IP \[bu] 2
The balance command\[aq]s \f[CR]\-\-budget\f[R] option uses these same
periodic rules to generate goals for the budget report.
.IP \[bu] 2
Auto posting rules can generate extra postings on certain matched
transactions.
They are always applied to forecast transactions; with the
\f[CR]\-\-auto\f[R] flag they are applied to transactions recorded in
the journal as well.
Missing amounts or missing costs in transactions are inferred
automatically when possible.
.IP \[bu] 2
The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity
postings from \[at]/\[at]\[at] costs.
And the inverse \f[CR]\-\-infer\-costs\f[R] flag infers missing
\[at]/\[at]\[at] costs from conversion equity postings.
.IP \[bu] 2
The \f[CR]\-\-infer\-costs\f[R] flag infers missing costs from
conversion equity postings.
.IP \[bu] 2
The \f[CR]\-\-infer\-market\-prices\f[R] flag infers \f[CR]P\f[R] price
directives from costs.
.IP \[bu] 2
The \f[CR]\-\-auto\f[R] flag adds extra postings to transactions matched
by auto posting rules.
.IP \[bu] 2
The \f[CR]\-\-forecast\f[R] option generates transactions from periodic
transaction rules.
.IP \[bu] 2
The \f[CR]balance \-\-budget\f[R] report infers budget goals from
periodic transaction rules.
.IP \[bu] 2
Commands like \f[CR]close\f[R], \f[CR]rewrite\f[R], and
\f[CR]hledger\-interest\f[R] generate transactions or postings.
.IP \[bu] 2
CSV data is converted to transactions by applying CSV conversion rules..
etc.
.PP
Generated data of this kind is temporary, existing only at report time.
But you can see it in the output of \f[CR]hledger print\f[R], and you
can save that to your journal, in effect converting it from temporary
generated data to permanent recorded data.
This could be useful as a data entry aid.
Such generated data is temporary, existing only at report time.
You can convert it to permanent recorded data by, eg, capturing the
output of \f[CR]hledger print\f[R] and saving it in your journal file.
This can sometimes be useful as a data entry aid.
.PP
If you are wondering what data is being generated and why, add the
\f[CR]\-\-verbose\-tags\f[R] flag.
In \f[CR]hledger print\f[R] output you will see extra tags like
\f[CR]generated\-transaction\f[R], \f[CR]generated\-posting\f[R], and
\f[CR]modified\f[R] on generated/modified data.
Also, even without \f[CR]\-\-verbose\-tags\f[R], generated data always
has equivalen hidden tags (with an underscore prefix), so eg you could
match generated transactions with
\f[CR]tag:_generated\-transaction\f[R].
If you are curious what data is being generated and why, run
\f[CR]hledger print \-x \-\-verbose\-tags\f[R].
\f[CR]\-x/\-\-explicit\f[R] shows inferred amounts and
\f[CR]\-\-verbose\-tags\f[R] adds tags like
\f[CR]generated\-transaction\f[R] (from periodic rules) and
\f[CR]generated\-posting\f[R], \f[CR]modified\f[R] (from auto posting
rules).
Similar hidden tags (with an underscore prefix) are always present,
also, so you can always match such data with queries like
\f[CR]tag:generated\f[R] or \f[CR]tag:modified\f[R].
.SH Forecasting
Forecasting, or speculative future reporting, can be useful for
estimating future balances, or for exploring different future scenarios.

2278
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

273
hledger/hledger.txt
View File

@ -7,8 +7,10 @@ NAME
SYNOPSIS
hledger
hledger COMMAND [OPTS] [ARGS]
hledger ADDONCMD -- [OPTS] [ARGS]
or
hledger COMMAND [OPTS] [ARGS]
or
hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]
DESCRIPTION
hledger is a robust, user-friendly, cross-platform set of programs for
@ -149,29 +151,29 @@ Input
$ cat FILE | hledger -f- print
If reading non-journal data in this way, you'll need to add a file for-
mat prefix, like:
If reading non-journal data in this way, you'll need to write the for-
mat as a prefix, like timeclock: here:
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
Multiple files
You can specify multiple -f options, to read multiple files as one big
You can specify multiple -f options, to read multiple files as one big
journal. When doing this, note that certain features (described below)
will be affected:
o Balance assertions will not see the effect of transactions in previ-
ous files. (Usually this doesn't matter as each file will set the
o Balance assertions will not see the effect of transactions in previ-
ous files. (Usually this doesn't matter as each file will set the
corresponding opening balances.)
o Some directives will not affect previous or subsequent files.
If needed, you can work around these by using a single parent file
If needed, you can work around these by using a single parent file
which includes the others, or concatenating the files into one, eg: cat
a.journal b.journal | hledger -f- CMD.
Strict mode
hledger checks input files for valid data. By default, the most impor-
tant errors are detected, while still accepting easy journal files
tant errors are detected, while still accepting easy journal files
without a lot of declarations:
o Are the input files parseable, with valid syntax ?
@ -182,7 +184,7 @@ Input
With the -s/--strict flag, additional checks are performed:
o Are all accounts posted to, declared with an account directive ?
o Are all accounts posted to, declared with an account directive ?
(Account error checking)
o Are all commodities declared with a commodity directive ? (Commodity
@ -190,13 +192,13 @@ Input
o Are all commodity conversions declared explicitly ?
You can use the check command to run individual checks -- the ones
You can use the check command to run individual checks -- the ones
listed above and some more.
Commands
hledger provides various subcommands for getting things done. Most of
these commands do not change the journal file; they just read it and
output a report. A few commands assist with adding data and file man-
hledger provides various subcommands for getting things done. Most of
these commands do not change the journal file; they just read it and
output a report. A few commands assist with adding data and file man-
agement.
To show the commands list, run hledger with no arguments. The commands
@ -204,44 +206,44 @@ Commands
To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
o CMD is the full command name, or its standard abbreviation shown in
o CMD is the full command name, or its standard abbreviation shown in
the commands list, or any unambiguous prefix of the name.
o CMDOPTS are command-specific options, if any. Command-specific op-
o CMDOPTS are command-specific options, if any. Command-specific op-
tions must be written after the command name. Eg: hledger print -x.
o CMDARGS are additional arguments to the command, if any. Most
hledger commands accept arguments representing a query, to limit the
o CMDARGS are additional arguments to the command, if any. Most
hledger commands accept arguments representing a query, to limit the
data in some way. Eg: hledger reg assets:checking.
To list a command's options, arguments, and documentation in the termi-
nal, run hledger CMD -h. Eg: hledger bal -h.
Add-on commands
In addition to the built-in commands, you can install add-on commands:
programs or scripts named "hledger-SOMETHING", which will also appear
in hledger's commands list. If you used the hledger-install script,
you will have several add-ons installed already. Some more can be
found in hledger's bin/ directory, documented at
In addition to the built-in commands, you can install add-on commands:
programs or scripts named "hledger-SOMETHING", which will also appear
in hledger's commands list. If you used the hledger-install script,
you will have several add-ons installed already. Some more can be
found in hledger's bin/ directory, documented at
https://hledger.org/scripts.html.
More precisely, add-on commands are programs or scripts in your shell's
PATH, whose name starts with "hledger-" and ends with no extension or a
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
and mac) which has executable permission for the current user.
You can run add-on commands using hledger, much like built-in commands:
hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
hyphen argument, required before add-on-specific options. Eg: hledger
ui -- --watch or hledger web -- --serve. If this causes difficulty,
hyphen argument, required before add-on-specific options. Eg: hledger
ui -- --watch or hledger web -- --serve. If this causes difficulty,
you can always run the add-on directly, without using hledger:
hledger-ui --watch or hledger-web --serve.
Options
Run hledger -h to see general command line help, and general options
which are common to most hledger commands. These options can be writ-
ten anywhere on the command line:
Run hledger -h to see general command line help. The following general
options are common to most hledger commands. General options can be
written either before or after the command name.
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
@ -309,7 +311,6 @@ Options
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -318,19 +319,22 @@ Options
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
Some reporting options can also be written as query arguments.
Usually hledger accepts any unambiguous flag prefix, eg you can write
--tl instead of --tldr or --dry instead of --dry-run.
Command line tips
Here are some details useful to know about for hledger command lines
(and elsewhere). Feel free to skip this section until you need it.
If the same option appears more than once in a command, usually the
last (right-most) wins.
Option repetition
If options are repeated in a command line, hledger will generally use
the last (right-most) occurence.
With most commands, arguments are interpreted as a hledger query which
filter the data. Some queries can be expressed either with options or
with arguments.
Below are more tips for using the command line interface - feel free to
skip these until you need them.
Special characters
Single escaping (shell metacharacters)
@ -616,78 +620,79 @@ Output
sentation of hledger's internal data types. To understand the JSON,
read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/mas-
ter/hledger-lib/Hledger/Data/Types.hs.
ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI speci-
fication may also be relevant.
o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
arise in practice (from automatically-calculated transaction prices),
and would break most JSON consumers. So in JSON, we show quantities
and would break most JSON consumers. So in JSON, we show quantities
as simple Numbers with at most 10 decimal places. We don't limit the
number of integer digits, but that part is under your control. We
hope this approach will not cause problems in practice; if you find
number of integer digits, but that part is under your control. We
hope this approach will not cause problems in practice; if you find
otherwise, please let us know. (Cf #1195)
SQL output
o This is not yet much used; real-world feedback is welcome.
o SQL output is expected to work at least with SQLite, MySQL and Post-
o SQL output is expected to work at least with SQLite, MySQL and Post-
gres.
o For SQLite, it will be more useful if you modify the generated id
o For SQLite, it will be more useful if you modify the generated id
field to be a PRIMARY KEY. Eg:
$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
o SQL output is structured with the expectations that statements will
be executed in the empty database. If you already have tables cre-
ated via SQL output of hledger, you would probably want to either
o SQL output is structured with the expectations that statements will
be executed in the empty database. If you already have tables cre-
ated via SQL output of hledger, you would probably want to either
clear tables of existing data (via delete or truncate SQL statements)
or drop tables completely as otherwise your postings will be duped.
Commodity styles
When displaying amounts, hledger infers a standard display style for
When displaying amounts, hledger infers a standard display style for
each commodity/currency, as described below in Commodity display style.
If needed, this can be overridden by a -c/--commodity-style option (ex-
cept for cost amounts and amounts displayed by the print command, which
are always displayed with all decimal digits). For example, the fol-
are always displayed with all decimal digits). For example, the fol-
lowing will force dollar amounts to be displayed as shown:
$ hledger print -c '$1.000,0'
This option can repeated to set the display style for multiple commodi-
ties/currencies. Its argument is as described in the commodity direc-
ties/currencies. Its argument is as described in the commodity direc-
tive.
In some cases hledger will adjust number formatting to improve their
In some cases hledger will adjust number formatting to improve their
parseability (such as adding trailing decimal marks when needed).
Colour
In terminal output, some commands can produce colour when the terminal
In terminal output, some commands can produce colour when the terminal
supports it:
o if the --color/--colour option is given a value of yes or always (or
o if the --color/--colour option is given a value of yes or always (or
no or never), colour will (or will not) be used;
o otherwise, if the NO_COLOR environment variable is set, colour will
o otherwise, if the NO_COLOR environment variable is set, colour will
not be used;
o otherwise, colour will be used if the output (terminal or file) sup-
o otherwise, colour will be used if the output (terminal or file) sup-
ports it.
Box-drawing
In terminal output, you can enable unicode box-drawing characters to
In terminal output, you can enable unicode box-drawing characters to
render prettier tables:
o if the --pretty option is given a value of yes or always (or no or
o if the --pretty option is given a value of yes or always (or no or
never), unicode characters will (or will not) be used;
o otherwise, unicode characters will not be used.
Paging
When showing long output in the terminal, hledger will try to use the
pager specified by the PAGER environment variable, or less, or more.
(A pager is a helper program that shows one page at a time rather than
When showing long output in the terminal, hledger will try to use the
pager specified by the PAGER environment variable, or less, or more.
(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,
@ -697,23 +702,23 @@ Output
o when viewing manuals with hledger help or hledger --man.
Note the pager is expected to handle ANSI codes, which hledger uses eg
Note the pager is expected to handle ANSI codes, which hledger uses eg
for bold emphasis. For the common pager less (and its more compatibil-
ity mode), we add R to the LESS and MORE environment variables to make
this work. If you use a different pager, you might need to configure
ity mode), we add R to the LESS and MORE 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 NO_COLOR environment variable to 1 to disable all ANSI
you can set the NO_COLOR environment variable to 1 to disable all ANSI
output (see Colour).
Debug output
We intend hledger to be relatively easy to troubleshoot, introspect and
develop. You can add --debug[=N] to any hledger command line to see
additional 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, and is not
develop. You can add --debug[=N] to any hledger command line to see
additional 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, and is not
affected by -o/--output-file (unless you redirect stderr to stdout, eg:
2>&1). It will be interleaved with normal output, which can help re-
veal when parts of the code are evaluated. To capture debug output in
2>&1). It will be interleaved with normal output, which can help re-
veal when parts of the code are evaluated. To capture debug output in
a log file instead, you can usually redirect stderr, eg:
hledger bal --debug=3 2>hledger.log
@ -721,16 +726,16 @@ Output
Environment
These environment variables affect hledger:
COLUMNS This is normally set by your terminal; some hledger commands
(register) will format their output to this width. If not set, they
COLUMNS This is normally set by your terminal; some hledger commands
(register) will format their output to this width. If not set, they
will try to use the available terminal width.
LEDGER_FILE The main journal file to use when not specified with
LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal.
NO_COLOR If this environment variable is set (with any value), hledger
will not use ANSI color codes in terminal output, unless overridden by
an explicit --color/--colour option.
NO_COLOR If this environment variable exists (with any value, including
empty), hledger will not use ANSI color codes in terminal output, un-
less overridden by an explicit --color=y/--colour=y option.
PART 2: DATA FORMATS
Journal
@ -2670,20 +2675,40 @@ Journal
Secondary dates
A secondary date is written after the primary date, following an equals
sign. If the year is omitted, the primary date's year is assumed.
When running reports, the primary (left) date is used by default, but
with the --date2 flag (or --aux-date or --effective), the secondary
(right) date will be used instead.
sign: DATE1=DATE2. If the year is omitted, the primary date's year is
assumed. When running reports, the primary (left side) date is used by
default, but with the --date2 flag (--aux-date or--effective also work,
for Ledger users), the secondary (right side) date will be used in-
stead.
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg "primary = the bank's clearing date, secondary =
date the transaction was initiated, if different".
The meaning of secondary dates is up to you. Eg it could be "primary
is the bank's clearing date, secondary is the date the transaction was
initiated, if different".
Downsides: makes your financial data more complicated, less portable,
and less trustworthy in an audit. Keeping the meaning of the two dates
consistent requires discipline, and you have to remember which report-
ing mode is appropriate for a given report. Posting dates are simpler
and better.
In practice, this feature usually adds confusion:
o You have to remember the primary and secondary dates' meaning, and
follow that consistently.
o It splits your bookkeeping into two modes, and you have to remember
which mode is appropriate for a given report.
o Usually your balance assertions will work with only one of these
modes.
o It makes your financial data more complicated, less portable, and
less clear in an audit.
o It interacts with every feature, creating an ongoing cost for imple-
mentors.
o It distracts new users and supporters.
o Posting dates are simpler and work better.
So secondary dates are officially deprecated in hledger, remaining only
as a Ledger compatibility aid; we recommend using posting dates in-
stead.
Star comments
Lines beginning with * (star/asterisk) are also comment lines. This
@ -4899,37 +4924,47 @@ Pivoting
-2 EUR
Generating data
hledger has several features for generating data, such as:
hledger can enrich the data provided to it, or generate new data, in a
number of ways. Mostly, this is done only if you request it:
o Periodic transaction rules can generate single or repeating transac-
tions following a template. These are usually dated in the future,
eg to help with forecasting. They are activated by the --forecast
option.
o The balance command's --budget option uses these same periodic rules
to generate goals for the budget report.
o Auto posting rules can generate extra postings on certain matched
transactions. They are always applied to forecast transactions; with
the --auto flag they are applied to transactions recorded in the
journal as well.
o Missing amounts or missing costs in transactions are inferred auto-
matically when possible.
o The --infer-equity flag infers missing conversion equity postings
from @/@@ costs. And the inverse --infer-costs flag infers missing
@/@@ costs from conversion equity postings.
from @/@@ costs.
Generated data of this kind is temporary, existing only at report time.
But you can see it in the output of hledger print, and you can save
that to your journal, in effect converting it from temporary generated
data to permanent recorded data. This could be useful as a data entry
aid.
o The --infer-costs flag infers missing costs from conversion equity
postings.
If you are wondering what data is being generated and why, add the
--verbose-tags flag. In hledger print output you will see extra tags
like generated-transaction, generated-posting, and modified on gener-
ated/modified data. Also, even without --verbose-tags, generated data
always has equivalen hidden tags (with an underscore prefix), so eg you
could match generated transactions with tag:_generated-transaction.
o The --infer-market-prices flag infers P price directives from costs.
o The --auto flag adds extra postings to transactions matched by auto
posting rules.
o The --forecast option generates transactions from periodic transac-
tion rules.
o The balance --budget report infers budget goals from periodic trans-
action rules.
o Commands like close, rewrite, and hledger-interest generate transac-
tions or postings.
o CSV data is converted to transactions by applying CSV conversion
rules.. etc.
Such generated data is temporary, existing only at report time. You
can convert it to permanent recorded data by, eg, capturing the output
of hledger print and saving it in your journal file. This can some-
times be useful as a data entry aid.
If you are curious what data is being generated and why, run hledger
print -x --verbose-tags. -x/--explicit shows inferred amounts and
--verbose-tags adds tags like generated-transaction (from periodic
rules) and generated-posting, modified (from auto posting rules). Sim-
ilar hidden tags (with an underscore prefix) are always present, also,
so you can always match such data with queries like tag:generated or
tag:modified.
Forecasting
Forecasting, or speculative future reporting, can be useful for esti-
@ -9112,4 +9147,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.34 May 2024 HLEDGER(1)
hledger-1.34 June 2024 HLEDGER(1)