diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 276c059acf0..6b435ba2a83 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -640,9 +640,8 @@ The config file feature was added in hledger 1.40 and is considered *experimenta ## Shell completions -If you use the bash shell, you can optionally set up context-sensitive autocompletions when you press TAB in a hledger command line. -At a bash shell prompt, try pressing -`hledger` (should list all hledger commands) +If you use the bash or zsh shells, you can optionally set up context-sensitive autocompletion for hledger command lines. +Try pressing `hledger` (should list all hledger commands) or `hledger reg acct:` (should list your top-level account names). If completions aren't working, or for more details, see [Install > Shell completions](install.html#shell-completions). diff --git a/hledger/shell-completion/README.md b/hledger/shell-completion/README.md index e10dd2fa568..2fd4e3a7414 100644 --- a/hledger/shell-completion/README.md +++ b/hledger/shell-completion/README.md @@ -2,8 +2,13 @@ This code generates shell completion scripts for hledger's command line interface. Context-sensitive completions are usually triggered by pressing the tab key once or twice after typing the command `hledger ` (or `hledger-ui` or `hledger-web`). -Currently only Bash is supported, but Zsh or Fish could be added. +Currently there are detailed bash completions here in the hledger repo, which this doc is mostly about; +and there are some zsh completions maintained in zsh-completions repo. + +## bash completions + +An old demo: [![asciicast](https://asciinema.org/a/227935.svg)](https://asciinema.org/a/227935) To use hledger's bash shell completions, these must be installed on your system: @@ -12,24 +17,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 user setup and usage instructions, please see [Install > Shell completions](https://hledger.org/install.html#shell-completions). - -To test the bash completions, at a bash shell prompt, type -`hledger` (should list all hledger commands) -or `hledger reg acct:` (should list your top-level account names). - -The bash completion script can handle: - -- hledger's command argument -- general flags -- command-specific flags, after the command argument -- flag values, for flags that have standard values -- query prefixes -- account names from the journal, after an account name prefix -- appropriate data from the journal, after these query prefixes: `acct:`, `code:`, `cur:`, `desc:`, `note:`, `payee:`, `real:`, `status:`, `tag:` -- amount comparison operators, after `amt:`. +For latest user setup instructions and feature list, please see [Install > Shell completions](https://hledger.org/install.html#shell-completions). -## Generating hledger shell completions +### Generating the bash completions In the main hledger repo, first build and install an up-to-date version of hledger in PATH, @@ -49,7 +39,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 completions +### Installing the bash completions (If you want a released version of the completion script, use the Install page link above instead.) @@ -64,19 +54,20 @@ 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 +### Packaging the bash 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 +hledger versions before 1.40 don't have up-to-date bash completions. + +For hledger 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 +Since hledger 1.41, this is included in the Github release bindists, and available at urls like +https://github.com/simonmichael/hledger/blob/1.41/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`. @@ -88,7 +79,12 @@ Here is a place to track the status of shell completions in hledger packages. As - Arch Linux AUR: packaging in progress - Others: unknown -## Completion scripts for other shells +## zsh completions + +There are some [zsh completions](https://github.com/zsh-users/zsh-completions/blob/master/src/_hledger) in the zsh-completions repo. + + +## Completions for other shells You're welcome to add completion scripts for other shells. It should not be too hard! All available hledger options and commands are already there (generated by