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

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-03-06 16:14:31 -10:00
parent 3d1994ea76
commit d65cdbef27
3 changed files with 770 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
hledger/hledger.1
View File

@ -8349,6 +8349,49 @@ test \- run self tests
.PP
Next, these commands are described in detail.
.SH Help commands
.SS commands
Show the hledger commands list.
.IP
.EX
Flags:
\-\-builtin show only builtin commands, not addons
.EE
.SS demo
Play demos of hledger usage in the terminal, if asciinema is installed.
.IP
.EX
Flags:
\-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2
is double, etc (default: 2))
.EE
.PP
Run this command with no argument to list the demos.
To play a demo, write its number or a prefix or substring of its title.
Tips:
.PP
Make your terminal window large enough to see the demo clearly.
.PP
Use the \-s/\-\-speed SPEED option to set your preferred playback speed,
eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to
play at half speed.
The default speed is 2x.
.PP
Other asciinema options can be added following a double dash, eg
\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list
asciinema\[aq]s other options.
.PP
During playback, several keys are available: SPACE to pause/unpause, .
to step forward (while paused), CTRL\-c quit.
.PP
Examples:
.IP
.EX
$ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed
.EE
.PP
This command is experimental: there aren\[aq]t many useful demos yet.
.SS help
Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a
pager.
@ -8396,43 +8439,190 @@ $ hledger help # show the manual with info, man or $PAGER
$ hledger help \[aq]time periods\[aq] # show the manual\[aq]s \[dq]Time periods\[dq] topic
$ hledger help \[aq]time periods\[aq] \-m # use man, even if info is installed
.EE
.SS demo
Play demos of hledger usage in the terminal, if asciinema is installed.
.SH User interface commands
.SS repl
Start an interactive prompt, where you can run any of hledger\[aq]s
commands.
Data files are parsed just once, so the commands run faster.
.IP
.EX
Flags:
\-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2
is double, etc (default: 2))
no command\-specific flags
.EE
.PP
Run this command with no argument to list the demos.
To play a demo, write its number or a prefix or substring of its title.
Tips:
This command is experimental and could change in the future.
.PP
Make your terminal window large enough to see the demo clearly.
\f[CR]hledger repl\f[R] starts a read\-eval\-print loop (REPL) where you
can enter commands interactively.
As with the \f[CR]run\f[R] command, each input file (or each input
file/input options combination) is parsed just once, so commands will
run more quickly than if you ran them individually at the command line.
.PP
Use the \-s/\-\-speed SPEED option to set your preferred playback speed,
eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to
play at half speed.
The default speed is 2x.
Also like \f[CR]run\f[R], the input file(s) specified for the
\f[CR]repl\f[R] command will be the default input for all interactive
commands, you can override this temporarily by specifying an
\f[CR]\-f\f[R] option in particular commands, and commands will not see
any changes made to input files (eg by \f[CR]add\f[R]) until you exit
and restart the REPL.
.PP
Other asciinema options can be added following a double dash, eg
\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list
asciinema\[aq]s other options.
The command syntax is the same as with \f[CR]run\f[R]:
.IP \[bu] 2
enter one hledger command at a time, without the usual
\f[CR]hledger\f[R] first word
.IP \[bu] 2
empty lines and comment text from \f[CR]#\f[R] to end of line are
ignored
.IP \[bu] 2
use single or double quotes to quote arguments when needed
.IP \[bu] 2
type \f[CR]exit\f[R] or \f[CR]quit\f[R] or control\-D to exit the REPL.
.PP
During playback, several keys are available: SPACE to pause/unpause, .
to step forward (while paused), CTRL\-c quit.
While it is running, the REPL remembers your command history, and you
can navigate in the usual ways: \- Keypad or Emacs navigation keys to
edit the current command line \- UP/DOWN or control\-P/control\-N to
step back/forward through history \- control\-R to search for a past
command, etc.
.PP
Examples:
The \f[CR]commands\f[R] and \f[CR]help\f[R]\ commands, and the command
help flags (\f[CR]CMD \-\-tldr\f[R], \f[CR]CMD \-h/\-\-help\f[R],
\f[CR]CMD \-\-info\f[R], \f[CR]CMD \-\-man\f[R]), work in the usual way,
and can be useful.
.PP
You can type control\-C to cancel a long\-running command (but only
once; typing it a second time will exit the REPL).
.PP
And in most shells you can type control\-Z to exit temporarily to the
shell (and \f[CR]fg\f[R] to return to the REPL).
.SS Caveats
You may find some differences in behaviour between \f[CR]run\f[R]
command lines and normal hledger command lines.
For example, in the REPL,
.IP \[bu] 2
the command name must be written first, options afterward
.IP \[bu] 2
full command names or official abbreviations (as in the command list)
must be used
.IP \[bu] 2
options parsing with addon commands might be less flexible than the CLI
.IP \[bu] 2
the \f[CR]stats\f[R] command gives false timings, currently
.SS Examples
Start the REPL:
.IP
.EX
$ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed
hledger repl
.EE
.PP
This command is experimental: there aren\[aq]t many useful demos yet.
.SH User interface commands
or
.IP
.EX
hledger repl \-f some.journal
.EE
.SS run
Run a sequence of hledger commands, provided as files or command line
arguments.
Data files are parsed just once, so the commands run faster.
.IP
.EX
Flags:
no command\-specific flags
.EE
.PP
This command is experimental and could change in the future.
.PP
You can use \f[CR]run\f[R] in three ways:
.IP \[bu] 2
\f[CR]hledger run \-\- CMD1 \-\- CMD2 \-\- CMD3\f[R] \- read commands
from the command line, separated by \f[CR]\-\-\f[R]
.IP \[bu] 2
\f[CR]hledger run SCRIPTFILE1 SCRIPTFILE2\f[R] \- read commands from one
or more files
.IP \[bu] 2
\f[CR]cat SCRIPTFILE1 | hledger run\f[R] \- read commands from standard
input.
.PP
\f[CR]run\f[R] first loads the input file(s) specified by
\f[CR]LEDGER_FILE\f[R] or by \f[CR]\-f\f[R] options, in the usual way.
Then it runs each command in turn, each using the same input data.
But if you want a particular command to use different input, you can
specify an \f[CR]\-f\f[R] option within that command.
This will override (not add to) the default input, just for that
command.
.PP
Each input file (more precisely, each combination of input file and
input options) is parsed only once.
This means that commands will not see any changes made to these files,
until the next run.
But the commands will run more quickly than if run individually
(typically about twice as fast).
.PP
Command scripts, whether in a file or written on the command line, have
a simple syntax:
.IP \[bu] 2
each line may contain a single hledger command and its arguments,
without the usual \f[CR]hledger\f[R] first word
.IP \[bu] 2
empty lines are ignored
.IP \[bu] 2
text from \f[CR]#\f[R] to end of line is a comment, and ignored
.IP \[bu] 2
you can use single or double quotes to quote arguments when needed, as
on the command line
.IP \[bu] 2
these extra commands are available: \f[CR]echo TEXT\f[R] prints some
text, and \f[CR]exit\f[R] or \f[CR]quit\f[R] ends the run.
.PP
On unix systems you can use \f[CR]#!/usr/bin/env hledger run\f[R] in the
first line of a command file to make it a runnable script.
If that gives an error, use \f[CR]#!/usr/bin/env \-S hledger run\f[R].
.PP
It\[aq]s ok to use the \f[CR]run\f[R] command recursively within a
command script.
.SS Caveats
You may find some differences in behaviour between \f[CR]run\f[R]
command lines and normal hledger command lines.
For example, with \f[CR]run\f[R],
.IP \[bu] 2
the command name must be written first, options afterward
.IP \[bu] 2
full command names or official abbreviations (as in the command list)
must be used
.SS Examples
Run commands specified on the command line:
.IP
.EX
hledger \-f some.journal run \-\- balance assets \-\-depth 2 \-\- balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose \-\- stats
.EE
.PP
This would load \f[CR]some.journal\f[R], run
\f[CR]balance assets \-\-depth 2\f[R] on it, then run
\f[CR]balance liabilities \-\-depth 3 \-\-transpose\f[R] on
\f[CR]/some/other.journal\f[R], and finally run \f[CR]stats\f[R] on
\f[CR]some.journal\f[R]
.PP
Run commands from standard input:
.IP
.EX
(echo \[dq]files\[dq]; echo \[dq]stats\[dq]) | hledger \-f some.journal run
.EE
.PP
Provide commands as a runnable script:
.IP
.EX
#!/usr/bin/env \-S hledger run \-f some.journal
echo \[dq]List of accounts in some.journal\[dq]
accounts
echo \[dq]Assets of some.journal\[dq]
balance assets \-\-depth 2
echo \[dq]Liabilities from /some/other.journal\[dq]
balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose
echo \[dq]Commands from another.script, applied to another.journal\[dq]
run \-f another.journal another.script
.EE
.SS ui
Runs hledger\-ui (if installed).
.SS web

