[idea] Allow copy-mode keymaps to be configured.

[takaya-ishiyama]

idea / problem

Herdr lets users configure the keybinding that enters copy mode with keys.copy_mode, but the keybindings used inside copy mode are currently fixed.

For example, copy mode uses h/j/k/l for movement, w/b/e for word motions, { / } for paragraph movement, v or Space to start selection, y or Enter to copy, and q or Esc to exit.

This works well as a vi-style default, but it is hard to adapt for users who want different copy-mode bindings.

requested change

Allow copy-mode keymaps to be configured while preserving the current bindings as defaults.

why you want this

The default vi-style copy mode is a good starting point, but some keys are awkward depending on keyboard layout. For me, { and } are uncomfortable enough that I avoid using those motions.

Since Herdr already supports configurable keybindings elsewhere, I expected copy-mode actions to be configurable too. Keeping the current defaults while allowing remaps would make copy mode easier to use without changing behavior for existing users.

[shibayu36]

+1 to this proposal. I thought about a possible spec, so I would like to share it here.

Why I want this

In my case, I want to use emacs-style keybindings in copy mode, the same bindings I use in my other tools. Everyone prefers different keys, so if each action can be configured, this would cover a wide range of use cases.

Proposed spec

herdr already has a good precedent for this. In #193, the keys inside navigate mode became configurable as flat navigate_* fields under [keys]. The pattern is: defaults are kept, only the actions you write are overridden, and some keys such as Esc stay reserved. I think it is natural to add copy_mode_* fields for copy mode with the same pattern.

For copy mode, I think Esc is the only key that needs to stay reserved. Esc switches between two functions depending on context — it clears the selection or search if there is one, and exits otherwise — so it does not fit the one-action-per-field form. Keeping it out of the config also guarantees that you can always leave copy mode with Esc, no matter what settings are written. Every key other than Esc can be overridden or unbound as a default key in the table below.

For example, in my case, I could get emacs-style keys like this:

[keys]
copy_mode = "prefix+["        # existing field (the key to enter copy mode), unchanged
copy_mode_cursor_down = "ctrl+n"
copy_mode_cursor_up = "ctrl+p"
copy_mode_begin_selection = "ctrl+space"
copy_mode_copy = ["ctrl+w", "y"]
...

For reference, tmux has a two-layer design: vi/emacs presets plus per-key overrides. But for herdr, I think the simple form following the navigate precedent — keep the defaults and override per action — is enough. People who want emacs-style bindings can write all the actions, and this form also stays compatible if presets are added later.

Also, if we want to make it clearer that these are keybindings for a mode, a sub-table like [keys.copy_mode] could be another option (though it would be inconsistent with the existing navigate_* fields). I think this is a point worth discussing.

Proposed field names

The names are based on tmux copy-mode command names, vim terms, existing herdr fields (previous_tab/next_tab, edit_scrollback, etc.), and the current implementation. This is just a first draft; I think the naming is the part that needs discussion most.

Field	Default keys	Action	Notes
copy_mode_cancel	q	Exit without copying
copy_mode_copy	y, Enter	Copy and exit	Same as tmux copy-selection-and-cancel; picked a shorter name
copy_mode_cursor_left	h, Left	Move left
copy_mode_cursor_down	j, Down	Move down
copy_mode_cursor_up	k, Up	Move up
copy_mode_cursor_right	l, Right	Move right
copy_mode_next_word	w	Move to start of next word
copy_mode_previous_word	b	Move to start of previous word
copy_mode_next_word_end	e	Move to end of next word
copy_mode_next_big_word	W	Move to start of next big word	tmux uses next-space, but this follows the "big-word" wording in herdr docs (same for B/E)
copy_mode_previous_big_word	B	Move to start of previous big word
copy_mode_next_big_word_end	E	Move to end of next big word
copy_mode_first_non_blank	^	Move to first non-blank character of the line	tmux uses back-to-indentation, but this follows vim's "first non-blank" wording
copy_mode_start_of_line	0, Home	Move to start of line
copy_mode_end_of_line	$, End	Move to end of line
copy_mode_next_paragraph	}	Move to next paragraph
copy_mode_previous_paragraph	{	Move to previous paragraph
copy_mode_scrollback_top	g	Move to top of scrollback	herdr internals use the word history, but this follows user-facing terms like edit_scrollback (same for G)
copy_mode_scrollback_bottom	G	Move to bottom of scrollback
copy_mode_page_up	ctrl+b, PageUp	Scroll up one page
copy_mode_page_down	ctrl+f, PageDown	Scroll down one page
copy_mode_half_page_up	ctrl+u	Scroll up half a page
copy_mode_half_page_down	ctrl+d	Scroll down half a page
copy_mode_begin_selection	v, Space	Start character-wise selection
copy_mode_select_line	V	Select by line
copy_mode_search_forward	/	Start forward search input
copy_mode_search_backward	?	Start backward search input
copy_mode_search_next	n	Repeat search in the same direction
copy_mode_search_previous	N	Repeat search in the opposite direction

[shibayu36]

Note: I edited the comment above. I had misunderstood how the reserved keys should work, so the spec now reserves only Esc — the arrow keys, Home/End, PageUp/PageDown, and Enter are ordinary default keys in the table and can be overridden.