slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-06-01 13:30:47 -10:00
parent d18c00e1ec
commit 3f3672e999
13 changed files with 1803 additions and 1870 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_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_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

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "May 2024" "hledger-ui-1.33.99 " "hledger User Manuals" .TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34.99 " "hledger User Manuals"
@ -11,9 +11,13 @@ robust, friendly plain text accounting app.
.PD 0 .PD 0
.P .P
.PD .PD
or
.PD 0
.P
.PD
\f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R] \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION .SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.33.99. This manual is for hledger\[aq]s terminal interface, version 1.34.99.
See also the hledger manual for common concepts and file formats. See also the hledger manual for common concepts and file formats.
.PP .PP
hledger is a robust, user\-friendly, cross\-platform set of programs for hledger is a robust, user\-friendly, cross\-platform set of programs for
@ -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 transactions, by pressing the F key (or starting with \-\-forecast) to
enable \[dq]forecast mode\[dq]. enable \[dq]forecast mode\[dq].
.SH OPTIONS .SH OPTIONS
Any QUERYARGS are interpreted as a hledger search query which filters Any arguments are interpreted as a hledger query which filters the data.
the data.
.PP
hledger\-ui provides the following options: hledger\-ui provides the following options:
.TP .IP
\f[CR]\-w \-\-watch\f[R] .EX
watch for data and date changes and reload automatically Flags:
.TP \-w \-\-watch watch for data and date changes and reload
\f[CR]\-\-theme=default|terminal|greenterm|dark\f[R] automatically
use this custom display theme \-\-theme=THEME use this custom display theme (default,
.TP greenterm, terminal, dark)
\f[CR]\-\-menu\f[R] \-\-cash start in the cash accounts screen
start in the menu screen \-\-bs start in the balance sheet accounts screen
.TP \-\-is start in the income statement accounts screen
\f[CR]\-\-cash\f[R] \-\-all start in the all accounts screen
start in the cash accounts screen \-\-register=ACCTREGEX start in the (first matched) account\[aq]s register
.TP \-\-change show period balances (changes) at startup instead
\f[CR]\-\-bs\f[R] of historical balances
start in the balance sheet accounts screen \-l \-\-flat show accounts as a flat list (default)
.TP \-t \-\-tree show accounts as a tree
\f[CR]\-\-is\f[R] .EE
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
.PP .PP
hledger\-ui also supports many of hledger\[aq]s general options (and the and also supports many of hledger\[aq]s general options:
hledger manual\[aq]s command line tips also apply here):
.SS General options
.IP .IP
.EX .EX
General input/data transformation flags: 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] Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be \-\-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]. \[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 \-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -160,10 +143,13 @@ General output/reporting flags (supported by some commands):
General help flags: General help flags:
\-h \-\-help show command line help \-h \-\-help show command line help
\-\-tldr show command examples with tldr \-\-tldr show command examples with tldr
\-\-info show the hledger manual with info \-\-info show the manual with info
\-\-man show the hledger manual with man \-\-man show the manual with man
\-\-version show version information \-\-version show version information
.EE .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 .SH 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: 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 Once you have fixed the problem, press g again to reload and resume
normal operation. normal operation.
(Or, you can press escape to cancel the reload attempt.) (Or, you can press escape to cancel the reload attempt.)
.SH TIPS .SH WATCH MODE
.SS Watch mode
One of hledger\-ui\[aq]s best features is the auto\-reloading One of hledger\-ui\[aq]s best features is the auto\-reloading
\f[CR]\-w/\-\-watch\f[R] mode. \f[CR]\-w/\-\-watch\f[R] mode.
With this flag, it will update the display automatically whenever With this flag, it will update the display automatically whenever
@ -458,12 +443,6 @@ know.)
.PP .PP
If you are viewing files mounted from another machine, the system clocks If you are viewing files mounted from another machine, the system clocks
on both machines should be roughly in agreement. 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 .SH ENVIRONMENT
\f[B]COLUMNS\f[R] The screen width to use. \f[B]COLUMNS\f[R] The screen width to use.
Default: the full terminal width. Default: the full terminal width.

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

@ -15,9 +15,10 @@ hledger-ui - terminal interface (TUI) for 'hledger', a robust, friendly
plain text accounting app. plain text accounting app.
'hledger-ui [OPTS] [QUERYARGS]' 'hledger-ui [OPTS] [QUERYARGS]'
or
'hledger ui -- [OPTS] [QUERYARGS]' 'hledger ui -- [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.33.99. This manual is for hledger's terminal interface, version 1.34.99.
See also the hledger manual for common concepts and file formats. See also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs hledger is a robust, user-friendly, cross-platform set of programs
@ -49,7 +50,7 @@ enable "forecast mode".
* MOUSE:: * MOUSE::
* KEYS:: * KEYS::
* SCREENS:: * SCREENS::
* TIPS:: * WATCH MODE::
* ENVIRONMENT:: * ENVIRONMENT::
* BUGS:: * BUGS::
@ -59,58 +60,25 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top
1 OPTIONS 1 OPTIONS
********* *********
Any QUERYARGS are interpreted as a hledger search query which filters Any arguments are interpreted as a hledger query which filters the data.
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' and also supports many of hledger's general options:
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
===================
General input/data transformation flags: General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be -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' Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be --color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. '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 --pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'. 'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -187,10 +154,13 @@ General output/reporting flags (supported by some commands):
General help flags: General help flags:
-h --help show command line help -h --help show command line help
--tldr show command examples with tldr --tldr show command examples with tldr
--info show the hledger manual with info --info show the manual with info
--man show the hledger manual with man --man show the manual with man
--version show version information --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 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. 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 4 SCREENS
********* *********
@ -485,21 +455,10 @@ again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.) 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 5 WATCH MODE
****** ************
* Menu:
* Watch mode::
* Debug output::

File: hledger-ui.info, Node: Watch mode, Next: Debug output, Up: TIPS
5.1 Watch mode
==============
One of hledger-ui's best features is the auto-reloading '-w/--watch' One of hledger-ui's best features is the auto-reloading '-w/--watch'
mode. With this flag, it will update the display automatically whenever 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. clocks on both machines should be roughly in agreement.
 
File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top
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
6 ENVIRONMENT 6 ENVIRONMENT
************* *************
@ -581,42 +530,36 @@ above).
 
