2.2.5

Author: jaclu

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented here.
 
 ---
 
+## [2.2.5] - 2025-05-09
+
+### Added
+
+- New documentation: docs/SingleQuotes.md
+
+### Changed
+
+- Updated README.md to refer to docs/SingleQuotes.md when relevant
+
+---
+
 ## [2.2.4] - 2025-05-09
 
 ### Added

README.md

@@ -20,13 +20,12 @@ experienced users, then add more for newbies.
 
 ## Recent Changes
 
+- Added `docs/SingleQuotes.md` to explain some pitfalls of single quoted variables.
+- Now handles tmux 3.4 odd interpretation of `$HOME` inside single quotes
 - Prevent tmux variables from being expanded in `Display Menu Commands`
 - Moved Layouts and Split window into Windows menu
 - Main menu help displays kind of an about box info, about what version of the
   plugin is used
-- `Display menu commands` Rotates between displaying commands and all matching
-  prefix and root binds.
-- Added parameter `@menus_border_type` for Styling
 
 </details>
 <details>
@@ -172,17 +171,8 @@ The default trigger is `<prefix> \` The trigger is configured like this:
 set -g @menus_trigger 'Space'
 ```
 
-Note: Non-standard keys, such as the default backslash (`\`), must be prefixed with `\`
-(e.g., `\\`) to prevent confusion in tmux.
-
-Handling special keys becomes more complex when using quotes:
-
-- Inside single quotes, both `'\'` and `'\\'` work.
-- Inside double quotes, only `"\\"` is valid.
-
-To avoid unexpected errors when switching between quoting styles, it's recommended
-to always prefix special keys with `\` inside both single and double quotes,
-as well as when not using quotes.
+See [SingleQuotes](docs/SingleQuotes.md) for how to handle special chars like `\`
+in tmux variables.
 
 ### Display without using prefix
 
@@ -197,9 +187,12 @@ Use this in order to trigger menus without first hitting `<prefix>`
 ### Pointer to the config file
 
 ```tmux
-set -g @menus_config_file '~/.configs/tmux.conf'
+set -g @menus_config_file "~/.configs/tmux.conf"
 ```
 
+See [SingleQuotes](docs/SingleQuotes.md) for how to handle `$HOME` and `~`
+in tmux variables.
+
 In the main menu, the tmux config file to be reloaded.
 The default location for this is:
 
@@ -306,9 +299,12 @@ Per default logging is disabled. If this is desired, provide a log file name
 like this:
 
 ```tmux
-set -g @menus_log_file '~/tmp/tmux-menus.log'
+set -g @menus_log_file "~/tmp/tmux-menus.log"
 ```
 
+See [SingleQuotes](docs/SingleQuotes.md) for how to handle `$HOME` and `~`
+in tmux variables.
+
 ### Display menu commands
 
 ```tmux

docs/SingleQuotes.md

@@ -0,0 +1,67 @@
+# Quoting Pitfalls in Plugin Variable Assignments
+
+## `$HOME`, `~`, and Single Quotes
+
+A common but problematic habit is using single quotes when assigning plugin variables,
+especially with paths involving `$HOME` or `~`.
+
+Before tmux 3.0, tmux would automatically interpret paths like `'$HOME/some/path'`
+or `'~/some/path'` correctly—effectively converting them to `"$HOME/some/path"`
+behind the scenes.
+
+That changed starting with version 3.0:
+
+- `'$HOME/some/path'` is interpreted as `"\$HOME/some/path"`
+- `'~/some/path'` becomes `\~/some/path`
+
+In 3.4, `$HOME` became `"\\$HOME/some/path"` while `~` was still broken in the same way.
+As of 3.5, tmux reverted to the 3.0 behavior again.
+
+To work around this inconsistency, a helper—`fix_home_path()`—has been added.
+It detects the tmux version and rewrites broken single-quoted paths into their
+proper double-quoted form.
+
+While this provides some compatibility, **it’s still discouraged**. Most plugins
+do not account for these quirks, and relying on single quotes leads to broken
+behavior across versions.
+
+**Best practice:** Always wrap paths and variables like `$HOME` or `~` in
+double quotes. This ensures consistent, correct expansion in all tmux versions.
+
+---
+
+## Special Characters and Escaping
+
+Quoting also affects how special characters like the backslash (`\`) are parsed.
+
+- With no quoting, `\\` must be used
+- In _single quotes_, both `'\\'` and `'\'` can be used.
+- In _double quotes_, you must escape the backslash: `"\\"`.
+
+To avoid subtle quoting issues in key bindings or option values,
+**escape special characters consistently**, regardless of quoting style:
+
+- Use `\\` for a literal backslash
+- Avoid switching between single and double quotes unless necessary
+
+---
+
+## Examples
+
+**Incorrect (common mistakes):**
+
+```tmux
+set -g @plugin_path '$HOME/.tmux/plugins'
+set -g @plugin_path '~/plugins'
+set -g @my_key '\'  # unreliable in some quoting contexts
+```
+
+**Correct (portable and safe):**
+
+```tmux
+set -g @plugin_path "$HOME/.tmux/plugins"
+set -g @plugin_path "$HOME/plugins"
+set -g @my_key "\\" # explicit and unambiguous
+```
+
+These patterns behave consistently across tmux versions and quoting contexts.