524
hledger/hledger.info
View File

@ -8064,13 +8064,60 @@ File: hledger.info, Node: Help commands, Next: User interface commands, Prev:
* Menu:
* help::
* commands::
* demo::
* help::

File: hledger.info, Node: help, Next: demo, Up: Help commands
File: hledger.info, Node: commands, Next: demo, Up: Help commands
24.1 help
24.1 commands
=============
Show the hledger commands list.
Flags:
--builtin show only builtin commands, not addons

File: hledger.info, Node: demo, Next: help, Prev: commands, Up: Help commands
24.2 demo
=========
Play demos of hledger usage in the terminal, if asciinema is installed.
Flags:
-s --speed=SPEED playback speed (1 is original speed, .5 is half, 2
is double, etc (default: 2))
Run this command with no argument to list the demos. To play a demo,
write its number or a prefix or substring of its title. Tips:
Make your terminal window large enough to see the demo clearly.
Use the -s/-speed SPEED option to set your preferred playback speed,
eg '-s4' to play at 4x original speed or '-s.5' to play at half speed.
The default speed is 2x.
Other asciinema options can be added following a double dash, eg '--
-i.1' to limit pauses or '-- -h' to list asciinema's other options.
During playback, several keys are available: SPACE to pause/unpause,
. to step forward (while paused), CTRL-c quit.
Examples:
$ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install -s4 # play the "install" demo at 4x speed
This command is experimental: there aren't many useful demos yet.