Tag Table: Tag Table:
Node: Top221 Node: Top221
Node: OPTIONS1863 Node: OPTIONS1872
Ref: #options1961 Ref: #options1970
Node: General options2928 Node: MOUSE8150
Ref: #general-options3032 Ref: #mouse8245
Node: MOUSE8182 Node: KEYS8482
Ref: #mouse8277 Ref: #keys8575
Node: KEYS8514 Node: SCREENS13230
Ref: #keys8607 Ref: #screens13334
Node: SCREENS13262 Node: Menu screen13970
Ref: #screens13360 Ref: #menu-screen14091
Node: Menu screen13996 Node: Cash accounts screen14286
Ref: #menu-screen14117 Ref: #cash-accounts-screen14463
Node: Cash accounts screen14312 Node: Balance sheet accounts screen14647
Ref: #cash-accounts-screen14489 Ref: #balance-sheet-accounts-screen14863
Node: Balance sheet accounts screen14673 Node: Income statement accounts screen14983
Ref: #balance-sheet-accounts-screen14889 Ref: #income-statement-accounts-screen15204
Node: Income statement accounts screen15009 Node: All accounts screen15368
Ref: #income-statement-accounts-screen15230 Ref: #all-accounts-screen15549
Node: All accounts screen15394 Node: Register screen15731
Ref: #all-accounts-screen15575 Ref: #register-screen15890
Node: Register screen15757 Node: Transaction screen18174
Ref: #register-screen15916 Ref: #transaction-screen18332
Node: Transaction screen18200 Node: Error screen19749
Ref: #transaction-screen18358 Ref: #error-screen19871
Node: Error screen19775 Node: WATCH MODE20115
Ref: #error-screen19897 Ref: #watch-mode20232
Node: TIPS20141 Node: ENVIRONMENT21691
Ref: #tips20240 Ref: #environment21807
Node: Watch mode20282 Node: BUGS21998
Ref: #watch-mode20389 Ref: #bugs22081
Node: Debug output21848
Ref: #debug-output21959
Node: ENVIRONMENT22171
Ref: #environment22281
Node: BUGS22472
Ref: #bugs22555
 
End Tag Table End Tag Table

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

