You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`register` is now deprecated and will be removed in the next major release. Read this section for alternatives.
84
+
:::
85
+
86
+
We've changed the way plugins are managed in Nushell in this release. In 0.92 and earlier, plugins were added with `register`, e.g.:
87
+
88
+
```nushell
89
+
> register ~/.cargo/bin/nu_plugin_gstat
90
+
```
91
+
92
+
This ran the plugin to get the signatures of the commands it supports, and then did two things: it added them to your `$nu.plugin-file` (previously called `plugin.nu`), so that they would be ready next time `nu` is run without having to ask the plugin again, and it also added them to your scope so you could use them immediately. While this was convenient, it had the drawback of always running the plugin at parse time (see issue [#11923](https://github.com/nushell/nushell/issues/11923)), which was less than ideal.
93
+
94
+
We now have two commands to replace `register` that break this functionality into two steps:
95
+
96
+
1.[`plugin add`](#plugin-add-toc), a normal command, which runs the plugin to get command signatures and adds them to your `$nu.plugin-file`, replacing any existing plugin definition with the same name
97
+
2.[`plugin use`](#plugin-use-toc), a parser command, which loads the plugin command signatures from your `$nu.plugin-file` and makes them available in scope.
98
+
99
+
The previous example would now be equivalent to this, at the REPL:
100
+
101
+
```nushell
102
+
# Add the plugin's commands to your plugin cache file:
103
+
> plugin add ~/.cargo/bin/nu_plugin_gstat
104
+
105
+
# Load it into scope:
106
+
> plugin use gstat
107
+
```
108
+
109
+
Note that this _will not_ work in a script in this order, as `plugin use` is a [parser command](/book/thinking_in_nu.md#think-of-nushell-as-a-compiled-language) and would get evaluated first. If you would like to make sure a certain plugin is available in a script, there are a few options:
110
+
111
+
1. Prepare a plugin cache file in advance, and use `--plugin-config` with `plugin use`:
112
+
```nushell
113
+
plugin use --plugin-config /path/to/custom.msgpackz your_required_plugin
114
+
```
115
+
2. The same thing, but pass the `plugin config` to `nu`:
116
+
```nushell
117
+
nu --plugin-config /path/to/custom.msgpackz your-script.nu
118
+
```
119
+
3. Pass a NUON list to `--plugins` (new in 0.93) to `nu`, to use plugins without a cache file:
120
+
```nushell
121
+
nu --plugins '[/path/to/nu_plugin_your_required_plugin]' your-script.nu
122
+
123
+
# or you can use `to nuon` from inside nu:
124
+
let plugins = [
125
+
'/path/to/nu_plugin_foo'
126
+
'/path/to/nu_plugin_bar'
127
+
]
128
+
nu --plugins ($plugins | to nuon) your-script.nu
129
+
```
130
+
131
+
The last option will run the plugin to get signatures at startup, without modifying the user's cache file, and can even be used when `--no-config-file` is specified.
132
+
133
+
Finally, we have also added [`plugin rm`](#plugin-rm-toc), which removes a plugin from the cache file. This was something that previously needed to be done manually in a text editor, but is made possible by the new format.
134
+
135
+
## New plugin cache format [[toc](#table-of-content)]
136
+
137
+
::: warning Breaking change
138
+
See a full overview of the [breaking changes](#breaking-changes)
139
+
:::
140
+
141
+
The plugin cache format has been changed from the previous Nushell script format (containing a sequence of `register` commands) to a custom, declarative format based on [MessagePack](https://msgpack.org/) compressed with [brotli](https://github.com/google/brotli). This new format is called `msgpackz`, and the default plugin file is `plugin.msgpackz` instead of `plugin.nu`.
142
+
143
+
Your existing `plugin.nu` file will be automatically upgraded to `plugin.msgpackz` the first time version 0.93 runs.
144
+
145
+
The declarative format brings a number of benefits:
146
+
147
+
1. It can be edited more structurally, allowing us to replace the entire definition of one plugin at once, which is more logically consistent if a plugin removes commands from one version to the next, and also allowing us to support new commands like [`plugin rm`](#plugin-rm-toc).
148
+
2. It supports adding metadata about plugins as a whole rather than just the command signatures, if we need to.
149
+
3. It contains the Nushell version that generated it, allowing us to potentially fix issues between versions.
150
+
4. It fails gracefully - if something about a particular plugin can't be parsed because of a change to the serialization format, other plugins that don't have that issue can still load.
151
+
152
+
We chose to use compressed MessagePack because it is very fast to load, and the file is loaded every time `nu` starts, so with a lot of plugins or plugins that expose a lot of commands (e.g. the new `polars` plugin), this was a big problem for startup times in general.
153
+
154
+
The most significantly _breaking_ part of this breaking change is that the following is no longer possible:
155
+
156
+
```nushell
157
+
source $nu.plugin-file
158
+
```
159
+
160
+
You can use the [`plugin use`](#plugin-use-toc) command instead to (re-)load a specific plugin from the plugin cache file:
161
+
162
+
```nushell
163
+
> plugin use gstat
164
+
```
165
+
166
+
## Improved terminal interaction for plugins [[toc](#table-of-content)]
167
+
168
+
Plugins are now able to run over a UNIX domain socket or Windows named pipe instead of `stdin`/`stdout` if they support it ([#12448](https://github.com/nushell/nushell/pull/12448)). All Rust plugins support this mode by default, but it is optional; plugins written in other languages are not forced to implement this, and the stdio mode is still always attempted. The [feature is advertised as `LocalSocket`](/contributor-book/plugin_protocol_reference.md#localsocket-feature) and the upgrade is automatic when supported by the plugin and confirmed to be functional.
169
+
170
+
This frees up stdio for interaction with the user's terminal, which makes plugins that rely on that, including terminal UI plugins like @amtoine's [`nu_plugin_explore`](https://github.com/amtoine/nu_plugin_explore) simpler and more reliable to implement.
171
+
172
+
We also added [engine calls](/contributor-book/plugin_protocol_reference.md#enterforeground-engine-call) for moving the plugin into the terminal controlling (foreground) process group, mainly for Unix platforms. This was also necessary to fully support terminal UI plugins, after the last release's new persistence functionality caused plugins to run in a new, background process group by default.
173
+
70
174
## Hall of fame [[toc](#table-of-content)]
71
175
### Bug fixes [[toc](#table-of-content)]
72
176
Thanks to all the contributors below for helping us solve issues and bugs :pray:
@@ -84,10 +188,67 @@ Thanks to all the contributors below for helping us making the documentation of
84
188
As usual, new release rhyms with changes to commands!
85
189
86
190
### New commands [[toc](#table-of-content)]
191
+
192
+
#### `plugin add`[[toc](#table-of-content)]
193
+
194
+
Adds a plugin to the plugin cache file (default `$nu.plugin-path`).
Replaces part of `register`, but can be used as a normal command, so it can be used within a script on a generated path. For example the following is now possible:
207
+
208
+
```nushell
209
+
glob ~/.cargo/bin/nu_plugin_* | each { |file| plugin add $file }
210
+
```
211
+
212
+
#### `plugin rm`[[toc](#table-of-content)]
213
+
214
+
Removes a plugin from the plugin cache file (default `$nu.plugin-path`).
The commands will still remain in scope, but will not be present the next time `nu` is started.
222
+
223
+
#### `plugin use`[[toc](#table-of-content)]
224
+
225
+
Loads a plugin from the plugin cache file (default `$nu.plugin-path`) **at parse time**.
226
+
227
+
This replaces the other part of `register` - actually adding the commands to scope. It does not run the plugin executable, though, it just loads the [previously added](#plugin-add-toc) commands from the cache file.
228
+
87
229
### Changes to existing commands [[toc](#table-of-content)]
This command is deprecated in favor of the new [`plugin add`](#plugin-add-toc) and [`plugin use`](#plugin-use-toc) commands. See the [relevant section](#redesigned-plugin-management-commands-toc) for the reasoning behind this change.
235
+
89
236
### Removed commands [[toc](#table-of-content)]
90
237
238
+
## For plugin developers [[toc](#table-of-content)]
239
+
240
+
### New protocol features [[toc](#table-of-content)]
241
+
242
+
-[`LocalSocket`: local socket mode.](/contributor-book/plugin_protocol_reference.md#localsocket-feature) Added in PR [#12448](https://github.com/nushell/nushell/pull/12448).
243
+
244
+
### New engine calls [[toc](#table-of-content)]
245
+
246
+
See the [Rust docs for `EngineInterface`](https://docs.rs/nu-plugin/0.93.0/nu_plugin/struct.EngineInterface.html) for specific documentation for Rust plugins.
247
+
248
+
-[`GetSpanContents`: view the source code of a span.](/contributor-book/plugin_protocol_reference.md#getspancontents-engine-call) Added in PR [#12439](https://github.com/nushell/nushell/pull/12439).
249
+
-[`EnterForeground`: enter the terminal controlling (foreground) process group.](/contributor-book/plugin_protocol_reference.md#enterforeground-engine-call) Added in PR [#12448](https://github.com/nushell/nushell/pull/12448).
250
+
-[`LeaveForeground`: leave the foreground process group.](/contributor-book/plugin_protocol_reference.md#leaveforeground-engine-call) Added in PR [#12448](https://github.com/nushell/nushell/pull/12448).
251
+
91
252
<!-- NOTE: to start investigating the contributions of last release, i like to list them all in a raw table.
92
253
to achieve this, one can use the [`list-merged-prs` script from `nu_scripts`](https://github.com/nushell/nu_scripts/blob/main/make_release/release-note/list-merged-prs)
0 commit comments