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-09-09 14:07:29 -07:00
parent 91db5ef5d1
commit 30aeb662f2
13 changed files with 2281 additions and 2021 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

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

2
hledger-ui/.date.m4
View File

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

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34.99 " "hledger User Manuals"
.TH "HLEDGER\-UI" "1" "September 2024" "hledger-ui-1.40.99 " "hledger User Manuals"
@ -17,7 +17,7 @@ or
.PD
\f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.34.99.
This manual is for hledger\[aq]s terminal interface, version 1.40.99.
See also the hledger manual for common concepts and file formats.
.PP
hledger is a robust, user\-friendly, cross\-platform set of programs for
@ -178,31 +178,10 @@ Emacs\-style
(\f[CR]CTRL\-p\f[R]/\f[CR]CTRL\-n\f[R]/\f[CR]CTRL\-f\f[R]/\f[CR]CTRL\-b\f[R])
and VI\-style (\f[CR]k\f[R],\f[CR]j\f[R],\f[CR]l\f[R],\f[CR]h\f[R])
movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, to move
.PP
(Tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it.
(If you\[aq]re on a mac, the karabiner app is one way to do that.)
.PP
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
\f[CR]SHIFT\-DOWN/UP\f[R] steps downward and upward through these
standard report period durations: year, quarter, month, week, day.
Then, \f[CR]SHIFT\-LEFT/RIGHT\f[R] moves to the previous/next period.
\f[CR]T\f[R] sets the report period to today.
With the \f[CR]\-w/\-\-watch\f[R] option, when viewing a
\[dq]current\[dq] period (the current day, week, month, quarter, or
year), the period will move automatically to track the current date.
To set a non\-standard period, you can use \f[CR]/\f[R] and a
\f[CR]date:\f[R] query.
.PP
(Mac users: SHIFT\-DOWN/UP keys do not work by default in Terminal, as
of MacOS Monterey.
You can configure them as follows: open Terminal, press CMD\-comma to
open preferences, click Profiles, select your current terminal profile
on the left, click Keyboard on the right, click + and add this for
Shift\-Down: \f[CR]\[rs]033[1;2B\f[R], click + and add this for
Shift\-Up: \f[CR]\[rs]033[1;2A\f[R].
Press the Escape key to enter the \f[CR]\[rs]033\f[R] part, you
can\[aq]t type it directly.)
On a mac, the Karabiner app is one way to do that.)
.PP
\f[CR]/\f[R] lets you set a general filter query limiting the data
shown, using the same query terms as in hledger and hledger\-web.
@ -219,6 +198,31 @@ transactions generated by rule.
\f[CR]F\f[R] toggles forecast mode, in which future/forecasted
transactions are shown.
.PP
Pressing \f[CR]SHIFT\-DOWN\f[R] narrows the report period, and pressing
\f[CR]SHIFT\-UP\f[R] expands it again.
When narrowed, the current report period is displayed in the header
line, pressing \f[CR]SHIFT\-LEFT\f[R] or \f[CR]SHIFT\-RIGHT\f[R] moves
to the previous or next period, and pressing \f[CR]T\f[R] sets the
period to \[dq]today\[dq].
If you are using \f[CR]\-w/\-\-watch\f[R] and viewing a narrowed period
containing today, the view will follow any changes in system date
(moving to the period containing the new date).
.PP
You can also specify a non\-standard period with \f[CR]/\f[R] and a
\f[CR]date:\f[R] query; in this case, the period is not movable with the
arrow keys.
.PP
(Tip: arrow keys with Shift do not work out of the box in all terminal
software.
Eg in Apple\[aq]s Terminal, the SHIFT\-DOWN and SHIFT\-UP keys must be
configured as follows: in Terminal\[aq]s preferences, click Profiles,
select your current profile on the left, click Keyboard on the right,
click + and add this for SHIFT\-DOWN: \f[CR]\[rs]033[1;2B\f[R], click +
and add this for SHIFT\-UP: \f[CR]\[rs]033[1;2A\f[R].
\ In other terminals (Windows Terminal ?)
you might need to configure SHIFT\-RIGHT and SHIFT\-LEFT to emit
\f[CR]\[rs]033[1;2C\f[R] and \f[CR]\[rs]033[1;2D\f[R] respectively.)
.PP
\f[CR]ESCAPE\f[R] resets the UI state and jumps back to the top screen,
restoring the app\[aq]s initial state at startup.
Or, it cancels minibuffer data entry or the help dialog.

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

@ -18,7 +18,7 @@ plain text accounting app.
or
'hledger ui -- [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.34.99.
This manual is for hledger's terminal interface, version 1.40.99.
See also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs
@ -192,27 +192,11 @@ most screens:
returns to the previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END'
move up and down through lists. Emacs-style
('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') and VI-style ('k','j','l','h')
movement keys are also supported. A tip: movement speed is limited by
your keyboard repeat rate, to move faster you may want to adjust it.
(If you're on a mac, the karabiner app is one way to do that.)
movement keys are also supported.
With shift pressed, the cursor keys adjust the report period,
limiting the transactions to be shown (by default, all are shown).
'SHIFT-DOWN/UP' steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then,
'SHIFT-LEFT/RIGHT' moves to the previous/next period. 'T' sets the
report period to today. With the '-w/--watch' option, when viewing a
"current" period (the current day, week, month, quarter, or year), the
period will move automatically to track the current date. To set a
non-standard period, you can use '/' and a 'date:' query.
(Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as
of MacOS Monterey. You can configure them as follows: open Terminal,
press CMD-comma to open preferences, click Profiles, select your current
terminal profile on the left, click Keyboard on the right, click + and
add this for Shift-Down: '\033[1;2B', click + and add this for Shift-Up:
'\033[1;2A'. Press the Escape key to enter the '\033' part, you can't
type it directly.)
(Tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it. On a mac, the Karabiner app is one
way to do that.)
'/' lets you set a general filter query limiting the data shown,
using the same query terms as in hledger and hledger-web. While editing
@ -227,6 +211,26 @@ both ordinary transactions recorded in the journal, and periodic
transactions generated by rule. 'F' toggles forecast mode, in which
future/forecasted transactions are shown.
Pressing 'SHIFT-DOWN' narrows the report period, and pressing
'SHIFT-UP' expands it again. When narrowed, the current report period
is displayed in the header line, pressing 'SHIFT-LEFT' or 'SHIFT-RIGHT'
moves to the previous or next period, and pressing 'T' sets the period
to "today". If you are using '-w/--watch' and viewing a narrowed period
containing today, the view will follow any changes in system date
(moving to the period containing the new date).
You can also specify a non-standard period with '/' and a 'date:'
query; in this case, the period is not movable with the arrow keys.
(Tip: arrow keys with Shift do not work out of the box in all
terminal software. Eg in Apple's Terminal, the SHIFT-DOWN and SHIFT-UP
keys must be configured as follows: in Terminal's preferences, click
Profiles, select your current profile on the left, click Keyboard on the
right, click + and add this for SHIFT-DOWN: '\033[1;2B', click + and add
this for SHIFT-UP: '\033[1;2A'. In other terminals (Windows Terminal ?)
you might need to configure SHIFT-RIGHT and SHIFT-LEFT to emit
'\033[1;2C' and '\033[1;2D' respectively.)
'ESCAPE' resets the UI state and jumps back to the top screen,
restoring the app's initial state at startup. Or, it cancels minibuffer
data entry or the help dialog.
@ -537,30 +541,30 @@ Node: MOUSE8236
Ref: #mouse8331
Node: KEYS8568
Ref: #keys8661
Node: SCREENS13316
Ref: #screens13420
Node: Menu screen14056
Ref: #menu-screen14177
Node: Cash accounts screen14372
Ref: #cash-accounts-screen14549
Node: Balance sheet accounts screen14733
Ref: #balance-sheet-accounts-screen14949
Node: Income statement accounts screen15069
Ref: #income-statement-accounts-screen15290
Node: All accounts screen15454
Ref: #all-accounts-screen15635
Node: Register screen15817
Ref: #register-screen15976
Node: Transaction screen18260
Ref: #transaction-screen18418
Node: Error screen19835
Ref: #error-screen19957
Node: WATCH MODE20201
Ref: #watch-mode20318
Node: ENVIRONMENT21777
Ref: #environment21893
Node: BUGS22084
Ref: #bugs22167
Node: SCREENS13396
Ref: #screens13500
Node: Menu screen14136
Ref: #menu-screen14257
Node: Cash accounts screen14452
Ref: #cash-accounts-screen14629
Node: Balance sheet accounts screen14813
Ref: #balance-sheet-accounts-screen15029
Node: Income statement accounts screen15149
Ref: #income-statement-accounts-screen15370
Node: All accounts screen15534
Ref: #all-accounts-screen15715
Node: Register screen15897
Ref: #register-screen16056
Node: Transaction screen18340
Ref: #transaction-screen18498
Node: Error screen19915
Ref: #error-screen20037
Node: WATCH MODE20281
Ref: #watch-mode20398
Node: ENVIRONMENT21857
Ref: #environment21973
Node: BUGS22164
Ref: #bugs22247

End Tag Table

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

@ -11,7 +11,7 @@ SYNOPSIS
hledger ui -- [OPTS] [QUERYARGS]
DESCRIPTION
This manual is for hledger's terminal interface, version 1.34.99. See
This manual is for hledger's terminal interface, version 1.40.99. See
also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for
@ -161,28 +161,11 @@ KEYS
The cursor keys navigate: RIGHT or ENTER goes deeper, LEFT returns to
the previous screen, UP/DOWN/PGUP/PGDN/HOME/END move up and down
through lists. Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style
(k,j,l,h) movement keys are also supported. A tip: movement speed is
limited by your keyboard repeat rate, to move faster you may want to
adjust it. (If you're on a mac, the karabiner app is one way to do
that.)
(k,j,l,h) movement keys are also supported.
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
SHIFT-DOWN/UP steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then,
SHIFT-LEFT/RIGHT moves to the previous/next period. T sets the report
period to today. With the -w/--watch option, when viewing a "current"
period (the current day, week, month, quarter, or year), the period
will move automatically to track the current date. To set a non-stan-
dard period, you can use / and a date: query.
(Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as
of MacOS Monterey. You can configure them as follows: open Terminal,
press CMD-comma to open preferences, click Profiles, select your cur-
rent terminal profile on the left, click Keyboard on the right, click +
and add this for Shift-Down: \033[1;2B, click + and add this for
Shift-Up: \033[1;2A. Press the Escape key to enter the \033 part, you
can't type it directly.)
(Tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it. On a mac, the Karabiner app is one
way to do that.)
/ 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
@ -196,6 +179,26 @@ KEYS
actions generated by rule. F toggles forecast mode, in which fu-
ture/forecasted transactions are shown.
Pressing SHIFT-DOWN narrows the report period, and pressing SHIFT-UP
expands it again. When narrowed, the current report period is dis-
played in the header line, pressing SHIFT-LEFT or SHIFT-RIGHT moves to
the previous or next period, and pressing T sets the period to "today".
If you are using -w/--watch and viewing a narrowed period containing
today, the view will follow any changes in system date (moving to the
period containing the new date).
You can also specify a non-standard period with / and a date: query; in
this case, the period is not movable with the arrow keys.
(Tip: arrow keys with Shift do not work out of the box in all terminal
software. Eg in Apple's Terminal, the SHIFT-DOWN and SHIFT-UP keys
must be configured as follows: in Terminal's preferences, click Pro-
files, select your current profile on the left, click Keyboard on the
right, click + and add this for SHIFT-DOWN: \033[1;2B, click + and add
this for SHIFT-UP: \033[1;2A. In other terminals (Windows Terminal ?)
you might need to configure SHIFT-RIGHT and SHIFT-LEFT to emit
\033[1;2C and \033[1;2D respectively.)
ESCAPE resets the UI state and jumps back to the top screen, restoring
the app's initial state at startup. Or, it cancels minibuffer data en-
try or the help dialog.
@ -441,4 +444,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.34.99 June 2024 HLEDGER-UI(1)
hledger-ui-1.40.99 September 2024 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

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

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34.99 " "hledger User Manuals"
.TH "HLEDGER\-WEB" "1" "September 2024" "hledger-web-1.40.99 " "hledger User Manuals"
@ -17,7 +17,7 @@ or
.PD
\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.34.99.
This manual is for hledger\[aq]s web interface, version 1.40.99.
See also the hledger manual for common concepts and file formats.
.PP
hledger is a robust, user\-friendly, cross\-platform set of programs for

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

@ -18,7 +18,7 @@ plain text accounting app.
or
'hledger web -- [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.34.99. See
This manual is for hledger's web interface, version 1.40.99. See
also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs

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

@ -11,7 +11,7 @@ SYNOPSIS
hledger web -- [OPTS] [QUERY]
DESCRIPTION
This manual is for hledger's web interface, version 1.34.99. See also
This manual is for hledger's web interface, version 1.40.99. See also
the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for
@ -474,4 +474,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.34.99 June 2024 HLEDGER-WEB(1)
hledger-web-1.40.99 September 2024 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

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

215
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "HLEDGER" "1" "June 2024" "hledger-1.34.99 " "hledger User Manuals"
.TH "HLEDGER" "1" "September 2024" "hledger-1.40.99 " "hledger User Manuals"
@ -33,7 +33,7 @@ hledger is inspired by and largely compatible with ledger(1), and
largely interconvertible with beancount(1).
.PP
This manual is for hledger\[aq]s command line interface, version
1.34.99.
1.40.99.
It also describes the common options, file formats and concepts used by
all hledger programs.
It might accidentally teach you some bookkeeping/accounting as well!
@ -112,7 +112,7 @@ hledger reads one or more data files, each time you run it.
You can specify a file with \f[CR]\-f\f[R], like so
.IP
.EX
$ hledger \-f FILE print
$ hledger \-f FILE [\-f FILE2 ...] print
.EE
.PP
Files are most often in hledger\[aq]s journal format, with the
@ -731,32 +731,62 @@ quoting than you would at the command prompt.)
.PP
Argument files are now superseded by..
.SS Config files
hledger will read extra command line options from a
\f[CR]hledger.conf\f[R] config file.
These will be inserted early in the command line, so your later options
can override them if needed.
The config file can contain general options (which will be used with all
commands that support them), and command\-specific options (or
arguments).
hledger.conf.sample is an example, which you can install as
\f[CR]./hledger.conf\f[R] or \f[CR]$HOME/.hledger.conf\f[R].
As of hledger 1.40, you can optionally save command line options (or
arguments) to be used when running hledger commands, in a config file.
Here\[aq]s a small example:
.IP
.EX
\f[I]# General options are listed first, one or more per line.\f[R]
\f[I]# These will be used with all hledger commands that support them.\f[R]
\-\-pretty
\f[I]# Options following a \[ga][COMMANDNAME]\[ga] heading are used with that hledger command only.\f[R]
\f[B][print]\f[R]
\-\-explicit \-\-show\-costs
.EE
.PP
To be precise, hledger looks for \f[CR]hledger.conf\f[R] in the current
directory or above, or in your home directory (with a dotted name,
\f[CR]\[ti]/.hledger.conf\f[R]), or finally in your XDG config directory
(\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
Or you can select a particular config file by using the
\f[CR]\-\-conf\f[R] option, or by adding a \f[CR]hledger \-\-conf\f[R]
shebang line to a config file and executing it like a script (see the
example file).
You can inspect the finding and processing of config files with
\f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=8\f[R].
To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.
Its options will be inserted near the start of your command line (so you
can override them if needed).
Or, you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config
file and execute it like a script.
.PP
If you want to run hledger without a config file, to ensure standard
defaults and behaviour, use the \f[CR]\-n/\-\-no\-conf\f[R] flag.
This is useful when troubleshooting problems or sharing examples.
Or, you can set up an automatic config file that is used whenever you
run hledger.
This can be \f[CR]hledger.conf\f[R] in the current directory or above,
or \f[CR].hledger.conf\f[R] in your home directory
(\f[CR]\[ti]/.hledger.conf\f[R]), or \f[CR]hledger.conf\f[R] in your XDG
config directory (\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
.PP
\f[I](Added in 1.40; experimental)\f[R]
You can ignore config files by adding the \f[CR]\-n/\-\-no\-conf\f[R]
flag.
This is useful when using hledger in scripts, or when troubleshooting.
(When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are
used, the right\-most wins.)
To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or
\f[CR]\-\-debug=8\f[R].
.PP
Here is another example config file you could start with:
https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
.PP
Automatic config files are convenient, but have a cost: it\[aq]s easy to
change a report\[aq]s behaviour, or break scripts/applications which use
hledger, in unintended ways that will surprise you later.
They change the nature of hledger somewhat, making it less transparent
and predictable.
If you decide to use one, here are some tips:
.IP \[bu] 2
Be conservative about what you put in it.
Try to consider the effect on all your reports.
.IP \[bu] 2
Whenever a hledger command does not work as expected, try it again with
\f[CR]\-n\f[R].
.IP \[bu] 2
If that helps, you can run it with \f[CR]\-\-debug\f[R] to see how a
config file affected it.
.PP
This feature has been added in hledger 1.40 and is considered
\f[I]experimental\f[R].
.SH Output
.SS Output destination
hledger commands send their output to the terminal by default.
@ -783,7 +813,7 @@ Here are those commands and the formats currently supported:
.PP
.TS
tab(@);
lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).
lw(13.6n) lw(12.2n) lw(12.2n) lw(12.2n) lw(12.2n) lw(4.1n) lw(3.4n).
T{
\-
T}@T{
@ -793,6 +823,8 @@ csv/tsv
T}@T{
html
T}@T{
fods
T}@T{
json
T}@T{
sql
@ -807,6 +839,7 @@ Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
@ -817,7 +850,9 @@ Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1,2\f[R]
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
@ -831,6 +866,7 @@ Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
T}@T{
Y
T}@T{
T}
@ -843,6 +879,7 @@ Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
T}@T{
Y
T}@T{
T}
@ -855,6 +892,7 @@ Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
T}@T{
Y
T}@T{
T}
@ -867,6 +905,7 @@ Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
T}@T{
Y
T}@T{
T}
@ -878,6 +917,7 @@ T}@T{
Y
T}@T{
T}@T{
T}@T{
Y
T}@T{
Y
@ -890,6 +930,7 @@ T}@T{
Y
T}@T{
T}@T{
T}@T{
Y
T}@T{
T}
@ -897,9 +938,6 @@ T}
.IP \[bu] 2
\f[I]1 Also affected by the balance commands\[aq] \f[CI]\-\-layout\f[I]
option.\f[R]
.IP \[bu] 2
\f[I]2 \f[CI]balance\f[I] does not support html output without a report
interval or with \f[CI]\-\-budget\f[I].\f[R]
.PP
The output format is selected by the
\f[CR]\-O/\-\-output\-format=FMT\f[R] option:
@ -1104,7 +1142,7 @@ the add or web or import commands to create and update it.
.PP
Many users, though, edit the journal file with a text editor, and track
changes with a version control system such as git.
Editor addons such as ledger\-mode or hledger\-mode for Emacs,
Editor add\-ons such as ledger\-mode or hledger\-mode for Emacs,
vim\-ledger for Vim, and hledger\-vscode for Visual Studio Code, make
this easier, adding colour, formatting, tab completion, and useful
commands.
@ -5329,11 +5367,17 @@ $ hledger \-f sample.timeclock register \-p weekly \-\-depth 1 \-\-empty # time
.PP
To generate time logs, ie to clock in and clock out, you could:
.IP \[bu] 2
use emacs and the built\-in timeclock.el, or the extended
timeclock\-x.el and perhaps the extras in ledgerutils.el
use these shell aliases at the command line:
.RS 2
.IP
.EX
alias ti=\[aq]echo i \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] $* >>$TIMELOG\[aq]
alias to=\[aq]echo o \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] >>$TIMELOG\[aq]
.EE
.RE
.IP \[bu] 2
at the command line, use these bash aliases:
\f[CR]cli alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]
or Emacs\[aq]s built\-in timeclock.el, or the extended timeclock\-x.el,
and perhaps the extras in ledgerutils.el
.IP \[bu] 2
or use the old \f[CR]ti\f[R] and \f[CR]to\f[R] scripts in the ledger 2.x
repository.
@ -5687,26 +5731,62 @@ flags:
.PP
More complex intervals can be specified using \f[CR]\-p/\-\-period\f[R],
described below.
.SS Date adjustment
When there is a report interval (other than daily), report start/end
dates which have been inferred, eg from the journal, are automatically
adjusted to natural period boundaries.
This is convenient for producing simple periodic reports.
More precisely:
.IP \[bu] 2
an inferred start date will be adjusted earlier if needed to fall on a
natural period boundary
.IP \[bu] 2
an inferred end date will be adjusted later if needed to make the last
period the same length as the others.
.SS Date adjustments
.SS Start date adjustment
If you let hledger infer a report\[aq]s start date, it will adjust the
date to the previous natural boundary of the report interval, for
convenient periodic reports.
(If you don\[aq]t want that, specify a start date.)
.PP
By contrast, start/end dates which have been specified explicitly, with
\f[CR]\-b\f[R], \f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R], will
not be adjusted (since hledger 1.29).
This makes it possible to specify non\-standard report periods, but it
also means that if you are specifying a start date, you should pick one
that\[aq]s on a period boundary if you want to see simple report period
headings.
For example, if the journal\[aq]s first transaction is on january 10th,
.IP \[bu] 2
\f[CR]hledger register\f[R] (no report interval) will start the report
on january 10th.
.IP \[bu] 2
\f[CR]hledger register \-\-monthly\f[R] will start the report on the
previous month boundary, january 1st.
.IP \[bu] 2
\f[CR]hledger register \-\-monthly \-\-begin 1/5\f[R] will start the
report on january 5th [1].
.PP
Also if you are generating transactions or budget goals with periodic
transaction rules, their start date may be adjusted in a similar way (in
certain situations).
.SS End date adjustment
A report\[aq]s end date is always adjusted to include a whole number of
intervals, so that the last subperiod has the same length as the others.
.PP
For example, if the journal\[aq]s last transaction is on february 20th,
.IP \[bu] 2
\f[CR]hledger register\f[R] will end the report on february 20th.
.IP \[bu] 2
\f[CR]hledger register \-\-monthly\f[R] will end the report at the end
of february.
.IP \[bu] 2
\f[CR]hledger register \-\-monthly \-\-end 2/14\f[R] also will end the
report at the end of february.
.IP \[bu] 2
\f[CR]hledger register \-\-monthly \-\-begin 1/5 \-\-end 2/14\f[R] will
end the report on march 4th [1].
.PP
[1] Since hledger 1.29.
.SS Period headings
With non\-standard subperiods, hledger will show
\[dq]STARTDATE..ENDDATE\[dq] headings.
With standard subperiods (ie, starting on a natural interval boundary),
you\[aq]ll see more compact headings, which are usually preferable.
(Though month names will be in english, currently.)
.PP
So if you are specifying a start date and you want compact headings:
choose a start of year for yearly reports, a start of quarter for
quarterly reports, a start of month for monthly reports, etc.
(Remember, you can write eg \f[CR]\-b 2024\f[R] or \f[CR]1/1\f[R] as a
shortcut for a start of year, or \f[CR]2024\-04\f[R] or
\f[CR]202404\f[R] or \f[CR]Apr\f[R] for a start of month or quarter.)
.PP
For weekly reports, choose a date that\[aq]s a Monday.
(You can try different dates until you see the short headings, or write
eg \f[CR]\-b \[aq]3 weeks ago\[aq]\f[R].)
.SS Period expressions
The \f[CR]\-p/\-\-period\f[R] option specifies a period expression,
which is a compact way of expressing a start date, end date, and/or
@ -5873,7 +5953,7 @@ adjusted to each month\[aq]s last day)
.IP \[bu] 2
\f[CR]every Nth WEEKDAYNAME [of month]\f[R]
.PP
Yearly on a custom day:
Yearly on a custom month and day:
.IP \[bu] 2
\f[CR]every MM/DD [of year]\f[R] (month number and day of month number)
.IP \[bu] 2
@ -6519,7 +6599,7 @@ $ hledger print \-\-forecast \-\-today=2023/4/21
.EE
.PP
Here there are no ordinary transactions, so the forecasted transactions
begin on the first occurence after today\[aq]s date.
begin on the first occurrence after today\[aq]s date.
(You won\[aq]t normally use \f[CR]\-\-today\f[R]; it\[aq]s just to make
these examples reproducible.)
.SS Forecast reports
@ -7755,7 +7835,6 @@ T}
\f[CR]\-\-cumulative\f[R] is omitted to save space, it works like
\f[CR]\-H\f[R] but with a zero starting balance.
.SH PART 4: COMMANDS
\
.PP
Here are the standard commands, which you can list by running
\f[CR]hledger\f[R].
@ -7967,9 +8046,6 @@ payees/descriptions, dates (\f[CR]yesterday\f[R], \f[CR]today\f[R],
\f[CR]tomorrow\f[R]).
If the input area is empty, it will insert the default value.
.IP \[bu] 2
If the journal defines a default commodity, it will be added to any bare
numbers entered.
.IP \[bu] 2
A parenthesised transaction code may be entered following a date.
.IP \[bu] 2
Comments and tags may be entered following a description or amount.
@ -8827,6 +8903,9 @@ Flags:
description closest to DESC
\-r \-\-related show postings\[aq] siblings instead
\-\-invert display all amounts with reversed sign
\-\-sort=FIELDS sort by: date, desc, account, amount, absamount,
or a comma\-separated combination of these. For a
descending sort, prefix with \-. (Default: date)
\-w \-\-width=N set output width (default: terminal width or
$COLUMNS). \-wN,M sets description width as well.
\-\-align\-all guarantee alignment across all lines (slower)
@ -8894,6 +8973,16 @@ For example, it can be used on an income account where amounts are
normally displayed as negative numbers.
It\[aq]s also useful to show postings on the checking account together
with the related account:
.PP
The \f[CR]\-\-sort=FIELDS\f[R] flag sorts by the fields given, which can
be any of \f[CR]account\f[R], \f[CR]amount\f[R], \f[CR]absamount\f[R],
\f[CR]date\f[R], or \f[CR]desc\f[R]/\f[CR]description\f[R], optionally
separated by commas.
For example, \f[CR]\-\-sort account,amount\f[R] will group all
transactions in each account, sorted by transaction amount.
Each field can be negated by a preceding \f[CR]\-\f[R], so
\f[CR]\-\-sort \-amount\f[R] will show transactions ordered from
smallest amount to largest amount.
.IP
.EX
$ hledger register \-\-related \-\-invert assets:checking
@ -9450,7 +9539,7 @@ Flags:
\[aq]bare\[aq] : commodity symbols in one column
\[aq]tidy\[aq] : every attribute in its own column
\-O \-\-output\-format=FMT select the output format. Supported formats:
txt, html, csv, tsv, json.
txt, html, csv, tsv, json, fods.
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
one of the above formats selects that format.
.EE
@ -9543,7 +9632,7 @@ commodities displayed on the same line or multiple lines
This command supports the output destination and output format options,
with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R]
(\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports
only:) \f[CR]html\f[R].
only:) \f[CR]html\f[R], \f[CR]fods\f[R] (\f[I]Added in 1.40\f[R]).
In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
amounts are shown in red.
.SS Simple balance report

1571
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

187
hledger/hledger.txt
View File

@ -19,7 +19,7 @@ DESCRIPTION
and largely compatible with ledger(1), and largely interconvertible
with beancount(1).
This manual is for hledger's command line interface, version 1.34.99.
This manual is for hledger's command line interface, version 1.40.99.
It also describes the common options, file formats and concepts used by
all hledger programs. It might accidentally teach you some bookkeep-
ing/accounting as well! You don't need to know everything in here to
@ -83,7 +83,7 @@ Input
hledger reads one or more data files, each time you run it. You can
specify a file with -f, like so
$ hledger -f FILE print
$ hledger -f FILE [-f FILE2 ...] print
Files are most often in hledger's journal format, with the .journal
file extension (.hledger or .j also work); these files describe trans-
@ -568,28 +568,54 @@ Options
Argument files are now superseded by..
Config files
hledger will read extra command line options from a hledger.conf config
file. These will be inserted early in the command line, so your later
options can override them if needed. The config file can contain gen-
eral options (which will be used with all commands that support them),
and command-specific options (or arguments). hledger.conf.sample is an
example, which you can install as ./hledger.conf or
$HOME/.hledger.conf.
As of hledger 1.40, you can optionally save command line options (or
arguments) to be used when running hledger commands, in a config file.
Here's a small example:
To be precise, hledger looks for hledger.conf in the current directory
or above, or in your home directory (with a dotted name,
~/.hledger.conf), or finally in your XDG config directory (~/.con-
fig/hledger/hledger.conf). Or you can select a particular config file
by using the --conf option, or by adding a hledger --conf shebang line
to a config file and executing it like a script (see the example file).
You can inspect the finding and processing of config files with --debug
or --debug=8.
# General options are listed first, one or more per line.
# These will be used with all hledger commands that support them.
--pretty
If you want to run hledger without a config file, to ensure standard
defaults and behaviour, use the -n/--no-conf flag. This is useful when
troubleshooting problems or sharing examples.
# Options following a `[COMMANDNAME]` heading are used with that hledger command only.
[print]
--explicit --show-costs
(Added in 1.40; experimental)
To use a config file, specify it with the --conf option. Its options
will be inserted near the start of your command line (so you can over-
ride them if needed). Or, you can add a hledger --conf shebang line to
a config file and execute it like a script.
Or, you can set up an automatic config file that is used whenever you
run hledger. This can be hledger.conf in the current directory or
above, or .hledger.conf in your home directory (~/.hledger.conf), or
hledger.conf in your XDG config directory (~/.con-
fig/hledger/hledger.conf).
You can ignore config files by adding the -n/--no-conf flag. This is
useful when using hledger in scripts, or when troubleshooting. (When
both --conf and --no-conf options are used, the right-most wins.) To
inspect the processing of config files, use --debug or --debug=8.
Here is another example config file you could start with:
https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
Automatic config files are convenient, but have a cost: it's easy to
change a report's behaviour, or break scripts/applications which use
hledger, in unintended ways that will surprise you later. They change
the nature of hledger somewhat, making it less transparent and pre-
dictable. If you decide to use one, here are some tips:
o Be conservative about what you put in it. Try to consider the effect
on all your reports.
o Whenever a hledger command does not work as expected, try it again
with -n.
o If that helps, you can run it with --debug to see how a config file
affected it.
This feature has been added in hledger 1.40 and is considered experi-
mental.
Output
Output destination
@ -609,23 +635,21 @@ Output
Some commands offer other kinds of output, not just text on the termi-
nal. Here are those commands and the formats currently supported:
- txt csv/tsv html json sql
--------------------------------------------------------------------------------------
- txt csv/tsv html fods json sql
-----------------------------------------------------------------------------------------
aregister Y Y Y Y
balance Y 1 Y 1 Y 1,2 Y
balance Y 1 Y 1 Y 1 Y 1 Y
balancesheet Y 1 Y 1 Y 1 Y
balancesheete- Y 1 Y 1 Y 1 Y
quity
cashflow Y 1 Y 1 Y 1 Y
incomestatement Y 1 Y 1 Y 1 Y
incomestate- Y 1 Y 1 Y 1 Y
ment
print Y Y Y Y
register Y Y Y
o 1 Also affected by the balance commands' --layout option.
o 2 balance does not support html output without a report interval or
with --budget.
The output format is selected by the -O/--output-format=FMT option:
$ hledger print -O csv # print CSV on stdout
@ -797,7 +821,7 @@ Journal
the add or web or import commands to create and update it.
Many users, though, edit the journal file with a text editor, and track
changes with a version control system such as git. Editor addons such
changes with a version control system such as git. Editor add-ons such
as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
hledger-vscode for Visual Studio Code, make this easier, adding colour,
formatting, tab completion, and useful commands. See Editor configura-
@ -4221,12 +4245,13 @@ Timeclock
To generate time logs, ie to clock in and clock out, you could:
o use emacs and the built-in timeclock.el, or the extended time-
clock-x.el and perhaps the extras in ledgerutils.el
o use these shell aliases at the command line:
o at the command line, use these bash aliases: cli alias ti="echo i
`date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
`date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG'
alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG'
o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and
perhaps the extras in ledgerutils.el
o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2
@ -4531,24 +4556,61 @@ Time periods
More complex intervals can be specified using -p/--period, described
below.
Date adjustment
When there is a report interval (other than daily), report start/end
dates which have been inferred, eg from the journal, are automatically
adjusted to natural period boundaries. This is convenient for produc-
ing simple periodic reports. More precisely:
Date adjustments
Start date adjustment
If you let hledger infer a report's start date, it will adjust the date
to the previous natural boundary of the report interval, for convenient
periodic reports. (If you don't want that, specify a start date.)
o an inferred start date will be adjusted earlier if needed to fall on
a natural period boundary
For example, if the journal's first transaction is on january 10th,
o an inferred end date will be adjusted later if needed to make the
last period the same length as the others.
o hledger register (no report interval) will start the report on janu-
ary 10th.
By contrast, start/end dates which have been specified explicitly, with
-b, -e, -p or date:, will not be adjusted (since hledger 1.29). This
makes it possible to specify non-standard report periods, but it also
means that if you are specifying a start date, you should pick one
that's on a period boundary if you want to see simple report period
headings.
o hledger register --monthly will start the report on the previous
month boundary, january 1st.
o hledger register --monthly --begin 1/5 will start the report on janu-
ary 5th [1].
Also if you are generating transactions or budget goals with periodic
transaction rules, their start date may be adjusted in a similar way
(in certain situations).
End date adjustment
A report's end date is always adjusted to include a whole number of in-
tervals, so that the last subperiod has the same length as the others.
For example, if the journal's last transaction is on february 20th,
o hledger register will end the report on february 20th.
o hledger register --monthly will end the report at the end of febru-
ary.
o hledger register --monthly --end 2/14 also will end the report at the
end of february.
o hledger register --monthly --begin 1/5 --end 2/14 will end the report
on march 4th [1].
[1] Since hledger 1.29.
Period headings
With non-standard subperiods, hledger will show "STARTDATE..ENDDATE"
headings. With standard subperiods (ie, starting on a natural interval
boundary), you'll see more compact headings, which are usually prefer-
able. (Though month names will be in english, currently.)
So if you are specifying a start date and you want compact headings:
choose a start of year for yearly reports, a start of quarter for quar-
terly reports, a start of month for monthly reports, etc. (Remember,
you can write eg -b 2024 or 1/1 as a shortcut for a start of year, or
2024-04 or 202404 or Apr for a start of month or quarter.)
For weekly reports, choose a date that's a Monday. (You can try dif-
ferent dates until you see the short headings, or write eg -b '3 weeks
ago'.)
Period expressions
The -p/--period option specifies a period expression, which is a com-
@ -4637,7 +4699,7 @@ Time periods
o every Nth WEEKDAYNAME [of month]
Yearly on a custom day:
Yearly on a custom month and day:
o every MM/DD [of year] (month number and day of month number)
@ -5065,7 +5127,7 @@ Forecasting
expenses:rent $1000
Here there are no ordinary transactions, so the forecasted transactions
begin on the first occurence after today's date. (You won't normally
begin on the first occurrence after today's date. (You won't normally
use --today; it's just to make these examples reproducible.)
Forecast reports
@ -5981,8 +6043,6 @@ Value reporting
starting balance.
PART 4: COMMANDS
Here are the standard commands, which you can list by running hledger.
If you have installed more add-on commands, they also will be listed.
@ -6174,9 +6234,6 @@ Data entry commands
ees/descriptions, dates (yesterday, today, tomorrow). If the input
area is empty, it will insert the default value.
o If the journal defines a default commodity, it will be added to any
bare numbers entered.
o A parenthesised transaction code may be entered following a date.
o Comments and tags may be entered following a description or amount.
@ -6935,6 +6992,9 @@ Standard report commands
description closest to DESC
-r --related show postings' siblings instead
--invert display all amounts with reversed sign
--sort=FIELDS sort by: date, desc, account, amount, absamount,
or a comma-separated combination of these. For a
descending sort, prefix with -. (Default: date)
-w --width=N set output width (default: terminal width or
$COLUMNS). -wN,M sets description width as well.
--align-all guarantee alignment across all lines (slower)
@ -6993,6 +7053,13 @@ Standard report commands
bers. It's also useful to show postings on the checking account to-
gether with the related account:
The --sort=FIELDS flag sorts by the fields given, which can be any of
account, amount, absamount, date, or desc/description, optionally sepa-
rated by commas. For example, --sort account,amount will group all
transactions in each account, sorted by transaction amount. Each field
can be negated by a preceding -, so --sort -amount will show transac-
tions ordered from smallest amount to largest amount.
$ hledger register --related --invert assets:checking
With a reporting interval, register shows summary postings, one per in-
@ -7498,7 +7565,7 @@ Advanced report commands
'bare' : commodity symbols in one column
'tidy' : every attribute in its own column
-O --output-format=FMT select the output format. Supported formats:
txt, html, csv, tsv, json.
txt, html, csv, tsv, json, fods.
-o --output-file=FILE write output to FILE. A file extension matching
one of the above formats selects that format.
@ -7582,8 +7649,8 @@ Advanced report commands
This command supports the output destination and output format options,
with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe-
riod reports only:) html. In txt output in a colour-supporting termi-
nal, negative amounts are shown in red.
riod reports only:) html, fods (Added in 1.40). In txt output in a
colour-supporting terminal, negative amounts are shown in red.
Simple balance report
With no arguments, balance shows a list of all accounts and their
@ -9598,4 +9665,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.34.99 June 2024 HLEDGER(1)
hledger-1.40.99 September 2024 HLEDGER(1)