From 58f8f176ee047b640fcf98707f9ed95fa5de7f07 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 19 Aug 2026 14:25:15 +0300 Subject: [PATCH 1/8] - Update completions --- Gemfile.lock | 30 ++--- src/advanced/bash-completion.md | 226 ++++++++++++++++++++------------ src/configuration/argument.md | 20 ++- src/configuration/command.md | 15 --- src/configuration/flag.md | 38 ++++-- src/examples.md | 3 +- src/installation.md | 18 ++- src/upgrading-to-bashly-2.0.md | 165 +++++++++++++++++++++++ src/usage/settings.md | 13 ++ 9 files changed, 393 insertions(+), 135 deletions(-) create mode 100644 src/upgrading-to-bashly-2.0.md diff --git a/Gemfile.lock b/Gemfile.lock index b04b38e..c1f591d 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,15 +1,15 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.9) + addressable (2.9.0) public_suffix (>= 2.0.2, < 8.0) base64 (0.3.0) clamp (1.5.2) - colsole (1.0.0) + colsole (1.0.1) docopt_ng (0.7.1) domain_name (0.6.20240107) - ffi (1.17.3-x86_64-linux-gnu) - ffi-compiler (1.3.2) + ffi (1.17.4-x86_64-linux-gnu) + ffi-compiler (1.4.2) ffi (>= 1.15.5) rake filewatcher (3.0.1) @@ -25,7 +25,7 @@ GEM http-cookie (~> 1.0) http-form_data (~> 2.2) llhttp-ffi (~> 0.5.0) - http-cookie (1.1.0) + http-cookie (1.1.6) domain_name (~> 0.5) http-form_data (2.3.0) httpme (0.2.4) @@ -35,7 +35,7 @@ GEM rack-contrib (~> 2.3) rackup (~> 2.2) sinatra (~> 4.2) - io-console (0.8.2) + io-console (0.9.2) llhttp-ffi (0.5.1) ffi-compiler (~> 1.0) rake (~> 13.0) @@ -45,31 +45,29 @@ GEM docopt_ng (~> 0.7.1) reline (~> 0.6) module_methods (1.0.0) - mustermann (3.0.4) - ruby2_keywords (~> 0.0.1) + mustermann (3.1.1) nio4r (2.7.5) - nokogiri (1.19.2-x86_64-linux-gnu) + nokogiri (1.19.4-x86_64-linux-gnu) racc (~> 1.4) public_suffix (7.0.5) - puma (7.2.0) + puma (7.2.1) nio4r (~> 2.0) racc (1.8.1) - rack (3.2.5) + rack (3.2.7) rack-contrib (2.5.0) rack (< 4) rack-protection (4.2.1) base64 (>= 0.1.0) logger (>= 1.6.0) rack (>= 3.0.0, < 4) - rack-session (2.1.1) + rack-session (2.1.2) base64 (>= 0.1.0) rack (>= 3.0.0) rackup (2.3.1) rack (>= 3) - rake (13.3.1) - reline (0.6.3) + rake (13.4.2) + reline (0.7.0) io-console (~> 0.5) - ruby2_keywords (0.0.5) sinatra (4.2.1) logger (>= 1.6.0) mustermann (~> 3.0) @@ -83,7 +81,7 @@ GEM nokogiri (~> 1.10) webcache (~> 0.8) thor (1.5.0) - tilt (2.7.0) + tilt (2.9.0) webcache (0.9.0) http (~> 5.0) diff --git a/src/advanced/bash-completion.md b/src/advanced/bash-completion.md index 89975d1..910826a 100644 --- a/src/advanced/bash-completion.md +++ b/src/advanced/bash-completion.md @@ -5,123 +5,179 @@ order: 60 # Bash Completion -Bashly comes with a built-in bash completions generator, provided by the -[completely][completely] gem. +Bashly can generate native runtime completions for your application. The +generated completion script suggests commands, aliases, flags, positional +arguments with `allowed` values, and flag arguments with `allowed` values. -By running `bashly add completions`, you can add this functionality to your -script in one of three ways: +Runtime completions are disabled by default and currently support Bash only. +## Enable runtime completions -==- `bashly add completions` -Creates a function in your `./src/lib` directory that echoes a completion -script. You can then call this function from any command (for example `yourcli -completions`) and your users will be able to install the completions by running -`eval "$(yourcli completions)"`. +Enable completions in your Bashly settings file: -==- `bashly add completions_script` -Creates a standalone completions script that can be sourced or copied to the -system's bash completions directory. +```yaml settings.yml +enable_completions: always +``` -==- `bashly add completions_yaml` -Creates the raw data YAML file. This is intended mainly for development -purposes. +Add a command that users can call to generate the completion script: -=== +```yaml bashly.yml +commands: +- name: completions + help: Generate a shell completion script + args: + - name: shell + help: Shell to generate completions for + allowed: [bash] + default: bash +``` -The bash completions generation is **completely automatic**, but you will have -to regenerate the completion function whenever you make changes to your -`bashly.yml` file. +In the command handler, call `send_completions` with the requested shell: -!!!success Tip -By running `bashly generate --upgrade`, your completions function -(generated with `bashly add completions`) will be regenerated. -!!! +```bash src/completions_command.sh +send_completions "${args[shell]}" +``` -## Custom argument completions +After regenerating your application, users can load its completion script in +Bash: -In addition to the automatic suggestion of subcommands and flags, you can -instruct bashly to also suggest files, directories, users, git branches and -more. +```bash +source <(cli completions) +``` -For positional arguments, add `completions` to the argument that should receive -these suggestions: +Replace `cli` with the name or path of your generated application. -```yaml bashly.yml -commands: -- name: upload - help: Upload a file - args: - - name: source - help: File to upload - required: true - completions: - - - - - - $(git branch 2> /dev/null) +[!button variant="primary" icon="code-review" text="Runtime Completions Example"](https://github.com/bashly-framework/bashly/tree/master/examples/completions#readme) + +## Configure completion candidates + +In addition to the candidates Bashly generates automatically, you can +configure custom completions for positional arguments and flags that have an +`arg`. + +The `completions` mapping accepts three optional keys: +- `static`: literal completion candidates. +- `dynamic`: Bash commands that print completion candidates. +- `options`: completion behavior and filesystem candidate sources. + +### Static candidates + +Use `static` for literal suggestions: + +```yaml bashly.yml +args: +- name: environment + help: Environment to deploy to + completions: + static: + - staging + - production ``` -The `completions` option is still supported on commands as a fallback for -positional arguments, but it is discouraged for new configurations. Prefer -placing completions directly on the relevant `args` entry. +!!! Note +Use [`allowed`](/configuration/argument/#allowed) when values should be +validated. Use `completions.static` when they should only be suggested. +Values configured with `allowed` are suggested automatically. +!!! -## Custom flag completions +### Dynamic candidates -For flag values, add `completions` to flags that have an `arg`. Similarly to -the `allowed` option for arguments and flags, the allowed list is added to the -suggestions automatically (without the need to use `completions`). +Use `dynamic` to run external commands or Bash functions included in your +generated application: ```yaml bashly.yml -commands: -- name: login - help: Login to SETI - flags: - - long: --user - arg: username - completions: - - - - long: --protocol - arg: protocol - allowed: - - ssh - - telnet +args: +- name: branch + help: Branch to deploy + completions: + dynamic: + - git branch --format='%(refname:short)' + - completion_branches ``` -- Anything between `<...>` will be added using the `compgen -A action` flag. -- Anything else will be appended to the `compgen -W` flag. +Each command or function must print one candidate per line to standard output. +A producer that fails contributes no candidates. Its failure and error output +do not fail or pollute the overall completion request. !!! Note -In case you are using the -[Argument `allowed` option](../configuration/argument.md#allowed) or -the [Flag argument `allowed` option](../configuration/flag.md#allowed), -these will be automatically added to the completions list as well. +Dynamic entries run whenever the user requests a completion. Keep them fast +and side-effect free. !!! -## Completions in ZSH +### Completion options -If you are using Oh-My-Zsh, bash completions should already be enabled, -otherwise, you should enable completion by adding this to your `~/.zshrc` -(if it is not already there): +Use `options` to add filesystem candidates or change how an inserted +completion behaves: -```bash -# Load completion functions -autoload -Uz +X compinit && compinit -autoload -Uz +X bashcompinit && bashcompinit +```yaml bashly.yml +flags: +- long: --config + arg: file + help: Configuration file + completions: + options: [files] + +- long: --directory + arg: path + help: Working directory + completions: + options: [directories] +``` + +The supported options are: + +- `files`: add file and directory candidates. +- `directories`: add directory candidates only. +- `no-space`: do not append a space after inserting a completion. + +Filesystem completion is not implicit. Without `files` or `directories`, the +shell uses only candidates returned by Bashly. + +Normal spacing is the default. Use `no-space` only when the user should +continue typing immediately after the inserted candidate. Candidate +de-duplication is always enabled and is not configurable. + +## Combine completion sources + +You can combine `static`, `dynamic`, and `options` on the same argument or +flag: + +```yaml bashly.yml +args: +- name: environment + help: Environment to deploy to + completions: + static: [staging, production] + dynamic: [completion_environments] + options: [no-space] ``` -After adding this (and restarting your session), you should be able to source -any bash completion script in zsh. +## Test completion candidates -## Additional documentation +The generated application includes an internal `__complete` command. You can +use it to inspect the raw candidates returned for a command line without +loading the completion script: + +```bash +cli __complete deploy main st +``` -For more information about these custom completions, see the -[documentation for the completely gem][completely-docs]. +Each argument after `__complete` represents one word in the command line. Pass +an empty final argument to represent the blank word after a trailing space: -## Example +```bash +cli __complete deploy --config "" +``` -[!button variant="primary" icon="code-review" text="Bash Completions Example"](https://github.com/bashly-framework/bashly/tree/master/examples/completions#readme) +Candidate lines are written to standard output, followed by an internal +`:options=` line used by the Bash completion script. This makes `__complete` +useful when testing custom `static`, `dynamic`, or filesystem completions. +!!! Note +`__complete` is an internal completion endpoint intended for testing and shell +integration. Users should normally load completions with +`source <(cli completions)`. +!!! -[completely]: https://github.com/DannyBen/completely -[completely-docs]: https://github.com/DannyBen/completely#suggesting-files-directories-and-other-bash-built-ins -[compgen]: https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html +[!button variant="primary" icon="code-review" text="Advanced Completions Example"](https://github.com/bashly-framework/bashly/tree/master/examples/completions-advanced#readme) diff --git a/src/configuration/argument.md b/src/configuration/argument.md index 660a2b5..a8ec83e 100644 --- a/src/configuration/argument.md +++ b/src/configuration/argument.md @@ -101,10 +101,24 @@ Allowed values are also added to generated bash completions automatically. ### completions -[!badge Array of Strings] +[!badge Hash] + +Configure additional runtime completions for this argument: + +```yaml +completions: + static: [main, develop] + dynamic: + - git branch --format='%(refname:short)' + options: [no-space] +``` + +- `static` contains literal candidates. +- `dynamic` contains Bash commands or functions that print one candidate per + line. +- `options` accepts `files`, `directories`, and `no-space`. -Specify an array of additional completion suggestions when used in conjunction -with `bashly add completions`. +All three keys are optional and can be combined. [!ref](/advanced/bash-completion.md) diff --git a/src/configuration/command.md b/src/configuration/command.md index cc22c98..f9e554f 100644 --- a/src/configuration/command.md +++ b/src/configuration/command.md @@ -291,21 +291,6 @@ To access arguments captured by `catch_all` in your script, use the [!button variant="primary" icon="code-review" text="Catch All Example"](https://github.com/bashly-framework/bashly/tree/master/examples/catch-all#readme) [!button variant="primary" icon="code-review" text="Catch All Advanced Example"](https://github.com/bashly-framework/bashly/tree/master/examples/catch-all-advanced#readme) -### completions - -[!badge Array of Strings] - -Specify an array of additional completion suggestions when used in conjunction -with `bashly add completions`. - -This command-level option is supported as a fallback for positional arguments, -but it is discouraged for new configurations. Prefer setting -[`completions`](argument.md#completions) on the relevant argument, or on the -relevant [`flag`](flag.md#completions) when completing a flag value. - -[!ref](/advanced/bash-completion.md) - - ### dependencies [!badge Array of Strings / Hash / Array of Dependencies] diff --git a/src/configuration/flag.md b/src/configuration/flag.md index b3659c4..4948f29 100644 --- a/src/configuration/flag.md +++ b/src/configuration/flag.md @@ -166,6 +166,32 @@ Remember to set the [`arg`](#arg) name when using this option. [!button variant="primary" icon="code-review" text="Whitelist Example"](https://github.com/bashly-framework/bashly/tree/master/examples/whitelist#readme) +### completions + +[!badge Hash] + +Configure additional runtime completions for this flag's value: + +```yaml +flags: +- long: --config + arg: file + completions: + options: [files] +``` + +- `static` contains literal candidates. +- `dynamic` contains Bash commands or functions that print one candidate per + line. +- `options` accepts `files`, `directories`, and `no-space`. + +All three keys are optional and can be combined. + +Remember to set the [`arg`](#arg) name when using this option. + +[!ref](/advanced/bash-completion.md) + + ### conflicts [!badge Array of Strings] @@ -181,18 +207,6 @@ This option should be specified on both sides of the exclusivity. [!button variant="primary" icon="code-review" text="Conflicts Example"](https://github.com/bashly-framework/bashly/tree/master/examples/conflicts#readme) -### completions - -[!badge Array of Strings] - -Specify an array of additional completion suggestions for this flag's value -when used in conjunction with `bashly add completions`. - -Remember to set the [`arg`](#arg) name when using this option. - -[!ref](/advanced/bash-completion.md) - - ### needs [!badge Array of Strings] diff --git a/src/examples.md b/src/examples.md index 630352b..4b13d77 100644 --- a/src/examples.md +++ b/src/examples.md @@ -32,9 +32,11 @@ All examples are listed below for convenience. - [default-values](https://github.com/bashly-framework/bashly/tree/master/examples/default-values#readme) - arguments and flags with default values - [minus-v](https://github.com/bashly-framework/bashly/tree/master/examples/minus-v#readme) - using `-v` and `-h` in your script - [multiline](https://github.com/bashly-framework/bashly/tree/master/examples/multiline#readme) - help messages with multiple lines +- [completions](https://github.com/bashly-framework/bashly/tree/master/examples/completions#readme) - exposing runtime shell completions ## Advanced configuration features +- [completions-advanced](https://github.com/bashly-framework/bashly/tree/master/examples/completions-advanced#readme) - configuring static, dynamic, and option-based runtime completions - [catch-all](https://github.com/bashly-framework/bashly/tree/master/examples/catch-all#readme) - a command that can receive an arbitrary number of arguments - [catch-all-advanced](https://github.com/bashly-framework/bashly/tree/master/examples/catch-all-advanced#readme) - another example for the `catch_all` option - [catch-all-stdin](https://github.com/bashly-framework/bashly/tree/master/examples/catch-all-stdin#readme) - combining `catch_all` with `stdin` to read multiple files @@ -78,7 +80,6 @@ All examples are listed below for convenience. - [ini](https://github.com/bashly-framework/bashly/tree/master/examples/ini#readme) - using the ini library for direct, low level access to INI files - [yaml](https://github.com/bashly-framework/bashly/tree/master/examples/yaml#readme) - using the YAML reading functions - [colors](https://github.com/bashly-framework/bashly/tree/master/examples/colors#readme) - using the color print feature -- [completions](https://github.com/bashly-framework/bashly/tree/master/examples/completions#readme) - adding bash completion functionality - [validations](https://github.com/bashly-framework/bashly/tree/master/examples/validations#readme) - adding validation functions for arguments, flags or environment variables - [hooks](https://github.com/bashly-framework/bashly/tree/master/examples/hooks#readme) - adding before/after hooks - [stacktrace](https://github.com/bashly-framework/bashly/tree/master/examples/stacktrace#readme) - adding stacktrace on error diff --git a/src/installation.md b/src/installation.md index d6236cb..e6deb8a 100644 --- a/src/installation.md +++ b/src/installation.md @@ -9,7 +9,7 @@ Install bashly using one of these methods. +++ Ruby Gem -Bashly requires Ruby 3.2 or higher (`ruby -v`). +Bashly requires Ruby 3.3 or higher (`ruby -v`). ```shell gem install bashly @@ -35,12 +35,24 @@ whalebrew install dannyben/bashly ## Bash Completions -To enable bash completions for the `bashly` executable itself run: +To load completions for the `bashly` executable in the current Bash session, +run: ```shell -bashly completions --install +source <(bashly completions) ``` +For a persistent per-user installation, save the script as `bashly` in the +standard user completions directory: + +```shell +mkdir -p ~/.local/share/bash-completion/completions +bashly completions > ~/.local/share/bash-completion/completions/bashly +``` + +The `bash-completion` package will load this file on demand when completing the +`bashly` command. + You might need to install the `bash-completion` package for your operating system if it is not already installed. For example: diff --git a/src/upgrading-to-bashly-2.0.md b/src/upgrading-to-bashly-2.0.md new file mode 100644 index 0000000..85a14b7 --- /dev/null +++ b/src/upgrading-to-bashly-2.0.md @@ -0,0 +1,165 @@ +--- +icon: arrow-up +order: 55 +--- + +# Upgrading to Bashly 2.0 + +Bashly 2.0 is mostly backward compatible. The main breaking change is the new +native runtime completion system, which replaces the Completely-based system +used by earlier versions. + +This guide explains how to update an existing Bashly project. + +## Migrate generated completion support + +If your application provides a completion script: + +1. Remove completion files previously created with `bashly add completions`, + `bashly add completions_script`, or `bashly add completions_yaml`. These + libraries are no longer used. +2. Remove any generated `send_completions` function from your `lib` folder. + Bashly now generates this function internally. +3. Enable runtime completions in your Bashly settings file: + + ```yaml settings.yml + enable_completions: always + ``` + +4. Regenerate your application. Existing commands or flags that call + `send_completions` can continue to do so. + +The generated `send_completions` function currently supports Bash. For +example, an application can expose it through a `completions` command whose +handler contains: + +```bash +send_completions "${args[shell]}" +``` + +[!ref](/advanced/bash-completion/) + +[!button variant="primary" icon="code-review" text="Runtime Completions Example"][completions-example] + +## Migrate custom completions + +The `completions` directive in `bashly.yml` now uses a structured runtime +format and is supported only on arguments and flags. The old array syntax and +command-level `completions` are no longer supported. + +### Literal candidates + +Move literal candidates to `static`: + +```yaml +# Before +completions: + - main + - develop + +# After +completions: + static: + - main + - develop +``` + +!!! Note +Use [`allowed`](/configuration/argument/#allowed) when values should be +validated. Use `completions.static` when they should only be suggested. +!!! + +### Commands and functions + +Move shell commands and Bash functions to `dynamic`, without wrapping them in +`$()`: + +```yaml +# Before +completions: + - $(git branch --format='%(refname:short)') + - $(my_completion_function) + +# After +completions: + dynamic: + - git branch --format='%(refname:short)' + - my_completion_function +``` + +Each dynamic entry runs in the generated Bashly script when completion is +requested and must print one candidate per line. Bash resolves whether the +entry invokes an external command or a function included in the generated +script. + +A failing entry contributes no candidates. Its failure and error output do not +fail or pollute the overall completion request. + +!!! Note +Dynamic entries run whenever the user requests a completion. Use fast, +side-effect-free commands and functions. +!!! + +### Files and directories + +Move file and directory completion to `options`: + +```yaml +# Before +completions: + - + - + +# After +completions: + options: + - files + - directories +``` + +The supported completion options are: + +- `files`: add file and directory candidates. +- `directories`: add directory candidates only. +- `no-space`: do not append a space after inserting a completion. + +Filesystem completion is never implicit. Without `files` or `directories`, +the shell uses only candidates returned by Bashly. + +Normal spacing is the default. Use `no-space` only when the user should +continue typing immediately after the inserted candidate. Candidate +de-duplication is always enabled and is not configurable. + +### Command-level completions + +Remove `completions` from commands and configure the relevant positional +argument or flag argument instead: + +```yaml +# Before +commands: +- name: checkout + completions: + - $(git branch --format='%(refname:short)') + +# After +commands: +- name: checkout + args: + - name: branch + completions: + dynamic: + - git branch --format='%(refname:short)' +``` + +### Completely actions + +Completely-specific actions such as ``, ``, and `` no +longer have built-in equivalents. Replace them with a dynamic command or +function that prints the desired candidates, one per line. + +[!button variant="primary" icon="code-review" text="Advanced Completions Example"][completions-advanced-example] + + +[completions-example]: https://github.com/bashly-framework/bashly/tree/master/examples/completions#readme +[completions-advanced-example]: https://github.com/bashly-framework/bashly/tree/master/examples/completions-advanced#readme diff --git a/src/usage/settings.md b/src/usage/settings.md index c07e3ac..48e2c3e 100644 --- a/src/usage/settings.md +++ b/src/usage/settings.md @@ -353,6 +353,19 @@ enable_bash3_bouncer: always Specify if you wish to render the piece of code that aborts the script execution when bash version is < 4.2. +### `enable_completions` + +```yaml +# default (allowed: always, never, development, production) +enable_completions: never +``` + +Specify if you want the generated script to include native runtime completion +support, including the `send_completions` function and internal `__complete` +command. + +[!ref](/advanced/bash-completion/) + ### `enable_view_markers` ```yaml From 4dc4478aed37a41397e52365adf869222295411c Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 19 Aug 2026 14:25:52 +0300 Subject: [PATCH 2/8] version 2.0.0 --- retype.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/retype.yml b/retype.yml index 405e605..a40f337 100644 --- a/retype.yml +++ b/retype.yml @@ -12,7 +12,7 @@ editor: enabled: false branding: - label: v1.4.0 + label: v2.0.0 logo: assets/logo.svg logoDark: assets/logo-dark.svg # logoWidth: 143 From 2044ce735798343424f60d60a4ccbc890da24ae3 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 19 Aug 2026 15:16:11 +0300 Subject: [PATCH 3/8] rename to enable_bash_version_bouncer --- src/usage/settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/usage/settings.md b/src/usage/settings.md index 48e2c3e..1a7ce8a 100644 --- a/src/usage/settings.md +++ b/src/usage/settings.md @@ -343,11 +343,11 @@ enable_header_comment: always Specify if you wish to render the "do not modify" comment at the beginning of the script. -### `enable_bash3_bouncer` +### `enable_bash_version_bouncer` ```yaml # default (allowed: always, never, development, production) -enable_bash3_bouncer: always +enable_bash_version_bouncer: always ``` Specify if you wish to render the piece of code that aborts the script execution From 169b04c2c7f31ba6caf95aa742047098d93dfce5 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 19 Aug 2026 15:19:59 +0300 Subject: [PATCH 4/8] update migration guide --- src/upgrading-to-bashly-2.0.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/upgrading-to-bashly-2.0.md b/src/upgrading-to-bashly-2.0.md index 85a14b7..e306678 100644 --- a/src/upgrading-to-bashly-2.0.md +++ b/src/upgrading-to-bashly-2.0.md @@ -11,6 +11,11 @@ used by earlier versions. This guide explains how to update an existing Bashly project. +## Rename the Bash version bouncer setting + +Rename `enable_bash3_bouncer` to `enable_bash_version_bouncer` in your Bashly +settings file. Its allowed values and behavior remain unchanged. + ## Migrate generated completion support If your application provides a completion script: From 8058f692646ff06702eab4d70033d1f933ea8152 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 19 Aug 2026 18:02:26 +0300 Subject: [PATCH 5/8] update completions settings --- src/advanced/bash-completion.md | 24 +++++++++++------- src/installation.md | 4 +-- src/upgrading-to-bashly-2.0.md | 21 +++++++++++++--- src/usage/settings.md | 44 +++++++++++++++++++++++---------- 4 files changed, 65 insertions(+), 28 deletions(-) diff --git a/src/advanced/bash-completion.md b/src/advanced/bash-completion.md index 910826a..f5baf32 100644 --- a/src/advanced/bash-completion.md +++ b/src/advanced/bash-completion.md @@ -3,20 +3,22 @@ icon: dot order: 60 --- -# Bash Completion +# Runtime Completions Bashly can generate native runtime completions for your application. The generated completion script suggests commands, aliases, flags, positional arguments with `allowed` values, and flag arguments with `allowed` values. -Runtime completions are disabled by default and currently support Bash only. +Runtime completions are disabled by default. Bashly provides adapters for Bash +and Zsh. ## Enable runtime completions -Enable completions in your Bashly settings file: +Enable the runtime engine and all available shell adapters in your Bashly +settings file: ```yaml settings.yml -enable_completions: always +completions: full ``` Add a command that users can call to generate the completion script: @@ -28,7 +30,7 @@ commands: args: - name: shell help: Shell to generate completions for - allowed: [bash] + allowed: [bash, zsh] default: bash ``` @@ -39,10 +41,14 @@ send_completions "${args[shell]}" ``` After regenerating your application, users can load its completion script in -Bash: +their shell: ```bash -source <(cli completions) +# Bash +source <(cli completions bash) + +# Zsh +source <(cli completions zsh) ``` Replace `cli` with the name or path of your generated application. @@ -171,13 +177,13 @@ cli __complete deploy --config "" ``` Candidate lines are written to standard output, followed by an internal -`:options=` line used by the Bash completion script. This makes `__complete` +`:options=` line used by the shell adapters. This makes `__complete` useful when testing custom `static`, `dynamic`, or filesystem completions. !!! Note `__complete` is an internal completion endpoint intended for testing and shell integration. Users should normally load completions with -`source <(cli completions)`. +`source <(cli completions bash)` or `source <(cli completions zsh)`. !!! [!button variant="primary" icon="code-review" text="Advanced Completions Example"](https://github.com/bashly-framework/bashly/tree/master/examples/completions-advanced#readme) diff --git a/src/installation.md b/src/installation.md index e6deb8a..14e9a29 100644 --- a/src/installation.md +++ b/src/installation.md @@ -63,8 +63,8 @@ sudo apt install bash-completion ``` !!!success Tip -To generate bash completions for your own scripts, see -[Advanced Features :icon-chevron-right: Bash Completion](/advanced/bash-completion/) +To generate runtime completions for your own scripts, see [Advanced Features +:icon-chevron-right: Runtime Completions](/advanced/bash-completion/) !!! ## Prerequisites diff --git a/src/upgrading-to-bashly-2.0.md b/src/upgrading-to-bashly-2.0.md index e306678..6ac028a 100644 --- a/src/upgrading-to-bashly-2.0.md +++ b/src/upgrading-to-bashly-2.0.md @@ -28,15 +28,28 @@ If your application provides a completion script: 3. Enable runtime completions in your Bashly settings file: ```yaml settings.yml - enable_completions: always + completions: full ``` 4. Regenerate your application. Existing commands or flags that call `send_completions` can continue to do so. -The generated `send_completions` function currently supports Bash. For -example, an application can expose it through a `completions` command whose -handler contains: +The generated `send_completions` function supports Bash and Zsh. For example, +an application can expose it through a `completions` command whose shell +argument allows both adapters: + +```yaml bashly.yml +commands: +- name: completions + help: Generate a shell completion script + args: + - name: shell + help: Shell to generate completions for + allowed: [bash, zsh] + default: bash +``` + +Its handler can then dispatch to the requested adapter: ```bash send_completions "${args[shell]}" diff --git a/src/usage/settings.md b/src/usage/settings.md index 1a7ce8a..b05f444 100644 --- a/src/usage/settings.md +++ b/src/usage/settings.md @@ -311,6 +311,37 @@ This option cannot be set using environment variables. ## Feature Toggles +### `completions` + +```yaml +# Generate the runtime engine and all available shell adapters +completions: full + +# default +completions: ~ +``` + +Specify which native runtime completion components to include in the generated +script: + +- `~` or `false`: generate no completion code (default). +- `minimal`: generate the internal `__complete` runtime engine without + `send_completions` or shell adapters. +- `bash`: generate the runtime engine and Bash adapter. +- `zsh`: generate the runtime engine and Zsh adapter. +- `bash,zsh` or `bash, zsh`: generate the runtime engine and the selected + adapters. +- `full`: generate the runtime engine and every available adapter. + +When at least one adapter is selected, Bashly generates the +`send_completions` function. Bash and Zsh adapters are currently available. + +The same values can be provided through `BASHLY_COMPLETIONS`. Like other +settings, this setting can use an environment suffix, such as +`completions_production`. + +[!ref](/advanced/bash-completion/) + ### `env` ```yaml @@ -353,19 +384,6 @@ enable_bash_version_bouncer: always Specify if you wish to render the piece of code that aborts the script execution when bash version is < 4.2. -### `enable_completions` - -```yaml -# default (allowed: always, never, development, production) -enable_completions: never -``` - -Specify if you want the generated script to include native runtime completion -support, including the `send_completions` function and internal `__complete` -command. - -[!ref](/advanced/bash-completion/) - ### `enable_view_markers` ```yaml From afdfe422437326a1b7852c910f9efbf110a4d9ff Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 19 Aug 2026 20:48:44 +0300 Subject: [PATCH 6/8] add start override --- src/usage/settings.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/usage/settings.md b/src/usage/settings.md index b05f444..6fde049 100644 --- a/src/usage/settings.md +++ b/src/usage/settings.md @@ -504,11 +504,13 @@ This option cannot be set using environment variables. ```yaml # default function_names: + start: ~ run: ~ initialize: ~ # example function_names: + start: bashly_start run: bashly_run initialize: bashly_initialize ``` @@ -516,8 +518,8 @@ function_names: Update one or more of these options in case you wish to change the name of the equivalent internal bashly function. -This feature can be useful when you wish to reserve the function name `run` or -`initialize` for something else. +This feature can be useful when you wish to reserve the function name `start`, +`run`, or `initialize` for something else. !!! Note This option cannot be set using environment variables. From 6ef5c24d2452958e6f8b4bae7310f38ecf58f279 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 22 Aug 2026 17:44:50 +0300 Subject: [PATCH 7/8] update brew instructions --- src/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/installation.md b/src/installation.md index 8c03139..f0247b3 100644 --- a/src/installation.md +++ b/src/installation.md @@ -19,10 +19,10 @@ gem install bashly +++ Homebrew -If you have Homebrew installed, you can install Bashly from the official tap: +If you have Homebrew installed, you can install Bashly directly from Homebrew Core: ```shell -brew install bashly-framework/tap/bashly +brew install bashly ``` +++ Docker From 6e150491fe973cfd159170e43c0d1442b27f7e72 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 22 Aug 2026 19:52:48 +0300 Subject: [PATCH 8/8] update migration guide --- src/upgrading-to-bashly-2.0.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/upgrading-to-bashly-2.0.md b/src/upgrading-to-bashly-2.0.md index 6ac028a..f0e22f1 100644 --- a/src/upgrading-to-bashly-2.0.md +++ b/src/upgrading-to-bashly-2.0.md @@ -5,18 +5,18 @@ order: 55 # Upgrading to Bashly 2.0 -Bashly 2.0 is mostly backward compatible. The main breaking change is the new -native runtime completion system, which replaces the Completely-based system -used by earlier versions. +Bashly 2.0 is mostly backward compatible. Review the settings changes and shell +completion migration steps below before regenerating your application. -This guide explains how to update an existing Bashly project. +## Settings -## Rename the Bash version bouncer setting +- Rename `enable_bash3_bouncer` to `enable_bash_version_bouncer`. +- Delete `watch_evented`. Evented file watching is no longer supported; Bashly + now uses polling. -Rename `enable_bash3_bouncer` to `enable_bash_version_bouncer` in your Bashly -settings file. Its allowed values and behavior remain unchanged. +## Shell Completion -## Migrate generated completion support +### Generated completion support If your application provides a completion script: @@ -59,13 +59,13 @@ send_completions "${args[shell]}" [!button variant="primary" icon="code-review" text="Runtime Completions Example"][completions-example] -## Migrate custom completions +### Custom completions The `completions` directive in `bashly.yml` now uses a structured runtime format and is supported only on arguments and flags. The old array syntax and command-level `completions` are no longer supported. -### Literal candidates +#### Literal candidates Move literal candidates to `static`: @@ -87,7 +87,7 @@ Use [`allowed`](/configuration/argument/#allowed) when values should be validated. Use `completions.static` when they should only be suggested. !!! -### Commands and functions +#### Commands and functions Move shell commands and Bash functions to `dynamic`, without wrapping them in `$()`: @@ -118,7 +118,7 @@ Dynamic entries run whenever the user requests a completion. Use fast, side-effect-free commands and functions. !!! -### Files and directories +#### Files and directories Move file and directory completion to `options`: @@ -148,7 +148,7 @@ Normal spacing is the default. Use `no-space` only when the user should continue typing immediately after the inserted candidate. Candidate de-duplication is always enabled and is not configurable. -### Command-level completions +#### Command-level completions Remove `completions` from commands and configure the relevant positional argument or flag argument instead: @@ -170,7 +170,7 @@ commands: - git branch --format='%(refname:short)' ``` -### Completely actions +#### Completely actions Completely-specific actions such as ``, ``, and `` no longer have built-in equivalents. Replace them with a dynamic command or