= WeeChat Release Notes :author: Sébastien Helleu :email: flashcode@flashtux.org :lang: en :toc: left :docinfo1: This document lists important changes for each version, that require manual actions. It is recommended to read it when upgrading to a new stable version. + For a complete list of changes, please look at ChangeLog. [[v4.1.0]] == Version 4.1.0 (under dev) [[v4.1.0_fset_allowed_values]] === Allowed values for options on fset buffer A new variable `allowed_values` has been added in fset options. The default value for the second format has changed. + You can reset it with this command: ---- /reset fset.format.option2 ---- [[v4.1.0_fset_mouse]] === Mouse actions on fset buffer Mouse actions on fset buffer has been fixed when option `fset.look.format_number` is set to 2. The key for button 1 on fset buffer has been fixed. + You can reset it with this command: ---- /reset weechat.key_mouse.@chat(fset.fset):button1 ---- [[v4.0.1]] == Version 4.0.1 (2023-06-30) [[v4.0.1_config_set_plugin]] === Functions config_set_plugin and config_set_desc_plugin The functions link:https://weechat.org/doc/weechat/plugin/#_config_set_plugin[config_set_plugin] and link:https://weechat.org/doc/weechat/plugin/#_config_set_desc_plugin[config_set_desc_plugin] are not converting any more the option name to lower case because since version 4.0.0, the name of options is case sensitive. [[v4.0.1_grab_raw_key]] === Grab raw key and command Key kbd:[Alt+K] (upper case) has been removed, as well as commands `/input grab_raw_key` and `/input grab_raw_key_command`. Now the key kbd:[Alt+k] displays the actual key name and command, possibly raw key. [[v4.0.0]] == Version 4.0.0 (2023-06-24) This is a major version that includes breaking changes described below. [[v4.0.0_irc_capabilities]] === Support of new IRC capabilities Support of new capabilities has been introduced in this version and are all enabled by default, if the server supports them: * batch * draft/multiline * echo-message When the capability "echo-message" is enabled, you may notice time before your own IRC messages are displayed in the buffer, this is normal : the capability forces the server to sent back messages, and WeeChat displays messages only when they are received from the server. If you want to disable this capability on all servers, you can do: ---- /set irc.server_default.capabilities "*,!echo-message" ---- If you are already connected to a server with echo-message enabled, just ask the server to disable the capability on-the-fly (no need to reconnect): ---- /cap req -echo-message ---- [[v4.0.0_config_files]] === Configuration file version A version has been introduced in configuration file, and due to the many breaking changes (listed in the chapters below), the following files are automatically upgraded to a new version: - weechat.conf: new key names (see <>) - alias.conf: aliases converted to lower case (see <>) - irc.conf: options "ssl*" renamed to "tls*" (see <>) - relay.conf: options and protocol "ssl*" renamed to "tls*" (see <>) [WARNING] Because of this new format, you must *NOT* load the new configuration files in any older WeeChat version < 4.0.0 once you have run any version ≥ 4.0.0 at least one time. + For example the new key names make the input completely broken (you can not enter most chars in input any more and Enter key does not work). [[v4.0.0_key_bindings_improvements]] === Key bindings improvements The format of key bindings has changed to be more user-friendly, and this is a breaking change: legacy keys are automatically converted, but some triggers, plugins or scripts might need manual changes. Overview of new features: - use of alias for keys (`meta-left` instead of `meta2-1;3D`) - use comma to separate keys in combos (`meta-w,meta-up` instead of `meta-wmeta-meta2-A`) - control keys are converted to lower keys (`ctrl-a` instead of `ctrl-A`) - keys are normal options, so they are shown and can be updated with `/set` and `/fset` commands - command `/key` without arguments opens the fset buffer with all keys See https://specs.weechat.org/specs/2023-002-key-bindings-improvements.html[Key bindings improvements specification] for more information. [[v4.0.0_new_key_format]] ==== New key format Aliases are now used for keys, like `f1`, `home`, `return`, etc. + In addition, a comma is now required between different keys, for example `ctrl-cb` is not valid any more and must be replaced by `ctrl-c,b`. The keys in weechat.conf are automatically converted from legacy format on first run or upgrade with a legacy configuration file. For keys bound in external plugins or scripts, WeeChat tries to convert them on-the-fly to stay compatible, but this can not work in all cases (this is a breaking change). The following fixes are done on keys when they are defined: - transform upper case ctrl keys to lower case - replace space char by `space` - replace `meta2-` by `meta-[` (modifier `meta2-` doesn't exist any more) - mouse modifiers are now in this order: `alt-` then `ctrl-`. A warning is displayed when a raw key or invalid key is added. + For example `meta-[A` (which should be `up`) or `ctrl-ca` (missing comma, it should be `ctrl-c,a`). [[v4.0.0_grab_raw_key]] ==== Grab raw key and command New key kbd:[Alt+K] (upper case) is added to grab raw key and its command. Most of times this command is not needed, and the existing key kbd:[Alt+k] (lower case) is preferred, as it returns the key using the new aliases. For example: - key kbd:[Alt+k] then up arrow displays: `up /input history_previous` - key kbd:[Alt+K] then up arrow displays: `meta-[A` Raw keys have higher priority than key with alias (they are looked first); they can still be used and bound, but this is not recommended. + They should be used only in case of problem with the new aliases or with your terminal. [[v4.0.0_ctrl_keys_lower_case]] ==== Control keys as lower case Keys using the kbd:[Ctrl] key and a letter are now automatically converted to lower case. + That means for example keys `ctrl-q` and `ctrl-Q` are the same and saved as `ctrl-q` (lower case). Example of key being automatically converted to lower case: ---- /key bind ctrl-Q /print test ---- Output is now: ---- New key binding (context "default"): ctrl-q => /print test ---- With older releases, upper case was mandatory and lower case letter for control keys were not working at all. [[v4.0.0_case_sensitive_identifiers]] === Case sensitive identifiers Many identifiers are made case sensitive, including among others: - configuration files, sections, options - commands, aliases - completion (except nick completion) - bars, bar items - colors - filters - IRC servers - scripts - triggers. See https://specs.weechat.org/specs/2023-001-case-sensitive-identifiers.html[Case sensitive identifiers specification] for more information. Accordingly, default aliases are now in lower case. + All aliases (default ones and those added manually) are automatically converted to lower case with a message like this one: ---- Alias converted to lower case: "CLOSE" => "close" ---- [[v4.0.0_tls]] === TLS options and connections Option `weechat.color.status_name_insecure` has been added, the buffer name is now displayed with color `lightmagenta` by default if the connection with the server is *NOT* made with TLS. Options, commands and documentation have been updated to "TLS" instead of "SSL": * core option: ** weechat.color.status_name_ssl -> weechat.color.status_name_tls * IRC server default options: ** irc.server_default.ssl -> irc.server_default.tls ** irc.server_default.ssl_cert -> irc.server_default.tls_cert ** irc.server_default.ssl_dhkey_size -> irc.server_default.tls_dhkey_size ** irc.server_default.ssl_fingerprint -> irc.server_default.tls_fingerprint ** irc.server_default.ssl_password -> irc.server_default.tls_password ** irc.server_default.ssl_priorities -> irc.server_default.tls_priorities ** irc.server_default.ssl_verify -> irc.server_default.tls_verify * IRC options for a specific server: ** irc.server.xxx.ssl -> irc.server.xxx.tls ** irc.server.xxx.ssl_cert -> irc.server.xxx.tls_cert ** irc.server.xxx.ssl_dhkey_size -> irc.server.xxx.tls_dhkey_size ** irc.server.xxx.ssl_fingerprint -> irc.server.xxx.tls_fingerprint ** irc.server.xxx.ssl_password -> irc.server.xxx.tls_password ** irc.server.xxx.ssl_priorities -> irc.server.xxx.tls_priorities ** irc.server.xxx.ssl_verify -> irc.server.xxx.tls_verify * Relay options: ** relay.network.ssl_cert_key -> relay.network.tls_cert_key ** relay.network.ssl_priorities -> relay.network.tls_priorities * Relay: ** protocol `ssl` -> `tls` * Relay command: ** `/relay sslcertkey` -> `/relay tlscertkey` Default value of option `irc.server_default.tls` is now `on`. + Connection to IRC servers is done with TLS and port 6697 by default. For example to create libera.chat server, using TLS (if option `irc.server_default.tls` is `on`) and default port 6697: ---- /server add libera irc.libera.chat irc: server added: libera -> irc.libera.chat/6697 (TLS: enabled) ---- To force non-TLS connection (with default port 6667): ---- /server add libera irc.libera.chat -notls irc: server added: libera -> irc.libera.chat/6667 (TLS: disabled) ---- [[v4.0.0_insert_multiple_pasted_lines]] === Insert of multiple pasted lines in input By default multiple pasted lines are now inserted in input and not sent immediately. To enable this feature, the default value of option `weechat.look.paste_max_lines` has been changed to `100` (it was `1`). + If needed, you can reset the option to the new default value after upgrade: ---- /reset weechat.look.paste_max_lines ---- The option `weechat.look.paste_auto_add_newline` has been removed. [[v4.0.0_default_triggers]] === Default triggers The default triggers "cmd_pass", "cmd_pass_register" and "server_pass" have been updated to be compatible with multiline input. You can restore these default triggers with the following command: ---- /trigger restore cmd_pass cmd_pass_register server_pass ---- [[v4.0.0_build]] === Build [[v4.0.0_build_autotools]] ==== Autotools The autotools support for build of WeeChat has been removed. + WeeChat must now be built with CMake. [[v4.0.0_build_doc]] ==== Documentation The auto-generated files for documentation are now built with `weechat-headless`, after compilation of WeeChat and the plugins (the files are not in repository any more). + This implies all plugins must be compiled and loaded in order to have complete docs (User's guide and Plugin API reference). If ever you want to disable some plugins and force the build of incomplete docs, a new option has been added: `ENABLE_DOC_INCOMPLETE` (`OFF` by default). For example if you disable PHP plugin but still want docs where PHP options, commands, etc. are missing: ---- cmake .. -DENABLE_PHP=OFF -DENABLE_DOC=ON -DENABLE_DOC_INCOMPLETE=ON ---- [[v4.0.0_packaging]] === Packaging [[v4.0.0_packaging_tarballs]] ==== Tarballs The command `make dist` now builds only `.gz` and `.xz` compressed tarballs. + Formats `.bz2` and `.zst` are not built any more. [[v4.0.0_packaging_rpm]] ==== RPM packaging The file `weechat.spec` used for RPM packaging has been removed. + openSUSE has its own here: https://build.opensuse.org/package/view_file/server:irc/weechat/weechat.spec?expand=1 [[v4.0.0_packaging_cpack]] ==== cpack The configuration for cpack has been removed. + It was used to build binary package of WeeChat, which has never been released in this format. [[v4.0.0_bar_new]] === Function bar_new When the bar name already exists, the API function link:https://weechat.org/doc/weechat/plugin/#_bar_new[bar_new] returns the pointer to the bar (instead of NULL) and sets the default value for all options with the values received. + If you don't want to set default values in an existing bar, it is recommended to first check if the bar exists with the API function link:https://weechat.org/doc/weechat/plugin/#_bar_search[bar_search]. [[v3.8]] == Version 3.8 (2023-01-08) [[v3.8_command_input_options]] === Move of options out of command /input Some options of `/input` command have been moved to other commands (they can still be used with `/input` but marked as deprecated and completion has been removed): [width="100%",cols="4m,4m,3",options="header"] |=== | Old command | New command | Default key | /input jump_smart | /buffer jump smart | kbd:[Alt+a] | /input jump_previously_visited_buffer | /buffer jump prev_visited | kbd:[Alt+<] | /input jump_next_visited_buffer | /buffer jump next_visited | kbd:[Alt+>] | /input jump_last_buffer_displayed | /buffer jump last_displayed | kbd:[Alt+/] | /input hotlist_clear | /hotlist clear | kbd:[Alt+h], kbd:[Alt+c] | /input hotlist_remove_buffer | /hotlist remove | kbd:[Alt+h], kbd:[Alt+m] | /input hotlist_restore_buffer | /hotlist restore | kbd:[Alt+h], kbd:[Alt+r] | /input hotlist_restore_all | /hotlist restore -all | kbd:[Alt+h], kbd:[Alt+Shift+R] | /input set_unread | /allbuf /buffer set unread | kbd:[Ctrl+s], kbd:[Ctrl+u] | /input set_unread_current_buffer | /buffer set unread | (none) | /input switch_active_buffer | /buffer switch | kbd:[Ctrl+x] | /input switch_active_buffer_previous | /buffer switch -previous | (none) | /input zoom_merged_buffer | /buffer zoom | kbd:[Alt+x] |=== The following default keys can be reset to use the new command: ---- /key reset meta-a /key reset meta-< /key reset meta-> /key reset meta-/ /key reset meta-hmeta-c /key reset meta-hmeta-m /key reset meta-hmeta-r /key reset meta-hmeta-R /key reset ctrl-Sctrl-U /key reset ctrl-X /key reset meta-x ---- [[v3.8_return_code_string_comparison_functions]] === Return code of string comparison functions The following functions now return arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1: * string_charcmp * string_charcasecmp * string_charcasecmp_range * string_strcasecmp * string_strcasecmp_range * string_strncasecmp * string_strncasecmp_range * string_strcmp_ignore_chars In addition, the case conversion has been extended, now in addition to range A-Z, all chars that have a lower case version are handled. + That means for example the case insensitive comparison of "é" and "É" is 0 (chars are considered equal). Example with WeeChat 3.8: [source,c] ---- int diff = string_strcasecmp ("aaa", "CCC"); /* == -2 */ ---- With older releases: [source,c] ---- int diff = string_strcasecmp ("aaa", "CCC"); /* == -1 */ ---- [[v3.8_api_string_lower_upper]] === API functions string_tolower and string_toupper The functions link:https://weechat.org/doc/weechat/plugin/#_string_tolower[string_tolower] and link:https://weechat.org/doc/weechat/plugin/#_string_toupper[string_toupper] now return newly allocated string instead of doing the change in place. + The returned string must then be freed after use. [[v3.8_trigger_regex_command]] === Trigger regex command The trigger regex now starts with a command, which is "s" (regex replace, default) or "y" (translate chars). For compatibility, any regex starting with a delimiter different from a letter will still work. If you defined some triggers with a regex starting with a letter (used as delimiter), then you must change them *before* upgrading WeeChat, otherwise they'll be lost after upgrade (with an error when WeeChat tries to load them from configuration file). For example this regex is now invalid: ---- XabcXdefX ---- And must be replaced by: ---- sXabcXdefX ---- For more information on the regex format, see the trigger chapter in the _WeeChat User's guide_. [[v3.8_remove_python2_support]] === Remove Python 2 support The CMake option `ENABLE_PYTHON2` and autotools option `--enable-python2` have been removed, and WeeChat can not be compiled with Python 2.x any more. [[v3.8_config_new_option_callbacks]] === Callbacks of function config_new_option The two callbacks "callback_change" and "callback_delete" in scripting API function config_new_option have been changed: an integer return value was expected by error, now any return value is ignored (like it has always been in the C API). [[v3.7.1]] == Version 3.7.1 (2022-10-21) Bug fix and maintenance release. [[v3.7]] == Version 3.7 (2022-10-09) [[v3.7_upgrade_new_callback_object_id]] === Argument "object_id" in callback of upgrade_new In all script languages (except PHP), the argument "object_id" sent to the callback of "upgrade_new" is now an integer (it was a string in older releases). To be compatible with all versions, it is recommended to convert the argument to integer before testing it, for example in Python: [source,python] ---- if int(object_id) == 1: # ... ---- [[v3.7_hook_timer_callback_remaining_calls]] === Argument "remaining_calls" in callback of hook_timer In all script languages (except PHP), the argument "remaining_calls" sent to the callback of "hook_timer" is now an integer (it was a string in older releases). To be compatible with all versions, it is recommended to convert the argument to integer before testing it, for example in Python: [source,python] ---- if int(remaining_calls) > 0: # ... ---- [[v3.7_delete_previous_word_whitespace]] === Delete previous word until whitespace A new parameter `delete_previous_word_whitespace` has been added in `/input` command to delete previous word until backspace. + This is now bound by default to the key kbd:[Ctrl+w] (see issue #559). A new key kbd:[Alt+Backspace] has been added to delete word, like kbd:[Ctrl+w] did in previous releases. You can get the new behavior for kbd:[Ctrl+w] with this command: ---- /key bind ctrl-W /input delete_previous_word_whitespace ---- And add the new key kbd:[Alt+Backspace] with this command: ---- /key missing ---- [[v3.7_api_string_rebuild_split_string]] === Function string_rebuild_split_string The API function string_build_with_split_string has been renamed to link:https://weechat.org/doc/weechat/plugin/#_string_rebuild_split_string[string_rebuild_split_string] and two new arguments have been added: _index_start_ and _index_end_. To stay compatible, the existing calls to the function must be done with the new function name and these values: * _index_start_: `0` * _index_end_: `-1` [[v3.6]] == Version 3.6 (2022-07-10) [[v3.6_hook_print_empty_messages]] === Hook print on empty messages The "hook_print" callback is now called even when an empty message is displayed (with or without prefix). This was a bug, but is mentioned here just in case some scripts callbacks would be surprised to be called with such empty messages. [[v3.6_trigger_beep]] === Default trigger "beep" The command of "beep" trigger is now executed only if the buffer notify is NOT set to `none` (in addition to existing conditions). You can restore the default trigger "beep" with the following command: ---- /trigger restore beep ---- [[v3.5]] == Version 3.5 (2022-03-27) [[v3.5_relay_weechat_compression_zstd]] === Compression "zstandard" in relay Relay of type "weechat" now offers a compression with https://facebook.github.io/zstd/[Zstandard], which allows better compression and is much faster than zlib for both compression and decompression. The new compression type is `zstd`, and the default compression is now `off` instead of `zlib`: the compression must now be explicitly given in the link:https://weechat.org/doc/weechat/relay/#command_handshake[handshake] command. The option `compression` in link:https://weechat.org/doc/weechat/relay/#command_handshake[init] command has been removed, it is now ignored and must be given in the link:https://weechat.org/doc/weechat/relay/#command_handshake[handshake] command (it was deprecated since WeeChat 2.9). The option relay.network.compression_level has been renamed to relay.network.compression and is now a percentage between `0` and `100`: * `0`: disable compression * `1`: low compression (fast) * `100`: best compression (slow) [[v3.4.1]] == Version 3.4.1 (2022-03-13) Bug fix and maintenance release. [[v3.4]] == Version 3.4 (2021-12-18) [[v3.4_default_triggers]] === Default triggers The existing triggers "cmd_pass" and "cmd_pass_register" have been updated to hide key and password in command `/msg nickserv setpass ` and support the option `-server `. You can restore the default triggers with the following command: ---- /trigger restore cmd_pass cmd_pass_register ---- [[v3.4_hdata_search]] === New parameters in function hdata_search New parameters have been added in function link:https://weechat.org/doc/weechat/plugin/#_hdata_search[hdata_search], used for the evaluation of expression. New parameters are the same as function link:https://weechat.org/doc/weechat/plugin/#_string_eval_expression[string_eval_expression]: * pointers: hashtable with pointers (pointers) * extra_vars: hashtable with extra variables (strings) * options: hashtable with options (strings). The following scripts are updated consequently to be compatible with all WeeChat versions: * https://weechat.org/scripts/source/autoauth.py/[autoauth.py] 1.3 * https://weechat.org/scripts/source/buffer_open.py/[buffer_open.py] 0.3 * https://weechat.org/scripts/source/collapse_channel.py/[collapse_channel.py] 0.9 * https://weechat.org/scripts/source/grep_filter.py/[grep_filter.py] 0.11 * https://weechat.org/scripts/source/samechannel.rb/[samechannel.rb] 0.2 * https://weechat.org/scripts/source/soju.py/[soju.py] 0.1.4 * https://weechat.org/scripts/source/stalker.pl/[stalker.pl] 1.6.3 [[v3.4_hdata_arrays]] === Static array support in hdata Support of static array in hdata has been added. For pointers to arrays, a prefix `*,` must be added in parameter `array_size` of API function link:https://weechat.org/doc/weechat/plugin/#_hdata_new_var[hdata_new_var]. [[v3.3]] == Version 3.3 (2021-09-19) [[v3.3_hotlist_keys_clear_restore]] === New keys for hotlist New keys have been added to manipulate the hotlist: * kbd:[Alt+h], kbd:[Alt+c]: clear the whole hotlist (former key: kbd:[Alt+h]) * kbd:[Alt+h], kbd:[Alt+m]: mark the current buffer as read by removing it from the hotlist * kbd:[Alt+h], kbd:[Alt+r]: restore latest hotlist removed in the current buffer * kbd:[Alt+h], kbd:[Alt+Shift+R]: restore latest hotlist removed in all buffers You can add them with the following command: ---- /key missing ---- Since the key kbd:[Alt+h] has been moved to kbd:[Alt+h], kbd:[Alt+c], you must manually remove the old key: ---- /key unbind meta-h ---- [[v3.3_typing_bar_item]] === Bar item "typing" A bar item called "typing" has been added to status bar by default. It is used to display users that are currently typing a message on the current IRC channel or private buffer. If you want to display typing notifications in the status bar, add `,[typing]` in your option weechat.bar.status.items. [[v3.3_ordered_hashtables]] === Ordered hashtables Hashtables entries are now ordered by creation date, the following functions are now returning entries sorted by insertion order: * hashtable_map * hashtable_map_string * hashtable_get_string (all properties except "keys_sorted" and "keys_values_sorted") * hashtable_add_to_infolist [[v3.3_irc_default_capabilities]] === IRC default capabilities All supported capabilities are now enabled by default if the server support them: * account-notify * away-notify * cap-notify * chghost * extended-join * invite-notify * message-tags * multi-prefix * server-time * setname * userhost-in-names Two new options have been added and enabled by default to customize the behavior of capabilities "account-notify" and "extended-join": * irc.look.display_account_message: display ACCOUNT messages received * irc.look.display_extended_join: display extended join info in the JOIN messages: account name and real name The default value of option irc.server_default.capabilities is now `*` which means that all capabilities supported by both WeeChat and the server are enabled by default. After upgrade, to enable all capabilities and remove custom capabilities you have set, you can do: ---- /set irc.server_default.capabilities "*" /unset irc.server.example.capabilities ---- You can also explicitly disable some capabilities with this syntax (see `/help irc.server_default.capabilities`): ---- /set irc.server_default.capabilities "*,!away-notify,!extended-join" ---- [[v3.3_irc_sasl_blowfish_aes]] === IRC SASL DH-BLOWFISH and DH-AES mechanisms removed The SASL mechanisms DH-BLOWFISH and DH-AES have been removed, because they are insecure and already removed from most IRC servers. + If you were using one of these mechanisms, it is highly recommended to switch to any other supported SASL mechanism. For example: ---- /set irc.server.example.sasl_mechanism scram-sha-256 ---- [[v3.2.1]] == Version 3.2.1 (2021-09-04) Bug fix and maintenance release. [[v3.2]] == Version 3.2 (2021-06-13) [[v3.2_xdg_directories]] === XDG directories Support of XDG directories has been added. For compatibility, if the XDG directories are not found but `~/.weechat` exists, this single directory is used for all files. If you want to switch to XDG directories, you must create and move manually all files in the appropriate directories. + See https://specs.weechat.org/specs/001285-follow-xdg-base-dir-spec.html#weechat-home[WeeChat XDG specification] for more information. Some options have new default value: `%h` is replaced by `${weechat_xxx_dir}`. + If you didn't change the value, it is recommended to set the new default value, by doing `/unset