From 982354765bc6f0bfb225d7c1f96e5b73f9880533 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 27 Mar 2013 11:17:12 +0000 Subject: Remove tmux's (already minimal) 88 colour support. Such terminals are few and unnecessary. --- colour.c | 26 -------------------------- options-table.c | 2 +- server-client.c | 2 -- tmux.h | 6 ++---- tty-term.c | 4 +--- tty.c | 32 ++++---------------------------- 6 files changed, 8 insertions(+), 64 deletions(-) diff --git a/colour.c b/colour.c index ff492687..9e90596f 100644 --- a/colour.c +++ b/colour.c @@ -287,29 +287,3 @@ colour_256to16(u_char c) return (table[c]); } - -/* Convert 256 colour palette to 88. */ -u_char -colour_256to88(u_char c) -{ - static const u_char table[256] = { - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, - 16, 17, 17, 18, 18, 19, 20, 21, 21, 22, 22, 23, 20, 21, 21, 22, - 22, 23, 24, 25, 25, 26, 26, 27, 24, 25, 25, 26, 26, 27, 28, 29, - 29, 30, 30, 31, 32, 33, 33, 34, 34, 35, 36, 37, 37, 38, 38, 39, - 36, 37, 37, 38, 38, 39, 40, 41, 41, 42, 42, 43, 40, 41, 41, 42, - 42, 43, 44, 45, 45, 46, 46, 47, 32, 33, 33, 34, 34, 35, 36, 37, - 37, 38, 38, 39, 36, 37, 37, 38, 38, 39, 40, 41, 41, 42, 42, 43, - 40, 41, 41, 42, 42, 43, 44, 45, 45, 46, 46, 47, 48, 49, 49, 50, - 50, 51, 52, 53, 53, 54, 54, 55, 52, 53, 53, 54, 54, 55, 56, 57, - 57, 58, 58, 59, 56, 57, 57, 58, 58, 59, 60, 61, 61, 62, 62, 63, - 48, 49, 49, 50, 50, 51, 52, 53, 53, 54, 54, 55, 52, 53, 53, 54, - 54, 55, 56, 57, 57, 58, 58, 59, 56, 57, 57, 58, 58, 59, 60, 61, - 61, 62, 62, 63, 64, 65, 65, 66, 66, 67, 68, 69, 69, 70, 70, 71, - 68, 69, 69, 70, 70, 71, 72, 73, 73, 74, 74, 75, 72, 73, 73, 74, - 74, 75, 76, 77, 77, 78, 78, 79, 0, 0, 80, 80, 80, 81, 81, 81, - 82, 82, 82, 83, 83, 83, 84, 84, 84, 85, 85, 85, 86, 86, 86, 87 - }; - - return (table[c]); -} diff --git a/options-table.c b/options-table.c index ae711882..c4ada1f2 100644 --- a/options-table.c +++ b/options-table.c @@ -414,7 +414,7 @@ const struct options_table_entry session_options_table[] = { { .name = "terminal-overrides", .type = OPTIONS_TABLE_STRING, - .default_str = "*88col*:colors=88,*256col*:colors=256" + .default_str = "*256col*:colors=256" ",xterm*:XT:Ms=\\E]52;%p1%s;%p2%s\\007" ":Cc=\\E]12;%p1%s\\007:Cr=\\E]112\\007" ":Cs=\\E[%p1%d q:Csr=\\E[2 q,screen*:XT" diff --git a/server-client.c b/server-client.c index f61912bc..ac4ecf29 100644 --- a/server-client.c +++ b/server-client.c @@ -981,8 +981,6 @@ server_client_msg_identify( c->tty.flags |= TTY_UTF8; if (data->flags & IDENTIFY_256COLOURS) c->tty.term_flags |= TERM_256COLOURS; - else if (data->flags & IDENTIFY_88COLOURS) - c->tty.term_flags |= TERM_88COLOURS; tty_resize(&c->tty); diff --git a/tmux.h b/tmux.h index 10da2bee..053b574e 100644 --- a/tmux.h +++ b/tmux.h @@ -481,7 +481,7 @@ struct msg_identify_data { #define IDENTIFY_UTF8 0x1 #define IDENTIFY_256COLOURS 0x2 -#define IDENTIFY_88COLOURS 0x4 +/* 0x4 unused */ #define IDENTIFY_CONTROL 0x8 #define IDENTIFY_TERMIOS 0x10 int flags; @@ -1141,8 +1141,7 @@ struct tty_term { struct tty_code codes[NTTYCODE]; #define TERM_256COLOURS 0x1 -#define TERM_88COLOURS 0x2 -#define TERM_EARLYWRAP 0x4 +#define TERM_EARLYWRAP 0x2 int flags; LIST_ENTRY(tty_term) entry; @@ -1986,7 +1985,6 @@ void colour_set_bg(struct grid_cell *, int); const char *colour_tostring(int); int colour_fromstring(const char *); u_char colour_256to16(u_char); -u_char colour_256to88(u_char); /* attributes.c */ const char *attributes_tostring(u_char); diff --git a/tty-term.c b/tty-term.c index c827a444..254569f6 100644 --- a/tty-term.c +++ b/tty-term.c @@ -404,11 +404,9 @@ tty_term_find(char *name, int fd, const char *overrides, char **cause) goto error; } - /* Figure out if we have 256 or 88 colours. */ + /* Figure out if we have 256. */ if (tty_term_number(term, TTYC_COLORS) == 256) term->flags |= TERM_256COLOURS; - if (tty_term_number(term, TTYC_COLORS) == 88) - term->flags |= TERM_88COLOURS; /* * Terminals without xenl (eat newline glitch) wrap at at $COLUMNS - 1 diff --git a/tty.c b/tty.c index 75a2f657..bffddac6 100644 --- a/tty.c +++ b/tty.c @@ -35,7 +35,6 @@ void tty_read_callback(struct bufferevent *, void *); void tty_error_callback(struct bufferevent *, short, void *); int tty_try_256(struct tty *, u_char, const char *); -int tty_try_88(struct tty *, u_char, const char *); void tty_colours(struct tty *, const struct grid_cell *); void tty_check_fg(struct tty *, struct grid_cell *); @@ -1446,9 +1445,7 @@ tty_check_fg(struct tty *tty, struct grid_cell *gc) /* Is this a 256-colour colour? */ if (gc->flags & GRID_FLAG_FG256) { /* And not a 256 colour mode? */ - if (!(tty->term->flags & TERM_88COLOURS) && - !(tty->term_flags & TERM_88COLOURS) && - !(tty->term->flags & TERM_256COLOURS) && + if (!(tty->term->flags & TERM_256COLOURS) && !(tty->term_flags & TERM_256COLOURS)) { gc->fg = colour_256to16(gc->fg); if (gc->fg & 8) { @@ -1481,9 +1478,7 @@ tty_check_bg(struct tty *tty, struct grid_cell *gc) * palette. Bold background doesn't exist portably, so just * discard the bold bit if set. */ - if (!(tty->term->flags & TERM_88COLOURS) && - !(tty->term_flags & TERM_88COLOURS) && - !(tty->term->flags & TERM_256COLOURS) && + if (!(tty->term->flags & TERM_256COLOURS) && !(tty->term_flags & TERM_256COLOURS)) { gc->bg = colour_256to16(gc->bg); if (gc->bg & 8) @@ -1511,11 +1506,9 @@ tty_colours_fg(struct tty *tty, const struct grid_cell *gc) /* Is this a 256-colour colour? */ if (gc->flags & GRID_FLAG_FG256) { - /* Try as 256 colours or translating to 88. */ + /* Try as 256 colours. */ if (tty_try_256(tty, fg, "38") == 0) goto save_fg; - if (tty_try_88(tty, fg, "38") == 0) - goto save_fg; /* Else already handled by tty_check_fg. */ return; } @@ -1546,11 +1539,9 @@ tty_colours_bg(struct tty *tty, const struct grid_cell *gc) /* Is this a 256-colour colour? */ if (gc->flags & GRID_FLAG_BG256) { - /* Try as 256 colours or translating to 88. */ + /* Try as 256 colours. */ if (tty_try_256(tty, bg, "48") == 0) goto save_bg; - if (tty_try_88(tty, bg, "48") == 0) - goto save_bg; /* Else already handled by tty_check_bg. */ return; } @@ -1591,21 +1582,6 @@ tty_try_256(struct tty *tty, u_char colour, const char *type) return (0); } -int -tty_try_88(struct tty *tty, u_char colour, const char *type) -{ - char s[32]; - - if (!(tty->term->flags & TERM_88COLOURS) && - !(tty->term_flags & TERM_88COLOURS)) - return (-1); - colour = colour_256to88(colour); - - xsnprintf(s, sizeof s, "\033[%s;5;%hhum", type, colour); - tty_puts(tty, s); - return (0); -} - void tty_bell(struct tty *tty) { -- cgit From 5e4d9a3197a229ecb30d51f5b7e6756ef31dc1d2 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 27 Mar 2013 11:19:19 +0000 Subject: Move the cursor back into the last column on CUU/CUD to match xterm behaviour. From George Nachman. --- screen-write.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/screen-write.c b/screen-write.c index 348065c6..c0935c95 100644 --- a/screen-write.c +++ b/screen-write.c @@ -488,6 +488,8 @@ screen_write_cursorup(struct screen_write_ctx *ctx, u_int ny) if (ny > s->cy - s->rupper) ny = s->cy - s->rupper; } + if (s->cx == screen_size_x(s)) + s->cx--; if (ny == 0) return; @@ -512,6 +514,8 @@ screen_write_cursordown(struct screen_write_ctx *ctx, u_int ny) if (ny > s->rlower - s->cy) ny = s->rlower - s->cy; } + if (s->cx == screen_size_x(s)) + s->cx--; if (ny == 0) return; -- cgit From 7f636587098593c6c0efd3feaecb970aa7170116 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 27 Mar 2013 11:24:18 +0000 Subject: Add TMUX_TMPDIR variable to put the socket directory outside TMPDIR. From Ben Boeckel. --- tmux.1 | 13 +++++-------- tmux.c | 15 ++++++--------- 2 files changed, 11 insertions(+), 17 deletions(-) diff --git a/tmux.1 b/tmux.1 index 0dc68bfe..9b1488fc 100644 --- a/tmux.1 +++ b/tmux.1 @@ -98,10 +98,6 @@ The options are as follows: Force .Nm to assume the terminal supports 256 colours. -.It Fl 8 -Like -.Fl 2 , -but indicates that the terminal supports 88 colours. .It Fl C Start in control mode. Given twice @@ -145,11 +141,12 @@ session created, and continues to process the rest of the configuration file. .It Fl L Ar socket-name .Nm stores the server socket in a directory under -.Pa /tmp -(or +.Ev TMUX_TMPDIR , .Ev TMPDIR -if set); -the default socket is named +if it is unset, or +.Pa /tmp +if both are unset. +The default socket is named .Em default . This option allows a different socket name to be specified, allowing several independent diff --git a/tmux.c b/tmux.c index 368562f8..1f4057dc 100644 --- a/tmux.c +++ b/tmux.c @@ -164,10 +164,12 @@ makesocketpath(const char *label) u_int uid; uid = getuid(); - if ((s = getenv("TMPDIR")) == NULL || *s == '\0') - xsnprintf(base, sizeof base, "%s/tmux-%u", _PATH_TMP, uid); - else + if ((s = getenv("TMUX_TMPDIR")) != NULL && *s != '\0') + xsnprintf(base, sizeof base, "%s/", s); + else if ((s = getenv("TMPDIR")) != NULL && *s != '\0') xsnprintf(base, sizeof base, "%s/tmux-%u", s, uid); + else + xsnprintf(base, sizeof base, "%s/tmux-%u", _PATH_TMP, uid); if (mkdir(base, S_IRWXU) != 0 && errno != EEXIST) return (NULL); @@ -244,15 +246,10 @@ main(int argc, char **argv) quiet = flags = 0; label = path = NULL; login_shell = (**argv == '-'); - while ((opt = getopt(argc, argv, "28c:Cdf:lL:qS:uUv")) != -1) { + while ((opt = getopt(argc, argv, "2c:Cdf:lL:qS:uUv")) != -1) { switch (opt) { case '2': flags |= IDENTIFY_256COLOURS; - flags &= ~IDENTIFY_88COLOURS; - break; - case '8': - flags |= IDENTIFY_88COLOURS; - flags &= ~IDENTIFY_256COLOURS; break; case 'c': free(shell_cmd); -- cgit From 66afcf5be092ed0ab86d1d4059426823e72c63d5 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Thu, 28 Mar 2013 15:07:42 +0000 Subject: Make copy-mode -u still scroll up if already in copy mode, handy for people who bind it with -n. --- cmd-copy-mode.c | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/cmd-copy-mode.c b/cmd-copy-mode.c index 59b5a9e5..883a9376 100644 --- a/cmd-copy-mode.c +++ b/cmd-copy-mode.c @@ -54,9 +54,11 @@ cmd_copy_mode_exec(struct cmd *self, struct cmd_q *cmdq) if (cmd_find_pane(cmdq, args_get(args, 't'), NULL, &wp) == NULL) return (CMD_RETURN_ERROR); - if (window_pane_set_mode(wp, &window_copy_mode) != 0) - return (CMD_RETURN_NORMAL); - window_copy_init_from_pane(wp); + if (wp->mode != &window_copy_mode) { + if (window_pane_set_mode(wp, &window_copy_mode) != 0) + return (CMD_RETURN_NORMAL); + window_copy_init_from_pane(wp); + } if (wp->mode == &window_copy_mode && args_has(self->args, 'u')) window_copy_pageup(wp); -- cgit From 738e789dbd7712ab94073036cf4e903abc68447f Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Thu, 28 Mar 2013 15:08:12 +0000 Subject: If -s to swap-pane is not given, use the current pane. --- cmd-swap-pane.c | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/cmd-swap-pane.c b/cmd-swap-pane.c index e7ea6242..e6b46d67 100644 --- a/cmd-swap-pane.c +++ b/cmd-swap-pane.c @@ -75,8 +75,12 @@ cmd_swap_pane_exec(struct cmd *self, struct cmd_q *cmdq) src_wp = TAILQ_PREV(dst_wp, window_panes, entry); if (src_wp == NULL) src_wp = TAILQ_LAST(&dst_w->panes, window_panes); - } else - return (CMD_RETURN_NORMAL); + } else { + src_wl = cmd_find_pane(cmdq, NULL, NULL, &src_wp); + if (src_wl == NULL) + return (CMD_RETURN_ERROR); + src_w = src_wl->window; + } } else { src_wl = cmd_find_pane(cmdq, args_get(args, 's'), NULL, &src_wp); if (src_wl == NULL) -- cgit From 69c86379e39476013205fce627951dd733d647b3 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 10 Apr 2013 11:51:16 +0000 Subject: Remove some code not needed on OpenBSD. --- server-client.c | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/server-client.c b/server-client.c index ac4ecf29..6cacefa7 100644 --- a/server-client.c +++ b/server-client.c @@ -534,18 +534,8 @@ server_client_check_resize(struct window_pane *wp) ws.ws_col = wp->sx; ws.ws_row = wp->sy; - if (ioctl(wp->fd, TIOCSWINSZ, &ws) == -1) { -#ifdef __sun - /* - * Some versions of Solaris apparently can return an error when - * resizing; don't know why this happens, can't reproduce on - * other platforms and ignoring it doesn't seem to cause any - * issues. - */ - if (errno != EINVAL) -#endif + if (ioctl(wp->fd, TIOCSWINSZ, &ws) == -1) fatal("ioctl failed"); - } wp->flags &= ~PANE_RESIZE; } -- cgit From e312db140868754358d40ec17595327a8fbbf180 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 10 Apr 2013 13:04:19 +0100 Subject: Add wait-for to tmux.vim from Ben Boeckel. --- examples/tmux.vim | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tmux.vim b/examples/tmux.vim index 076115c1..e85f8ff6 100644 --- a/examples/tmux.vim +++ b/examples/tmux.vim @@ -56,7 +56,7 @@ syn keyword tmuxCmds \ list-buffers loadb load-buffer pasteb paste-buffer saveb save-buffer \ setb set-buffer showb show-buffer \ clock-mode if[-shell] lock[-server] run[-shell] server-info info - \ choose-list + \ choose-list wait-for syn keyword tmuxOptsSet \ buffer-limit escape-time exit-unattached exit-unattached quiet -- cgit From 20f0d917beb0f774af2628ed7efe2a33cf59f42a Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 10 Apr 2013 12:07:18 +0000 Subject: Missed -o from set-window-option, from Ben Boeckel. --- tmux.1 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tmux.1 b/tmux.1 index 9b1488fc..b38b43bb 100644 --- a/tmux.1 +++ b/tmux.1 @@ -2645,7 +2645,7 @@ The default is .Ql \ -_@ . .El .It Xo Ic set-window-option -.Op Fl agqu +.Op Fl agoqu .Op Fl t Ar target-window .Ar option Ar value .Xc @@ -2654,6 +2654,7 @@ Set a window option. The .Fl a , .Fl g , +.Fl o , .Fl q and .Fl u -- cgit From 7ada64d5f8a0df39229c41b992c0ee8ac9f0a1d7 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 10 Apr 2013 12:15:36 +0000 Subject: Fix bug where end guard in control mode was not printed after session destroyed, from George Nachman. --- cmd-queue.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd-queue.c b/cmd-queue.c index b1c0a4eb..a64d332c 100644 --- a/cmd-queue.c +++ b/cmd-queue.c @@ -158,7 +158,7 @@ cmdq_guard(struct cmd_q *cmdq, const char *guard) { struct client *c = cmdq->client; - if (c == NULL || c->session == NULL) + if (c == NULL) return 0; if (!(c->flags & CLIENT_CONTROL)) return 0; -- cgit From 9fcda95a6f55f017536cdf24366754a2304c1059 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 10 Apr 2013 12:20:35 +0000 Subject: Set EV_WRITE for jobs or run/if-shell jobs can hang. From Chris Johnsen. --- job.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/job.c b/job.c index b76b3345..291e000e 100644 --- a/job.c +++ b/job.c @@ -109,7 +109,7 @@ job_run(const char *cmd, struct session *s, job->event = bufferevent_new(job->fd, NULL, job_write_callback, job_callback, job); - bufferevent_enable(job->event, EV_READ); + bufferevent_enable(job->event, EV_READ|EV_WRITE); log_debug("run job %p: %s, pid %ld", job, job->cmd, (long) job->pid); return (job); -- cgit From cbee283c26968304b473e2191d2bb5f52208b58d Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Thu, 11 Apr 2013 07:27:27 +0000 Subject: Send an SGR0 after turning on modifyOtherKeys to fix Terminal.app which treats \033[>4;1m and \033[4;1m (bold+underline). Reported & tested by otto@. --- tty.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tty.c b/tty.c index bffddac6..74988eb3 100644 --- a/tty.c +++ b/tty.c @@ -220,7 +220,7 @@ tty_start_tty(struct tty *tty) tty_puts(tty, "\033[?1000l\033[?1006l\033[?1005l"); if (tty_term_has(tty->term, TTYC_XT)) - tty_puts(tty, "\033[c\033[>4;1m\033[?1004h"); + tty_puts(tty, "\033[c\033[>4;1m\033[?1004h\033[m"); tty->cx = UINT_MAX; tty->cy = UINT_MAX; @@ -283,7 +283,7 @@ tty_stop_tty(struct tty *tty) tty_raw(tty, "\033[?1000l\033[?1006l\033[?1005l"); if (tty_term_has(tty->term, TTYC_XT)) - tty_raw(tty, "\033[>4m\033[?1004l"); + tty_raw(tty, "\033[>4m\033[?1004l\033[m"); tty_raw(tty, tty_term_string(tty->term, TTYC_RMCUP)); -- cgit From 4ccb2e2c218a10a8039ca801231aaf09b6bf3bce Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Thu, 11 Apr 2013 22:45:05 +0100 Subject: TODO tweaks. --- TODO | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/TODO b/TODO index d3e3b46b..92b60a9a 100644 --- a/TODO +++ b/TODO @@ -47,7 +47,7 @@ - hooks! - warts on current naming: - * display-time but message-fg/bg/attr + * display-time but message-fg/bg/attr * list-* vs show-* * server-info * split-window -> split-pane?? @@ -55,6 +55,7 @@ - way to keep a job running just read its last line of output for #() - better UTF-8 support: + * #22T can split in the middle of UTF-8 characters! * window names and titles * message display * prompt input -- cgit From 7f9b225cc269211b86a4c4d2168146c217d63118 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Thu, 11 Apr 2013 21:52:18 +0000 Subject: Call setlocale(LC_TIME) at startup. --- clock.c | 15 +++++++++++---- tmux.c | 3 +++ 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/clock.c b/clock.c index 00d818be..283a4a1e 100644 --- a/clock.c +++ b/clock.c @@ -103,13 +103,20 @@ clock_draw(struct screen_write_ctx *ctx, int colour, int style) struct grid_cell gc; char tim[64], *ptr; time_t t; + struct tm *tm; u_int i, j, x, y, idx; t = time(NULL); - if (style == 0) - strftime(tim, sizeof tim, "%l:%M %p", localtime(&t)); - else - strftime(tim, sizeof tim, "%H:%M", localtime(&t)); + tm = localtime(&t); + if (style == 0) { + strftime(tim, sizeof tim, "%l:%M ", localtime(&t)); + if (tm->tm_hour >= 12) + strlcat(tim, "PM", sizeof tim); + else + strlcat(tim, "AM", sizeof tim); + } else + strftime(tim, sizeof tim, "%H:%M", tm); + screen_write_clearscreen(ctx); diff --git a/tmux.c b/tmux.c index 1f4057dc..e9b28d7e 100644 --- a/tmux.c +++ b/tmux.c @@ -22,6 +22,7 @@ #include #include #include +#include #include #include #include @@ -243,6 +244,8 @@ main(int argc, char **argv) malloc_options = (char *) "AFGJPX"; #endif + setlocale(LC_TIME, ""); + quiet = flags = 0; label = path = NULL; login_shell = (**argv == '-'); -- cgit From caa8290510244990b26106e027aa253237ada629 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Fri, 12 Apr 2013 12:44:31 +0000 Subject: Copy the client into the new cmdq in source-file so commands that work on it (such as new-session) can work. Fixes issue reported by oss-adv at users dot sf dot net. --- cmd-source-file.c | 1 + 1 file changed, 1 insertion(+) diff --git a/cmd-source-file.c b/cmd-source-file.c index 1bd2bb0a..f50efbe3 100644 --- a/cmd-source-file.c +++ b/cmd-source-file.c @@ -49,6 +49,7 @@ cmd_source_file_exec(struct cmd *self, struct cmd_q *cmdq) char *cause; cmdq1 = cmdq_new(NULL); + cmdq1->client = cmdq->client; cmdq1->emptyfn = cmd_source_file_done; cmdq1->data = cmdq; -- cgit From 27dcf470dc4aa5901ac7f01b3a9f971e02f2229e Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Fri, 12 Apr 2013 12:50:36 +0000 Subject: Remove some Korean characters from the zero-width list that apparently shouldn't be there, from Jeong Mok Cho. --- utf8.c | 1 - 1 file changed, 1 deletion(-) diff --git a/utf8.c b/utf8.c index b276d872..1c81392b 100644 --- a/utf8.c +++ b/utf8.c @@ -171,7 +171,6 @@ struct utf8_width_entry utf8_width_table[] = { { 0x30000, 0x3fffd, 2, NULL, NULL }, { 0x00711, 0x00711, 0, NULL, NULL }, { 0x0fe00, 0x0fe0f, 0, NULL, NULL }, - { 0x01160, 0x011ff, 0, NULL, NULL }, { 0x0180b, 0x0180d, 0, NULL, NULL }, { 0x10a3f, 0x10a3f, 0, NULL, NULL }, { 0x00981, 0x00981, 0, NULL, NULL }, -- cgit From 2c4543b9e9bd38bcc45393dad94930bcde872e6c Mon Sep 17 00:00:00 2001 From: Thomas Adam Date: Sun, 14 Apr 2013 18:07:08 +0100 Subject: Add back missing -V flag This went walkies from a previous git commit. --- tmux.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tmux.c b/tmux.c index e8fd98b2..e6de5cfe 100644 --- a/tmux.c +++ b/tmux.c @@ -253,7 +253,7 @@ main(int argc, char **argv) quiet = flags = 0; label = path = NULL; login_shell = (**argv == '-'); - while ((opt = getopt(argc, argv, "2c:Cdf:lL:qS:uUv")) != -1) { + while ((opt = getopt(argc, argv, "2c:Cdf:lL:qS:uUVv")) != -1) { switch (opt) { case '2': flags |= IDENTIFY_256COLOURS; -- cgit From c24b58e2ee8691870736959deb252c225b205b4d Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Tue, 16 Apr 2013 11:33:53 +0100 Subject: Generate tmux.1 using mdoc2man.awk on Solaris, issue brought up and changes tested by Dagobert Michelsen. --- .gitignore | 1 + Makefile.am | 14 +- configure.ac | 5 + mdoc2man.awk | 370 ++++++ tmux.1 | 3808 ---------------------------------------------------------- tmux.1.in | 3808 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 4196 insertions(+), 3810 deletions(-) create mode 100644 mdoc2man.awk delete mode 100644 tmux.1 create mode 100644 tmux.1.in diff --git a/.gitignore b/.gitignore index c3906ada..3b400861 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ tmux Makefile Makefile.in configure +tmux.1 diff --git a/Makefile.am b/Makefile.am index 2ce54b1a..b85eae0c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,12 +2,14 @@ # Obvious program stuff. bin_PROGRAMS = tmux -dist_man1_MANS = tmux.1 +nodist_man1_MANS = tmux.1 +CLEANFILES = tmux.1 # Distribution tarball options. EXTRA_DIST = \ CHANGES FAQ README TODO examples compat \ - array.h compat.h tmux.h osdep-*.c + array.h compat.h tmux.h osdep-*.c mdoc2man.awk \ + tmux.1.in dist-hook: grep "^#found_debug=" configure find $(distdir) -name .svn -type d|xargs rm -Rf @@ -232,6 +234,14 @@ if NO_B64_NTOP nodist_tmux_SOURCES += compat/b64_ntop.c endif +# Build tmux.1 in the right format. +tmux.1: tmux.1.in + if test x@MANFORMAT@ = xmdoc; then \ + cp tmux.1.in tmux.1; \ + else \ + $(AWK) -fmdoc2man.awk tmux.1.in >tmux.1; \ + fi + # Update SF web site. upload-index.html: update-index.html scp www/index.html www/main.css www/images/*.png \ diff --git a/configure.ac b/configure.ac index f00937f0..b4f76f5f 100644 --- a/configure.ac +++ b/configure.ac @@ -416,6 +416,10 @@ else AC_MSG_RESULT(no) fi +# Man page defaults to mdoc. +MANFORMAT=mdoc +AC_SUBST(MANFORMAT) + # Figure out the platform for osdep-*.c and forkpty-*.c. AC_MSG_CHECKING(platform) case "$host_os" in @@ -455,6 +459,7 @@ case "$host_os" in *solaris*) AC_MSG_RESULT(sunos) PLATFORM=sunos + MANFORMAT=man ;; *hpux*) AC_MSG_RESULT(hpux) diff --git a/mdoc2man.awk b/mdoc2man.awk new file mode 100644 index 00000000..80e8d5ff --- /dev/null +++ b/mdoc2man.awk @@ -0,0 +1,370 @@ +#!/usr/bin/awk +# +# $Id: mdoc2man.awk,v 1.9 2009/10/24 00:52:42 dtucker Exp $ +# +# Version history: +# v4+ Adapted for OpenSSH Portable (see cvs Id and history) +# v3, I put the program under a proper license +# Dan Nelson added .An, .Aq and fixed a typo +# v2, fixed to work on GNU awk --posix and MacOS X +# v1, first attempt, didn't work on MacOS X +# +# Copyright (c) 2003 Peter Stuge +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + +BEGIN { + optlist=0 + oldoptlist=0 + nospace=0 + synopsis=0 + reference=0 + block=0 + ext=0 + extopt=0 + literal=0 + prenl=0 + breakw=0 + line="" +} + +function wtail() { + retval="" + while(w0;i--) { + add(refauthors[i]) + if(i>1) + add(", ") + } + if(nrefauthors>1) + add(" and ") + if(nrefauthors>0) + add(refauthors[0] ", ") + add("\\fI" reftitle "\\fP") + if(length(refissue)) + add(", " refissue) + if(length(refreport)) { + add(", " refreport) + } + if(length(refdate)) + add(", " refdate) + if(length(refopt)) + add(", " refopt) + add(".") + reference=0 + } else if(reference) { + if(match(words[w],"^%A$")) { refauthors[nrefauthors++]=wtail() } + if(match(words[w],"^%T$")) { + reftitle=wtail() + sub("^\"","",reftitle) + sub("\"$","",reftitle) + } + if(match(words[w],"^%N$")) { refissue=wtail() } + if(match(words[w],"^%D$")) { refdate=wtail() } + if(match(words[w],"^%O$")) { refopt=wtail() } + if(match(words[w],"^%R$")) { refreport=wtail() } + } else if(match(words[w],"^Nm$")) { + if(synopsis) { + add(".br") + prenl++ + } + n=words[++w] + if(!length(name)) + name=n + if(!length(n)) + n=name + add("\\fB" n "\\fP") + if(!nospace&&match(words[w+1],"^[\\.,]")) + nospace=1 + } else if(match(words[w],"^Nd$")) { + add("\\- " wtail()) + } else if(match(words[w],"^Fl$")) { + add("\\fB\\-" words[++w] "\\fP") + if(!nospace&&match(words[w+1],"^[\\.,]")) + nospace=1 + } else if(match(words[w],"^Ar$")) { + add("\\fI") + if(w==nwords) + add("file ...\\fP") + else { + add(words[++w] "\\fP") + while(match(words[w+1],"^\\|$")) + add(OFS words[++w] " \\fI" words[++w] "\\fP") + } + if(!nospace&&match(words[w+1],"^[\\.,]")) + nospace=1 + } else if(match(words[w],"^Cm$")) { + add("\\fB" words[++w] "\\fP") + while(w") + if(option) + add("]") + if(ext&&!extopt&&!match(line," $")) + add(OFS) + if(!ext&&!extopt&&length(line)) { + print line + prenl=0 + line="" + } +} diff --git a/tmux.1 b/tmux.1 deleted file mode 100644 index 98bf9574..00000000 --- a/tmux.1 +++ /dev/null @@ -1,3808 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright (c) 2007 Nicholas Marriott -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER -.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING -.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: March 25 2013 $ -.Dt TMUX 1 -.Os -.Sh NAME -.Nm tmux -.Nd terminal multiplexer -.Sh SYNOPSIS -.Nm tmux -.Bk -words -.Op Fl 28lCquvV -.Op Fl c Ar shell-command -.Op Fl f Ar file -.Op Fl L Ar socket-name -.Op Fl S Ar socket-path -.Op Ar command Op Ar flags -.Ek -.Sh DESCRIPTION -.Nm -is a terminal multiplexer: -it enables a number of terminals to be created, accessed, and -controlled from a single screen. -.Nm -may be detached from a screen -and continue running in the background, -then later reattached. -.Pp -When -.Nm -is started it creates a new -.Em session -with a single -.Em window -and displays it on screen. -A status line at the bottom of the screen -shows information on the current session -and is used to enter interactive commands. -.Pp -A session is a single collection of -.Em pseudo terminals -under the management of -.Nm . -Each session has one or more -windows linked to it. -A window occupies the entire screen -and may be split into rectangular panes, -each of which is a separate pseudo terminal -(the -.Xr pty 4 -manual page documents the technical details of pseudo terminals). -Any number of -.Nm -instances may connect to the same session, -and any number of windows may be present in the same session. -Once all sessions are killed, -.Nm -exits. -.Pp -Each session is persistent and will survive accidental disconnection -(such as -.Xr ssh 1 -connection timeout) or intentional detaching (with the -.Ql C-b d -key strokes). -.Nm -may be reattached using: -.Pp -.Dl $ tmux attach -.Pp -In -.Nm , -a session is displayed on screen by a -.Em client -and all sessions are managed by a single -.Em server . -The server and each client are separate processes which communicate through a -socket in -.Pa /tmp . -.Pp -The options are as follows: -.Bl -tag -width "XXXXXXXXXXXX" -.It Fl 2 -Force -.Nm -to assume the terminal supports 256 colours. -.It Fl C -Start in control mode. -Given twice -.Xo ( Fl CC ) Xc -disables echo. -.It Fl c Ar shell-command -Execute -.Ar shell-command -using the default shell. -If necessary, the -.Nm -server will be started to retrieve the -.Ic default-shell -option. -This option is for compatibility with -.Xr sh 1 -when -.Nm -is used as a login shell. -.It Fl f Ar file -Specify an alternative configuration file. -By default, -.Nm -loads the system configuration file from -.Pa /etc/tmux.conf , -if present, then looks for a user configuration file at -.Pa ~/.tmux.conf . -.Pp -The configuration file is a set of -.Nm -commands which are executed in sequence when the server is first started. -.Nm -loads configuration files once when the server process has started. -The -.Ic source-file -command may be used to load a file later. -.Pp -.Nm -shows any error messages from commands in configuration files in the first -session created, and continues to process the rest of the configuration file. -.It Fl L Ar socket-name -.Nm -stores the server socket in a directory under -.Ev TMUX_TMPDIR , -.Ev TMPDIR -if it is unset, or -.Pa /tmp -if both are unset. -The default socket is named -.Em default . -This option allows a different socket name to be specified, allowing several -independent -.Nm -servers to be run. -Unlike -.Fl S -a full path is not necessary: the sockets are all created in the same -directory. -.Pp -If the socket is accidentally removed, the -.Dv SIGUSR1 -signal may be sent to the -.Nm -server process to recreate it. -.It Fl l -Behave as a login shell. -This flag currently has no effect and is for compatibility with other shells -when using tmux as a login shell. -.It Fl q -Set the -.Ic quiet -server option to prevent the server sending various informational messages. -.It Fl S Ar socket-path -Specify a full alternative path to the server socket. -If -.Fl S -is specified, the default socket directory is not used and any -.Fl L -flag is ignored. -.It Fl u -.Nm -attempts to guess if the terminal is likely to support UTF-8 by checking the -first of the -.Ev LC_ALL , -.Ev LC_CTYPE -and -.Ev LANG -environment variables to be set for the string "UTF-8". -This is not always correct: the -.Fl u -flag explicitly informs -.Nm -that UTF-8 is supported. -.Pp -If the server is started from a client passed -.Fl u -or where UTF-8 is detected, the -.Ic utf8 -and -.Ic status-utf8 -options are enabled in the global window and session options respectively. -.It Fl v -Request verbose logging. -This option may be specified multiple times for increasing verbosity. -Log messages will be saved into -.Pa tmux-client-PID.log -and -.Pa tmux-server-PID.log -files in the current directory, where -.Em PID -is the PID of the server or client process. -.It Fl V -Report the -.Nm -version. -.It Ar command Op Ar flags -This specifies one of a set of commands used to control -.Nm , -as described in the following sections. -If no commands are specified, the -.Ic new-session -command is assumed. -.El -.Sh KEY BINDINGS -.Nm -may be controlled from an attached client by using a key combination of a -prefix key, -.Ql C-b -(Ctrl-b) by default, followed by a command key. -.Pp -The default command key bindings are: -.Pp -.Bl -tag -width "XXXXXXXXXX" -offset indent -compact -.It C-b -Send the prefix key (C-b) through to the application. -.It C-o -Rotate the panes in the current window forwards. -.It C-z -Suspend the -.Nm -client. -.It ! -Break the current pane out of the window. -.It \&" -Split the current pane into two, top and bottom. -.It # -List all paste buffers. -.It $ -Rename the current session. -.It % -Split the current pane into two, left and right. -.It & -Kill the current window. -.It ' -Prompt for a window index to select. -.It , -Rename the current window. -.It - -Delete the most recently copied buffer of text. -.It . -Prompt for an index to move the current window. -.It 0 to 9 -Select windows 0 to 9. -.It : -Enter the -.Nm -command prompt. -.It ; -Move to the previously active pane. -.It = -Choose which buffer to paste interactively from a list. -.It \&? -List all key bindings. -.It D -Choose a client to detach. -.It \&[ -Enter copy mode to copy text or view the history. -.It \&] -Paste the most recently copied buffer of text. -.It c -Create a new window. -.It d -Detach the current client. -.It f -Prompt to search for text in open windows. -.It i -Display some information about the current window. -.It l -Move to the previously selected window. -.It n -Change to the next window. -.It o -Select the next pane in the current window. -.It p -Change to the previous window. -.It q -Briefly display pane indexes. -.It r -Force redraw of the attached client. -.It s -Select a new session for the attached client interactively. -.It L -Switch the attached client back to the last session. -.It t -Show the time. -.It w -Choose the current window interactively. -.It x -Kill the current pane. -.It { -Swap the current pane with the previous pane. -.It } -Swap the current pane with the next pane. -.It ~ -Show previous messages from -.Nm , -if any. -.It Page Up -Enter copy mode and scroll one page up. -.It Up, Down -.It Left, Right -Change to the pane above, below, to the left, or to the right of the current -pane. -.It M-1 to M-5 -Arrange panes in one of the five preset layouts: even-horizontal, -even-vertical, main-horizontal, main-vertical, or tiled. -.It M-n -Move to the next window with a bell or activity marker. -.It M-o -Rotate the panes in the current window backwards. -.It M-p -Move to the previous window with a bell or activity marker. -.It C-Up, C-Down -.It C-Left, C-Right -Resize the current pane in steps of one cell. -.It M-Up, M-Down -.It M-Left, M-Right -Resize the current pane in steps of five cells. -.El -.Pp -Key bindings may be changed with the -.Ic bind-key -and -.Ic unbind-key -commands. -.Sh COMMANDS -This section contains a list of the commands supported by -.Nm . -Most commands accept the optional -.Fl t -argument with one of -.Ar target-client , -.Ar target-session -.Ar target-window , -or -.Ar target-pane . -These specify the client, session, window or pane which a command should affect. -.Ar target-client -is the name of the -.Xr pty 4 -file to which the client is connected, for example either of -.Pa /dev/ttyp1 -or -.Pa ttyp1 -for the client attached to -.Pa /dev/ttyp1 . -If no client is specified, the current client is chosen, if possible, or an -error is reported. -Clients may be listed with the -.Ic list-clients -command. -.Pp -.Ar target-session -is the session id prefixed with a $, the name of a session (as listed by the -.Ic list-sessions -command), or the name of a client with the same syntax as -.Ar target-client , -in which case the session attached to the client is used. -When looking for the session name, -.Nm -initially searches for an exact match; if none is found, the session names -are checked for any for which -.Ar target-session -is a prefix or for which it matches as an -.Xr fnmatch 3 -pattern. -If a single match is found, it is used as the target session; multiple matches -produce an error. -If a session is omitted, the current session is used if available; if no -current session is available, the most recently used is chosen. -.Pp -.Ar target-window -specifies a window in the form -.Em session Ns \&: Ns Em window . -.Em session -follows the same rules as for -.Ar target-session , -and -.Em window -is looked for in order: as a window index, for example mysession:1; -as a window ID, such as @1; -as an exact window name, such as mysession:mywindow; then as an -.Xr fnmatch 3 -pattern or the start of a window name, such as mysession:mywin* or -mysession:mywin. -An empty window name specifies the next unused index if appropriate (for -example the -.Ic new-window -and -.Ic link-window -commands) -otherwise the current window in -.Em session -is chosen. -The special character -.Ql \&! -uses the last (previously current) window, -.Ql ^ -selects the highest numbered window, -.Ql $ -selects the lowest numbered window, and -.Ql + -and -.Ql - -select the next window or the previous window by number. -When the argument does not contain a colon, -.Nm -first attempts to parse it as window; if that fails, an attempt is made to -match a session. -.Pp -.Ar target-pane -takes a similar form to -.Ar target-window -but with the optional addition of a period followed by a pane index, for -example: mysession:mywindow.1. -If the pane index is omitted, the currently active pane in the specified -window is used. -If neither a colon nor period appears, -.Nm -first attempts to use the argument as a pane index; if that fails, it is looked -up as for -.Ar target-window . -A -.Ql + -or -.Ql - -indicate the next or previous pane index, respectively. -One of the strings -.Em top , -.Em bottom , -.Em left , -.Em right , -.Em top-left , -.Em top-right , -.Em bottom-left -or -.Em bottom-right -may be used instead of a pane index. -.Pp -The special characters -.Ql + -and -.Ql - -may be followed by an offset, for example: -.Bd -literal -offset indent -select-window -t:+2 -.Ed -.Pp -When dealing with a session that doesn't contain sequential window indexes, -they will be correctly skipped. -.Pp -.Nm -also gives each pane created in a server an identifier consisting of a -.Ql % -and a number, starting from zero. -A pane's identifier is unique for the life of the -.Nm -server and is passed to the child process of the pane in the -.Ev TMUX_PANE -environment variable. -It may be used alone to target a pane or the window containing it. -.Pp -.Ar shell-command -arguments are -.Xr sh 1 -commands. -These must be passed as a single item, which typically means quoting them, for -example: -.Bd -literal -offset indent -new-window 'vi /etc/passwd' -.Ed -.Pp -.Ar command -.Op Ar arguments -refers to a -.Nm -command, passed with the command and arguments separately, for example: -.Bd -literal -offset indent -bind-key F1 set-window-option force-width 81 -.Ed -.Pp -Or if using -.Xr sh 1 : -.Bd -literal -offset indent -$ tmux bind-key F1 set-window-option force-width 81 -.Ed -.Pp -Multiple commands may be specified together as part of a -.Em command sequence . -Each command should be separated by spaces and a semicolon; -commands are executed sequentially from left to right and -lines ending with a backslash continue on to the next line, -except when escaped by another backslash. -A literal semicolon may be included by escaping it with a backslash (for -example, when specifying a command sequence to -.Ic bind-key ) . -.Pp -Example -.Nm -commands include: -.Bd -literal -offset indent -refresh-client -t/dev/ttyp2 - -rename-session -tfirst newname - -set-window-option -t:0 monitor-activity on - -new-window ; split-window -d - -bind-key R source-file ~/.tmux.conf \e; \e - display-message "source-file done" -.Ed -.Pp -Or from -.Xr sh 1 : -.Bd -literal -offset indent -$ tmux kill-window -t :1 - -$ tmux new-window \e; split-window -d - -$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach -.Ed -.Sh CLIENTS AND SESSIONS -The -.Nm -server manages clients, sessions, windows and panes. -Clients are attached to sessions to interact with them, either -when they are created with the -.Ic new-session -command, or later with the -.Ic attach-session -command. -Each session has one or more windows -.Em linked -into it. -Windows may be linked to multiple sessions and are made up of one or -more panes, -each of which contains a pseudo terminal. -Commands for creating, linking and otherwise manipulating windows -are covered -in the -.Sx WINDOWS AND PANES -section. -.Pp -The following commands are available to manage clients and sessions: -.Bl -tag -width Ds -.It Xo Ic attach-session -.Op Fl dr -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic attach ) -If run from outside -.Nm , -create a new client in the current terminal and attach it to -.Ar target-session . -If used from inside, switch the current client. -If -.Fl d -is specified, any other clients attached to the session are detached. -.Fl r -signifies the client is read-only (only keys bound to the -.Ic detach-client -or -.Ic switch-client -commands have any effect) -.Pp -If no server is started, -.Ic attach-session -will attempt to start it; this will fail unless sessions are created in the -configuration file. -.Pp -The -.Ar target-session -rules for -.Ic attach-session -are slightly adjusted: if -.Nm -needs to select the most recently used session, it will prefer the most -recently used -.Em unattached -session. -.It Xo Ic detach-client -.Op Fl P -.Op Fl a -.Op Fl s Ar target-session -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic detach ) -Detach the current client if bound to a key, the client specified with -.Fl t , -or all clients currently attached to the session specified by -.Fl s . -The -.Fl a -option kills all but the client given with -.Fl t . -If -.Fl P -is given, send SIGHUP to the parent process of the client, typically causing it -to exit. -.It Ic has-session Op Fl t Ar target-session -.D1 (alias: Ic has ) -Report an error and exit with 1 if the specified session does not exist. -If it does exist, exit with 0. -.It Ic kill-server -Kill the -.Nm -server and clients and destroy all sessions. -.It Ic kill-session -.Op Fl a -.Op Fl t Ar target-session -Destroy the given session, closing any windows linked to it and no other -sessions, and detaching all clients attached to it. -If -.Fl a -is given, all sessions but the specified one is killed. -.It Xo Ic list-clients -.Op Fl F Ar format -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic lsc ) -List all clients attached to the server. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -If -.Ar target-session -is specified, list only clients connected to that session. -.It Ic list-commands -.D1 (alias: Ic lscm ) -List the syntax of all commands supported by -.Nm . -.It Ic list-sessions Op Fl F Ar format -.D1 (alias: Ic ls ) -List all sessions managed by the server. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Ic lock-client Op Fl t Ar target-client -.D1 (alias: Ic lockc ) -Lock -.Ar target-client , -see the -.Ic lock-server -command. -.It Ic lock-session Op Fl t Ar target-session -.D1 (alias: Ic locks ) -Lock all clients attached to -.Ar target-session . -.It Xo Ic new-session -.Op Fl AdDP -.Op Fl F Ar format -.Op Fl n Ar window-name -.Op Fl s Ar session-name -.Op Fl t Ar target-session -.Op Fl x Ar width -.Op Fl y Ar height -.Op Ar shell-command -.Xc -.D1 (alias: Ic new ) -Create a new session with name -.Ar session-name . -.Pp -The new session is attached to the current terminal unless -.Fl d -is given. -.Ar window-name -and -.Ar shell-command -are the name of and shell command to execute in the initial window. -If -.Fl d -is used, -.Fl x -and -.Fl y -specify the size of the initial window (80 by 24 if not given). -.Pp -If run from a terminal, any -.Xr termios 4 -special characters are saved and used for new windows in the new session. -.Pp -The -.Fl A -flag makes -.Ic new-session -behave like -.Ic attach-session -if -.Ar session-name -already exists; in the case, -.Fl D -behaves like -.Fl d -to -.Ic attach-session . -.Pp -If -.Fl t -is given, the new session is -.Em grouped -with -.Ar target-session . -This means they share the same set of windows - all windows from -.Ar target-session -are linked to the new session and any subsequent new windows or windows being -closed are applied to both sessions. -The current and previous window and any session options remain independent and -either session may be killed without affecting the other. -Giving -.Fl n -or -.Ar shell-command -are invalid if -.Fl t -is used. -.Pp -The -.Fl P -option prints information about the new session after it has been created. -By default, it uses the format -.Ql #{session_name}: -but a different format may be specified with -.Fl F . -.It Xo Ic refresh-client -.Op Fl S -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic refresh ) -Refresh the current client if bound to a key, or a single client if one is given -with -.Fl t . -If -.Fl S -is specified, only update the client's status bar. -.It Xo Ic rename-session -.Op Fl t Ar target-session -.Ar new-name -.Xc -.D1 (alias: Ic rename ) -Rename the session to -.Ar new-name . -.It Xo Ic show-messages -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic showmsgs ) -Any messages displayed on the status line are saved in a per-client message -log, up to a maximum of the limit set by the -.Ar message-limit -session option for the session attached to that client. -This command displays the log for -.Ar target-client . -.It Ic source-file Ar path -.D1 (alias: Ic source ) -Execute commands from -.Ar path . -.It Ic start-server -.D1 (alias: Ic start ) -Start the -.Nm -server, if not already running, without creating any sessions. -.It Xo Ic suspend-client -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic suspendc ) -Suspend a client by sending -.Dv SIGTSTP -(tty stop). -.It Xo Ic switch-client -.Op Fl lnpr -.Op Fl c Ar target-client -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic switchc ) -Switch the current session for client -.Ar target-client -to -.Ar target-session . -If -.Fl l , -.Fl n -or -.Fl p -is used, the client is moved to the last, next or previous session -respectively. -.Fl r -toggles whether a client is read-only (see the -.Ic attach-session -command). -.El -.Sh WINDOWS AND PANES -A -.Nm -window may be in one of several modes. -The default permits direct access to the terminal attached to the window. -The other is copy mode, which permits a section of a window or its -history to be copied to a -.Em paste buffer -for later insertion into another window. -This mode is entered with the -.Ic copy-mode -command, bound to -.Ql \&[ -by default. -It is also entered when a command that produces output, such as -.Ic list-keys , -is executed from a key binding. -.Pp -The keys available depend on whether emacs or vi mode is selected -(see the -.Ic mode-keys -option). -The following keys are supported as appropriate for the mode: -.Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent -.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" -.It Li "Back to indentation" Ta "^" Ta "M-m" -.It Li "Bottom of history" Ta "G" Ta "M-<" -.It Li "Clear selection" Ta "Escape" Ta "C-g" -.It Li "Copy selection" Ta "Enter" Ta "M-w" -.It Li "Cursor down" Ta "j" Ta "Down" -.It Li "Cursor left" Ta "h" Ta "Left" -.It Li "Cursor right" Ta "l" Ta "Right" -.It Li "Cursor to bottom line" Ta "L" Ta "" -.It Li "Cursor to middle line" Ta "M" Ta "M-r" -.It Li "Cursor to top line" Ta "H" Ta "M-R" -.It Li "Cursor up" Ta "k" Ta "Up" -.It Li "Delete entire line" Ta "d" Ta "C-u" -.It Li "Delete/Copy to end of line" Ta "D" Ta "C-k" -.It Li "End of line" Ta "$" Ta "C-e" -.It Li "Go to line" Ta ":" Ta "g" -.It Li "Half page down" Ta "C-d" Ta "M-Down" -.It Li "Half page up" Ta "C-u" Ta "M-Up" -.It Li "Jump forward" Ta "f" Ta "f" -.It Li "Jump to forward" Ta "t" Ta "" -.It Li "Jump backward" Ta "F" Ta "F" -.It Li "Jump to backward" Ta "T" Ta "" -.It Li "Jump again" Ta ";" Ta ";" -.It Li "Jump again in reverse" Ta "," Ta "," -.It Li "Next page" Ta "C-f" Ta "Page down" -.It Li "Next space" Ta "W" Ta "" -.It Li "Next space, end of word" Ta "E" Ta "" -.It Li "Next word" Ta "w" Ta "" -.It Li "Next word end" Ta "e" Ta "M-f" -.It Li "Paste buffer" Ta "p" Ta "C-y" -.It Li "Previous page" Ta "C-b" Ta "Page up" -.It Li "Previous word" Ta "b" Ta "M-b" -.It Li "Previous space" Ta "B" Ta "" -.It Li "Quit mode" Ta "q" Ta "Escape" -.It Li "Rectangle toggle" Ta "v" Ta "R" -.It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down" -.It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up" -.It Li "Search again" Ta "n" Ta "n" -.It Li "Search again in reverse" Ta "N" Ta "N" -.It Li "Search backward" Ta "?" Ta "C-r" -.It Li "Search forward" Ta "/" Ta "C-s" -.It Li "Start of line" Ta "0" Ta "C-a" -.It Li "Start selection" Ta "Space" Ta "C-Space" -.It Li "Top of history" Ta "g" Ta "M->" -.It Li "Transpose characters" Ta "" Ta "C-t" -.El -.Pp -The next and previous word keys use space and the -.Ql - , -.Ql _ -and -.Ql @ -characters as word delimiters by default, but this can be adjusted by -setting the -.Em word-separators -session option. -Next word moves to the start of the next word, next word end to the end of the -next word and previous word to the start of the previous word. -The three next and previous space keys work similarly but use a space alone as -the word separator. -.Pp -The jump commands enable quick movement within a line. -For instance, typing -.Ql f -followed by -.Ql / -will move the cursor to the next -.Ql / -character on the current line. -A -.Ql \&; -will then jump to the next occurrence. -.Pp -Commands in copy mode may be prefaced by an optional repeat count. -With vi key bindings, a prefix is entered using the number keys; with -emacs, the Alt (meta) key and a number begins prefix entry. -For example, to move the cursor forward by ten words, use -.Ql M-1 0 M-f -in emacs mode, and -.Ql 10w -in vi. -.Pp -When copying the selection, the repeat count indicates the buffer index to -replace, if used. -.Pp -Mode key bindings are defined in a set of named tables: -.Em vi-edit -and -.Em emacs-edit -for keys used when line editing at the command prompt; -.Em vi-choice -and -.Em emacs-choice -for keys used when choosing from lists (such as produced by the -.Ic choose-window -command); and -.Em vi-copy -and -.Em emacs-copy -used in copy mode. -The tables may be viewed with the -.Ic list-keys -command and keys modified or removed with -.Ic bind-key -and -.Ic unbind-key . -One command accepts an argument, -.Ic copy-pipe , -which copies the selection and pipes it to a command. -For example the following will bind -.Ql C-q -to copy the selection into -.Pa /tmp -as well as the paste buffer: -.Bd -literal -offset indent -bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" -.Ed -.Pp -The paste buffer key pastes the first line from the top paste buffer on the -stack. -.Pp -The synopsis for the -.Ic copy-mode -command is: -.Bl -tag -width Ds -.It Xo Ic copy-mode -.Op Fl u -.Op Fl t Ar target-pane -.Xc -Enter copy mode. -The -.Fl u -option scrolls one page up. -.El -.Pp -Each window displayed by -.Nm -may be split into one or more -.Em panes ; -each pane takes up a certain area of the display and is a separate terminal. -A window may be split into panes using the -.Ic split-window -command. -Windows may be split horizontally (with the -.Fl h -flag) or vertically. -Panes may be resized with the -.Ic resize-pane -command (bound to -.Ql C-up , -.Ql C-down -.Ql C-left -and -.Ql C-right -by default), the current pane may be changed with the -.Ic select-pane -command and the -.Ic rotate-window -and -.Ic swap-pane -commands may be used to swap panes without changing their position. -Panes are numbered beginning from zero in the order they are created. -.Pp -A number of preset -.Em layouts -are available. -These may be selected with the -.Ic select-layout -command or cycled with -.Ic next-layout -(bound to -.Ql Space -by default); once a layout is chosen, panes within it may be moved and resized -as normal. -.Pp -The following layouts are supported: -.Bl -tag -width Ds -.It Ic even-horizontal -Panes are spread out evenly from left to right across the window. -.It Ic even-vertical -Panes are spread evenly from top to bottom. -.It Ic main-horizontal -A large (main) pane is shown at the top of the window and the remaining panes -are spread from left to right in the leftover space at the bottom. -Use the -.Em main-pane-height -window option to specify the height of the top pane. -.It Ic main-vertical -Similar to -.Ic main-horizontal -but the large pane is placed on the left and the others spread from top to -bottom along the right. -See the -.Em main-pane-width -window option. -.It Ic tiled -Panes are spread out as evenly as possible over the window in both rows and -columns. -.El -.Pp -In addition, -.Ic select-layout -may be used to apply a previously used layout - the -.Ic list-windows -command displays the layout of each window in a form suitable for use with -.Ic select-layout . -For example: -.Bd -literal -offset indent -$ tmux list-windows -0: ksh [159x48] - layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} -$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} -.Ed -.Pp -.Nm -automatically adjusts the size of the layout for the current window size. -Note that a layout cannot be applied to a window with more panes than that -from which the layout was originally defined. -.Pp -Commands related to windows and panes are as follows: -.Bl -tag -width Ds -.It Xo Ic break-pane -.Op Fl dP -.Op Fl F Ar format -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic breakp ) -Break -.Ar target-pane -off from its containing window to make it the only pane in a new window. -If -.Fl d -is given, the new window does not become the current window. -The -.Fl P -option prints information about the new window after it has been created. -By default, it uses the format -.Ql #{session_name}:#{window_index} -but a different format may be specified with -.Fl F . -.It Xo Ic capture-pane -.Op Fl aepPq -.Op Fl b Ar buffer-index -.Op Fl E Ar end-line -.Op Fl S Ar start-line -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic capturep ) -Capture the contents of a pane. -If -.Fl p -is given, the output goes to stdout, otherwise to the buffer specified with -.Fl b -or a new buffer if omitted. -If -.Fl a -is given, the alternate screen is used, and the history is not accessible. -If no alternate screen exists, an error will be returned unless -.Fl q -is given. -If -.Fl e -is given, the output includes escape sequences for text and background -attributes. -.Fl C -also escapes non-printable characters as octal \exxx. -.Fl J -joins wrapped lines and preserves trailing spaces at each line's end. -.Fl P -captures only any output that the pane has received that is the beginning of an -as-yet incomplete escape sequence. -.Pp -.Fl S -and -.Fl E -specify the starting and ending line numbers, zero is the first line of the -visible pane and negative numbers are lines in the history. -The default is to capture only the visible contents of the pane. -.It Xo -.Ic choose-client -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into client choice mode, allowing a client to be selected -interactively from a list. -After a client is chosen, -.Ql %% -is replaced by the client -.Xr pty 4 -path in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "detach-client -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-list -.Op Fl l Ar items -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into list choice mode, allowing -.Ar items -to be selected. -.Ar items -can be a comma-separated list to display more than one item. -If an item has spaces, that entry must be quoted. -After an item is chosen, -.Ql %% -is replaced by the chosen item in the -.Ar template -and the result is executed as a command. -If -.Ar template -is not given, "run-shell '%%'" is used. -.Ar items -also accepts format specifiers. -For the meaning of this see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-session -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into session choice mode, where a session may be selected -interactively from a list. -When one is chosen, -.Ql %% -is replaced by the session name in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "switch-client -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-tree -.Op Fl suw -.Op Fl b Ar session-template -.Op Fl c Ar window-template -.Op Fl S Ar format -.Op Fl W Ar format -.Op Fl t Ar target-window -.Xc -Put a window into tree choice mode, where either sessions or windows may be -selected interactively from a list. -By default, windows belonging to a session are indented to show their -relationship to a session. -.Pp -Note that the -.Ic choose-window -and -.Ic choose-session -commands are wrappers around -.Ic choose-tree . -.Pp -If -.Fl s -is given, will show sessions. -If -.Fl w -is given, will show windows. -.Pp -By default, the tree is collapsed and sessions must be expanded to windows -with the right arrow key. -The -.Fl u -option will start with all sessions expanded instead. -.Pp -If -.Fl b -is given, will override the default session command. -Note that -.Ql %% -can be used and will be replaced with the session name. -The default option if not specified is "switch-client -t '%%'". -If -.Fl c -is given, will override the default window command. -Like -.Fl b , -.Ql %% -can be used and will be replaced with the session name and window index. -When a window is chosen from the list, the session command is run before the -window command. -.Pp -If -.Fl S -is given will display the specified format instead of the default session -format. -If -.Fl W -is given will display the specified format instead of the default window -format. -For the meaning of the -.Fl s -and -.Fl w -options, see the -.Sx FORMATS -section. -.Pp -This command works only if at least one client is attached. -.It Xo -.Ic choose-window -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into window choice mode, where a window may be chosen -interactively from a list. -After a window is selected, -.Ql %% -is replaced by the session name and window index in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "select-window -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Ic display-panes Op Fl t Ar target-client -.D1 (alias: Ic displayp) -Display a visible indicator of each pane shown by -.Ar target-client . -See the -.Ic display-panes-time , -.Ic display-panes-colour , -and -.Ic display-panes-active-colour -session options. -While the indicator is on screen, a pane may be selected with the -.Ql 0 -to -.Ql 9 -keys. -.It Xo Ic find-window -.Op Fl CNT -.Op Fl F Ar format -.Op Fl t Ar target-window -.Ar match-string -.Xc -.D1 (alias: Ic findw ) -Search for the -.Xr fnmatch 3 -pattern -.Ar match-string -in window names, titles, and visible content (but not history). -The flags control matching behavior: -.Fl C -matches only visible window contents, -.Fl N -matches only the window name and -.Fl T -matches only the window title. -The default is -.Fl CNT . -If only one window is matched, it'll be automatically selected, -otherwise a choice list is shown. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo Ic join-pane -.Op Fl bdhv -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic joinp ) -Like -.Ic split-window , -but instead of splitting -.Ar dst-pane -and creating a new pane, split it and move -.Ar src-pane -into the space. -This can be used to reverse -.Ic break-pane . -The -.Fl b -option causes -.Ar src-pane -to be joined to left of or above -.Ar dst-pane . -.It Xo Ic kill-pane -.Op Fl a -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic killp ) -Destroy the given pane. -If no panes remain in the containing window, it is also destroyed. -The -.Fl a -option kills all but the pane given with -.Fl t . -.It Xo Ic kill-window -.Op Fl a -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic killw ) -Kill the current window or the window at -.Ar target-window , -removing it from any sessions to which it is linked. -The -.Fl a -option kills all but the window given with -.Fl t . -.It Ic last-pane Op Fl t Ar target-window -.D1 (alias: Ic lastp ) -Select the last (previously selected) pane. -.It Ic last-window Op Fl t Ar target-session -.D1 (alias: Ic last ) -Select the last (previously selected) window. -If no -.Ar target-session -is specified, select the last window of the current session. -.It Xo Ic link-window -.Op Fl dk -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic linkw ) -Link the window at -.Ar src-window -to the specified -.Ar dst-window . -If -.Ar dst-window -is specified and no such window exists, the -.Ar src-window -is linked there. -If -.Fl k -is given and -.Ar dst-window -exists, it is killed, otherwise an error is generated. -If -.Fl d -is given, the newly linked window is not selected. -.It Xo Ic list-panes -.Op Fl as -.Op Fl F Ar format -.Op Fl t Ar target -.Xc -.D1 (alias: Ic lsp ) -If -.Fl a -is given, -.Ar target -is ignored and all panes on the server are listed. -If -.Fl s -is given, -.Ar target -is a session (or the current session). -If neither is given, -.Ar target -is a window (or the current window). -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic list-windows -.Op Fl a -.Op Fl F Ar format -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic lsw ) -If -.Fl a -is given, list all windows on the server. -Otherwise, list windows in the current session or in -.Ar target-session . -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic move-pane -.Op Fl bdhv -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic movep ) -Like -.Ic join-pane , -but -.Ar src-pane -and -.Ar dst-pane -may belong to the same window. -.It Xo Ic move-window -.Op Fl rdk -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic movew ) -This is similar to -.Ic link-window , -except the window at -.Ar src-window -is moved to -.Ar dst-window . -With -.Fl r , -all windows in the session are renumbered in sequential order, respecting -the -.Ic base-index -option. -.It Xo Ic new-window -.Op Fl adkP -.Op Fl c Ar start-directory -.Op Fl F Ar format -.Op Fl n Ar window-name -.Op Fl t Ar target-window -.Op Ar shell-command -.Xc -.D1 (alias: Ic neww ) -Create a new window. -With -.Fl a , -the new window is inserted at the next index up from the specified -.Ar target-window , -moving windows up if necessary, -otherwise -.Ar target-window -is the new window location. -.Pp -If -.Fl d -is given, the session does not make the new window the current window. -.Ar target-window -represents the window to be created; if the target already exists an error is -shown, unless the -.Fl k -flag is used, in which case it is destroyed. -.Ar shell-command -is the command to execute. -If -.Ar shell-command -is not specified, the value of the -.Ic default-command -option is used. -.Fl c -specifies the working directory in which the new window is created. -It may have an absolute path or one of the following values (or a subdirectory): -.Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent -.It Li "Empty string" Ta "Current pane's directory" -.It Li "~" Ta "User's home directory" -.It Li "-" Ta "Where session was started" -.It Li "." Ta "Where server was started" -.El -.Pp -When the shell command completes, the window closes. -See the -.Ic remain-on-exit -option to change this behaviour. -.Pp -The -.Ev TERM -environment variable must be set to -.Dq screen -for all programs running -.Em inside -.Nm . -New windows will automatically have -.Dq TERM=screen -added to their environment, but care must be taken not to reset this in shell -start-up files. -.Pp -The -.Fl P -option prints information about the new window after it has been created. -By default, it uses the format -.Ql #{session_name}:#{window_index} -but a different format may be specified with -.Fl F . -.It Ic next-layout Op Fl t Ar target-window -.D1 (alias: Ic nextl ) -Move a window to the next layout and rearrange the panes to fit. -.It Xo Ic next-window -.Op Fl a -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic next ) -Move to the next window in the session. -If -.Fl a -is used, move to the next window with an alert. -.It Xo Ic pipe-pane -.Op Fl o -.Op Fl t Ar target-pane -.Op Ar shell-command -.Xc -.D1 (alias: Ic pipep ) -Pipe any output sent by the program in -.Ar target-pane -to a shell command. -A pane may only be piped to one command at a time, any existing pipe is -closed before -.Ar shell-command -is executed. -The -.Ar shell-command -string may contain the special character sequences supported by the -.Ic status-left -option. -If no -.Ar shell-command -is given, the current pipe (if any) is closed. -.Pp -The -.Fl o -option only opens a new pipe if no previous pipe exists, allowing a pipe to -be toggled with a single key, for example: -.Bd -literal -offset indent -bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' -.Ed -.It Xo Ic previous-layout -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic prevl ) -Move to the previous layout in the session. -.It Xo Ic previous-window -.Op Fl a -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic prev ) -Move to the previous window in the session. -With -.Fl a , -move to the previous window with an alert. -.It Xo Ic rename-window -.Op Fl t Ar target-window -.Ar new-name -.Xc -.D1 (alias: Ic renamew ) -Rename the current window, or the window at -.Ar target-window -if specified, to -.Ar new-name . -.It Xo Ic resize-pane -.Op Fl DLRUZ -.Op Fl t Ar target-pane -.Op Fl x Ar width -.Op Fl y Ar height -.Op Ar adjustment -.Xc -.D1 (alias: Ic resizep ) -Resize a pane, up, down, left or right by -.Ar adjustment -with -.Fl U , -.Fl D , -.Fl L -or -.Fl R , -or -to an absolute size -with -.Fl x -or -.Fl y . -The -.Ar adjustment -is given in lines or cells (the default is 1). -.Pp -With -.Fl Z , -the active pane is toggled between zoomed (occupying the whole of the window) -and unzoomed (its normal position in the layout). -.It Xo Ic respawn-pane -.Op Fl k -.Op Fl t Ar target-pane -.Op Ar shell-command -.Xc -.D1 (alias: Ic respawnp ) -Reactivate a pane in which the command has exited (see the -.Ic remain-on-exit -window option). -If -.Ar shell-command -is not given, the command used when the pane was created is executed. -The pane must be already inactive, unless -.Fl k -is given, in which case any existing command is killed. -.It Xo Ic respawn-window -.Op Fl k -.Op Fl t Ar target-window -.Op Ar shell-command -.Xc -.D1 (alias: Ic respawnw ) -Reactivate a window in which the command has exited (see the -.Ic remain-on-exit -window option). -If -.Ar shell-command -is not given, the command used when the window was created is executed. -The window must be already inactive, unless -.Fl k -is given, in which case any existing command is killed. -.It Xo Ic rotate-window -.Op Fl DU -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic rotatew ) -Rotate the positions of the panes within a window, either upward (numerically -lower) with -.Fl U -or downward (numerically higher). -.It Xo Ic select-layout -.Op Fl np -.Op Fl t Ar target-window -.Op Ar layout-name -.Xc -.D1 (alias: Ic selectl ) -Choose a specific layout for a window. -If -.Ar layout-name -is not given, the last preset layout used (if any) is reapplied. -.Fl n -and -.Fl p -are equivalent to the -.Ic next-layout -and -.Ic previous-layout -commands. -.It Xo Ic select-pane -.Op Fl lDLRU -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic selectp ) -Make pane -.Ar target-pane -the active pane in window -.Ar target-window . -If one of -.Fl D , -.Fl L , -.Fl R , -or -.Fl U -is used, respectively the pane below, to the left, to the right, or above the -target pane is used. -.Fl l -is the same as using the -.Ic last-pane -command. -.It Xo Ic select-window -.Op Fl lnpT -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic selectw ) -Select the window at -.Ar target-window . -.Fl l , -.Fl n -and -.Fl p -are equivalent to the -.Ic last-window , -.Ic next-window -and -.Ic previous-window -commands. -If -.Fl T -is given and the selected window is already the current window, -the command behaves like -.Ic last-window . -.It Xo Ic split-window -.Op Fl dhvP -.Op Fl c Ar start-directory -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl t Ar target-pane -.Op Ar shell-command -.Op Fl F Ar format -.Xc -.D1 (alias: Ic splitw ) -Create a new pane by splitting -.Ar target-pane : -.Fl h -does a horizontal split and -.Fl v -a vertical split; if neither is specified, -.Fl v -is assumed. -The -.Fl l -and -.Fl p -options specify the size of the new pane in lines (for vertical split) or in -cells (for horizontal split), or as a percentage, respectively. -All other options have the same meaning as for the -.Ic new-window -command. -.It Xo Ic swap-pane -.Op Fl dDU -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic swapp ) -Swap two panes. -If -.Fl U -is used and no source pane is specified with -.Fl s , -.Ar dst-pane -is swapped with the previous pane (before it numerically); -.Fl D -swaps with the next pane (after it numerically). -.Fl d -instructs -.Nm -not to change the active pane. -.It Xo Ic swap-window -.Op Fl d -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic swapw ) -This is similar to -.Ic link-window , -except the source and destination windows are swapped. -It is an error if no window exists at -.Ar src-window . -.It Xo Ic unlink-window -.Op Fl k -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic unlinkw ) -Unlink -.Ar target-window . -Unless -.Fl k -is given, a window may be unlinked only if it is linked to multiple sessions - -windows may not be linked to no sessions; -if -.Fl k -is specified and the window is linked to only one session, it is unlinked and -destroyed. -.El -.Sh KEY BINDINGS -.Nm -allows a command to be bound to most keys, with or without a prefix key. -When specifying keys, most represent themselves (for example -.Ql A -to -.Ql Z ) . -Ctrl keys may be prefixed with -.Ql C- -or -.Ql ^ , -and Alt (meta) with -.Ql M- . -In addition, the following special key names are accepted: -.Em Up , -.Em Down , -.Em Left , -.Em Right , -.Em BSpace , -.Em BTab , -.Em DC -(Delete), -.Em End , -.Em Enter , -.Em Escape , -.Em F1 -to -.Em F20 , -.Em Home , -.Em IC -(Insert), -.Em NPage/PageDown/PgDn , -.Em PPage/PageUp/PgUp , -.Em Space , -and -.Em Tab . -Note that to bind the -.Ql \&" -or -.Ql ' -keys, quotation marks are necessary, for example: -.Bd -literal -offset indent -bind-key '"' split-window -bind-key "'" new-window -.Ed -.Pp -Commands related to key bindings are as follows: -.Bl -tag -width Ds -.It Xo Ic bind-key -.Op Fl cnr -.Op Fl t Ar key-table -.Ar key Ar command Op Ar arguments -.Xc -.D1 (alias: Ic bind ) -Bind key -.Ar key -to -.Ar command . -By default (without -.Fl t ) -the primary key bindings are modified (those normally activated with the prefix -key); in this case, if -.Fl n -is specified, it is not necessary to use the prefix key, -.Ar command -is bound to -.Ar key -alone. -The -.Fl r -flag indicates this key may repeat, see the -.Ic repeat-time -option. -.Pp -If -.Fl t -is present, -.Ar key -is bound in -.Ar key-table : -the binding for command mode with -.Fl c -or for normal mode without. -To view the default bindings and possible commands, see the -.Ic list-keys -command. -.It Ic list-keys Op Fl t Ar key-table -.D1 (alias: Ic lsk ) -List all key bindings. -Without -.Fl t -the primary key bindings - those executed when preceded by the prefix key - -are printed. -.Pp -With -.Fl t , -the key bindings in -.Ar key-table -are listed; this may be one of: -.Em vi-edit , -.Em emacs-edit , -.Em vi-choice , -.Em emacs-choice , -.Em vi-copy -or -.Em emacs-copy . -.It Xo Ic send-keys -.Op Fl lR -.Op Fl t Ar target-pane -.Ar key Ar ... -.Xc -.D1 (alias: Ic send ) -Send a key or keys to a window. -Each argument -.Ar key -is the name of the key (such as -.Ql C-a -or -.Ql npage -) to send; if the string is not recognised as a key, it is sent as a series of -characters. -The -.Fl l -flag disables key name lookup and sends the keys literally. -All arguments are sent sequentially from first to last. -The -.Fl R -flag causes the terminal state to be reset. -.It Xo Ic send-prefix -.Op Fl 2 -.Op Fl t Ar target-pane -.Xc -Send the prefix key, or with -.Fl 2 -the secondary prefix key, to a window as if it was pressed. -.It Xo Ic unbind-key -.Op Fl acn -.Op Fl t Ar key-table -.Ar key -.Xc -.D1 (alias: Ic unbind ) -Unbind the command bound to -.Ar key . -Without -.Fl t -the primary key bindings are modified; in this case, if -.Fl n -is specified, the command bound to -.Ar key -without a prefix (if any) is removed. -If -.Fl a -is present, all key bindings are removed. -.Pp -If -.Fl t -is present, -.Ar key -in -.Ar key-table -is unbound: the binding for command mode with -.Fl c -or for normal mode without. -.El -.Sh OPTIONS -The appearance and behaviour of -.Nm -may be modified by changing the value of various options. -There are three types of option: -.Em server options , -.Em session options -and -.Em window options . -.Pp -The -.Nm -server has a set of global options which do not apply to any particular -window or session. -These are altered with the -.Ic set-option -.Fl s -command, or displayed with the -.Ic show-options -.Fl s -command. -.Pp -In addition, each individual session may have a set of session options, and -there is a separate set of global session options. -Sessions which do not have a particular option configured inherit the value -from the global session options. -Session options are set or unset with the -.Ic set-option -command and may be listed with the -.Ic show-options -command. -The available server and session options are listed under the -.Ic set-option -command. -.Pp -Similarly, a set of window options is attached to each window, and there is -a set of global window options from which any unset options are inherited. -Window options are altered with the -.Ic set-window-option -command and can be listed with the -.Ic show-window-options -command. -All window options are documented with the -.Ic set-window-option -command. -.Pp -.Nm -also supports user options which are prefixed with a -.Ql \&@ . -User options may have any name, so long as they are prefixed with -.Ql \&@ , -and be set to any string. -For example -.Bd -literal -offset indent -$ tmux setw -q @foo "abc123" -$ tmux showw -v @foo -abc123 -.Ed -.Pp -Commands which set options are as follows: -.Bl -tag -width Ds -.It Xo Ic set-option -.Op Fl agoqsuw -.Op Fl t Ar target-session | Ar target-window -.Ar option Ar value -.Xc -.D1 (alias: Ic set ) -Set a window option with -.Fl w -(equivalent to the -.Ic set-window-option -command), -a server option with -.Fl s , -otherwise a session option. -.Pp -If -.Fl g -is specified, the global session or window option is set. -With -.Fl a , -and if the option expects a string, -.Ar value -is appended to the existing setting. -The -.Fl u -flag unsets an option, so a session inherits the option from the global -options. -It is not possible to unset a global option. -.Pp -The -.Fl o -flag prevents setting an option that is already set. -.Pp -The -.Fl q -flag suppresses the informational message (as if the -.Ic quiet -server option was set). -.Pp -Available window options are listed under -.Ic set-window-option . -.Pp -.Ar value -depends on the option and may be a number, a string, or a flag (on, off, or -omitted to toggle). -.Pp -Available server options are: -.Bl -tag -width Ds -.It Ic buffer-limit Ar number -Set the number of buffers; as new buffers are added to the top of the stack, -old ones are removed from the bottom if necessary to maintain this maximum -length. -.It Ic escape-time Ar time -Set the time in milliseconds for which -.Nm -waits after an escape is input to determine if it is part of a function or meta -key sequences. -The default is 500 milliseconds. -.It Xo Ic exit-unattached -.Op Ic on | off -.Xc -If enabled, the server will exit when there are no attached clients. -.It Xo Ic quiet -.Op Ic on | off -.Xc -Enable or disable the display of various informational messages (see also the -.Fl q -command line flag). -.It Xo Ic set-clipboard -.Op Ic on | off -.Xc -Attempt to set the terminal clipboard content using the -\ee]52;...\e007 -.Xr xterm 1 -escape sequences. -This option is on by default if there is an -.Em \&Ms -entry in the -.Xr terminfo 5 -description for the client terminal. -Note that this feature needs to be enabled in -.Xr xterm 1 -by setting the resource: -.Bd -literal -offset indent -disallowedWindowOps: 20,21,SetXprop -.Ed -.Pp -Or changing this property from the -.Xr xterm 1 -interactive menu when required. -.El -.Pp -Available session options are: -.Bl -tag -width Ds -.It Ic assume-paste-time Ar milliseconds -If keys are entered faster than one in -.Ar milliseconds , -they are assumed to have been pasted rather than typed and -.Nm -key bindings are not processed. -The default is one millisecond and zero disables. -.It Ic base-index Ar index -Set the base index from which an unused index should be searched when a new -window is created. -The default is zero. -.It Xo Ic bell-action -.Op Ic any | none | current -.Xc -Set action on window bell. -.Ic any -means a bell in any window linked to a session causes a bell in the current -window of that session, -.Ic none -means all bells are ignored and -.Ic current -means only bells in windows other than the current window are ignored. -.It Xo Ic bell-on-alert -.Op Ic on | off -.Xc -If on, ring the terminal bell when an alert -occurs. -.It Ic default-command Ar shell-command -Set the command used for new windows (if not specified when the window is -created) to -.Ar shell-command , -which may be any -.Xr sh 1 -command. -The default is an empty string, which instructs -.Nm -to create a login shell using the value of the -.Ic default-shell -option. -.It Ic default-path Ar path -Set the default working directory for new panes. -If empty (the default), the working directory is determined from the process -running in the active pane, from the command line environment or from the -working directory where the session was created. -Otherwise the same options are available as for the -.Fl c -flag to -.Ic new-window . -.It Ic default-shell Ar path -Specify the default shell. -This is used as the login shell for new windows when the -.Ic default-command -option is set to empty, and must be the full path of the executable. -When started -.Nm -tries to set a default value from the first suitable of the -.Ev SHELL -environment variable, the shell returned by -.Xr getpwuid 3 , -or -.Pa /bin/sh . -This option should be configured when -.Nm -is used as a login shell. -.It Ic default-terminal Ar terminal -Set the default terminal for new windows created in this session - the -default value of the -.Ev TERM -environment variable. -For -.Nm -to work correctly, this -.Em must -be set to -.Ql screen -or a derivative of it. -.It Xo Ic destroy-unattached -.Op Ic on | off -.Xc -If enabled and the session is no longer attached to any clients, it is -destroyed. -.It Xo Ic detach-on-destroy -.Op Ic on | off -.Xc -If on (the default), the client is detached when the session it is attached to -is destroyed. -If off, the client is switched to the most recently active of the remaining -sessions. -.It Ic display-panes-active-colour Ar colour -Set the colour used by the -.Ic display-panes -command to show the indicator for the active pane. -.It Ic display-panes-colour Ar colour -Set the colour used by the -.Ic display-panes -command to show the indicators for inactive panes. -.It Ic display-panes-time Ar time -Set the time in milliseconds for which the indicators shown by the -.Ic display-panes -command appear. -.It Ic display-time Ar time -Set the amount of time for which status line messages and other on-screen -indicators are displayed. -.Ar time -is in milliseconds. -.It Ic history-limit Ar lines -Set the maximum number of lines held in window history. -This setting applies only to new windows - existing window histories are not -resized and retain the limit at the point they were created. -.It Ic lock-after-time Ar number -Lock the session (like the -.Ic lock-session -command) after -.Ar number -seconds of inactivity, or the entire server (all sessions) if the -.Ic lock-server -option is set. -The default is not to lock (set to 0). -.It Ic lock-command Ar shell-command -Command to run when locking each client. -The default is to run -.Xr lock 1 -with -.Fl np . -.It Xo Ic lock-server -.Op Ic on | off -.Xc -If this option is -.Ic on -(the default), -instead of each session locking individually as each has been -idle for -.Ic lock-after-time , -the entire server will lock after -.Em all -sessions would have locked. -This has no effect as a session option; it must be set as a global option. -.It Ic message-attr Ar attributes -Set status line message attributes, where -.Ar attributes -is either -.Ic none -or a comma-delimited list of one or more of: -.Ic bright -(or -.Ic bold ) , -.Ic dim , -.Ic underscore , -.Ic blink , -.Ic reverse , -.Ic hidden , -or -.Ic italics . -.It Ic message-bg Ar colour -Set status line message background colour, where -.Ar colour -is one of: -.Ic black , -.Ic red , -.Ic green , -.Ic yellow , -.Ic blue , -.Ic magenta , -.Ic cyan , -.Ic white , -aixterm bright variants (if supported: -.Ic brightred , -.Ic brightgreen , -and so on), -.Ic colour0 -to -.Ic colour255 -from the 256-colour set, -.Ic default , -or a hexadecimal RGB string such as -.Ql #ffffff , -which chooses the closest match from the default 256-colour set. -.It Ic message-command-attr Ar attributes -Set status line message attributes when in command mode. -.It Ic message-command-bg Ar colour -Set status line message background colour when in command mode. -.It Ic message-command-fg Ar colour -Set status line message foreground colour when in command mode. -.It Ic message-fg Ar colour -Set status line message foreground colour. -.It Ic message-limit Ar number -Set the number of error or information messages to save in the message log for -each client. -The default is 20. -.It Xo Ic mouse-resize-pane -.Op Ic on | off -.Xc -If on, -.Nm -captures the mouse and allows panes to be resized by dragging on their borders. -.It Xo Ic mouse-select-pane -.Op Ic on | off -.Xc -If on, -.Nm -captures the mouse and when a window is split into multiple panes the mouse may -be used to select the current pane. -The mouse click is also passed through to the application as normal. -.It Xo Ic mouse-select-window -.Op Ic on | off -.Xc -If on, clicking the mouse on a window name in the status line will select that -window. -.It Xo Ic mouse-utf8 -.Op Ic on | off -.Xc -If enabled, request mouse input as UTF-8 on UTF-8 terminals. -.It Ic pane-active-border-bg Ar colour -.It Ic pane-active-border-fg Ar colour -Set the pane border colour for the currently active pane. -.It Ic pane-border-bg Ar colour -.It Ic pane-border-fg Ar colour -Set the pane border colour for panes aside from the active pane. -.It Ic prefix Ar key -Set the key accepted as a prefix key. -.It Ic prefix2 Ar key -Set a secondary key accepted as a prefix key. -.It Xo Ic renumber-windows -.Op Ic on | off -.Xc -If on, when a window is closed in a session, automatically renumber the other -windows in numerical order. -This respects the -.Ic base-index -option if it has been set. -If off, do not renumber the windows. -.It Ic repeat-time Ar time -Allow multiple commands to be entered without pressing the prefix-key again -in the specified -.Ar time -milliseconds (the default is 500). -Whether a key repeats may be set when it is bound using the -.Fl r -flag to -.Ic bind-key . -Repeat is enabled for the default keys bound to the -.Ic resize-pane -command. -.It Xo Ic set-remain-on-exit -.Op Ic on | off -.Xc -Set the -.Ic remain-on-exit -window option for any windows first created in this session. -When this option is true, windows in which the running program has -exited do not close, instead remaining open but inactivate. -Use the -.Ic respawn-window -command to reactivate such a window, or the -.Ic kill-window -command to destroy it. -.It Xo Ic set-titles -.Op Ic on | off -.Xc -Attempt to set the client terminal title using the -.Em tsl -and -.Em fsl -.Xr terminfo 5 -entries if they exist. -.Nm -automatically sets these to the \ee]2;...\e007 sequence if -the terminal appears to be an xterm. -This option is off by default. -Note that elinks -will only attempt to set the window title if the STY environment -variable is set. -.It Ic set-titles-string Ar string -String used to set the window title if -.Ic set-titles -is on. -Character sequences are replaced as for the -.Ic status-left -option. -.It Xo Ic status -.Op Ic on | off -.Xc -Show or hide the status line. -.It Ic status-attr Ar attributes -Set status line attributes. -.It Ic status-bg Ar colour -Set status line background colour. -.It Ic status-fg Ar colour -Set status line foreground colour. -.It Ic status-interval Ar interval -Update the status bar every -.Ar interval -seconds. -By default, updates will occur every 15 seconds. -A setting of zero disables redrawing at interval. -.It Xo Ic status-justify -.Op Ic left | centre | right -.Xc -Set the position of the window list component of the status line: left, centre -or right justified. -.It Xo Ic status-keys -.Op Ic vi | emacs -.Xc -Use vi or emacs-style -key bindings in the status line, for example at the command prompt. -The default is emacs, unless the -.Ev VISUAL -or -.Ev EDITOR -environment variables are set and contain the string -.Ql vi . -.It Ic status-left Ar string -Display -.Ar string -to the left of the status bar. -.Ar string -will be passed through -.Xr strftime 3 -before being used. -By default, the session name is shown. -.Ar string -may contain any of the following special character sequences: -.Bl -column "Character pair" "Replaced with" -offset indent -.It Sy "Character pair" Ta Sy "Replaced with" -.It Li "#(shell-command)" Ta "First line of the command's output" -.It Li "#[attributes]" Ta "Colour or attribute change" -.It Li "#H" Ta "Hostname of local host" -.It Li "#h" Ta "Hostname of local host without the domain name" -.It Li "#F" Ta "Current window flag" -.It Li "#I" Ta "Current window index" -.It Li "#D" Ta "Current pane unique identifier" -.It Li "#P" Ta "Current pane index" -.It Li "#S" Ta "Session name" -.It Li "#T" Ta "Current pane title" -.It Li "#W" Ta "Current window name" -.It Li "##" Ta "A literal" Ql # -.El -.Pp -The #(shell-command) form executes -.Ql shell-command -and inserts the first line of its output. -Note that shell commands are only executed once at the interval specified by -the -.Ic status-interval -option: if the status line is redrawn in the meantime, the previous result is -used. -Shell commands are executed with the -.Nm -global environment set (see the -.Sx ENVIRONMENT -section). -.Pp -For details on how the names and titles can be set see the -.Sx "NAMES AND TITLES" -section. -.Pp -#[attributes] allows a comma-separated list of attributes to be specified, -these may be -.Ql fg=colour -to set the foreground colour, -.Ql bg=colour -to set the background colour, the name of one of the attributes (listed under -the -.Ic message-attr -option) to turn an attribute on, or an attribute prefixed with -.Ql no -to turn one off, for example -.Ic nobright . -Examples are: -.Bd -literal -offset indent -#(sysctl vm.loadavg) -#[fg=yellow,bold]#(apm -l)%%#[default] [#S] -.Ed -.Pp -Where appropriate, special character sequences may be prefixed with a number to -specify the maximum length, for example -.Ql #24T . -.Pp -By default, UTF-8 in -.Ar string -is not interpreted, to enable UTF-8, use the -.Ic status-utf8 -option. -.It Ic status-left-attr Ar attributes -Set the attribute of the left part of the status line. -.It Ic status-left-bg Ar colour -Set the background colour of the left part of the status line. -.It Ic status-left-fg Ar colour -Set the foreground colour of the left part of the status line. -.It Ic status-left-length Ar length -Set the maximum -.Ar length -of the left component of the status bar. -The default is 10. -.It Xo Ic status-position -.Op Ic top | bottom -.Xc -Set the position of the status line. -.It Ic status-right Ar string -Display -.Ar string -to the right of the status bar. -By default, the current window title in double quotes, the date and the time -are shown. -As with -.Ic status-left , -.Ar string -will be passed to -.Xr strftime 3 , -character pairs are replaced, and UTF-8 is dependent on the -.Ic status-utf8 -option. -.It Ic status-right-attr Ar attributes -Set the attribute of the right part of the status line. -.It Ic status-right-bg Ar colour -Set the background colour of the right part of the status line. -.It Ic status-right-fg Ar colour -Set the foreground colour of the right part of the status line. -.It Ic status-right-length Ar length -Set the maximum -.Ar length -of the right component of the status bar. -The default is 40. -.It Xo Ic status-utf8 -.Op Ic on | off -.Xc -Instruct -.Nm -to treat top-bit-set characters in the -.Ic status-left -and -.Ic status-right -strings as UTF-8; notably, this is important for wide characters. -This option defaults to off. -.It Ic terminal-overrides Ar string -Contains a list of entries which override terminal descriptions read using -.Xr terminfo 5 . -.Ar string -is a comma-separated list of items each a colon-separated string made up of a -terminal type pattern (matched using -.Xr fnmatch 3 ) -and a set of -.Em name=value -entries. -.Pp -For example, to set the -.Ql clear -.Xr terminfo 5 -entry to -.Ql \ee[H\ee[2J -for all terminal types and the -.Ql dch1 -entry to -.Ql \ee[P -for the -.Ql rxvt -terminal type, the option could be set to the string: -.Bd -literal -offset indent -"*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P" -.Ed -.Pp -The terminal entry value is passed through -.Xr strunvis 3 -before interpretation. -The default value forcibly corrects the -.Ql colors -entry for terminals which support 88 or 256 colours: -.Bd -literal -offset indent -"*88col*:colors=88,*256col*:colors=256,xterm*:XT" -.Ed -.It Ic update-environment Ar variables -Set a space-separated string containing a list of environment variables to be -copied into the session environment when a new session is created or an -existing session is attached. -Any variables that do not exist in the source environment are set to be -removed from the session environment (as if -.Fl r -was given to the -.Ic set-environment -command). -The default is -"DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID -XAUTHORITY". -.It Xo Ic visual-activity -.Op Ic on | off -.Xc -If on, display a status line message when activity occurs in a window -for which the -.Ic monitor-activity -window option is enabled. -.It Xo Ic visual-bell -.Op Ic on | off -.Xc -If this option is on, a message is shown on a bell instead of it being passed -through to the terminal (which normally makes a sound). -Also see the -.Ic bell-action -option. -.It Xo Ic visual-content -.Op Ic on | off -.Xc -Like -.Ic visual-activity , -display a message when content is present in a window -for which the -.Ic monitor-content -window option is enabled. -.It Xo Ic visual-silence -.Op Ic on | off -.Xc -If -.Ic monitor-silence -is enabled, prints a message after the interval has expired on a given window. -.It Ic word-separators Ar string -Sets the session's conception of what characters are considered word -separators, for the purposes of the next and previous word commands in -copy mode. -The default is -.Ql \ -_@ . -.El -.It Xo Ic set-window-option -.Op Fl agoqu -.Op Fl t Ar target-window -.Ar option Ar value -.Xc -.D1 (alias: Ic setw ) -Set a window option. -The -.Fl a , -.Fl g , -.Fl o , -.Fl q -and -.Fl u -flags work similarly to the -.Ic set-option -command. -.Pp -Supported window options are: -.Pp -.Bl -tag -width Ds -compact -.It Xo Ic aggressive-resize -.Op Ic on | off -.Xc -Aggressively resize the chosen window. -This means that -.Nm -will resize the window to the size of the smallest session for which it is the -current window, rather than the smallest session to which it is attached. -The window may resize when the current window is changed on another sessions; -this option is good for full-screen programs which support -.Dv SIGWINCH -and poor for interactive programs such as shells. -.Pp -.It Xo Ic allow-rename -.Op Ic on | off -.Xc -Allow programs to change the window name using a terminal escape -sequence (\\033k...\\033\\\\). -The default is on. -.Pp -.It Xo Ic alternate-screen -.Op Ic on | off -.Xc -This option configures whether programs running inside -.Nm -may use the terminal alternate screen feature, which allows the -.Em smcup -and -.Em rmcup -.Xr terminfo 5 -capabilities. -The alternate screen feature preserves the contents of the window when an -interactive application starts and restores it on exit, so that any output -visible before the application starts reappears unchanged after it exits. -The default is on. -.Pp -.It Xo Ic automatic-rename -.Op Ic on | off -.Xc -Control automatic window renaming. -When this setting is enabled, -.Nm -will attempt - on supported platforms - to rename the window to reflect the -command currently running in it. -This flag is automatically disabled for an individual window when a name -is specified at creation with -.Ic new-window -or -.Ic new-session , -or later with -.Ic rename-window , -or with a terminal escape sequence. -It may be switched off globally with: -.Bd -literal -offset indent -set-window-option -g automatic-rename off -.Ed -.Pp -.It Ic c0-change-interval Ar interval -.It Ic c0-change-trigger Ar trigger -These two options configure a simple form of rate limiting for a pane. -If -.Nm -sees more than -.Ar trigger -C0 sequences that modify the screen (for example, carriage returns, linefeeds -or backspaces) in one millisecond, it will stop updating the pane immediately and -instead redraw it entirely every -.Ar interval -milliseconds. -This helps to prevent fast output (such as -.Xr yes 1 -overwhelming the terminal). -The default is a trigger of 250 and an interval of 100. -A trigger of zero disables the rate limiting. -.Pp -.It Ic clock-mode-colour Ar colour -Set clock colour. -.Pp -.It Xo Ic clock-mode-style -.Op Ic 12 | 24 -.Xc -Set clock hour format. -.Pp -.It Ic force-height Ar height -.It Ic force-width Ar width -Prevent -.Nm -from resizing a window to greater than -.Ar width -or -.Ar height . -A value of zero restores the default unlimited setting. -.Pp -.It Ic main-pane-height Ar height -.It Ic main-pane-width Ar width -Set the width or height of the main (left or top) pane in the -.Ic main-horizontal -or -.Ic main-vertical -layouts. -.Pp -.It Ic mode-attr Ar attributes -Set window modes attributes. -.Pp -.It Ic mode-bg Ar colour -Set window modes background colour. -.Pp -.It Ic mode-fg Ar colour -Set window modes foreground colour. -.Pp -.It Xo Ic mode-keys -.Op Ic vi | emacs -.Xc -Use vi or emacs-style key bindings in copy and choice modes. -As with the -.Ic status-keys -option, the default is emacs, unless -.Ev VISUAL -or -.Ev EDITOR -contains -.Ql vi . -.Pp -.It Xo Ic mode-mouse -.Op Ic on | off | copy-mode -.Xc -Mouse state in modes. -If on, the mouse may be used to enter copy mode and copy a selection by -dragging, to enter copy mode and scroll with the mouse wheel, or to select an -option in choice mode. -If set to -.Em copy-mode , -the mouse behaves as set to on, but cannot be used to enter copy -mode. -.Pp -.It Xo Ic monitor-activity -.Op Ic on | off -.Xc -Monitor for activity in the window. -Windows with activity are highlighted in the status line. -.Pp -.It Ic monitor-content Ar match-string -Monitor content in the window. -When -.Xr fnmatch 3 -pattern -.Ar match-string -appears in the window, it is highlighted in the status line. -.Pp -.It Xo Ic monitor-silence -.Op Ic interval -.Xc -Monitor for silence (no activity) in the window within -.Ic interval -seconds. -Windows that have been silent for the interval are highlighted in the -status line. -An interval of zero disables the monitoring. -.Pp -.It Ic other-pane-height Ar height -Set the height of the other panes (not the main pane) in the -.Ic main-horizontal -layout. -If this option is set to 0 (the default), it will have no effect. -If both the -.Ic main-pane-height -and -.Ic other-pane-height -options are set, the main pane will grow taller to make the other panes the -specified height, but will never shrink to do so. -.Pp -.It Ic other-pane-width Ar width -Like -.Ic other-pane-height , -but set the width of other panes in the -.Ic main-vertical -layout. -.Pp -.It Ic pane-base-index Ar index -Like -.Ic base-index , -but set the starting index for pane numbers. -.Pp -.It Xo Ic remain-on-exit -.Op Ic on | off -.Xc -A window with this flag set is not destroyed when the program running in it -exits. -The window may be reactivated with the -.Ic respawn-window -command. -.Pp -.It Xo Ic synchronize-panes -.Op Ic on | off -.Xc -Duplicate input to any pane to all other panes in the same window (only -for panes that are not in any special mode). -.Pp -.It Xo Ic utf8 -.Op Ic on | off -.Xc -Instructs -.Nm -to expect UTF-8 sequences to appear in this window. -.Pp -.It Ic window-status-bell-attr Ar attributes -Set status line attributes for windows which have a bell alert. -.Pp -.It Ic window-status-bell-bg Ar colour -Set status line background colour for windows with a bell alert. -.Pp -.It Ic window-status-bell-fg Ar colour -Set status line foreground colour for windows with a bell alert. -.Pp -.It Ic window-status-content-attr Ar attributes -Set status line attributes for windows which have a content alert. -.Pp -.It Ic window-status-content-bg Ar colour -Set status line background colour for windows with a content alert. -.Pp -.It Ic window-status-content-fg Ar colour -Set status line foreground colour for windows with a content alert. -.Pp -.It Ic window-status-activity-attr Ar attributes -Set status line attributes for windows which have an activity (or silence) alert. -.Pp -.It Ic window-status-activity-bg Ar colour -Set status line background colour for windows with an activity alert. -.Pp -.It Ic window-status-activity-fg Ar colour -Set status line foreground colour for windows with an activity alert. -.Pp -.It Ic window-status-attr Ar attributes -Set status line attributes for a single window. -.Pp -.It Ic window-status-bg Ar colour -Set status line background colour for a single window. -.Pp -.It Ic window-status-current-attr Ar attributes -Set status line attributes for the currently active window. -.Pp -.It Ic window-status-current-bg Ar colour -Set status line background colour for the currently active window. -.Pp -.It Ic window-status-current-fg Ar colour -Set status line foreground colour for the currently active window. -.Pp -.It Ic window-status-current-format Ar string -Like -.Ar window-status-format , -but is the format used when the window is the current window. -.Pp -.It Ic window-status-last-attr Ar attributes -Set status line attributes for the last active window. -.Pp -.It Ic window-status-last-bg Ar colour -Set status line background colour for the last active window. -.Pp -.It Ic window-status-last-fg Ar colour -Set status line foreground colour for the last active window. -.Pp -.It Ic window-status-fg Ar colour -Set status line foreground colour for a single window. -.Pp -.It Ic window-status-format Ar string -Set the format in which the window is displayed in the status line window list. -See the -.Ar status-left -option for details of special character sequences available. -The default is -.Ql #I:#W#F . -.Pp -.It Ic window-status-separator Ar string -Sets the separator drawn between windows in the status line. -The default is a single space character. -.Pp -.It Xo Ic xterm-keys -.Op Ic on | off -.Xc -If this option is set, -.Nm -will generate -.Xr xterm 1 -style -function key sequences; these have a number included to indicate modifiers such -as Shift, Alt or Ctrl. -The default is off. -.Pp -.It Xo Ic wrap-search -.Op Ic on | off -.Xc -If this option is set, searches will wrap around the end of the pane contents. -The default is on. -.El -.It Xo Ic show-options -.Op Fl gqsvw -.Op Fl t Ar target-session | Ar target-window -.Op Ar option -.Xc -.D1 (alias: Ic show ) -Show the window options (or a single window option if given) with -.Fl w -(equivalent to -.Ic show-window-options ) , -the server options with -.Fl s , -otherwise the session options for -.Ar target session . -Global session or window options are listed if -.Fl g -is used. -.Fl v -shows only the option value, not the name. -If -.Fl q -is set, no error will be returned if -.Ar option -is unset. -.It Xo Ic show-window-options -.Op Fl gv -.Op Fl t Ar target-window -.Op Ar option -.Xc -.D1 (alias: Ic showw ) -List the window options or a single option for -.Ar target-window , -or the global window options if -.Fl g -is used. -.Fl v -shows only the option value, not the name. -.El -.Sh FORMATS -Certain commands accept the -.Fl F -flag with a -.Ar format -argument. -This is a string which controls the output format of the command. -Special character sequences are replaced as documented under the -.Ic status-left -option and an additional long form is accepted. -Replacement variables are enclosed in -.Ql #{ -and -.Ql } , -for example -.Ql #{session_name} -is equivalent to -.Ql #S . -Conditionals are also accepted by prefixing with -.Ql \&? -and separating two alternatives with a comma; -if the specified variable exists and is not zero, the first alternative -is chosen, otherwise the second is used. -For example -.Ql #{?session_attached,attached,not attached} -will include the string -.Ql attached -if the session is attached and the string -.Ql not attached -if it is unattached. -.Pp -The following variables are available, where appropriate: -.Bl -column "session_created_string" "Replaced with" -offset indent -.It Sy "Variable name" Ta Sy "Replaced with" -.It Li "alternate_on" Ta "If pane is in alternate screen" -.It Li "alternate_saved_x" Ta "Saved cursor X in alternate screen" -.It Li "alternate_saved_y" Ta "Saved cursor Y in alternate screen" -.It Li "buffer_sample" Ta "First 50 characters from the specified buffer" -.It Li "buffer_size" Ta "Size of the specified buffer in bytes" -.It Li "client_activity" Ta "Integer time client last had activity" -.It Li "client_activity_string" Ta "String time client last had activity" -.It Li "client_created" Ta "Integer time client created" -.It Li "client_created_string" Ta "String time client created" -.It Li "client_cwd" Ta "Working directory of client" -.It Li "client_height" Ta "Height of client" -.It Li "client_last_session" Ta "Name of the client's last session" -.It Li "client_prefix" Ta "1 if prefix key has been pressed" -.It Li "client_readonly" Ta "1 if client is readonly" -.It Li "client_session" Ta "Name of the client's session" -.It Li "client_termname" Ta "Terminal name of client" -.It Li "client_tty" Ta "Pseudo terminal of client" -.It Li "client_utf8" Ta "1 if client supports utf8" -.It Li "client_width" Ta "Width of client" -.It Li "cursor_flag" Ta "Pane cursor flag" -.It Li "cursor_x" Ta "Cursor X position in pane" -.It Li "cursor_y" Ta "Cursor Y position in pane" -.It Li "history_bytes" Ta "Number of bytes in window history" -.It Li "history_limit" Ta "Maximum window history lines" -.It Li "history_size" Ta "Size of history in bytes" -.It Li "host" Ta "Hostname of local host" -.It Li "insert_flag" Ta "Pane insert flag" -.It Li "keypad_cursor_flag" Ta "Pane keypad cursor flag" -.It Li "keypad_flag" Ta "Pane keypad flag" -.It Li "line" Ta "Line number in the list" -.It Li "mouse_any_flag" Ta "Pane mouse any flag" -.It Li "mouse_button_flag" Ta "Pane mouse button flag" -.It Li "mouse_standard_flag" Ta "Pane mouse standard flag" -.It Li "mouse_utf8_flag" Ta "Pane mouse UTF-8 flag" -.It Li "pane_active" Ta "1 if active pane" -.It Li "pane_current_command" Ta "Current command if available" -.It Li "pane_current_path" Ta "Current path if available" -.It Li "pane_dead" Ta "1 if pane is dead" -.It Li "pane_height" Ta "Height of pane" -.It Li "pane_id" Ta "Unique pane ID" -.It Li "pane_in_mode" Ta "If pane is in a mode" -.It Li "pane_index" Ta "Index of pane" -.It Li "pane_pid" Ta "PID of first process in pane" -.It Li "pane_start_command" Ta "Command pane started with" -.It Li "pane_start_path" Ta "Path pane started with" -.It Li "pane_tabs" Ta "Pane tab positions" -.It Li "pane_title" Ta "Title of pane" -.It Li "pane_tty" Ta "Pseudo terminal of pane" -.It Li "pane_width" Ta "Width of pane" -.It Li "saved_cursor_x" Ta "Saved cursor X in pane" -.It Li "saved_cursor_y" Ta "Saved cursor Y in pane" -.It Li "scroll_region_lower" Ta "Bottom of scroll region in pane" -.It Li "scroll_region_upper" Ta "Top of scroll region in pane" -.It Li "session_attached" Ta "1 if session attached" -.It Li "session_created" Ta "Integer time session created" -.It Li "session_created_string" Ta "String time session created" -.It Li "session_group" Ta "Number of session group" -.It Li "session_grouped" Ta "1 if session in a group" -.It Li "session_height" Ta "Height of session" -.It Li "session_id" Ta "Unique session ID" -.It Li "session_name" Ta "Name of session" -.It Li "session_width" Ta "Width of session" -.It Li "session_windows" Ta "Number of windows in session" -.It Li "window_active" Ta "1 if window active" -.It Li "window_find_matches" Ta "Matched data from the find-window command if available" -.It Li "window_flags" Ta "Window flags" -.It Li "window_height" Ta "Height of window" -.It Li "window_id" Ta "Unique window ID" -.It Li "window_index" Ta "Index of window" -.It Li "window_layout" Ta "Window layout description" -.It Li "window_name" Ta "Name of window" -.It Li "window_panes" Ta "Number of panes in window" -.It Li "window_width" Ta "Width of window" -.It Li "wrap_flag" Ta "Pane wrap flag" -.El -.Sh NAMES AND TITLES -.Nm -distinguishes between names and titles. -Windows and sessions have names, which may be used to specify them in targets -and are displayed in the status line and various lists: the name is the -.Nm -identifier for a window or session. -Only panes have titles. -A pane's title is typically set by the program running inside the pane and -is not modified by -.Nm . -It is the same mechanism used to set for example the -.Xr xterm 1 -window title in an -.Xr X 7 -window manager. -Windows themselves do not have titles - a window's title is the title of its -active pane. -.Nm -itself may set the title of the terminal in which the client is running, see -the -.Ic set-titles -option. -.Pp -A session's name is set with the -.Ic new-session -and -.Ic rename-session -commands. -A window's name is set with one of: -.Bl -enum -width Ds -.It -A command argument (such as -.Fl n -for -.Ic new-window -or -.Ic new-session ) . -.It -An escape sequence: -.Bd -literal -offset indent -$ printf '\e033kWINDOW_NAME\e033\e\e' -.Ed -.It -Automatic renaming, which sets the name to the active command in the window's -active pane. -See the -.Ic automatic-rename -option. -.El -.Pp -When a pane is first created, its title is the hostname. -A pane's title can be set via the OSC title setting sequence, for example: -.Bd -literal -offset indent -$ printf '\e033]2;My Title\e033\e\e' -.Ed -.Sh ENVIRONMENT -When the server is started, -.Nm -copies the environment into the -.Em global environment ; -in addition, each session has a -.Em session environment . -When a window is created, the session and global environments are merged. -If a variable exists in both, the value from the session environment is used. -The result is the initial environment passed to the new process. -.Pp -The -.Ic update-environment -session option may be used to update the session environment from the client -when a new session is created or an old reattached. -.Nm -also initialises the -.Ev TMUX -variable with some internal information to allow commands to be executed -from inside, and the -.Ev TERM -variable with the correct terminal setting of -.Ql screen . -.Pp -Commands to alter and view the environment are: -.Bl -tag -width Ds -.It Xo Ic set-environment -.Op Fl gru -.Op Fl t Ar target-session -.Ar name Op Ar value -.Xc -.D1 (alias: Ic setenv ) -Set or unset an environment variable. -If -.Fl g -is used, the change is made in the global environment; otherwise, it is applied -to the session environment for -.Ar target-session . -The -.Fl u -flag unsets a variable. -.Fl r -indicates the variable is to be removed from the environment before starting a -new process. -.It Xo Ic show-environment -.Op Fl g -.Op Fl t Ar target-session -.Op Ar variable -.Xc -.D1 (alias: Ic showenv ) -Display the environment for -.Ar target-session -or the global environment with -.Fl g . -If -.Ar variable -is omitted, all variables are shown. -Variables removed from the environment are prefixed with -.Ql - . -.El -.Sh STATUS LINE -.Nm -includes an optional status line which is displayed in the bottom line of each -terminal. -By default, the status line is enabled (it may be disabled with the -.Ic status -session option) and contains, from left-to-right: the name of the current -session in square brackets; the window list; the title of the active pane -in double quotes; and the time and date. -.Pp -The status line is made of three parts: configurable left and right sections -(which may contain dynamic content such as the time or output from a shell -command, see the -.Ic status-left , -.Ic status-left-length , -.Ic status-right , -and -.Ic status-right-length -options below), and a central window list. -By default, the window list shows the index, name and (if any) flag of the -windows present in the current session in ascending numerical order. -It may be customised with the -.Ar window-status-format -and -.Ar window-status-current-format -options. -The flag is one of the following symbols appended to the window name: -.Bl -column "Symbol" "Meaning" -offset indent -.It Sy "Symbol" Ta Sy "Meaning" -.It Li "*" Ta "Denotes the current window." -.It Li "-" Ta "Marks the last window (previously selected)." -.It Li "#" Ta "Window is monitored and activity has been detected." -.It Li "!" Ta "A bell has occurred in the window." -.It Li "+" Ta "Window is monitored for content and it has appeared." -.It Li "~" Ta "The window has been silent for the monitor-silence interval." -.It Li "Z" Ta "The window's active pane is zoomed." -.El -.Pp -The # symbol relates to the -.Ic monitor-activity -and + to the -.Ic monitor-content -window options. -The window name is printed in inverted colours if an alert (bell, activity or -content) is present. -.Pp -The colour and attributes of the status line may be configured, the entire -status line using the -.Ic status-attr , -.Ic status-fg -and -.Ic status-bg -session options and individual windows using the -.Ic window-status-attr , -.Ic window-status-fg -and -.Ic window-status-bg -window options. -.Pp -The status line is automatically refreshed at interval if it has changed, the -interval may be controlled with the -.Ic status-interval -session option. -.Pp -Commands related to the status line are as follows: -.Bl -tag -width Ds -.It Xo Ic command-prompt -.Op Fl I Ar inputs -.Op Fl p Ar prompts -.Op Fl t Ar target-client -.Op Ar template -.Xc -Open the command prompt in a client. -This may be used from inside -.Nm -to execute commands interactively. -.Pp -If -.Ar template -is specified, it is used as the command. -If present, -.Fl I -is a comma-separated list of the initial text for each prompt. -If -.Fl p -is given, -.Ar prompts -is a comma-separated list of prompts which are displayed in order; otherwise -a single prompt is displayed, constructed from -.Ar template -if it is present, or -.Ql \&: -if not. -.Pp -Both -.Ar inputs -and -.Ar prompts -may contain the special character sequences supported by the -.Ic status-left -option. -.Pp -Before the command is executed, the first occurrence of the string -.Ql %% -and all occurrences of -.Ql %1 -are replaced by the response to the first prompt, the second -.Ql %% -and all -.Ql %2 -are replaced with the response to the second prompt, and so on for further -prompts. -Up to nine prompt responses may be replaced -.Po -.Ql %1 -to -.Ql %9 -.Pc . -.It Xo Ic confirm-before -.Op Fl p Ar prompt -.Op Fl t Ar target-client -.Ar command -.Xc -.D1 (alias: Ic confirm ) -Ask for confirmation before executing -.Ar command . -If -.Fl p -is given, -.Ar prompt -is the prompt to display; otherwise a prompt is constructed from -.Ar command . -It may contain the special character sequences supported by the -.Ic status-left -option. -.Pp -This command works only from inside -.Nm . -.It Xo Ic display-message -.Op Fl p -.Op Fl c Ar target-client -.Op Fl t Ar target-pane -.Op Ar message -.Xc -.D1 (alias: Ic display ) -Display a message. -If -.Fl p -is given, the output is printed to stdout, otherwise it is displayed in the -.Ar target-client -status line. -The format of -.Ar message -is described in the -.Sx FORMATS -section; information is taken from -.Ar target-pane -if -.Fl t -is given, otherwise the active pane for the session attached to -.Ar target-client . -.El -.Sh BUFFERS -.Nm -maintains a stack of -.Em paste buffers . -Up to the value of the -.Ic buffer-limit -option are kept; when a new buffer is added, the buffer at the bottom of the -stack is removed. -Buffers may be added using -.Ic copy-mode -or the -.Ic set-buffer -command, and pasted into a window using the -.Ic paste-buffer -command. -.Pp -A configurable history buffer is also maintained for each window. -By default, up to 2000 lines are kept; this can be altered with the -.Ic history-limit -option (see the -.Ic set-option -command above). -.Pp -The buffer commands are as follows: -.Bl -tag -width Ds -.It Xo -.Ic choose-buffer -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into buffer choice mode, where a buffer may be chosen -interactively from a list. -After a buffer is selected, -.Ql %% -is replaced by the buffer index in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "paste-buffer -b '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Ic clear-history Op Fl t Ar target-pane -.D1 (alias: Ic clearhist ) -Remove and free the history for the specified pane. -.It Ic delete-buffer Op Fl b Ar buffer-index -.D1 (alias: Ic deleteb ) -Delete the buffer at -.Ar buffer-index , -or the top buffer if not specified. -.It Xo Ic list-buffers -.Op Fl F Ar format -.Xc -.D1 (alias: Ic lsb ) -List the global buffers. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic load-buffer -.Op Fl b Ar buffer-index -.Ar path -.Xc -.D1 (alias: Ic loadb ) -Load the contents of the specified paste buffer from -.Ar path . -.It Xo Ic paste-buffer -.Op Fl dpr -.Op Fl b Ar buffer-index -.Op Fl s Ar separator -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic pasteb ) -Insert the contents of a paste buffer into the specified pane. -If not specified, paste into the current one. -With -.Fl d , -also delete the paste buffer from the stack. -When output, any linefeed (LF) characters in the paste buffer are replaced with -a separator, by default carriage return (CR). -A custom separator may be specified using the -.Fl s -flag. -The -.Fl r -flag means to do no replacement (equivalent to a separator of LF). -If -.Fl p -is specified, paste bracket control codes are inserted around the -buffer if the application has requested bracketed paste mode. -.It Xo Ic save-buffer -.Op Fl a -.Op Fl b Ar buffer-index -.Ar path -.Xc -.D1 (alias: Ic saveb ) -Save the contents of the specified paste buffer to -.Ar path . -The -.Fl a -option appends to rather than overwriting the file. -.It Xo Ic set-buffer -.Op Fl b Ar buffer-index -.Ar data -.Xc -.D1 (alias: Ic setb ) -Set the contents of the specified buffer to -.Ar data . -.It Xo Ic show-buffer -.Op Fl b Ar buffer-index -.Xc -.D1 (alias: Ic showb ) -Display the contents of the specified buffer. -.El -.Sh MISCELLANEOUS -Miscellaneous commands are as follows: -.Bl -tag -width Ds -.It Ic clock-mode Op Fl t Ar target-pane -Display a large clock. -.It Xo Ic if-shell -.Op Fl b -.Op Fl t Ar target-pane -.Ar shell-command command -.Op Ar command -.Xc -.D1 (alias: Ic if ) -Execute the first -.Ar command -if -.Ar shell-command -returns success or the second -.Ar command -otherwise. -Before being executed, shell-command is expanded using the rules specified in the -.Sx FORMATS -section, including those relevant to -.Ar target-pane . -With -.Fl b , -.Ar shell-command -is run in the background. -.It Ic lock-server -.D1 (alias: Ic lock ) -Lock each client individually by running the command specified by the -.Ic lock-command -option. -.It Xo Ic run-shell -.Fl b -.Op Fl t Ar target-pane -.Ar shell-command -.Xc -.D1 (alias: Ic run ) -Execute -.Ar shell-command -in the background without creating a window. -Before being executed, shell-command is expanded using the rules specified in -the -.Sx FORMATS -section. -With -.Fl b , -the command is run in the background. -After it finishes, any output to stdout is displayed in copy mode (in the pane -specified by -.Fl t -or the current pane if omitted). -If the command doesn't return success, the exit status is also displayed. -.It Ic server-info -.D1 (alias: Ic info ) -Show server information and terminal details. -.It Xo Ic wait-for -.Fl LSU -.Ar channel -.Xc -.D1 (alias: Ic wait ) -When used without options, prevents the client from exiting until woken using -.Ic wait-for -.Fl S -with the same channel. -When -.Fl L -is used, the channel is locked and any clients that try to lock the same -channel are made to wait until the channel is unlocked with -.Ic wait-for -.Fl U . -This command only works from outside -.Nm . -.El -.Sh TERMINFO EXTENSIONS -.Nm -understands some extensions to -.Xr terminfo 5 : -.Bl -tag -width Ds -.It Em Cc , Cr -Set the cursor colour. -The first takes a single string argument and is used to set the colour; -the second takes no arguments and restores the default cursor colour. -If set, a sequence such as this may be used -to change the cursor colour from inside -.Nm : -.Bd -literal -offset indent -$ printf '\e033]12;red\e033\e\e' -.Ed -.It Em Cs , Csr -Change the cursor style. -If set, a sequence such as this may be used -to change the cursor to an underline: -.Bd -literal -offset indent -$ printf '\e033[4 q' -.Ed -.Pp -If -.Em Csr -is set, it will be used to reset the cursor style instead -of -.Em Cs . -.It Em \&Ms -This sequence can be used by -.Nm -to store the current buffer in the host terminal's selection (clipboard). -See the -.Em set-clipboard -option above and the -.Xr xterm 1 -man page. -.El -.Sh CONTROL MODE -.Nm -offers a textual interface called -.Em control mode . -This allows applications to communicate with -.Nm -using a simple text-only protocol. -.Pp -In control mode, a client sends -.Nm -commands or command sequences terminated by newlines on standard input. -Each command will produce one block of output on standard output. -An output block consists of a -.Em %begin -line followed by the output (which may be empty). -The output block ends with a -.Em %end -or -.Em %error . -.Em %begin -and matching -.Em %end -or -.Em %error -have two arguments: an integer time (as seconds from epoch) and command number. -For example: -.Bd -literal -offset indent -%begin 1363006971 2 -0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) -%end 1363006971 2 -.Ed -.Pp -In control mode, -.Nm -outputs notifications. -A notification will never occur inside an output block. -.Pp -The following notifications are defined: -.Bl -tag -width Ds -.It Ic %exit Op Ar reason -The -.Nm -client is exiting immediately, either because it is not attached to any session -or an error occurred. -If present, -.Ar reason -describes why the client exited. -.It Ic %layout-change Ar window-id Ar window-layout -The layout of a window with ID -.Ar window-id -changed. -The new layout is -.Ar window-layout . -.It Ic %output Ar pane-id Ar value -A window pane produced output. -.Ar value -escapes non-printable characters and backslash as octal \\xxx. -.It Ic %session-changed Ar session-id Ar name -The client is now attached to the session with ID -.Ar session-id , -which is named -.Ar name . -.It Ic %session-renamed Ar name -The current session was renamed to -.Ar name . -.It Ic %sessions-changed -A session was created or destroyed. -.It Ic %unlinked-window-add Ar window-id -The window with ID -.Ar window-id -was created but is not linked to the current session. -.It Ic %window-add Ar window-id -The window with ID -.Ar window-id -was linked to the current session. -.It Ic %window-close Ar window-id -The window with ID -.Ar window-id -closed. -.It Ic %window-renamed Ar window-id Ar name -The window with ID -.Ar window-id -was renamed to -.Ar name . -.El -.Sh FILES -.Bl -tag -width "/etc/tmux.confXXX" -compact -.It Pa ~/.tmux.conf -Default -.Nm -configuration file. -.It Pa /etc/tmux.conf -System-wide configuration file. -.El -.Sh EXAMPLES -To create a new -.Nm -session running -.Xr vi 1 : -.Pp -.Dl $ tmux new-session vi -.Pp -Most commands have a shorter form, known as an alias. -For new-session, this is -.Ic new : -.Pp -.Dl $ tmux new vi -.Pp -Alternatively, the shortest unambiguous form of a command is accepted. -If there are several options, they are listed: -.Bd -literal -offset indent -$ tmux n -ambiguous command: n, could be: new-session, new-window, next-window -.Ed -.Pp -Within an active session, a new window may be created by typing -.Ql C-b c -(Ctrl -followed by the -.Ql b -key -followed by the -.Ql c -key). -.Pp -Windows may be navigated with: -.Ql C-b 0 -(to select window 0), -.Ql C-b 1 -(to select window 1), and so on; -.Ql C-b n -to select the next window; and -.Ql C-b p -to select the previous window. -.Pp -A session may be detached using -.Ql C-b d -(or by an external event such as -.Xr ssh 1 -disconnection) and reattached with: -.Pp -.Dl $ tmux attach-session -.Pp -Typing -.Ql C-b \&? -lists the current key bindings in the current window; up and down may be used -to navigate the list or -.Ql q -to exit from it. -.Pp -Commands to be run when the -.Nm -server is started may be placed in the -.Pa ~/.tmux.conf -configuration file. -Common examples include: -.Pp -Changing the default prefix key: -.Bd -literal -offset indent -set-option -g prefix C-a -unbind-key C-b -bind-key C-a send-prefix -.Ed -.Pp -Turning the status line off, or changing its colour: -.Bd -literal -offset indent -set-option -g status off -set-option -g status-bg blue -.Ed -.Pp -Setting other options, such as the default command, -or locking after 30 minutes of inactivity: -.Bd -literal -offset indent -set-option -g default-command "exec /bin/ksh" -set-option -g lock-after-time 1800 -.Ed -.Pp -Creating new key bindings: -.Bd -literal -offset indent -bind-key b set-option status -bind-key / command-prompt "split-window 'exec man %%'" -bind-key S command-prompt "new-window -n %1 'ssh %1'" -.Ed -.Sh SEE ALSO -.Xr pty 4 -.Sh AUTHORS -.An Nicholas Marriott Aq nicm@users.sourceforge.net diff --git a/tmux.1.in b/tmux.1.in new file mode 100644 index 00000000..98bf9574 --- /dev/null +++ b/tmux.1.in @@ -0,0 +1,3808 @@ +.\" $Id$ +.\" +.\" Copyright (c) 2007 Nicholas Marriott +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER +.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING +.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: March 25 2013 $ +.Dt TMUX 1 +.Os +.Sh NAME +.Nm tmux +.Nd terminal multiplexer +.Sh SYNOPSIS +.Nm tmux +.Bk -words +.Op Fl 28lCquvV +.Op Fl c Ar shell-command +.Op Fl f Ar file +.Op Fl L Ar socket-name +.Op Fl S Ar socket-path +.Op Ar command Op Ar flags +.Ek +.Sh DESCRIPTION +.Nm +is a terminal multiplexer: +it enables a number of terminals to be created, accessed, and +controlled from a single screen. +.Nm +may be detached from a screen +and continue running in the background, +then later reattached. +.Pp +When +.Nm +is started it creates a new +.Em session +with a single +.Em window +and displays it on screen. +A status line at the bottom of the screen +shows information on the current session +and is used to enter interactive commands. +.Pp +A session is a single collection of +.Em pseudo terminals +under the management of +.Nm . +Each session has one or more +windows linked to it. +A window occupies the entire screen +and may be split into rectangular panes, +each of which is a separate pseudo terminal +(the +.Xr pty 4 +manual page documents the technical details of pseudo terminals). +Any number of +.Nm +instances may connect to the same session, +and any number of windows may be present in the same session. +Once all sessions are killed, +.Nm +exits. +.Pp +Each session is persistent and will survive accidental disconnection +(such as +.Xr ssh 1 +connection timeout) or intentional detaching (with the +.Ql C-b d +key strokes). +.Nm +may be reattached using: +.Pp +.Dl $ tmux attach +.Pp +In +.Nm , +a session is displayed on screen by a +.Em client +and all sessions are managed by a single +.Em server . +The server and each client are separate processes which communicate through a +socket in +.Pa /tmp . +.Pp +The options are as follows: +.Bl -tag -width "XXXXXXXXXXXX" +.It Fl 2 +Force +.Nm +to assume the terminal supports 256 colours. +.It Fl C +Start in control mode. +Given twice +.Xo ( Fl CC ) Xc +disables echo. +.It Fl c Ar shell-command +Execute +.Ar shell-command +using the default shell. +If necessary, the +.Nm +server will be started to retrieve the +.Ic default-shell +option. +This option is for compatibility with +.Xr sh 1 +when +.Nm +is used as a login shell. +.It Fl f Ar file +Specify an alternative configuration file. +By default, +.Nm +loads the system configuration file from +.Pa /etc/tmux.conf , +if present, then looks for a user configuration file at +.Pa ~/.tmux.conf . +.Pp +The configuration file is a set of +.Nm +commands which are executed in sequence when the server is first started. +.Nm +loads configuration files once when the server process has started. +The +.Ic source-file +command may be used to load a file later. +.Pp +.Nm +shows any error messages from commands in configuration files in the first +session created, and continues to process the rest of the configuration file. +.It Fl L Ar socket-name +.Nm +stores the server socket in a directory under +.Ev TMUX_TMPDIR , +.Ev TMPDIR +if it is unset, or +.Pa /tmp +if both are unset. +The default socket is named +.Em default . +This option allows a different socket name to be specified, allowing several +independent +.Nm +servers to be run. +Unlike +.Fl S +a full path is not necessary: the sockets are all created in the same +directory. +.Pp +If the socket is accidentally removed, the +.Dv SIGUSR1 +signal may be sent to the +.Nm +server process to recreate it. +.It Fl l +Behave as a login shell. +This flag currently has no effect and is for compatibility with other shells +when using tmux as a login shell. +.It Fl q +Set the +.Ic quiet +server option to prevent the server sending various informational messages. +.It Fl S Ar socket-path +Specify a full alternative path to the server socket. +If +.Fl S +is specified, the default socket directory is not used and any +.Fl L +flag is ignored. +.It Fl u +.Nm +attempts to guess if the terminal is likely to support UTF-8 by checking the +first of the +.Ev LC_ALL , +.Ev LC_CTYPE +and +.Ev LANG +environment variables to be set for the string "UTF-8". +This is not always correct: the +.Fl u +flag explicitly informs +.Nm +that UTF-8 is supported. +.Pp +If the server is started from a client passed +.Fl u +or where UTF-8 is detected, the +.Ic utf8 +and +.Ic status-utf8 +options are enabled in the global window and session options respectively. +.It Fl v +Request verbose logging. +This option may be specified multiple times for increasing verbosity. +Log messages will be saved into +.Pa tmux-client-PID.log +and +.Pa tmux-server-PID.log +files in the current directory, where +.Em PID +is the PID of the server or client process. +.It Fl V +Report the +.Nm +version. +.It Ar command Op Ar flags +This specifies one of a set of commands used to control +.Nm , +as described in the following sections. +If no commands are specified, the +.Ic new-session +command is assumed. +.El +.Sh KEY BINDINGS +.Nm +may be controlled from an attached client by using a key combination of a +prefix key, +.Ql C-b +(Ctrl-b) by default, followed by a command key. +.Pp +The default command key bindings are: +.Pp +.Bl -tag -width "XXXXXXXXXX" -offset indent -compact +.It C-b +Send the prefix key (C-b) through to the application. +.It C-o +Rotate the panes in the current window forwards. +.It C-z +Suspend the +.Nm +client. +.It ! +Break the current pane out of the window. +.It \&" +Split the current pane into two, top and bottom. +.It # +List all paste buffers. +.It $ +Rename the current session. +.It % +Split the current pane into two, left and right. +.It & +Kill the current window. +.It ' +Prompt for a window index to select. +.It , +Rename the current window. +.It - +Delete the most recently copied buffer of text. +.It . +Prompt for an index to move the current window. +.It 0 to 9 +Select windows 0 to 9. +.It : +Enter the +.Nm +command prompt. +.It ; +Move to the previously active pane. +.It = +Choose which buffer to paste interactively from a list. +.It \&? +List all key bindings. +.It D +Choose a client to detach. +.It \&[ +Enter copy mode to copy text or view the history. +.It \&] +Paste the most recently copied buffer of text. +.It c +Create a new window. +.It d +Detach the current client. +.It f +Prompt to search for text in open windows. +.It i +Display some information about the current window. +.It l +Move to the previously selected window. +.It n +Change to the next window. +.It o +Select the next pane in the current window. +.It p +Change to the previous window. +.It q +Briefly display pane indexes. +.It r +Force redraw of the attached client. +.It s +Select a new session for the attached client interactively. +.It L +Switch the attached client back to the last session. +.It t +Show the time. +.It w +Choose the current window interactively. +.It x +Kill the current pane. +.It { +Swap the current pane with the previous pane. +.It } +Swap the current pane with the next pane. +.It ~ +Show previous messages from +.Nm , +if any. +.It Page Up +Enter copy mode and scroll one page up. +.It Up, Down +.It Left, Right +Change to the pane above, below, to the left, or to the right of the current +pane. +.It M-1 to M-5 +Arrange panes in one of the five preset layouts: even-horizontal, +even-vertical, main-horizontal, main-vertical, or tiled. +.It M-n +Move to the next window with a bell or activity marker. +.It M-o +Rotate the panes in the current window backwards. +.It M-p +Move to the previous window with a bell or activity marker. +.It C-Up, C-Down +.It C-Left, C-Right +Resize the current pane in steps of one cell. +.It M-Up, M-Down +.It M-Left, M-Right +Resize the current pane in steps of five cells. +.El +.Pp +Key bindings may be changed with the +.Ic bind-key +and +.Ic unbind-key +commands. +.Sh COMMANDS +This section contains a list of the commands supported by +.Nm . +Most commands accept the optional +.Fl t +argument with one of +.Ar target-client , +.Ar target-session +.Ar target-window , +or +.Ar target-pane . +These specify the client, session, window or pane which a command should affect. +.Ar target-client +is the name of the +.Xr pty 4 +file to which the client is connected, for example either of +.Pa /dev/ttyp1 +or +.Pa ttyp1 +for the client attached to +.Pa /dev/ttyp1 . +If no client is specified, the current client is chosen, if possible, or an +error is reported. +Clients may be listed with the +.Ic list-clients +command. +.Pp +.Ar target-session +is the session id prefixed with a $, the name of a session (as listed by the +.Ic list-sessions +command), or the name of a client with the same syntax as +.Ar target-client , +in which case the session attached to the client is used. +When looking for the session name, +.Nm +initially searches for an exact match; if none is found, the session names +are checked for any for which +.Ar target-session +is a prefix or for which it matches as an +.Xr fnmatch 3 +pattern. +If a single match is found, it is used as the target session; multiple matches +produce an error. +If a session is omitted, the current session is used if available; if no +current session is available, the most recently used is chosen. +.Pp +.Ar target-window +specifies a window in the form +.Em session Ns \&: Ns Em window . +.Em session +follows the same rules as for +.Ar target-session , +and +.Em window +is looked for in order: as a window index, for example mysession:1; +as a window ID, such as @1; +as an exact window name, such as mysession:mywindow; then as an +.Xr fnmatch 3 +pattern or the start of a window name, such as mysession:mywin* or +mysession:mywin. +An empty window name specifies the next unused index if appropriate (for +example the +.Ic new-window +and +.Ic link-window +commands) +otherwise the current window in +.Em session +is chosen. +The special character +.Ql \&! +uses the last (previously current) window, +.Ql ^ +selects the highest numbered window, +.Ql $ +selects the lowest numbered window, and +.Ql + +and +.Ql - +select the next window or the previous window by number. +When the argument does not contain a colon, +.Nm +first attempts to parse it as window; if that fails, an attempt is made to +match a session. +.Pp +.Ar target-pane +takes a similar form to +.Ar target-window +but with the optional addition of a period followed by a pane index, for +example: mysession:mywindow.1. +If the pane index is omitted, the currently active pane in the specified +window is used. +If neither a colon nor period appears, +.Nm +first attempts to use the argument as a pane index; if that fails, it is looked +up as for +.Ar target-window . +A +.Ql + +or +.Ql - +indicate the next or previous pane index, respectively. +One of the strings +.Em top , +.Em bottom , +.Em left , +.Em right , +.Em top-left , +.Em top-right , +.Em bottom-left +or +.Em bottom-right +may be used instead of a pane index. +.Pp +The special characters +.Ql + +and +.Ql - +may be followed by an offset, for example: +.Bd -literal -offset indent +select-window -t:+2 +.Ed +.Pp +When dealing with a session that doesn't contain sequential window indexes, +they will be correctly skipped. +.Pp +.Nm +also gives each pane created in a server an identifier consisting of a +.Ql % +and a number, starting from zero. +A pane's identifier is unique for the life of the +.Nm +server and is passed to the child process of the pane in the +.Ev TMUX_PANE +environment variable. +It may be used alone to target a pane or the window containing it. +.Pp +.Ar shell-command +arguments are +.Xr sh 1 +commands. +These must be passed as a single item, which typically means quoting them, for +example: +.Bd -literal -offset indent +new-window 'vi /etc/passwd' +.Ed +.Pp +.Ar command +.Op Ar arguments +refers to a +.Nm +command, passed with the command and arguments separately, for example: +.Bd -literal -offset indent +bind-key F1 set-window-option force-width 81 +.Ed +.Pp +Or if using +.Xr sh 1 : +.Bd -literal -offset indent +$ tmux bind-key F1 set-window-option force-width 81 +.Ed +.Pp +Multiple commands may be specified together as part of a +.Em command sequence . +Each command should be separated by spaces and a semicolon; +commands are executed sequentially from left to right and +lines ending with a backslash continue on to the next line, +except when escaped by another backslash. +A literal semicolon may be included by escaping it with a backslash (for +example, when specifying a command sequence to +.Ic bind-key ) . +.Pp +Example +.Nm +commands include: +.Bd -literal -offset indent +refresh-client -t/dev/ttyp2 + +rename-session -tfirst newname + +set-window-option -t:0 monitor-activity on + +new-window ; split-window -d + +bind-key R source-file ~/.tmux.conf \e; \e + display-message "source-file done" +.Ed +.Pp +Or from +.Xr sh 1 : +.Bd -literal -offset indent +$ tmux kill-window -t :1 + +$ tmux new-window \e; split-window -d + +$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach +.Ed +.Sh CLIENTS AND SESSIONS +The +.Nm +server manages clients, sessions, windows and panes. +Clients are attached to sessions to interact with them, either +when they are created with the +.Ic new-session +command, or later with the +.Ic attach-session +command. +Each session has one or more windows +.Em linked +into it. +Windows may be linked to multiple sessions and are made up of one or +more panes, +each of which contains a pseudo terminal. +Commands for creating, linking and otherwise manipulating windows +are covered +in the +.Sx WINDOWS AND PANES +section. +.Pp +The following commands are available to manage clients and sessions: +.Bl -tag -width Ds +.It Xo Ic attach-session +.Op Fl dr +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic attach ) +If run from outside +.Nm , +create a new client in the current terminal and attach it to +.Ar target-session . +If used from inside, switch the current client. +If +.Fl d +is specified, any other clients attached to the session are detached. +.Fl r +signifies the client is read-only (only keys bound to the +.Ic detach-client +or +.Ic switch-client +commands have any effect) +.Pp +If no server is started, +.Ic attach-session +will attempt to start it; this will fail unless sessions are created in the +configuration file. +.Pp +The +.Ar target-session +rules for +.Ic attach-session +are slightly adjusted: if +.Nm +needs to select the most recently used session, it will prefer the most +recently used +.Em unattached +session. +.It Xo Ic detach-client +.Op Fl P +.Op Fl a +.Op Fl s Ar target-session +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic detach ) +Detach the current client if bound to a key, the client specified with +.Fl t , +or all clients currently attached to the session specified by +.Fl s . +The +.Fl a +option kills all but the client given with +.Fl t . +If +.Fl P +is given, send SIGHUP to the parent process of the client, typically causing it +to exit. +.It Ic has-session Op Fl t Ar target-session +.D1 (alias: Ic has ) +Report an error and exit with 1 if the specified session does not exist. +If it does exist, exit with 0. +.It Ic kill-server +Kill the +.Nm +server and clients and destroy all sessions. +.It Ic kill-session +.Op Fl a +.Op Fl t Ar target-session +Destroy the given session, closing any windows linked to it and no other +sessions, and detaching all clients attached to it. +If +.Fl a +is given, all sessions but the specified one is killed. +.It Xo Ic list-clients +.Op Fl F Ar format +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic lsc ) +List all clients attached to the server. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +If +.Ar target-session +is specified, list only clients connected to that session. +.It Ic list-commands +.D1 (alias: Ic lscm ) +List the syntax of all commands supported by +.Nm . +.It Ic list-sessions Op Fl F Ar format +.D1 (alias: Ic ls ) +List all sessions managed by the server. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Ic lock-client Op Fl t Ar target-client +.D1 (alias: Ic lockc ) +Lock +.Ar target-client , +see the +.Ic lock-server +command. +.It Ic lock-session Op Fl t Ar target-session +.D1 (alias: Ic locks ) +Lock all clients attached to +.Ar target-session . +.It Xo Ic new-session +.Op Fl AdDP +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl s Ar session-name +.Op Fl t Ar target-session +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar shell-command +.Xc +.D1 (alias: Ic new ) +Create a new session with name +.Ar session-name . +.Pp +The new session is attached to the current terminal unless +.Fl d +is given. +.Ar window-name +and +.Ar shell-command +are the name of and shell command to execute in the initial window. +If +.Fl d +is used, +.Fl x +and +.Fl y +specify the size of the initial window (80 by 24 if not given). +.Pp +If run from a terminal, any +.Xr termios 4 +special characters are saved and used for new windows in the new session. +.Pp +The +.Fl A +flag makes +.Ic new-session +behave like +.Ic attach-session +if +.Ar session-name +already exists; in the case, +.Fl D +behaves like +.Fl d +to +.Ic attach-session . +.Pp +If +.Fl t +is given, the new session is +.Em grouped +with +.Ar target-session . +This means they share the same set of windows - all windows from +.Ar target-session +are linked to the new session and any subsequent new windows or windows being +closed are applied to both sessions. +The current and previous window and any session options remain independent and +either session may be killed without affecting the other. +Giving +.Fl n +or +.Ar shell-command +are invalid if +.Fl t +is used. +.Pp +The +.Fl P +option prints information about the new session after it has been created. +By default, it uses the format +.Ql #{session_name}: +but a different format may be specified with +.Fl F . +.It Xo Ic refresh-client +.Op Fl S +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic refresh ) +Refresh the current client if bound to a key, or a single client if one is given +with +.Fl t . +If +.Fl S +is specified, only update the client's status bar. +.It Xo Ic rename-session +.Op Fl t Ar target-session +.Ar new-name +.Xc +.D1 (alias: Ic rename ) +Rename the session to +.Ar new-name . +.It Xo Ic show-messages +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic showmsgs ) +Any messages displayed on the status line are saved in a per-client message +log, up to a maximum of the limit set by the +.Ar message-limit +session option for the session attached to that client. +This command displays the log for +.Ar target-client . +.It Ic source-file Ar path +.D1 (alias: Ic source ) +Execute commands from +.Ar path . +.It Ic start-server +.D1 (alias: Ic start ) +Start the +.Nm +server, if not already running, without creating any sessions. +.It Xo Ic suspend-client +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic suspendc ) +Suspend a client by sending +.Dv SIGTSTP +(tty stop). +.It Xo Ic switch-client +.Op Fl lnpr +.Op Fl c Ar target-client +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic switchc ) +Switch the current session for client +.Ar target-client +to +.Ar target-session . +If +.Fl l , +.Fl n +or +.Fl p +is used, the client is moved to the last, next or previous session +respectively. +.Fl r +toggles whether a client is read-only (see the +.Ic attach-session +command). +.El +.Sh WINDOWS AND PANES +A +.Nm +window may be in one of several modes. +The default permits direct access to the terminal attached to the window. +The other is copy mode, which permits a section of a window or its +history to be copied to a +.Em paste buffer +for later insertion into another window. +This mode is entered with the +.Ic copy-mode +command, bound to +.Ql \&[ +by default. +It is also entered when a command that produces output, such as +.Ic list-keys , +is executed from a key binding. +.Pp +The keys available depend on whether emacs or vi mode is selected +(see the +.Ic mode-keys +option). +The following keys are supported as appropriate for the mode: +.Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent +.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" +.It Li "Back to indentation" Ta "^" Ta "M-m" +.It Li "Bottom of history" Ta "G" Ta "M-<" +.It Li "Clear selection" Ta "Escape" Ta "C-g" +.It Li "Copy selection" Ta "Enter" Ta "M-w" +.It Li "Cursor down" Ta "j" Ta "Down" +.It Li "Cursor left" Ta "h" Ta "Left" +.It Li "Cursor right" Ta "l" Ta "Right" +.It Li "Cursor to bottom line" Ta "L" Ta "" +.It Li "Cursor to middle line" Ta "M" Ta "M-r" +.It Li "Cursor to top line" Ta "H" Ta "M-R" +.It Li "Cursor up" Ta "k" Ta "Up" +.It Li "Delete entire line" Ta "d" Ta "C-u" +.It Li "Delete/Copy to end of line" Ta "D" Ta "C-k" +.It Li "End of line" Ta "$" Ta "C-e" +.It Li "Go to line" Ta ":" Ta "g" +.It Li "Half page down" Ta "C-d" Ta "M-Down" +.It Li "Half page up" Ta "C-u" Ta "M-Up" +.It Li "Jump forward" Ta "f" Ta "f" +.It Li "Jump to forward" Ta "t" Ta "" +.It Li "Jump backward" Ta "F" Ta "F" +.It Li "Jump to backward" Ta "T" Ta "" +.It Li "Jump again" Ta ";" Ta ";" +.It Li "Jump again in reverse" Ta "," Ta "," +.It Li "Next page" Ta "C-f" Ta "Page down" +.It Li "Next space" Ta "W" Ta "" +.It Li "Next space, end of word" Ta "E" Ta "" +.It Li "Next word" Ta "w" Ta "" +.It Li "Next word end" Ta "e" Ta "M-f" +.It Li "Paste buffer" Ta "p" Ta "C-y" +.It Li "Previous page" Ta "C-b" Ta "Page up" +.It Li "Previous word" Ta "b" Ta "M-b" +.It Li "Previous space" Ta "B" Ta "" +.It Li "Quit mode" Ta "q" Ta "Escape" +.It Li "Rectangle toggle" Ta "v" Ta "R" +.It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down" +.It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up" +.It Li "Search again" Ta "n" Ta "n" +.It Li "Search again in reverse" Ta "N" Ta "N" +.It Li "Search backward" Ta "?" Ta "C-r" +.It Li "Search forward" Ta "/" Ta "C-s" +.It Li "Start of line" Ta "0" Ta "C-a" +.It Li "Start selection" Ta "Space" Ta "C-Space" +.It Li "Top of history" Ta "g" Ta "M->" +.It Li "Transpose characters" Ta "" Ta "C-t" +.El +.Pp +The next and previous word keys use space and the +.Ql - , +.Ql _ +and +.Ql @ +characters as word delimiters by default, but this can be adjusted by +setting the +.Em word-separators +session option. +Next word moves to the start of the next word, next word end to the end of the +next word and previous word to the start of the previous word. +The three next and previous space keys work similarly but use a space alone as +the word separator. +.Pp +The jump commands enable quick movement within a line. +For instance, typing +.Ql f +followed by +.Ql / +will move the cursor to the next +.Ql / +character on the current line. +A +.Ql \&; +will then jump to the next occurrence. +.Pp +Commands in copy mode may be prefaced by an optional repeat count. +With vi key bindings, a prefix is entered using the number keys; with +emacs, the Alt (meta) key and a number begins prefix entry. +For example, to move the cursor forward by ten words, use +.Ql M-1 0 M-f +in emacs mode, and +.Ql 10w +in vi. +.Pp +When copying the selection, the repeat count indicates the buffer index to +replace, if used. +.Pp +Mode key bindings are defined in a set of named tables: +.Em vi-edit +and +.Em emacs-edit +for keys used when line editing at the command prompt; +.Em vi-choice +and +.Em emacs-choice +for keys used when choosing from lists (such as produced by the +.Ic choose-window +command); and +.Em vi-copy +and +.Em emacs-copy +used in copy mode. +The tables may be viewed with the +.Ic list-keys +command and keys modified or removed with +.Ic bind-key +and +.Ic unbind-key . +One command accepts an argument, +.Ic copy-pipe , +which copies the selection and pipes it to a command. +For example the following will bind +.Ql C-q +to copy the selection into +.Pa /tmp +as well as the paste buffer: +.Bd -literal -offset indent +bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" +.Ed +.Pp +The paste buffer key pastes the first line from the top paste buffer on the +stack. +.Pp +The synopsis for the +.Ic copy-mode +command is: +.Bl -tag -width Ds +.It Xo Ic copy-mode +.Op Fl u +.Op Fl t Ar target-pane +.Xc +Enter copy mode. +The +.Fl u +option scrolls one page up. +.El +.Pp +Each window displayed by +.Nm +may be split into one or more +.Em panes ; +each pane takes up a certain area of the display and is a separate terminal. +A window may be split into panes using the +.Ic split-window +command. +Windows may be split horizontally (with the +.Fl h +flag) or vertically. +Panes may be resized with the +.Ic resize-pane +command (bound to +.Ql C-up , +.Ql C-down +.Ql C-left +and +.Ql C-right +by default), the current pane may be changed with the +.Ic select-pane +command and the +.Ic rotate-window +and +.Ic swap-pane +commands may be used to swap panes without changing their position. +Panes are numbered beginning from zero in the order they are created. +.Pp +A number of preset +.Em layouts +are available. +These may be selected with the +.Ic select-layout +command or cycled with +.Ic next-layout +(bound to +.Ql Space +by default); once a layout is chosen, panes within it may be moved and resized +as normal. +.Pp +The following layouts are supported: +.Bl -tag -width Ds +.It Ic even-horizontal +Panes are spread out evenly from left to right across the window. +.It Ic even-vertical +Panes are spread evenly from top to bottom. +.It Ic main-horizontal +A large (main) pane is shown at the top of the window and the remaining panes +are spread from left to right in the leftover space at the bottom. +Use the +.Em main-pane-height +window option to specify the height of the top pane. +.It Ic main-vertical +Similar to +.Ic main-horizontal +but the large pane is placed on the left and the others spread from top to +bottom along the right. +See the +.Em main-pane-width +window option. +.It Ic tiled +Panes are spread out as evenly as possible over the window in both rows and +columns. +.El +.Pp +In addition, +.Ic select-layout +may be used to apply a previously used layout - the +.Ic list-windows +command displays the layout of each window in a form suitable for use with +.Ic select-layout . +For example: +.Bd -literal -offset indent +$ tmux list-windows +0: ksh [159x48] + layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} +$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} +.Ed +.Pp +.Nm +automatically adjusts the size of the layout for the current window size. +Note that a layout cannot be applied to a window with more panes than that +from which the layout was originally defined. +.Pp +Commands related to windows and panes are as follows: +.Bl -tag -width Ds +.It Xo Ic break-pane +.Op Fl dP +.Op Fl F Ar format +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic breakp ) +Break +.Ar target-pane +off from its containing window to make it the only pane in a new window. +If +.Fl d +is given, the new window does not become the current window. +The +.Fl P +option prints information about the new window after it has been created. +By default, it uses the format +.Ql #{session_name}:#{window_index} +but a different format may be specified with +.Fl F . +.It Xo Ic capture-pane +.Op Fl aepPq +.Op Fl b Ar buffer-index +.Op Fl E Ar end-line +.Op Fl S Ar start-line +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic capturep ) +Capture the contents of a pane. +If +.Fl p +is given, the output goes to stdout, otherwise to the buffer specified with +.Fl b +or a new buffer if omitted. +If +.Fl a +is given, the alternate screen is used, and the history is not accessible. +If no alternate screen exists, an error will be returned unless +.Fl q +is given. +If +.Fl e +is given, the output includes escape sequences for text and background +attributes. +.Fl C +also escapes non-printable characters as octal \exxx. +.Fl J +joins wrapped lines and preserves trailing spaces at each line's end. +.Fl P +captures only any output that the pane has received that is the beginning of an +as-yet incomplete escape sequence. +.Pp +.Fl S +and +.Fl E +specify the starting and ending line numbers, zero is the first line of the +visible pane and negative numbers are lines in the history. +The default is to capture only the visible contents of the pane. +.It Xo +.Ic choose-client +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into client choice mode, allowing a client to be selected +interactively from a list. +After a client is chosen, +.Ql %% +is replaced by the client +.Xr pty 4 +path in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "detach-client -t '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo +.Ic choose-list +.Op Fl l Ar items +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into list choice mode, allowing +.Ar items +to be selected. +.Ar items +can be a comma-separated list to display more than one item. +If an item has spaces, that entry must be quoted. +After an item is chosen, +.Ql %% +is replaced by the chosen item in the +.Ar template +and the result is executed as a command. +If +.Ar template +is not given, "run-shell '%%'" is used. +.Ar items +also accepts format specifiers. +For the meaning of this see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo +.Ic choose-session +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into session choice mode, where a session may be selected +interactively from a list. +When one is chosen, +.Ql %% +is replaced by the session name in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "switch-client -t '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo +.Ic choose-tree +.Op Fl suw +.Op Fl b Ar session-template +.Op Fl c Ar window-template +.Op Fl S Ar format +.Op Fl W Ar format +.Op Fl t Ar target-window +.Xc +Put a window into tree choice mode, where either sessions or windows may be +selected interactively from a list. +By default, windows belonging to a session are indented to show their +relationship to a session. +.Pp +Note that the +.Ic choose-window +and +.Ic choose-session +commands are wrappers around +.Ic choose-tree . +.Pp +If +.Fl s +is given, will show sessions. +If +.Fl w +is given, will show windows. +.Pp +By default, the tree is collapsed and sessions must be expanded to windows +with the right arrow key. +The +.Fl u +option will start with all sessions expanded instead. +.Pp +If +.Fl b +is given, will override the default session command. +Note that +.Ql %% +can be used and will be replaced with the session name. +The default option if not specified is "switch-client -t '%%'". +If +.Fl c +is given, will override the default window command. +Like +.Fl b , +.Ql %% +can be used and will be replaced with the session name and window index. +When a window is chosen from the list, the session command is run before the +window command. +.Pp +If +.Fl S +is given will display the specified format instead of the default session +format. +If +.Fl W +is given will display the specified format instead of the default window +format. +For the meaning of the +.Fl s +and +.Fl w +options, see the +.Sx FORMATS +section. +.Pp +This command works only if at least one client is attached. +.It Xo +.Ic choose-window +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into window choice mode, where a window may be chosen +interactively from a list. +After a window is selected, +.Ql %% +is replaced by the session name and window index in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "select-window -t '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Ic display-panes Op Fl t Ar target-client +.D1 (alias: Ic displayp) +Display a visible indicator of each pane shown by +.Ar target-client . +See the +.Ic display-panes-time , +.Ic display-panes-colour , +and +.Ic display-panes-active-colour +session options. +While the indicator is on screen, a pane may be selected with the +.Ql 0 +to +.Ql 9 +keys. +.It Xo Ic find-window +.Op Fl CNT +.Op Fl F Ar format +.Op Fl t Ar target-window +.Ar match-string +.Xc +.D1 (alias: Ic findw ) +Search for the +.Xr fnmatch 3 +pattern +.Ar match-string +in window names, titles, and visible content (but not history). +The flags control matching behavior: +.Fl C +matches only visible window contents, +.Fl N +matches only the window name and +.Fl T +matches only the window title. +The default is +.Fl CNT . +If only one window is matched, it'll be automatically selected, +otherwise a choice list is shown. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo Ic join-pane +.Op Fl bdhv +.Oo Fl l +.Ar size | +.Fl p Ar percentage Oc +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 (alias: Ic joinp ) +Like +.Ic split-window , +but instead of splitting +.Ar dst-pane +and creating a new pane, split it and move +.Ar src-pane +into the space. +This can be used to reverse +.Ic break-pane . +The +.Fl b +option causes +.Ar src-pane +to be joined to left of or above +.Ar dst-pane . +.It Xo Ic kill-pane +.Op Fl a +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic killp ) +Destroy the given pane. +If no panes remain in the containing window, it is also destroyed. +The +.Fl a +option kills all but the pane given with +.Fl t . +.It Xo Ic kill-window +.Op Fl a +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic killw ) +Kill the current window or the window at +.Ar target-window , +removing it from any sessions to which it is linked. +The +.Fl a +option kills all but the window given with +.Fl t . +.It Ic last-pane Op Fl t Ar target-window +.D1 (alias: Ic lastp ) +Select the last (previously selected) pane. +.It Ic last-window Op Fl t Ar target-session +.D1 (alias: Ic last ) +Select the last (previously selected) window. +If no +.Ar target-session +is specified, select the last window of the current session. +.It Xo Ic link-window +.Op Fl dk +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 (alias: Ic linkw ) +Link the window at +.Ar src-window +to the specified +.Ar dst-window . +If +.Ar dst-window +is specified and no such window exists, the +.Ar src-window +is linked there. +If +.Fl k +is given and +.Ar dst-window +exists, it is killed, otherwise an error is generated. +If +.Fl d +is given, the newly linked window is not selected. +.It Xo Ic list-panes +.Op Fl as +.Op Fl F Ar format +.Op Fl t Ar target +.Xc +.D1 (alias: Ic lsp ) +If +.Fl a +is given, +.Ar target +is ignored and all panes on the server are listed. +If +.Fl s +is given, +.Ar target +is a session (or the current session). +If neither is given, +.Ar target +is a window (or the current window). +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Xo Ic list-windows +.Op Fl a +.Op Fl F Ar format +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic lsw ) +If +.Fl a +is given, list all windows on the server. +Otherwise, list windows in the current session or in +.Ar target-session . +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Xo Ic move-pane +.Op Fl bdhv +.Oo Fl l +.Ar size | +.Fl p Ar percentage Oc +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 (alias: Ic movep ) +Like +.Ic join-pane , +but +.Ar src-pane +and +.Ar dst-pane +may belong to the same window. +.It Xo Ic move-window +.Op Fl rdk +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 (alias: Ic movew ) +This is similar to +.Ic link-window , +except the window at +.Ar src-window +is moved to +.Ar dst-window . +With +.Fl r , +all windows in the session are renumbered in sequential order, respecting +the +.Ic base-index +option. +.It Xo Ic new-window +.Op Fl adkP +.Op Fl c Ar start-directory +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl t Ar target-window +.Op Ar shell-command +.Xc +.D1 (alias: Ic neww ) +Create a new window. +With +.Fl a , +the new window is inserted at the next index up from the specified +.Ar target-window , +moving windows up if necessary, +otherwise +.Ar target-window +is the new window location. +.Pp +If +.Fl d +is given, the session does not make the new window the current window. +.Ar target-window +represents the window to be created; if the target already exists an error is +shown, unless the +.Fl k +flag is used, in which case it is destroyed. +.Ar shell-command +is the command to execute. +If +.Ar shell-command +is not specified, the value of the +.Ic default-command +option is used. +.Fl c +specifies the working directory in which the new window is created. +It may have an absolute path or one of the following values (or a subdirectory): +.Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent +.It Li "Empty string" Ta "Current pane's directory" +.It Li "~" Ta "User's home directory" +.It Li "-" Ta "Where session was started" +.It Li "." Ta "Where server was started" +.El +.Pp +When the shell command completes, the window closes. +See the +.Ic remain-on-exit +option to change this behaviour. +.Pp +The +.Ev TERM +environment variable must be set to +.Dq screen +for all programs running +.Em inside +.Nm . +New windows will automatically have +.Dq TERM=screen +added to their environment, but care must be taken not to reset this in shell +start-up files. +.Pp +The +.Fl P +option prints information about the new window after it has been created. +By default, it uses the format +.Ql #{session_name}:#{window_index} +but a different format may be specified with +.Fl F . +.It Ic next-layout Op Fl t Ar target-window +.D1 (alias: Ic nextl ) +Move a window to the next layout and rearrange the panes to fit. +.It Xo Ic next-window +.Op Fl a +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic next ) +Move to the next window in the session. +If +.Fl a +is used, move to the next window with an alert. +.It Xo Ic pipe-pane +.Op Fl o +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 (alias: Ic pipep ) +Pipe any output sent by the program in +.Ar target-pane +to a shell command. +A pane may only be piped to one command at a time, any existing pipe is +closed before +.Ar shell-command +is executed. +The +.Ar shell-command +string may contain the special character sequences supported by the +.Ic status-left +option. +If no +.Ar shell-command +is given, the current pipe (if any) is closed. +.Pp +The +.Fl o +option only opens a new pipe if no previous pipe exists, allowing a pipe to +be toggled with a single key, for example: +.Bd -literal -offset indent +bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' +.Ed +.It Xo Ic previous-layout +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic prevl ) +Move to the previous layout in the session. +.It Xo Ic previous-window +.Op Fl a +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic prev ) +Move to the previous window in the session. +With +.Fl a , +move to the previous window with an alert. +.It Xo Ic rename-window +.Op Fl t Ar target-window +.Ar new-name +.Xc +.D1 (alias: Ic renamew ) +Rename the current window, or the window at +.Ar target-window +if specified, to +.Ar new-name . +.It Xo Ic resize-pane +.Op Fl DLRUZ +.Op Fl t Ar target-pane +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar adjustment +.Xc +.D1 (alias: Ic resizep ) +Resize a pane, up, down, left or right by +.Ar adjustment +with +.Fl U , +.Fl D , +.Fl L +or +.Fl R , +or +to an absolute size +with +.Fl x +or +.Fl y . +The +.Ar adjustment +is given in lines or cells (the default is 1). +.Pp +With +.Fl Z , +the active pane is toggled between zoomed (occupying the whole of the window) +and unzoomed (its normal position in the layout). +.It Xo Ic respawn-pane +.Op Fl k +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 (alias: Ic respawnp ) +Reactivate a pane in which the command has exited (see the +.Ic remain-on-exit +window option). +If +.Ar shell-command +is not given, the command used when the pane was created is executed. +The pane must be already inactive, unless +.Fl k +is given, in which case any existing command is killed. +.It Xo Ic respawn-window +.Op Fl k +.Op Fl t Ar target-window +.Op Ar shell-command +.Xc +.D1 (alias: Ic respawnw ) +Reactivate a window in which the command has exited (see the +.Ic remain-on-exit +window option). +If +.Ar shell-command +is not given, the command used when the window was created is executed. +The window must be already inactive, unless +.Fl k +is given, in which case any existing command is killed. +.It Xo Ic rotate-window +.Op Fl DU +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic rotatew ) +Rotate the positions of the panes within a window, either upward (numerically +lower) with +.Fl U +or downward (numerically higher). +.It Xo Ic select-layout +.Op Fl np +.Op Fl t Ar target-window +.Op Ar layout-name +.Xc +.D1 (alias: Ic selectl ) +Choose a specific layout for a window. +If +.Ar layout-name +is not given, the last preset layout used (if any) is reapplied. +.Fl n +and +.Fl p +are equivalent to the +.Ic next-layout +and +.Ic previous-layout +commands. +.It Xo Ic select-pane +.Op Fl lDLRU +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic selectp ) +Make pane +.Ar target-pane +the active pane in window +.Ar target-window . +If one of +.Fl D , +.Fl L , +.Fl R , +or +.Fl U +is used, respectively the pane below, to the left, to the right, or above the +target pane is used. +.Fl l +is the same as using the +.Ic last-pane +command. +.It Xo Ic select-window +.Op Fl lnpT +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic selectw ) +Select the window at +.Ar target-window . +.Fl l , +.Fl n +and +.Fl p +are equivalent to the +.Ic last-window , +.Ic next-window +and +.Ic previous-window +commands. +If +.Fl T +is given and the selected window is already the current window, +the command behaves like +.Ic last-window . +.It Xo Ic split-window +.Op Fl dhvP +.Op Fl c Ar start-directory +.Oo Fl l +.Ar size | +.Fl p Ar percentage Oc +.Op Fl t Ar target-pane +.Op Ar shell-command +.Op Fl F Ar format +.Xc +.D1 (alias: Ic splitw ) +Create a new pane by splitting +.Ar target-pane : +.Fl h +does a horizontal split and +.Fl v +a vertical split; if neither is specified, +.Fl v +is assumed. +The +.Fl l +and +.Fl p +options specify the size of the new pane in lines (for vertical split) or in +cells (for horizontal split), or as a percentage, respectively. +All other options have the same meaning as for the +.Ic new-window +command. +.It Xo Ic swap-pane +.Op Fl dDU +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 (alias: Ic swapp ) +Swap two panes. +If +.Fl U +is used and no source pane is specified with +.Fl s , +.Ar dst-pane +is swapped with the previous pane (before it numerically); +.Fl D +swaps with the next pane (after it numerically). +.Fl d +instructs +.Nm +not to change the active pane. +.It Xo Ic swap-window +.Op Fl d +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 (alias: Ic swapw ) +This is similar to +.Ic link-window , +except the source and destination windows are swapped. +It is an error if no window exists at +.Ar src-window . +.It Xo Ic unlink-window +.Op Fl k +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic unlinkw ) +Unlink +.Ar target-window . +Unless +.Fl k +is given, a window may be unlinked only if it is linked to multiple sessions - +windows may not be linked to no sessions; +if +.Fl k +is specified and the window is linked to only one session, it is unlinked and +destroyed. +.El +.Sh KEY BINDINGS +.Nm +allows a command to be bound to most keys, with or without a prefix key. +When specifying keys, most represent themselves (for example +.Ql A +to +.Ql Z ) . +Ctrl keys may be prefixed with +.Ql C- +or +.Ql ^ , +and Alt (meta) with +.Ql M- . +In addition, the following special key names are accepted: +.Em Up , +.Em Down , +.Em Left , +.Em Right , +.Em BSpace , +.Em BTab , +.Em DC +(Delete), +.Em End , +.Em Enter , +.Em Escape , +.Em F1 +to +.Em F20 , +.Em Home , +.Em IC +(Insert), +.Em NPage/PageDown/PgDn , +.Em PPage/PageUp/PgUp , +.Em Space , +and +.Em Tab . +Note that to bind the +.Ql \&" +or +.Ql ' +keys, quotation marks are necessary, for example: +.Bd -literal -offset indent +bind-key '"' split-window +bind-key "'" new-window +.Ed +.Pp +Commands related to key bindings are as follows: +.Bl -tag -width Ds +.It Xo Ic bind-key +.Op Fl cnr +.Op Fl t Ar key-table +.Ar key Ar command Op Ar arguments +.Xc +.D1 (alias: Ic bind ) +Bind key +.Ar key +to +.Ar command . +By default (without +.Fl t ) +the primary key bindings are modified (those normally activated with the prefix +key); in this case, if +.Fl n +is specified, it is not necessary to use the prefix key, +.Ar command +is bound to +.Ar key +alone. +The +.Fl r +flag indicates this key may repeat, see the +.Ic repeat-time +option. +.Pp +If +.Fl t +is present, +.Ar key +is bound in +.Ar key-table : +the binding for command mode with +.Fl c +or for normal mode without. +To view the default bindings and possible commands, see the +.Ic list-keys +command. +.It Ic list-keys Op Fl t Ar key-table +.D1 (alias: Ic lsk ) +List all key bindings. +Without +.Fl t +the primary key bindings - those executed when preceded by the prefix key - +are printed. +.Pp +With +.Fl t , +the key bindings in +.Ar key-table +are listed; this may be one of: +.Em vi-edit , +.Em emacs-edit , +.Em vi-choice , +.Em emacs-choice , +.Em vi-copy +or +.Em emacs-copy . +.It Xo Ic send-keys +.Op Fl lR +.Op Fl t Ar target-pane +.Ar key Ar ... +.Xc +.D1 (alias: Ic send ) +Send a key or keys to a window. +Each argument +.Ar key +is the name of the key (such as +.Ql C-a +or +.Ql npage +) to send; if the string is not recognised as a key, it is sent as a series of +characters. +The +.Fl l +flag disables key name lookup and sends the keys literally. +All arguments are sent sequentially from first to last. +The +.Fl R +flag causes the terminal state to be reset. +.It Xo Ic send-prefix +.Op Fl 2 +.Op Fl t Ar target-pane +.Xc +Send the prefix key, or with +.Fl 2 +the secondary prefix key, to a window as if it was pressed. +.It Xo Ic unbind-key +.Op Fl acn +.Op Fl t Ar key-table +.Ar key +.Xc +.D1 (alias: Ic unbind ) +Unbind the command bound to +.Ar key . +Without +.Fl t +the primary key bindings are modified; in this case, if +.Fl n +is specified, the command bound to +.Ar key +without a prefix (if any) is removed. +If +.Fl a +is present, all key bindings are removed. +.Pp +If +.Fl t +is present, +.Ar key +in +.Ar key-table +is unbound: the binding for command mode with +.Fl c +or for normal mode without. +.El +.Sh OPTIONS +The appearance and behaviour of +.Nm +may be modified by changing the value of various options. +There are three types of option: +.Em server options , +.Em session options +and +.Em window options . +.Pp +The +.Nm +server has a set of global options which do not apply to any particular +window or session. +These are altered with the +.Ic set-option +.Fl s +command, or displayed with the +.Ic show-options +.Fl s +command. +.Pp +In addition, each individual session may have a set of session options, and +there is a separate set of global session options. +Sessions which do not have a particular option configured inherit the value +from the global session options. +Session options are set or unset with the +.Ic set-option +command and may be listed with the +.Ic show-options +command. +The available server and session options are listed under the +.Ic set-option +command. +.Pp +Similarly, a set of window options is attached to each window, and there is +a set of global window options from which any unset options are inherited. +Window options are altered with the +.Ic set-window-option +command and can be listed with the +.Ic show-window-options +command. +All window options are documented with the +.Ic set-window-option +command. +.Pp +.Nm +also supports user options which are prefixed with a +.Ql \&@ . +User options may have any name, so long as they are prefixed with +.Ql \&@ , +and be set to any string. +For example +.Bd -literal -offset indent +$ tmux setw -q @foo "abc123" +$ tmux showw -v @foo +abc123 +.Ed +.Pp +Commands which set options are as follows: +.Bl -tag -width Ds +.It Xo Ic set-option +.Op Fl agoqsuw +.Op Fl t Ar target-session | Ar target-window +.Ar option Ar value +.Xc +.D1 (alias: Ic set ) +Set a window option with +.Fl w +(equivalent to the +.Ic set-window-option +command), +a server option with +.Fl s , +otherwise a session option. +.Pp +If +.Fl g +is specified, the global session or window option is set. +With +.Fl a , +and if the option expects a string, +.Ar value +is appended to the existing setting. +The +.Fl u +flag unsets an option, so a session inherits the option from the global +options. +It is not possible to unset a global option. +.Pp +The +.Fl o +flag prevents setting an option that is already set. +.Pp +The +.Fl q +flag suppresses the informational message (as if the +.Ic quiet +server option was set). +.Pp +Available window options are listed under +.Ic set-window-option . +.Pp +.Ar value +depends on the option and may be a number, a string, or a flag (on, off, or +omitted to toggle). +.Pp +Available server options are: +.Bl -tag -width Ds +.It Ic buffer-limit Ar number +Set the number of buffers; as new buffers are added to the top of the stack, +old ones are removed from the bottom if necessary to maintain this maximum +length. +.It Ic escape-time Ar time +Set the time in milliseconds for which +.Nm +waits after an escape is input to determine if it is part of a function or meta +key sequences. +The default is 500 milliseconds. +.It Xo Ic exit-unattached +.Op Ic on | off +.Xc +If enabled, the server will exit when there are no attached clients. +.It Xo Ic quiet +.Op Ic on | off +.Xc +Enable or disable the display of various informational messages (see also the +.Fl q +command line flag). +.It Xo Ic set-clipboard +.Op Ic on | off +.Xc +Attempt to set the terminal clipboard content using the +\ee]52;...\e007 +.Xr xterm 1 +escape sequences. +This option is on by default if there is an +.Em \&Ms +entry in the +.Xr terminfo 5 +description for the client terminal. +Note that this feature needs to be enabled in +.Xr xterm 1 +by setting the resource: +.Bd -literal -offset indent +disallowedWindowOps: 20,21,SetXprop +.Ed +.Pp +Or changing this property from the +.Xr xterm 1 +interactive menu when required. +.El +.Pp +Available session options are: +.Bl -tag -width Ds +.It Ic assume-paste-time Ar milliseconds +If keys are entered faster than one in +.Ar milliseconds , +they are assumed to have been pasted rather than typed and +.Nm +key bindings are not processed. +The default is one millisecond and zero disables. +.It Ic base-index Ar index +Set the base index from which an unused index should be searched when a new +window is created. +The default is zero. +.It Xo Ic bell-action +.Op Ic any | none | current +.Xc +Set action on window bell. +.Ic any +means a bell in any window linked to a session causes a bell in the current +window of that session, +.Ic none +means all bells are ignored and +.Ic current +means only bells in windows other than the current window are ignored. +.It Xo Ic bell-on-alert +.Op Ic on | off +.Xc +If on, ring the terminal bell when an alert +occurs. +.It Ic default-command Ar shell-command +Set the command used for new windows (if not specified when the window is +created) to +.Ar shell-command , +which may be any +.Xr sh 1 +command. +The default is an empty string, which instructs +.Nm +to create a login shell using the value of the +.Ic default-shell +option. +.It Ic default-path Ar path +Set the default working directory for new panes. +If empty (the default), the working directory is determined from the process +running in the active pane, from the command line environment or from the +working directory where the session was created. +Otherwise the same options are available as for the +.Fl c +flag to +.Ic new-window . +.It Ic default-shell Ar path +Specify the default shell. +This is used as the login shell for new windows when the +.Ic default-command +option is set to empty, and must be the full path of the executable. +When started +.Nm +tries to set a default value from the first suitable of the +.Ev SHELL +environment variable, the shell returned by +.Xr getpwuid 3 , +or +.Pa /bin/sh . +This option should be configured when +.Nm +is used as a login shell. +.It Ic default-terminal Ar terminal +Set the default terminal for new windows created in this session - the +default value of the +.Ev TERM +environment variable. +For +.Nm +to work correctly, this +.Em must +be set to +.Ql screen +or a derivative of it. +.It Xo Ic destroy-unattached +.Op Ic on | off +.Xc +If enabled and the session is no longer attached to any clients, it is +destroyed. +.It Xo Ic detach-on-destroy +.Op Ic on | off +.Xc +If on (the default), the client is detached when the session it is attached to +is destroyed. +If off, the client is switched to the most recently active of the remaining +sessions. +.It Ic display-panes-active-colour Ar colour +Set the colour used by the +.Ic display-panes +command to show the indicator for the active pane. +.It Ic display-panes-colour Ar colour +Set the colour used by the +.Ic display-panes +command to show the indicators for inactive panes. +.It Ic display-panes-time Ar time +Set the time in milliseconds for which the indicators shown by the +.Ic display-panes +command appear. +.It Ic display-time Ar time +Set the amount of time for which status line messages and other on-screen +indicators are displayed. +.Ar time +is in milliseconds. +.It Ic history-limit Ar lines +Set the maximum number of lines held in window history. +This setting applies only to new windows - existing window histories are not +resized and retain the limit at the point they were created. +.It Ic lock-after-time Ar number +Lock the session (like the +.Ic lock-session +command) after +.Ar number +seconds of inactivity, or the entire server (all sessions) if the +.Ic lock-server +option is set. +The default is not to lock (set to 0). +.It Ic lock-command Ar shell-command +Command to run when locking each client. +The default is to run +.Xr lock 1 +with +.Fl np . +.It Xo Ic lock-server +.Op Ic on | off +.Xc +If this option is +.Ic on +(the default), +instead of each session locking individually as each has been +idle for +.Ic lock-after-time , +the entire server will lock after +.Em all +sessions would have locked. +This has no effect as a session option; it must be set as a global option. +.It Ic message-attr Ar attributes +Set status line message attributes, where +.Ar attributes +is either +.Ic none +or a comma-delimited list of one or more of: +.Ic bright +(or +.Ic bold ) , +.Ic dim , +.Ic underscore , +.Ic blink , +.Ic reverse , +.Ic hidden , +or +.Ic italics . +.It Ic message-bg Ar colour +Set status line message background colour, where +.Ar colour +is one of: +.Ic black , +.Ic red , +.Ic green , +.Ic yellow , +.Ic blue , +.Ic magenta , +.Ic cyan , +.Ic white , +aixterm bright variants (if supported: +.Ic brightred , +.Ic brightgreen , +and so on), +.Ic colour0 +to +.Ic colour255 +from the 256-colour set, +.Ic default , +or a hexadecimal RGB string such as +.Ql #ffffff , +which chooses the closest match from the default 256-colour set. +.It Ic message-command-attr Ar attributes +Set status line message attributes when in command mode. +.It Ic message-command-bg Ar colour +Set status line message background colour when in command mode. +.It Ic message-command-fg Ar colour +Set status line message foreground colour when in command mode. +.It Ic message-fg Ar colour +Set status line message foreground colour. +.It Ic message-limit Ar number +Set the number of error or information messages to save in the message log for +each client. +The default is 20. +.It Xo Ic mouse-resize-pane +.Op Ic on | off +.Xc +If on, +.Nm +captures the mouse and allows panes to be resized by dragging on their borders. +.It Xo Ic mouse-select-pane +.Op Ic on | off +.Xc +If on, +.Nm +captures the mouse and when a window is split into multiple panes the mouse may +be used to select the current pane. +The mouse click is also passed through to the application as normal. +.It Xo Ic mouse-select-window +.Op Ic on | off +.Xc +If on, clicking the mouse on a window name in the status line will select that +window. +.It Xo Ic mouse-utf8 +.Op Ic on | off +.Xc +If enabled, request mouse input as UTF-8 on UTF-8 terminals. +.It Ic pane-active-border-bg Ar colour +.It Ic pane-active-border-fg Ar colour +Set the pane border colour for the currently active pane. +.It Ic pane-border-bg Ar colour +.It Ic pane-border-fg Ar colour +Set the pane border colour for panes aside from the active pane. +.It Ic prefix Ar key +Set the key accepted as a prefix key. +.It Ic prefix2 Ar key +Set a secondary key accepted as a prefix key. +.It Xo Ic renumber-windows +.Op Ic on | off +.Xc +If on, when a window is closed in a session, automatically renumber the other +windows in numerical order. +This respects the +.Ic base-index +option if it has been set. +If off, do not renumber the windows. +.It Ic repeat-time Ar time +Allow multiple commands to be entered without pressing the prefix-key again +in the specified +.Ar time +milliseconds (the default is 500). +Whether a key repeats may be set when it is bound using the +.Fl r +flag to +.Ic bind-key . +Repeat is enabled for the default keys bound to the +.Ic resize-pane +command. +.It Xo Ic set-remain-on-exit +.Op Ic on | off +.Xc +Set the +.Ic remain-on-exit +window option for any windows first created in this session. +When this option is true, windows in which the running program has +exited do not close, instead remaining open but inactivate. +Use the +.Ic respawn-window +command to reactivate such a window, or the +.Ic kill-window +command to destroy it. +.It Xo Ic set-titles +.Op Ic on | off +.Xc +Attempt to set the client terminal title using the +.Em tsl +and +.Em fsl +.Xr terminfo 5 +entries if they exist. +.Nm +automatically sets these to the \ee]2;...\e007 sequence if +the terminal appears to be an xterm. +This option is off by default. +Note that elinks +will only attempt to set the window title if the STY environment +variable is set. +.It Ic set-titles-string Ar string +String used to set the window title if +.Ic set-titles +is on. +Character sequences are replaced as for the +.Ic status-left +option. +.It Xo Ic status +.Op Ic on | off +.Xc +Show or hide the status line. +.It Ic status-attr Ar attributes +Set status line attributes. +.It Ic status-bg Ar colour +Set status line background colour. +.It Ic status-fg Ar colour +Set status line foreground colour. +.It Ic status-interval Ar interval +Update the status bar every +.Ar interval +seconds. +By default, updates will occur every 15 seconds. +A setting of zero disables redrawing at interval. +.It Xo Ic status-justify +.Op Ic left | centre | right +.Xc +Set the position of the window list component of the status line: left, centre +or right justified. +.It Xo Ic status-keys +.Op Ic vi | emacs +.Xc +Use vi or emacs-style +key bindings in the status line, for example at the command prompt. +The default is emacs, unless the +.Ev VISUAL +or +.Ev EDITOR +environment variables are set and contain the string +.Ql vi . +.It Ic status-left Ar string +Display +.Ar string +to the left of the status bar. +.Ar string +will be passed through +.Xr strftime 3 +before being used. +By default, the session name is shown. +.Ar string +may contain any of the following special character sequences: +.Bl -column "Character pair" "Replaced with" -offset indent +.It Sy "Character pair" Ta Sy "Replaced with" +.It Li "#(shell-command)" Ta "First line of the command's output" +.It Li "#[attributes]" Ta "Colour or attribute change" +.It Li "#H" Ta "Hostname of local host" +.It Li "#h" Ta "Hostname of local host without the domain name" +.It Li "#F" Ta "Current window flag" +.It Li "#I" Ta "Current window index" +.It Li "#D" Ta "Current pane unique identifier" +.It Li "#P" Ta "Current pane index" +.It Li "#S" Ta "Session name" +.It Li "#T" Ta "Current pane title" +.It Li "#W" Ta "Current window name" +.It Li "##" Ta "A literal" Ql # +.El +.Pp +The #(shell-command) form executes +.Ql shell-command +and inserts the first line of its output. +Note that shell commands are only executed once at the interval specified by +the +.Ic status-interval +option: if the status line is redrawn in the meantime, the previous result is +used. +Shell commands are executed with the +.Nm +global environment set (see the +.Sx ENVIRONMENT +section). +.Pp +For details on how the names and titles can be set see the +.Sx "NAMES AND TITLES" +section. +.Pp +#[attributes] allows a comma-separated list of attributes to be specified, +these may be +.Ql fg=colour +to set the foreground colour, +.Ql bg=colour +to set the background colour, the name of one of the attributes (listed under +the +.Ic message-attr +option) to turn an attribute on, or an attribute prefixed with +.Ql no +to turn one off, for example +.Ic nobright . +Examples are: +.Bd -literal -offset indent +#(sysctl vm.loadavg) +#[fg=yellow,bold]#(apm -l)%%#[default] [#S] +.Ed +.Pp +Where appropriate, special character sequences may be prefixed with a number to +specify the maximum length, for example +.Ql #24T . +.Pp +By default, UTF-8 in +.Ar string +is not interpreted, to enable UTF-8, use the +.Ic status-utf8 +option. +.It Ic status-left-attr Ar attributes +Set the attribute of the left part of the status line. +.It Ic status-left-bg Ar colour +Set the background colour of the left part of the status line. +.It Ic status-left-fg Ar colour +Set the foreground colour of the left part of the status line. +.It Ic status-left-length Ar length +Set the maximum +.Ar length +of the left component of the status bar. +The default is 10. +.It Xo Ic status-position +.Op Ic top | bottom +.Xc +Set the position of the status line. +.It Ic status-right Ar string +Display +.Ar string +to the right of the status bar. +By default, the current window title in double quotes, the date and the time +are shown. +As with +.Ic status-left , +.Ar string +will be passed to +.Xr strftime 3 , +character pairs are replaced, and UTF-8 is dependent on the +.Ic status-utf8 +option. +.It Ic status-right-attr Ar attributes +Set the attribute of the right part of the status line. +.It Ic status-right-bg Ar colour +Set the background colour of the right part of the status line. +.It Ic status-right-fg Ar colour +Set the foreground colour of the right part of the status line. +.It Ic status-right-length Ar length +Set the maximum +.Ar length +of the right component of the status bar. +The default is 40. +.It Xo Ic status-utf8 +.Op Ic on | off +.Xc +Instruct +.Nm +to treat top-bit-set characters in the +.Ic status-left +and +.Ic status-right +strings as UTF-8; notably, this is important for wide characters. +This option defaults to off. +.It Ic terminal-overrides Ar string +Contains a list of entries which override terminal descriptions read using +.Xr terminfo 5 . +.Ar string +is a comma-separated list of items each a colon-separated string made up of a +terminal type pattern (matched using +.Xr fnmatch 3 ) +and a set of +.Em name=value +entries. +.Pp +For example, to set the +.Ql clear +.Xr terminfo 5 +entry to +.Ql \ee[H\ee[2J +for all terminal types and the +.Ql dch1 +entry to +.Ql \ee[P +for the +.Ql rxvt +terminal type, the option could be set to the string: +.Bd -literal -offset indent +"*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P" +.Ed +.Pp +The terminal entry value is passed through +.Xr strunvis 3 +before interpretation. +The default value forcibly corrects the +.Ql colors +entry for terminals which support 88 or 256 colours: +.Bd -literal -offset indent +"*88col*:colors=88,*256col*:colors=256,xterm*:XT" +.Ed +.It Ic update-environment Ar variables +Set a space-separated string containing a list of environment variables to be +copied into the session environment when a new session is created or an +existing session is attached. +Any variables that do not exist in the source environment are set to be +removed from the session environment (as if +.Fl r +was given to the +.Ic set-environment +command). +The default is +"DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID +XAUTHORITY". +.It Xo Ic visual-activity +.Op Ic on | off +.Xc +If on, display a status line message when activity occurs in a window +for which the +.Ic monitor-activity +window option is enabled. +.It Xo Ic visual-bell +.Op Ic on | off +.Xc +If this option is on, a message is shown on a bell instead of it being passed +through to the terminal (which normally makes a sound). +Also see the +.Ic bell-action +option. +.It Xo Ic visual-content +.Op Ic on | off +.Xc +Like +.Ic visual-activity , +display a message when content is present in a window +for which the +.Ic monitor-content +window option is enabled. +.It Xo Ic visual-silence +.Op Ic on | off +.Xc +If +.Ic monitor-silence +is enabled, prints a message after the interval has expired on a given window. +.It Ic word-separators Ar string +Sets the session's conception of what characters are considered word +separators, for the purposes of the next and previous word commands in +copy mode. +The default is +.Ql \ -_@ . +.El +.It Xo Ic set-window-option +.Op Fl agoqu +.Op Fl t Ar target-window +.Ar option Ar value +.Xc +.D1 (alias: Ic setw ) +Set a window option. +The +.Fl a , +.Fl g , +.Fl o , +.Fl q +and +.Fl u +flags work similarly to the +.Ic set-option +command. +.Pp +Supported window options are: +.Pp +.Bl -tag -width Ds -compact +.It Xo Ic aggressive-resize +.Op Ic on | off +.Xc +Aggressively resize the chosen window. +This means that +.Nm +will resize the window to the size of the smallest session for which it is the +current window, rather than the smallest session to which it is attached. +The window may resize when the current window is changed on another sessions; +this option is good for full-screen programs which support +.Dv SIGWINCH +and poor for interactive programs such as shells. +.Pp +.It Xo Ic allow-rename +.Op Ic on | off +.Xc +Allow programs to change the window name using a terminal escape +sequence (\\033k...\\033\\\\). +The default is on. +.Pp +.It Xo Ic alternate-screen +.Op Ic on | off +.Xc +This option configures whether programs running inside +.Nm +may use the terminal alternate screen feature, which allows the +.Em smcup +and +.Em rmcup +.Xr terminfo 5 +capabilities. +The alternate screen feature preserves the contents of the window when an +interactive application starts and restores it on exit, so that any output +visible before the application starts reappears unchanged after it exits. +The default is on. +.Pp +.It Xo Ic automatic-rename +.Op Ic on | off +.Xc +Control automatic window renaming. +When this setting is enabled, +.Nm +will attempt - on supported platforms - to rename the window to reflect the +command currently running in it. +This flag is automatically disabled for an individual window when a name +is specified at creation with +.Ic new-window +or +.Ic new-session , +or later with +.Ic rename-window , +or with a terminal escape sequence. +It may be switched off globally with: +.Bd -literal -offset indent +set-window-option -g automatic-rename off +.Ed +.Pp +.It Ic c0-change-interval Ar interval +.It Ic c0-change-trigger Ar trigger +These two options configure a simple form of rate limiting for a pane. +If +.Nm +sees more than +.Ar trigger +C0 sequences that modify the screen (for example, carriage returns, linefeeds +or backspaces) in one millisecond, it will stop updating the pane immediately and +instead redraw it entirely every +.Ar interval +milliseconds. +This helps to prevent fast output (such as +.Xr yes 1 +overwhelming the terminal). +The default is a trigger of 250 and an interval of 100. +A trigger of zero disables the rate limiting. +.Pp +.It Ic clock-mode-colour Ar colour +Set clock colour. +.Pp +.It Xo Ic clock-mode-style +.Op Ic 12 | 24 +.Xc +Set clock hour format. +.Pp +.It Ic force-height Ar height +.It Ic force-width Ar width +Prevent +.Nm +from resizing a window to greater than +.Ar width +or +.Ar height . +A value of zero restores the default unlimited setting. +.Pp +.It Ic main-pane-height Ar height +.It Ic main-pane-width Ar width +Set the width or height of the main (left or top) pane in the +.Ic main-horizontal +or +.Ic main-vertical +layouts. +.Pp +.It Ic mode-attr Ar attributes +Set window modes attributes. +.Pp +.It Ic mode-bg Ar colour +Set window modes background colour. +.Pp +.It Ic mode-fg Ar colour +Set window modes foreground colour. +.Pp +.It Xo Ic mode-keys +.Op Ic vi | emacs +.Xc +Use vi or emacs-style key bindings in copy and choice modes. +As with the +.Ic status-keys +option, the default is emacs, unless +.Ev VISUAL +or +.Ev EDITOR +contains +.Ql vi . +.Pp +.It Xo Ic mode-mouse +.Op Ic on | off | copy-mode +.Xc +Mouse state in modes. +If on, the mouse may be used to enter copy mode and copy a selection by +dragging, to enter copy mode and scroll with the mouse wheel, or to select an +option in choice mode. +If set to +.Em copy-mode , +the mouse behaves as set to on, but cannot be used to enter copy +mode. +.Pp +.It Xo Ic monitor-activity +.Op Ic on | off +.Xc +Monitor for activity in the window. +Windows with activity are highlighted in the status line. +.Pp +.It Ic monitor-content Ar match-string +Monitor content in the window. +When +.Xr fnmatch 3 +pattern +.Ar match-string +appears in the window, it is highlighted in the status line. +.Pp +.It Xo Ic monitor-silence +.Op Ic interval +.Xc +Monitor for silence (no activity) in the window within +.Ic interval +seconds. +Windows that have been silent for the interval are highlighted in the +status line. +An interval of zero disables the monitoring. +.Pp +.It Ic other-pane-height Ar height +Set the height of the other panes (not the main pane) in the +.Ic main-horizontal +layout. +If this option is set to 0 (the default), it will have no effect. +If both the +.Ic main-pane-height +and +.Ic other-pane-height +options are set, the main pane will grow taller to make the other panes the +specified height, but will never shrink to do so. +.Pp +.It Ic other-pane-width Ar width +Like +.Ic other-pane-height , +but set the width of other panes in the +.Ic main-vertical +layout. +.Pp +.It Ic pane-base-index Ar index +Like +.Ic base-index , +but set the starting index for pane numbers. +.Pp +.It Xo Ic remain-on-exit +.Op Ic on | off +.Xc +A window with this flag set is not destroyed when the program running in it +exits. +The window may be reactivated with the +.Ic respawn-window +command. +.Pp +.It Xo Ic synchronize-panes +.Op Ic on | off +.Xc +Duplicate input to any pane to all other panes in the same window (only +for panes that are not in any special mode). +.Pp +.It Xo Ic utf8 +.Op Ic on | off +.Xc +Instructs +.Nm +to expect UTF-8 sequences to appear in this window. +.Pp +.It Ic window-status-bell-attr Ar attributes +Set status line attributes for windows which have a bell alert. +.Pp +.It Ic window-status-bell-bg Ar colour +Set status line background colour for windows with a bell alert. +.Pp +.It Ic window-status-bell-fg Ar colour +Set status line foreground colour for windows with a bell alert. +.Pp +.It Ic window-status-content-attr Ar attributes +Set status line attributes for windows which have a content alert. +.Pp +.It Ic window-status-content-bg Ar colour +Set status line background colour for windows with a content alert. +.Pp +.It Ic window-status-content-fg Ar colour +Set status line foreground colour for windows with a content alert. +.Pp +.It Ic window-status-activity-attr Ar attributes +Set status line attributes for windows which have an activity (or silence) alert. +.Pp +.It Ic window-status-activity-bg Ar colour +Set status line background colour for windows with an activity alert. +.Pp +.It Ic window-status-activity-fg Ar colour +Set status line foreground colour for windows with an activity alert. +.Pp +.It Ic window-status-attr Ar attributes +Set status line attributes for a single window. +.Pp +.It Ic window-status-bg Ar colour +Set status line background colour for a single window. +.Pp +.It Ic window-status-current-attr Ar attributes +Set status line attributes for the currently active window. +.Pp +.It Ic window-status-current-bg Ar colour +Set status line background colour for the currently active window. +.Pp +.It Ic window-status-current-fg Ar colour +Set status line foreground colour for the currently active window. +.Pp +.It Ic window-status-current-format Ar string +Like +.Ar window-status-format , +but is the format used when the window is the current window. +.Pp +.It Ic window-status-last-attr Ar attributes +Set status line attributes for the last active window. +.Pp +.It Ic window-status-last-bg Ar colour +Set status line background colour for the last active window. +.Pp +.It Ic window-status-last-fg Ar colour +Set status line foreground colour for the last active window. +.Pp +.It Ic window-status-fg Ar colour +Set status line foreground colour for a single window. +.Pp +.It Ic window-status-format Ar string +Set the format in which the window is displayed in the status line window list. +See the +.Ar status-left +option for details of special character sequences available. +The default is +.Ql #I:#W#F . +.Pp +.It Ic window-status-separator Ar string +Sets the separator drawn between windows in the status line. +The default is a single space character. +.Pp +.It Xo Ic xterm-keys +.Op Ic on | off +.Xc +If this option is set, +.Nm +will generate +.Xr xterm 1 -style +function key sequences; these have a number included to indicate modifiers such +as Shift, Alt or Ctrl. +The default is off. +.Pp +.It Xo Ic wrap-search +.Op Ic on | off +.Xc +If this option is set, searches will wrap around the end of the pane contents. +The default is on. +.El +.It Xo Ic show-options +.Op Fl gqsvw +.Op Fl t Ar target-session | Ar target-window +.Op Ar option +.Xc +.D1 (alias: Ic show ) +Show the window options (or a single window option if given) with +.Fl w +(equivalent to +.Ic show-window-options ) , +the server options with +.Fl s , +otherwise the session options for +.Ar target session . +Global session or window options are listed if +.Fl g +is used. +.Fl v +shows only the option value, not the name. +If +.Fl q +is set, no error will be returned if +.Ar option +is unset. +.It Xo Ic show-window-options +.Op Fl gv +.Op Fl t Ar target-window +.Op Ar option +.Xc +.D1 (alias: Ic showw ) +List the window options or a single option for +.Ar target-window , +or the global window options if +.Fl g +is used. +.Fl v +shows only the option value, not the name. +.El +.Sh FORMATS +Certain commands accept the +.Fl F +flag with a +.Ar format +argument. +This is a string which controls the output format of the command. +Special character sequences are replaced as documented under the +.Ic status-left +option and an additional long form is accepted. +Replacement variables are enclosed in +.Ql #{ +and +.Ql } , +for example +.Ql #{session_name} +is equivalent to +.Ql #S . +Conditionals are also accepted by prefixing with +.Ql \&? +and separating two alternatives with a comma; +if the specified variable exists and is not zero, the first alternative +is chosen, otherwise the second is used. +For example +.Ql #{?session_attached,attached,not attached} +will include the string +.Ql attached +if the session is attached and the string +.Ql not attached +if it is unattached. +.Pp +The following variables are available, where appropriate: +.Bl -column "session_created_string" "Replaced with" -offset indent +.It Sy "Variable name" Ta Sy "Replaced with" +.It Li "alternate_on" Ta "If pane is in alternate screen" +.It Li "alternate_saved_x" Ta "Saved cursor X in alternate screen" +.It Li "alternate_saved_y" Ta "Saved cursor Y in alternate screen" +.It Li "buffer_sample" Ta "First 50 characters from the specified buffer" +.It Li "buffer_size" Ta "Size of the specified buffer in bytes" +.It Li "client_activity" Ta "Integer time client last had activity" +.It Li "client_activity_string" Ta "String time client last had activity" +.It Li "client_created" Ta "Integer time client created" +.It Li "client_created_string" Ta "String time client created" +.It Li "client_cwd" Ta "Working directory of client" +.It Li "client_height" Ta "Height of client" +.It Li "client_last_session" Ta "Name of the client's last session" +.It Li "client_prefix" Ta "1 if prefix key has been pressed" +.It Li "client_readonly" Ta "1 if client is readonly" +.It Li "client_session" Ta "Name of the client's session" +.It Li "client_termname" Ta "Terminal name of client" +.It Li "client_tty" Ta "Pseudo terminal of client" +.It Li "client_utf8" Ta "1 if client supports utf8" +.It Li "client_width" Ta "Width of client" +.It Li "cursor_flag" Ta "Pane cursor flag" +.It Li "cursor_x" Ta "Cursor X position in pane" +.It Li "cursor_y" Ta "Cursor Y position in pane" +.It Li "history_bytes" Ta "Number of bytes in window history" +.It Li "history_limit" Ta "Maximum window history lines" +.It Li "history_size" Ta "Size of history in bytes" +.It Li "host" Ta "Hostname of local host" +.It Li "insert_flag" Ta "Pane insert flag" +.It Li "keypad_cursor_flag" Ta "Pane keypad cursor flag" +.It Li "keypad_flag" Ta "Pane keypad flag" +.It Li "line" Ta "Line number in the list" +.It Li "mouse_any_flag" Ta "Pane mouse any flag" +.It Li "mouse_button_flag" Ta "Pane mouse button flag" +.It Li "mouse_standard_flag" Ta "Pane mouse standard flag" +.It Li "mouse_utf8_flag" Ta "Pane mouse UTF-8 flag" +.It Li "pane_active" Ta "1 if active pane" +.It Li "pane_current_command" Ta "Current command if available" +.It Li "pane_current_path" Ta "Current path if available" +.It Li "pane_dead" Ta "1 if pane is dead" +.It Li "pane_height" Ta "Height of pane" +.It Li "pane_id" Ta "Unique pane ID" +.It Li "pane_in_mode" Ta "If pane is in a mode" +.It Li "pane_index" Ta "Index of pane" +.It Li "pane_pid" Ta "PID of first process in pane" +.It Li "pane_start_command" Ta "Command pane started with" +.It Li "pane_start_path" Ta "Path pane started with" +.It Li "pane_tabs" Ta "Pane tab positions" +.It Li "pane_title" Ta "Title of pane" +.It Li "pane_tty" Ta "Pseudo terminal of pane" +.It Li "pane_width" Ta "Width of pane" +.It Li "saved_cursor_x" Ta "Saved cursor X in pane" +.It Li "saved_cursor_y" Ta "Saved cursor Y in pane" +.It Li "scroll_region_lower" Ta "Bottom of scroll region in pane" +.It Li "scroll_region_upper" Ta "Top of scroll region in pane" +.It Li "session_attached" Ta "1 if session attached" +.It Li "session_created" Ta "Integer time session created" +.It Li "session_created_string" Ta "String time session created" +.It Li "session_group" Ta "Number of session group" +.It Li "session_grouped" Ta "1 if session in a group" +.It Li "session_height" Ta "Height of session" +.It Li "session_id" Ta "Unique session ID" +.It Li "session_name" Ta "Name of session" +.It Li "session_width" Ta "Width of session" +.It Li "session_windows" Ta "Number of windows in session" +.It Li "window_active" Ta "1 if window active" +.It Li "window_find_matches" Ta "Matched data from the find-window command if available" +.It Li "window_flags" Ta "Window flags" +.It Li "window_height" Ta "Height of window" +.It Li "window_id" Ta "Unique window ID" +.It Li "window_index" Ta "Index of window" +.It Li "window_layout" Ta "Window layout description" +.It Li "window_name" Ta "Name of window" +.It Li "window_panes" Ta "Number of panes in window" +.It Li "window_width" Ta "Width of window" +.It Li "wrap_flag" Ta "Pane wrap flag" +.El +.Sh NAMES AND TITLES +.Nm +distinguishes between names and titles. +Windows and sessions have names, which may be used to specify them in targets +and are displayed in the status line and various lists: the name is the +.Nm +identifier for a window or session. +Only panes have titles. +A pane's title is typically set by the program running inside the pane and +is not modified by +.Nm . +It is the same mechanism used to set for example the +.Xr xterm 1 +window title in an +.Xr X 7 +window manager. +Windows themselves do not have titles - a window's title is the title of its +active pane. +.Nm +itself may set the title of the terminal in which the client is running, see +the +.Ic set-titles +option. +.Pp +A session's name is set with the +.Ic new-session +and +.Ic rename-session +commands. +A window's name is set with one of: +.Bl -enum -width Ds +.It +A command argument (such as +.Fl n +for +.Ic new-window +or +.Ic new-session ) . +.It +An escape sequence: +.Bd -literal -offset indent +$ printf '\e033kWINDOW_NAME\e033\e\e' +.Ed +.It +Automatic renaming, which sets the name to the active command in the window's +active pane. +See the +.Ic automatic-rename +option. +.El +.Pp +When a pane is first created, its title is the hostname. +A pane's title can be set via the OSC title setting sequence, for example: +.Bd -literal -offset indent +$ printf '\e033]2;My Title\e033\e\e' +.Ed +.Sh ENVIRONMENT +When the server is started, +.Nm +copies the environment into the +.Em global environment ; +in addition, each session has a +.Em session environment . +When a window is created, the session and global environments are merged. +If a variable exists in both, the value from the session environment is used. +The result is the initial environment passed to the new process. +.Pp +The +.Ic update-environment +session option may be used to update the session environment from the client +when a new session is created or an old reattached. +.Nm +also initialises the +.Ev TMUX +variable with some internal information to allow commands to be executed +from inside, and the +.Ev TERM +variable with the correct terminal setting of +.Ql screen . +.Pp +Commands to alter and view the environment are: +.Bl -tag -width Ds +.It Xo Ic set-environment +.Op Fl gru +.Op Fl t Ar target-session +.Ar name Op Ar value +.Xc +.D1 (alias: Ic setenv ) +Set or unset an environment variable. +If +.Fl g +is used, the change is made in the global environment; otherwise, it is applied +to the session environment for +.Ar target-session . +The +.Fl u +flag unsets a variable. +.Fl r +indicates the variable is to be removed from the environment before starting a +new process. +.It Xo Ic show-environment +.Op Fl g +.Op Fl t Ar target-session +.Op Ar variable +.Xc +.D1 (alias: Ic showenv ) +Display the environment for +.Ar target-session +or the global environment with +.Fl g . +If +.Ar variable +is omitted, all variables are shown. +Variables removed from the environment are prefixed with +.Ql - . +.El +.Sh STATUS LINE +.Nm +includes an optional status line which is displayed in the bottom line of each +terminal. +By default, the status line is enabled (it may be disabled with the +.Ic status +session option) and contains, from left-to-right: the name of the current +session in square brackets; the window list; the title of the active pane +in double quotes; and the time and date. +.Pp +The status line is made of three parts: configurable left and right sections +(which may contain dynamic content such as the time or output from a shell +command, see the +.Ic status-left , +.Ic status-left-length , +.Ic status-right , +and +.Ic status-right-length +options below), and a central window list. +By default, the window list shows the index, name and (if any) flag of the +windows present in the current session in ascending numerical order. +It may be customised with the +.Ar window-status-format +and +.Ar window-status-current-format +options. +The flag is one of the following symbols appended to the window name: +.Bl -column "Symbol" "Meaning" -offset indent +.It Sy "Symbol" Ta Sy "Meaning" +.It Li "*" Ta "Denotes the current window." +.It Li "-" Ta "Marks the last window (previously selected)." +.It Li "#" Ta "Window is monitored and activity has been detected." +.It Li "!" Ta "A bell has occurred in the window." +.It Li "+" Ta "Window is monitored for content and it has appeared." +.It Li "~" Ta "The window has been silent for the monitor-silence interval." +.It Li "Z" Ta "The window's active pane is zoomed." +.El +.Pp +The # symbol relates to the +.Ic monitor-activity +and + to the +.Ic monitor-content +window options. +The window name is printed in inverted colours if an alert (bell, activity or +content) is present. +.Pp +The colour and attributes of the status line may be configured, the entire +status line using the +.Ic status-attr , +.Ic status-fg +and +.Ic status-bg +session options and individual windows using the +.Ic window-status-attr , +.Ic window-status-fg +and +.Ic window-status-bg +window options. +.Pp +The status line is automatically refreshed at interval if it has changed, the +interval may be controlled with the +.Ic status-interval +session option. +.Pp +Commands related to the status line are as follows: +.Bl -tag -width Ds +.It Xo Ic command-prompt +.Op Fl I Ar inputs +.Op Fl p Ar prompts +.Op Fl t Ar target-client +.Op Ar template +.Xc +Open the command prompt in a client. +This may be used from inside +.Nm +to execute commands interactively. +.Pp +If +.Ar template +is specified, it is used as the command. +If present, +.Fl I +is a comma-separated list of the initial text for each prompt. +If +.Fl p +is given, +.Ar prompts +is a comma-separated list of prompts which are displayed in order; otherwise +a single prompt is displayed, constructed from +.Ar template +if it is present, or +.Ql \&: +if not. +.Pp +Both +.Ar inputs +and +.Ar prompts +may contain the special character sequences supported by the +.Ic status-left +option. +.Pp +Before the command is executed, the first occurrence of the string +.Ql %% +and all occurrences of +.Ql %1 +are replaced by the response to the first prompt, the second +.Ql %% +and all +.Ql %2 +are replaced with the response to the second prompt, and so on for further +prompts. +Up to nine prompt responses may be replaced +.Po +.Ql %1 +to +.Ql %9 +.Pc . +.It Xo Ic confirm-before +.Op Fl p Ar prompt +.Op Fl t Ar target-client +.Ar command +.Xc +.D1 (alias: Ic confirm ) +Ask for confirmation before executing +.Ar command . +If +.Fl p +is given, +.Ar prompt +is the prompt to display; otherwise a prompt is constructed from +.Ar command . +It may contain the special character sequences supported by the +.Ic status-left +option. +.Pp +This command works only from inside +.Nm . +.It Xo Ic display-message +.Op Fl p +.Op Fl c Ar target-client +.Op Fl t Ar target-pane +.Op Ar message +.Xc +.D1 (alias: Ic display ) +Display a message. +If +.Fl p +is given, the output is printed to stdout, otherwise it is displayed in the +.Ar target-client +status line. +The format of +.Ar message +is described in the +.Sx FORMATS +section; information is taken from +.Ar target-pane +if +.Fl t +is given, otherwise the active pane for the session attached to +.Ar target-client . +.El +.Sh BUFFERS +.Nm +maintains a stack of +.Em paste buffers . +Up to the value of the +.Ic buffer-limit +option are kept; when a new buffer is added, the buffer at the bottom of the +stack is removed. +Buffers may be added using +.Ic copy-mode +or the +.Ic set-buffer +command, and pasted into a window using the +.Ic paste-buffer +command. +.Pp +A configurable history buffer is also maintained for each window. +By default, up to 2000 lines are kept; this can be altered with the +.Ic history-limit +option (see the +.Ic set-option +command above). +.Pp +The buffer commands are as follows: +.Bl -tag -width Ds +.It Xo +.Ic choose-buffer +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into buffer choice mode, where a buffer may be chosen +interactively from a list. +After a buffer is selected, +.Ql %% +is replaced by the buffer index in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "paste-buffer -b '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Ic clear-history Op Fl t Ar target-pane +.D1 (alias: Ic clearhist ) +Remove and free the history for the specified pane. +.It Ic delete-buffer Op Fl b Ar buffer-index +.D1 (alias: Ic deleteb ) +Delete the buffer at +.Ar buffer-index , +or the top buffer if not specified. +.It Xo Ic list-buffers +.Op Fl F Ar format +.Xc +.D1 (alias: Ic lsb ) +List the global buffers. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Xo Ic load-buffer +.Op Fl b Ar buffer-index +.Ar path +.Xc +.D1 (alias: Ic loadb ) +Load the contents of the specified paste buffer from +.Ar path . +.It Xo Ic paste-buffer +.Op Fl dpr +.Op Fl b Ar buffer-index +.Op Fl s Ar separator +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic pasteb ) +Insert the contents of a paste buffer into the specified pane. +If not specified, paste into the current one. +With +.Fl d , +also delete the paste buffer from the stack. +When output, any linefeed (LF) characters in the paste buffer are replaced with +a separator, by default carriage return (CR). +A custom separator may be specified using the +.Fl s +flag. +The +.Fl r +flag means to do no replacement (equivalent to a separator of LF). +If +.Fl p +is specified, paste bracket control codes are inserted around the +buffer if the application has requested bracketed paste mode. +.It Xo Ic save-buffer +.Op Fl a +.Op Fl b Ar buffer-index +.Ar path +.Xc +.D1 (alias: Ic saveb ) +Save the contents of the specified paste buffer to +.Ar path . +The +.Fl a +option appends to rather than overwriting the file. +.It Xo Ic set-buffer +.Op Fl b Ar buffer-index +.Ar data +.Xc +.D1 (alias: Ic setb ) +Set the contents of the specified buffer to +.Ar data . +.It Xo Ic show-buffer +.Op Fl b Ar buffer-index +.Xc +.D1 (alias: Ic showb ) +Display the contents of the specified buffer. +.El +.Sh MISCELLANEOUS +Miscellaneous commands are as follows: +.Bl -tag -width Ds +.It Ic clock-mode Op Fl t Ar target-pane +Display a large clock. +.It Xo Ic if-shell +.Op Fl b +.Op Fl t Ar target-pane +.Ar shell-command command +.Op Ar command +.Xc +.D1 (alias: Ic if ) +Execute the first +.Ar command +if +.Ar shell-command +returns success or the second +.Ar command +otherwise. +Before being executed, shell-command is expanded using the rules specified in the +.Sx FORMATS +section, including those relevant to +.Ar target-pane . +With +.Fl b , +.Ar shell-command +is run in the background. +.It Ic lock-server +.D1 (alias: Ic lock ) +Lock each client individually by running the command specified by the +.Ic lock-command +option. +.It Xo Ic run-shell +.Fl b +.Op Fl t Ar target-pane +.Ar shell-command +.Xc +.D1 (alias: Ic run ) +Execute +.Ar shell-command +in the background without creating a window. +Before being executed, shell-command is expanded using the rules specified in +the +.Sx FORMATS +section. +With +.Fl b , +the command is run in the background. +After it finishes, any output to stdout is displayed in copy mode (in the pane +specified by +.Fl t +or the current pane if omitted). +If the command doesn't return success, the exit status is also displayed. +.It Ic server-info +.D1 (alias: Ic info ) +Show server information and terminal details. +.It Xo Ic wait-for +.Fl LSU +.Ar channel +.Xc +.D1 (alias: Ic wait ) +When used without options, prevents the client from exiting until woken using +.Ic wait-for +.Fl S +with the same channel. +When +.Fl L +is used, the channel is locked and any clients that try to lock the same +channel are made to wait until the channel is unlocked with +.Ic wait-for +.Fl U . +This command only works from outside +.Nm . +.El +.Sh TERMINFO EXTENSIONS +.Nm +understands some extensions to +.Xr terminfo 5 : +.Bl -tag -width Ds +.It Em Cc , Cr +Set the cursor colour. +The first takes a single string argument and is used to set the colour; +the second takes no arguments and restores the default cursor colour. +If set, a sequence such as this may be used +to change the cursor colour from inside +.Nm : +.Bd -literal -offset indent +$ printf '\e033]12;red\e033\e\e' +.Ed +.It Em Cs , Csr +Change the cursor style. +If set, a sequence such as this may be used +to change the cursor to an underline: +.Bd -literal -offset indent +$ printf '\e033[4 q' +.Ed +.Pp +If +.Em Csr +is set, it will be used to reset the cursor style instead +of +.Em Cs . +.It Em \&Ms +This sequence can be used by +.Nm +to store the current buffer in the host terminal's selection (clipboard). +See the +.Em set-clipboard +option above and the +.Xr xterm 1 +man page. +.El +.Sh CONTROL MODE +.Nm +offers a textual interface called +.Em control mode . +This allows applications to communicate with +.Nm +using a simple text-only protocol. +.Pp +In control mode, a client sends +.Nm +commands or command sequences terminated by newlines on standard input. +Each command will produce one block of output on standard output. +An output block consists of a +.Em %begin +line followed by the output (which may be empty). +The output block ends with a +.Em %end +or +.Em %error . +.Em %begin +and matching +.Em %end +or +.Em %error +have two arguments: an integer time (as seconds from epoch) and command number. +For example: +.Bd -literal -offset indent +%begin 1363006971 2 +0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) +%end 1363006971 2 +.Ed +.Pp +In control mode, +.Nm +outputs notifications. +A notification will never occur inside an output block. +.Pp +The following notifications are defined: +.Bl -tag -width Ds +.It Ic %exit Op Ar reason +The +.Nm +client is exiting immediately, either because it is not attached to any session +or an error occurred. +If present, +.Ar reason +describes why the client exited. +.It Ic %layout-change Ar window-id Ar window-layout +The layout of a window with ID +.Ar window-id +changed. +The new layout is +.Ar window-layout . +.It Ic %output Ar pane-id Ar value +A window pane produced output. +.Ar value +escapes non-printable characters and backslash as octal \\xxx. +.It Ic %session-changed Ar session-id Ar name +The client is now attached to the session with ID +.Ar session-id , +which is named +.Ar name . +.It Ic %session-renamed Ar name +The current session was renamed to +.Ar name . +.It Ic %sessions-changed +A session was created or destroyed. +.It Ic %unlinked-window-add Ar window-id +The window with ID +.Ar window-id +was created but is not linked to the current session. +.It Ic %window-add Ar window-id +The window with ID +.Ar window-id +was linked to the current session. +.It Ic %window-close Ar window-id +The window with ID +.Ar window-id +closed. +.It Ic %window-renamed Ar window-id Ar name +The window with ID +.Ar window-id +was renamed to +.Ar name . +.El +.Sh FILES +.Bl -tag -width "/etc/tmux.confXXX" -compact +.It Pa ~/.tmux.conf +Default +.Nm +configuration file. +.It Pa /etc/tmux.conf +System-wide configuration file. +.El +.Sh EXAMPLES +To create a new +.Nm +session running +.Xr vi 1 : +.Pp +.Dl $ tmux new-session vi +.Pp +Most commands have a shorter form, known as an alias. +For new-session, this is +.Ic new : +.Pp +.Dl $ tmux new vi +.Pp +Alternatively, the shortest unambiguous form of a command is accepted. +If there are several options, they are listed: +.Bd -literal -offset indent +$ tmux n +ambiguous command: n, could be: new-session, new-window, next-window +.Ed +.Pp +Within an active session, a new window may be created by typing +.Ql C-b c +(Ctrl +followed by the +.Ql b +key +followed by the +.Ql c +key). +.Pp +Windows may be navigated with: +.Ql C-b 0 +(to select window 0), +.Ql C-b 1 +(to select window 1), and so on; +.Ql C-b n +to select the next window; and +.Ql C-b p +to select the previous window. +.Pp +A session may be detached using +.Ql C-b d +(or by an external event such as +.Xr ssh 1 +disconnection) and reattached with: +.Pp +.Dl $ tmux attach-session +.Pp +Typing +.Ql C-b \&? +lists the current key bindings in the current window; up and down may be used +to navigate the list or +.Ql q +to exit from it. +.Pp +Commands to be run when the +.Nm +server is started may be placed in the +.Pa ~/.tmux.conf +configuration file. +Common examples include: +.Pp +Changing the default prefix key: +.Bd -literal -offset indent +set-option -g prefix C-a +unbind-key C-b +bind-key C-a send-prefix +.Ed +.Pp +Turning the status line off, or changing its colour: +.Bd -literal -offset indent +set-option -g status off +set-option -g status-bg blue +.Ed +.Pp +Setting other options, such as the default command, +or locking after 30 minutes of inactivity: +.Bd -literal -offset indent +set-option -g default-command "exec /bin/ksh" +set-option -g lock-after-time 1800 +.Ed +.Pp +Creating new key bindings: +.Bd -literal -offset indent +bind-key b set-option status +bind-key / command-prompt "split-window 'exec man %%'" +bind-key S command-prompt "new-window -n %1 'ssh %1'" +.Ed +.Sh SEE ALSO +.Xr pty 4 +.Sh AUTHORS +.An Nicholas Marriott Aq nicm@users.sourceforge.net -- cgit From 88428cff3a0ef2e2013e990679dc746c58a99d12 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 17 Apr 2013 08:41:41 +0000 Subject: %zu format for size_t. --- job.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/job.c b/job.c index 291e000e..0ae03b31 100644 --- a/job.c +++ b/job.c @@ -144,8 +144,8 @@ job_write_callback(unused struct bufferevent *bufev, void *data) struct job *job = data; size_t len = EVBUFFER_LENGTH(EVBUFFER_OUTPUT(job->event)); - log_debug("job write %p: %s, pid %ld, output left %lu", job, job->cmd, - (long) job->pid, (unsigned long) len); + log_debug("job write %p: %s, pid %ld, output left %zu", job, job->cmd, + (long) job->pid, len); if (len == 0) { shutdown(job->fd, SHUT_WR); -- cgit From 55640a31b3fbe5fd9b3eb4537779e2ffac58f47d Mon Sep 17 00:00:00 2001 From: Theo Deraadt Date: Wed, 17 Apr 2013 14:52:31 +0000 Subject: (long long) and %lld for time_t output ok nicm --- format.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/format.c b/format.c index b357876e..9918cfe8 100644 --- a/format.c +++ b/format.c @@ -288,7 +288,7 @@ format_session(struct format_tree *ft, struct session *s) format_add(ft, "session_group", "%u", session_group_index(sg)); t = s->creation_time.tv_sec; - format_add(ft, "session_created", "%ld", (long) t); + format_add(ft, "session_created", "%lld", (long long) t); tim = ctime(&t); *strchr(tim, '\n') = '\0'; format_add(ft, "session_created_string", "%s", tim); @@ -314,13 +314,13 @@ format_client(struct format_tree *ft, struct client *c) format_add(ft, "client_termname", "%s", c->tty.termname); t = c->creation_time.tv_sec; - format_add(ft, "client_created", "%ld", (long) t); + format_add(ft, "client_created", "%lld", (long long) t); tim = ctime(&t); *strchr(tim, '\n') = '\0'; format_add(ft, "client_created_string", "%s", tim); t = c->activity_time.tv_sec; - format_add(ft, "client_activity", "%ld", (long) t); + format_add(ft, "client_activity", "%lld", (long long) t); tim = ctime(&t); *strchr(tim, '\n') = '\0'; format_add(ft, "client_activity_string", "%s", tim); -- cgit From 5dda1abc32b7b1eb59901a5592569e21d88c6ad2 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Sun, 21 Apr 2013 21:32:00 +0000 Subject: Don't let server_client_check_focus use a dead bufferevent, from Romain Francoise. --- server-client.c | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/server-client.c b/server-client.c index 6cacefa7..3b7b988a 100644 --- a/server-client.c +++ b/server-client.c @@ -514,8 +514,10 @@ server_client_loop(void) w->flags &= ~WINDOW_REDRAW; TAILQ_FOREACH(wp, &w->panes, entry) { - server_client_check_focus(wp); - server_client_check_resize(wp); + if (wp->fd != -1) { + server_client_check_focus(wp); + server_client_check_resize(wp); + } wp->flags &= ~PANE_REDRAW; } } @@ -527,7 +529,7 @@ server_client_check_resize(struct window_pane *wp) { struct winsize ws; - if (wp->fd == -1 || !(wp->flags & PANE_RESIZE)) + if (!(wp->flags & PANE_RESIZE)) return; memset(&ws, 0, sizeof ws); -- cgit From a46ccbd883495d2acb3eab89e5bcdb61c0c7e195 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 09:39:21 +0100 Subject: -paths.h. Fixes Solaris, from Dagobert Michelsen. --- tmux.c | 1 - 1 file changed, 1 deletion(-) diff --git a/tmux.c b/tmux.c index e6de5cfe..2916bbb5 100644 --- a/tmux.c +++ b/tmux.c @@ -23,7 +23,6 @@ #include #include #include -#include #include #include #include -- cgit From d89b35e6826ecaccc4d2f421c8013f35ec5854a0 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 08:42:19 +0000 Subject: Use lockf which is more portable than flock, from Dagobert Michelsen. --- client.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/client.c b/client.c index 70e7f1ec..0c8657eb 100644 --- a/client.c +++ b/client.c @@ -78,8 +78,8 @@ client_get_lock(char *lockfile) if ((lockfd = open(lockfile, O_WRONLY|O_CREAT, 0600)) == -1) fatal("open failed"); - if (flock(lockfd, LOCK_EX|LOCK_NB) == -1 && errno == EWOULDBLOCK) { - while (flock(lockfd, LOCK_EX) == -1 && errno == EINTR) + if (lockf(lockfd, F_TLOCK, 0) == -1 && errno == EAGAIN) { + while (lockf(lockfd, F_LOCK, 0) == -1 && errno == EINTR) /* nothing */; close(lockfd); return (-1); -- cgit From 792e2856c9774cca262929f81b9adbbac0fa1d13 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 09:44:15 +0100 Subject: Add compat for cfmakeraw, from Dagobert Michelsen. --- Makefile.am | 3 +++ compat.h | 5 +++++ compat/cfmakeraw.c | 32 ++++++++++++++++++++++++++++++++ configure.ac | 8 ++++++++ 4 files changed, 48 insertions(+) create mode 100644 compat/cfmakeraw.c diff --git a/Makefile.am b/Makefile.am index b85eae0c..c5369fd9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -233,6 +233,9 @@ endif if NO_B64_NTOP nodist_tmux_SOURCES += compat/b64_ntop.c endif +if NO_CFMAKERAW +nodist_tmux_SOURCES += compat/cfmakeraw.c +endif # Build tmux.1 in the right format. tmux.1: tmux.1.in diff --git a/compat.h b/compat.h index 622006e1..d3973797 100644 --- a/compat.h +++ b/compat.h @@ -236,6 +236,11 @@ int setenv(const char *, const char *, int); int unsetenv(const char *); #endif +#ifndef HAVE_CFMAKERAW +/* cfmakeraw.c */ +void cfmakeraw(struct termios *tio); +#endif + #ifdef HAVE_GETOPT #include #else diff --git a/compat/cfmakeraw.c b/compat/cfmakeraw.c new file mode 100644 index 00000000..3f8dc7e5 --- /dev/null +++ b/compat/cfmakeraw.c @@ -0,0 +1,32 @@ +/* $Id$ */ + +/* + * Copyright (c) 2013 Dagobert Michelsen + * Copyright (c) 2013 Nicholas Marriott + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER + * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING + * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#include + +#include "tmux.h" + +void +cfmakeraw(struct termios *tio) +{ + tio->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP|INLCR|IGNCR|ICRNL|IXON); + tio->c_oflag &= ~OPOST; + tio->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN); + tio->c_cflag &= ~(CSIZE|PARENB); + tio->c_cflag |= CS8; +} diff --git a/configure.ac b/configure.ac index b4f76f5f..80cf1266 100644 --- a/configure.ac +++ b/configure.ac @@ -313,6 +313,13 @@ if test "x$found_strnvis" = xyes; then fi AM_CONDITIONAL(NO_VIS, [test "x$found_strnvis" = xno]) +# Look for cfmakeraw, compat/cfmakeraw.c used if missing. +AC_CHECK_FUNC(cfmakeraw, found_cfmakeraw=yes, found_cfmakeraw=no) +if test "x$found_cfmakeraw" = xyes; then + AC_DEFINE(HAVE_CFMAKERAW) +fi +AM_CONDITIONAL(NO_CFMAKERAW, [test "x$found_cfmakeraw" = xno]) + # Look for getopt. glibc's getopt does not enforce argument order and the ways # of making it do so are stupid, so just use our own instead. AC_CHECK_FUNC(getopt, found_getopt=yes, found_getopt=no) @@ -345,6 +352,7 @@ AC_CHECK_FUNCS( dirfd \ setproctitle \ sysconf \ + cfmakeraw \ ] ) -- cgit From 11b90bc9591b4b101efef1f8a9a0d9656d2953c9 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 14:04:40 +0100 Subject: Pass tmux.1.in to awk on stdin rather than as an argument. --- Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile.am b/Makefile.am index c5369fd9..c131940a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -242,7 +242,7 @@ tmux.1: tmux.1.in if test x@MANFORMAT@ = xmdoc; then \ cp tmux.1.in tmux.1; \ else \ - $(AWK) -fmdoc2man.awk tmux.1.in >tmux.1; \ + $(AWK) -fmdoc2man.awk tmux.1; \ fi # Update SF web site. -- cgit From 46c7dbef0f7803dad39db355ee866ecab8db696c Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 13:35:18 +0000 Subject: Call recalculate_sizes() after killing window in case it is in a grouped session, from Daniel Ralston. --- server-fn.c | 1 + 1 file changed, 1 insertion(+) diff --git a/server-fn.c b/server-fn.c index c0b005e8..d92754e1 100644 --- a/server-fn.c +++ b/server-fn.c @@ -283,6 +283,7 @@ server_kill_window(struct window *w) if (options_get_number(&s->options, "renumber-windows")) session_renumber_windows(s); } + recalculate_sizes(); } int -- cgit From 04f54ab38f9a5f32e6fb89b57380cc7150c08006 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 16:34:53 +0000 Subject: Get session of -t window rather than client's window. --- cmd-choose-tree.c | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/cmd-choose-tree.c b/cmd-choose-tree.c index f22f17c2..db0333e7 100644 --- a/cmd-choose-tree.c +++ b/cmd-choose-tree.c @@ -89,10 +89,7 @@ cmd_choose_tree_exec(struct cmd *self, struct cmd_q *cmdq) return (CMD_RETURN_ERROR); } - if ((s = c->session) == NULL) - return (CMD_RETURN_ERROR); - - if ((wl = cmd_find_window(cmdq, args_get(args, 't'), NULL)) == NULL) + if ((wl = cmd_find_window(cmdq, args_get(args, 't'), &s)) == NULL) return (CMD_RETURN_ERROR); if (window_pane_set_mode(wl->window->active, &window_choose_mode) != 0) -- cgit From 3d2b7d5bce9532cedd647ace319afbf95ebe0e20 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Mon, 22 Apr 2013 22:17:29 +0000 Subject: When using choose-tree -u, start with the current window highlighted. From Thomas Adam. --- cmd-choose-tree.c | 5 ++++- tmux.h | 2 ++ window-choose.c | 14 +++++++++++--- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/cmd-choose-tree.c b/cmd-choose-tree.c index db0333e7..601d24f1 100644 --- a/cmd-choose-tree.c +++ b/cmd-choose-tree.c @@ -228,9 +228,12 @@ windows_only: free(final_win_template_last); window_choose_ready(wl->window->active, cur_win, NULL); + window_choose_collapse_all(wl->window->active); - if (args_has(args, 'u')) + if (args_has(args, 'u')) { window_choose_expand_all(wl->window->active); + window_choose_set_current(wl->window->active, cur_win); + } return (CMD_RETURN_NORMAL); } diff --git a/tmux.h b/tmux.h index 053b574e..8fb06223 100644 --- a/tmux.h +++ b/tmux.h @@ -2257,6 +2257,8 @@ struct window_choose_data *window_choose_add_item(struct window_pane *, struct client *, struct winlink *, const char *, const char *, u_int); void window_choose_expand_all(struct window_pane *); +void window_choose_collapse_all(struct window_pane *); +void window_choose_set_current(struct window_pane *, u_int); /* names.c */ void queue_window_name(struct window *); diff --git a/window-choose.c b/window-choose.c index 792224c1..38773605 100644 --- a/window-choose.c +++ b/window-choose.c @@ -44,7 +44,6 @@ void window_choose_scroll_down(struct window_pane *); void window_choose_collapse(struct window_pane *, struct session *); void window_choose_expand(struct window_pane *, struct session *, u_int); -void window_choose_collapse_all(struct window_pane *); enum window_choose_input_type { WINDOW_CHOOSE_NORMAL = -1, @@ -102,8 +101,7 @@ window_choose_add(struct window_pane *wp, struct window_choose_data *wcd) } void -window_choose_ready(struct window_pane *wp, u_int cur, - void (*callbackfn)(struct window_choose_data *)) +window_choose_set_current(struct window_pane *wp, u_int cur) { struct window_choose_mode_data *data = wp->modedata; struct screen *s = &data->screen; @@ -112,12 +110,22 @@ window_choose_ready(struct window_pane *wp, u_int cur, if (data->selected > screen_size_y(s) - 1) data->top = ARRAY_LENGTH(&data->list) - screen_size_y(s); + window_choose_redraw_screen(wp); +} + +void +window_choose_ready(struct window_pane *wp, u_int cur, + void (*callbackfn)(struct window_choose_data *)) +{ + struct window_choose_mode_data *data = wp->modedata; + data->callbackfn = callbackfn; if (data->callbackfn == NULL) data->callbackfn = window_choose_default_callback; ARRAY_CONCAT(&data->old_list, &data->list); + window_choose_set_current(wp, cur); window_choose_collapse_all(wp); } -- cgit From 4f3c31a6b63f4489bfc672b510036fd8d9491595 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 24 Apr 2013 10:57:03 +0100 Subject: Use sysconfdir for the location of global tmux.conf (but default it to /etc), based on changes from Dagobert Michelsen. --- Makefile.am | 7 ++++--- configure.ac | 3 +++ server.c | 8 ++++---- tmux.1.in | 6 +++--- tmux.c | 2 +- tmux.h | 4 ---- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/Makefile.am b/Makefile.am index c131940a..726582a5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -15,7 +15,7 @@ dist-hook: find $(distdir) -name .svn -type d|xargs rm -Rf # Preprocessor flags. -CPPFLAGS += @XOPEN_DEFINES@ +CPPFLAGS += @XOPEN_DEFINES@ -DTMUX_CONF="\"$(sysconfdir)/tmux.conf\"" # glibc as usual does things ass-backwards and hides useful things by default, # so everyone has to add this. @@ -240,9 +240,10 @@ endif # Build tmux.1 in the right format. tmux.1: tmux.1.in if test x@MANFORMAT@ = xmdoc; then \ - cp tmux.1.in tmux.1; \ + sed -e "s|@SYSCONFDIR@|$(sysconfdir)|g" tmux.1.in >tmux.1; \ else \ - $(AWK) -fmdoc2man.awk tmux.1; \ + sed -e "s|@SYSCONFDIR@|$(sysconfdir)|g" tmux.1.in| \ + $(AWK) -fmdoc2man.awk >tmux.1; \ fi # Update SF web site. diff --git a/configure.ac b/configure.ac index 80cf1266..590b9db0 100644 --- a/configure.ac +++ b/configure.ac @@ -18,6 +18,9 @@ AC_PROG_CC AM_PROG_CC_C_O AC_PROG_INSTALL +# Default tmux.conf goes in /etc not ${prefix}/etc. +test "$sysconfdir" = '${prefix}/etc' && sysconfdir=/etc + # Check for various headers. Alternatives included from compat.h. AC_CHECK_HEADERS( [ \ diff --git a/server.c b/server.c index 4bfa9185..bd28d517 100644 --- a/server.c +++ b/server.c @@ -170,13 +170,13 @@ server_start(int lockfd, char *lockfile) cfg_references = 1; ARRAY_INIT(&cfg_causes); - if (access(SYSTEM_CFG, R_OK) == 0) { - if (load_cfg(SYSTEM_CFG, cfg_cmd_q, &cause) == -1) { - xasprintf(&cause, "%s: %s", SYSTEM_CFG, cause); + if (access(TMUX_CONF, R_OK) == 0) { + if (load_cfg(TMUX_CONF, cfg_cmd_q, &cause) == -1) { + xasprintf(&cause, "%s: %s", TMUX_CONF, cause); ARRAY_ADD(&cfg_causes, cause); } } else if (errno != ENOENT) { - xasprintf(&cause, "%s: %s", SYSTEM_CFG, strerror(errno)); + xasprintf(&cause, "%s: %s", TMUX_CONF, strerror(errno)); ARRAY_ADD(&cfg_causes, cause); } if (cfg_file != NULL) { diff --git a/tmux.1.in b/tmux.1.in index 98bf9574..7f783b86 100644 --- a/tmux.1.in +++ b/tmux.1.in @@ -122,7 +122,7 @@ Specify an alternative configuration file. By default, .Nm loads the system configuration file from -.Pa /etc/tmux.conf , +.Pa @SYSCONFDIR@/tmux.conf , if present, then looks for a user configuration file at .Pa ~/.tmux.conf . .Pp @@ -3705,12 +3705,12 @@ was renamed to .Ar name . .El .Sh FILES -.Bl -tag -width "/etc/tmux.confXXX" -compact +.Bl -tag -width "@SYSCONFDIR@/tmux.confXXX" -compact .It Pa ~/.tmux.conf Default .Nm configuration file. -.It Pa /etc/tmux.conf +.It Pa @SYSCONFDIR@/tmux.conf System-wide configuration file. .El .Sh EXAMPLES diff --git a/tmux.c b/tmux.c index 2916bbb5..606c574f 100644 --- a/tmux.c +++ b/tmux.c @@ -363,7 +363,7 @@ main(int argc, char **argv) if (pw != NULL) home = pw->pw_dir; } - xasprintf(&cfg_file, "%s/%s", home, DEFAULT_CFG); + xasprintf(&cfg_file, "%s/.tmux.conf", home); if (access(cfg_file, R_OK) != 0 && errno == ENOENT) { free(cfg_file); cfg_file = NULL; diff --git a/tmux.h b/tmux.h index f0b9edf0..fc5561b5 100644 --- a/tmux.h +++ b/tmux.h @@ -39,10 +39,6 @@ extern char *__progname; extern char **environ; -/* Default configuration files. */ -#define DEFAULT_CFG ".tmux.conf" -#define SYSTEM_CFG "/etc/tmux.conf" - /* Default prompt history length. */ #define PROMPT_HISTORY 100 -- cgit From e323101edede281b65e3c7141d79afdb2501a8ea Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 24 Apr 2013 10:01:32 +0000 Subject: Rename global configuration define. --- server.c | 8 ++++---- tmux.c | 2 +- tmux.h | 5 ++--- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/server.c b/server.c index a07fa1fd..ffc25db0 100644 --- a/server.c +++ b/server.c @@ -169,13 +169,13 @@ server_start(int lockfd, char *lockfile) cfg_references = 1; ARRAY_INIT(&cfg_causes); - if (access(SYSTEM_CFG, R_OK) == 0) { - if (load_cfg(SYSTEM_CFG, cfg_cmd_q, &cause) == -1) { - xasprintf(&cause, "%s: %s", SYSTEM_CFG, cause); + if (access(TMUX_CONF, R_OK) == 0) { + if (load_cfg(TMUX_CONF, cfg_cmd_q, &cause) == -1) { + xasprintf(&cause, "%s: %s", TMUX_CONF, cause); ARRAY_ADD(&cfg_causes, cause); } } else if (errno != ENOENT) { - xasprintf(&cause, "%s: %s", SYSTEM_CFG, strerror(errno)); + xasprintf(&cause, "%s: %s", TMUX_CONF, strerror(errno)); ARRAY_ADD(&cfg_causes, cause); } if (cfg_file != NULL) { diff --git a/tmux.c b/tmux.c index e9b28d7e..b229967d 100644 --- a/tmux.c +++ b/tmux.c @@ -357,7 +357,7 @@ main(int argc, char **argv) if (pw != NULL) home = pw->pw_dir; } - xasprintf(&cfg_file, "%s/%s", home, DEFAULT_CFG); + xasprintf(&cfg_file, "%s/.tmux.conf", home); if (access(cfg_file, R_OK) != 0 && errno == ENOENT) { free(cfg_file); cfg_file = NULL; diff --git a/tmux.h b/tmux.h index 8fb06223..7404b27f 100644 --- a/tmux.h +++ b/tmux.h @@ -43,9 +43,8 @@ extern char *__progname; extern char **environ; -/* Default configuration files. */ -#define DEFAULT_CFG ".tmux.conf" -#define SYSTEM_CFG "/etc/tmux.conf" +/* Default global configuration file. */ +#define TMUX_CONF "/etc/tmux.conf" /* Default prompt history length. */ #define PROMPT_HISTORY 100 -- cgit From 2555ac58ccc9b5e9c188dcb3a3a4cce6aa4821d1 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 24 Apr 2013 10:15:47 +0000 Subject: .Op Fl b not .Fl b for run-shell synopsis, from Ben Boeckel. --- tmux.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tmux.1 b/tmux.1 index b38b43bb..9b874f7b 100644 --- a/tmux.1 +++ b/tmux.1 @@ -3536,7 +3536,7 @@ Lock each client individually by running the command specified by the .Ic lock-command option. .It Xo Ic run-shell -.Fl b +.Op Fl b .Op Fl t Ar target-pane .Ar shell-command .Xc -- cgit From fce095665c62eb38826f42ae55a0fbe998f18be0 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Sun, 28 Apr 2013 15:37:02 +0100 Subject: Use $(srcdir) for generating tmux.1, reported by fasta_ on IRC. --- Makefile.am | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Makefile.am b/Makefile.am index 726582a5..3eb3190f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -240,10 +240,11 @@ endif # Build tmux.1 in the right format. tmux.1: tmux.1.in if test x@MANFORMAT@ = xmdoc; then \ - sed -e "s|@SYSCONFDIR@|$(sysconfdir)|g" tmux.1.in >tmux.1; \ + sed -e "s|@SYSCONFDIR@|$(sysconfdir)|g" $(srcdir)/tmux.1.in \ + >$(srcdir)/tmux.1; \ else \ - sed -e "s|@SYSCONFDIR@|$(sysconfdir)|g" tmux.1.in| \ - $(AWK) -fmdoc2man.awk >tmux.1; \ + sed -e "s|@SYSCONFDIR@|$(sysconfdir)|g" $(srcdir)/tmux.1.in| \ + $(AWK) -fmdoc2man.awk >$(srcdir)/tmux.1; \ fi # Update SF web site. -- cgit From 66f4c60a8477e0cf9eb059e7687ca524f135e442 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Tue, 7 May 2013 11:00:16 +0000 Subject: Don't limit width and height to 222 in standard mouse mode. --- input-keys.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/input-keys.c b/input-keys.c index d7e8513d..2de48e97 100644 --- a/input-keys.c +++ b/input-keys.c @@ -227,7 +227,7 @@ input_mouse(struct window_pane *wp, struct session *s, struct mouse_event *m) len += utf8_split2(m->x + 33, &buf[len]); len += utf8_split2(m->y + 33, &buf[len]); } else { - if (m->xb > 223 || m->x >= 222 || m->y > 222) + if (m->xb > 223) return; len = xsnprintf(buf, sizeof buf, "\033[M"); buf[len++] = m->xb + 32; -- cgit From 5b1cf02f2ea224922661495af32d46b024e28eef Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 15 May 2013 16:27:30 +0100 Subject: Rename tmux.1.in back to tmux.1 and generate tmux.1.{mdoc,man} instead. --- Makefile.am | 16 +- tmux.1 | 3808 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ tmux.1.in | 3808 ----------------------------------------------------------- 3 files changed, 3816 insertions(+), 3816 deletions(-) create mode 100644 tmux.1 delete mode 100644 tmux.1.in diff --git a/Makefile.am b/Makefile.am index c131940a..c746b3d9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,14 +2,12 @@ # Obvious program stuff. bin_PROGRAMS = tmux -nodist_man1_MANS = tmux.1 -CLEANFILES = tmux.1 +CLEANFILES = tmux.1.mdoc tmux.1.man # Distribution tarball options. EXTRA_DIST = \ CHANGES FAQ README TODO examples compat \ - array.h compat.h tmux.h osdep-*.c mdoc2man.awk \ - tmux.1.in + array.h compat.h tmux.h osdep-*.c mdoc2man.awk tmux.1 dist-hook: grep "^#found_debug=" configure find $(distdir) -name .svn -type d|xargs rm -Rf @@ -237,13 +235,15 @@ if NO_CFMAKERAW nodist_tmux_SOURCES += compat/cfmakeraw.c endif -# Build tmux.1 in the right format. -tmux.1: tmux.1.in +# Install tmux.1 in the right format. +install-exec-hook: if test x@MANFORMAT@ = xmdoc; then \ - cp tmux.1.in tmux.1; \ + cp tmux.1 tmux.1.mdoc; \ else \ - $(AWK) -fmdoc2man.awk tmux.1; \ + $(AWK) -fmdoc2man.awk tmux.1.man; \ fi + $(MKDIR_P) $(DESTDIR)$(mandir)/man1 + $(INSTALL_DATA) tmux.1.@MANFORMAT@ $(DESTDIR)$(mandir)/man1/tmux.1 # Update SF web site. upload-index.html: update-index.html diff --git a/tmux.1 b/tmux.1 new file mode 100644 index 00000000..98bf9574 --- /dev/null +++ b/tmux.1 @@ -0,0 +1,3808 @@ +.\" $Id$ +.\" +.\" Copyright (c) 2007 Nicholas Marriott +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER +.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING +.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: March 25 2013 $ +.Dt TMUX 1 +.Os +.Sh NAME +.Nm tmux +.Nd terminal multiplexer +.Sh SYNOPSIS +.Nm tmux +.Bk -words +.Op Fl 28lCquvV +.Op Fl c Ar shell-command +.Op Fl f Ar file +.Op Fl L Ar socket-name +.Op Fl S Ar socket-path +.Op Ar command Op Ar flags +.Ek +.Sh DESCRIPTION +.Nm +is a terminal multiplexer: +it enables a number of terminals to be created, accessed, and +controlled from a single screen. +.Nm +may be detached from a screen +and continue running in the background, +then later reattached. +.Pp +When +.Nm +is started it creates a new +.Em session +with a single +.Em window +and displays it on screen. +A status line at the bottom of the screen +shows information on the current session +and is used to enter interactive commands. +.Pp +A session is a single collection of +.Em pseudo terminals +under the management of +.Nm . +Each session has one or more +windows linked to it. +A window occupies the entire screen +and may be split into rectangular panes, +each of which is a separate pseudo terminal +(the +.Xr pty 4 +manual page documents the technical details of pseudo terminals). +Any number of +.Nm +instances may connect to the same session, +and any number of windows may be present in the same session. +Once all sessions are killed, +.Nm +exits. +.Pp +Each session is persistent and will survive accidental disconnection +(such as +.Xr ssh 1 +connection timeout) or intentional detaching (with the +.Ql C-b d +key strokes). +.Nm +may be reattached using: +.Pp +.Dl $ tmux attach +.Pp +In +.Nm , +a session is displayed on screen by a +.Em client +and all sessions are managed by a single +.Em server . +The server and each client are separate processes which communicate through a +socket in +.Pa /tmp . +.Pp +The options are as follows: +.Bl -tag -width "XXXXXXXXXXXX" +.It Fl 2 +Force +.Nm +to assume the terminal supports 256 colours. +.It Fl C +Start in control mode. +Given twice +.Xo ( Fl CC ) Xc +disables echo. +.It Fl c Ar shell-command +Execute +.Ar shell-command +using the default shell. +If necessary, the +.Nm +server will be started to retrieve the +.Ic default-shell +option. +This option is for compatibility with +.Xr sh 1 +when +.Nm +is used as a login shell. +.It Fl f Ar file +Specify an alternative configuration file. +By default, +.Nm +loads the system configuration file from +.Pa /etc/tmux.conf , +if present, then looks for a user configuration file at +.Pa ~/.tmux.conf . +.Pp +The configuration file is a set of +.Nm +commands which are executed in sequence when the server is first started. +.Nm +loads configuration files once when the server process has started. +The +.Ic source-file +command may be used to load a file later. +.Pp +.Nm +shows any error messages from commands in configuration files in the first +session created, and continues to process the rest of the configuration file. +.It Fl L Ar socket-name +.Nm +stores the server socket in a directory under +.Ev TMUX_TMPDIR , +.Ev TMPDIR +if it is unset, or +.Pa /tmp +if both are unset. +The default socket is named +.Em default . +This option allows a different socket name to be specified, allowing several +independent +.Nm +servers to be run. +Unlike +.Fl S +a full path is not necessary: the sockets are all created in the same +directory. +.Pp +If the socket is accidentally removed, the +.Dv SIGUSR1 +signal may be sent to the +.Nm +server process to recreate it. +.It Fl l +Behave as a login shell. +This flag currently has no effect and is for compatibility with other shells +when using tmux as a login shell. +.It Fl q +Set the +.Ic quiet +server option to prevent the server sending various informational messages. +.It Fl S Ar socket-path +Specify a full alternative path to the server socket. +If +.Fl S +is specified, the default socket directory is not used and any +.Fl L +flag is ignored. +.It Fl u +.Nm +attempts to guess if the terminal is likely to support UTF-8 by checking the +first of the +.Ev LC_ALL , +.Ev LC_CTYPE +and +.Ev LANG +environment variables to be set for the string "UTF-8". +This is not always correct: the +.Fl u +flag explicitly informs +.Nm +that UTF-8 is supported. +.Pp +If the server is started from a client passed +.Fl u +or where UTF-8 is detected, the +.Ic utf8 +and +.Ic status-utf8 +options are enabled in the global window and session options respectively. +.It Fl v +Request verbose logging. +This option may be specified multiple times for increasing verbosity. +Log messages will be saved into +.Pa tmux-client-PID.log +and +.Pa tmux-server-PID.log +files in the current directory, where +.Em PID +is the PID of the server or client process. +.It Fl V +Report the +.Nm +version. +.It Ar command Op Ar flags +This specifies one of a set of commands used to control +.Nm , +as described in the following sections. +If no commands are specified, the +.Ic new-session +command is assumed. +.El +.Sh KEY BINDINGS +.Nm +may be controlled from an attached client by using a key combination of a +prefix key, +.Ql C-b +(Ctrl-b) by default, followed by a command key. +.Pp +The default command key bindings are: +.Pp +.Bl -tag -width "XXXXXXXXXX" -offset indent -compact +.It C-b +Send the prefix key (C-b) through to the application. +.It C-o +Rotate the panes in the current window forwards. +.It C-z +Suspend the +.Nm +client. +.It ! +Break the current pane out of the window. +.It \&" +Split the current pane into two, top and bottom. +.It # +List all paste buffers. +.It $ +Rename the current session. +.It % +Split the current pane into two, left and right. +.It & +Kill the current window. +.It ' +Prompt for a window index to select. +.It , +Rename the current window. +.It - +Delete the most recently copied buffer of text. +.It . +Prompt for an index to move the current window. +.It 0 to 9 +Select windows 0 to 9. +.It : +Enter the +.Nm +command prompt. +.It ; +Move to the previously active pane. +.It = +Choose which buffer to paste interactively from a list. +.It \&? +List all key bindings. +.It D +Choose a client to detach. +.It \&[ +Enter copy mode to copy text or view the history. +.It \&] +Paste the most recently copied buffer of text. +.It c +Create a new window. +.It d +Detach the current client. +.It f +Prompt to search for text in open windows. +.It i +Display some information about the current window. +.It l +Move to the previously selected window. +.It n +Change to the next window. +.It o +Select the next pane in the current window. +.It p +Change to the previous window. +.It q +Briefly display pane indexes. +.It r +Force redraw of the attached client. +.It s +Select a new session for the attached client interactively. +.It L +Switch the attached client back to the last session. +.It t +Show the time. +.It w +Choose the current window interactively. +.It x +Kill the current pane. +.It { +Swap the current pane with the previous pane. +.It } +Swap the current pane with the next pane. +.It ~ +Show previous messages from +.Nm , +if any. +.It Page Up +Enter copy mode and scroll one page up. +.It Up, Down +.It Left, Right +Change to the pane above, below, to the left, or to the right of the current +pane. +.It M-1 to M-5 +Arrange panes in one of the five preset layouts: even-horizontal, +even-vertical, main-horizontal, main-vertical, or tiled. +.It M-n +Move to the next window with a bell or activity marker. +.It M-o +Rotate the panes in the current window backwards. +.It M-p +Move to the previous window with a bell or activity marker. +.It C-Up, C-Down +.It C-Left, C-Right +Resize the current pane in steps of one cell. +.It M-Up, M-Down +.It M-Left, M-Right +Resize the current pane in steps of five cells. +.El +.Pp +Key bindings may be changed with the +.Ic bind-key +and +.Ic unbind-key +commands. +.Sh COMMANDS +This section contains a list of the commands supported by +.Nm . +Most commands accept the optional +.Fl t +argument with one of +.Ar target-client , +.Ar target-session +.Ar target-window , +or +.Ar target-pane . +These specify the client, session, window or pane which a command should affect. +.Ar target-client +is the name of the +.Xr pty 4 +file to which the client is connected, for example either of +.Pa /dev/ttyp1 +or +.Pa ttyp1 +for the client attached to +.Pa /dev/ttyp1 . +If no client is specified, the current client is chosen, if possible, or an +error is reported. +Clients may be listed with the +.Ic list-clients +command. +.Pp +.Ar target-session +is the session id prefixed with a $, the name of a session (as listed by the +.Ic list-sessions +command), or the name of a client with the same syntax as +.Ar target-client , +in which case the session attached to the client is used. +When looking for the session name, +.Nm +initially searches for an exact match; if none is found, the session names +are checked for any for which +.Ar target-session +is a prefix or for which it matches as an +.Xr fnmatch 3 +pattern. +If a single match is found, it is used as the target session; multiple matches +produce an error. +If a session is omitted, the current session is used if available; if no +current session is available, the most recently used is chosen. +.Pp +.Ar target-window +specifies a window in the form +.Em session Ns \&: Ns Em window . +.Em session +follows the same rules as for +.Ar target-session , +and +.Em window +is looked for in order: as a window index, for example mysession:1; +as a window ID, such as @1; +as an exact window name, such as mysession:mywindow; then as an +.Xr fnmatch 3 +pattern or the start of a window name, such as mysession:mywin* or +mysession:mywin. +An empty window name specifies the next unused index if appropriate (for +example the +.Ic new-window +and +.Ic link-window +commands) +otherwise the current window in +.Em session +is chosen. +The special character +.Ql \&! +uses the last (previously current) window, +.Ql ^ +selects the highest numbered window, +.Ql $ +selects the lowest numbered window, and +.Ql + +and +.Ql - +select the next window or the previous window by number. +When the argument does not contain a colon, +.Nm +first attempts to parse it as window; if that fails, an attempt is made to +match a session. +.Pp +.Ar target-pane +takes a similar form to +.Ar target-window +but with the optional addition of a period followed by a pane index, for +example: mysession:mywindow.1. +If the pane index is omitted, the currently active pane in the specified +window is used. +If neither a colon nor period appears, +.Nm +first attempts to use the argument as a pane index; if that fails, it is looked +up as for +.Ar target-window . +A +.Ql + +or +.Ql - +indicate the next or previous pane index, respectively. +One of the strings +.Em top , +.Em bottom , +.Em left , +.Em right , +.Em top-left , +.Em top-right , +.Em bottom-left +or +.Em bottom-right +may be used instead of a pane index. +.Pp +The special characters +.Ql + +and +.Ql - +may be followed by an offset, for example: +.Bd -literal -offset indent +select-window -t:+2 +.Ed +.Pp +When dealing with a session that doesn't contain sequential window indexes, +they will be correctly skipped. +.Pp +.Nm +also gives each pane created in a server an identifier consisting of a +.Ql % +and a number, starting from zero. +A pane's identifier is unique for the life of the +.Nm +server and is passed to the child process of the pane in the +.Ev TMUX_PANE +environment variable. +It may be used alone to target a pane or the window containing it. +.Pp +.Ar shell-command +arguments are +.Xr sh 1 +commands. +These must be passed as a single item, which typically means quoting them, for +example: +.Bd -literal -offset indent +new-window 'vi /etc/passwd' +.Ed +.Pp +.Ar command +.Op Ar arguments +refers to a +.Nm +command, passed with the command and arguments separately, for example: +.Bd -literal -offset indent +bind-key F1 set-window-option force-width 81 +.Ed +.Pp +Or if using +.Xr sh 1 : +.Bd -literal -offset indent +$ tmux bind-key F1 set-window-option force-width 81 +.Ed +.Pp +Multiple commands may be specified together as part of a +.Em command sequence . +Each command should be separated by spaces and a semicolon; +commands are executed sequentially from left to right and +lines ending with a backslash continue on to the next line, +except when escaped by another backslash. +A literal semicolon may be included by escaping it with a backslash (for +example, when specifying a command sequence to +.Ic bind-key ) . +.Pp +Example +.Nm +commands include: +.Bd -literal -offset indent +refresh-client -t/dev/ttyp2 + +rename-session -tfirst newname + +set-window-option -t:0 monitor-activity on + +new-window ; split-window -d + +bind-key R source-file ~/.tmux.conf \e; \e + display-message "source-file done" +.Ed +.Pp +Or from +.Xr sh 1 : +.Bd -literal -offset indent +$ tmux kill-window -t :1 + +$ tmux new-window \e; split-window -d + +$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach +.Ed +.Sh CLIENTS AND SESSIONS +The +.Nm +server manages clients, sessions, windows and panes. +Clients are attached to sessions to interact with them, either +when they are created with the +.Ic new-session +command, or later with the +.Ic attach-session +command. +Each session has one or more windows +.Em linked +into it. +Windows may be linked to multiple sessions and are made up of one or +more panes, +each of which contains a pseudo terminal. +Commands for creating, linking and otherwise manipulating windows +are covered +in the +.Sx WINDOWS AND PANES +section. +.Pp +The following commands are available to manage clients and sessions: +.Bl -tag -width Ds +.It Xo Ic attach-session +.Op Fl dr +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic attach ) +If run from outside +.Nm , +create a new client in the current terminal and attach it to +.Ar target-session . +If used from inside, switch the current client. +If +.Fl d +is specified, any other clients attached to the session are detached. +.Fl r +signifies the client is read-only (only keys bound to the +.Ic detach-client +or +.Ic switch-client +commands have any effect) +.Pp +If no server is started, +.Ic attach-session +will attempt to start it; this will fail unless sessions are created in the +configuration file. +.Pp +The +.Ar target-session +rules for +.Ic attach-session +are slightly adjusted: if +.Nm +needs to select the most recently used session, it will prefer the most +recently used +.Em unattached +session. +.It Xo Ic detach-client +.Op Fl P +.Op Fl a +.Op Fl s Ar target-session +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic detach ) +Detach the current client if bound to a key, the client specified with +.Fl t , +or all clients currently attached to the session specified by +.Fl s . +The +.Fl a +option kills all but the client given with +.Fl t . +If +.Fl P +is given, send SIGHUP to the parent process of the client, typically causing it +to exit. +.It Ic has-session Op Fl t Ar target-session +.D1 (alias: Ic has ) +Report an error and exit with 1 if the specified session does not exist. +If it does exist, exit with 0. +.It Ic kill-server +Kill the +.Nm +server and clients and destroy all sessions. +.It Ic kill-session +.Op Fl a +.Op Fl t Ar target-session +Destroy the given session, closing any windows linked to it and no other +sessions, and detaching all clients attached to it. +If +.Fl a +is given, all sessions but the specified one is killed. +.It Xo Ic list-clients +.Op Fl F Ar format +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic lsc ) +List all clients attached to the server. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +If +.Ar target-session +is specified, list only clients connected to that session. +.It Ic list-commands +.D1 (alias: Ic lscm ) +List the syntax of all commands supported by +.Nm . +.It Ic list-sessions Op Fl F Ar format +.D1 (alias: Ic ls ) +List all sessions managed by the server. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Ic lock-client Op Fl t Ar target-client +.D1 (alias: Ic lockc ) +Lock +.Ar target-client , +see the +.Ic lock-server +command. +.It Ic lock-session Op Fl t Ar target-session +.D1 (alias: Ic locks ) +Lock all clients attached to +.Ar target-session . +.It Xo Ic new-session +.Op Fl AdDP +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl s Ar session-name +.Op Fl t Ar target-session +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar shell-command +.Xc +.D1 (alias: Ic new ) +Create a new session with name +.Ar session-name . +.Pp +The new session is attached to the current terminal unless +.Fl d +is given. +.Ar window-name +and +.Ar shell-command +are the name of and shell command to execute in the initial window. +If +.Fl d +is used, +.Fl x +and +.Fl y +specify the size of the initial window (80 by 24 if not given). +.Pp +If run from a terminal, any +.Xr termios 4 +special characters are saved and used for new windows in the new session. +.Pp +The +.Fl A +flag makes +.Ic new-session +behave like +.Ic attach-session +if +.Ar session-name +already exists; in the case, +.Fl D +behaves like +.Fl d +to +.Ic attach-session . +.Pp +If +.Fl t +is given, the new session is +.Em grouped +with +.Ar target-session . +This means they share the same set of windows - all windows from +.Ar target-session +are linked to the new session and any subsequent new windows or windows being +closed are applied to both sessions. +The current and previous window and any session options remain independent and +either session may be killed without affecting the other. +Giving +.Fl n +or +.Ar shell-command +are invalid if +.Fl t +is used. +.Pp +The +.Fl P +option prints information about the new session after it has been created. +By default, it uses the format +.Ql #{session_name}: +but a different format may be specified with +.Fl F . +.It Xo Ic refresh-client +.Op Fl S +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic refresh ) +Refresh the current client if bound to a key, or a single client if one is given +with +.Fl t . +If +.Fl S +is specified, only update the client's status bar. +.It Xo Ic rename-session +.Op Fl t Ar target-session +.Ar new-name +.Xc +.D1 (alias: Ic rename ) +Rename the session to +.Ar new-name . +.It Xo Ic show-messages +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic showmsgs ) +Any messages displayed on the status line are saved in a per-client message +log, up to a maximum of the limit set by the +.Ar message-limit +session option for the session attached to that client. +This command displays the log for +.Ar target-client . +.It Ic source-file Ar path +.D1 (alias: Ic source ) +Execute commands from +.Ar path . +.It Ic start-server +.D1 (alias: Ic start ) +Start the +.Nm +server, if not already running, without creating any sessions. +.It Xo Ic suspend-client +.Op Fl t Ar target-client +.Xc +.D1 (alias: Ic suspendc ) +Suspend a client by sending +.Dv SIGTSTP +(tty stop). +.It Xo Ic switch-client +.Op Fl lnpr +.Op Fl c Ar target-client +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic switchc ) +Switch the current session for client +.Ar target-client +to +.Ar target-session . +If +.Fl l , +.Fl n +or +.Fl p +is used, the client is moved to the last, next or previous session +respectively. +.Fl r +toggles whether a client is read-only (see the +.Ic attach-session +command). +.El +.Sh WINDOWS AND PANES +A +.Nm +window may be in one of several modes. +The default permits direct access to the terminal attached to the window. +The other is copy mode, which permits a section of a window or its +history to be copied to a +.Em paste buffer +for later insertion into another window. +This mode is entered with the +.Ic copy-mode +command, bound to +.Ql \&[ +by default. +It is also entered when a command that produces output, such as +.Ic list-keys , +is executed from a key binding. +.Pp +The keys available depend on whether emacs or vi mode is selected +(see the +.Ic mode-keys +option). +The following keys are supported as appropriate for the mode: +.Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent +.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" +.It Li "Back to indentation" Ta "^" Ta "M-m" +.It Li "Bottom of history" Ta "G" Ta "M-<" +.It Li "Clear selection" Ta "Escape" Ta "C-g" +.It Li "Copy selection" Ta "Enter" Ta "M-w" +.It Li "Cursor down" Ta "j" Ta "Down" +.It Li "Cursor left" Ta "h" Ta "Left" +.It Li "Cursor right" Ta "l" Ta "Right" +.It Li "Cursor to bottom line" Ta "L" Ta "" +.It Li "Cursor to middle line" Ta "M" Ta "M-r" +.It Li "Cursor to top line" Ta "H" Ta "M-R" +.It Li "Cursor up" Ta "k" Ta "Up" +.It Li "Delete entire line" Ta "d" Ta "C-u" +.It Li "Delete/Copy to end of line" Ta "D" Ta "C-k" +.It Li "End of line" Ta "$" Ta "C-e" +.It Li "Go to line" Ta ":" Ta "g" +.It Li "Half page down" Ta "C-d" Ta "M-Down" +.It Li "Half page up" Ta "C-u" Ta "M-Up" +.It Li "Jump forward" Ta "f" Ta "f" +.It Li "Jump to forward" Ta "t" Ta "" +.It Li "Jump backward" Ta "F" Ta "F" +.It Li "Jump to backward" Ta "T" Ta "" +.It Li "Jump again" Ta ";" Ta ";" +.It Li "Jump again in reverse" Ta "," Ta "," +.It Li "Next page" Ta "C-f" Ta "Page down" +.It Li "Next space" Ta "W" Ta "" +.It Li "Next space, end of word" Ta "E" Ta "" +.It Li "Next word" Ta "w" Ta "" +.It Li "Next word end" Ta "e" Ta "M-f" +.It Li "Paste buffer" Ta "p" Ta "C-y" +.It Li "Previous page" Ta "C-b" Ta "Page up" +.It Li "Previous word" Ta "b" Ta "M-b" +.It Li "Previous space" Ta "B" Ta "" +.It Li "Quit mode" Ta "q" Ta "Escape" +.It Li "Rectangle toggle" Ta "v" Ta "R" +.It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down" +.It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up" +.It Li "Search again" Ta "n" Ta "n" +.It Li "Search again in reverse" Ta "N" Ta "N" +.It Li "Search backward" Ta "?" Ta "C-r" +.It Li "Search forward" Ta "/" Ta "C-s" +.It Li "Start of line" Ta "0" Ta "C-a" +.It Li "Start selection" Ta "Space" Ta "C-Space" +.It Li "Top of history" Ta "g" Ta "M->" +.It Li "Transpose characters" Ta "" Ta "C-t" +.El +.Pp +The next and previous word keys use space and the +.Ql - , +.Ql _ +and +.Ql @ +characters as word delimiters by default, but this can be adjusted by +setting the +.Em word-separators +session option. +Next word moves to the start of the next word, next word end to the end of the +next word and previous word to the start of the previous word. +The three next and previous space keys work similarly but use a space alone as +the word separator. +.Pp +The jump commands enable quick movement within a line. +For instance, typing +.Ql f +followed by +.Ql / +will move the cursor to the next +.Ql / +character on the current line. +A +.Ql \&; +will then jump to the next occurrence. +.Pp +Commands in copy mode may be prefaced by an optional repeat count. +With vi key bindings, a prefix is entered using the number keys; with +emacs, the Alt (meta) key and a number begins prefix entry. +For example, to move the cursor forward by ten words, use +.Ql M-1 0 M-f +in emacs mode, and +.Ql 10w +in vi. +.Pp +When copying the selection, the repeat count indicates the buffer index to +replace, if used. +.Pp +Mode key bindings are defined in a set of named tables: +.Em vi-edit +and +.Em emacs-edit +for keys used when line editing at the command prompt; +.Em vi-choice +and +.Em emacs-choice +for keys used when choosing from lists (such as produced by the +.Ic choose-window +command); and +.Em vi-copy +and +.Em emacs-copy +used in copy mode. +The tables may be viewed with the +.Ic list-keys +command and keys modified or removed with +.Ic bind-key +and +.Ic unbind-key . +One command accepts an argument, +.Ic copy-pipe , +which copies the selection and pipes it to a command. +For example the following will bind +.Ql C-q +to copy the selection into +.Pa /tmp +as well as the paste buffer: +.Bd -literal -offset indent +bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" +.Ed +.Pp +The paste buffer key pastes the first line from the top paste buffer on the +stack. +.Pp +The synopsis for the +.Ic copy-mode +command is: +.Bl -tag -width Ds +.It Xo Ic copy-mode +.Op Fl u +.Op Fl t Ar target-pane +.Xc +Enter copy mode. +The +.Fl u +option scrolls one page up. +.El +.Pp +Each window displayed by +.Nm +may be split into one or more +.Em panes ; +each pane takes up a certain area of the display and is a separate terminal. +A window may be split into panes using the +.Ic split-window +command. +Windows may be split horizontally (with the +.Fl h +flag) or vertically. +Panes may be resized with the +.Ic resize-pane +command (bound to +.Ql C-up , +.Ql C-down +.Ql C-left +and +.Ql C-right +by default), the current pane may be changed with the +.Ic select-pane +command and the +.Ic rotate-window +and +.Ic swap-pane +commands may be used to swap panes without changing their position. +Panes are numbered beginning from zero in the order they are created. +.Pp +A number of preset +.Em layouts +are available. +These may be selected with the +.Ic select-layout +command or cycled with +.Ic next-layout +(bound to +.Ql Space +by default); once a layout is chosen, panes within it may be moved and resized +as normal. +.Pp +The following layouts are supported: +.Bl -tag -width Ds +.It Ic even-horizontal +Panes are spread out evenly from left to right across the window. +.It Ic even-vertical +Panes are spread evenly from top to bottom. +.It Ic main-horizontal +A large (main) pane is shown at the top of the window and the remaining panes +are spread from left to right in the leftover space at the bottom. +Use the +.Em main-pane-height +window option to specify the height of the top pane. +.It Ic main-vertical +Similar to +.Ic main-horizontal +but the large pane is placed on the left and the others spread from top to +bottom along the right. +See the +.Em main-pane-width +window option. +.It Ic tiled +Panes are spread out as evenly as possible over the window in both rows and +columns. +.El +.Pp +In addition, +.Ic select-layout +may be used to apply a previously used layout - the +.Ic list-windows +command displays the layout of each window in a form suitable for use with +.Ic select-layout . +For example: +.Bd -literal -offset indent +$ tmux list-windows +0: ksh [159x48] + layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} +$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} +.Ed +.Pp +.Nm +automatically adjusts the size of the layout for the current window size. +Note that a layout cannot be applied to a window with more panes than that +from which the layout was originally defined. +.Pp +Commands related to windows and panes are as follows: +.Bl -tag -width Ds +.It Xo Ic break-pane +.Op Fl dP +.Op Fl F Ar format +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic breakp ) +Break +.Ar target-pane +off from its containing window to make it the only pane in a new window. +If +.Fl d +is given, the new window does not become the current window. +The +.Fl P +option prints information about the new window after it has been created. +By default, it uses the format +.Ql #{session_name}:#{window_index} +but a different format may be specified with +.Fl F . +.It Xo Ic capture-pane +.Op Fl aepPq +.Op Fl b Ar buffer-index +.Op Fl E Ar end-line +.Op Fl S Ar start-line +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic capturep ) +Capture the contents of a pane. +If +.Fl p +is given, the output goes to stdout, otherwise to the buffer specified with +.Fl b +or a new buffer if omitted. +If +.Fl a +is given, the alternate screen is used, and the history is not accessible. +If no alternate screen exists, an error will be returned unless +.Fl q +is given. +If +.Fl e +is given, the output includes escape sequences for text and background +attributes. +.Fl C +also escapes non-printable characters as octal \exxx. +.Fl J +joins wrapped lines and preserves trailing spaces at each line's end. +.Fl P +captures only any output that the pane has received that is the beginning of an +as-yet incomplete escape sequence. +.Pp +.Fl S +and +.Fl E +specify the starting and ending line numbers, zero is the first line of the +visible pane and negative numbers are lines in the history. +The default is to capture only the visible contents of the pane. +.It Xo +.Ic choose-client +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into client choice mode, allowing a client to be selected +interactively from a list. +After a client is chosen, +.Ql %% +is replaced by the client +.Xr pty 4 +path in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "detach-client -t '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo +.Ic choose-list +.Op Fl l Ar items +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into list choice mode, allowing +.Ar items +to be selected. +.Ar items +can be a comma-separated list to display more than one item. +If an item has spaces, that entry must be quoted. +After an item is chosen, +.Ql %% +is replaced by the chosen item in the +.Ar template +and the result is executed as a command. +If +.Ar template +is not given, "run-shell '%%'" is used. +.Ar items +also accepts format specifiers. +For the meaning of this see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo +.Ic choose-session +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into session choice mode, where a session may be selected +interactively from a list. +When one is chosen, +.Ql %% +is replaced by the session name in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "switch-client -t '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo +.Ic choose-tree +.Op Fl suw +.Op Fl b Ar session-template +.Op Fl c Ar window-template +.Op Fl S Ar format +.Op Fl W Ar format +.Op Fl t Ar target-window +.Xc +Put a window into tree choice mode, where either sessions or windows may be +selected interactively from a list. +By default, windows belonging to a session are indented to show their +relationship to a session. +.Pp +Note that the +.Ic choose-window +and +.Ic choose-session +commands are wrappers around +.Ic choose-tree . +.Pp +If +.Fl s +is given, will show sessions. +If +.Fl w +is given, will show windows. +.Pp +By default, the tree is collapsed and sessions must be expanded to windows +with the right arrow key. +The +.Fl u +option will start with all sessions expanded instead. +.Pp +If +.Fl b +is given, will override the default session command. +Note that +.Ql %% +can be used and will be replaced with the session name. +The default option if not specified is "switch-client -t '%%'". +If +.Fl c +is given, will override the default window command. +Like +.Fl b , +.Ql %% +can be used and will be replaced with the session name and window index. +When a window is chosen from the list, the session command is run before the +window command. +.Pp +If +.Fl S +is given will display the specified format instead of the default session +format. +If +.Fl W +is given will display the specified format instead of the default window +format. +For the meaning of the +.Fl s +and +.Fl w +options, see the +.Sx FORMATS +section. +.Pp +This command works only if at least one client is attached. +.It Xo +.Ic choose-window +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into window choice mode, where a window may be chosen +interactively from a list. +After a window is selected, +.Ql %% +is replaced by the session name and window index in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "select-window -t '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Ic display-panes Op Fl t Ar target-client +.D1 (alias: Ic displayp) +Display a visible indicator of each pane shown by +.Ar target-client . +See the +.Ic display-panes-time , +.Ic display-panes-colour , +and +.Ic display-panes-active-colour +session options. +While the indicator is on screen, a pane may be selected with the +.Ql 0 +to +.Ql 9 +keys. +.It Xo Ic find-window +.Op Fl CNT +.Op Fl F Ar format +.Op Fl t Ar target-window +.Ar match-string +.Xc +.D1 (alias: Ic findw ) +Search for the +.Xr fnmatch 3 +pattern +.Ar match-string +in window names, titles, and visible content (but not history). +The flags control matching behavior: +.Fl C +matches only visible window contents, +.Fl N +matches only the window name and +.Fl T +matches only the window title. +The default is +.Fl CNT . +If only one window is matched, it'll be automatically selected, +otherwise a choice list is shown. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Xo Ic join-pane +.Op Fl bdhv +.Oo Fl l +.Ar size | +.Fl p Ar percentage Oc +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 (alias: Ic joinp ) +Like +.Ic split-window , +but instead of splitting +.Ar dst-pane +and creating a new pane, split it and move +.Ar src-pane +into the space. +This can be used to reverse +.Ic break-pane . +The +.Fl b +option causes +.Ar src-pane +to be joined to left of or above +.Ar dst-pane . +.It Xo Ic kill-pane +.Op Fl a +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic killp ) +Destroy the given pane. +If no panes remain in the containing window, it is also destroyed. +The +.Fl a +option kills all but the pane given with +.Fl t . +.It Xo Ic kill-window +.Op Fl a +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic killw ) +Kill the current window or the window at +.Ar target-window , +removing it from any sessions to which it is linked. +The +.Fl a +option kills all but the window given with +.Fl t . +.It Ic last-pane Op Fl t Ar target-window +.D1 (alias: Ic lastp ) +Select the last (previously selected) pane. +.It Ic last-window Op Fl t Ar target-session +.D1 (alias: Ic last ) +Select the last (previously selected) window. +If no +.Ar target-session +is specified, select the last window of the current session. +.It Xo Ic link-window +.Op Fl dk +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 (alias: Ic linkw ) +Link the window at +.Ar src-window +to the specified +.Ar dst-window . +If +.Ar dst-window +is specified and no such window exists, the +.Ar src-window +is linked there. +If +.Fl k +is given and +.Ar dst-window +exists, it is killed, otherwise an error is generated. +If +.Fl d +is given, the newly linked window is not selected. +.It Xo Ic list-panes +.Op Fl as +.Op Fl F Ar format +.Op Fl t Ar target +.Xc +.D1 (alias: Ic lsp ) +If +.Fl a +is given, +.Ar target +is ignored and all panes on the server are listed. +If +.Fl s +is given, +.Ar target +is a session (or the current session). +If neither is given, +.Ar target +is a window (or the current window). +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Xo Ic list-windows +.Op Fl a +.Op Fl F Ar format +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic lsw ) +If +.Fl a +is given, list all windows on the server. +Otherwise, list windows in the current session or in +.Ar target-session . +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Xo Ic move-pane +.Op Fl bdhv +.Oo Fl l +.Ar size | +.Fl p Ar percentage Oc +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 (alias: Ic movep ) +Like +.Ic join-pane , +but +.Ar src-pane +and +.Ar dst-pane +may belong to the same window. +.It Xo Ic move-window +.Op Fl rdk +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 (alias: Ic movew ) +This is similar to +.Ic link-window , +except the window at +.Ar src-window +is moved to +.Ar dst-window . +With +.Fl r , +all windows in the session are renumbered in sequential order, respecting +the +.Ic base-index +option. +.It Xo Ic new-window +.Op Fl adkP +.Op Fl c Ar start-directory +.Op Fl F Ar format +.Op Fl n Ar window-name +.Op Fl t Ar target-window +.Op Ar shell-command +.Xc +.D1 (alias: Ic neww ) +Create a new window. +With +.Fl a , +the new window is inserted at the next index up from the specified +.Ar target-window , +moving windows up if necessary, +otherwise +.Ar target-window +is the new window location. +.Pp +If +.Fl d +is given, the session does not make the new window the current window. +.Ar target-window +represents the window to be created; if the target already exists an error is +shown, unless the +.Fl k +flag is used, in which case it is destroyed. +.Ar shell-command +is the command to execute. +If +.Ar shell-command +is not specified, the value of the +.Ic default-command +option is used. +.Fl c +specifies the working directory in which the new window is created. +It may have an absolute path or one of the following values (or a subdirectory): +.Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent +.It Li "Empty string" Ta "Current pane's directory" +.It Li "~" Ta "User's home directory" +.It Li "-" Ta "Where session was started" +.It Li "." Ta "Where server was started" +.El +.Pp +When the shell command completes, the window closes. +See the +.Ic remain-on-exit +option to change this behaviour. +.Pp +The +.Ev TERM +environment variable must be set to +.Dq screen +for all programs running +.Em inside +.Nm . +New windows will automatically have +.Dq TERM=screen +added to their environment, but care must be taken not to reset this in shell +start-up files. +.Pp +The +.Fl P +option prints information about the new window after it has been created. +By default, it uses the format +.Ql #{session_name}:#{window_index} +but a different format may be specified with +.Fl F . +.It Ic next-layout Op Fl t Ar target-window +.D1 (alias: Ic nextl ) +Move a window to the next layout and rearrange the panes to fit. +.It Xo Ic next-window +.Op Fl a +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic next ) +Move to the next window in the session. +If +.Fl a +is used, move to the next window with an alert. +.It Xo Ic pipe-pane +.Op Fl o +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 (alias: Ic pipep ) +Pipe any output sent by the program in +.Ar target-pane +to a shell command. +A pane may only be piped to one command at a time, any existing pipe is +closed before +.Ar shell-command +is executed. +The +.Ar shell-command +string may contain the special character sequences supported by the +.Ic status-left +option. +If no +.Ar shell-command +is given, the current pipe (if any) is closed. +.Pp +The +.Fl o +option only opens a new pipe if no previous pipe exists, allowing a pipe to +be toggled with a single key, for example: +.Bd -literal -offset indent +bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' +.Ed +.It Xo Ic previous-layout +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic prevl ) +Move to the previous layout in the session. +.It Xo Ic previous-window +.Op Fl a +.Op Fl t Ar target-session +.Xc +.D1 (alias: Ic prev ) +Move to the previous window in the session. +With +.Fl a , +move to the previous window with an alert. +.It Xo Ic rename-window +.Op Fl t Ar target-window +.Ar new-name +.Xc +.D1 (alias: Ic renamew ) +Rename the current window, or the window at +.Ar target-window +if specified, to +.Ar new-name . +.It Xo Ic resize-pane +.Op Fl DLRUZ +.Op Fl t Ar target-pane +.Op Fl x Ar width +.Op Fl y Ar height +.Op Ar adjustment +.Xc +.D1 (alias: Ic resizep ) +Resize a pane, up, down, left or right by +.Ar adjustment +with +.Fl U , +.Fl D , +.Fl L +or +.Fl R , +or +to an absolute size +with +.Fl x +or +.Fl y . +The +.Ar adjustment +is given in lines or cells (the default is 1). +.Pp +With +.Fl Z , +the active pane is toggled between zoomed (occupying the whole of the window) +and unzoomed (its normal position in the layout). +.It Xo Ic respawn-pane +.Op Fl k +.Op Fl t Ar target-pane +.Op Ar shell-command +.Xc +.D1 (alias: Ic respawnp ) +Reactivate a pane in which the command has exited (see the +.Ic remain-on-exit +window option). +If +.Ar shell-command +is not given, the command used when the pane was created is executed. +The pane must be already inactive, unless +.Fl k +is given, in which case any existing command is killed. +.It Xo Ic respawn-window +.Op Fl k +.Op Fl t Ar target-window +.Op Ar shell-command +.Xc +.D1 (alias: Ic respawnw ) +Reactivate a window in which the command has exited (see the +.Ic remain-on-exit +window option). +If +.Ar shell-command +is not given, the command used when the window was created is executed. +The window must be already inactive, unless +.Fl k +is given, in which case any existing command is killed. +.It Xo Ic rotate-window +.Op Fl DU +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic rotatew ) +Rotate the positions of the panes within a window, either upward (numerically +lower) with +.Fl U +or downward (numerically higher). +.It Xo Ic select-layout +.Op Fl np +.Op Fl t Ar target-window +.Op Ar layout-name +.Xc +.D1 (alias: Ic selectl ) +Choose a specific layout for a window. +If +.Ar layout-name +is not given, the last preset layout used (if any) is reapplied. +.Fl n +and +.Fl p +are equivalent to the +.Ic next-layout +and +.Ic previous-layout +commands. +.It Xo Ic select-pane +.Op Fl lDLRU +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic selectp ) +Make pane +.Ar target-pane +the active pane in window +.Ar target-window . +If one of +.Fl D , +.Fl L , +.Fl R , +or +.Fl U +is used, respectively the pane below, to the left, to the right, or above the +target pane is used. +.Fl l +is the same as using the +.Ic last-pane +command. +.It Xo Ic select-window +.Op Fl lnpT +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic selectw ) +Select the window at +.Ar target-window . +.Fl l , +.Fl n +and +.Fl p +are equivalent to the +.Ic last-window , +.Ic next-window +and +.Ic previous-window +commands. +If +.Fl T +is given and the selected window is already the current window, +the command behaves like +.Ic last-window . +.It Xo Ic split-window +.Op Fl dhvP +.Op Fl c Ar start-directory +.Oo Fl l +.Ar size | +.Fl p Ar percentage Oc +.Op Fl t Ar target-pane +.Op Ar shell-command +.Op Fl F Ar format +.Xc +.D1 (alias: Ic splitw ) +Create a new pane by splitting +.Ar target-pane : +.Fl h +does a horizontal split and +.Fl v +a vertical split; if neither is specified, +.Fl v +is assumed. +The +.Fl l +and +.Fl p +options specify the size of the new pane in lines (for vertical split) or in +cells (for horizontal split), or as a percentage, respectively. +All other options have the same meaning as for the +.Ic new-window +command. +.It Xo Ic swap-pane +.Op Fl dDU +.Op Fl s Ar src-pane +.Op Fl t Ar dst-pane +.Xc +.D1 (alias: Ic swapp ) +Swap two panes. +If +.Fl U +is used and no source pane is specified with +.Fl s , +.Ar dst-pane +is swapped with the previous pane (before it numerically); +.Fl D +swaps with the next pane (after it numerically). +.Fl d +instructs +.Nm +not to change the active pane. +.It Xo Ic swap-window +.Op Fl d +.Op Fl s Ar src-window +.Op Fl t Ar dst-window +.Xc +.D1 (alias: Ic swapw ) +This is similar to +.Ic link-window , +except the source and destination windows are swapped. +It is an error if no window exists at +.Ar src-window . +.It Xo Ic unlink-window +.Op Fl k +.Op Fl t Ar target-window +.Xc +.D1 (alias: Ic unlinkw ) +Unlink +.Ar target-window . +Unless +.Fl k +is given, a window may be unlinked only if it is linked to multiple sessions - +windows may not be linked to no sessions; +if +.Fl k +is specified and the window is linked to only one session, it is unlinked and +destroyed. +.El +.Sh KEY BINDINGS +.Nm +allows a command to be bound to most keys, with or without a prefix key. +When specifying keys, most represent themselves (for example +.Ql A +to +.Ql Z ) . +Ctrl keys may be prefixed with +.Ql C- +or +.Ql ^ , +and Alt (meta) with +.Ql M- . +In addition, the following special key names are accepted: +.Em Up , +.Em Down , +.Em Left , +.Em Right , +.Em BSpace , +.Em BTab , +.Em DC +(Delete), +.Em End , +.Em Enter , +.Em Escape , +.Em F1 +to +.Em F20 , +.Em Home , +.Em IC +(Insert), +.Em NPage/PageDown/PgDn , +.Em PPage/PageUp/PgUp , +.Em Space , +and +.Em Tab . +Note that to bind the +.Ql \&" +or +.Ql ' +keys, quotation marks are necessary, for example: +.Bd -literal -offset indent +bind-key '"' split-window +bind-key "'" new-window +.Ed +.Pp +Commands related to key bindings are as follows: +.Bl -tag -width Ds +.It Xo Ic bind-key +.Op Fl cnr +.Op Fl t Ar key-table +.Ar key Ar command Op Ar arguments +.Xc +.D1 (alias: Ic bind ) +Bind key +.Ar key +to +.Ar command . +By default (without +.Fl t ) +the primary key bindings are modified (those normally activated with the prefix +key); in this case, if +.Fl n +is specified, it is not necessary to use the prefix key, +.Ar command +is bound to +.Ar key +alone. +The +.Fl r +flag indicates this key may repeat, see the +.Ic repeat-time +option. +.Pp +If +.Fl t +is present, +.Ar key +is bound in +.Ar key-table : +the binding for command mode with +.Fl c +or for normal mode without. +To view the default bindings and possible commands, see the +.Ic list-keys +command. +.It Ic list-keys Op Fl t Ar key-table +.D1 (alias: Ic lsk ) +List all key bindings. +Without +.Fl t +the primary key bindings - those executed when preceded by the prefix key - +are printed. +.Pp +With +.Fl t , +the key bindings in +.Ar key-table +are listed; this may be one of: +.Em vi-edit , +.Em emacs-edit , +.Em vi-choice , +.Em emacs-choice , +.Em vi-copy +or +.Em emacs-copy . +.It Xo Ic send-keys +.Op Fl lR +.Op Fl t Ar target-pane +.Ar key Ar ... +.Xc +.D1 (alias: Ic send ) +Send a key or keys to a window. +Each argument +.Ar key +is the name of the key (such as +.Ql C-a +or +.Ql npage +) to send; if the string is not recognised as a key, it is sent as a series of +characters. +The +.Fl l +flag disables key name lookup and sends the keys literally. +All arguments are sent sequentially from first to last. +The +.Fl R +flag causes the terminal state to be reset. +.It Xo Ic send-prefix +.Op Fl 2 +.Op Fl t Ar target-pane +.Xc +Send the prefix key, or with +.Fl 2 +the secondary prefix key, to a window as if it was pressed. +.It Xo Ic unbind-key +.Op Fl acn +.Op Fl t Ar key-table +.Ar key +.Xc +.D1 (alias: Ic unbind ) +Unbind the command bound to +.Ar key . +Without +.Fl t +the primary key bindings are modified; in this case, if +.Fl n +is specified, the command bound to +.Ar key +without a prefix (if any) is removed. +If +.Fl a +is present, all key bindings are removed. +.Pp +If +.Fl t +is present, +.Ar key +in +.Ar key-table +is unbound: the binding for command mode with +.Fl c +or for normal mode without. +.El +.Sh OPTIONS +The appearance and behaviour of +.Nm +may be modified by changing the value of various options. +There are three types of option: +.Em server options , +.Em session options +and +.Em window options . +.Pp +The +.Nm +server has a set of global options which do not apply to any particular +window or session. +These are altered with the +.Ic set-option +.Fl s +command, or displayed with the +.Ic show-options +.Fl s +command. +.Pp +In addition, each individual session may have a set of session options, and +there is a separate set of global session options. +Sessions which do not have a particular option configured inherit the value +from the global session options. +Session options are set or unset with the +.Ic set-option +command and may be listed with the +.Ic show-options +command. +The available server and session options are listed under the +.Ic set-option +command. +.Pp +Similarly, a set of window options is attached to each window, and there is +a set of global window options from which any unset options are inherited. +Window options are altered with the +.Ic set-window-option +command and can be listed with the +.Ic show-window-options +command. +All window options are documented with the +.Ic set-window-option +command. +.Pp +.Nm +also supports user options which are prefixed with a +.Ql \&@ . +User options may have any name, so long as they are prefixed with +.Ql \&@ , +and be set to any string. +For example +.Bd -literal -offset indent +$ tmux setw -q @foo "abc123" +$ tmux showw -v @foo +abc123 +.Ed +.Pp +Commands which set options are as follows: +.Bl -tag -width Ds +.It Xo Ic set-option +.Op Fl agoqsuw +.Op Fl t Ar target-session | Ar target-window +.Ar option Ar value +.Xc +.D1 (alias: Ic set ) +Set a window option with +.Fl w +(equivalent to the +.Ic set-window-option +command), +a server option with +.Fl s , +otherwise a session option. +.Pp +If +.Fl g +is specified, the global session or window option is set. +With +.Fl a , +and if the option expects a string, +.Ar value +is appended to the existing setting. +The +.Fl u +flag unsets an option, so a session inherits the option from the global +options. +It is not possible to unset a global option. +.Pp +The +.Fl o +flag prevents setting an option that is already set. +.Pp +The +.Fl q +flag suppresses the informational message (as if the +.Ic quiet +server option was set). +.Pp +Available window options are listed under +.Ic set-window-option . +.Pp +.Ar value +depends on the option and may be a number, a string, or a flag (on, off, or +omitted to toggle). +.Pp +Available server options are: +.Bl -tag -width Ds +.It Ic buffer-limit Ar number +Set the number of buffers; as new buffers are added to the top of the stack, +old ones are removed from the bottom if necessary to maintain this maximum +length. +.It Ic escape-time Ar time +Set the time in milliseconds for which +.Nm +waits after an escape is input to determine if it is part of a function or meta +key sequences. +The default is 500 milliseconds. +.It Xo Ic exit-unattached +.Op Ic on | off +.Xc +If enabled, the server will exit when there are no attached clients. +.It Xo Ic quiet +.Op Ic on | off +.Xc +Enable or disable the display of various informational messages (see also the +.Fl q +command line flag). +.It Xo Ic set-clipboard +.Op Ic on | off +.Xc +Attempt to set the terminal clipboard content using the +\ee]52;...\e007 +.Xr xterm 1 +escape sequences. +This option is on by default if there is an +.Em \&Ms +entry in the +.Xr terminfo 5 +description for the client terminal. +Note that this feature needs to be enabled in +.Xr xterm 1 +by setting the resource: +.Bd -literal -offset indent +disallowedWindowOps: 20,21,SetXprop +.Ed +.Pp +Or changing this property from the +.Xr xterm 1 +interactive menu when required. +.El +.Pp +Available session options are: +.Bl -tag -width Ds +.It Ic assume-paste-time Ar milliseconds +If keys are entered faster than one in +.Ar milliseconds , +they are assumed to have been pasted rather than typed and +.Nm +key bindings are not processed. +The default is one millisecond and zero disables. +.It Ic base-index Ar index +Set the base index from which an unused index should be searched when a new +window is created. +The default is zero. +.It Xo Ic bell-action +.Op Ic any | none | current +.Xc +Set action on window bell. +.Ic any +means a bell in any window linked to a session causes a bell in the current +window of that session, +.Ic none +means all bells are ignored and +.Ic current +means only bells in windows other than the current window are ignored. +.It Xo Ic bell-on-alert +.Op Ic on | off +.Xc +If on, ring the terminal bell when an alert +occurs. +.It Ic default-command Ar shell-command +Set the command used for new windows (if not specified when the window is +created) to +.Ar shell-command , +which may be any +.Xr sh 1 +command. +The default is an empty string, which instructs +.Nm +to create a login shell using the value of the +.Ic default-shell +option. +.It Ic default-path Ar path +Set the default working directory for new panes. +If empty (the default), the working directory is determined from the process +running in the active pane, from the command line environment or from the +working directory where the session was created. +Otherwise the same options are available as for the +.Fl c +flag to +.Ic new-window . +.It Ic default-shell Ar path +Specify the default shell. +This is used as the login shell for new windows when the +.Ic default-command +option is set to empty, and must be the full path of the executable. +When started +.Nm +tries to set a default value from the first suitable of the +.Ev SHELL +environment variable, the shell returned by +.Xr getpwuid 3 , +or +.Pa /bin/sh . +This option should be configured when +.Nm +is used as a login shell. +.It Ic default-terminal Ar terminal +Set the default terminal for new windows created in this session - the +default value of the +.Ev TERM +environment variable. +For +.Nm +to work correctly, this +.Em must +be set to +.Ql screen +or a derivative of it. +.It Xo Ic destroy-unattached +.Op Ic on | off +.Xc +If enabled and the session is no longer attached to any clients, it is +destroyed. +.It Xo Ic detach-on-destroy +.Op Ic on | off +.Xc +If on (the default), the client is detached when the session it is attached to +is destroyed. +If off, the client is switched to the most recently active of the remaining +sessions. +.It Ic display-panes-active-colour Ar colour +Set the colour used by the +.Ic display-panes +command to show the indicator for the active pane. +.It Ic display-panes-colour Ar colour +Set the colour used by the +.Ic display-panes +command to show the indicators for inactive panes. +.It Ic display-panes-time Ar time +Set the time in milliseconds for which the indicators shown by the +.Ic display-panes +command appear. +.It Ic display-time Ar time +Set the amount of time for which status line messages and other on-screen +indicators are displayed. +.Ar time +is in milliseconds. +.It Ic history-limit Ar lines +Set the maximum number of lines held in window history. +This setting applies only to new windows - existing window histories are not +resized and retain the limit at the point they were created. +.It Ic lock-after-time Ar number +Lock the session (like the +.Ic lock-session +command) after +.Ar number +seconds of inactivity, or the entire server (all sessions) if the +.Ic lock-server +option is set. +The default is not to lock (set to 0). +.It Ic lock-command Ar shell-command +Command to run when locking each client. +The default is to run +.Xr lock 1 +with +.Fl np . +.It Xo Ic lock-server +.Op Ic on | off +.Xc +If this option is +.Ic on +(the default), +instead of each session locking individually as each has been +idle for +.Ic lock-after-time , +the entire server will lock after +.Em all +sessions would have locked. +This has no effect as a session option; it must be set as a global option. +.It Ic message-attr Ar attributes +Set status line message attributes, where +.Ar attributes +is either +.Ic none +or a comma-delimited list of one or more of: +.Ic bright +(or +.Ic bold ) , +.Ic dim , +.Ic underscore , +.Ic blink , +.Ic reverse , +.Ic hidden , +or +.Ic italics . +.It Ic message-bg Ar colour +Set status line message background colour, where +.Ar colour +is one of: +.Ic black , +.Ic red , +.Ic green , +.Ic yellow , +.Ic blue , +.Ic magenta , +.Ic cyan , +.Ic white , +aixterm bright variants (if supported: +.Ic brightred , +.Ic brightgreen , +and so on), +.Ic colour0 +to +.Ic colour255 +from the 256-colour set, +.Ic default , +or a hexadecimal RGB string such as +.Ql #ffffff , +which chooses the closest match from the default 256-colour set. +.It Ic message-command-attr Ar attributes +Set status line message attributes when in command mode. +.It Ic message-command-bg Ar colour +Set status line message background colour when in command mode. +.It Ic message-command-fg Ar colour +Set status line message foreground colour when in command mode. +.It Ic message-fg Ar colour +Set status line message foreground colour. +.It Ic message-limit Ar number +Set the number of error or information messages to save in the message log for +each client. +The default is 20. +.It Xo Ic mouse-resize-pane +.Op Ic on | off +.Xc +If on, +.Nm +captures the mouse and allows panes to be resized by dragging on their borders. +.It Xo Ic mouse-select-pane +.Op Ic on | off +.Xc +If on, +.Nm +captures the mouse and when a window is split into multiple panes the mouse may +be used to select the current pane. +The mouse click is also passed through to the application as normal. +.It Xo Ic mouse-select-window +.Op Ic on | off +.Xc +If on, clicking the mouse on a window name in the status line will select that +window. +.It Xo Ic mouse-utf8 +.Op Ic on | off +.Xc +If enabled, request mouse input as UTF-8 on UTF-8 terminals. +.It Ic pane-active-border-bg Ar colour +.It Ic pane-active-border-fg Ar colour +Set the pane border colour for the currently active pane. +.It Ic pane-border-bg Ar colour +.It Ic pane-border-fg Ar colour +Set the pane border colour for panes aside from the active pane. +.It Ic prefix Ar key +Set the key accepted as a prefix key. +.It Ic prefix2 Ar key +Set a secondary key accepted as a prefix key. +.It Xo Ic renumber-windows +.Op Ic on | off +.Xc +If on, when a window is closed in a session, automatically renumber the other +windows in numerical order. +This respects the +.Ic base-index +option if it has been set. +If off, do not renumber the windows. +.It Ic repeat-time Ar time +Allow multiple commands to be entered without pressing the prefix-key again +in the specified +.Ar time +milliseconds (the default is 500). +Whether a key repeats may be set when it is bound using the +.Fl r +flag to +.Ic bind-key . +Repeat is enabled for the default keys bound to the +.Ic resize-pane +command. +.It Xo Ic set-remain-on-exit +.Op Ic on | off +.Xc +Set the +.Ic remain-on-exit +window option for any windows first created in this session. +When this option is true, windows in which the running program has +exited do not close, instead remaining open but inactivate. +Use the +.Ic respawn-window +command to reactivate such a window, or the +.Ic kill-window +command to destroy it. +.It Xo Ic set-titles +.Op Ic on | off +.Xc +Attempt to set the client terminal title using the +.Em tsl +and +.Em fsl +.Xr terminfo 5 +entries if they exist. +.Nm +automatically sets these to the \ee]2;...\e007 sequence if +the terminal appears to be an xterm. +This option is off by default. +Note that elinks +will only attempt to set the window title if the STY environment +variable is set. +.It Ic set-titles-string Ar string +String used to set the window title if +.Ic set-titles +is on. +Character sequences are replaced as for the +.Ic status-left +option. +.It Xo Ic status +.Op Ic on | off +.Xc +Show or hide the status line. +.It Ic status-attr Ar attributes +Set status line attributes. +.It Ic status-bg Ar colour +Set status line background colour. +.It Ic status-fg Ar colour +Set status line foreground colour. +.It Ic status-interval Ar interval +Update the status bar every +.Ar interval +seconds. +By default, updates will occur every 15 seconds. +A setting of zero disables redrawing at interval. +.It Xo Ic status-justify +.Op Ic left | centre | right +.Xc +Set the position of the window list component of the status line: left, centre +or right justified. +.It Xo Ic status-keys +.Op Ic vi | emacs +.Xc +Use vi or emacs-style +key bindings in the status line, for example at the command prompt. +The default is emacs, unless the +.Ev VISUAL +or +.Ev EDITOR +environment variables are set and contain the string +.Ql vi . +.It Ic status-left Ar string +Display +.Ar string +to the left of the status bar. +.Ar string +will be passed through +.Xr strftime 3 +before being used. +By default, the session name is shown. +.Ar string +may contain any of the following special character sequences: +.Bl -column "Character pair" "Replaced with" -offset indent +.It Sy "Character pair" Ta Sy "Replaced with" +.It Li "#(shell-command)" Ta "First line of the command's output" +.It Li "#[attributes]" Ta "Colour or attribute change" +.It Li "#H" Ta "Hostname of local host" +.It Li "#h" Ta "Hostname of local host without the domain name" +.It Li "#F" Ta "Current window flag" +.It Li "#I" Ta "Current window index" +.It Li "#D" Ta "Current pane unique identifier" +.It Li "#P" Ta "Current pane index" +.It Li "#S" Ta "Session name" +.It Li "#T" Ta "Current pane title" +.It Li "#W" Ta "Current window name" +.It Li "##" Ta "A literal" Ql # +.El +.Pp +The #(shell-command) form executes +.Ql shell-command +and inserts the first line of its output. +Note that shell commands are only executed once at the interval specified by +the +.Ic status-interval +option: if the status line is redrawn in the meantime, the previous result is +used. +Shell commands are executed with the +.Nm +global environment set (see the +.Sx ENVIRONMENT +section). +.Pp +For details on how the names and titles can be set see the +.Sx "NAMES AND TITLES" +section. +.Pp +#[attributes] allows a comma-separated list of attributes to be specified, +these may be +.Ql fg=colour +to set the foreground colour, +.Ql bg=colour +to set the background colour, the name of one of the attributes (listed under +the +.Ic message-attr +option) to turn an attribute on, or an attribute prefixed with +.Ql no +to turn one off, for example +.Ic nobright . +Examples are: +.Bd -literal -offset indent +#(sysctl vm.loadavg) +#[fg=yellow,bold]#(apm -l)%%#[default] [#S] +.Ed +.Pp +Where appropriate, special character sequences may be prefixed with a number to +specify the maximum length, for example +.Ql #24T . +.Pp +By default, UTF-8 in +.Ar string +is not interpreted, to enable UTF-8, use the +.Ic status-utf8 +option. +.It Ic status-left-attr Ar attributes +Set the attribute of the left part of the status line. +.It Ic status-left-bg Ar colour +Set the background colour of the left part of the status line. +.It Ic status-left-fg Ar colour +Set the foreground colour of the left part of the status line. +.It Ic status-left-length Ar length +Set the maximum +.Ar length +of the left component of the status bar. +The default is 10. +.It Xo Ic status-position +.Op Ic top | bottom +.Xc +Set the position of the status line. +.It Ic status-right Ar string +Display +.Ar string +to the right of the status bar. +By default, the current window title in double quotes, the date and the time +are shown. +As with +.Ic status-left , +.Ar string +will be passed to +.Xr strftime 3 , +character pairs are replaced, and UTF-8 is dependent on the +.Ic status-utf8 +option. +.It Ic status-right-attr Ar attributes +Set the attribute of the right part of the status line. +.It Ic status-right-bg Ar colour +Set the background colour of the right part of the status line. +.It Ic status-right-fg Ar colour +Set the foreground colour of the right part of the status line. +.It Ic status-right-length Ar length +Set the maximum +.Ar length +of the right component of the status bar. +The default is 40. +.It Xo Ic status-utf8 +.Op Ic on | off +.Xc +Instruct +.Nm +to treat top-bit-set characters in the +.Ic status-left +and +.Ic status-right +strings as UTF-8; notably, this is important for wide characters. +This option defaults to off. +.It Ic terminal-overrides Ar string +Contains a list of entries which override terminal descriptions read using +.Xr terminfo 5 . +.Ar string +is a comma-separated list of items each a colon-separated string made up of a +terminal type pattern (matched using +.Xr fnmatch 3 ) +and a set of +.Em name=value +entries. +.Pp +For example, to set the +.Ql clear +.Xr terminfo 5 +entry to +.Ql \ee[H\ee[2J +for all terminal types and the +.Ql dch1 +entry to +.Ql \ee[P +for the +.Ql rxvt +terminal type, the option could be set to the string: +.Bd -literal -offset indent +"*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P" +.Ed +.Pp +The terminal entry value is passed through +.Xr strunvis 3 +before interpretation. +The default value forcibly corrects the +.Ql colors +entry for terminals which support 88 or 256 colours: +.Bd -literal -offset indent +"*88col*:colors=88,*256col*:colors=256,xterm*:XT" +.Ed +.It Ic update-environment Ar variables +Set a space-separated string containing a list of environment variables to be +copied into the session environment when a new session is created or an +existing session is attached. +Any variables that do not exist in the source environment are set to be +removed from the session environment (as if +.Fl r +was given to the +.Ic set-environment +command). +The default is +"DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID +XAUTHORITY". +.It Xo Ic visual-activity +.Op Ic on | off +.Xc +If on, display a status line message when activity occurs in a window +for which the +.Ic monitor-activity +window option is enabled. +.It Xo Ic visual-bell +.Op Ic on | off +.Xc +If this option is on, a message is shown on a bell instead of it being passed +through to the terminal (which normally makes a sound). +Also see the +.Ic bell-action +option. +.It Xo Ic visual-content +.Op Ic on | off +.Xc +Like +.Ic visual-activity , +display a message when content is present in a window +for which the +.Ic monitor-content +window option is enabled. +.It Xo Ic visual-silence +.Op Ic on | off +.Xc +If +.Ic monitor-silence +is enabled, prints a message after the interval has expired on a given window. +.It Ic word-separators Ar string +Sets the session's conception of what characters are considered word +separators, for the purposes of the next and previous word commands in +copy mode. +The default is +.Ql \ -_@ . +.El +.It Xo Ic set-window-option +.Op Fl agoqu +.Op Fl t Ar target-window +.Ar option Ar value +.Xc +.D1 (alias: Ic setw ) +Set a window option. +The +.Fl a , +.Fl g , +.Fl o , +.Fl q +and +.Fl u +flags work similarly to the +.Ic set-option +command. +.Pp +Supported window options are: +.Pp +.Bl -tag -width Ds -compact +.It Xo Ic aggressive-resize +.Op Ic on | off +.Xc +Aggressively resize the chosen window. +This means that +.Nm +will resize the window to the size of the smallest session for which it is the +current window, rather than the smallest session to which it is attached. +The window may resize when the current window is changed on another sessions; +this option is good for full-screen programs which support +.Dv SIGWINCH +and poor for interactive programs such as shells. +.Pp +.It Xo Ic allow-rename +.Op Ic on | off +.Xc +Allow programs to change the window name using a terminal escape +sequence (\\033k...\\033\\\\). +The default is on. +.Pp +.It Xo Ic alternate-screen +.Op Ic on | off +.Xc +This option configures whether programs running inside +.Nm +may use the terminal alternate screen feature, which allows the +.Em smcup +and +.Em rmcup +.Xr terminfo 5 +capabilities. +The alternate screen feature preserves the contents of the window when an +interactive application starts and restores it on exit, so that any output +visible before the application starts reappears unchanged after it exits. +The default is on. +.Pp +.It Xo Ic automatic-rename +.Op Ic on | off +.Xc +Control automatic window renaming. +When this setting is enabled, +.Nm +will attempt - on supported platforms - to rename the window to reflect the +command currently running in it. +This flag is automatically disabled for an individual window when a name +is specified at creation with +.Ic new-window +or +.Ic new-session , +or later with +.Ic rename-window , +or with a terminal escape sequence. +It may be switched off globally with: +.Bd -literal -offset indent +set-window-option -g automatic-rename off +.Ed +.Pp +.It Ic c0-change-interval Ar interval +.It Ic c0-change-trigger Ar trigger +These two options configure a simple form of rate limiting for a pane. +If +.Nm +sees more than +.Ar trigger +C0 sequences that modify the screen (for example, carriage returns, linefeeds +or backspaces) in one millisecond, it will stop updating the pane immediately and +instead redraw it entirely every +.Ar interval +milliseconds. +This helps to prevent fast output (such as +.Xr yes 1 +overwhelming the terminal). +The default is a trigger of 250 and an interval of 100. +A trigger of zero disables the rate limiting. +.Pp +.It Ic clock-mode-colour Ar colour +Set clock colour. +.Pp +.It Xo Ic clock-mode-style +.Op Ic 12 | 24 +.Xc +Set clock hour format. +.Pp +.It Ic force-height Ar height +.It Ic force-width Ar width +Prevent +.Nm +from resizing a window to greater than +.Ar width +or +.Ar height . +A value of zero restores the default unlimited setting. +.Pp +.It Ic main-pane-height Ar height +.It Ic main-pane-width Ar width +Set the width or height of the main (left or top) pane in the +.Ic main-horizontal +or +.Ic main-vertical +layouts. +.Pp +.It Ic mode-attr Ar attributes +Set window modes attributes. +.Pp +.It Ic mode-bg Ar colour +Set window modes background colour. +.Pp +.It Ic mode-fg Ar colour +Set window modes foreground colour. +.Pp +.It Xo Ic mode-keys +.Op Ic vi | emacs +.Xc +Use vi or emacs-style key bindings in copy and choice modes. +As with the +.Ic status-keys +option, the default is emacs, unless +.Ev VISUAL +or +.Ev EDITOR +contains +.Ql vi . +.Pp +.It Xo Ic mode-mouse +.Op Ic on | off | copy-mode +.Xc +Mouse state in modes. +If on, the mouse may be used to enter copy mode and copy a selection by +dragging, to enter copy mode and scroll with the mouse wheel, or to select an +option in choice mode. +If set to +.Em copy-mode , +the mouse behaves as set to on, but cannot be used to enter copy +mode. +.Pp +.It Xo Ic monitor-activity +.Op Ic on | off +.Xc +Monitor for activity in the window. +Windows with activity are highlighted in the status line. +.Pp +.It Ic monitor-content Ar match-string +Monitor content in the window. +When +.Xr fnmatch 3 +pattern +.Ar match-string +appears in the window, it is highlighted in the status line. +.Pp +.It Xo Ic monitor-silence +.Op Ic interval +.Xc +Monitor for silence (no activity) in the window within +.Ic interval +seconds. +Windows that have been silent for the interval are highlighted in the +status line. +An interval of zero disables the monitoring. +.Pp +.It Ic other-pane-height Ar height +Set the height of the other panes (not the main pane) in the +.Ic main-horizontal +layout. +If this option is set to 0 (the default), it will have no effect. +If both the +.Ic main-pane-height +and +.Ic other-pane-height +options are set, the main pane will grow taller to make the other panes the +specified height, but will never shrink to do so. +.Pp +.It Ic other-pane-width Ar width +Like +.Ic other-pane-height , +but set the width of other panes in the +.Ic main-vertical +layout. +.Pp +.It Ic pane-base-index Ar index +Like +.Ic base-index , +but set the starting index for pane numbers. +.Pp +.It Xo Ic remain-on-exit +.Op Ic on | off +.Xc +A window with this flag set is not destroyed when the program running in it +exits. +The window may be reactivated with the +.Ic respawn-window +command. +.Pp +.It Xo Ic synchronize-panes +.Op Ic on | off +.Xc +Duplicate input to any pane to all other panes in the same window (only +for panes that are not in any special mode). +.Pp +.It Xo Ic utf8 +.Op Ic on | off +.Xc +Instructs +.Nm +to expect UTF-8 sequences to appear in this window. +.Pp +.It Ic window-status-bell-attr Ar attributes +Set status line attributes for windows which have a bell alert. +.Pp +.It Ic window-status-bell-bg Ar colour +Set status line background colour for windows with a bell alert. +.Pp +.It Ic window-status-bell-fg Ar colour +Set status line foreground colour for windows with a bell alert. +.Pp +.It Ic window-status-content-attr Ar attributes +Set status line attributes for windows which have a content alert. +.Pp +.It Ic window-status-content-bg Ar colour +Set status line background colour for windows with a content alert. +.Pp +.It Ic window-status-content-fg Ar colour +Set status line foreground colour for windows with a content alert. +.Pp +.It Ic window-status-activity-attr Ar attributes +Set status line attributes for windows which have an activity (or silence) alert. +.Pp +.It Ic window-status-activity-bg Ar colour +Set status line background colour for windows with an activity alert. +.Pp +.It Ic window-status-activity-fg Ar colour +Set status line foreground colour for windows with an activity alert. +.Pp +.It Ic window-status-attr Ar attributes +Set status line attributes for a single window. +.Pp +.It Ic window-status-bg Ar colour +Set status line background colour for a single window. +.Pp +.It Ic window-status-current-attr Ar attributes +Set status line attributes for the currently active window. +.Pp +.It Ic window-status-current-bg Ar colour +Set status line background colour for the currently active window. +.Pp +.It Ic window-status-current-fg Ar colour +Set status line foreground colour for the currently active window. +.Pp +.It Ic window-status-current-format Ar string +Like +.Ar window-status-format , +but is the format used when the window is the current window. +.Pp +.It Ic window-status-last-attr Ar attributes +Set status line attributes for the last active window. +.Pp +.It Ic window-status-last-bg Ar colour +Set status line background colour for the last active window. +.Pp +.It Ic window-status-last-fg Ar colour +Set status line foreground colour for the last active window. +.Pp +.It Ic window-status-fg Ar colour +Set status line foreground colour for a single window. +.Pp +.It Ic window-status-format Ar string +Set the format in which the window is displayed in the status line window list. +See the +.Ar status-left +option for details of special character sequences available. +The default is +.Ql #I:#W#F . +.Pp +.It Ic window-status-separator Ar string +Sets the separator drawn between windows in the status line. +The default is a single space character. +.Pp +.It Xo Ic xterm-keys +.Op Ic on | off +.Xc +If this option is set, +.Nm +will generate +.Xr xterm 1 -style +function key sequences; these have a number included to indicate modifiers such +as Shift, Alt or Ctrl. +The default is off. +.Pp +.It Xo Ic wrap-search +.Op Ic on | off +.Xc +If this option is set, searches will wrap around the end of the pane contents. +The default is on. +.El +.It Xo Ic show-options +.Op Fl gqsvw +.Op Fl t Ar target-session | Ar target-window +.Op Ar option +.Xc +.D1 (alias: Ic show ) +Show the window options (or a single window option if given) with +.Fl w +(equivalent to +.Ic show-window-options ) , +the server options with +.Fl s , +otherwise the session options for +.Ar target session . +Global session or window options are listed if +.Fl g +is used. +.Fl v +shows only the option value, not the name. +If +.Fl q +is set, no error will be returned if +.Ar option +is unset. +.It Xo Ic show-window-options +.Op Fl gv +.Op Fl t Ar target-window +.Op Ar option +.Xc +.D1 (alias: Ic showw ) +List the window options or a single option for +.Ar target-window , +or the global window options if +.Fl g +is used. +.Fl v +shows only the option value, not the name. +.El +.Sh FORMATS +Certain commands accept the +.Fl F +flag with a +.Ar format +argument. +This is a string which controls the output format of the command. +Special character sequences are replaced as documented under the +.Ic status-left +option and an additional long form is accepted. +Replacement variables are enclosed in +.Ql #{ +and +.Ql } , +for example +.Ql #{session_name} +is equivalent to +.Ql #S . +Conditionals are also accepted by prefixing with +.Ql \&? +and separating two alternatives with a comma; +if the specified variable exists and is not zero, the first alternative +is chosen, otherwise the second is used. +For example +.Ql #{?session_attached,attached,not attached} +will include the string +.Ql attached +if the session is attached and the string +.Ql not attached +if it is unattached. +.Pp +The following variables are available, where appropriate: +.Bl -column "session_created_string" "Replaced with" -offset indent +.It Sy "Variable name" Ta Sy "Replaced with" +.It Li "alternate_on" Ta "If pane is in alternate screen" +.It Li "alternate_saved_x" Ta "Saved cursor X in alternate screen" +.It Li "alternate_saved_y" Ta "Saved cursor Y in alternate screen" +.It Li "buffer_sample" Ta "First 50 characters from the specified buffer" +.It Li "buffer_size" Ta "Size of the specified buffer in bytes" +.It Li "client_activity" Ta "Integer time client last had activity" +.It Li "client_activity_string" Ta "String time client last had activity" +.It Li "client_created" Ta "Integer time client created" +.It Li "client_created_string" Ta "String time client created" +.It Li "client_cwd" Ta "Working directory of client" +.It Li "client_height" Ta "Height of client" +.It Li "client_last_session" Ta "Name of the client's last session" +.It Li "client_prefix" Ta "1 if prefix key has been pressed" +.It Li "client_readonly" Ta "1 if client is readonly" +.It Li "client_session" Ta "Name of the client's session" +.It Li "client_termname" Ta "Terminal name of client" +.It Li "client_tty" Ta "Pseudo terminal of client" +.It Li "client_utf8" Ta "1 if client supports utf8" +.It Li "client_width" Ta "Width of client" +.It Li "cursor_flag" Ta "Pane cursor flag" +.It Li "cursor_x" Ta "Cursor X position in pane" +.It Li "cursor_y" Ta "Cursor Y position in pane" +.It Li "history_bytes" Ta "Number of bytes in window history" +.It Li "history_limit" Ta "Maximum window history lines" +.It Li "history_size" Ta "Size of history in bytes" +.It Li "host" Ta "Hostname of local host" +.It Li "insert_flag" Ta "Pane insert flag" +.It Li "keypad_cursor_flag" Ta "Pane keypad cursor flag" +.It Li "keypad_flag" Ta "Pane keypad flag" +.It Li "line" Ta "Line number in the list" +.It Li "mouse_any_flag" Ta "Pane mouse any flag" +.It Li "mouse_button_flag" Ta "Pane mouse button flag" +.It Li "mouse_standard_flag" Ta "Pane mouse standard flag" +.It Li "mouse_utf8_flag" Ta "Pane mouse UTF-8 flag" +.It Li "pane_active" Ta "1 if active pane" +.It Li "pane_current_command" Ta "Current command if available" +.It Li "pane_current_path" Ta "Current path if available" +.It Li "pane_dead" Ta "1 if pane is dead" +.It Li "pane_height" Ta "Height of pane" +.It Li "pane_id" Ta "Unique pane ID" +.It Li "pane_in_mode" Ta "If pane is in a mode" +.It Li "pane_index" Ta "Index of pane" +.It Li "pane_pid" Ta "PID of first process in pane" +.It Li "pane_start_command" Ta "Command pane started with" +.It Li "pane_start_path" Ta "Path pane started with" +.It Li "pane_tabs" Ta "Pane tab positions" +.It Li "pane_title" Ta "Title of pane" +.It Li "pane_tty" Ta "Pseudo terminal of pane" +.It Li "pane_width" Ta "Width of pane" +.It Li "saved_cursor_x" Ta "Saved cursor X in pane" +.It Li "saved_cursor_y" Ta "Saved cursor Y in pane" +.It Li "scroll_region_lower" Ta "Bottom of scroll region in pane" +.It Li "scroll_region_upper" Ta "Top of scroll region in pane" +.It Li "session_attached" Ta "1 if session attached" +.It Li "session_created" Ta "Integer time session created" +.It Li "session_created_string" Ta "String time session created" +.It Li "session_group" Ta "Number of session group" +.It Li "session_grouped" Ta "1 if session in a group" +.It Li "session_height" Ta "Height of session" +.It Li "session_id" Ta "Unique session ID" +.It Li "session_name" Ta "Name of session" +.It Li "session_width" Ta "Width of session" +.It Li "session_windows" Ta "Number of windows in session" +.It Li "window_active" Ta "1 if window active" +.It Li "window_find_matches" Ta "Matched data from the find-window command if available" +.It Li "window_flags" Ta "Window flags" +.It Li "window_height" Ta "Height of window" +.It Li "window_id" Ta "Unique window ID" +.It Li "window_index" Ta "Index of window" +.It Li "window_layout" Ta "Window layout description" +.It Li "window_name" Ta "Name of window" +.It Li "window_panes" Ta "Number of panes in window" +.It Li "window_width" Ta "Width of window" +.It Li "wrap_flag" Ta "Pane wrap flag" +.El +.Sh NAMES AND TITLES +.Nm +distinguishes between names and titles. +Windows and sessions have names, which may be used to specify them in targets +and are displayed in the status line and various lists: the name is the +.Nm +identifier for a window or session. +Only panes have titles. +A pane's title is typically set by the program running inside the pane and +is not modified by +.Nm . +It is the same mechanism used to set for example the +.Xr xterm 1 +window title in an +.Xr X 7 +window manager. +Windows themselves do not have titles - a window's title is the title of its +active pane. +.Nm +itself may set the title of the terminal in which the client is running, see +the +.Ic set-titles +option. +.Pp +A session's name is set with the +.Ic new-session +and +.Ic rename-session +commands. +A window's name is set with one of: +.Bl -enum -width Ds +.It +A command argument (such as +.Fl n +for +.Ic new-window +or +.Ic new-session ) . +.It +An escape sequence: +.Bd -literal -offset indent +$ printf '\e033kWINDOW_NAME\e033\e\e' +.Ed +.It +Automatic renaming, which sets the name to the active command in the window's +active pane. +See the +.Ic automatic-rename +option. +.El +.Pp +When a pane is first created, its title is the hostname. +A pane's title can be set via the OSC title setting sequence, for example: +.Bd -literal -offset indent +$ printf '\e033]2;My Title\e033\e\e' +.Ed +.Sh ENVIRONMENT +When the server is started, +.Nm +copies the environment into the +.Em global environment ; +in addition, each session has a +.Em session environment . +When a window is created, the session and global environments are merged. +If a variable exists in both, the value from the session environment is used. +The result is the initial environment passed to the new process. +.Pp +The +.Ic update-environment +session option may be used to update the session environment from the client +when a new session is created or an old reattached. +.Nm +also initialises the +.Ev TMUX +variable with some internal information to allow commands to be executed +from inside, and the +.Ev TERM +variable with the correct terminal setting of +.Ql screen . +.Pp +Commands to alter and view the environment are: +.Bl -tag -width Ds +.It Xo Ic set-environment +.Op Fl gru +.Op Fl t Ar target-session +.Ar name Op Ar value +.Xc +.D1 (alias: Ic setenv ) +Set or unset an environment variable. +If +.Fl g +is used, the change is made in the global environment; otherwise, it is applied +to the session environment for +.Ar target-session . +The +.Fl u +flag unsets a variable. +.Fl r +indicates the variable is to be removed from the environment before starting a +new process. +.It Xo Ic show-environment +.Op Fl g +.Op Fl t Ar target-session +.Op Ar variable +.Xc +.D1 (alias: Ic showenv ) +Display the environment for +.Ar target-session +or the global environment with +.Fl g . +If +.Ar variable +is omitted, all variables are shown. +Variables removed from the environment are prefixed with +.Ql - . +.El +.Sh STATUS LINE +.Nm +includes an optional status line which is displayed in the bottom line of each +terminal. +By default, the status line is enabled (it may be disabled with the +.Ic status +session option) and contains, from left-to-right: the name of the current +session in square brackets; the window list; the title of the active pane +in double quotes; and the time and date. +.Pp +The status line is made of three parts: configurable left and right sections +(which may contain dynamic content such as the time or output from a shell +command, see the +.Ic status-left , +.Ic status-left-length , +.Ic status-right , +and +.Ic status-right-length +options below), and a central window list. +By default, the window list shows the index, name and (if any) flag of the +windows present in the current session in ascending numerical order. +It may be customised with the +.Ar window-status-format +and +.Ar window-status-current-format +options. +The flag is one of the following symbols appended to the window name: +.Bl -column "Symbol" "Meaning" -offset indent +.It Sy "Symbol" Ta Sy "Meaning" +.It Li "*" Ta "Denotes the current window." +.It Li "-" Ta "Marks the last window (previously selected)." +.It Li "#" Ta "Window is monitored and activity has been detected." +.It Li "!" Ta "A bell has occurred in the window." +.It Li "+" Ta "Window is monitored for content and it has appeared." +.It Li "~" Ta "The window has been silent for the monitor-silence interval." +.It Li "Z" Ta "The window's active pane is zoomed." +.El +.Pp +The # symbol relates to the +.Ic monitor-activity +and + to the +.Ic monitor-content +window options. +The window name is printed in inverted colours if an alert (bell, activity or +content) is present. +.Pp +The colour and attributes of the status line may be configured, the entire +status line using the +.Ic status-attr , +.Ic status-fg +and +.Ic status-bg +session options and individual windows using the +.Ic window-status-attr , +.Ic window-status-fg +and +.Ic window-status-bg +window options. +.Pp +The status line is automatically refreshed at interval if it has changed, the +interval may be controlled with the +.Ic status-interval +session option. +.Pp +Commands related to the status line are as follows: +.Bl -tag -width Ds +.It Xo Ic command-prompt +.Op Fl I Ar inputs +.Op Fl p Ar prompts +.Op Fl t Ar target-client +.Op Ar template +.Xc +Open the command prompt in a client. +This may be used from inside +.Nm +to execute commands interactively. +.Pp +If +.Ar template +is specified, it is used as the command. +If present, +.Fl I +is a comma-separated list of the initial text for each prompt. +If +.Fl p +is given, +.Ar prompts +is a comma-separated list of prompts which are displayed in order; otherwise +a single prompt is displayed, constructed from +.Ar template +if it is present, or +.Ql \&: +if not. +.Pp +Both +.Ar inputs +and +.Ar prompts +may contain the special character sequences supported by the +.Ic status-left +option. +.Pp +Before the command is executed, the first occurrence of the string +.Ql %% +and all occurrences of +.Ql %1 +are replaced by the response to the first prompt, the second +.Ql %% +and all +.Ql %2 +are replaced with the response to the second prompt, and so on for further +prompts. +Up to nine prompt responses may be replaced +.Po +.Ql %1 +to +.Ql %9 +.Pc . +.It Xo Ic confirm-before +.Op Fl p Ar prompt +.Op Fl t Ar target-client +.Ar command +.Xc +.D1 (alias: Ic confirm ) +Ask for confirmation before executing +.Ar command . +If +.Fl p +is given, +.Ar prompt +is the prompt to display; otherwise a prompt is constructed from +.Ar command . +It may contain the special character sequences supported by the +.Ic status-left +option. +.Pp +This command works only from inside +.Nm . +.It Xo Ic display-message +.Op Fl p +.Op Fl c Ar target-client +.Op Fl t Ar target-pane +.Op Ar message +.Xc +.D1 (alias: Ic display ) +Display a message. +If +.Fl p +is given, the output is printed to stdout, otherwise it is displayed in the +.Ar target-client +status line. +The format of +.Ar message +is described in the +.Sx FORMATS +section; information is taken from +.Ar target-pane +if +.Fl t +is given, otherwise the active pane for the session attached to +.Ar target-client . +.El +.Sh BUFFERS +.Nm +maintains a stack of +.Em paste buffers . +Up to the value of the +.Ic buffer-limit +option are kept; when a new buffer is added, the buffer at the bottom of the +stack is removed. +Buffers may be added using +.Ic copy-mode +or the +.Ic set-buffer +command, and pasted into a window using the +.Ic paste-buffer +command. +.Pp +A configurable history buffer is also maintained for each window. +By default, up to 2000 lines are kept; this can be altered with the +.Ic history-limit +option (see the +.Ic set-option +command above). +.Pp +The buffer commands are as follows: +.Bl -tag -width Ds +.It Xo +.Ic choose-buffer +.Op Fl F Ar format +.Op Fl t Ar target-window +.Op Ar template +.Xc +Put a window into buffer choice mode, where a buffer may be chosen +interactively from a list. +After a buffer is selected, +.Ql %% +is replaced by the buffer index in +.Ar template +and the result executed as a command. +If +.Ar template +is not given, "paste-buffer -b '%%'" is used. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +This command works only if at least one client is attached. +.It Ic clear-history Op Fl t Ar target-pane +.D1 (alias: Ic clearhist ) +Remove and free the history for the specified pane. +.It Ic delete-buffer Op Fl b Ar buffer-index +.D1 (alias: Ic deleteb ) +Delete the buffer at +.Ar buffer-index , +or the top buffer if not specified. +.It Xo Ic list-buffers +.Op Fl F Ar format +.Xc +.D1 (alias: Ic lsb ) +List the global buffers. +For the meaning of the +.Fl F +flag, see the +.Sx FORMATS +section. +.It Xo Ic load-buffer +.Op Fl b Ar buffer-index +.Ar path +.Xc +.D1 (alias: Ic loadb ) +Load the contents of the specified paste buffer from +.Ar path . +.It Xo Ic paste-buffer +.Op Fl dpr +.Op Fl b Ar buffer-index +.Op Fl s Ar separator +.Op Fl t Ar target-pane +.Xc +.D1 (alias: Ic pasteb ) +Insert the contents of a paste buffer into the specified pane. +If not specified, paste into the current one. +With +.Fl d , +also delete the paste buffer from the stack. +When output, any linefeed (LF) characters in the paste buffer are replaced with +a separator, by default carriage return (CR). +A custom separator may be specified using the +.Fl s +flag. +The +.Fl r +flag means to do no replacement (equivalent to a separator of LF). +If +.Fl p +is specified, paste bracket control codes are inserted around the +buffer if the application has requested bracketed paste mode. +.It Xo Ic save-buffer +.Op Fl a +.Op Fl b Ar buffer-index +.Ar path +.Xc +.D1 (alias: Ic saveb ) +Save the contents of the specified paste buffer to +.Ar path . +The +.Fl a +option appends to rather than overwriting the file. +.It Xo Ic set-buffer +.Op Fl b Ar buffer-index +.Ar data +.Xc +.D1 (alias: Ic setb ) +Set the contents of the specified buffer to +.Ar data . +.It Xo Ic show-buffer +.Op Fl b Ar buffer-index +.Xc +.D1 (alias: Ic showb ) +Display the contents of the specified buffer. +.El +.Sh MISCELLANEOUS +Miscellaneous commands are as follows: +.Bl -tag -width Ds +.It Ic clock-mode Op Fl t Ar target-pane +Display a large clock. +.It Xo Ic if-shell +.Op Fl b +.Op Fl t Ar target-pane +.Ar shell-command command +.Op Ar command +.Xc +.D1 (alias: Ic if ) +Execute the first +.Ar command +if +.Ar shell-command +returns success or the second +.Ar command +otherwise. +Before being executed, shell-command is expanded using the rules specified in the +.Sx FORMATS +section, including those relevant to +.Ar target-pane . +With +.Fl b , +.Ar shell-command +is run in the background. +.It Ic lock-server +.D1 (alias: Ic lock ) +Lock each client individually by running the command specified by the +.Ic lock-command +option. +.It Xo Ic run-shell +.Fl b +.Op Fl t Ar target-pane +.Ar shell-command +.Xc +.D1 (alias: Ic run ) +Execute +.Ar shell-command +in the background without creating a window. +Before being executed, shell-command is expanded using the rules specified in +the +.Sx FORMATS +section. +With +.Fl b , +the command is run in the background. +After it finishes, any output to stdout is displayed in copy mode (in the pane +specified by +.Fl t +or the current pane if omitted). +If the command doesn't return success, the exit status is also displayed. +.It Ic server-info +.D1 (alias: Ic info ) +Show server information and terminal details. +.It Xo Ic wait-for +.Fl LSU +.Ar channel +.Xc +.D1 (alias: Ic wait ) +When used without options, prevents the client from exiting until woken using +.Ic wait-for +.Fl S +with the same channel. +When +.Fl L +is used, the channel is locked and any clients that try to lock the same +channel are made to wait until the channel is unlocked with +.Ic wait-for +.Fl U . +This command only works from outside +.Nm . +.El +.Sh TERMINFO EXTENSIONS +.Nm +understands some extensions to +.Xr terminfo 5 : +.Bl -tag -width Ds +.It Em Cc , Cr +Set the cursor colour. +The first takes a single string argument and is used to set the colour; +the second takes no arguments and restores the default cursor colour. +If set, a sequence such as this may be used +to change the cursor colour from inside +.Nm : +.Bd -literal -offset indent +$ printf '\e033]12;red\e033\e\e' +.Ed +.It Em Cs , Csr +Change the cursor style. +If set, a sequence such as this may be used +to change the cursor to an underline: +.Bd -literal -offset indent +$ printf '\e033[4 q' +.Ed +.Pp +If +.Em Csr +is set, it will be used to reset the cursor style instead +of +.Em Cs . +.It Em \&Ms +This sequence can be used by +.Nm +to store the current buffer in the host terminal's selection (clipboard). +See the +.Em set-clipboard +option above and the +.Xr xterm 1 +man page. +.El +.Sh CONTROL MODE +.Nm +offers a textual interface called +.Em control mode . +This allows applications to communicate with +.Nm +using a simple text-only protocol. +.Pp +In control mode, a client sends +.Nm +commands or command sequences terminated by newlines on standard input. +Each command will produce one block of output on standard output. +An output block consists of a +.Em %begin +line followed by the output (which may be empty). +The output block ends with a +.Em %end +or +.Em %error . +.Em %begin +and matching +.Em %end +or +.Em %error +have two arguments: an integer time (as seconds from epoch) and command number. +For example: +.Bd -literal -offset indent +%begin 1363006971 2 +0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) +%end 1363006971 2 +.Ed +.Pp +In control mode, +.Nm +outputs notifications. +A notification will never occur inside an output block. +.Pp +The following notifications are defined: +.Bl -tag -width Ds +.It Ic %exit Op Ar reason +The +.Nm +client is exiting immediately, either because it is not attached to any session +or an error occurred. +If present, +.Ar reason +describes why the client exited. +.It Ic %layout-change Ar window-id Ar window-layout +The layout of a window with ID +.Ar window-id +changed. +The new layout is +.Ar window-layout . +.It Ic %output Ar pane-id Ar value +A window pane produced output. +.Ar value +escapes non-printable characters and backslash as octal \\xxx. +.It Ic %session-changed Ar session-id Ar name +The client is now attached to the session with ID +.Ar session-id , +which is named +.Ar name . +.It Ic %session-renamed Ar name +The current session was renamed to +.Ar name . +.It Ic %sessions-changed +A session was created or destroyed. +.It Ic %unlinked-window-add Ar window-id +The window with ID +.Ar window-id +was created but is not linked to the current session. +.It Ic %window-add Ar window-id +The window with ID +.Ar window-id +was linked to the current session. +.It Ic %window-close Ar window-id +The window with ID +.Ar window-id +closed. +.It Ic %window-renamed Ar window-id Ar name +The window with ID +.Ar window-id +was renamed to +.Ar name . +.El +.Sh FILES +.Bl -tag -width "/etc/tmux.confXXX" -compact +.It Pa ~/.tmux.conf +Default +.Nm +configuration file. +.It Pa /etc/tmux.conf +System-wide configuration file. +.El +.Sh EXAMPLES +To create a new +.Nm +session running +.Xr vi 1 : +.Pp +.Dl $ tmux new-session vi +.Pp +Most commands have a shorter form, known as an alias. +For new-session, this is +.Ic new : +.Pp +.Dl $ tmux new vi +.Pp +Alternatively, the shortest unambiguous form of a command is accepted. +If there are several options, they are listed: +.Bd -literal -offset indent +$ tmux n +ambiguous command: n, could be: new-session, new-window, next-window +.Ed +.Pp +Within an active session, a new window may be created by typing +.Ql C-b c +(Ctrl +followed by the +.Ql b +key +followed by the +.Ql c +key). +.Pp +Windows may be navigated with: +.Ql C-b 0 +(to select window 0), +.Ql C-b 1 +(to select window 1), and so on; +.Ql C-b n +to select the next window; and +.Ql C-b p +to select the previous window. +.Pp +A session may be detached using +.Ql C-b d +(or by an external event such as +.Xr ssh 1 +disconnection) and reattached with: +.Pp +.Dl $ tmux attach-session +.Pp +Typing +.Ql C-b \&? +lists the current key bindings in the current window; up and down may be used +to navigate the list or +.Ql q +to exit from it. +.Pp +Commands to be run when the +.Nm +server is started may be placed in the +.Pa ~/.tmux.conf +configuration file. +Common examples include: +.Pp +Changing the default prefix key: +.Bd -literal -offset indent +set-option -g prefix C-a +unbind-key C-b +bind-key C-a send-prefix +.Ed +.Pp +Turning the status line off, or changing its colour: +.Bd -literal -offset indent +set-option -g status off +set-option -g status-bg blue +.Ed +.Pp +Setting other options, such as the default command, +or locking after 30 minutes of inactivity: +.Bd -literal -offset indent +set-option -g default-command "exec /bin/ksh" +set-option -g lock-after-time 1800 +.Ed +.Pp +Creating new key bindings: +.Bd -literal -offset indent +bind-key b set-option status +bind-key / command-prompt "split-window 'exec man %%'" +bind-key S command-prompt "new-window -n %1 'ssh %1'" +.Ed +.Sh SEE ALSO +.Xr pty 4 +.Sh AUTHORS +.An Nicholas Marriott Aq nicm@users.sourceforge.net diff --git a/tmux.1.in b/tmux.1.in deleted file mode 100644 index 98bf9574..00000000 --- a/tmux.1.in +++ /dev/null @@ -1,3808 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright (c) 2007 Nicholas Marriott -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER -.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING -.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: March 25 2013 $ -.Dt TMUX 1 -.Os -.Sh NAME -.Nm tmux -.Nd terminal multiplexer -.Sh SYNOPSIS -.Nm tmux -.Bk -words -.Op Fl 28lCquvV -.Op Fl c Ar shell-command -.Op Fl f Ar file -.Op Fl L Ar socket-name -.Op Fl S Ar socket-path -.Op Ar command Op Ar flags -.Ek -.Sh DESCRIPTION -.Nm -is a terminal multiplexer: -it enables a number of terminals to be created, accessed, and -controlled from a single screen. -.Nm -may be detached from a screen -and continue running in the background, -then later reattached. -.Pp -When -.Nm -is started it creates a new -.Em session -with a single -.Em window -and displays it on screen. -A status line at the bottom of the screen -shows information on the current session -and is used to enter interactive commands. -.Pp -A session is a single collection of -.Em pseudo terminals -under the management of -.Nm . -Each session has one or more -windows linked to it. -A window occupies the entire screen -and may be split into rectangular panes, -each of which is a separate pseudo terminal -(the -.Xr pty 4 -manual page documents the technical details of pseudo terminals). -Any number of -.Nm -instances may connect to the same session, -and any number of windows may be present in the same session. -Once all sessions are killed, -.Nm -exits. -.Pp -Each session is persistent and will survive accidental disconnection -(such as -.Xr ssh 1 -connection timeout) or intentional detaching (with the -.Ql C-b d -key strokes). -.Nm -may be reattached using: -.Pp -.Dl $ tmux attach -.Pp -In -.Nm , -a session is displayed on screen by a -.Em client -and all sessions are managed by a single -.Em server . -The server and each client are separate processes which communicate through a -socket in -.Pa /tmp . -.Pp -The options are as follows: -.Bl -tag -width "XXXXXXXXXXXX" -.It Fl 2 -Force -.Nm -to assume the terminal supports 256 colours. -.It Fl C -Start in control mode. -Given twice -.Xo ( Fl CC ) Xc -disables echo. -.It Fl c Ar shell-command -Execute -.Ar shell-command -using the default shell. -If necessary, the -.Nm -server will be started to retrieve the -.Ic default-shell -option. -This option is for compatibility with -.Xr sh 1 -when -.Nm -is used as a login shell. -.It Fl f Ar file -Specify an alternative configuration file. -By default, -.Nm -loads the system configuration file from -.Pa /etc/tmux.conf , -if present, then looks for a user configuration file at -.Pa ~/.tmux.conf . -.Pp -The configuration file is a set of -.Nm -commands which are executed in sequence when the server is first started. -.Nm -loads configuration files once when the server process has started. -The -.Ic source-file -command may be used to load a file later. -.Pp -.Nm -shows any error messages from commands in configuration files in the first -session created, and continues to process the rest of the configuration file. -.It Fl L Ar socket-name -.Nm -stores the server socket in a directory under -.Ev TMUX_TMPDIR , -.Ev TMPDIR -if it is unset, or -.Pa /tmp -if both are unset. -The default socket is named -.Em default . -This option allows a different socket name to be specified, allowing several -independent -.Nm -servers to be run. -Unlike -.Fl S -a full path is not necessary: the sockets are all created in the same -directory. -.Pp -If the socket is accidentally removed, the -.Dv SIGUSR1 -signal may be sent to the -.Nm -server process to recreate it. -.It Fl l -Behave as a login shell. -This flag currently has no effect and is for compatibility with other shells -when using tmux as a login shell. -.It Fl q -Set the -.Ic quiet -server option to prevent the server sending various informational messages. -.It Fl S Ar socket-path -Specify a full alternative path to the server socket. -If -.Fl S -is specified, the default socket directory is not used and any -.Fl L -flag is ignored. -.It Fl u -.Nm -attempts to guess if the terminal is likely to support UTF-8 by checking the -first of the -.Ev LC_ALL , -.Ev LC_CTYPE -and -.Ev LANG -environment variables to be set for the string "UTF-8". -This is not always correct: the -.Fl u -flag explicitly informs -.Nm -that UTF-8 is supported. -.Pp -If the server is started from a client passed -.Fl u -or where UTF-8 is detected, the -.Ic utf8 -and -.Ic status-utf8 -options are enabled in the global window and session options respectively. -.It Fl v -Request verbose logging. -This option may be specified multiple times for increasing verbosity. -Log messages will be saved into -.Pa tmux-client-PID.log -and -.Pa tmux-server-PID.log -files in the current directory, where -.Em PID -is the PID of the server or client process. -.It Fl V -Report the -.Nm -version. -.It Ar command Op Ar flags -This specifies one of a set of commands used to control -.Nm , -as described in the following sections. -If no commands are specified, the -.Ic new-session -command is assumed. -.El -.Sh KEY BINDINGS -.Nm -may be controlled from an attached client by using a key combination of a -prefix key, -.Ql C-b -(Ctrl-b) by default, followed by a command key. -.Pp -The default command key bindings are: -.Pp -.Bl -tag -width "XXXXXXXXXX" -offset indent -compact -.It C-b -Send the prefix key (C-b) through to the application. -.It C-o -Rotate the panes in the current window forwards. -.It C-z -Suspend the -.Nm -client. -.It ! -Break the current pane out of the window. -.It \&" -Split the current pane into two, top and bottom. -.It # -List all paste buffers. -.It $ -Rename the current session. -.It % -Split the current pane into two, left and right. -.It & -Kill the current window. -.It ' -Prompt for a window index to select. -.It , -Rename the current window. -.It - -Delete the most recently copied buffer of text. -.It . -Prompt for an index to move the current window. -.It 0 to 9 -Select windows 0 to 9. -.It : -Enter the -.Nm -command prompt. -.It ; -Move to the previously active pane. -.It = -Choose which buffer to paste interactively from a list. -.It \&? -List all key bindings. -.It D -Choose a client to detach. -.It \&[ -Enter copy mode to copy text or view the history. -.It \&] -Paste the most recently copied buffer of text. -.It c -Create a new window. -.It d -Detach the current client. -.It f -Prompt to search for text in open windows. -.It i -Display some information about the current window. -.It l -Move to the previously selected window. -.It n -Change to the next window. -.It o -Select the next pane in the current window. -.It p -Change to the previous window. -.It q -Briefly display pane indexes. -.It r -Force redraw of the attached client. -.It s -Select a new session for the attached client interactively. -.It L -Switch the attached client back to the last session. -.It t -Show the time. -.It w -Choose the current window interactively. -.It x -Kill the current pane. -.It { -Swap the current pane with the previous pane. -.It } -Swap the current pane with the next pane. -.It ~ -Show previous messages from -.Nm , -if any. -.It Page Up -Enter copy mode and scroll one page up. -.It Up, Down -.It Left, Right -Change to the pane above, below, to the left, or to the right of the current -pane. -.It M-1 to M-5 -Arrange panes in one of the five preset layouts: even-horizontal, -even-vertical, main-horizontal, main-vertical, or tiled. -.It M-n -Move to the next window with a bell or activity marker. -.It M-o -Rotate the panes in the current window backwards. -.It M-p -Move to the previous window with a bell or activity marker. -.It C-Up, C-Down -.It C-Left, C-Right -Resize the current pane in steps of one cell. -.It M-Up, M-Down -.It M-Left, M-Right -Resize the current pane in steps of five cells. -.El -.Pp -Key bindings may be changed with the -.Ic bind-key -and -.Ic unbind-key -commands. -.Sh COMMANDS -This section contains a list of the commands supported by -.Nm . -Most commands accept the optional -.Fl t -argument with one of -.Ar target-client , -.Ar target-session -.Ar target-window , -or -.Ar target-pane . -These specify the client, session, window or pane which a command should affect. -.Ar target-client -is the name of the -.Xr pty 4 -file to which the client is connected, for example either of -.Pa /dev/ttyp1 -or -.Pa ttyp1 -for the client attached to -.Pa /dev/ttyp1 . -If no client is specified, the current client is chosen, if possible, or an -error is reported. -Clients may be listed with the -.Ic list-clients -command. -.Pp -.Ar target-session -is the session id prefixed with a $, the name of a session (as listed by the -.Ic list-sessions -command), or the name of a client with the same syntax as -.Ar target-client , -in which case the session attached to the client is used. -When looking for the session name, -.Nm -initially searches for an exact match; if none is found, the session names -are checked for any for which -.Ar target-session -is a prefix or for which it matches as an -.Xr fnmatch 3 -pattern. -If a single match is found, it is used as the target session; multiple matches -produce an error. -If a session is omitted, the current session is used if available; if no -current session is available, the most recently used is chosen. -.Pp -.Ar target-window -specifies a window in the form -.Em session Ns \&: Ns Em window . -.Em session -follows the same rules as for -.Ar target-session , -and -.Em window -is looked for in order: as a window index, for example mysession:1; -as a window ID, such as @1; -as an exact window name, such as mysession:mywindow; then as an -.Xr fnmatch 3 -pattern or the start of a window name, such as mysession:mywin* or -mysession:mywin. -An empty window name specifies the next unused index if appropriate (for -example the -.Ic new-window -and -.Ic link-window -commands) -otherwise the current window in -.Em session -is chosen. -The special character -.Ql \&! -uses the last (previously current) window, -.Ql ^ -selects the highest numbered window, -.Ql $ -selects the lowest numbered window, and -.Ql + -and -.Ql - -select the next window or the previous window by number. -When the argument does not contain a colon, -.Nm -first attempts to parse it as window; if that fails, an attempt is made to -match a session. -.Pp -.Ar target-pane -takes a similar form to -.Ar target-window -but with the optional addition of a period followed by a pane index, for -example: mysession:mywindow.1. -If the pane index is omitted, the currently active pane in the specified -window is used. -If neither a colon nor period appears, -.Nm -first attempts to use the argument as a pane index; if that fails, it is looked -up as for -.Ar target-window . -A -.Ql + -or -.Ql - -indicate the next or previous pane index, respectively. -One of the strings -.Em top , -.Em bottom , -.Em left , -.Em right , -.Em top-left , -.Em top-right , -.Em bottom-left -or -.Em bottom-right -may be used instead of a pane index. -.Pp -The special characters -.Ql + -and -.Ql - -may be followed by an offset, for example: -.Bd -literal -offset indent -select-window -t:+2 -.Ed -.Pp -When dealing with a session that doesn't contain sequential window indexes, -they will be correctly skipped. -.Pp -.Nm -also gives each pane created in a server an identifier consisting of a -.Ql % -and a number, starting from zero. -A pane's identifier is unique for the life of the -.Nm -server and is passed to the child process of the pane in the -.Ev TMUX_PANE -environment variable. -It may be used alone to target a pane or the window containing it. -.Pp -.Ar shell-command -arguments are -.Xr sh 1 -commands. -These must be passed as a single item, which typically means quoting them, for -example: -.Bd -literal -offset indent -new-window 'vi /etc/passwd' -.Ed -.Pp -.Ar command -.Op Ar arguments -refers to a -.Nm -command, passed with the command and arguments separately, for example: -.Bd -literal -offset indent -bind-key F1 set-window-option force-width 81 -.Ed -.Pp -Or if using -.Xr sh 1 : -.Bd -literal -offset indent -$ tmux bind-key F1 set-window-option force-width 81 -.Ed -.Pp -Multiple commands may be specified together as part of a -.Em command sequence . -Each command should be separated by spaces and a semicolon; -commands are executed sequentially from left to right and -lines ending with a backslash continue on to the next line, -except when escaped by another backslash. -A literal semicolon may be included by escaping it with a backslash (for -example, when specifying a command sequence to -.Ic bind-key ) . -.Pp -Example -.Nm -commands include: -.Bd -literal -offset indent -refresh-client -t/dev/ttyp2 - -rename-session -tfirst newname - -set-window-option -t:0 monitor-activity on - -new-window ; split-window -d - -bind-key R source-file ~/.tmux.conf \e; \e - display-message "source-file done" -.Ed -.Pp -Or from -.Xr sh 1 : -.Bd -literal -offset indent -$ tmux kill-window -t :1 - -$ tmux new-window \e; split-window -d - -$ tmux new-session -d 'vi /etc/passwd' \e; split-window -d \e; attach -.Ed -.Sh CLIENTS AND SESSIONS -The -.Nm -server manages clients, sessions, windows and panes. -Clients are attached to sessions to interact with them, either -when they are created with the -.Ic new-session -command, or later with the -.Ic attach-session -command. -Each session has one or more windows -.Em linked -into it. -Windows may be linked to multiple sessions and are made up of one or -more panes, -each of which contains a pseudo terminal. -Commands for creating, linking and otherwise manipulating windows -are covered -in the -.Sx WINDOWS AND PANES -section. -.Pp -The following commands are available to manage clients and sessions: -.Bl -tag -width Ds -.It Xo Ic attach-session -.Op Fl dr -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic attach ) -If run from outside -.Nm , -create a new client in the current terminal and attach it to -.Ar target-session . -If used from inside, switch the current client. -If -.Fl d -is specified, any other clients attached to the session are detached. -.Fl r -signifies the client is read-only (only keys bound to the -.Ic detach-client -or -.Ic switch-client -commands have any effect) -.Pp -If no server is started, -.Ic attach-session -will attempt to start it; this will fail unless sessions are created in the -configuration file. -.Pp -The -.Ar target-session -rules for -.Ic attach-session -are slightly adjusted: if -.Nm -needs to select the most recently used session, it will prefer the most -recently used -.Em unattached -session. -.It Xo Ic detach-client -.Op Fl P -.Op Fl a -.Op Fl s Ar target-session -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic detach ) -Detach the current client if bound to a key, the client specified with -.Fl t , -or all clients currently attached to the session specified by -.Fl s . -The -.Fl a -option kills all but the client given with -.Fl t . -If -.Fl P -is given, send SIGHUP to the parent process of the client, typically causing it -to exit. -.It Ic has-session Op Fl t Ar target-session -.D1 (alias: Ic has ) -Report an error and exit with 1 if the specified session does not exist. -If it does exist, exit with 0. -.It Ic kill-server -Kill the -.Nm -server and clients and destroy all sessions. -.It Ic kill-session -.Op Fl a -.Op Fl t Ar target-session -Destroy the given session, closing any windows linked to it and no other -sessions, and detaching all clients attached to it. -If -.Fl a -is given, all sessions but the specified one is killed. -.It Xo Ic list-clients -.Op Fl F Ar format -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic lsc ) -List all clients attached to the server. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -If -.Ar target-session -is specified, list only clients connected to that session. -.It Ic list-commands -.D1 (alias: Ic lscm ) -List the syntax of all commands supported by -.Nm . -.It Ic list-sessions Op Fl F Ar format -.D1 (alias: Ic ls ) -List all sessions managed by the server. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Ic lock-client Op Fl t Ar target-client -.D1 (alias: Ic lockc ) -Lock -.Ar target-client , -see the -.Ic lock-server -command. -.It Ic lock-session Op Fl t Ar target-session -.D1 (alias: Ic locks ) -Lock all clients attached to -.Ar target-session . -.It Xo Ic new-session -.Op Fl AdDP -.Op Fl F Ar format -.Op Fl n Ar window-name -.Op Fl s Ar session-name -.Op Fl t Ar target-session -.Op Fl x Ar width -.Op Fl y Ar height -.Op Ar shell-command -.Xc -.D1 (alias: Ic new ) -Create a new session with name -.Ar session-name . -.Pp -The new session is attached to the current terminal unless -.Fl d -is given. -.Ar window-name -and -.Ar shell-command -are the name of and shell command to execute in the initial window. -If -.Fl d -is used, -.Fl x -and -.Fl y -specify the size of the initial window (80 by 24 if not given). -.Pp -If run from a terminal, any -.Xr termios 4 -special characters are saved and used for new windows in the new session. -.Pp -The -.Fl A -flag makes -.Ic new-session -behave like -.Ic attach-session -if -.Ar session-name -already exists; in the case, -.Fl D -behaves like -.Fl d -to -.Ic attach-session . -.Pp -If -.Fl t -is given, the new session is -.Em grouped -with -.Ar target-session . -This means they share the same set of windows - all windows from -.Ar target-session -are linked to the new session and any subsequent new windows or windows being -closed are applied to both sessions. -The current and previous window and any session options remain independent and -either session may be killed without affecting the other. -Giving -.Fl n -or -.Ar shell-command -are invalid if -.Fl t -is used. -.Pp -The -.Fl P -option prints information about the new session after it has been created. -By default, it uses the format -.Ql #{session_name}: -but a different format may be specified with -.Fl F . -.It Xo Ic refresh-client -.Op Fl S -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic refresh ) -Refresh the current client if bound to a key, or a single client if one is given -with -.Fl t . -If -.Fl S -is specified, only update the client's status bar. -.It Xo Ic rename-session -.Op Fl t Ar target-session -.Ar new-name -.Xc -.D1 (alias: Ic rename ) -Rename the session to -.Ar new-name . -.It Xo Ic show-messages -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic showmsgs ) -Any messages displayed on the status line are saved in a per-client message -log, up to a maximum of the limit set by the -.Ar message-limit -session option for the session attached to that client. -This command displays the log for -.Ar target-client . -.It Ic source-file Ar path -.D1 (alias: Ic source ) -Execute commands from -.Ar path . -.It Ic start-server -.D1 (alias: Ic start ) -Start the -.Nm -server, if not already running, without creating any sessions. -.It Xo Ic suspend-client -.Op Fl t Ar target-client -.Xc -.D1 (alias: Ic suspendc ) -Suspend a client by sending -.Dv SIGTSTP -(tty stop). -.It Xo Ic switch-client -.Op Fl lnpr -.Op Fl c Ar target-client -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic switchc ) -Switch the current session for client -.Ar target-client -to -.Ar target-session . -If -.Fl l , -.Fl n -or -.Fl p -is used, the client is moved to the last, next or previous session -respectively. -.Fl r -toggles whether a client is read-only (see the -.Ic attach-session -command). -.El -.Sh WINDOWS AND PANES -A -.Nm -window may be in one of several modes. -The default permits direct access to the terminal attached to the window. -The other is copy mode, which permits a section of a window or its -history to be copied to a -.Em paste buffer -for later insertion into another window. -This mode is entered with the -.Ic copy-mode -command, bound to -.Ql \&[ -by default. -It is also entered when a command that produces output, such as -.Ic list-keys , -is executed from a key binding. -.Pp -The keys available depend on whether emacs or vi mode is selected -(see the -.Ic mode-keys -option). -The following keys are supported as appropriate for the mode: -.Bl -column "FunctionXXXXXXXXXXXXXXXXX" "viXXXXXXXXXX" "emacs" -offset indent -.It Sy "Function" Ta Sy "vi" Ta Sy "emacs" -.It Li "Back to indentation" Ta "^" Ta "M-m" -.It Li "Bottom of history" Ta "G" Ta "M-<" -.It Li "Clear selection" Ta "Escape" Ta "C-g" -.It Li "Copy selection" Ta "Enter" Ta "M-w" -.It Li "Cursor down" Ta "j" Ta "Down" -.It Li "Cursor left" Ta "h" Ta "Left" -.It Li "Cursor right" Ta "l" Ta "Right" -.It Li "Cursor to bottom line" Ta "L" Ta "" -.It Li "Cursor to middle line" Ta "M" Ta "M-r" -.It Li "Cursor to top line" Ta "H" Ta "M-R" -.It Li "Cursor up" Ta "k" Ta "Up" -.It Li "Delete entire line" Ta "d" Ta "C-u" -.It Li "Delete/Copy to end of line" Ta "D" Ta "C-k" -.It Li "End of line" Ta "$" Ta "C-e" -.It Li "Go to line" Ta ":" Ta "g" -.It Li "Half page down" Ta "C-d" Ta "M-Down" -.It Li "Half page up" Ta "C-u" Ta "M-Up" -.It Li "Jump forward" Ta "f" Ta "f" -.It Li "Jump to forward" Ta "t" Ta "" -.It Li "Jump backward" Ta "F" Ta "F" -.It Li "Jump to backward" Ta "T" Ta "" -.It Li "Jump again" Ta ";" Ta ";" -.It Li "Jump again in reverse" Ta "," Ta "," -.It Li "Next page" Ta "C-f" Ta "Page down" -.It Li "Next space" Ta "W" Ta "" -.It Li "Next space, end of word" Ta "E" Ta "" -.It Li "Next word" Ta "w" Ta "" -.It Li "Next word end" Ta "e" Ta "M-f" -.It Li "Paste buffer" Ta "p" Ta "C-y" -.It Li "Previous page" Ta "C-b" Ta "Page up" -.It Li "Previous word" Ta "b" Ta "M-b" -.It Li "Previous space" Ta "B" Ta "" -.It Li "Quit mode" Ta "q" Ta "Escape" -.It Li "Rectangle toggle" Ta "v" Ta "R" -.It Li "Scroll down" Ta "C-Down or C-e" Ta "C-Down" -.It Li "Scroll up" Ta "C-Up or C-y" Ta "C-Up" -.It Li "Search again" Ta "n" Ta "n" -.It Li "Search again in reverse" Ta "N" Ta "N" -.It Li "Search backward" Ta "?" Ta "C-r" -.It Li "Search forward" Ta "/" Ta "C-s" -.It Li "Start of line" Ta "0" Ta "C-a" -.It Li "Start selection" Ta "Space" Ta "C-Space" -.It Li "Top of history" Ta "g" Ta "M->" -.It Li "Transpose characters" Ta "" Ta "C-t" -.El -.Pp -The next and previous word keys use space and the -.Ql - , -.Ql _ -and -.Ql @ -characters as word delimiters by default, but this can be adjusted by -setting the -.Em word-separators -session option. -Next word moves to the start of the next word, next word end to the end of the -next word and previous word to the start of the previous word. -The three next and previous space keys work similarly but use a space alone as -the word separator. -.Pp -The jump commands enable quick movement within a line. -For instance, typing -.Ql f -followed by -.Ql / -will move the cursor to the next -.Ql / -character on the current line. -A -.Ql \&; -will then jump to the next occurrence. -.Pp -Commands in copy mode may be prefaced by an optional repeat count. -With vi key bindings, a prefix is entered using the number keys; with -emacs, the Alt (meta) key and a number begins prefix entry. -For example, to move the cursor forward by ten words, use -.Ql M-1 0 M-f -in emacs mode, and -.Ql 10w -in vi. -.Pp -When copying the selection, the repeat count indicates the buffer index to -replace, if used. -.Pp -Mode key bindings are defined in a set of named tables: -.Em vi-edit -and -.Em emacs-edit -for keys used when line editing at the command prompt; -.Em vi-choice -and -.Em emacs-choice -for keys used when choosing from lists (such as produced by the -.Ic choose-window -command); and -.Em vi-copy -and -.Em emacs-copy -used in copy mode. -The tables may be viewed with the -.Ic list-keys -command and keys modified or removed with -.Ic bind-key -and -.Ic unbind-key . -One command accepts an argument, -.Ic copy-pipe , -which copies the selection and pipes it to a command. -For example the following will bind -.Ql C-q -to copy the selection into -.Pa /tmp -as well as the paste buffer: -.Bd -literal -offset indent -bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" -.Ed -.Pp -The paste buffer key pastes the first line from the top paste buffer on the -stack. -.Pp -The synopsis for the -.Ic copy-mode -command is: -.Bl -tag -width Ds -.It Xo Ic copy-mode -.Op Fl u -.Op Fl t Ar target-pane -.Xc -Enter copy mode. -The -.Fl u -option scrolls one page up. -.El -.Pp -Each window displayed by -.Nm -may be split into one or more -.Em panes ; -each pane takes up a certain area of the display and is a separate terminal. -A window may be split into panes using the -.Ic split-window -command. -Windows may be split horizontally (with the -.Fl h -flag) or vertically. -Panes may be resized with the -.Ic resize-pane -command (bound to -.Ql C-up , -.Ql C-down -.Ql C-left -and -.Ql C-right -by default), the current pane may be changed with the -.Ic select-pane -command and the -.Ic rotate-window -and -.Ic swap-pane -commands may be used to swap panes without changing their position. -Panes are numbered beginning from zero in the order they are created. -.Pp -A number of preset -.Em layouts -are available. -These may be selected with the -.Ic select-layout -command or cycled with -.Ic next-layout -(bound to -.Ql Space -by default); once a layout is chosen, panes within it may be moved and resized -as normal. -.Pp -The following layouts are supported: -.Bl -tag -width Ds -.It Ic even-horizontal -Panes are spread out evenly from left to right across the window. -.It Ic even-vertical -Panes are spread evenly from top to bottom. -.It Ic main-horizontal -A large (main) pane is shown at the top of the window and the remaining panes -are spread from left to right in the leftover space at the bottom. -Use the -.Em main-pane-height -window option to specify the height of the top pane. -.It Ic main-vertical -Similar to -.Ic main-horizontal -but the large pane is placed on the left and the others spread from top to -bottom along the right. -See the -.Em main-pane-width -window option. -.It Ic tiled -Panes are spread out as evenly as possible over the window in both rows and -columns. -.El -.Pp -In addition, -.Ic select-layout -may be used to apply a previously used layout - the -.Ic list-windows -command displays the layout of each window in a form suitable for use with -.Ic select-layout . -For example: -.Bd -literal -offset indent -$ tmux list-windows -0: ksh [159x48] - layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0} -$ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0} -.Ed -.Pp -.Nm -automatically adjusts the size of the layout for the current window size. -Note that a layout cannot be applied to a window with more panes than that -from which the layout was originally defined. -.Pp -Commands related to windows and panes are as follows: -.Bl -tag -width Ds -.It Xo Ic break-pane -.Op Fl dP -.Op Fl F Ar format -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic breakp ) -Break -.Ar target-pane -off from its containing window to make it the only pane in a new window. -If -.Fl d -is given, the new window does not become the current window. -The -.Fl P -option prints information about the new window after it has been created. -By default, it uses the format -.Ql #{session_name}:#{window_index} -but a different format may be specified with -.Fl F . -.It Xo Ic capture-pane -.Op Fl aepPq -.Op Fl b Ar buffer-index -.Op Fl E Ar end-line -.Op Fl S Ar start-line -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic capturep ) -Capture the contents of a pane. -If -.Fl p -is given, the output goes to stdout, otherwise to the buffer specified with -.Fl b -or a new buffer if omitted. -If -.Fl a -is given, the alternate screen is used, and the history is not accessible. -If no alternate screen exists, an error will be returned unless -.Fl q -is given. -If -.Fl e -is given, the output includes escape sequences for text and background -attributes. -.Fl C -also escapes non-printable characters as octal \exxx. -.Fl J -joins wrapped lines and preserves trailing spaces at each line's end. -.Fl P -captures only any output that the pane has received that is the beginning of an -as-yet incomplete escape sequence. -.Pp -.Fl S -and -.Fl E -specify the starting and ending line numbers, zero is the first line of the -visible pane and negative numbers are lines in the history. -The default is to capture only the visible contents of the pane. -.It Xo -.Ic choose-client -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into client choice mode, allowing a client to be selected -interactively from a list. -After a client is chosen, -.Ql %% -is replaced by the client -.Xr pty 4 -path in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "detach-client -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-list -.Op Fl l Ar items -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into list choice mode, allowing -.Ar items -to be selected. -.Ar items -can be a comma-separated list to display more than one item. -If an item has spaces, that entry must be quoted. -After an item is chosen, -.Ql %% -is replaced by the chosen item in the -.Ar template -and the result is executed as a command. -If -.Ar template -is not given, "run-shell '%%'" is used. -.Ar items -also accepts format specifiers. -For the meaning of this see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-session -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into session choice mode, where a session may be selected -interactively from a list. -When one is chosen, -.Ql %% -is replaced by the session name in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "switch-client -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo -.Ic choose-tree -.Op Fl suw -.Op Fl b Ar session-template -.Op Fl c Ar window-template -.Op Fl S Ar format -.Op Fl W Ar format -.Op Fl t Ar target-window -.Xc -Put a window into tree choice mode, where either sessions or windows may be -selected interactively from a list. -By default, windows belonging to a session are indented to show their -relationship to a session. -.Pp -Note that the -.Ic choose-window -and -.Ic choose-session -commands are wrappers around -.Ic choose-tree . -.Pp -If -.Fl s -is given, will show sessions. -If -.Fl w -is given, will show windows. -.Pp -By default, the tree is collapsed and sessions must be expanded to windows -with the right arrow key. -The -.Fl u -option will start with all sessions expanded instead. -.Pp -If -.Fl b -is given, will override the default session command. -Note that -.Ql %% -can be used and will be replaced with the session name. -The default option if not specified is "switch-client -t '%%'". -If -.Fl c -is given, will override the default window command. -Like -.Fl b , -.Ql %% -can be used and will be replaced with the session name and window index. -When a window is chosen from the list, the session command is run before the -window command. -.Pp -If -.Fl S -is given will display the specified format instead of the default session -format. -If -.Fl W -is given will display the specified format instead of the default window -format. -For the meaning of the -.Fl s -and -.Fl w -options, see the -.Sx FORMATS -section. -.Pp -This command works only if at least one client is attached. -.It Xo -.Ic choose-window -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into window choice mode, where a window may be chosen -interactively from a list. -After a window is selected, -.Ql %% -is replaced by the session name and window index in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "select-window -t '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Ic display-panes Op Fl t Ar target-client -.D1 (alias: Ic displayp) -Display a visible indicator of each pane shown by -.Ar target-client . -See the -.Ic display-panes-time , -.Ic display-panes-colour , -and -.Ic display-panes-active-colour -session options. -While the indicator is on screen, a pane may be selected with the -.Ql 0 -to -.Ql 9 -keys. -.It Xo Ic find-window -.Op Fl CNT -.Op Fl F Ar format -.Op Fl t Ar target-window -.Ar match-string -.Xc -.D1 (alias: Ic findw ) -Search for the -.Xr fnmatch 3 -pattern -.Ar match-string -in window names, titles, and visible content (but not history). -The flags control matching behavior: -.Fl C -matches only visible window contents, -.Fl N -matches only the window name and -.Fl T -matches only the window title. -The default is -.Fl CNT . -If only one window is matched, it'll be automatically selected, -otherwise a choice list is shown. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Xo Ic join-pane -.Op Fl bdhv -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic joinp ) -Like -.Ic split-window , -but instead of splitting -.Ar dst-pane -and creating a new pane, split it and move -.Ar src-pane -into the space. -This can be used to reverse -.Ic break-pane . -The -.Fl b -option causes -.Ar src-pane -to be joined to left of or above -.Ar dst-pane . -.It Xo Ic kill-pane -.Op Fl a -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic killp ) -Destroy the given pane. -If no panes remain in the containing window, it is also destroyed. -The -.Fl a -option kills all but the pane given with -.Fl t . -.It Xo Ic kill-window -.Op Fl a -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic killw ) -Kill the current window or the window at -.Ar target-window , -removing it from any sessions to which it is linked. -The -.Fl a -option kills all but the window given with -.Fl t . -.It Ic last-pane Op Fl t Ar target-window -.D1 (alias: Ic lastp ) -Select the last (previously selected) pane. -.It Ic last-window Op Fl t Ar target-session -.D1 (alias: Ic last ) -Select the last (previously selected) window. -If no -.Ar target-session -is specified, select the last window of the current session. -.It Xo Ic link-window -.Op Fl dk -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic linkw ) -Link the window at -.Ar src-window -to the specified -.Ar dst-window . -If -.Ar dst-window -is specified and no such window exists, the -.Ar src-window -is linked there. -If -.Fl k -is given and -.Ar dst-window -exists, it is killed, otherwise an error is generated. -If -.Fl d -is given, the newly linked window is not selected. -.It Xo Ic list-panes -.Op Fl as -.Op Fl F Ar format -.Op Fl t Ar target -.Xc -.D1 (alias: Ic lsp ) -If -.Fl a -is given, -.Ar target -is ignored and all panes on the server are listed. -If -.Fl s -is given, -.Ar target -is a session (or the current session). -If neither is given, -.Ar target -is a window (or the current window). -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic list-windows -.Op Fl a -.Op Fl F Ar format -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic lsw ) -If -.Fl a -is given, list all windows on the server. -Otherwise, list windows in the current session or in -.Ar target-session . -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic move-pane -.Op Fl bdhv -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic movep ) -Like -.Ic join-pane , -but -.Ar src-pane -and -.Ar dst-pane -may belong to the same window. -.It Xo Ic move-window -.Op Fl rdk -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic movew ) -This is similar to -.Ic link-window , -except the window at -.Ar src-window -is moved to -.Ar dst-window . -With -.Fl r , -all windows in the session are renumbered in sequential order, respecting -the -.Ic base-index -option. -.It Xo Ic new-window -.Op Fl adkP -.Op Fl c Ar start-directory -.Op Fl F Ar format -.Op Fl n Ar window-name -.Op Fl t Ar target-window -.Op Ar shell-command -.Xc -.D1 (alias: Ic neww ) -Create a new window. -With -.Fl a , -the new window is inserted at the next index up from the specified -.Ar target-window , -moving windows up if necessary, -otherwise -.Ar target-window -is the new window location. -.Pp -If -.Fl d -is given, the session does not make the new window the current window. -.Ar target-window -represents the window to be created; if the target already exists an error is -shown, unless the -.Fl k -flag is used, in which case it is destroyed. -.Ar shell-command -is the command to execute. -If -.Ar shell-command -is not specified, the value of the -.Ic default-command -option is used. -.Fl c -specifies the working directory in which the new window is created. -It may have an absolute path or one of the following values (or a subdirectory): -.Bl -column "XXXXXXXXXXXX" "XXXXXXXXXXXXXXXXXXXXXXXX" -offset indent -.It Li "Empty string" Ta "Current pane's directory" -.It Li "~" Ta "User's home directory" -.It Li "-" Ta "Where session was started" -.It Li "." Ta "Where server was started" -.El -.Pp -When the shell command completes, the window closes. -See the -.Ic remain-on-exit -option to change this behaviour. -.Pp -The -.Ev TERM -environment variable must be set to -.Dq screen -for all programs running -.Em inside -.Nm . -New windows will automatically have -.Dq TERM=screen -added to their environment, but care must be taken not to reset this in shell -start-up files. -.Pp -The -.Fl P -option prints information about the new window after it has been created. -By default, it uses the format -.Ql #{session_name}:#{window_index} -but a different format may be specified with -.Fl F . -.It Ic next-layout Op Fl t Ar target-window -.D1 (alias: Ic nextl ) -Move a window to the next layout and rearrange the panes to fit. -.It Xo Ic next-window -.Op Fl a -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic next ) -Move to the next window in the session. -If -.Fl a -is used, move to the next window with an alert. -.It Xo Ic pipe-pane -.Op Fl o -.Op Fl t Ar target-pane -.Op Ar shell-command -.Xc -.D1 (alias: Ic pipep ) -Pipe any output sent by the program in -.Ar target-pane -to a shell command. -A pane may only be piped to one command at a time, any existing pipe is -closed before -.Ar shell-command -is executed. -The -.Ar shell-command -string may contain the special character sequences supported by the -.Ic status-left -option. -If no -.Ar shell-command -is given, the current pipe (if any) is closed. -.Pp -The -.Fl o -option only opens a new pipe if no previous pipe exists, allowing a pipe to -be toggled with a single key, for example: -.Bd -literal -offset indent -bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' -.Ed -.It Xo Ic previous-layout -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic prevl ) -Move to the previous layout in the session. -.It Xo Ic previous-window -.Op Fl a -.Op Fl t Ar target-session -.Xc -.D1 (alias: Ic prev ) -Move to the previous window in the session. -With -.Fl a , -move to the previous window with an alert. -.It Xo Ic rename-window -.Op Fl t Ar target-window -.Ar new-name -.Xc -.D1 (alias: Ic renamew ) -Rename the current window, or the window at -.Ar target-window -if specified, to -.Ar new-name . -.It Xo Ic resize-pane -.Op Fl DLRUZ -.Op Fl t Ar target-pane -.Op Fl x Ar width -.Op Fl y Ar height -.Op Ar adjustment -.Xc -.D1 (alias: Ic resizep ) -Resize a pane, up, down, left or right by -.Ar adjustment -with -.Fl U , -.Fl D , -.Fl L -or -.Fl R , -or -to an absolute size -with -.Fl x -or -.Fl y . -The -.Ar adjustment -is given in lines or cells (the default is 1). -.Pp -With -.Fl Z , -the active pane is toggled between zoomed (occupying the whole of the window) -and unzoomed (its normal position in the layout). -.It Xo Ic respawn-pane -.Op Fl k -.Op Fl t Ar target-pane -.Op Ar shell-command -.Xc -.D1 (alias: Ic respawnp ) -Reactivate a pane in which the command has exited (see the -.Ic remain-on-exit -window option). -If -.Ar shell-command -is not given, the command used when the pane was created is executed. -The pane must be already inactive, unless -.Fl k -is given, in which case any existing command is killed. -.It Xo Ic respawn-window -.Op Fl k -.Op Fl t Ar target-window -.Op Ar shell-command -.Xc -.D1 (alias: Ic respawnw ) -Reactivate a window in which the command has exited (see the -.Ic remain-on-exit -window option). -If -.Ar shell-command -is not given, the command used when the window was created is executed. -The window must be already inactive, unless -.Fl k -is given, in which case any existing command is killed. -.It Xo Ic rotate-window -.Op Fl DU -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic rotatew ) -Rotate the positions of the panes within a window, either upward (numerically -lower) with -.Fl U -or downward (numerically higher). -.It Xo Ic select-layout -.Op Fl np -.Op Fl t Ar target-window -.Op Ar layout-name -.Xc -.D1 (alias: Ic selectl ) -Choose a specific layout for a window. -If -.Ar layout-name -is not given, the last preset layout used (if any) is reapplied. -.Fl n -and -.Fl p -are equivalent to the -.Ic next-layout -and -.Ic previous-layout -commands. -.It Xo Ic select-pane -.Op Fl lDLRU -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic selectp ) -Make pane -.Ar target-pane -the active pane in window -.Ar target-window . -If one of -.Fl D , -.Fl L , -.Fl R , -or -.Fl U -is used, respectively the pane below, to the left, to the right, or above the -target pane is used. -.Fl l -is the same as using the -.Ic last-pane -command. -.It Xo Ic select-window -.Op Fl lnpT -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic selectw ) -Select the window at -.Ar target-window . -.Fl l , -.Fl n -and -.Fl p -are equivalent to the -.Ic last-window , -.Ic next-window -and -.Ic previous-window -commands. -If -.Fl T -is given and the selected window is already the current window, -the command behaves like -.Ic last-window . -.It Xo Ic split-window -.Op Fl dhvP -.Op Fl c Ar start-directory -.Oo Fl l -.Ar size | -.Fl p Ar percentage Oc -.Op Fl t Ar target-pane -.Op Ar shell-command -.Op Fl F Ar format -.Xc -.D1 (alias: Ic splitw ) -Create a new pane by splitting -.Ar target-pane : -.Fl h -does a horizontal split and -.Fl v -a vertical split; if neither is specified, -.Fl v -is assumed. -The -.Fl l -and -.Fl p -options specify the size of the new pane in lines (for vertical split) or in -cells (for horizontal split), or as a percentage, respectively. -All other options have the same meaning as for the -.Ic new-window -command. -.It Xo Ic swap-pane -.Op Fl dDU -.Op Fl s Ar src-pane -.Op Fl t Ar dst-pane -.Xc -.D1 (alias: Ic swapp ) -Swap two panes. -If -.Fl U -is used and no source pane is specified with -.Fl s , -.Ar dst-pane -is swapped with the previous pane (before it numerically); -.Fl D -swaps with the next pane (after it numerically). -.Fl d -instructs -.Nm -not to change the active pane. -.It Xo Ic swap-window -.Op Fl d -.Op Fl s Ar src-window -.Op Fl t Ar dst-window -.Xc -.D1 (alias: Ic swapw ) -This is similar to -.Ic link-window , -except the source and destination windows are swapped. -It is an error if no window exists at -.Ar src-window . -.It Xo Ic unlink-window -.Op Fl k -.Op Fl t Ar target-window -.Xc -.D1 (alias: Ic unlinkw ) -Unlink -.Ar target-window . -Unless -.Fl k -is given, a window may be unlinked only if it is linked to multiple sessions - -windows may not be linked to no sessions; -if -.Fl k -is specified and the window is linked to only one session, it is unlinked and -destroyed. -.El -.Sh KEY BINDINGS -.Nm -allows a command to be bound to most keys, with or without a prefix key. -When specifying keys, most represent themselves (for example -.Ql A -to -.Ql Z ) . -Ctrl keys may be prefixed with -.Ql C- -or -.Ql ^ , -and Alt (meta) with -.Ql M- . -In addition, the following special key names are accepted: -.Em Up , -.Em Down , -.Em Left , -.Em Right , -.Em BSpace , -.Em BTab , -.Em DC -(Delete), -.Em End , -.Em Enter , -.Em Escape , -.Em F1 -to -.Em F20 , -.Em Home , -.Em IC -(Insert), -.Em NPage/PageDown/PgDn , -.Em PPage/PageUp/PgUp , -.Em Space , -and -.Em Tab . -Note that to bind the -.Ql \&" -or -.Ql ' -keys, quotation marks are necessary, for example: -.Bd -literal -offset indent -bind-key '"' split-window -bind-key "'" new-window -.Ed -.Pp -Commands related to key bindings are as follows: -.Bl -tag -width Ds -.It Xo Ic bind-key -.Op Fl cnr -.Op Fl t Ar key-table -.Ar key Ar command Op Ar arguments -.Xc -.D1 (alias: Ic bind ) -Bind key -.Ar key -to -.Ar command . -By default (without -.Fl t ) -the primary key bindings are modified (those normally activated with the prefix -key); in this case, if -.Fl n -is specified, it is not necessary to use the prefix key, -.Ar command -is bound to -.Ar key -alone. -The -.Fl r -flag indicates this key may repeat, see the -.Ic repeat-time -option. -.Pp -If -.Fl t -is present, -.Ar key -is bound in -.Ar key-table : -the binding for command mode with -.Fl c -or for normal mode without. -To view the default bindings and possible commands, see the -.Ic list-keys -command. -.It Ic list-keys Op Fl t Ar key-table -.D1 (alias: Ic lsk ) -List all key bindings. -Without -.Fl t -the primary key bindings - those executed when preceded by the prefix key - -are printed. -.Pp -With -.Fl t , -the key bindings in -.Ar key-table -are listed; this may be one of: -.Em vi-edit , -.Em emacs-edit , -.Em vi-choice , -.Em emacs-choice , -.Em vi-copy -or -.Em emacs-copy . -.It Xo Ic send-keys -.Op Fl lR -.Op Fl t Ar target-pane -.Ar key Ar ... -.Xc -.D1 (alias: Ic send ) -Send a key or keys to a window. -Each argument -.Ar key -is the name of the key (such as -.Ql C-a -or -.Ql npage -) to send; if the string is not recognised as a key, it is sent as a series of -characters. -The -.Fl l -flag disables key name lookup and sends the keys literally. -All arguments are sent sequentially from first to last. -The -.Fl R -flag causes the terminal state to be reset. -.It Xo Ic send-prefix -.Op Fl 2 -.Op Fl t Ar target-pane -.Xc -Send the prefix key, or with -.Fl 2 -the secondary prefix key, to a window as if it was pressed. -.It Xo Ic unbind-key -.Op Fl acn -.Op Fl t Ar key-table -.Ar key -.Xc -.D1 (alias: Ic unbind ) -Unbind the command bound to -.Ar key . -Without -.Fl t -the primary key bindings are modified; in this case, if -.Fl n -is specified, the command bound to -.Ar key -without a prefix (if any) is removed. -If -.Fl a -is present, all key bindings are removed. -.Pp -If -.Fl t -is present, -.Ar key -in -.Ar key-table -is unbound: the binding for command mode with -.Fl c -or for normal mode without. -.El -.Sh OPTIONS -The appearance and behaviour of -.Nm -may be modified by changing the value of various options. -There are three types of option: -.Em server options , -.Em session options -and -.Em window options . -.Pp -The -.Nm -server has a set of global options which do not apply to any particular -window or session. -These are altered with the -.Ic set-option -.Fl s -command, or displayed with the -.Ic show-options -.Fl s -command. -.Pp -In addition, each individual session may have a set of session options, and -there is a separate set of global session options. -Sessions which do not have a particular option configured inherit the value -from the global session options. -Session options are set or unset with the -.Ic set-option -command and may be listed with the -.Ic show-options -command. -The available server and session options are listed under the -.Ic set-option -command. -.Pp -Similarly, a set of window options is attached to each window, and there is -a set of global window options from which any unset options are inherited. -Window options are altered with the -.Ic set-window-option -command and can be listed with the -.Ic show-window-options -command. -All window options are documented with the -.Ic set-window-option -command. -.Pp -.Nm -also supports user options which are prefixed with a -.Ql \&@ . -User options may have any name, so long as they are prefixed with -.Ql \&@ , -and be set to any string. -For example -.Bd -literal -offset indent -$ tmux setw -q @foo "abc123" -$ tmux showw -v @foo -abc123 -.Ed -.Pp -Commands which set options are as follows: -.Bl -tag -width Ds -.It Xo Ic set-option -.Op Fl agoqsuw -.Op Fl t Ar target-session | Ar target-window -.Ar option Ar value -.Xc -.D1 (alias: Ic set ) -Set a window option with -.Fl w -(equivalent to the -.Ic set-window-option -command), -a server option with -.Fl s , -otherwise a session option. -.Pp -If -.Fl g -is specified, the global session or window option is set. -With -.Fl a , -and if the option expects a string, -.Ar value -is appended to the existing setting. -The -.Fl u -flag unsets an option, so a session inherits the option from the global -options. -It is not possible to unset a global option. -.Pp -The -.Fl o -flag prevents setting an option that is already set. -.Pp -The -.Fl q -flag suppresses the informational message (as if the -.Ic quiet -server option was set). -.Pp -Available window options are listed under -.Ic set-window-option . -.Pp -.Ar value -depends on the option and may be a number, a string, or a flag (on, off, or -omitted to toggle). -.Pp -Available server options are: -.Bl -tag -width Ds -.It Ic buffer-limit Ar number -Set the number of buffers; as new buffers are added to the top of the stack, -old ones are removed from the bottom if necessary to maintain this maximum -length. -.It Ic escape-time Ar time -Set the time in milliseconds for which -.Nm -waits after an escape is input to determine if it is part of a function or meta -key sequences. -The default is 500 milliseconds. -.It Xo Ic exit-unattached -.Op Ic on | off -.Xc -If enabled, the server will exit when there are no attached clients. -.It Xo Ic quiet -.Op Ic on | off -.Xc -Enable or disable the display of various informational messages (see also the -.Fl q -command line flag). -.It Xo Ic set-clipboard -.Op Ic on | off -.Xc -Attempt to set the terminal clipboard content using the -\ee]52;...\e007 -.Xr xterm 1 -escape sequences. -This option is on by default if there is an -.Em \&Ms -entry in the -.Xr terminfo 5 -description for the client terminal. -Note that this feature needs to be enabled in -.Xr xterm 1 -by setting the resource: -.Bd -literal -offset indent -disallowedWindowOps: 20,21,SetXprop -.Ed -.Pp -Or changing this property from the -.Xr xterm 1 -interactive menu when required. -.El -.Pp -Available session options are: -.Bl -tag -width Ds -.It Ic assume-paste-time Ar milliseconds -If keys are entered faster than one in -.Ar milliseconds , -they are assumed to have been pasted rather than typed and -.Nm -key bindings are not processed. -The default is one millisecond and zero disables. -.It Ic base-index Ar index -Set the base index from which an unused index should be searched when a new -window is created. -The default is zero. -.It Xo Ic bell-action -.Op Ic any | none | current -.Xc -Set action on window bell. -.Ic any -means a bell in any window linked to a session causes a bell in the current -window of that session, -.Ic none -means all bells are ignored and -.Ic current -means only bells in windows other than the current window are ignored. -.It Xo Ic bell-on-alert -.Op Ic on | off -.Xc -If on, ring the terminal bell when an alert -occurs. -.It Ic default-command Ar shell-command -Set the command used for new windows (if not specified when the window is -created) to -.Ar shell-command , -which may be any -.Xr sh 1 -command. -The default is an empty string, which instructs -.Nm -to create a login shell using the value of the -.Ic default-shell -option. -.It Ic default-path Ar path -Set the default working directory for new panes. -If empty (the default), the working directory is determined from the process -running in the active pane, from the command line environment or from the -working directory where the session was created. -Otherwise the same options are available as for the -.Fl c -flag to -.Ic new-window . -.It Ic default-shell Ar path -Specify the default shell. -This is used as the login shell for new windows when the -.Ic default-command -option is set to empty, and must be the full path of the executable. -When started -.Nm -tries to set a default value from the first suitable of the -.Ev SHELL -environment variable, the shell returned by -.Xr getpwuid 3 , -or -.Pa /bin/sh . -This option should be configured when -.Nm -is used as a login shell. -.It Ic default-terminal Ar terminal -Set the default terminal for new windows created in this session - the -default value of the -.Ev TERM -environment variable. -For -.Nm -to work correctly, this -.Em must -be set to -.Ql screen -or a derivative of it. -.It Xo Ic destroy-unattached -.Op Ic on | off -.Xc -If enabled and the session is no longer attached to any clients, it is -destroyed. -.It Xo Ic detach-on-destroy -.Op Ic on | off -.Xc -If on (the default), the client is detached when the session it is attached to -is destroyed. -If off, the client is switched to the most recently active of the remaining -sessions. -.It Ic display-panes-active-colour Ar colour -Set the colour used by the -.Ic display-panes -command to show the indicator for the active pane. -.It Ic display-panes-colour Ar colour -Set the colour used by the -.Ic display-panes -command to show the indicators for inactive panes. -.It Ic display-panes-time Ar time -Set the time in milliseconds for which the indicators shown by the -.Ic display-panes -command appear. -.It Ic display-time Ar time -Set the amount of time for which status line messages and other on-screen -indicators are displayed. -.Ar time -is in milliseconds. -.It Ic history-limit Ar lines -Set the maximum number of lines held in window history. -This setting applies only to new windows - existing window histories are not -resized and retain the limit at the point they were created. -.It Ic lock-after-time Ar number -Lock the session (like the -.Ic lock-session -command) after -.Ar number -seconds of inactivity, or the entire server (all sessions) if the -.Ic lock-server -option is set. -The default is not to lock (set to 0). -.It Ic lock-command Ar shell-command -Command to run when locking each client. -The default is to run -.Xr lock 1 -with -.Fl np . -.It Xo Ic lock-server -.Op Ic on | off -.Xc -If this option is -.Ic on -(the default), -instead of each session locking individually as each has been -idle for -.Ic lock-after-time , -the entire server will lock after -.Em all -sessions would have locked. -This has no effect as a session option; it must be set as a global option. -.It Ic message-attr Ar attributes -Set status line message attributes, where -.Ar attributes -is either -.Ic none -or a comma-delimited list of one or more of: -.Ic bright -(or -.Ic bold ) , -.Ic dim , -.Ic underscore , -.Ic blink , -.Ic reverse , -.Ic hidden , -or -.Ic italics . -.It Ic message-bg Ar colour -Set status line message background colour, where -.Ar colour -is one of: -.Ic black , -.Ic red , -.Ic green , -.Ic yellow , -.Ic blue , -.Ic magenta , -.Ic cyan , -.Ic white , -aixterm bright variants (if supported: -.Ic brightred , -.Ic brightgreen , -and so on), -.Ic colour0 -to -.Ic colour255 -from the 256-colour set, -.Ic default , -or a hexadecimal RGB string such as -.Ql #ffffff , -which chooses the closest match from the default 256-colour set. -.It Ic message-command-attr Ar attributes -Set status line message attributes when in command mode. -.It Ic message-command-bg Ar colour -Set status line message background colour when in command mode. -.It Ic message-command-fg Ar colour -Set status line message foreground colour when in command mode. -.It Ic message-fg Ar colour -Set status line message foreground colour. -.It Ic message-limit Ar number -Set the number of error or information messages to save in the message log for -each client. -The default is 20. -.It Xo Ic mouse-resize-pane -.Op Ic on | off -.Xc -If on, -.Nm -captures the mouse and allows panes to be resized by dragging on their borders. -.It Xo Ic mouse-select-pane -.Op Ic on | off -.Xc -If on, -.Nm -captures the mouse and when a window is split into multiple panes the mouse may -be used to select the current pane. -The mouse click is also passed through to the application as normal. -.It Xo Ic mouse-select-window -.Op Ic on | off -.Xc -If on, clicking the mouse on a window name in the status line will select that -window. -.It Xo Ic mouse-utf8 -.Op Ic on | off -.Xc -If enabled, request mouse input as UTF-8 on UTF-8 terminals. -.It Ic pane-active-border-bg Ar colour -.It Ic pane-active-border-fg Ar colour -Set the pane border colour for the currently active pane. -.It Ic pane-border-bg Ar colour -.It Ic pane-border-fg Ar colour -Set the pane border colour for panes aside from the active pane. -.It Ic prefix Ar key -Set the key accepted as a prefix key. -.It Ic prefix2 Ar key -Set a secondary key accepted as a prefix key. -.It Xo Ic renumber-windows -.Op Ic on | off -.Xc -If on, when a window is closed in a session, automatically renumber the other -windows in numerical order. -This respects the -.Ic base-index -option if it has been set. -If off, do not renumber the windows. -.It Ic repeat-time Ar time -Allow multiple commands to be entered without pressing the prefix-key again -in the specified -.Ar time -milliseconds (the default is 500). -Whether a key repeats may be set when it is bound using the -.Fl r -flag to -.Ic bind-key . -Repeat is enabled for the default keys bound to the -.Ic resize-pane -command. -.It Xo Ic set-remain-on-exit -.Op Ic on | off -.Xc -Set the -.Ic remain-on-exit -window option for any windows first created in this session. -When this option is true, windows in which the running program has -exited do not close, instead remaining open but inactivate. -Use the -.Ic respawn-window -command to reactivate such a window, or the -.Ic kill-window -command to destroy it. -.It Xo Ic set-titles -.Op Ic on | off -.Xc -Attempt to set the client terminal title using the -.Em tsl -and -.Em fsl -.Xr terminfo 5 -entries if they exist. -.Nm -automatically sets these to the \ee]2;...\e007 sequence if -the terminal appears to be an xterm. -This option is off by default. -Note that elinks -will only attempt to set the window title if the STY environment -variable is set. -.It Ic set-titles-string Ar string -String used to set the window title if -.Ic set-titles -is on. -Character sequences are replaced as for the -.Ic status-left -option. -.It Xo Ic status -.Op Ic on | off -.Xc -Show or hide the status line. -.It Ic status-attr Ar attributes -Set status line attributes. -.It Ic status-bg Ar colour -Set status line background colour. -.It Ic status-fg Ar colour -Set status line foreground colour. -.It Ic status-interval Ar interval -Update the status bar every -.Ar interval -seconds. -By default, updates will occur every 15 seconds. -A setting of zero disables redrawing at interval. -.It Xo Ic status-justify -.Op Ic left | centre | right -.Xc -Set the position of the window list component of the status line: left, centre -or right justified. -.It Xo Ic status-keys -.Op Ic vi | emacs -.Xc -Use vi or emacs-style -key bindings in the status line, for example at the command prompt. -The default is emacs, unless the -.Ev VISUAL -or -.Ev EDITOR -environment variables are set and contain the string -.Ql vi . -.It Ic status-left Ar string -Display -.Ar string -to the left of the status bar. -.Ar string -will be passed through -.Xr strftime 3 -before being used. -By default, the session name is shown. -.Ar string -may contain any of the following special character sequences: -.Bl -column "Character pair" "Replaced with" -offset indent -.It Sy "Character pair" Ta Sy "Replaced with" -.It Li "#(shell-command)" Ta "First line of the command's output" -.It Li "#[attributes]" Ta "Colour or attribute change" -.It Li "#H" Ta "Hostname of local host" -.It Li "#h" Ta "Hostname of local host without the domain name" -.It Li "#F" Ta "Current window flag" -.It Li "#I" Ta "Current window index" -.It Li "#D" Ta "Current pane unique identifier" -.It Li "#P" Ta "Current pane index" -.It Li "#S" Ta "Session name" -.It Li "#T" Ta "Current pane title" -.It Li "#W" Ta "Current window name" -.It Li "##" Ta "A literal" Ql # -.El -.Pp -The #(shell-command) form executes -.Ql shell-command -and inserts the first line of its output. -Note that shell commands are only executed once at the interval specified by -the -.Ic status-interval -option: if the status line is redrawn in the meantime, the previous result is -used. -Shell commands are executed with the -.Nm -global environment set (see the -.Sx ENVIRONMENT -section). -.Pp -For details on how the names and titles can be set see the -.Sx "NAMES AND TITLES" -section. -.Pp -#[attributes] allows a comma-separated list of attributes to be specified, -these may be -.Ql fg=colour -to set the foreground colour, -.Ql bg=colour -to set the background colour, the name of one of the attributes (listed under -the -.Ic message-attr -option) to turn an attribute on, or an attribute prefixed with -.Ql no -to turn one off, for example -.Ic nobright . -Examples are: -.Bd -literal -offset indent -#(sysctl vm.loadavg) -#[fg=yellow,bold]#(apm -l)%%#[default] [#S] -.Ed -.Pp -Where appropriate, special character sequences may be prefixed with a number to -specify the maximum length, for example -.Ql #24T . -.Pp -By default, UTF-8 in -.Ar string -is not interpreted, to enable UTF-8, use the -.Ic status-utf8 -option. -.It Ic status-left-attr Ar attributes -Set the attribute of the left part of the status line. -.It Ic status-left-bg Ar colour -Set the background colour of the left part of the status line. -.It Ic status-left-fg Ar colour -Set the foreground colour of the left part of the status line. -.It Ic status-left-length Ar length -Set the maximum -.Ar length -of the left component of the status bar. -The default is 10. -.It Xo Ic status-position -.Op Ic top | bottom -.Xc -Set the position of the status line. -.It Ic status-right Ar string -Display -.Ar string -to the right of the status bar. -By default, the current window title in double quotes, the date and the time -are shown. -As with -.Ic status-left , -.Ar string -will be passed to -.Xr strftime 3 , -character pairs are replaced, and UTF-8 is dependent on the -.Ic status-utf8 -option. -.It Ic status-right-attr Ar attributes -Set the attribute of the right part of the status line. -.It Ic status-right-bg Ar colour -Set the background colour of the right part of the status line. -.It Ic status-right-fg Ar colour -Set the foreground colour of the right part of the status line. -.It Ic status-right-length Ar length -Set the maximum -.Ar length -of the right component of the status bar. -The default is 40. -.It Xo Ic status-utf8 -.Op Ic on | off -.Xc -Instruct -.Nm -to treat top-bit-set characters in the -.Ic status-left -and -.Ic status-right -strings as UTF-8; notably, this is important for wide characters. -This option defaults to off. -.It Ic terminal-overrides Ar string -Contains a list of entries which override terminal descriptions read using -.Xr terminfo 5 . -.Ar string -is a comma-separated list of items each a colon-separated string made up of a -terminal type pattern (matched using -.Xr fnmatch 3 ) -and a set of -.Em name=value -entries. -.Pp -For example, to set the -.Ql clear -.Xr terminfo 5 -entry to -.Ql \ee[H\ee[2J -for all terminal types and the -.Ql dch1 -entry to -.Ql \ee[P -for the -.Ql rxvt -terminal type, the option could be set to the string: -.Bd -literal -offset indent -"*:clear=\ee[H\ee[2J,rxvt:dch1=\ee[P" -.Ed -.Pp -The terminal entry value is passed through -.Xr strunvis 3 -before interpretation. -The default value forcibly corrects the -.Ql colors -entry for terminals which support 88 or 256 colours: -.Bd -literal -offset indent -"*88col*:colors=88,*256col*:colors=256,xterm*:XT" -.Ed -.It Ic update-environment Ar variables -Set a space-separated string containing a list of environment variables to be -copied into the session environment when a new session is created or an -existing session is attached. -Any variables that do not exist in the source environment are set to be -removed from the session environment (as if -.Fl r -was given to the -.Ic set-environment -command). -The default is -"DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID -XAUTHORITY". -.It Xo Ic visual-activity -.Op Ic on | off -.Xc -If on, display a status line message when activity occurs in a window -for which the -.Ic monitor-activity -window option is enabled. -.It Xo Ic visual-bell -.Op Ic on | off -.Xc -If this option is on, a message is shown on a bell instead of it being passed -through to the terminal (which normally makes a sound). -Also see the -.Ic bell-action -option. -.It Xo Ic visual-content -.Op Ic on | off -.Xc -Like -.Ic visual-activity , -display a message when content is present in a window -for which the -.Ic monitor-content -window option is enabled. -.It Xo Ic visual-silence -.Op Ic on | off -.Xc -If -.Ic monitor-silence -is enabled, prints a message after the interval has expired on a given window. -.It Ic word-separators Ar string -Sets the session's conception of what characters are considered word -separators, for the purposes of the next and previous word commands in -copy mode. -The default is -.Ql \ -_@ . -.El -.It Xo Ic set-window-option -.Op Fl agoqu -.Op Fl t Ar target-window -.Ar option Ar value -.Xc -.D1 (alias: Ic setw ) -Set a window option. -The -.Fl a , -.Fl g , -.Fl o , -.Fl q -and -.Fl u -flags work similarly to the -.Ic set-option -command. -.Pp -Supported window options are: -.Pp -.Bl -tag -width Ds -compact -.It Xo Ic aggressive-resize -.Op Ic on | off -.Xc -Aggressively resize the chosen window. -This means that -.Nm -will resize the window to the size of the smallest session for which it is the -current window, rather than the smallest session to which it is attached. -The window may resize when the current window is changed on another sessions; -this option is good for full-screen programs which support -.Dv SIGWINCH -and poor for interactive programs such as shells. -.Pp -.It Xo Ic allow-rename -.Op Ic on | off -.Xc -Allow programs to change the window name using a terminal escape -sequence (\\033k...\\033\\\\). -The default is on. -.Pp -.It Xo Ic alternate-screen -.Op Ic on | off -.Xc -This option configures whether programs running inside -.Nm -may use the terminal alternate screen feature, which allows the -.Em smcup -and -.Em rmcup -.Xr terminfo 5 -capabilities. -The alternate screen feature preserves the contents of the window when an -interactive application starts and restores it on exit, so that any output -visible before the application starts reappears unchanged after it exits. -The default is on. -.Pp -.It Xo Ic automatic-rename -.Op Ic on | off -.Xc -Control automatic window renaming. -When this setting is enabled, -.Nm -will attempt - on supported platforms - to rename the window to reflect the -command currently running in it. -This flag is automatically disabled for an individual window when a name -is specified at creation with -.Ic new-window -or -.Ic new-session , -or later with -.Ic rename-window , -or with a terminal escape sequence. -It may be switched off globally with: -.Bd -literal -offset indent -set-window-option -g automatic-rename off -.Ed -.Pp -.It Ic c0-change-interval Ar interval -.It Ic c0-change-trigger Ar trigger -These two options configure a simple form of rate limiting for a pane. -If -.Nm -sees more than -.Ar trigger -C0 sequences that modify the screen (for example, carriage returns, linefeeds -or backspaces) in one millisecond, it will stop updating the pane immediately and -instead redraw it entirely every -.Ar interval -milliseconds. -This helps to prevent fast output (such as -.Xr yes 1 -overwhelming the terminal). -The default is a trigger of 250 and an interval of 100. -A trigger of zero disables the rate limiting. -.Pp -.It Ic clock-mode-colour Ar colour -Set clock colour. -.Pp -.It Xo Ic clock-mode-style -.Op Ic 12 | 24 -.Xc -Set clock hour format. -.Pp -.It Ic force-height Ar height -.It Ic force-width Ar width -Prevent -.Nm -from resizing a window to greater than -.Ar width -or -.Ar height . -A value of zero restores the default unlimited setting. -.Pp -.It Ic main-pane-height Ar height -.It Ic main-pane-width Ar width -Set the width or height of the main (left or top) pane in the -.Ic main-horizontal -or -.Ic main-vertical -layouts. -.Pp -.It Ic mode-attr Ar attributes -Set window modes attributes. -.Pp -.It Ic mode-bg Ar colour -Set window modes background colour. -.Pp -.It Ic mode-fg Ar colour -Set window modes foreground colour. -.Pp -.It Xo Ic mode-keys -.Op Ic vi | emacs -.Xc -Use vi or emacs-style key bindings in copy and choice modes. -As with the -.Ic status-keys -option, the default is emacs, unless -.Ev VISUAL -or -.Ev EDITOR -contains -.Ql vi . -.Pp -.It Xo Ic mode-mouse -.Op Ic on | off | copy-mode -.Xc -Mouse state in modes. -If on, the mouse may be used to enter copy mode and copy a selection by -dragging, to enter copy mode and scroll with the mouse wheel, or to select an -option in choice mode. -If set to -.Em copy-mode , -the mouse behaves as set to on, but cannot be used to enter copy -mode. -.Pp -.It Xo Ic monitor-activity -.Op Ic on | off -.Xc -Monitor for activity in the window. -Windows with activity are highlighted in the status line. -.Pp -.It Ic monitor-content Ar match-string -Monitor content in the window. -When -.Xr fnmatch 3 -pattern -.Ar match-string -appears in the window, it is highlighted in the status line. -.Pp -.It Xo Ic monitor-silence -.Op Ic interval -.Xc -Monitor for silence (no activity) in the window within -.Ic interval -seconds. -Windows that have been silent for the interval are highlighted in the -status line. -An interval of zero disables the monitoring. -.Pp -.It Ic other-pane-height Ar height -Set the height of the other panes (not the main pane) in the -.Ic main-horizontal -layout. -If this option is set to 0 (the default), it will have no effect. -If both the -.Ic main-pane-height -and -.Ic other-pane-height -options are set, the main pane will grow taller to make the other panes the -specified height, but will never shrink to do so. -.Pp -.It Ic other-pane-width Ar width -Like -.Ic other-pane-height , -but set the width of other panes in the -.Ic main-vertical -layout. -.Pp -.It Ic pane-base-index Ar index -Like -.Ic base-index , -but set the starting index for pane numbers. -.Pp -.It Xo Ic remain-on-exit -.Op Ic on | off -.Xc -A window with this flag set is not destroyed when the program running in it -exits. -The window may be reactivated with the -.Ic respawn-window -command. -.Pp -.It Xo Ic synchronize-panes -.Op Ic on | off -.Xc -Duplicate input to any pane to all other panes in the same window (only -for panes that are not in any special mode). -.Pp -.It Xo Ic utf8 -.Op Ic on | off -.Xc -Instructs -.Nm -to expect UTF-8 sequences to appear in this window. -.Pp -.It Ic window-status-bell-attr Ar attributes -Set status line attributes for windows which have a bell alert. -.Pp -.It Ic window-status-bell-bg Ar colour -Set status line background colour for windows with a bell alert. -.Pp -.It Ic window-status-bell-fg Ar colour -Set status line foreground colour for windows with a bell alert. -.Pp -.It Ic window-status-content-attr Ar attributes -Set status line attributes for windows which have a content alert. -.Pp -.It Ic window-status-content-bg Ar colour -Set status line background colour for windows with a content alert. -.Pp -.It Ic window-status-content-fg Ar colour -Set status line foreground colour for windows with a content alert. -.Pp -.It Ic window-status-activity-attr Ar attributes -Set status line attributes for windows which have an activity (or silence) alert. -.Pp -.It Ic window-status-activity-bg Ar colour -Set status line background colour for windows with an activity alert. -.Pp -.It Ic window-status-activity-fg Ar colour -Set status line foreground colour for windows with an activity alert. -.Pp -.It Ic window-status-attr Ar attributes -Set status line attributes for a single window. -.Pp -.It Ic window-status-bg Ar colour -Set status line background colour for a single window. -.Pp -.It Ic window-status-current-attr Ar attributes -Set status line attributes for the currently active window. -.Pp -.It Ic window-status-current-bg Ar colour -Set status line background colour for the currently active window. -.Pp -.It Ic window-status-current-fg Ar colour -Set status line foreground colour for the currently active window. -.Pp -.It Ic window-status-current-format Ar string -Like -.Ar window-status-format , -but is the format used when the window is the current window. -.Pp -.It Ic window-status-last-attr Ar attributes -Set status line attributes for the last active window. -.Pp -.It Ic window-status-last-bg Ar colour -Set status line background colour for the last active window. -.Pp -.It Ic window-status-last-fg Ar colour -Set status line foreground colour for the last active window. -.Pp -.It Ic window-status-fg Ar colour -Set status line foreground colour for a single window. -.Pp -.It Ic window-status-format Ar string -Set the format in which the window is displayed in the status line window list. -See the -.Ar status-left -option for details of special character sequences available. -The default is -.Ql #I:#W#F . -.Pp -.It Ic window-status-separator Ar string -Sets the separator drawn between windows in the status line. -The default is a single space character. -.Pp -.It Xo Ic xterm-keys -.Op Ic on | off -.Xc -If this option is set, -.Nm -will generate -.Xr xterm 1 -style -function key sequences; these have a number included to indicate modifiers such -as Shift, Alt or Ctrl. -The default is off. -.Pp -.It Xo Ic wrap-search -.Op Ic on | off -.Xc -If this option is set, searches will wrap around the end of the pane contents. -The default is on. -.El -.It Xo Ic show-options -.Op Fl gqsvw -.Op Fl t Ar target-session | Ar target-window -.Op Ar option -.Xc -.D1 (alias: Ic show ) -Show the window options (or a single window option if given) with -.Fl w -(equivalent to -.Ic show-window-options ) , -the server options with -.Fl s , -otherwise the session options for -.Ar target session . -Global session or window options are listed if -.Fl g -is used. -.Fl v -shows only the option value, not the name. -If -.Fl q -is set, no error will be returned if -.Ar option -is unset. -.It Xo Ic show-window-options -.Op Fl gv -.Op Fl t Ar target-window -.Op Ar option -.Xc -.D1 (alias: Ic showw ) -List the window options or a single option for -.Ar target-window , -or the global window options if -.Fl g -is used. -.Fl v -shows only the option value, not the name. -.El -.Sh FORMATS -Certain commands accept the -.Fl F -flag with a -.Ar format -argument. -This is a string which controls the output format of the command. -Special character sequences are replaced as documented under the -.Ic status-left -option and an additional long form is accepted. -Replacement variables are enclosed in -.Ql #{ -and -.Ql } , -for example -.Ql #{session_name} -is equivalent to -.Ql #S . -Conditionals are also accepted by prefixing with -.Ql \&? -and separating two alternatives with a comma; -if the specified variable exists and is not zero, the first alternative -is chosen, otherwise the second is used. -For example -.Ql #{?session_attached,attached,not attached} -will include the string -.Ql attached -if the session is attached and the string -.Ql not attached -if it is unattached. -.Pp -The following variables are available, where appropriate: -.Bl -column "session_created_string" "Replaced with" -offset indent -.It Sy "Variable name" Ta Sy "Replaced with" -.It Li "alternate_on" Ta "If pane is in alternate screen" -.It Li "alternate_saved_x" Ta "Saved cursor X in alternate screen" -.It Li "alternate_saved_y" Ta "Saved cursor Y in alternate screen" -.It Li "buffer_sample" Ta "First 50 characters from the specified buffer" -.It Li "buffer_size" Ta "Size of the specified buffer in bytes" -.It Li "client_activity" Ta "Integer time client last had activity" -.It Li "client_activity_string" Ta "String time client last had activity" -.It Li "client_created" Ta "Integer time client created" -.It Li "client_created_string" Ta "String time client created" -.It Li "client_cwd" Ta "Working directory of client" -.It Li "client_height" Ta "Height of client" -.It Li "client_last_session" Ta "Name of the client's last session" -.It Li "client_prefix" Ta "1 if prefix key has been pressed" -.It Li "client_readonly" Ta "1 if client is readonly" -.It Li "client_session" Ta "Name of the client's session" -.It Li "client_termname" Ta "Terminal name of client" -.It Li "client_tty" Ta "Pseudo terminal of client" -.It Li "client_utf8" Ta "1 if client supports utf8" -.It Li "client_width" Ta "Width of client" -.It Li "cursor_flag" Ta "Pane cursor flag" -.It Li "cursor_x" Ta "Cursor X position in pane" -.It Li "cursor_y" Ta "Cursor Y position in pane" -.It Li "history_bytes" Ta "Number of bytes in window history" -.It Li "history_limit" Ta "Maximum window history lines" -.It Li "history_size" Ta "Size of history in bytes" -.It Li "host" Ta "Hostname of local host" -.It Li "insert_flag" Ta "Pane insert flag" -.It Li "keypad_cursor_flag" Ta "Pane keypad cursor flag" -.It Li "keypad_flag" Ta "Pane keypad flag" -.It Li "line" Ta "Line number in the list" -.It Li "mouse_any_flag" Ta "Pane mouse any flag" -.It Li "mouse_button_flag" Ta "Pane mouse button flag" -.It Li "mouse_standard_flag" Ta "Pane mouse standard flag" -.It Li "mouse_utf8_flag" Ta "Pane mouse UTF-8 flag" -.It Li "pane_active" Ta "1 if active pane" -.It Li "pane_current_command" Ta "Current command if available" -.It Li "pane_current_path" Ta "Current path if available" -.It Li "pane_dead" Ta "1 if pane is dead" -.It Li "pane_height" Ta "Height of pane" -.It Li "pane_id" Ta "Unique pane ID" -.It Li "pane_in_mode" Ta "If pane is in a mode" -.It Li "pane_index" Ta "Index of pane" -.It Li "pane_pid" Ta "PID of first process in pane" -.It Li "pane_start_command" Ta "Command pane started with" -.It Li "pane_start_path" Ta "Path pane started with" -.It Li "pane_tabs" Ta "Pane tab positions" -.It Li "pane_title" Ta "Title of pane" -.It Li "pane_tty" Ta "Pseudo terminal of pane" -.It Li "pane_width" Ta "Width of pane" -.It Li "saved_cursor_x" Ta "Saved cursor X in pane" -.It Li "saved_cursor_y" Ta "Saved cursor Y in pane" -.It Li "scroll_region_lower" Ta "Bottom of scroll region in pane" -.It Li "scroll_region_upper" Ta "Top of scroll region in pane" -.It Li "session_attached" Ta "1 if session attached" -.It Li "session_created" Ta "Integer time session created" -.It Li "session_created_string" Ta "String time session created" -.It Li "session_group" Ta "Number of session group" -.It Li "session_grouped" Ta "1 if session in a group" -.It Li "session_height" Ta "Height of session" -.It Li "session_id" Ta "Unique session ID" -.It Li "session_name" Ta "Name of session" -.It Li "session_width" Ta "Width of session" -.It Li "session_windows" Ta "Number of windows in session" -.It Li "window_active" Ta "1 if window active" -.It Li "window_find_matches" Ta "Matched data from the find-window command if available" -.It Li "window_flags" Ta "Window flags" -.It Li "window_height" Ta "Height of window" -.It Li "window_id" Ta "Unique window ID" -.It Li "window_index" Ta "Index of window" -.It Li "window_layout" Ta "Window layout description" -.It Li "window_name" Ta "Name of window" -.It Li "window_panes" Ta "Number of panes in window" -.It Li "window_width" Ta "Width of window" -.It Li "wrap_flag" Ta "Pane wrap flag" -.El -.Sh NAMES AND TITLES -.Nm -distinguishes between names and titles. -Windows and sessions have names, which may be used to specify them in targets -and are displayed in the status line and various lists: the name is the -.Nm -identifier for a window or session. -Only panes have titles. -A pane's title is typically set by the program running inside the pane and -is not modified by -.Nm . -It is the same mechanism used to set for example the -.Xr xterm 1 -window title in an -.Xr X 7 -window manager. -Windows themselves do not have titles - a window's title is the title of its -active pane. -.Nm -itself may set the title of the terminal in which the client is running, see -the -.Ic set-titles -option. -.Pp -A session's name is set with the -.Ic new-session -and -.Ic rename-session -commands. -A window's name is set with one of: -.Bl -enum -width Ds -.It -A command argument (such as -.Fl n -for -.Ic new-window -or -.Ic new-session ) . -.It -An escape sequence: -.Bd -literal -offset indent -$ printf '\e033kWINDOW_NAME\e033\e\e' -.Ed -.It -Automatic renaming, which sets the name to the active command in the window's -active pane. -See the -.Ic automatic-rename -option. -.El -.Pp -When a pane is first created, its title is the hostname. -A pane's title can be set via the OSC title setting sequence, for example: -.Bd -literal -offset indent -$ printf '\e033]2;My Title\e033\e\e' -.Ed -.Sh ENVIRONMENT -When the server is started, -.Nm -copies the environment into the -.Em global environment ; -in addition, each session has a -.Em session environment . -When a window is created, the session and global environments are merged. -If a variable exists in both, the value from the session environment is used. -The result is the initial environment passed to the new process. -.Pp -The -.Ic update-environment -session option may be used to update the session environment from the client -when a new session is created or an old reattached. -.Nm -also initialises the -.Ev TMUX -variable with some internal information to allow commands to be executed -from inside, and the -.Ev TERM -variable with the correct terminal setting of -.Ql screen . -.Pp -Commands to alter and view the environment are: -.Bl -tag -width Ds -.It Xo Ic set-environment -.Op Fl gru -.Op Fl t Ar target-session -.Ar name Op Ar value -.Xc -.D1 (alias: Ic setenv ) -Set or unset an environment variable. -If -.Fl g -is used, the change is made in the global environment; otherwise, it is applied -to the session environment for -.Ar target-session . -The -.Fl u -flag unsets a variable. -.Fl r -indicates the variable is to be removed from the environment before starting a -new process. -.It Xo Ic show-environment -.Op Fl g -.Op Fl t Ar target-session -.Op Ar variable -.Xc -.D1 (alias: Ic showenv ) -Display the environment for -.Ar target-session -or the global environment with -.Fl g . -If -.Ar variable -is omitted, all variables are shown. -Variables removed from the environment are prefixed with -.Ql - . -.El -.Sh STATUS LINE -.Nm -includes an optional status line which is displayed in the bottom line of each -terminal. -By default, the status line is enabled (it may be disabled with the -.Ic status -session option) and contains, from left-to-right: the name of the current -session in square brackets; the window list; the title of the active pane -in double quotes; and the time and date. -.Pp -The status line is made of three parts: configurable left and right sections -(which may contain dynamic content such as the time or output from a shell -command, see the -.Ic status-left , -.Ic status-left-length , -.Ic status-right , -and -.Ic status-right-length -options below), and a central window list. -By default, the window list shows the index, name and (if any) flag of the -windows present in the current session in ascending numerical order. -It may be customised with the -.Ar window-status-format -and -.Ar window-status-current-format -options. -The flag is one of the following symbols appended to the window name: -.Bl -column "Symbol" "Meaning" -offset indent -.It Sy "Symbol" Ta Sy "Meaning" -.It Li "*" Ta "Denotes the current window." -.It Li "-" Ta "Marks the last window (previously selected)." -.It Li "#" Ta "Window is monitored and activity has been detected." -.It Li "!" Ta "A bell has occurred in the window." -.It Li "+" Ta "Window is monitored for content and it has appeared." -.It Li "~" Ta "The window has been silent for the monitor-silence interval." -.It Li "Z" Ta "The window's active pane is zoomed." -.El -.Pp -The # symbol relates to the -.Ic monitor-activity -and + to the -.Ic monitor-content -window options. -The window name is printed in inverted colours if an alert (bell, activity or -content) is present. -.Pp -The colour and attributes of the status line may be configured, the entire -status line using the -.Ic status-attr , -.Ic status-fg -and -.Ic status-bg -session options and individual windows using the -.Ic window-status-attr , -.Ic window-status-fg -and -.Ic window-status-bg -window options. -.Pp -The status line is automatically refreshed at interval if it has changed, the -interval may be controlled with the -.Ic status-interval -session option. -.Pp -Commands related to the status line are as follows: -.Bl -tag -width Ds -.It Xo Ic command-prompt -.Op Fl I Ar inputs -.Op Fl p Ar prompts -.Op Fl t Ar target-client -.Op Ar template -.Xc -Open the command prompt in a client. -This may be used from inside -.Nm -to execute commands interactively. -.Pp -If -.Ar template -is specified, it is used as the command. -If present, -.Fl I -is a comma-separated list of the initial text for each prompt. -If -.Fl p -is given, -.Ar prompts -is a comma-separated list of prompts which are displayed in order; otherwise -a single prompt is displayed, constructed from -.Ar template -if it is present, or -.Ql \&: -if not. -.Pp -Both -.Ar inputs -and -.Ar prompts -may contain the special character sequences supported by the -.Ic status-left -option. -.Pp -Before the command is executed, the first occurrence of the string -.Ql %% -and all occurrences of -.Ql %1 -are replaced by the response to the first prompt, the second -.Ql %% -and all -.Ql %2 -are replaced with the response to the second prompt, and so on for further -prompts. -Up to nine prompt responses may be replaced -.Po -.Ql %1 -to -.Ql %9 -.Pc . -.It Xo Ic confirm-before -.Op Fl p Ar prompt -.Op Fl t Ar target-client -.Ar command -.Xc -.D1 (alias: Ic confirm ) -Ask for confirmation before executing -.Ar command . -If -.Fl p -is given, -.Ar prompt -is the prompt to display; otherwise a prompt is constructed from -.Ar command . -It may contain the special character sequences supported by the -.Ic status-left -option. -.Pp -This command works only from inside -.Nm . -.It Xo Ic display-message -.Op Fl p -.Op Fl c Ar target-client -.Op Fl t Ar target-pane -.Op Ar message -.Xc -.D1 (alias: Ic display ) -Display a message. -If -.Fl p -is given, the output is printed to stdout, otherwise it is displayed in the -.Ar target-client -status line. -The format of -.Ar message -is described in the -.Sx FORMATS -section; information is taken from -.Ar target-pane -if -.Fl t -is given, otherwise the active pane for the session attached to -.Ar target-client . -.El -.Sh BUFFERS -.Nm -maintains a stack of -.Em paste buffers . -Up to the value of the -.Ic buffer-limit -option are kept; when a new buffer is added, the buffer at the bottom of the -stack is removed. -Buffers may be added using -.Ic copy-mode -or the -.Ic set-buffer -command, and pasted into a window using the -.Ic paste-buffer -command. -.Pp -A configurable history buffer is also maintained for each window. -By default, up to 2000 lines are kept; this can be altered with the -.Ic history-limit -option (see the -.Ic set-option -command above). -.Pp -The buffer commands are as follows: -.Bl -tag -width Ds -.It Xo -.Ic choose-buffer -.Op Fl F Ar format -.Op Fl t Ar target-window -.Op Ar template -.Xc -Put a window into buffer choice mode, where a buffer may be chosen -interactively from a list. -After a buffer is selected, -.Ql %% -is replaced by the buffer index in -.Ar template -and the result executed as a command. -If -.Ar template -is not given, "paste-buffer -b '%%'" is used. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -This command works only if at least one client is attached. -.It Ic clear-history Op Fl t Ar target-pane -.D1 (alias: Ic clearhist ) -Remove and free the history for the specified pane. -.It Ic delete-buffer Op Fl b Ar buffer-index -.D1 (alias: Ic deleteb ) -Delete the buffer at -.Ar buffer-index , -or the top buffer if not specified. -.It Xo Ic list-buffers -.Op Fl F Ar format -.Xc -.D1 (alias: Ic lsb ) -List the global buffers. -For the meaning of the -.Fl F -flag, see the -.Sx FORMATS -section. -.It Xo Ic load-buffer -.Op Fl b Ar buffer-index -.Ar path -.Xc -.D1 (alias: Ic loadb ) -Load the contents of the specified paste buffer from -.Ar path . -.It Xo Ic paste-buffer -.Op Fl dpr -.Op Fl b Ar buffer-index -.Op Fl s Ar separator -.Op Fl t Ar target-pane -.Xc -.D1 (alias: Ic pasteb ) -Insert the contents of a paste buffer into the specified pane. -If not specified, paste into the current one. -With -.Fl d , -also delete the paste buffer from the stack. -When output, any linefeed (LF) characters in the paste buffer are replaced with -a separator, by default carriage return (CR). -A custom separator may be specified using the -.Fl s -flag. -The -.Fl r -flag means to do no replacement (equivalent to a separator of LF). -If -.Fl p -is specified, paste bracket control codes are inserted around the -buffer if the application has requested bracketed paste mode. -.It Xo Ic save-buffer -.Op Fl a -.Op Fl b Ar buffer-index -.Ar path -.Xc -.D1 (alias: Ic saveb ) -Save the contents of the specified paste buffer to -.Ar path . -The -.Fl a -option appends to rather than overwriting the file. -.It Xo Ic set-buffer -.Op Fl b Ar buffer-index -.Ar data -.Xc -.D1 (alias: Ic setb ) -Set the contents of the specified buffer to -.Ar data . -.It Xo Ic show-buffer -.Op Fl b Ar buffer-index -.Xc -.D1 (alias: Ic showb ) -Display the contents of the specified buffer. -.El -.Sh MISCELLANEOUS -Miscellaneous commands are as follows: -.Bl -tag -width Ds -.It Ic clock-mode Op Fl t Ar target-pane -Display a large clock. -.It Xo Ic if-shell -.Op Fl b -.Op Fl t Ar target-pane -.Ar shell-command command -.Op Ar command -.Xc -.D1 (alias: Ic if ) -Execute the first -.Ar command -if -.Ar shell-command -returns success or the second -.Ar command -otherwise. -Before being executed, shell-command is expanded using the rules specified in the -.Sx FORMATS -section, including those relevant to -.Ar target-pane . -With -.Fl b , -.Ar shell-command -is run in the background. -.It Ic lock-server -.D1 (alias: Ic lock ) -Lock each client individually by running the command specified by the -.Ic lock-command -option. -.It Xo Ic run-shell -.Fl b -.Op Fl t Ar target-pane -.Ar shell-command -.Xc -.D1 (alias: Ic run ) -Execute -.Ar shell-command -in the background without creating a window. -Before being executed, shell-command is expanded using the rules specified in -the -.Sx FORMATS -section. -With -.Fl b , -the command is run in the background. -After it finishes, any output to stdout is displayed in copy mode (in the pane -specified by -.Fl t -or the current pane if omitted). -If the command doesn't return success, the exit status is also displayed. -.It Ic server-info -.D1 (alias: Ic info ) -Show server information and terminal details. -.It Xo Ic wait-for -.Fl LSU -.Ar channel -.Xc -.D1 (alias: Ic wait ) -When used without options, prevents the client from exiting until woken using -.Ic wait-for -.Fl S -with the same channel. -When -.Fl L -is used, the channel is locked and any clients that try to lock the same -channel are made to wait until the channel is unlocked with -.Ic wait-for -.Fl U . -This command only works from outside -.Nm . -.El -.Sh TERMINFO EXTENSIONS -.Nm -understands some extensions to -.Xr terminfo 5 : -.Bl -tag -width Ds -.It Em Cc , Cr -Set the cursor colour. -The first takes a single string argument and is used to set the colour; -the second takes no arguments and restores the default cursor colour. -If set, a sequence such as this may be used -to change the cursor colour from inside -.Nm : -.Bd -literal -offset indent -$ printf '\e033]12;red\e033\e\e' -.Ed -.It Em Cs , Csr -Change the cursor style. -If set, a sequence such as this may be used -to change the cursor to an underline: -.Bd -literal -offset indent -$ printf '\e033[4 q' -.Ed -.Pp -If -.Em Csr -is set, it will be used to reset the cursor style instead -of -.Em Cs . -.It Em \&Ms -This sequence can be used by -.Nm -to store the current buffer in the host terminal's selection (clipboard). -See the -.Em set-clipboard -option above and the -.Xr xterm 1 -man page. -.El -.Sh CONTROL MODE -.Nm -offers a textual interface called -.Em control mode . -This allows applications to communicate with -.Nm -using a simple text-only protocol. -.Pp -In control mode, a client sends -.Nm -commands or command sequences terminated by newlines on standard input. -Each command will produce one block of output on standard output. -An output block consists of a -.Em %begin -line followed by the output (which may be empty). -The output block ends with a -.Em %end -or -.Em %error . -.Em %begin -and matching -.Em %end -or -.Em %error -have two arguments: an integer time (as seconds from epoch) and command number. -For example: -.Bd -literal -offset indent -%begin 1363006971 2 -0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) -%end 1363006971 2 -.Ed -.Pp -In control mode, -.Nm -outputs notifications. -A notification will never occur inside an output block. -.Pp -The following notifications are defined: -.Bl -tag -width Ds -.It Ic %exit Op Ar reason -The -.Nm -client is exiting immediately, either because it is not attached to any session -or an error occurred. -If present, -.Ar reason -describes why the client exited. -.It Ic %layout-change Ar window-id Ar window-layout -The layout of a window with ID -.Ar window-id -changed. -The new layout is -.Ar window-layout . -.It Ic %output Ar pane-id Ar value -A window pane produced output. -.Ar value -escapes non-printable characters and backslash as octal \\xxx. -.It Ic %session-changed Ar session-id Ar name -The client is now attached to the session with ID -.Ar session-id , -which is named -.Ar name . -.It Ic %session-renamed Ar name -The current session was renamed to -.Ar name . -.It Ic %sessions-changed -A session was created or destroyed. -.It Ic %unlinked-window-add Ar window-id -The window with ID -.Ar window-id -was created but is not linked to the current session. -.It Ic %window-add Ar window-id -The window with ID -.Ar window-id -was linked to the current session. -.It Ic %window-close Ar window-id -The window with ID -.Ar window-id -closed. -.It Ic %window-renamed Ar window-id Ar name -The window with ID -.Ar window-id -was renamed to -.Ar name . -.El -.Sh FILES -.Bl -tag -width "/etc/tmux.confXXX" -compact -.It Pa ~/.tmux.conf -Default -.Nm -configuration file. -.It Pa /etc/tmux.conf -System-wide configuration file. -.El -.Sh EXAMPLES -To create a new -.Nm -session running -.Xr vi 1 : -.Pp -.Dl $ tmux new-session vi -.Pp -Most commands have a shorter form, known as an alias. -For new-session, this is -.Ic new : -.Pp -.Dl $ tmux new vi -.Pp -Alternatively, the shortest unambiguous form of a command is accepted. -If there are several options, they are listed: -.Bd -literal -offset indent -$ tmux n -ambiguous command: n, could be: new-session, new-window, next-window -.Ed -.Pp -Within an active session, a new window may be created by typing -.Ql C-b c -(Ctrl -followed by the -.Ql b -key -followed by the -.Ql c -key). -.Pp -Windows may be navigated with: -.Ql C-b 0 -(to select window 0), -.Ql C-b 1 -(to select window 1), and so on; -.Ql C-b n -to select the next window; and -.Ql C-b p -to select the previous window. -.Pp -A session may be detached using -.Ql C-b d -(or by an external event such as -.Xr ssh 1 -disconnection) and reattached with: -.Pp -.Dl $ tmux attach-session -.Pp -Typing -.Ql C-b \&? -lists the current key bindings in the current window; up and down may be used -to navigate the list or -.Ql q -to exit from it. -.Pp -Commands to be run when the -.Nm -server is started may be placed in the -.Pa ~/.tmux.conf -configuration file. -Common examples include: -.Pp -Changing the default prefix key: -.Bd -literal -offset indent -set-option -g prefix C-a -unbind-key C-b -bind-key C-a send-prefix -.Ed -.Pp -Turning the status line off, or changing its colour: -.Bd -literal -offset indent -set-option -g status off -set-option -g status-bg blue -.Ed -.Pp -Setting other options, such as the default command, -or locking after 30 minutes of inactivity: -.Bd -literal -offset indent -set-option -g default-command "exec /bin/ksh" -set-option -g lock-after-time 1800 -.Ed -.Pp -Creating new key bindings: -.Bd -literal -offset indent -bind-key b set-option status -bind-key / command-prompt "split-window 'exec man %%'" -bind-key S command-prompt "new-window -n %1 'ssh %1'" -.Ed -.Sh SEE ALSO -.Xr pty 4 -.Sh AUTHORS -.An Nicholas Marriott Aq nicm@users.sourceforge.net -- cgit From 772d61f3ed762a50ea4436b7fb70e7024674e6c6 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 15 May 2013 15:32:14 +0000 Subject: RIS should reset focus reporting, from Hayaki Saito. --- screen-write.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/screen-write.c b/screen-write.c index c0935c95..7fcfc5ee 100644 --- a/screen-write.c +++ b/screen-write.c @@ -56,7 +56,7 @@ screen_write_reset(struct screen_write_ctx *ctx) screen_reset_tabs(s); screen_write_scrollregion(ctx, 0, screen_size_y(s) - 1); - s->mode &= ~(MODE_INSERT|MODE_KCURSOR|MODE_KKEYPAD); + s->mode &= ~(MODE_INSERT|MODE_KCURSOR|MODE_KKEYPAD|MODE_FOCUSON); s->mode &= ~(ALL_MOUSE_MODES|MODE_MOUSE_UTF8|MODE_MOUSE_SGR); screen_write_clearscreen(ctx); -- cgit From 25c430b1cd25d64c52d1c14834957abfaaeb69b6 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 15 May 2013 15:34:09 +0000 Subject: Reserve space for \0 in cmd_print, from George Nachman. --- cmd.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cmd.c b/cmd.c index d0348704..e7290f26 100644 --- a/cmd.c +++ b/cmd.c @@ -295,8 +295,8 @@ cmd_print(struct cmd *cmd, char *buf, size_t len) size_t off, used; off = xsnprintf(buf, len, "%s ", cmd->entry->name); - if (off < len) { - used = args_print(cmd->args, buf + off, len - off); + if (off + 1 < len) { + used = args_print(cmd->args, buf + off, len - off - 1); if (used == 0) off--; else -- cgit From 88a4da97478ec6b4b2f361315a5a183333d0aa3f Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 15 May 2013 15:39:51 +0000 Subject: Don't let cursor position overflow when reflowing, from Christopher Collins. --- screen.c | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/screen.c b/screen.c index 754effc2..76aa91c6 100644 --- a/screen.c +++ b/screen.c @@ -365,7 +365,13 @@ void screen_reflow(struct screen *s, u_int new_x) { struct grid *old = s->grid; + u_int change; s->grid = grid_create(old->sx, old->sy, old->hlimit); - s->cy -= grid_reflow(s->grid, old, new_x); + + change = grid_reflow(s->grid, old, new_x); + if (change < s->cy) + s->cy -= change; + else + s->cy = 0; } -- cgit