feat(tmux): new completion #1364

dseomn · 2025-04-10T22:27:56Z

From tmux/tmux#259 it doesn't look like the tmux maintainers were interested in having a bash completion script in the upstream repo. However, I added license headers to put these new files under either bash-completion's license or tmux's, in case they want it there in the future.

I'm aware of a handful of existing tmux bash completion scripts, below. As far as I can tell, they all hard-code a decent amount of tmux's available options, commands, etc. Some are also abandoned and out of date with more recent versions of tmux. Rather than base this code off of those, I decided to implement completion using tmux's own introspection commands as much as possible. Hopefully that will reduce the ongoing maintenance work and make it stay up to date with most tmux changes automatically.

This commit has a relatively minimal set of completions, see the TODO in _comp_cmd_tmux__value(). I have code for more completions in varying states of readiness, but this commit is already pretty large. I'll make follow-up PR(s) for those.

I'm willing to maintain this script. (And I'm hoping that the design mentioned above will make that easier.)

Existing implementations that I'm aware of:

test/t/test_tmux.py

dseomn · 2025-04-15T01:46:14Z

At a glance, the test failure looks unrelated. Let me know if I need to do anything about it?

akinomyoga

The general quality of this PR seems very good, but I'm busy this week. I'll look at this later.

completions/tmux

dseomn · 2025-04-15T18:36:28Z

The general quality of this PR seems very good, but I'm busy this week. I'll look at this later.

Thanks, and no rush.

(In addition to the changes in comments above, I also added a new test test_parse_usage_alternative_options.)

scop

Looks good overall to me on a quick glance, thanks!

Left a few remarks, but I'll happily defer remainder of this review to someone else, as I don't use tmux myself (yet, anyway, I guess).

completions/tmux

scop · 2025-04-20T08:48:00Z

completions/tmux

+    case "$option_type" in
+        command)
+            _comp_compgen_split -l -- \
+                "$(LC_ALL=C tmux list-commands -F "#{command_list_name}")"


Would be good to pass around the original tmux command invoked instead of hardcoding just tmux from $PATH (or as an alias or a function) -- tmux might not be in $PATH (or the like) in the first place, or the tmux there might not be the one that was invoked (maybe another one with a full path to it was).

To add more context, one simple way is to use "$1" (at the top-level function) or "${comp_args[0]}" (in the helper functions that are called from the top-level function). A more robust way is to use _comp_dequote "${comp_args[0]}" as _comp_compgen_help__get_help_lines is doing:

bash-completion/bash_completion

Lines 1561 to 1569 in 90162b0

local REPLY

_comp_dequote "${comp_args[0]-}" || REPLY=${comp_args[0]-}

help_cmd=("${REPLY:-false}" "$@")

;;

esac

local REPLY

_comp_split -l REPLY "$(LC_ALL=C "${help_cmd[@]}" 2>&1)" &&

_lines=("${REPLY[@]}")