@ -7,10 +7,11 @@ NAME
SYNOPSIS SYNOPSIS
hledger-ui [OPTS] [QUERYARGS] hledger-ui [OPTS] [QUERYARGS]
or
hledger ui -- [OPTS] [QUERYARGS] hledger ui -- [OPTS] [QUERYARGS]
DESCRIPTION DESCRIPTION
This manual is for hledger's terminal interface, version 1.33.99. See This manual is for hledger's terminal interface, version 1.34.99. See
also the hledger manual for common concepts and file formats. also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for hledger is a robust, user-friendly, cross-platform set of programs for
@ -37,44 +38,26 @@ DESCRIPTION
enable "forecast mode". enable "forecast mode".
OPTIONS OPTIONS
Any QUERYARGS are interpreted as a hledger search query which filters Any arguments are interpreted as a hledger query which filters the
the data. 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 and also supports many of hledger's general options:
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):
General options
General input/data transformation flags: General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be -f --file=FILE Read data from FILE, or from stdin if -. Can be
specified more than once. If not specified, reads specified more than once. If not specified, reads
@ -141,7 +124,6 @@ OPTIONS
Eg: -c '.' or -c '1.000,00 EUR' Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be --color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. '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 --pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'. 'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -150,12 +132,15 @@ OPTIONS
General help flags: General help flags:
-h --help show command line help -h --help show command line help
--tldr show command examples with tldr --tldr show command examples with tldr
--info show the hledger manual with info --info show the manual with info
--man show the hledger manual with man --man show the manual with man
--version show version information --version show version information
With hledger-ui, the --debug option sends debug output to a
hledger-ui.log file in the current directory.
MOUSE 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: mouse or touchpad:
o Use mouse wheel or trackpad to scroll up and down o Use mouse wheel or trackpad to scroll up and down
@ -167,95 +152,95 @@ MOUSE
KEYS KEYS
Keyboard gives more control. Keyboard gives more control.
? shows a help dialog listing all keys. (Some of these also appear in ? 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- 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 CAPE, or LEFT, or q) to close it. The following keys work on most
screens: 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 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 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 (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 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 adjust it. (If you're on a mac, the karabiner app is one way to do
that.) that.)
With shift pressed, the cursor keys adjust the report period, limiting With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown). the transactions to be shown (by default, all are shown).
SHIFT-DOWN/UP steps downward and upward through these standard report SHIFT-DOWN/UP steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then, period durations: year, quarter, month, week, day. Then,
SHIFT-LEFT/RIGHT moves to the previous/next period. T sets the report 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 to today. With the -w/--watch option, when viewing a "current"
period (the current day, week, month, quarter, or year), the period period (the current day, week, month, quarter, or year), the period
will move automatically to track the current date. To set a non-stan- will move automatically to track the current date. To set a non-stan-
dard period, you can use / and a date: query. dard period, you can use / and a date: query.
(Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as (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, of MacOS Monterey. You can configure them as follows: open Terminal,
press CMD-comma to open preferences, click Profiles, select your cur- press CMD-comma to open preferences, click Profiles, select your cur-
rent terminal profile on the left, click Keyboard on the right, click + 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 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 Shift-Up: \033[1;2A. Press the Escape key to enter the \033 part, you
can't type it directly.) can't type it directly.)
/ lets you set a general filter query limiting the data shown, using / 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 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 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 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. 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- 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. 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- the app's initial state at startup. Or, it cancels minibuffer data en-
try or the help dialog. try or the help dialog.
CTRL-l redraws the screen and centers the selection if possible (selec- 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). top).
g reloads from the data file(s) and updates the current screen and any g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable previous screens. (With large files, this could cause a noticeable
pause.) pause.)
I toggles balance assertion checking. Disabling balance assertions I toggles balance assertion checking. Disabling balance assertions
temporarily can be useful for troubleshooting. 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. file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a terminal 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 interface. This key will be available if hledger-iadd is installed in
$path. $path.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor -nw) on the journal file. With some editors (emacs, vi), the cursor
will be positioned at the current transaction when invoked from the will be positioned at the current transaction when invoked from the
register and transaction screens, and at the error location (if possi- register and transaction screens, and at the error location (if possi-
ble) when invoked from the error screen. 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. 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, (see hledger manual > Valuation flag). More specifically,
1. By default, the V key toggles showing end value (--value=end) on or 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, off. The valuation date will be the report end date if specified,
otherwise today. 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. --value=then,EUR), the V key toggles that off or on.
Cost/value tips: - When showing end value, you can change the report Cost/value tips: - When showing end value, you can change the report
end date without restarting, by pressing / and adding a query like end date without restarting, by pressing / and adding a query like
date:..YYYY-MM-DD. - Either cost mode, or value mode, can be active, 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 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 any visual indicator that cost or value mode is active, other than the
amount values. amount values.
q quits the application. q quits the application.
@ -263,47 +248,47 @@ KEYS
Additional screen-specific keys are described below. Additional screen-specific keys are described below.
SCREENS 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, 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. 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). screen (--cs, --bs, --is, --all, or --register=ACCT).
Menu screen Menu screen
This is the top-most screen. From here you can navigate to several 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 screens listing accounts of various types. Note some of these may not
show anything until you have configured account types. show anything until you have configured account types.
Cash accounts screen Cash accounts screen
This screen shows "cash" (ie, liquid asset) accounts (like hledger bal- 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). ances on the date shown in the title line).
Balance sheet accounts screen 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. balancesheetequity). It always shows balances.
Income statement accounts screen Income statement accounts screen
This screen shows revenue and expense accounts (like hledger incomes- This screen shows revenue and expense accounts (like hledger incomes-
tatement). It always shows changes (balance changes in the period tatement). It always shows changes (balance changes in the period
shown in the title line). shown in the title line).
All accounts screen All accounts screen
This screen shows all accounts in your journal (unless filtered by a This screen shows all accounts in your journal (unless filtered by a
query; like hledger balance). It shows balances by default; you can query; like hledger balance). It shows balances by default; you can
toggle showing changes with the H key. toggle showing changes with the H key.
Register screen 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: Each line represents one transaction, and shows:
o the other account(s) involved, in abbreviated form. (If there are o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected both real and virtual postings, it shows only the accounts affected
by real postings.) 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. inflow to this account, negative for an outflow.
o the running total after the transaction. With the H key you can tog- 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 the period total, which is from just the transactions displayed
o or the historical total, which includes any undisplayed transac- o or the historical total, which includes any undisplayed transac-
tions before the start of the report period (and matching the fil- tions before the start of the report period (and matching the fil-
ter query if any). This will be the running historical balance 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 (what you would see on a bank's website, eg) if not disturbed by a
query. query.
Note, this screen combines each transaction's in-period postings to a Note, this screen combines each transaction's in-period postings to a
single line item, dated with the earliest in-period transaction or single line item, dated with the earliest in-period transaction or
posting date (like hledger's aregister). So custom posting dates can posting date (like hledger's aregister). So custom posting dates can
cause the running balance to be temporarily inaccurate. (See hledger cause the running balance to be temporarily inaccurate. (See hledger
manual > aregister and posting dates.) 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 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 mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac- depth limit. In other words, the register always shows the transac-
tions contributing to the balance shown on the accounts screen. Tree tions contributing to the balance shown on the accounts screen. Tree
mode/list mode can be toggled with t here also. mode/list mode can be toggled with t here also.
U toggles filtering by unmarked status, showing or hiding unmarked U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac- 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.) tions 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 nonzero z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com- change are shown (hledger-ui shows zero items by default, unlike com-
mand-line hledger). mand-line hledger).
Press RIGHT to view the selected transaction in detail. Press RIGHT to view the selected transaction in detail.
Transaction screen Transaction screen
This screen shows a single transaction, as a general journal entry, This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour- similar to hledger's print command and journal format (hledger_jour-
nal(5)). nal(5)).
The transaction's date(s) and any cleared flag, transaction code, de- The transaction's date(s) and any cleared flag, transaction code, de-
scription, comments, along with all of its account postings are shown. scription, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in Simple transactions have two postings, but there can be more (or in
certain cases, fewer). certain cases, fewer).
UP and DOWN will step through all transactions listed in the previous UP and DOWN will step through all transactions listed in the previous
account register screen. In the title bar, the numbers in parentheses account register screen. In the title bar, the numbers in parentheses
show your position within that account register. They will vary de- show your position within that account register. They will vary de-
pending on which account register you came from (remember most transac- 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- them is the transaction's position within the complete unfiltered jour-
nal, which is a more stable id (at least until the next reload). 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 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. ble.
This screen has a limitation with showing file updates: it will not 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 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, 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 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 file (or use -w/--watch mode) - press LEFT then RIGHT to exit and
re-enter the transaction screen. re-enter the transaction screen.
Error screen Error screen
This screen will appear if there is a problem, such as a parse error, 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 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 again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.) to cancel the reload attempt.)
TIPS WATCH MODE
Watch mode One of hledger-ui's best features is the auto-reloading -w/--watch
One of hledger-ui's best features is the auto-reloading -w/--watch mode. With this flag, it will update the display automatically when-
mode. With this flag, it will update the display automatically when-
ever changes are saved to the data files. ever changes are saved to the data files.
This is very useful when reconciling. A good workflow is to have your 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 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 journal file open in an editor window; and hledger-ui in watch mode in
a terminal window, eg: a terminal window, eg:
$ hledger-ui --watch --register checking -C $ hledger-ui --watch --register checking -C
As you mark things cleared in the editor, you can see the effect imme- As you mark things cleared in the editor, you can see the effect imme-
diately without having to context switch. This leaves more mental diately without having to context switch. This leaves more mental
bandwidth for your accounting. Of course you can still interact with bandwidth for your accounting. Of course you can still interact with
hledger-ui when needed, eg to toggle cleared mode, or to explore the hledger-ui when needed, eg to toggle cleared mode, or to explore the
history. history.
There are currently some limitations with --watch: 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- It may not work correctly for you, depending on platform or system con-
figuration. (Eg #836.) figuration. (Eg #836.)
At least on mac, there can be a slow build-up of CPU usage over time, 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 until the program is restarted (or, suspending and restarting with
CTRL-z fg may be enough). CTRL-z fg may be enough).
It will not detect file changes made by certain editors, such as Jet- 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 brains IDEs or gedit, or on certain less common filesystems. (To work
around, press g to reload manually, or try #1617's fs.ino- around, press g to reload manually, or try #1617's fs.ino-
tify.max_user_watches workaround and let us know.) 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. 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 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 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. -f/--file. Default: $HOME/.hledger.journal.
BUGS BUGS
We welcome bug reports in the hledger issue tracker (shortcut: 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). (https://hledger.org/support).
Some known issues: Some known issues:
@ -440,7 +419,7 @@ BUGS
The Transaction screen does not update from file changes until you exit The Transaction screen does not update from file changes until you exit
and re-endter it (see SCREENS > Transaction above). 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). above).
@ -461,4 +440,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.33.99 May 2024 HLEDGER-UI(1) hledger-ui-1.34.99 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_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

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "May 2024" "hledger-web-1.33.99 " "hledger User Manuals" .TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34.99 " "hledger User Manuals"
@ -7,13 +7,17 @@
hledger\-web \- web interface and API for \f[CR]hledger\f[R], a robust, hledger\-web \- web interface and API for \f[CR]hledger\f[R], a robust,
friendly plain text accounting app. friendly plain text accounting app.
.SH SYNOPSIS .SH SYNOPSIS
\f[CR]hledger\-web [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R] \f[CR]hledger\-web [OPTS] [QUERY]\f[R]
.PD 0 .PD 0
.P .P
.PD .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 .SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.33.99. This manual is for hledger\[aq]s web interface, version 1.34.99.
See also the hledger manual for common concepts and file formats. See also the hledger manual for common concepts and file formats.
.PP .PP
hledger is a robust, user\-friendly, cross\-platform set of programs for hledger is a robust, user\-friendly, cross\-platform set of programs for
@ -61,45 +65,41 @@ In all cases hledger\-web runs as a foreground process, logging requests
to stdout. to stdout.
.SH OPTIONS .SH OPTIONS
hledger\-web provides the following options: hledger\-web provides the following options:
.TP .IP
\f[CR]\-\-serve\f[R] .EX
serve and log requests, don\[aq]t browse or auto\-exit after timeout Flags:
.TP \-\-serve \-\-server serve and log requests, don\[aq]t browse or auto\-exit
\f[CR]\-\-serve\-api\f[R] \-\-serve\-api like \-\-serve, but serve only the JSON web API,
like \-\-serve, but serve only the JSON web API, not the web UI not the web UI
.TP \-\-allow=view|add|edit set the user\[aq]s access level for changing data
\f[CR]\-\-allow=view|add|edit\f[R] (default: \[ga]add\[ga]). It also accepts \[ga]sandstorm\[ga] for
set the user\[aq]s access level for changing data (default: use on that platform (reads permissions from the
\f[CR]add\f[R]). \[ga]X\-Sandstorm\-Permissions\[ga] request header).
It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads \-\-cors=ORIGIN allow cross\-origin requests from the specified
permissions from the \f[CR]X\-Sandstorm\-Permissions\f[R] request origin; setting ORIGIN to \[dq]*\[dq] allows requests from
header). any origin
.TP \-\-host=IPADDR listen on this IP address (default: 127.0.0.1)
\f[CR]\-\-cors=ORIGIN\f[R] \-\-port=PORT listen on this TCP port (default: 5000)
allow cross\-origin requests from the specified origin; setting ORIGIN \-\-socket=SOCKET listen on the given unix socket instead of an IP
to \[dq]*\[dq] allows requests from any origin address and port (unix only; implies \-\-serve)
.TP \-\-base\-url=BASEURL set the base url (default: http://IPADDR:PORT)
\f[CR]\-\-host=IPADDR\f[R] \-\-test run hledger\-web\[aq]s tests and exit. hspec test
listen on this IP address (default: 127.0.0.1) runner args may follow a \-\-, eg: hledger\-web \-\-test
\-\- \-\-help
.EE
.PP .PP
By default the server listens on IP address \f[CR]127.0.0.1\f[R], which By default hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R],
is accessible only to requests from the local machine.. which be accessed only from the local machine.
You can use \f[CR]\-\-host\f[R] to listen on a different address .PP
configured on the machine, eg to allow access from other machines. To allow access from elsewhere, use \f[CR]\-\-host\f[R] to specify an
The special address \f[CR]0.0.0.0\f[R] causes it to listen on all externally accessible address configured on this machine, The special
addresses configured on the machine. address \f[CR]0.0.0.0\f[R] causes it to listen on all of this
.TP machine\[aq]s addresses.
\f[CR]\-\-port=PORT\f[R]
listen on this TCP port (default: 5000)
.PP .PP
Similarly, you can use \f[CR]\-\-port\f[R] to listen on a TCP port other Similarly, you can use \f[CR]\-\-port\f[R] to listen on a TCP port other
than 5000. than 5000.
This is useful if you want to run multiple hledger\-web instances on a This is useful if you want to run multiple hledger\-web instances on a
machine. 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 .PP
When \f[CR]\-\-socket\f[R] is used, hledger\-web creates and When \f[CR]\-\-socket\f[R] is used, hledger\-web creates and
communicates via a socket file instead of a TCP port. 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. nginx reverse proxy.
(Eg: (Eg:
\f[CR]proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;\f[R].) \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 .PP
You can use \f[CR]\-\-base\-url\f[R] to change the protocol, hostname, 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. 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 configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT
is 80). is 80).
Note this affects url generation but not route parsing. 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 .PP
hledger\-web also supports many of hledger\[aq]s general options. 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
.IP .IP
.EX .EX
General input/data transformation flags: 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] Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be \-\-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]. \[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 \-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -216,10 +194,22 @@ General output/reporting flags (supported by some commands):
General help flags: General help flags:
\-h \-\-help show command line help \-h \-\-help show command line help
\-\-tldr show command examples with tldr \-\-tldr show command examples with tldr
\-\-info show the hledger manual with info \-\-info show the manual with info
\-\-man show the hledger manual with man \-\-man show the manual with man
\-\-version show version information \-\-version show version information
.EE .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 .SH PERMISSIONS
By default, hledger\-web allows anyone who can reach it to view the 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. 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 what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. on the various data types, eg Transaction.
And for a higher level understanding, see the journal docs. And for a higher level understanding, see the journal docs.
There is also a basic OpenAPI specification.
.PP .PP
In some cases there is outer JSON corresponding to a \[dq]Report\[dq] In some cases there is outer JSON corresponding to a \[dq]Report\[dq]
type. type.

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

@ -14,10 +14,11 @@ hledger-web(1)
hledger-web - web interface and API for 'hledger', a robust, friendly hledger-web - web interface and API for 'hledger', a robust, friendly
plain text accounting app. plain text accounting app.
'hledger-web [--serve|--serve-api] [OPTS] [ARGS]' 'hledger-web [OPTS] [QUERY]'
'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]' or
'hledger web -- [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.33.99. See This manual is for hledger's web interface, version 1.34.99. See
also the hledger manual for common concepts and file formats. also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs hledger is a robust, user-friendly, cross-platform set of programs
@ -78,54 +79,43 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
hledger-web provides the following options: 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 By default hledger-web listens only on IP address '127.0.0.1', which
'--serve-api' be accessed only from the local machine.
like -serve, but serve only the JSON web API, not the web UI To allow access from elsewhere, use '--host' to specify an externally
'--allow=view|add|edit' accessible address configured on this machine, The special address
'0.0.0.0' causes it to listen on all of this machine's addresses.
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)
Similarly, you can use '--port' to listen on a TCP port other than 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 5000. This is useful if you want to run multiple hledger-web instances
on a machine. 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 When '--socket' is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as unix file permissions, and makes certain use cases easier, such as
running per-user instances behind an nginx reverse proxy. (Eg: running per-user instances behind an nginx reverse proxy. (Eg:
'proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;'.) '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 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 path that appear in hledger-web's hyperlinks. This is useful eg when
integrating hledger-web within a larger website. The default is 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 port (or 'http://HOST' if PORT is 80). Note this affects url generation
but not route parsing. but not route parsing.
'--test' hledger-web also supports many of hledger's general options:
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
===================
General input/data transformation flags: General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be -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' Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be --color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. '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 --pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'. 'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -237,10 +199,21 @@ General output/reporting flags (supported by some commands):
General help flags: General help flags:
-h --help show command line help -h --help show command line help
--tldr show command examples with tldr --tldr show command examples with tldr
--info show the hledger manual with info --info show the manual with info
--man show the hledger manual with man --man show the manual with man
--version show version information --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 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 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 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 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. 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 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: Tag Table:
Node: Top223 Node: Top223
Node: OPTIONS2608 Node: OPTIONS2569
Ref: #options2713 Ref: #options2674
Node: General options5617 Node: PERMISSIONS10862
Ref: #general-options5722 Ref: #permissions11001
Node: PERMISSIONS10872 Node: EDITING UPLOADING DOWNLOADING12213
Ref: #permissions11011 Ref: #editing-uploading-downloading12394
Node: EDITING UPLOADING DOWNLOADING12223 Node: RELOADING13228
Ref: #editing-uploading-downloading12404 Ref: #reloading13362
Node: RELOADING13238 Node: JSON API13795
Ref: #reloading13372 Ref: #json-api13910
Node: JSON API13805 Node: DEBUG OUTPUT19444
Ref: #json-api13920 Ref: #debug-output19569
Node: DEBUG OUTPUT19408 Node: Debug output19596
Ref: #debug-output19533 Ref: #debug-output-119697
Node: Debug output19560 Node: ENVIRONMENT20114
Ref: #debug-output-119661 Ref: #environment20233
Node: ENVIRONMENT20078 Node: BUGS20350
Ref: #environment20197 Ref: #bugs20434
Node: BUGS20314
Ref: #bugs20398
 
End Tag Table End Tag Table

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

@ -6,11 +6,12 @@ NAME
plain text accounting app. plain text accounting app.
SYNOPSIS SYNOPSIS
hledger-web [--serve|--serve-api] [OPTS] [ARGS] hledger-web [OPTS] [QUERY]
hledger web -- [--serve|--serve-api] [OPTS] [ARGS] or
hledger web -- [OPTS] [QUERY]
DESCRIPTION DESCRIPTION
This manual is for hledger's web interface, version 1.33.99. See also This manual is for hledger's web interface, version 1.34.99. See also
the hledger manual for common concepts and file formats. the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for hledger is a robust, user-friendly, cross-platform set of programs for
@ -55,50 +56,43 @@ DESCRIPTION
OPTIONS OPTIONS
hledger-web provides the following options: hledger-web provides the following options:
--serve Flags:
serve and log requests, don't browse or auto-exit after timeout --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 By default hledger-web listens only on IP address 127.0.0.1, which be
like --serve, but serve only the JSON web API, not the web UI accessed only from the local machine.
--allow=view|add|edit To allow access from elsewhere, use --host to specify an externally ac-
set the user's access level for changing data (default: add). cessible address configured on this machine, The special address
It also accepts sandstorm for use on that platform (reads per- 0.0.0.0 causes it to listen on all of this machine's addresses.
missions from the X-Sandstorm-Permissions request header).
--cors=ORIGIN Similarly, you can use --port to listen on a TCP port other than 5000.
allow cross-origin requests from the specified origin; setting This is useful if you want to run multiple hledger-web instances on a
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
machine. 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 When --socket is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects 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- unix file permissions, and makes certain use cases easier, such as run-
ning per-user instances behind an nginx reverse proxy. (Eg: proxy_pass ning per-user instances behind an nginx reverse proxy. (Eg: proxy_pass
http://unix:/tmp/hledger/${remote_user}.socket;.) 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 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- that appear in hledger-web's hyperlinks. This is useful eg when inte-
grating hledger-web within a larger website. The default is 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 port (or http://HOST if PORT is 80). Note this affects url generation
but not route parsing. but not route parsing.
--test run hledger-web's tests and exit. hspec test runner args may hledger-web also supports many of hledger's general options:
follow a --, eg: hledger-web --test -- --help
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: General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be -f --file=FILE Read data from FILE, or from stdin if -. Can be
specified more than once. If not specified, reads specified more than once. If not specified, reads
@ -190,7 +168,6 @@ OPTIONS
Eg: -c '.' or -c '1.000,00 EUR' Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be --color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. '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 --pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'. 'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -199,10 +176,21 @@ OPTIONS
General help flags: General help flags:
-h --help show command line help -h --help show command line help
--tldr show command examples with tldr --tldr show command examples with tldr
--info show the hledger manual with info --info show the manual with info
--man show the hledger manual with man --man show the manual with man
--version show version information --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 PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the 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. 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 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 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- 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 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 understand that, go to the Hledger.Web.Handler.MiscR haddock and look
@ -484,4 +473,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.33.99 May 2024 HLEDGER-WEB(1) hledger-web-1.34.99 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_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

175
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "HLEDGER" "1" "May 2024" "hledger-1.33.99 " "hledger User Manuals" .TH "HLEDGER" "1" "June 2024" "hledger-1.34.99 " "hledger User Manuals"
@ -12,11 +12,19 @@ version).
.PD 0 .PD 0
.P .P
.PD .PD
\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R] or
.PD 0 .PD 0
.P .P
.PD .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 .SH DESCRIPTION
hledger is a robust, user\-friendly, cross\-platform set of programs for hledger is a robust, user\-friendly, cross\-platform set of programs for
tracking money, time, or any other commodity, using double\-entry tracking money, time, or any other commodity, using double\-entry
@ -25,7 +33,7 @@ hledger is inspired by and largely compatible with ledger(1), and
largely interconvertible with beancount(1). largely interconvertible with beancount(1).
.PP .PP
This manual is for hledger\[aq]s command line interface, version This manual is for hledger\[aq]s command line interface, version
1.33.99. 1.34.99.
It also describes the common options, file formats and concepts used by It also describes the common options, file formats and concepts used by
all hledger programs. all hledger programs.
It might accidentally teach you some bookkeeping/accounting as well! It might accidentally teach you some bookkeeping/accounting as well!
@ -227,8 +235,8 @@ The file name \f[CR]\-\f[R] means standard input:
$ cat FILE | hledger \-f\- print $ cat FILE | hledger \-f\- print
.EE .EE
.PP .PP
If reading non\-journal data in this way, you\[aq]ll need to add a file If reading non\-journal data in this way, you\[aq]ll need to write the
format prefix, like: format as a prefix, like \f[CR]timeclock:\f[R] here:
.IP .IP
.EX .EX
$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\- $ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\-
@ -329,9 +337,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 without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or
\f[CR]hledger\-web \-\-serve\f[R]. \f[CR]hledger\-web \-\-serve\f[R].
.SH Options .SH Options
Run \f[CR]hledger \-h\f[R] to see general command line help, and general Run \f[CR]hledger \-h\f[R] to see general command line help.
options which are common to most hledger commands. The following general options are common to most hledger commands.
These options can be written anywhere on the command line: General options can be written either before or after the command name.
.IP .IP
.EX .EX
General input/data transformation flags: General input/data transformation flags:
@ -400,7 +408,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be \-\-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]. \[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 \-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -409,19 +416,24 @@ General output/reporting flags (supported by some commands):
General help flags: General help flags:
\-h \-\-help show command line help \-h \-\-help show command line help
\-\-tldr show command examples with tldr \-\-tldr show command examples with tldr
\-\-info show the hledger manual with info \-\-info show the manual with info
\-\-man show the hledger manual with man \-\-man show the manual with man
\-\-version show version information \-\-version show version information
.EE .EE
.PP .PP
Some reporting options can also be written as query arguments. Usually hledger accepts any unambiguous flag prefix, eg you can write
.SH Command line tips \f[CR]\-\-tl\f[R] instead of \f[CR]\-\-tldr\f[R] or \f[CR]\-\-dry\f[R]
Here are some details useful to know about for hledger command lines instead of \f[CR]\-\-dry\-run\f[R].
(and elsewhere). .PP
Feel free to skip this section until you need it. If the same option appears more than once in a command, usually the last
.SS Option repetition (right\-most) wins.
If options are repeated in a command line, hledger will generally use .PP
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.
.PP
Below are more tips for using the command line interface \- feel free to
skip these until you need them.
.SS Special characters .SS Special characters
.SS Single escaping (shell metacharacters) .SS Single escaping (shell metacharacters)
In shell command lines, characters significant to your shell \- such as In shell command lines, characters significant to your shell \- such as
@ -886,6 +898,7 @@ representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are To understand the JSON, read the Haskell type definitions, which are
mostly in mostly in
https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs. 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 .IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255 hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. significant digits, eg for repeating decimals.
@ -1018,9 +1031,10 @@ If not set, they will try to use the available terminal width.
with \f[CR]\-f/\-\-file\f[R]. with \f[CR]\-f/\-\-file\f[R].
Default: \f[CR]$HOME/.hledger.journal\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R].
.PP .PP
\f[B]NO_COLOR\f[R] If this environment variable is set (with any value), \f[B]NO_COLOR\f[R] If this environment variable exists (with any value,
hledger will not use ANSI color codes in terminal output, unless including empty), hledger will not use ANSI color codes in terminal
overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option. 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 PART 2: DATA FORMATS
.SH Journal .SH Journal
hledger\[aq]s usual data source is a plain text file containing journal hledger\[aq]s usual data source is a plain text file containing journal
@ -3411,24 +3425,39 @@ when evaluating a region of the journal in your editor.
A missing Y directive makes reports dependent on today\[aq]s date. A missing Y directive makes reports dependent on today\[aq]s date.
.SS Secondary dates .SS Secondary dates
A secondary date is written after the primary date, following an equals 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. 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 When running reports, the primary (left side) date is used by default,
with the \f[CR]\-\-date2\f[R] flag (or \f[CR]\-\-aux\-date\f[R] or but with the \f[CR]\-\-date2\f[R] flag (\f[CR]\-\-aux\-date\f[R]
\f[CR]\-\-effective\f[R]), the secondary (right) date will be used or\f[CR]\-\-effective\f[R] also work, for Ledger users), the secondary
instead. (right side) date will be used instead.
.PP .PP
The meaning of secondary dates is up to you, but it\[aq]s best to follow The meaning of secondary dates is up to you.
a consistent rule. Eg it could be \[dq]primary is the bank\[aq]s clearing date, secondary
Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the is the date the transaction was initiated, if different\[dq].
transaction was initiated, if different\[dq].
.PP .PP
Downsides: makes your financial data more complicated, less portable, In practice, this feature usually adds confusion:
and less trustworthy in an audit. .IP \[bu] 2
Keeping the meaning of the two dates consistent requires discipline, and You have to remember the primary and secondary dates\[aq] meaning, and
you have to remember which reporting mode is appropriate for a given follow that consistently.
report. .IP \[bu] 2
Posting dates are simpler and better. 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 .SS Star comments
Lines beginning with \f[CR]*\f[R] (star/asterisk) are also comment Lines beginning with \f[CR]*\f[R] (star/asterisk) are also comment
lines. lines.
@ -6335,42 +6364,52 @@ $ hledger balance Income:Dues \-\-pivot kind:member
\-2 EUR \-2 EUR
.EE .EE
.SH Generating data .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 .IP \[bu] 2
Periodic transaction rules can generate single or repeating transactions Missing amounts or missing costs in transactions are inferred
following a template. automatically when possible.
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.
.IP \[bu] 2 .IP \[bu] 2
The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity
postings from \[at]/\[at]\[at] costs. postings from \[at]/\[at]\[at] costs.
And the inverse \f[CR]\-\-infer\-costs\f[R] flag infers missing .IP \[bu] 2
\[at]/\[at]\[at] costs from conversion equity postings. 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 .PP
Generated data of this kind is temporary, existing only at report time. Such generated data is temporary, existing only at report time.
But you can see it in the output of \f[CR]hledger print\f[R], and you You can convert it to permanent recorded data by, eg, capturing the
can save that to your journal, in effect converting it from temporary output of \f[CR]hledger print\f[R] and saving it in your journal file.
generated data to permanent recorded data. This can sometimes be useful as a data entry aid.
This could be useful as a data entry aid.
.PP .PP
If you are wondering what data is being generated and why, add the If you are curious what data is being generated and why, run
\f[CR]\-\-verbose\-tags\f[R] flag. \f[CR]hledger print \-x \-\-verbose\-tags\f[R].
In \f[CR]hledger print\f[R] output you will see extra tags like \f[CR]\-x/\-\-explicit\f[R] shows inferred amounts and
\f[CR]generated\-transaction\f[R], \f[CR]generated\-posting\f[R], and \f[CR]\-\-verbose\-tags\f[R] adds tags like
\f[CR]modified\f[R] on generated/modified data. \f[CR]generated\-transaction\f[R] (from periodic rules) and
Also, even without \f[CR]\-\-verbose\-tags\f[R], generated data always \f[CR]generated\-posting\f[R], \f[CR]modified\f[R] (from auto posting
has equivalen hidden tags (with an underscore prefix), so eg you could rules).
match generated transactions with Similar hidden tags (with an underscore prefix) are always present,
\f[CR]tag:_generated\-transaction\f[R]. 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 .SH Forecasting
Forecasting, or speculative future reporting, can be useful for Forecasting, or speculative future reporting, can be useful for
estimating future balances, or for exploring different future scenarios. estimating future balances, or for exploring different future scenarios.

2280
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

275
hledger/hledger.txt
View File

@ -7,8 +7,10 @@ NAME
SYNOPSIS SYNOPSIS
hledger hledger
hledger COMMAND [OPTS] [ARGS] or
hledger ADDONCMD -- [OPTS] [ARGS] hledger COMMAND [OPTS] [ARGS]
or
hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]
DESCRIPTION DESCRIPTION
hledger is a robust, user-friendly, cross-platform set of programs for hledger is a robust, user-friendly, cross-platform set of programs for
@ -17,7 +19,7 @@ DESCRIPTION
and largely compatible with ledger(1), and largely interconvertible and largely compatible with ledger(1), and largely interconvertible
with beancount(1). with beancount(1).
This manual is for hledger's command line interface, version 1.33.99. This manual is for hledger's command line interface, version 1.34.99.
It also describes the common options, file formats and concepts used by It also describes the common options, file formats and concepts used by
all hledger programs. It might accidentally teach you some bookkeep- all hledger programs. It might accidentally teach you some bookkeep-
ing/accounting as well! You don't need to know everything in here to ing/accounting as well! You don't need to know everything in here to
@ -149,29 +151,29 @@ Input
$ cat FILE | hledger -f- print $ cat FILE | hledger -f- print
If reading non-journal data in this way, you'll need to add a file for- If reading non-journal data in this way, you'll need to write the for-
mat prefix, like: mat as a prefix, like timeclock: here:
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
Multiple files 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) journal. When doing this, note that certain features (described below)
will be affected: will be affected:
o Balance assertions will not see the effect of transactions in previ- 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 ous files. (Usually this doesn't matter as each file will set the
corresponding opening balances.) corresponding opening balances.)
o Some directives will not affect previous or subsequent files. 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 which includes the others, or concatenating the files into one, eg: cat
a.journal b.journal | hledger -f- CMD. a.journal b.journal | hledger -f- CMD.
Strict mode Strict mode
hledger checks input files for valid data. By default, the most impor- 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: without a lot of declarations:
o Are the input files parseable, with valid syntax ? o Are the input files parseable, with valid syntax ?
@ -182,7 +184,7 @@ Input
With the -s/--strict flag, additional checks are performed: 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) (Account error checking)
o Are all commodities declared with a commodity directive ? (Commodity o Are all commodities declared with a commodity directive ? (Commodity
@ -190,13 +192,13 @@ Input
o Are all commodity conversions declared explicitly ? 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. listed above and some more.
Commands Commands
hledger provides various subcommands for getting things done. Most of hledger provides various subcommands for getting things done. Most of
these commands do not change the journal file; they just read it and 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- output a report. A few commands assist with adding data and file man-
agement. agement.
To show the commands list, run hledger with no arguments. The commands 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], 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. 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. tions must be written after the command name. Eg: hledger print -x.
o CMDARGS are additional arguments to the command, if any. Most o CMDARGS are additional arguments to the command, if any. Most
hledger commands accept arguments representing a query, to limit the hledger commands accept arguments representing a query, to limit the
data in some way. Eg: hledger reg assets:checking. data in some way. Eg: hledger reg assets:checking.
To list a command's options, arguments, and documentation in the termi- To list a command's options, arguments, and documentation in the termi-
nal, run hledger CMD -h. Eg: hledger bal -h. nal, run hledger CMD -h. Eg: hledger bal -h.
Add-on commands Add-on commands
In addition to the built-in commands, you can install 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 programs or scripts named "hledger-SOMETHING", which will also appear
in hledger's commands list. If you used the hledger-install script, in hledger's commands list. If you used the hledger-install script,
you will have several add-ons installed already. Some more can be you will have several add-ons installed already. Some more can be
found in hledger's bin/ directory, documented at found in hledger's bin/ directory, documented at
https://hledger.org/scripts.html. https://hledger.org/scripts.html.
More precisely, add-on commands are programs or scripts in your shell's 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 PATH, whose name starts with "hledger-" and ends with no extension or a
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
and mac) which has executable permission for the current user. and mac) which has executable permission for the current user.
You can run add-on commands using hledger, much like built-in commands: You can run add-on commands using hledger, much like built-in commands:
hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
hyphen argument, required before add-on-specific options. Eg: hledger hyphen argument, required before add-on-specific options. Eg: hledger
ui -- --watch or hledger web -- --serve. If this causes difficulty, ui -- --watch or hledger web -- --serve. If this causes difficulty,
you can always run the add-on directly, without using hledger: you can always run the add-on directly, without using hledger:
hledger-ui --watch or hledger-web --serve. hledger-ui --watch or hledger-web --serve.
Options Options
Run hledger -h to see general command line help, and general options Run hledger -h to see general command line help. The following general
which are common to most hledger commands. These options can be writ- options are common to most hledger commands. General options can be
ten anywhere on the command line: written either before or after the command name.
General input/data transformation flags: General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be -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' Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be --color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. '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 --pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'. 'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required. If YN is specified, the equals is required.
@ -318,19 +319,22 @@ Options
General help flags: General help flags:
-h --help show command line help -h --help show command line help
--tldr show command examples with tldr --tldr show command examples with tldr
--info show the hledger manual with info --info show the manual with info
--man show the hledger manual with man --man show the manual with man
--version show version information --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 If the same option appears more than once in a command, usually the
Here are some details useful to know about for hledger command lines last (right-most) wins.
(and elsewhere). Feel free to skip this section until you need it.
Option repetition With most commands, arguments are interpreted as a hledger query which
If options are repeated in a command line, hledger will generally use filter the data. Some queries can be expressed either with options or
the last (right-most) occurence. with arguments.
Below are more tips for using the command line interface - feel free to
skip these until you need them.
Special characters Special characters
Single escaping (shell metacharacters) Single escaping (shell metacharacters)
@ -616,78 +620,79 @@ Output
sentation of hledger's internal data types. To understand the JSON, sentation of hledger's internal data types. To understand the JSON,
read the Haskell type definitions, which are mostly in read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/mas- 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 o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can significant digits, eg for repeating decimals. Such numbers can
arise in practice (from automatically-calculated transaction prices), 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 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 number of integer digits, but that part is under your control. We
hope this approach will not cause problems in practice; if you find hope this approach will not cause problems in practice; if you find
otherwise, please let us know. (Cf #1195) otherwise, please let us know. (Cf #1195)
SQL output SQL output
o This is not yet much used; real-world feedback is welcome. 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. 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: field to be a PRIMARY KEY. Eg:
$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... $ 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 o SQL output is structured with the expectations that statements will
be executed in the empty database. If you already have tables cre- be executed in the empty database. If you already have tables cre-
ated via SQL output of hledger, you would probably want to either ated via SQL output of hledger, you would probably want to either
clear tables of existing data (via delete or truncate SQL statements) clear tables of existing data (via delete or truncate SQL statements)
or drop tables completely as otherwise your postings will be duped. or drop tables completely as otherwise your postings will be duped.
Commodity styles 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. each commodity/currency, as described below in Commodity display style.
If needed, this can be overridden by a -c/--commodity-style option (ex- 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 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: lowing will force dollar amounts to be displayed as shown:
$ hledger print -c '$1.000,0' $ hledger print -c '$1.000,0'
This option can repeated to set the display style for multiple commodi- 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. 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). parseability (such as adding trailing decimal marks when needed).
Colour 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: 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; 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; 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. ports it.
Box-drawing 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: 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; never), unicode characters will (or will not) be used;
o otherwise, unicode characters will not be used. o otherwise, unicode characters will not be used.
Paging Paging
When showing long output in the terminal, hledger will try to use the When showing long output in the terminal, hledger will try to use the
pager specified by the PAGER environment variable, or less, or more. 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 (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 scrolling everything off screen). Currently it does this only for help
output, not for reports; specifically, output, not for reports; specifically,
@ -697,23 +702,23 @@ Output
o when viewing manuals with hledger help or hledger --man. 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- 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 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 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, 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). output (see Colour).
Debug output Debug output
We intend hledger to be relatively easy to troubleshoot, introspect and We intend hledger to be relatively easy to troubleshoot, introspect and
develop. You can add --debug[=N] to any hledger command line to see develop. You can add --debug[=N] to any hledger command line to see
additional debug output. N ranges from 1 (least output, the default) additional debug output. N ranges from 1 (least output, the default)
to 9 (maximum output). Typically you would start with 1 and increase 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 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: 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- 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 veal when parts of the code are evaluated. To capture debug output in
a log file instead, you can usually redirect stderr, eg: a log file instead, you can usually redirect stderr, eg:
hledger bal --debug=3 2>hledger.log hledger bal --debug=3 2>hledger.log
@ -721,16 +726,16 @@ Output
Environment Environment
These environment variables affect hledger: These environment variables affect hledger:
COLUMNS This is normally set by your terminal; some hledger commands COLUMNS This is normally set by your terminal; some hledger commands
(register) will format their output to this width. If not set, they (register) will format their output to this width. If not set, they
will try to use the available terminal width. 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. -f/--file. Default: $HOME/.hledger.journal.
NO_COLOR If this environment variable is set (with any value), hledger NO_COLOR If this environment variable exists (with any value, including
will not use ANSI color codes in terminal output, unless overridden by empty), hledger will not use ANSI color codes in terminal output, un-
an explicit --color/--colour option. less overridden by an explicit --color=y/--colour=y option.
PART 2: DATA FORMATS PART 2: DATA FORMATS
Journal Journal
@ -2670,20 +2675,40 @@ Journal
Secondary dates Secondary dates
A secondary date is written after the primary date, following an equals 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. sign: DATE1=DATE2. If the year is omitted, the primary date's year is
When running reports, the primary (left) date is used by default, but assumed. When running reports, the primary (left side) date is used by
with the --date2 flag (or --aux-date or --effective), the secondary default, but with the --date2 flag (--aux-date or--effective also work,
(right) date will be used instead. 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 The meaning of secondary dates is up to you. Eg it could be "primary
consistent rule. Eg "primary = the bank's clearing date, secondary = is the bank's clearing date, secondary is the date the transaction was
date the transaction was initiated, if different". initiated, if different".
Downsides: makes your financial data more complicated, less portable, In practice, this feature usually adds confusion:
and less trustworthy in an audit. Keeping the meaning of the two dates
consistent requires discipline, and you have to remember which report- o You have to remember the primary and secondary dates' meaning, and
ing mode is appropriate for a given report. Posting dates are simpler follow that consistently.
and better.
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 Star comments
Lines beginning with * (star/asterisk) are also comment lines. This Lines beginning with * (star/asterisk) are also comment lines. This
@ -4899,37 +4924,47 @@ Pivoting
-2 EUR -2 EUR
Generating data 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- o Missing amounts or missing costs in transactions are inferred auto-
tions following a template. These are usually dated in the future, matically when possible.
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 The --infer-equity flag infers missing conversion equity postings o The --infer-equity flag infers missing conversion equity postings
from @/@@ costs. And the inverse --infer-costs flag infers missing from @/@@ costs.
@/@@ costs from conversion equity postings.
Generated data of this kind is temporary, existing only at report time. o The --infer-costs flag infers missing costs from conversion equity
But you can see it in the output of hledger print, and you can save postings.
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.
If you are wondering what data is being generated and why, add the o The --infer-market-prices flag infers P price directives from costs.
--verbose-tags flag. In hledger print output you will see extra tags
like generated-transaction, generated-posting, and modified on gener- o The --auto flag adds extra postings to transactions matched by auto
ated/modified data. Also, even without --verbose-tags, generated data posting rules.
always has equivalen hidden tags (with an underscore prefix), so eg you
could match generated transactions with tag:_generated-transaction. 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
Forecasting, or speculative future reporting, can be useful for esti- Forecasting, or speculative future reporting, can be useful for esti-
@ -9112,4 +9147,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.33.99 May 2024 HLEDGER(1) hledger-1.34.99 June 2024 HLEDGER(1)