aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-08-17 13:17:54 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-08-17 13:17:54 -0400
commit7587dd3aaf7aa477935fa6badf679203a4f279ba (patch)
treeb5c0043c9463b7c11c8b9b2232cdbede2f9a9bbe
parentupdate changelog (diff)
downloadtmux-toggle-term-7587dd3aaf7aa477935fa6badf679203a4f279ba.zip
Add ability to use prefix key with key bindingsv0.3.0
-rw-r--r--CHANGELOG.md6
-rw-r--r--README.md27
-rwxr-xr-xplugin.tmux36
-rwxr-xr-xscripts/tmux.sh17
-rwxr-xr-xscripts/toggle-term.sh17
-rw-r--r--tests/tests.sh118
6 files changed, 200 insertions, 21 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd2433a..ecf2b71 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.3.0] - 2025-08-17
+
+### Added
+
+- Ability to change key bindings and use a prefix key.
+
## [0.2.1] - 2025-08-17
### Fixed
diff --git a/README.md b/README.md
index 7020efe..d253e2e 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ A terminal toggle for tmux that supports a per-window split pane and a global fl
Using [TPM](https://github.com/tmux-plugins/tpm):
```tmux
-set -g @plugin 'https://git.sr.ht/~eugenetriguba/tmux-toggle-term'
+set-option -g @plugin 'https://git.sr.ht/~eugenetriguba/tmux-toggle-term'
```
Reload tmux and press prefix + I to install.
@@ -26,13 +26,32 @@ Reload tmux and press prefix + I to install.
![Floating Window](./docs/float-open.webp)
-### Customization
+## Customization
-If needed, you can override the default keybindings by setting the
-`toggle-term-split-key` and `toggle-term-float-key` options.
+### Custom Key Bindings
+
+You can override the default keybindings by setting the
+`toggle-term-split-key` and `toggle-term-float-key` options:
```tmux
set -g @toggle-term-split-key 'M-t'
set -g @toggle-term-float-key 'M-f'
```
+### Using Tmux Prefix Keys
+
+By default, the plugin binds keys don't require the tmux prefix. If you prefer to
+use the tmux prefix key, you can enable it by setting the use-prefix options:
+
+```tmux
+set -g @toggle-term-float-key 'f'
+set -g @toggle-term-float-use-prefix 'true'
+
+set -g @toggle-term-split-key ';'
+set -g @toggle-term-split-use-prefix 'true'
+```
+
+With the above configuration:
+- **Prefix + f** → Toggle floating terminal
+- **Prefix + ;** → Toggle split terminal
+
diff --git a/plugin.tmux b/plugin.tmux
index cae2ea5..32ff62e 100755
--- a/plugin.tmux
+++ b/plugin.tmux
@@ -2,31 +2,59 @@
# vi: ft=sh
set -e
-CURRENT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CURRENT_DIR="$(dirname "$0")"
+. "$CURRENT_DIR/scripts/tmux.sh"
+
SCRIPTS_DIR="${CURRENT_DIR}/scripts"
FLOAT_KEYBINDING="C-f"
FLOAT_KEYBINDING_OPTION="@toggle-term-float-key"
+FLOAT_USE_PREFIX_OPTION="@toggle-term-float-use-prefix"
+
SPLIT_KEYBINDING="C-\;"
SPLIT_KEYBINDING_OPTION="@toggle-term-split-key"
+SPLIT_USE_PREFIX_OPTION="@toggle-term-split-use-prefix"
main() {
- tmux bind-key -n "$(float_key)" run-shell -b "$SCRIPTS_DIR/toggle-term.sh float"
- tmux bind-key -n "$(split_key)" run-shell -b "$SCRIPTS_DIR/toggle-term.sh split"
+ tmux_cmd="$(get_tmux_cmd)"
+
+ float_key_binding="$(float_key)"
+ if [ "$(use_prefix_for_float)" = "true" ]; then
+ $tmux_cmd bind-key "$float_key_binding" run-shell -b "$SCRIPTS_DIR/toggle-term.sh float"
+ else
+ $tmux_cmd bind-key -n "$float_key_binding" run-shell -b "$SCRIPTS_DIR/toggle-term.sh float"
+ fi
+
+ split_key_binding="$(split_key)"
+ if [ "$(use_prefix_for_split)" = "true" ]; then
+ $tmux_cmd bind-key "$split_key_binding" run-shell -b "$SCRIPTS_DIR/toggle-term.sh split"
+ else
+ $tmux_cmd bind-key -n "$split_key_binding" run-shell -b "$SCRIPTS_DIR/toggle-term.sh split"
+ fi
}
float_key() {
get_tmux_option "$FLOAT_KEYBINDING_OPTION" "$FLOAT_KEYBINDING"
}
+use_prefix_for_float() {
+ get_tmux_option "$FLOAT_USE_PREFIX_OPTION" "false"
+}
+
split_key() {
get_tmux_option "$SPLIT_KEYBINDING_OPTION" "$SPLIT_KEYBINDING"
}
+use_prefix_for_split() {
+ get_tmux_option "$SPLIT_USE_PREFIX_OPTION" "false"
+}
+
get_tmux_option() {
option="$1"
default_value="$2"
- option_value=$(tmux show-option -gqv "$option")
+ tmux_cmd=$(get_tmux_cmd)
+
+ option_value=$($tmux_cmd show-option -gqv "$option")
if [ -z "$option_value" ]; then
echo "$default_value"
else
diff --git a/scripts/tmux.sh b/scripts/tmux.sh
new file mode 100755
index 0000000..b919043
--- /dev/null
+++ b/scripts/tmux.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+
+get_tmux_cmd() {
+ TMUX_CMD="tmux"
+ # The script supports targeting a different tmux socket
+ # or configuration file solely for testing purposes. This
+ # allows isolation between the tmux installation on the host
+ # and the tmux session for the test run.
+ if [ -n "${TMUX_SOCKET:-}" ]; then
+ if [ -n "${TMUX_CONFIG_PATH:-}" ]; then
+ TMUX_CMD="tmux -f $TMUX_CONFIG_PATH -L $TMUX_SOCKET"
+ else
+ TMUX_CMD="tmux -L $TMUX_SOCKET"
+ fi
+ fi
+ echo "$TMUX_CMD"
+}
diff --git a/scripts/toggle-term.sh b/scripts/toggle-term.sh
index cd2e5c1..0cc7414 100755
--- a/scripts/toggle-term.sh
+++ b/scripts/toggle-term.sh
@@ -1,20 +1,11 @@
#!/bin/sh
-TMUX_CMD="tmux"
+CURRENT_DIR="$(dirname "$0")"
+. "$CURRENT_DIR/tmux.sh"
+
POPUP_SESSION_NAME="popup"
main() {
- # The script supports targeting a different tmux socket
- # or configuration file solely for testing purposes. This
- # allows isolation between the tmux installation on the host
- # and the tmux session for the test run.
- if [ -n "${TMUX_SOCKET:-}" ]; then
- if [ -n "${TMUX_CONFIG_PATH:-}" ]; then
- TMUX_CMD="tmux -f $TMUX_CONFIG_PATH -L $TMUX_SOCKET"
- else
- TMUX_CMD="tmux -L $TMUX_SOCKET"
- fi
- fi
-
+ TMUX_CMD=$(get_tmux_cmd)
# Modes:
# float → global floating window
# split → per-window split pane
diff --git a/tests/tests.sh b/tests/tests.sh
index 99706dd..bf9204e 100644
--- a/tests/tests.sh
+++ b/tests/tests.sh
@@ -4,6 +4,7 @@ load '../vendor/bats-support/load'
load '../vendor/bats-assert/load'
TOGGLE_TERM_SCRIPT_PATH="$BATS_TEST_DIRNAME/../scripts/toggle-term.sh"
+PLUGIN_SCRIPT_PATH="$BATS_TEST_DIRNAME/../plugin.tmux"
setup() {
export TMUX_SOCKET="test$$"
@@ -43,6 +44,32 @@ tmux_is_zoomed() {
fi
}
+tmux_set_option() {
+ option="$1"
+ value="$2"
+ tmux -f "$TMUX_CONFIG_PATH" -L "$TMUX_SOCKET" set-option -g "$option" "$value"
+}
+
+tmux_get_key_bindings() {
+ tmux -f "$TMUX_CONFIG_PATH" -L "$TMUX_SOCKET" list-keys 2>/dev/null | grep "toggle-term" || echo ""
+}
+
+tmux_has_prefix_binding() {
+ key="$1"
+ mode="$2"
+ tmux_get_key_bindings | grep -q "bind-key.*-T prefix.*${key}.*toggle-term.sh $mode"
+}
+
+tmux_has_root_binding() {
+ key="$1"
+ mode="$2"
+ tmux_get_key_bindings | grep -q "bind-key.*-T root.*\"*${key}\"*.*toggle-term.sh $mode"
+}
+
+load_plugin() {
+ "$PLUGIN_SCRIPT_PATH"
+}
+
@test 'split creates a new pane' {
assert_equal "$(tmux_pane_count)" 1
assert_equal "$(tmux_active_panes)" '1'
@@ -67,3 +94,94 @@ tmux_is_zoomed() {
assert_equal "$(tmux_active_panes)" '1-0'
assert_equal "$(tmux_is_zoomed)" 'true'
}
+
+@test 'plugin loads with default key bindings' {
+ run load_plugin
+ assert_success
+
+ run tmux_has_root_binding "C-f" "float"
+ assert_success
+ run tmux_has_root_binding "C-;" "split"
+ assert_success
+}
+
+@test 'custom float key without prefix works' {
+ tmux_set_option "@toggle-term-float-key" "M-f"
+
+ run load_plugin
+ assert_success
+
+ run tmux_has_root_binding "M-f" "float"
+ assert_success
+}
+
+@test 'custom split key without prefix works' {
+ tmux_set_option "@toggle-term-split-key" "M-t"
+
+ run load_plugin
+ assert_success
+
+ run tmux_has_root_binding "M-t" "split"
+ assert_success
+}
+
+@test 'float key with prefix enabled' {
+ tmux_set_option "@toggle-term-float-key" "f"
+ tmux_set_option "@toggle-term-float-use-prefix" "true"
+
+ run load_plugin
+ assert_success
+
+ run tmux_has_prefix_binding "f" "float"
+ assert_success
+ run tmux_has_root_binding "f" "float"
+ assert_failure
+}
+
+@test 'split key with prefix enabled' {
+ tmux_set_option "@toggle-term-split-key" "s"
+ tmux_set_option "@toggle-term-split-use-prefix" "true"
+
+ run load_plugin
+ assert_success
+
+ run tmux_has_prefix_binding "s" "split"
+ assert_success
+ run tmux_has_root_binding "s" "split"
+ assert_failure
+}
+
+@test 'mixed prefix configuration works' {
+ tmux_set_option "@toggle-term-float-key" "f"
+ tmux_set_option "@toggle-term-float-use-prefix" "true"
+ tmux_set_option "@toggle-term-split-key" "C-t"
+ tmux_set_option "@toggle-term-split-use-prefix" "false"
+
+ run load_plugin
+ assert_success
+
+ run tmux_has_prefix_binding "f" "float"
+ assert_success
+ run tmux_has_root_binding "f" "float"
+ assert_failure
+
+ run tmux_has_root_binding "C-t" "split"
+ assert_success
+ run tmux_has_prefix_binding "C-t" "split"
+ assert_failure
+}
+
+@test 'prefix options default to false' {
+ run load_plugin
+ assert_success
+
+ run tmux_has_root_binding "C-f" "float"
+ assert_success
+ run tmux_has_root_binding "C-;" "split"
+ assert_success
+
+ run tmux_has_prefix_binding "C-f" "float"
+ assert_failure
+ run tmux_has_prefix_binding "C-;" "split"
+ assert_failure
+}