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

;doc: shell-completion/README: packager notes [#986]

Browse Source
This commit is contained in:
Simon Michael 2024-09-17 11:25:52 -07:00
parent 2a054a3cc8
commit f76307bcdb
1 changed files with 22 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
hledger/shell-completion/README.md
View File

@ -12,9 +12,9 @@ To use hledger's bash shell completions, these must be installed on your system:
- hledger's bash completion script
- hledger, hledger-ui, and/or hledger-web
For full setup instructions, see [Install > Shell completions](https://hledger.org/install.html#shell-completions).
For user setup and usage instructions, please see [Install > Shell completions](https://hledger.org/install.html#shell-completions).
To test your setup: at a bash shell prompt, try typing
To test the bash completions, at a bash shell prompt, type
`hledger<SPACE><TAB><TAB>` (should list all hledger commands)
or `hledger reg acct:<TAB><TAB>` (should list your top-level account names).
@ -29,7 +29,7 @@ The bash completion script can handle:
- appropriate data from the journal, after these query prefixes: `acct:`, `code:`, `cur:`, `desc:`, `note:`, `payee:`, `real:`, `status:`, `tag:`
- amount comparison operators, after `amt:`.
## Generating the shell completion script
## Generating hledger shell completions
In the main hledger repo,
first build and install an up-to-date version of hledger in PATH,
@ -49,7 +49,7 @@ You can add `-jNUMPROCS` to make it run faster.
Data from the journal (account names, payee names etc.) is not gathered here;
the script detects those dynamically at completion time.
## Installing the generated shell completion script
## Installing the generated shell completions
(If you want a released version of the completion script, use the Install page link above instead.)
@ -64,6 +64,24 @@ bash will use it when completing command lines beginning with "hledger" or "hled
You can also just source the script it in your shell startup; this will load completions eagerly, adding a delay to your shell start up time.
Or you can source it in your current bash session for testing.
## Packaging hledger shell completions
It's great when hledger packagers can make shell completions just work for users.
Currently there is one completion script: `hledger-completion.bash`.
It is included in the hledger package's tarball on Hackage.
For hledger version 1.40, the up-to-date script is at
https://github.com/simonmichael/hledger/blob/39dfe5702e1b401f1883d814907d242958eec9c1/hledger/shell-completion/hledger-completion.bash.
From releases after 1.40, it will be included in the bindists provided in Github releases,
and available at urls like
https://github.com/simonmichael/hledger/blob/1.40/hledger/shell-completion/hledger-completion.bash
After it has been loaded, this script will provide completions for hledger, hledger-ui and hledger-web.
Note if it is installed only as `hledger`, bash-completion will not load it until the user types `hledger<SPACE><TAB>`.
Consider also symbolic-linking it as `hledger-ui` and `hledger-web`, so that `hledger-ui<SPACE><TAB>` and `hledger-web<SPACE><TAB>` will also load it.
## Completion scripts for other shells
You're welcome to add completion scripts for other shells. It should not be too