File: hledger.info, Node: help, Prev: demo, Up: Help commands
24.3 help
=========
Show the hledger user manual with 'info', 'man', or a pager. With a
@ -8109,41 +8156,6 @@ $ hledger help # show the manual with info, man or $PAGER
$ hledger help 'time periods' # show the manual's "Time periods" topic
$ hledger help 'time periods' -m # use man, even if info is installed

File: hledger.info, Node: demo, Prev: help, Up: Help commands
24.2 demo
=========
Play demos of hledger usage in the terminal, if asciinema is installed.
Flags:
-s --speed=SPEED playback speed (1 is original speed, .5 is half, 2
is double, etc (default: 2))
Run this command with no argument to list the demos. To play a demo,
write its number or a prefix or substring of its title. Tips:
Make your terminal window large enough to see the demo clearly.
Use the -s/-speed SPEED option to set your preferred playback speed,
eg '-s4' to play at 4x original speed or '-s.5' to play at half speed.
The default speed is 2x.
Other asciinema options can be added following a double dash, eg '--
-i.1' to limit pauses or '-- -h' to list asciinema's other options.
During playback, several keys are available: SPACE to pause/unpause,
. to step forward (while paused), CTRL-c quit.
Examples:
$ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install -s4 # play the "install" demo at 4x speed
This command is experimental: there aren't many useful demos yet.

