reorder sections to group completion related changes

Author: Bahex

blog/2025-10-14-nushell_v0_108_0.md

@@ -419,6 +419,120 @@ The following commands now have suggestions:
 - `table --theme <...>`
 - `split list --split <...>`
 
+### Simple syntax for simple completions ([#16789])
+
+Custom completions are powerful, able to provide dynamic completions based on what's written on the command line so far.
+
+But you don't always need that power. In fact, for most cases a simple static list of options is enough.
+
+To make it simpler and more concise to meet this need, this release adds a new way to define completions for command parameters:
+```ansi:no-line-numbers
+def go [
+    direction: string@[ left up right down ]
+] {
+    $direction
+}
+```
+
+Completions can be provided as a list of strings inline in the command signature, or stored in a `const` variable and used like that. 
+```ansi:no-line-numbers
+const directions = [ left up right down ]
+
+def go [ direction: string@$directions ] {
+    $direction
+}
+```
+
+### Command-wide completion handler ([#16765])
+
+There is big difference between custom completions that can be specified in a command's signature, and the "global" external completer (`$env.config.completions.external.completer`).
+
+The former is added to individual parameters, while the latter provides completions for all arguments of (external) commands.
+
+This makes using custom commands that wrap external commands awkward. The global external completer won't provide completions for the wrapper command and adding completions to that command uses a completely different API. It would be nice to be able to use the external completer's API for custom completions, or use the external completer for wrapper commands...
+
+#### `@complete external`
+
+Now it's possible to explicitly enable the global external completer for `extern` and custom command `def`initions:
+
+```nushell
+@complete external
+def --wrapped jc [...args] {
+    ^jc ...$args | from json
+}
+```
+
+#### `@complete <completer>`
+
+Instead of using the external completer, command-wide custom completers can be used for specific commands:
+
+```nushell
+def carapace-completer [spans: list<string>] {
+    ^carapace ..
+}
+
+@complete carapace-completer
+def --env get-env [name] { $env | get $name }
+
+@complete carapace-completer
+def --env set-env [name, value] { load-env { $name: $value } }
+
+@complete carapace-completer
+def --env unset-env [name] { hide-env $name }
+```
+
+Combined with `extern` definitions, this makes it trivial to use specific completion sources for specific commands:
+
+```nushell
+def fish-completer [spans: list<string>] {
+	^fish ..
+}
+
+@complete fish-completer
+extern git []
+
+@complete fish-completer
+extern asdf []
+```
+
+Yes, you can remove the `match` expression from your external completer!
+
+```nushell
+{|spans: list<string>|
+
+    # ...
+
+    # no need for this anymore! 
+    match $spans.0 {
+        # fish completes commits and branch names in a nicer way
+        git => $fish_completer
+        # carapace doesn't have completions for asdf
+        asdf => $fish_completer
+        _ => $carapace_completer
+    } | do $in $spans
+```
+
+<details>
+    <summary>Full implementation of <code>fish-completer</code> from the cookbook.</summary>
+
+```nushell
+def fish-completer [spans: list<string>] {
+	^fish --command $"complete '--do-complete=($spans | str replace --all "'" "\\'" | str join ' ')'"
+	| from tsv --flexible --noheaders --no-infer
+	| rename value description
+	| update value {|row|
+		let value = $row.value
+		let need_quote = ['\' ',' '[' ']' '(' ')' ' ' '\t' "'" '"' "`"] | any { $in in $value }
+		if ($need_quote and ($value | path exists)) {
+			let expanded_path = if ($value starts-with ~) { $value | path expand --no-symlink } else { $value }
+			$'"($expanded_path | str replace --all "\"" "\\\"")"'
+		} else { $value }
+	}
+}
+```
+
+</details>
+
 ### Add `$nu.is-lsp` to help with printing in lsp mode ([#16635])
 When nushell is launched with the `--lsp` flag, nushell will set `$nu.is-lsp` to true so that users can programmatically know when nushell is in LSP mode.
 
@@ -594,31 +708,6 @@ The `str length` command now has a `--chars` flag to allow you to count characte
   5
 ```
 
-### Simple syntax for simple completions ([#16789])
-
-Custom completions are powerful, able to provide dynamic completions based on what's written on the command line so far.
-
-But you don't always need that power. In fact, for most cases a simple static list of options is enough.
-
-To make it simpler and more concise to meet this need, this release adds a new way to define completions for command parameters:
-```ansi:no-line-numbers
-def go [
-    direction: string@[ left up right down ]
-] {
-    $direction
-}
-```
-
-Completions can be provided as a list of strings inline in the command signature, or stored in a `const` variable and used like that. 
-```ansi:no-line-numbers
-const directions = [ left up right down ]
-
-def go [ direction: string@$directions ] {
-    $direction
-}
-```
-
-
 ### Streams of Streams ([#16735])
 
 When you run `each` over a list (or stream), it can only return a single item for each input. When we need to create multiple values from a single input, we can just return a list in the closure and run the output through `flatten`.
