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 .PP
Next, these commands are described in detail. Next, these commands are described in detail.
.SH Help commands .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 .SS help
Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a
pager. 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] # show the manual\[aq]s \[dq]Time periods\[dq] topic
$ hledger help \[aq]time periods\[aq] \-m # use man, even if info is installed $ hledger help \[aq]time periods\[aq] \-m # use man, even if info is installed
.EE .EE
.SS demo .SH User interface commands
Play demos of hledger usage in the terminal, if asciinema is installed. .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 .IP
.EX .EX
Flags: Flags:
\-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2 no command\-specific flags
is double, etc (default: 2))
.EE .EE
.PP .PP
Run this command with no argument to list the demos. This command is experimental and could change in the future.
To play a demo, write its number or a prefix or substring of its title.
Tips:
.PP .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 .PP
Use the \-s/\-\-speed SPEED option to set your preferred playback speed, Also like \f[CR]run\f[R], the input file(s) specified for the
eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to \f[CR]repl\f[R] command will be the default input for all interactive
play at half speed. commands, you can override this temporarily by specifying an
The default speed is 2x. \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 .PP
Other asciinema options can be added following a double dash, eg The command syntax is the same as with \f[CR]run\f[R]:
\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list .IP \[bu] 2
asciinema\[aq]s other options. 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 .PP
During playback, several keys are available: SPACE to pause/unpause, . While it is running, the REPL remembers your command history, and you
to step forward (while paused), CTRL\-c quit. 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 .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 .IP
.EX .EX
$ hledger demo # list available demos hledger repl
$ 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 .EE
.PP .PP
This command is experimental: there aren\[aq]t many useful demos yet. or
.SH User interface commands .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 .SS ui
Runs hledger\-ui (if installed). Runs hledger\-ui (if installed).
.SS web .SS web

524
hledger/hledger.info
View File

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

209
hledger/hledger.txt
View File

@ -6487,6 +6487,42 @@ PART 4: COMMANDS
Next, these commands are described in detail. Next, these commands are described in detail.
Help commands 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 help
Show the hledger user manual with info, man, or a pager. With a (case 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. 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' # show the manual's "Time periods" topic
$ hledger help 'time periods' -m # use man, even if info is installed $ hledger help 'time periods' -m # use man, even if info is installed
demo User interface commands
Play demos of hledger usage in the terminal, if asciinema is installed. 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: Flags:
-s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 no command-specific flags
is double, etc (default: 2))
Run this command with no argument to list the demos. To play a demo, This command is experimental and could change in the future.
write its number or a prefix or substring of its title. Tips:
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, Also like run, the input file(s) specified for the repl command will be
eg -s4 to play at 4x original speed or -s.5 to play at half speed. The the default input for all interactive commands, you can override this
default speed is 2x. 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 -- The command syntax is the same as with run:
-i.1 to limit pauses or -- -h to list asciinema's other options.
During playback, several keys are available: SPACE to pause/unpause, . o enter one hledger command at a time, without the usual hledger first
to step forward (while paused), CTRL-c quit. word
Examples: o empty lines and comment text from # to end of line are ignored
$ hledger demo # list available demos o use single or double quotes to quote arguments when needed
$ 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. 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 ui
Runs hledger-ui (if installed). Runs hledger-ui (if installed).