Skip to content

Conversation

@patrick-motard
Copy link

Problem

Users find it difficult to discover key bindings for choose modes (choose-tree, choose-buffer, choose-client, customize-mode) without consulting the manual.

Fixes #4357

Solution

Add an F1 key binding that displays a help menu showing all available key bindings in choose modes. The menu lists navigation, selection, tagging, searching, and sorting keys.

Key Choice

F1 was chosen because the more intuitive alternatives are already in use:

  • h - Used for collapse/left navigation (same as Left arrow)
  • ? - Used for forward search (same as /)
  • H - Used in window-tree.c to jump to the current pane ("Home")

F1 is a conventional help key that doesn't conflict with existing bindings.

Testing

  1. Start tmux: tmux new-session
  2. Enter choose-tree mode: Ctrl+b w
  3. Press F1 to see the help menu
  4. Press q or Escape to close the help menu

@nicm
Copy link
Member

nicm commented Dec 7, 2025

Thanks:

  • Can you make it C-h as well as F1 like emacs?

  • This is not much use if nobody knows about it, so can you add it to tmux.1?

  • I think if this is going to be a menu then choosing an item should execute the command as if the key was pressed. If must be static then it should be a popup not a menu.

@patrick-motard
Copy link
Author

I can add those. Thanks for the review!

@nicm
Copy link
Member

nicm commented Jan 6, 2026

Are you still working on this?

@patrick-motard
Copy link
Author

Screen.Recording.2026-01-05.at.11.13.33.PM.mov

Add F1 key binding to display a help menu showing available key bindings
in choose modes (choose-tree, choose-buffer, choose-client, customize-mode).

The help menu displays all common key bindings for navigation, selection,
tagging, searching, and sorting, making it easier to discover available
functionality without consulting the manual.

Fixes tmux#4357
@patrick-motard patrick-motard force-pushed the pmotard/add-help-key-to-choose-modes branch from 5d7b0fb to c807f69 Compare January 6, 2026 05:14
@patrick-motard
Copy link
Author

patrick-motard commented Jan 6, 2026

Sorry for the delay. Let me know if this is what you had in mind.

@patrick-motard
Copy link
Author

  1. C-h key binding - Added alongside F1
  2. Popup instead of menu - Help now displays as a static popup that closes on any key
  3. Documentation in tmux.1 - Added F1/C-h help entries to all four choose modes (choose-tree, choose-client, choose-buffer, customize-mode)

@nicm
Copy link
Member

nicm commented Jan 6, 2026

Thanks.

I actually liked the menu, it just needed to execute the command when you chose it :-).

But a popup is OK instead, but we can't run cat just to show some output.

Please take a look at this which adds a way to directly write into a popup: help.diff.txt

I also added some formatting to the text.

The only problem now is that this is only the common keys, it doesn't include stuff like D in client mode, or f or e in buffer mode. I would probably fix this by just allowing a mode to completely replace the text, so adding a callback like:

struct window_mode {
...
    const char* (*help_text)(u_int *width, u_int *height, size_t *size);
...
}

I don't see any need to get complicated and try to merge common and individual mode help, I think we just copy the common keys into each one.

@nicm
Copy link
Member

nicm commented Jan 13, 2026

Did you get a chance to look at my changes? Do you want to work on this further or shall I do it?

@patrick-motard
Copy link
Author

I can get this over the finish line. My availability comes in small batches. I'll take  look at the code you shared. I can update it to be an interactive menu that executes selected commands.

@nicm
Copy link
Member

nicm commented Jan 15, 2026

Good stuff, thanks. I don't mind if it is a menu or a popup, I think it looks OK as a popup the way I have it. But it should include the commands that are special to each mode.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

FR: make key bindings for choose-tree, choose-buffer, customize-mode, etc self-documenting

2 participants