Note: I try to slightly change the behavior of _comp_dequote in 3e088b7 (PR #1357), so that one does not need to prefix || REPLY=${comp_args[0]-}.

After checking the implementation, I think maybe we can just use this function _comp_compgen_help__get_help_lines for broader purposes (with a small adjustment). Even with the current implementation, we can use _comp_compgen_help__get_help_lines for the present purpose in the following way:

_comp_compgen_help__get_help_lines -- list-commands -F "#{command_list_name}" && REPLY=("${_lines[@]}") && _comp_compgen -- -W '"${REPLY[@]}"'

Then, we may consider renaming this function to _comp_run_cmd and change its output variable from _lines to REPLY.

_comp_compgen_help__get_help_lines is private, so I shouldn't use it as is, right?

Should I wait for changes to _comp_compgen_help__get_help_lines and/or _comp_dequote, or use "${comp_args[0]}" / "$1" for now?

_comp_compgen_help__get_help_lines is private, so I shouldn't use it as is, right?

Yes, so I wrote

Then, we may consider renaming this function to _comp_run_cmd and change its output variable from _lines to REPLY.

Should I wait for changes to _comp_compgen_help__get_help_lines and/or _comp_dequote, or use "${comp_args[0]}" / "$1" for now?

You can change _comp_compgen_help__get_help_lines if other maintainers agree with it.

Ok, I'll wait a bit to see if @scop or others have opinions before changing this part.

I added _comp_cmd_tmux__run to do this without _comp_compgen_help__get_help_lines for now. Happy to switch to that later if maintainers want to rename it and make it public.

_comp_dequote "${comp_args[0]-}" || REPLY=${comp_args[0]-}

_comp_dequote's documentation says that REPLY is an array, so I didn't use that exactly. Should _comp_compgen_help__get_help_lines be changed too?

I also updated the semicolon detection to treat REPLY as an array too.

OK, I think we can update _comp_compgen_help__get_help_lines (_comp_run_cmd) in another PR.

Should _comp_compgen_help__get_help_lines be changed too?

Yeah, and it is actually addressed in 3e088b7 in #1357 (where REPLY is assigned after REPLY=()). It was actually a fix after the CI #2838 failure.

completions/tmux

dseomn · 2025-04-21T00:22:38Z

Thanks for the reviews! I'll try to get to these comments soon.

dseomn · 2025-04-22T19:58:16Z

Just FYI, tmux/tmux@68ffe65 will change some of the usage syntax in the next tmux release. The changes look relatively minor, and I'd like to support both the old and new syntaxes for at least a little while. And since this PR is already rather large, I'd like to go forward with this just supporting the syntax in released tmux versions, then make another PR adding support for the new changes, if that's ok.

akinomyoga · 2025-04-23T00:08:05Z

And since this PR is already rather large, I'd like to go forward with this just supporting the syntax in released tmux versions,

OK.

dseomn · 2025-04-26T16:07:53Z

I think I've addressed all the comments now, let me know if there's anything else I should change. (Or if I missed anything.)

In addition to changes from the comments, I also added one more test case that tmux/tmux#4480 reminded me about:

r"foo';'bar",  # semicolon doesn't need to be escaped in the middle

completions/tmux

From tmux/tmux#259 it doesn't look like the tmux maintainers were interested in having a bash completion script in the upstream repo. However, I added license headers to put these new files under either bash-completion's license or tmux's, in case they want it there in the future. I'm aware of a handful of existing tmux bash completion scripts, below. As far as I can tell, they all hard-code a decent amount of tmux's available options, commands, etc. Some are also abandoned and out of date with more recent versions of tmux. Rather than base this code off of those, I decided to implement completion using tmux's own introspection commands as much as possible. Hopefully that will reduce the ongoing maintenance work and make it stay up to date with most tmux changes automatically. This commit has a relatively minimal set of completions, see the TODO in _comp_cmd_tmux__value(). I have code for more completions in varying states of readiness, but this commit is already pretty large. I'll make follow-up PR(s) for those. I'm willing to maintain this script. (And I'm hoping that the design mentioned above will make that easier.) Existing implementations that I'm aware of: * https://github.com/Bash-it/bash-it/blob/master/completion/available/tmux.completion.bash * https://github.com/Boruch-Baum/tmux_bash_completion * https://github.com/imomaliev/tmux-bash-completion * scop#81 * https://github.com/srsudar/tmux-completion

akinomyoga

Thank you for all your investigation and updates! LGTM. The following points can be addressed later if necessary:

Move _comp_cmd_tmux__log to bash_completion with the name _comp_log
Update _comp_compgen_help__get_help_lines for more general use cases

dseomn · 2025-04-27T01:43:04Z

Since the CI tests are failing (hopefully to be fixed by #1373):

$ shellcheck completions/tmux && shfmt --diff completions/tmux && podman run --rm -ti -v ~/Code/bash-completion:/home/dseomn/bash-completion:ro localhost/dev-environment:latest bash -c 'cd bash-completion && pytest test/t/test_tmux.py'
===================================================================================================================================================================================== test session starts =====================================================================================================================================================================================
platform linux -- Python 3.13.2, pytest-8.3.5, pluggy-1.5.0
rootdir: /home/dseomn/bash-completion/test
configfile: setup.cfg
plugins: cov-5.0.0, typeguard-4.4.2
collected 34 items                                                                                                                                                                                                                                                                                                                                                                            

test/t/test_tmux.py ..................................                                                                                                                                                                                                                                                                                                                                  [100%]

====================================================================================================================================================================================== warnings summary =======================================================================================================================================================================================
../../../usr/lib/python3/dist-packages/_pytest/cacheprovider.py:475
  /usr/lib/python3/dist-packages/_pytest/cacheprovider.py:475: PytestCacheWarning: could not create cache path /home/dseomn/bash-completion/test/.pytest_cache/v/cache/nodeids: [Errno 30] Read-only file system: '/home/dseomn/bash-completion/test/pytest-cache-files-yf3g6vl0'
    config.cache.set("cache/nodeids", sorted(self.cached_nodeids))

../../../usr/lib/python3/dist-packages/_pytest/stepwise.py:51
  /usr/lib/python3/dist-packages/_pytest/stepwise.py:51: PytestCacheWarning: could not create cache path /home/dseomn/bash-completion/test/.pytest_cache/v/cache/stepwise: [Errno 30] Read-only file system: '/home/dseomn/bash-completion/test/pytest-cache-files-jy64przc'
    session.config.cache.set(STEPWISE_CACHE_DIR, [])

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
=============================================================================================================================================================================== 34 passed, 2 warnings in 13.75s ===============================================================================================================================================================================

(Ignore the Read-only file system warnings, that's just because I mounted the directory read-only.)

dseomn · 2025-04-28T18:34:54Z

Is there a style guide for the function documentation syntax that bash completion uses? I'm starting to work on the changes for tmux/tmux@68ffe65 and wrote the below for a new function. Is there a better way to say that $1 is the arg type and the rest of $@ is the command and its arguments?

# @param $@ the arg type of the command (e.g., command or shell-command), then
#     the command itself, then the arguments to the command, ending before the
#     current word to complete

akinomyoga · 2025-04-28T19:30:26Z

$1 is the arg type and the rest of $@ is the command and its arguments?

There isn't a precise documentation syntax because currently, no tools parse them (as discussed in #1343), but an existing use suggests $2... for the above use case:

bash-completion/bash_completion

Lines 3378 to 3386 in 1cdff0a

    
           # Function for loading and calling functions from dynamically loaded 
        
           # completion files that may not have been sourced yet. 
        
           # @param $1 completion file to load function from in case it is missing 
        
           # @param $2 the xfunc name.  When it does not start with `_', 
        
           #   `_comp_xfunc_${1//[^a-zA-Z0-9_]/_}_$2' is used for the actual name of the 
        
           #   shell function. 
        
           # @param $3... if any, specifies the arguments that are passed to the xfunc. 
        
           # @since 2.12 
        
           _comp_xfunc()

dseomn · 2025-05-09T19:45:21Z

What are the next steps for this PR? Is it just blocked on the CI being fixed?

akinomyoga · 2025-05-09T22:15:46Z

How about the situation with #1364 (comment)? I thought you planned to change it.

dseomn · 2025-05-09T22:45:31Z

Oh, sorry for the confusion. That question was about the follow-up that's blocked on this PR, not about this PR. Once this is merged I'll test the code that that question was about, and make another PR.

akinomyoga · 2025-05-09T23:01:20Z

Thanks!

dseomn · 2025-05-10T00:34:13Z

Thank you! I'll try to make the PR to update this for the latest unreleased version of tmux within the next few days.

the tmux bash completions are part of the bash-completions package now. See scop/bash-completion#1364

dseomn force-pushed the tmux branch from c1e913e to f315cde Compare April 10, 2025 22:38

dseomn commented Apr 10, 2025

View reviewed changes

test/t/test_tmux.py Outdated Show resolved Hide resolved

akinomyoga reviewed Apr 15, 2025

View reviewed changes

completions/tmux Outdated Show resolved Hide resolved

completions/tmux Outdated Show resolved Hide resolved

dseomn force-pushed the tmux branch from f315cde to 0ed8058 Compare April 15, 2025 18:30

scop requested changes Apr 20, 2025

View reviewed changes

akinomyoga reviewed Apr 20, 2025

View reviewed changes

completions/tmux Outdated Show resolved Hide resolved

completions/tmux Outdated Show resolved Hide resolved

completions/tmux Outdated Show resolved Hide resolved

completions/tmux Outdated Show resolved Hide resolved

completions/tmux Outdated Show resolved Hide resolved

dseomn mentioned this pull request Apr 21, 2025

Incorrect escaping in description of semicolons in shells? tmux/tmux#4480

Closed

dseomn force-pushed the tmux branch from 0ed8058 to 8b935e1 Compare April 22, 2025 19:28

dseomn force-pushed the tmux branch from 8b935e1 to 96c7c62 Compare April 26, 2025 15:51

akinomyoga approved these changes Apr 26, 2025

View reviewed changes

completions/tmux Outdated Show resolved Hide resolved

dseomn force-pushed the tmux branch from 96c7c62 to 2aa6779 Compare April 26, 2025 17:21

dseomn requested a review from scop April 26, 2025 17:24

akinomyoga reviewed Apr 26, 2025

View reviewed changes

completions/tmux Show resolved Hide resolved

dseomn force-pushed the tmux branch from 2aa6779 to 2048252 Compare April 26, 2025 21:06

dseomn mentioned this pull request Apr 26, 2025

no error message for invalid/unknown long options tmux/tmux#4491

Closed

akinomyoga reviewed Apr 26, 2025

View reviewed changes

completions/tmux Outdated Show resolved Hide resolved

dseomn force-pushed the tmux branch from 2048252 to 11aa059 Compare April 27, 2025 00:24

akinomyoga approved these changes Apr 27, 2025

View reviewed changes

akinomyoga approved these changes May 9, 2025

View reviewed changes

akinomyoga merged commit 1b87ff7 into scop:main May 9, 2025
1 of 7 checks passed

github-actions bot mentioned this pull request May 9, 2025

chore: release 2.17.0 #1298

Open

This was referenced May 12, 2025

Help maintaining imomaliev/tmux-bash-completion#13

Closed

imomaliev/tmux-bash-completion has been archived tmux/tmux#4504

Closed

dseomn deleted the tmux branch May 12, 2025 20:58

nephros pushed a commit to sailfishos-chum/tmux that referenced this pull request Sep 8, 2025

Add conflict with upstream bash completion

6553d4f

the tmux bash completions are part of the bash-completions package now. See scop/bash-completion#1364

	local REPLY
	_comp_dequote "${comp_args[0]-}" \|\| REPLY=${comp_args[0]-}
	help_cmd=("${REPLY:-false}" "$@")
	;;
	esac

	local REPLY
	_comp_split -l REPLY "$(LC_ALL=C "${help_cmd[@]}" 2>&1)" &&
	_lines=("${REPLY[@]}")

Uh oh!

feat(tmux): new completion #1364

feat(tmux): new completion #1364

Uh oh!

Conversation

dseomn commented Apr 10, 2025

Uh oh!

Uh oh!

dseomn commented Apr 15, 2025

Uh oh!

akinomyoga left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dseomn commented Apr 15, 2025

Uh oh!

scop left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

scop Apr 20, 2025

Choose a reason for hiding this comment

Uh oh!

akinomyoga Apr 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akinomyoga Apr 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dseomn Apr 21, 2025

Choose a reason for hiding this comment

Uh oh!

akinomyoga Apr 21, 2025

Choose a reason for hiding this comment

Uh oh!

dseomn Apr 22, 2025

Choose a reason for hiding this comment

Uh oh!

dseomn Apr 26, 2025

Choose a reason for hiding this comment

Uh oh!

akinomyoga Apr 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akinomyoga Apr 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dseomn commented Apr 21, 2025

Uh oh!

dseomn commented Apr 22, 2025

Uh oh!

akinomyoga commented Apr 23, 2025

Uh oh!

dseomn commented Apr 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

akinomyoga left a comment

Choose a reason for hiding this comment

Uh oh!

dseomn commented Apr 27, 2025

Uh oh!

dseomn commented Apr 28, 2025

Uh oh!

akinomyoga commented Apr 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

akinomyoga Apr 20, 2025 •

edited

Loading

akinomyoga Apr 20, 2025 •

edited

Loading

akinomyoga Apr 26, 2025 •

edited

Loading

akinomyoga Apr 26, 2025 •

edited

Loading

akinomyoga commented Apr 28, 2025 •

edited

Loading