CHANGELOG: editing for upcoming 3.0

[ci skip]

CHANGELOG.md

@@ -1,101 +1,96 @@
 # fish 3.0b1
 
-fish 3.0 is a major release which brings with it both improvements in functionality and some breaking changes. All fish scripts should be reviewed
-
-## Deprecations
-- The `IFS` variable is deprecated and will be removed in fish 4.0 (#4156).
-- The `function --on-process-exit` event will be removed in future (#4700). Use the `fish_exit` event instead.
-- `$_` is deprecated and will removed in the future (#813). Use `status current-command` in a subshell instead.
-- `^` as a redirection deprecated and will be removed in the future. (#4394). Use `2>` to redirect stderr. This is controlled by the `stderr-nocaret` feature flag.
-- `?` as a glob is deprecated and will be removed in the future. (#4520). This is controlled by the `qmark-noglob` feature flag.
+fish 3 is a major release, which introduces some breaking changes alongside improved functionality. Although most existing scripts will continue to work, they should be reviewed against the list below.
 
 ## Notable non-backward compatible changes
-- `%` is no longer used for process and job expansion, except for `%self` which is retained. Some commands have been wrapped to still understand process expansion, including `bg`, `fg` and `kill` (#4230, #1202)
-- Incoming environment variables are no longer split into arrays based on RS. Instead, variables are not split, unless their name ends in PATH, in which case they are split on colons. (#436)
-- A literal `{}` now expands to itself, rather than nothing. This makes working with `find -exec` easier. (#1109, #4632)
-- Successive commas in brace expansions are handled in less surprising manner (`{,,,}` expands to four empty strings rather than an empty string, a comma and an empty string again). (#3002, #4632).
+-  Process and job expansion has largely been removed. `%` will no longer perform these expansions, except for `%self` for the PID of the current shell. Additionally, job management commands (`disown`, `wait`, `bg`, `fg` and `kill`) will expand job specifiers starting with `%` (#4230, #1202).
+- `set x[1] x[2] a b`, to set multiple elements of an array at once, is no longer valid syntax (#4236).
+- A literal `{}` now expands to itself, rather than nothing. This makes working with `find -exec` easier (#1109, #4632).
+- Successive commas in brace expansions are handled in less surprising manner. For example, `{,,,}` expands to four empty strings rather than an empty string, a comma and an empty string again (#3002, #4632).
 - `for` loop control variables are no longer local to the `for` block (#1935).
 - Variables set in `if` and `while` conditions are available outside the block (#4820).
 - Local exported (`set -lx`) vars are now visible to functions (#1091).
-- `set x[1] x[2] a b` is no longer valid syntax (#4236).
 - The new `math` builtin (see below) does not support logical expressions; `test` should be used instead (#4777).
-- Range expansion (`$foo[1..5]`) will now always go forward if only the end is negative, and in reverse if just the start is. This is to enable clamping to the last valid index without changing direction if the list has fewer elements than expected.
-- Background jobs not first `disown`'d will be reaped upon `exec`, bringing the behavior in line with that of `exit`.
+- Range expansion will now behave sensibly when given a single positive and negative index (`$foo[5..-1]` or `$foo[-1..5]`), clamping to the last valid index without changing direction if the list has fewer elements than expected.
 - `read` now uses `-s` as short for `--silent` (à la `bash`); `--shell`'s abbreviation (formerly `-s`) is now `-S` instead (#4490).
-- `cd` no longer resolves symlinks. fish now maintains a virtual path, matching other shells. (#3350).
+- `cd` no longer resolves symlinks. fish now maintains a virtual path, matching other shells (#3350).
 - `source` now requires an explicit `-` as the filename to read from the terminal (#2633).
+- Arguments to `end` are now errors, instead of being silently ignored.
+- The names `argparse`, `read`, `set`, `status`, `test` and `[` are now reserved and not allowed as function names. This prevents users unintentionally breaking stuff (#3000).
+- The `fish_user_abbreviations` variable is no longer used; abbreviations will be migrated to the new storage format automatically.
+- The `FISH_READ_BYTE_LIMIT` variable is now called `fish_byte_limit` (#4414).
+- Environment variables are no longer split into arrays based on the record separator character on startup. Instead, variables are not split, unless their name ends in PATH, in which case they are split on colons (#436).
+
+## Deprecations
+
+With the release of fish 3, a number of features have been marked for removal in the future. All users are encouraged to explore alternatives. A small number of these features are currently behind feature flags, which are turned on at present but may be turned off by default in the future.
+
+A new feature flags mechanism is added for staging deprecations and breaking changes. Feature flags may be specified at launch with `fish --features ...` or by setting the universal `fish_features` variable. (#4940)
+
+- The use of the `IFS` variable for `read` is deprecated; `IFS` will be ignored in the future (#4156). Use the `read --delimiter` option instead.
+- The `function --on-process-exit` switch will be removed in future (#4700). Use the `fish_exit` event instead: `function --on-event fish_exit`.
+- `$_` is deprecated and will removed in the future (#813). Use `status current-command` in a command substitution instead.
+- `^` as a redirection deprecated and will be removed in the future. (#4394). Use `2>` to redirect stderr. This is controlled by the `stderr-nocaret` feature flag.
+- `?` as a glob is deprecated and will be removed in the future (#4520). This is controlled by the `qmark-noglob` feature flag.
+- The `CMD_DURATION` variable should be used as `cmd_duration`, although both versions are available for now.
 
 ## Notable fixes and improvements
-### Syntax/semantic changes and new builtins
-- fish now supports `&&`, `||`, and `!` (#4620).
+### Syntax changes and new commands
+- fish now supports `&&` (like `and`), `||` (like `or`), and `!` (like `not`), for better migration from POSIX-compliant shells (#4620).
 - Variables may be used as commands (#154).
-- fish may be started in private mode via `fish --private` or `fish -P`. Private mode fish sessions do not have access to the history file and any commands evaluated in private mode are not persisted for future sessions. A session variable `$fish_private_mode` can be queried to detect private mode and adjust the behavior of scripts accordingly to respect the user's wish for privacy.
-- A new feature flags mechanism is added for staging deprecations and breaking changes. Feature flags may be specified at launch with `fish --features ...` or by setting the universal `fish_features` variable. (#4940)
-- `wait` builtin is added for waiting on processes (#4498).
+- fish may be started in private mode via `fish --private`. Private mode fish sessions do not have access to the history file and any commands evaluated in private mode are not persisted for future sessions. A session variable `$fish_private_mode` can be queried to detect private mode and adjust the behavior of scripts accordingly to respect the user's wish for privacy.
+- A new `wait` command for waiting on backgrounded processes (#4498).
 - `math` is now a builtin rather than a wrapper around `bc` (#3157). The default scale is now 6, so that floating point computations produce decimals (#4478).
-- Using a read-only variable in a for loop is now an error. Note that this never worked. It simply failed to set the for loop var and thus silently produced incorrect results (#4342).
-- Arguments to `end` are now errors, instead of being silently ignored.
-- Setting `$PATH` no longer warns on non-existent directories, allowing for a single $PATH to be shared across machines (e.g. via dotfiles).
-- A pipe at the end of a line now allows the job to continue on the next line (#1285).
-- The names `argparse`, `read`, `set`, `status`, `test` and `[` are now reserved and not allowed as function names. This prevents users unintentionally breaking stuff (#3000).
-- `while` sets `$status` to a more useful value (#4982)
-- Command substitution output is now limited to 10 MB by default (#3822).
-- The machine hostname, where available, is now exposed as `$hostname` which is now a reserved variable. This drops the dependency on the `hostname` executable (#4422).
-- The universal variables file no longer contains the MAC address. It is now at the fixed location `.config/fish/fish_variables` (#1912).
+- Setting `$PATH` no longer warns on non-existent directories, allowing for a single $PATH to be shared across machines (eg via dotfiles) (#2969).
+- `while` sets `$status` to a non-zero value if the loop is not executed (#4982).
+- Command substitution output is now limited to 10 MB by default, controlled by the `fish_read_limit` variable (#3822).
+- The machine hostname, where available, is now exposed as the `$hostname` reserved variable. This removes the dependency on the `hostname` executable (#4422).
 - Bare `bind` invocations in config.fish now work. The `fish_user_key_bindings` function is no longer necessary, but will still be executed if it exists (#5191).
-- `$fish_pid` and `$last_pid` are available as an alternatives to `%self` and `%last`.
+- `$fish_pid` and `$last_pid` are available as replacements for `%self` and `%last`.
 
-### New features in builtins
-- `alias` now has a `-s` and `--save` option to save the function generated by the alias using `funcsave` (#4878).
-- `bind` has a new `--silent` option to ignore bind requests for named keys not available under the current `$TERMINAL` (#4188, #4431).
-- `complete` now has a `-k` and `--keep-order` option to keep the order of the `OPTION_ARGUMENTS` (#361).
-- `exec` now triggers the same safety features as `exit` and prompts for confirmation if background jobs are running.
-- `funced` now has a `-s` and `--save` option to automatically save the edited function after successfully editing (#4668).
-- `functions --handlers` can be used to show event handlers (#4694).
-- The `-d` option to `functions` to set the description of an existing function now works; before 3.0 it was documented but unimplemented. Note that the long form `--description` continues to work. (#5105)
+### New features in commands
+- `alias` has a new `--save` option to save the generated function immediately (#4878).
+- `bind` has a new `--silent` option to ignore bind requests for named keys not available under the current terminal (#4188, #4431).
+- `complete` has a new `--keep-order` option to show the provided or dynamically-generated argument list in the same order as specified, rather than alphabetically (#361).
+- `exec` prompts for confirmation if background jobs are running.
+- `funced` has a new `--save` option to automatically save the edited function after successfully editing (#4668).
+- `functions` has a new ` --handlers` option to show functions registered as event handlers (#4694).
 - `history search` supports globs for wildcard searching (#3136).
-- The `jobs` builtin now has a `-q` and `--quiet` option to silence the output.
-- `read` has a new `--delimiter` option as a better alternative to the `IFS` variable (#4256).
-- `read` writes directly to stdout if called without arguments (#4407)
-- `read` can now read one or more individual lines from the input stream without consuming the input in its entirety via `read -L/--line`. Refer to the `read` documentation for more info.
-- `set` has a new `--append` and `--prepend` option (#1326).
+- `jobs` has a new `--quiet` option to silence the output.
+- `read` has a new `--delimiter` option for splitting input into arrays (#4256).
+- `read` writes directly to stdout if called without arguments (#4407).
+- `read` can now read individual lines into separate variables without consuming the input in its entirety via the new `/--line` option.
+- `set` has new `--append` and `--prepend` options (#1326).
 - `set` has a new `--show` option to show lots of information about variables (#4265).
-- `string match` with an empty pattern and "--entire" in glob mode now matches everything instead of nothing (#4971).
-- `string split` supports `-n/--no-empty` to exclude empty strings from the result (#4779).
-- `string` builtin has new commands `split0` and `join0` for working with NUL-delimited output.
-- `string` can now read NULs via stdin, and will no longer stop processing text after them (#4605)
+- `string match` with an empty pattern and `--entire` in glob mode now matches everything instead of nothing (#4971).
+- `string split` supports a new `--no-empty` option to exclude empty strings from the result (#4779).
+- `string` has new subcommands `split0` and `join0` for working with NUL-delimited output.
+- `string` no longer stops processing text after NUL characters (#4605)
 - `test` now supports floating point values in numeric comparisons.
 
-### Performance improvements
-- `abbr` has been reimplemented to be faster. This means the old `fish_user_abbreviations` variable is ignored (#4048).
-- Setting variables is much faster (#4200, #4341).
-- Globs are faster (#4579).
-- `string` reads from stdin faster by a factor of 10 (#4610).
-- Slicing $history (in particular, `$history[1]` for the last executed command) is much faster.
-
-### Interactive improvements and completions
+### Interactive improvements
+- A pipe at the end of a line now allows the job to continue on the next line (#1285).
 - Italics and dim support out of the box on macOS for Terminal.app and iTerm (#4436).
 - `cd` tab completions no longer descend into the deepest unambiguous path (#4649).
 - `sudo` completions now provide completions for the target of the sudo command.
 - Pager navigation has been improved. Most notably, moving down now wraps around, moving up from the commandline now jumps to the last element and moving right and left now reverse each other even when wrapping around (#4680).
 - Typing normal characters while the completion pager is active no longer shows the search field. Instead it enters them into the command line, and ends paging (#2249).
-- A new input binding `pager-toggle-search` toggles the search field in the completions pager on and off. By default this is bound to control-s.
+- A new input binding `pager-toggle-search` toggles the search field in the completions pager on and off. By default, this is bound to Ctrl-S.
 - Searching in the pager now does a full fuzzy search (#5213).
 - The pager will now show the full command instead of just its last line if the number of completions is large (#4702).
 - Tildes in file names are now properly escaped in completions (#2274).
-- Wrapping completions (from `complete -w` or `function -w`) can now inject arguments. For example, `complete gco -w 'git checkout'` now works properly (#1976). The `alias` function has been updated to respect this behavior.
+- Wrapping completions (from `complete --wraps` or `function --wraps`) can now inject arguments. For example, `complete gco --wraps 'git checkout'` now works properly (#1976). The `alias` function has been updated to respect this behavior.
 - Path completions now support expansions, meaning expressions like `python ~/<TAB>` now provides file suggestions just like any other relative or absolute path. (This includes support for other expansions, too.)
 - Autosuggestions try to avoid arguments that are already present in the command line.
-- Notification about crashed processes is now always shown, even in command substitutions (#4962).
+- Notifications about crashed processes are now always shown, even in command substitutions (#4962).
 - The screen is no longer reset after a BEL, fixing graphical glitches (#3693).
 - vi-mode now supports ';' and ',' motions. This introduces new {forward,backward}-jump-till and repeat-jump{,-reverse} bind functions (#5140).
 - The `*y` vi-mode binding now works (#5100).
-- Truecolor is now enabled in neovim by default (#2792).
-- Terminal size ($COLUMNS/$LINES) is now updated before fish_prompt is called, allowing the prompt to react (improves #904).
+- True color is now enabled in neovim by default (#2792).
+- Terminal size variables (`$COLUMNS`/`$LINES`) is now updated before fish_prompt is called, allowing the prompt to react (#904).
 - Multi-line prompts no longer repeat when the terminal is resized (#2320).
-- `xclip` support in the clipboard integration (#5020).
-- $cmd_duration is no longer updated when no command is executed (#5011).
-
+- `xclip` support has been added to the clipboard integration (#5020).
+- `$cmd_duration` is no longer reset when no command is executed (#5011).
 - Added completions for
   - `bd` (#4472)
   - `bower`
@@ -119,16 +114,18 @@ fish 3.0 is a major release which brings with it both improvements in functional
   - `unzip`
   - `xsv`
 - Lots of improvements to completions (especially `darcs` (#5112), `git` and `hg`).
-- Completions for `yarn` and `npm` now require the `all-the-package-names` NPM package for full
-  functionality.
+- Completions for `yarn` and `npm` now require the `all-the-package-names` NPM package for full functionality.
 - Completions for `bower` and `yarn` now require the `jq` utility for full functionality.
 - Improved French translations.
 
 ### Other fixes and improvements
-- Fish's internal wcwidth function has been updated to deal with newer unicode, and the width of some characters can be configured via the "$fish_ambiguous_width" (#5149) and "$fish_emoji_width" (#2652) variables.
+- Significant performance improvements to `abbr` (#4048), setting variables (#4200, #4341), globs (#4579), `string` reading from standard input - by a factor of 10 (#4610), and slicing history (in particular, `$history[1]` for the last executed command).
+- Fish's internal wcwidth function has been updated to deal with newer Unicode, and the width of some characters can be configured via the `fish_ambiguous_width` (#5149) and `fish_emoji_width` (#2652) variables.
 - Alternatively, a new build-time option INTERNAL_WCWIDTH can be used to use the system's wcwidth instead (#4816).
-- Fuzzy translations are no longer used as they often produced nonsense and could even trigger crashes (#4847).
-- /etc/paths is now parsed like macOS' path_helper would, fixing $PATH order (#4336, #4852).
+- `functions` correctly supports `-d` as the short form of `--description`. (#5105)
+- `/etc/paths` is now parsed like macOS' bash `path_helper`, fixing $PATH order (#4336, #4852) on macOS.
+- Using a read-only variable in a `for` loop produces an error, rather than silently producing incorrect results (#4342).
+- The universal variables filename no longer contains the hostname or MAC address. It is now at the fixed location `.config/fish/fish_variables` (#1912).
 
 --