@@ -682,96 +771,6 @@ def slow-source [range: range] {
 </tbody>
 </table>
 
-### Command-wide completion handler ([#16765])
-
-There is big difference between custom completions that can be specified in a command's signature, and the "global" external completer (`$env.config.completions.external.completer`).
-
-The former is added to individual parameters, while the latter provides completions for all arguments of (external) commands.
-
-This makes using custom commands that wrap external commands awkward. The global external completer won't provide completions for the wrapper command and adding completions to that command uses a completely different API. It would be nice to be able to use the external completer's API for custom completions, or use the external completer for wrapper commands...
-
-#### `@complete external`
-
-Now it's possible to explicitly enable the global external completer for `extern` and custom command `def`initions:
-
-```nushell
-@complete external
-def --wrapped jc [...args] {
-    ^jc ...$args | from json
-}
-```
-
-#### `@complete <completer>`
-
-Instead of using the external completer, command-wide custom completers can be used for specific commands:
-
-```nushell
-def carapace-completer [spans: list<string>] {
-    ^carapace ..
-}
-
-@complete carapace-completer
-def --env get-env [name] { $env | get $name }
-
-@complete carapace-completer
-def --env set-env [name, value] { load-env { $name: $value } }
-
-@complete carapace-completer
-def --env unset-env [name] { hide-env $name }
-```
-
-Combined with `extern` definitions, this makes it trivial to use specific completion sources for specific commands:
-
-```nushell
-def fish-completer [spans: list<string>] {
-	^fish ..
-}
-
-@complete fish-completer
-extern git []
-
-@complete fish-completer
-extern asdf []
-```
-
-Yes, you can remove the `match` expression from your external completer!
-
-```nushell
-{|spans: list<string>|
-
-    # ...
-
-    # no need for this anymore! 
-    match $spans.0 {
-        # fish completes commits and branch names in a nicer way
-        git => $fish_completer
-        # carapace doesn't have completions for asdf
-        asdf => $fish_completer
-        _ => $carapace_completer
-    } | do $in $spans
-```
-
-<details>
-    <summary>Full implementation of <code>fish-completer</code> from the cookbook.</summary>
-
-```nushell
-def fish-completer [spans: list<string>] {
-	^fish --command $"complete '--do-complete=($spans | str replace --all "'" "\\'" | str join ' ')'"
-	| from tsv --flexible --noheaders --no-infer
-	| rename value description
-	| update value {|row|
-		let value = $row.value
-		let need_quote = ['\' ',' '[' ']' '(' ')' ' ' '\t' "'" '"' "`"] | any { $in in $value }
-		if ($need_quote and ($value | path exists)) {
-			let expanded_path = if ($value starts-with ~) { $value | path expand --no-symlink } else { $value }
-			$'"($expanded_path | str replace --all "\"" "\\\"")"'
-		} else { $value }
-	}
-}
-```
-
-</details>
-
 ### The `to md` command now always returns valid Markdown tables ([#16681])
 Previously, a command like this:
 ```shell
@@ -922,6 +921,14 @@ Error: nu::parser::invalid_binary_string
 
 ## Bug fixes
 
+### Aliases are now expanded before being sent to external completers ([#16640])
+
+Before this change, when an external completer was invoked for an alias, the first argument sent to the completer would be the alias itself instead of the aliased command.
+
+For example, with an alias defined as `alias gl = git log`, typing `gl branch_name` and pressing `TAB` would send the arguments `gl`, `log`, `branch_name` to the external completer.
+
+After this change, the alias is expanded and the arguments sent to the external completer will be `git`, `log`, `branch_name`.
+
 ### Discard `path add` input ([#16606])
 Previously `path add` (from `std/util`) could fail if it was fed `any` input.
 ```ansi:no-line-numbers
@@ -946,14 +953,6 @@ Now any input to `path add` will be discarded. It's still possible to pass it wi
 [a b c] | each {|p| $env.HOME | path join $p } | path add $in
 ```
 
-### Aliases are now expanded before being sent to external completers ([#16640])
-
-Before this change, when an external completer was invoked for an alias, the first argument sent to the completer would be the alias itself instead of the aliased command.
-
-For example, with an alias defined as `alias gl = git log`, typing `gl branch_name` and pressing `TAB` would send the arguments `gl`, `log`, `branch_name` to the external completer.
-
-After this change, the alias is expanded and the arguments sent to the external completer will be `git`, `log`, `branch_name`.
-
 ### Fixed IR evaluation error caused by redirecting output of branched blocks ([#16676])
 
 The following commands will no longer raise ir-eval errors: