Home

Awesome

Tmux Rapid Copy Toolkit

This tmux plugin is intended to allow copying on-screen data as efficiently and in as few keystrokes as possible. It is inspired by several other tmux plugins including tmux-jump, tmux-fingers, tmux-open, and other similar ones. This plugin combines, improves, and adds functionality on top of a common interface, with particular attention paid to stability and reliability with respect to wrapped lines, panes, zooming, etc.

Features

There are 5 major modes/features:

easymotion

This is a reimplementation of the classic vim-style easymotion movement. It allows rapid seeking to anywhere in copy-mode in just a few keystrokes (typically 3 or 4).

In tmux copy-mode, hit the easymotion key (by default s), then enter the character at the desired seek destination. Each instance of that character will then be highlighted and replaced with one or more letters. Enter the letter(s) corresponding to the desired seek destination to seek there. The j, k, and n line-based actions are also supported.

This mode has several variants that can be configured using options.

easycopy

This is effectively two easymotion movements in series to set the start and end positions of a block of text to copy. This can be used outside of copy-mode. With default keybinds, it allows copying nearly any arbitrary block of text on screen in 8 keystrokes or less (including prefix).

To use, hit Ctrl-b S to activate easycopy mode. Then enter the character at the start of the region to copy, and key in the corresponding label that appears. Immediately after, enter the character at the end (inclusive) of the region to copy, then the corresponding label. The block will then flash to confirm and will be copied.

quickcopy

This mode allows copying some of the most common elements of text in even fewer keystrokes; as few as 3 (including prefix) for very commonly-copied things like URLs. A set of patterns for commonly-copied elements such as paths, filenames, URLs, etc. is configured in tmux.conf (with a reasonable set of defaults) and these are used to select copyable regions.

To use, hit Ctrl-b Q to active quickcopy mode. All matched elements on screen will be highlighted with associated labels. Key in the label to copy the region of text. Shorter labels are assigned to the higher-priority matches. If there are overlapping matches (there usually are), matches are displayed sequentially in batches - press n to advance to the next batch. Batches are arranged by configured priority, but also optimized to fit as many matches on-screen as possible in a batch.

quickopen

This mode allows quickly opening URLs in a browser or absolute paths with their respective applications.

It is activated with Ctrl-b P and behaves identially to quickcopy mode, except that only openable things are highlighted. Selecting one invokes xdg-open (on Linux) or open (on Mac). It also includes a mechanism to import X environment variables from external source to ensure the command can reach X.

linecopy

This mode allows copying blocks of full lines, or a single line; essentially a faster version of easycopy when the start and end points are both line boundaries.

To use, hit Ctrl-b W to activate linecopy mode. The beginning of each terminal line is replaced by the label string. Key in a label string to select the first line to copy, then the label string for the last line to copy (inclusive). The block of lines will then be copied.

To copy a single line, key in that line's label using uppercase letters. In this case, do not enter a second label. This will not work if there are any capital letters defined in the label chars. Single-line copies can also be performed using quickcopy.

Line beginnings are assigned for all terminal lines, including wrapped lines; but the end of a line always goes to the end of a "logical" line (a hard line break). This allows both easily copying wrapped lines and copying some partial lines.

Requirements

Installation

Using tmux plugin manager, add the following to your tmux.conf:

set -g @plugin 'CrispyConductor/tmux-copy-toolkit'

Then reload tmux with Ctrl-b :source ~/.tmux.conf and install TPM plugins with Ctrl-b I.

Manual Install

To install without TPM:

git clone https://github.com/CrispyConductor/tmux-copy-toolkit/ ~/path/to/somewhere/

Then add to tmux.conf:

run-shell ~/path/to/somewhere/copytk.tmux

Keybinds

This table specifies the default keybinds. Additional keybinds can be added to tmux.conf. The defaults can be suppressed by adding this to tmux.conf:

set -g @copytk-no-default-binds on

You can find the commands corresponding to each binding in copytk.tmux.