File: hledger.info, Node: User interface commands, Next: Data entry commands, Prev: Help commands, Up: Top
@ -8152,13 +8164,206 @@ File: hledger.info, Node: User interface commands, Next: Data entry commands,
* Menu:
* repl::
* run::
* ui::
* web::

File: hledger.info, Node: ui, Next: web, Up: User interface commands
File: hledger.info, Node: repl, Next: run, Up: User interface commands
25.1 ui
25.1 repl
=========
Start an interactive prompt, where you can run any of hledger's
commands. Data files are parsed just once, so the commands run faster.
Flags:
no command-specific flags
This command is experimental and could change in the future.
'hledger repl' starts a read-eval-print loop (REPL) where you can
enter commands interactively. As with the 'run' command, each input
file (or each input file/input options combination) is parsed just once,
so commands will run more quickly than if you ran them individually at
the command line.
Also like 'run', the input file(s) specified for the 'repl' command
will be the default input for all interactive commands, you can override
this temporarily by specifying an '-f' option in particular commands,
and commands will not see any changes made to input files (eg by 'add')
until you exit and restart the REPL.
The command syntax is the same as with 'run':
* enter one hledger command at a time, without the usual 'hledger'
first word
* empty lines and comment text from '#' to end of line are ignored
* use single or double quotes to quote arguments when needed
* type 'exit' or 'quit' or control-D to exit the REPL.
While it is running, the REPL remembers your command history, and you
can navigate in the usual ways: - Keypad or Emacs navigation keys to
edit the current command line - UP/DOWN or control-P/control-N to step
back/forward through history - control-R to search for a past command,
etc.
The 'commands' and 'help' commands, and the command help flags ('CMD
--tldr', 'CMD -h/--help', 'CMD --info', 'CMD --man'), work in the usual
way, and can be useful.
You can type control-C to cancel a long-running command (but only
once; typing it a second time will exit the REPL).
And in most shells you can type control-Z to exit temporarily to the
shell (and 'fg' to return to the REPL).
* Menu:
* Caveats::
* Examples::

File: hledger.info, Node: Caveats, Next: Examples, Up: repl
25.1.1 Caveats
--------------
You may find some differences in behaviour between 'run' command lines
and normal hledger command lines. For example, in the REPL,
* the command name must be written first, options afterward
* full command names or official abbreviations (as in the command
list) must be used
* options parsing with addon commands might be less flexible than the
CLI
* the 'stats' command gives false timings, currently

File: hledger.info, Node: Examples, Prev: Caveats, Up: repl
25.1.2 Examples
---------------
Start the REPL:
hledger repl
or
hledger repl -f some.journal

File: hledger.info, Node: run, Next: ui, Prev: repl, Up: User interface commands
25.2 run
========
Run a sequence of hledger commands, provided as files or command line
arguments. Data files are parsed just once, so the commands run faster.
Flags:
no command-specific flags
This command is experimental and could change in the future.
You can use 'run' in three ways:
* 'hledger run -- CMD1 -- CMD2 -- CMD3' - read commands from the
command line, separated by '--'
* 'hledger run SCRIPTFILE1 SCRIPTFILE2' - read commands from one or
more files
* 'cat SCRIPTFILE1 | hledger run' - read commands from standard
input.
'run' first loads the input file(s) specified by 'LEDGER_FILE' or by
'-f' options, in the usual way. Then it runs each command in turn, each
using the same input data. But if you want a particular command to use
different input, you can specify an '-f' option within that command.
This will override (not add to) the default input, just for that
command.
Each input file (more precisely, each combination of input file and
input options) is parsed only once. This means that commands will not
see any changes made to these files, until the next run. But the
commands will run more quickly than if run individually (typically about
twice as fast).
Command scripts, whether in a file or written on the command line,
have a simple syntax:
* each line may contain a single hledger command and its arguments,
without the usual 'hledger' first word
* empty lines are ignored
* text from '#' to end of line is a comment, and ignored
* you can use single or double quotes to quote arguments when needed,
as on the command line
* these extra commands are available: 'echo TEXT' prints some text,
and 'exit' or 'quit' ends the run.
On unix systems you can use '#!/usr/bin/env hledger run' in the first
line of a command file to make it a runnable script. If that gives an
error, use '#!/usr/bin/env -S hledger run'.
It's ok to use the 'run' command recursively within a command script.
* Menu:
* Caveats: Caveats 2.
* Examples: Examples 2.

File: hledger.info, Node: Caveats 2, Next: Examples 2, Up: run
25.2.1 Caveats
--------------
You may find some differences in behaviour between 'run' command lines
and normal hledger command lines. For example, with 'run',
* the command name must be written first, options afterward
* full command names or official abbreviations (as in the command
list) must be used

File: hledger.info, Node: Examples 2, Prev: Caveats 2, Up: run
25.2.2 Examples
---------------
Run commands specified on the command line:
hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
This would load 'some.journal', run 'balance assets --depth 2' on it,
then run 'balance liabilities --depth 3 --transpose' on
'/some/other.journal', and finally run 'stats' on 'some.journal'
Run commands from standard input:
(echo "files"; echo "stats") | hledger -f some.journal run
Provide commands as a runnable script:
#!/usr/bin/env -S hledger run -f some.journal
echo "List of accounts in some.journal"
accounts
echo "Assets of some.journal"
balance assets --depth 2
echo "Liabilities from /some/other.journal"
balance liabilities -f /some/other.journal --depth 3 --transpose
echo "Commands from another.script, applied to another.journal"
run -f another.journal another.script

File: hledger.info, Node: ui, Next: web, Prev: run, Up: User interface commands
25.3 ui
=======
Runs hledger-ui (if installed).
@ -8166,7 +8371,7 @@ Runs hledger-ui (if installed).

File: hledger.info, Node: web, Prev: ui, Up: User interface commands
25.2 web
25.4 web
========
Runs hledger-web (if installed).
@ -12642,121 +12847,128 @@ Node: Interaction of valuation and queries283814
Node: Effect of valuation on reports284531
Node: PART 4 COMMANDS292429
Node: Help commands294645
Node: help294818
Node: demo296523
Node: User interface commands297740
Node: ui297934
Node: web298059
Node: Data entry commands298187
Node: add298385
Node: import300840
Node: Import preview301874
Node: Overlap detection302822
Node: First import305708
Node: Importing balance assignments306903
Node: Import and commodity styles307958
Node: Import special cases308396
Node: Basic report commands309731
Node: accounts310032
Node: codes312905
Node: commodities313927
Node: descriptions314171
Node: files314638
Node: notes314935
Node: payees315447
Node: prices316231
Node: stats317123
Node: tags318864
Node: Standard report commands320171
Node: print320476
Node: print explicitness323217
Node: print amount style324137
Node: print parseability325375
Node: print other features326294
Node: print output format327157
Node: aregister330442
Node: aregister and posting dates334901
Node: register335802
Node: Custom register output342977
Node: balancesheet344162
Node: balancesheetequity348932
Node: cashflow354072
Node: incomestatement358634
Node: Advanced report commands363232
Node: balance363440
Node: balance features368616
Node: Simple balance report370692
Node: Balance report line format372502
Node: Filtered balance report374862
Node: List or tree mode375381
Node: Depth limiting376894
Node: Dropping top-level accounts377661
Node: Showing declared accounts378171
Node: Sorting by amount378901
Node: Percentages379738
Node: Multi-period balance report380445
Node: Balance change end balance383197
Node: Balance report types384834
Node: Calculation type385513
Node: Accumulation type386217
Node: Valuation type387318
Node: Combining balance report types388507
Node: Budget report390539
Node: Using the budget report392844
Node: Budget date surprises395120
Node: Selecting budget goals396484
Node: Budgeting vs forecasting397432
Node: Balance report layout399109
Node: Wide layout400314
Node: Tall layout402719
Node: Bare layout404025
Node: Tidy layout406089
Node: Balance report output407633
Node: Some useful balance reports408448
Node: roi409708
Node: Spaces and special characters in --inv and --pnl411955
Node: Semantics of --inv and --pnl412681
Node: IRR and TWR explained414768
Node: Chart commands418179
Node: activity418360
Node: Data generation commands418857
Node: close419063
Node: close --clopen421626
Node: close --close423800
Node: close --open424324
Node: close --assert424574
Node: close --assign424901
Node: close --retain425580
Node: close customisation426437
Node: close and balance assertions428081
Node: close examples429603
Node: Retain earnings429840
Node: Migrate balances to a new file430343
Node: More detailed close examples431705
Node: rewrite431927
Node: Re-write rules in a file434499
Node: Diff output format435809
Node: rewrite vs print --auto437082
Node: Maintenance commands437796
Node: check438005
Node: Basic checks439087
Node: Strict checks440040
Node: Other checks440915
Node: Custom checks442770
Node: diff443225
Node: test444432
Node: PART 5 COMMON TASKS445304
Node: Getting help445537
Node: Constructing command lines446446
Node: Starting a journal file447284
Node: Setting LEDGER_FILE448668
Node: Setting opening balances449926
Node: Recording transactions453248
Node: Reconciling453973
Node: Reporting456362
Node: Migrating to a new file460476
Node: BUGS460925
Node: Troubleshooting461890
Node: commands294831
Node: demo295039
Node: help296273
Node: User interface commands297978
Node: repl298189
Node: Caveats300205
Node: Examples300730
Node: run300897
Node: Caveats 2303044
Node: Examples 2303433
Node: ui304416
Node: web304553
Node: Data entry commands304681
Node: add304879
Node: import307334
Node: Import preview308368
Node: Overlap detection309316
Node: First import312202
Node: Importing balance assignments313397
Node: Import and commodity styles314452
Node: Import special cases314890
Node: Basic report commands316225
Node: accounts316526
Node: codes319399
Node: commodities320421
Node: descriptions320665
Node: files321132
Node: notes321429
Node: payees321941
Node: prices322725
Node: stats323617
Node: tags325358
Node: Standard report commands326665
Node: print326970
Node: print explicitness329711
Node: print amount style330631
Node: print parseability331869
Node: print other features332788
Node: print output format333651
Node: aregister336936
Node: aregister and posting dates341395
Node: register342296
Node: Custom register output349471
Node: balancesheet350656
Node: balancesheetequity355426
Node: cashflow360566
Node: incomestatement365128
Node: Advanced report commands369726
Node: balance369934
Node: balance features375110
Node: Simple balance report377186
Node: Balance report line format378996
Node: Filtered balance report381356
Node: List or tree mode381875
Node: Depth limiting383388
Node: Dropping top-level accounts384155
Node: Showing declared accounts384665
Node: Sorting by amount385395
Node: Percentages386232
Node: Multi-period balance report386939
Node: Balance change end balance389691
Node: Balance report types391328
Node: Calculation type392007
Node: Accumulation type392711
Node: Valuation type393812
Node: Combining balance report types395001
Node: Budget report397033
Node: Using the budget report399338
Node: Budget date surprises401614
Node: Selecting budget goals402978
Node: Budgeting vs forecasting403926
Node: Balance report layout405603
Node: Wide layout406808
Node: Tall layout409213
Node: Bare layout410519
Node: Tidy layout412583
Node: Balance report output414127
Node: Some useful balance reports414942
Node: roi416202
Node: Spaces and special characters in --inv and --pnl418449
Node: Semantics of --inv and --pnl419175
Node: IRR and TWR explained421262
Node: Chart commands424673
Node: activity424854
Node: Data generation commands425351
Node: close425557
Node: close --clopen428120
Node: close --close430294
Node: close --open430818
Node: close --assert431068
Node: close --assign431395
Node: close --retain432074
Node: close customisation432931
Node: close and balance assertions434575
Node: close examples436097
Node: Retain earnings436334
Node: Migrate balances to a new file436837
Node: More detailed close examples438199
Node: rewrite438421
Node: Re-write rules in a file440993
Node: Diff output format442303
Node: rewrite vs print --auto443576
Node: Maintenance commands444290
Node: check444499
Node: Basic checks445581
Node: Strict checks446534
Node: Other checks447409
Node: Custom checks449264
Node: diff449719
Node: test450926
Node: PART 5 COMMON TASKS451798
Node: Getting help452031
Node: Constructing command lines452940
Node: Starting a journal file453778
Node: Setting LEDGER_FILE455162
Node: Setting opening balances456420
Node: Recording transactions459742
Node: Reconciling460467
Node: Reporting462856
Node: Migrating to a new file466970
Node: BUGS467419
Node: Troubleshooting468384

End Tag Table

209
hledger/hledger.txt
View File

@ -6487,6 +6487,42 @@ PART 4: COMMANDS
Next, these commands are described in detail.
Help commands
commands
Show the hledger commands list.
Flags:
--builtin show only builtin commands, not addons
demo
Play demos of hledger usage in the terminal, if asciinema is installed.
Flags:
-s --speed=SPEED playback speed (1 is original speed, .5 is half, 2
is double, etc (default: 2))
Run this command with no argument to list the demos. To play a demo,
write its number or a prefix or substring of its title. Tips:
Make your terminal window large enough to see the demo clearly.
Use the -s/--speed SPEED option to set your preferred playback speed,
eg -s4 to play at 4x original speed or -s.5 to play at half speed. The
default speed is 2x.
Other asciinema options can be added following a double dash, eg --
-i.1 to limit pauses or -- -h to list asciinema's other options.
During playback, several keys are available: SPACE to pause/unpause, .
to step forward (while paused), CTRL-c quit.
Examples:
$ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install -s4 # play the "install" demo at 4x speed
This command is experimental: there aren't many useful demos yet.
help
Show the hledger user manual with info, man, or a pager. With a (case
insensitive) TOPIC argument, try to open it at that section heading.
@ -6523,37 +6559,170 @@ Help commands
$ hledger help 'time periods' # show the manual's "Time periods" topic
$ hledger help 'time periods' -m # use man, even if info is installed
demo
Play demos of hledger usage in the terminal, if asciinema is installed.
User interface commands
repl
Start an interactive prompt, where you can run any of hledger's com-
mands. Data files are parsed just once, so the commands run faster.
Flags:
-s --speed=SPEED playback speed (1 is original speed, .5 is half, 2
is double, etc (default: 2))
no command-specific flags
Run this command with no argument to list the demos. To play a demo,
write its number or a prefix or substring of its title. Tips:
This command is experimental and could change in the future.
Make your terminal window large enough to see the demo clearly.
hledger repl starts a read-eval-print loop (REPL) where you can enter
commands interactively. As with the run command, each input file (or
each input file/input options combination) is parsed just once, so com-
mands will run more quickly than if you ran them individually at the
command line.
Use the -s/--speed SPEED option to set your preferred playback speed,
eg -s4 to play at 4x original speed or -s.5 to play at half speed. The
default speed is 2x.
Also like run, the input file(s) specified for the repl command will be
the default input for all interactive commands, you can override this
temporarily by specifying an -f option in particular commands, and com-
mands will not see any changes made to input files (eg by add) until
you exit and restart the REPL.
Other asciinema options can be added following a double dash, eg --
-i.1 to limit pauses or -- -h to list asciinema's other options.
The command syntax is the same as with run:
During playback, several keys are available: SPACE to pause/unpause, .
to step forward (while paused), CTRL-c quit.
o enter one hledger command at a time, without the usual hledger first
word
Examples:
o empty lines and comment text from # to end of line are ignored
$ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install -s4 # play the "install" demo at 4x speed
o use single or double quotes to quote arguments when needed
This command is experimental: there aren't many useful demos yet.
o type exit or quit or control-D to exit the REPL.
While it is running, the REPL remembers your command history, and you
can navigate in the usual ways: - Keypad or Emacs navigation keys to
edit the current command line - UP/DOWN or control-P/control-N to step
back/forward through history - control-R to search for a past command,
etc.
The commands and help commands, and the command help flags (CMD --tldr,
CMD -h/--help, CMD --info, CMD --man), work in the usual way, and can
be useful.
You can type control-C to cancel a long-running command (but only once;
typing it a second time will exit the REPL).
And in most shells you can type control-Z to exit temporarily to the
shell (and fg to return to the REPL).
Caveats
You may find some differences in behaviour between run command lines
and normal hledger command lines. For example, in the REPL,
o the command name must be written first, options afterward
o full command names or official abbreviations (as in the command list)
must be used
o options parsing with addon commands might be less flexible than the
CLI
o the stats command gives false timings, currently
Examples
Start the REPL:
hledger repl
or
hledger repl -f some.journal
run
Run a sequence of hledger commands, provided as files or command line
arguments. Data files are parsed just once, so the commands run
faster.
Flags:
no command-specific flags
This command is experimental and could change in the future.
You can use run in three ways:
o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
line, separated by --
o hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
files
o cat SCRIPTFILE1 | hledger run - read commands from standard input.
run first loads the input file(s) specified by LEDGER_FILE or by -f op-
tions, in the usual way. Then it runs each command in turn, each using
the same input data. But if you want a particular command to use dif-
ferent input, you can specify an -f option within that command. This
will override (not add to) the default input, just for that command.
Each input file (more precisely, each combination of input file and in-
put options) is parsed only once. This means that commands will not
see any changes made to these files, until the next run. But the com-
mands will run more quickly than if run individually (typically about
twice as fast).
Command scripts, whether in a file or written on the command line, have
a simple syntax:
o each line may contain a single hledger command and its arguments,
without the usual hledger first word
o empty lines are ignored
o text from # to end of line is a comment, and ignored
o you can use single or double quotes to quote arguments when needed,
as on the command line
o these extra commands are available: echo TEXT prints some text, and
exit or quit ends the run.
On unix systems you can use #!/usr/bin/env hledger run in the first
line of a command file to make it a runnable script. If that gives an
error, use #!/usr/bin/env -S hledger run.
It's ok to use the run command recursively within a command script.
Caveats
You may find some differences in behaviour between run command lines
and normal hledger command lines. For example, with run,
o the command name must be written first, options afterward
o full command names or official abbreviations (as in the command list)
must be used
Examples
Run commands specified on the command line:
hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
This would load some.journal, run balance assets --depth 2 on it, then
run balance liabilities --depth 3 --transpose on /some/other.journal,
and finally run stats on some.journal
Run commands from standard input:
(echo "files"; echo "stats") | hledger -f some.journal run
Provide commands as a runnable script:
#!/usr/bin/env -S hledger run -f some.journal
echo "List of accounts in some.journal"
accounts
echo "Assets of some.journal"
balance assets --depth 2
echo "Liabilities from /some/other.journal"
balance liabilities -f /some/other.journal --depth 3 --transpose
echo "Commands from another.script, applied to another.journal"
run -f another.journal another.script
User interface commands
ui
Runs hledger-ui (if installed).