ModeActionDefault Key
copyeasymotion seeks
copyeasymotion seek 2-charS S
copyeasymotion "j" action (lines below cursor)S j
copyeasymotion "k" action (lines above cursor)S k
copyeasymotion lines action (all lines)S n
anyeasycopy<Prefix> S
anyquickcopy<Prefix> Q
anyquickopen<Prefix> P
anylinecopy<Prefix> W

Options

These options can be configured in your tmux.conf like:

set -g @copytk-copy-command "VALUE"
OptionDefaultDescription
@copytk-copy-commandtmux load-buffer -Command to run to copy data. The command is run in a shell and data is piped to its stdin.
@copytk-label-charsasdghklqwertyuiopzxcvbnmfj;Characters to use for labels.
@copytk-cancel-keyEscape Enter ^CKey(s) to use to cancel out of a mode. These are curses-style key names (with the exception of a few that are mapped).
@copytk-flash-time0.5Seconds to flash copied text on screen.
@copytk-preflash-time0.05Seconds to blank screen before flash.
@copytk-case-sensitive-searchupperCase sensitivity for easymotion search char. on=case sensitive; off=not case sensitive; upper=case sensitive only for uppercase search char
@copytk-min-match-spacing2Minimum distance between easymotion search matches.
@copytk-quickcopy-match-*quickcopy patterns; see below
@copytk-quickopen-match-*
@copytk-quickcopy-next-batch-charnKey to assign to switching to next batch in quickcopy mode.
@copytk-quickopen-next-batch-charn
@copytk-quickcopy-min-match-len4Minimum length of matching blocks for quickcopy.
@copytk-quickopen-min-match-len4
@copytk-quickcopy-pack-tiersonWhether to allow mixing match tiers in the same batch to pack more in.
@copytk-flash-only-oneonIn quickcopy mode, if there is more than one instance of the copied text on-screen, this is whether to flash all occurrences of the text or just one.
@copytk-quickopen-env-file~/.tmux-copytk-envPath to a file containing newlike-separated KEY=VALUE environment variables. These are added to the environment for running the open command. Generation of this file can be automated in your shellrc.
@copytk-quickopen-open-commandxdg-open on Linux, open on MacCommand to run to open selected blocks in quickopen. The selected text is passed as an argument.
@copytk-color-highlightgreen:yellowThe color to use for highlighted matches, in the form foreground:background. Valid names are: none, black, red, green, yellow, blue, magenta, cyan, white
@copytk-color-labelcharred:noneThe color to use for the first/active label character.
@copytk-color-labelchar2yellow:noneThe color to use for the second and subsequent label characters.
@copytk-color-messagered:noneThe color to use for the status message.

quickcopy/quickopen matches

Match patterns for quickcopy and quickopen can be configured as well. Patterns for the 2 modes are tracked separately; all quickcopy match options have quickopen equivalents.

Patterns are divided into numbered tiers starting at 0. Tiers define the priorities for matches to be displayed when there are overlaps. Organizing patterns into tiers can be important for quickly finding the desired match. Lower-numbered tiers are higher priority.

Patterns are entered as options in the form @copytk-quickcopy-match-<TierNum>-<PatternNum> . The value is either a regular expression or a built-in pattern key. Tier numbers start at 0 and must be contiguous. Pattern numbers also start as 0 (for each tier) and also must be contiguous.

Any duplicate matches (within or across tiers) are removed; only the highest priority one is kept.

For an example of what this looks like, take a look at the defaults in copytk.tmux.

To suppress the default patterns and completely redefine your own:

set -g @copytk-no-default-matches on

The built-in pattern keys that can be used in place of a regex are:

In addition to these, the defaults include patterns for:

Custom quickcopy example

As an example, here's how one might define a simple quickcopy regex to match basic SQL-query-like things:

set -g @copytk-quickcopy-match-0-1 '(SELECT|INSERT) .+;'

This adds the regex as a tier 0 (high priority) match. It's added as index 1 in tier 0 because quickcopy-match-0-0 is already used by the defaults (but can be changed).