diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..3469509 --- /dev/null +++ b/Makefile @@ -0,0 +1,195 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/TheTaoofTmux.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/TheTaoofTmux.qhc" + +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/TheTaoofTmux" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/TheTaoofTmux" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +livehtml: + sphinx-autobuild -H 0.0.0.0 -p 8000 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/_ext/__init__.py b/_ext/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/_ext/aafig.py b/_ext/aafig.py new file mode 100644 index 0000000..491ed37 --- /dev/null +++ b/_ext/aafig.py @@ -0,0 +1,211 @@ +# -*- coding: utf-8 -*- +""" + sphinxcontrib.aafig + ~~~~~~~~~~~~~~~~~~~ + + Allow embeded ASCII art to be rendered as nice looking images + using the aafigure reStructuredText extension. + + See the README file for details. + + :author: Leandro Lucarella + :license: BOLA, see LICENSE for details +""" + +import posixpath +from os import path +try: + from hashlib import sha1 as sha +except ImportError: + from sha import sha + +from docutils import nodes +from docutils.parsers.rst.directives import images, nonnegative_int, flag + +from sphinx.errors import SphinxError +from sphinx.util import ensuredir, relative_uri +from sphinx.util.compat import Directive + +try: + import aafigure +except ImportError: + aafigure = None + + +DEFAULT_FORMATS = dict(html='svg', latex='pdf', text=None) + + +def merge_dict(dst, src): + for (k, v) in src.items(): + if k not in dst: + dst[k] = v + return dst + + +def get_basename(text, options, prefix='aafig'): + options = options.copy() + if 'format' in options: + del options['format'] + hashkey = text.encode('utf-8') + str(options) + id = sha(hashkey).hexdigest() + return '%s-%s' % (prefix, id) + + +class AafigError(SphinxError): + category = 'aafig error' + + +class AafigDirective(images.Image): + """ + Directive to insert an ASCII art figure to be rendered by aafigure. + """ + has_content = True + required_arguments = 0 + own_option_spec = dict( + line_width = float, + background = str, + foreground = str, + fill = str, + aspect = nonnegative_int, + textual = flag, + proportional = flag, + ) + option_spec = images.Image.option_spec.copy() + option_spec.update(own_option_spec) + + def run(self): + aafig_options = dict() + image_attrs = dict() + own_options_keys = self.own_option_spec.keys() + ['scale'] + for (k, v) in self.options.items(): + if k in own_options_keys: + # convert flags to booleans + if v is None: + v = True + # convert percentage to float + if k == 'scale' or k == 'aspect': + v = float(v) / 100.0 + aafig_options[k] = v + del self.options[k] + self.arguments = [''] + (image_node,) = images.Image.run(self) + if isinstance(image_node, nodes.system_message): + return [image_node] + text = '\n'.join(self.content) + image_node.aafig = dict(options = aafig_options, text = text) + return [image_node] + + +def render_aafig_images(app, doctree): + format_map = app.builder.config.aafig_format + merge_dict(format_map, DEFAULT_FORMATS) + if aafigure is None: + app.builder.warn('aafigure module not installed, ASCII art images ' + 'will be redered as literal text') + for img in doctree.traverse(nodes.image): + if not hasattr(img, 'aafig'): + continue + if aafigure is None: + img.replace_self(nodes.literal_block(text, text)) + continue + options = img.aafig['options'] + text = img.aafig['text'] + format = app.builder.format + merge_dict(options, app.builder.config.aafig_default_options) + if format in format_map: + options['format'] = format_map[format] + else: + app.builder.warn('unsupported builder format "%s", please ' + 'add a custom entry in aafig_format config option ' + 'for this builder' % format) + img.replace_self(nodes.literal_block(text, text)) + continue + if options['format'] is None: + img.replace_self(nodes.literal_block(text, text)) + continue + try: + fname, outfn, id, extra = render_aafigure(app, text, options) + except AafigError, exc: + app.builder.warn('aafigure error: ' + str(exc)) + img.replace_self(nodes.literal_block(text, text)) + continue + img['uri'] = fname + # FIXME: find some way to avoid this hack in aafigure + if extra: + (width, height) = [x.split('"')[1] for x in extra.split()] + if not img.has_key('width'): + img['width'] = width + if not img.has_key('height'): + img['height'] = height + + +def render_aafigure(app, text, options): + """ + Render an ASCII art figure into the requested format output file. + """ + + if aafigure is None: + raise AafigError('aafigure module not installed') + + fname = get_basename(text, options) + fname = '%s.%s' % (get_basename(text, options), options['format']) + if app.builder.format == 'html': + # HTML + imgpath = relative_uri(app.builder.env.docname, '_images') + relfn = posixpath.join(imgpath, fname) + outfn = path.join(app.builder.outdir, '_images', fname) + else: + # Non-HTML + if app.builder.format != 'latex': + app.builder.warn('aafig: the builder format %s is not officially ' + 'supported, aafigure images could not work. Please report ' + 'problems and working builder to avoid this warning in ' + 'the future' % app.builder.format) + relfn = fname + outfn = path.join(app.builder.outdir, fname) + metadata_fname = '%s.aafig' % outfn + + try: + if path.isfile(outfn): + extra = None + if options['format'].lower() == 'svg': + f = None + try: + try: + f = file(metadata_fname, 'r') + extra = f.read() + except: + raise AafigError() + finally: + if f is not None: + f.close() + return relfn, outfn, id, extra + except AafigError: + pass + + ensuredir(path.dirname(outfn)) + + try: + (visitor, output) = aafigure.render(text, outfn, options) + output.close() + except aafigure.UnsupportedFormatError, e: + raise AafigError(str(e)) + + extra = None + if options['format'].lower() == 'svg': + extra = visitor.get_size_attrs() + f = file(metadata_fname, 'w') + f.write(extra) + f.close() + + return relfn, outfn, id, extra + + +def setup(app): + app.add_directive('aafig', AafigDirective) + app.connect('doctree-read', render_aafig_images) + app.add_config_value('aafig_format', DEFAULT_FORMATS, 'html') + app.add_config_value('aafig_default_options', dict(), 'html') + + +# vim: set expandtab shiftwidth=4 softtabstop=4 : diff --git a/_ext/aafig.pyc b/_ext/aafig.pyc new file mode 100644 index 0000000..ef27141 Binary files /dev/null and b/_ext/aafig.pyc differ diff --git a/_static/tao-tmux-screenshot.png b/_static/tao-tmux-screenshot.png new file mode 100644 index 0000000..d4ed773 Binary files /dev/null and b/_static/tao-tmux-screenshot.png differ diff --git a/_static/tmuxp.css b/_static/tmuxp.css new file mode 100644 index 0000000..bdea201 --- /dev/null +++ b/_static/tmuxp.css @@ -0,0 +1,14 @@ +div.sidebar { + margin: 0px; + border: 0px; + padding: 0px; + background-color: inherit; +} + +div.sidebar .sidebar-title { + display: none; +} + +form.navbar-form { + padding: 0px 10px; +} diff --git a/_templates/layout.html b/_templates/layout.html new file mode 100644 index 0000000..494087e --- /dev/null +++ b/_templates/layout.html @@ -0,0 +1,6 @@ +{%- extends "basic/layout.html" %} + +{%- block sidebartoc %} +

{{ _('Table Of Contents') }}

+{{ toctree() }} +{%- endblock %} diff --git a/about_tmux.rst b/about_tmux.rst new file mode 100644 index 0000000..cb534e9 --- /dev/null +++ b/about_tmux.rst @@ -0,0 +1,658 @@ +.. _about_tmux: + +############### +The Tao of tmux +############### + +.. figure:: _static/tao-tmux-screenshot.png + :scale: 60% + :align: center + + BSD-licensed terminal multiplexer. + +tmux is geared for developers and admins who interact regularly with +CLI (text-only interfaces) + +In the world of computers, there are 2 realms: + +1. The text realm +2. The graphical realm + +Tmux resides in the text realm. This is about fixed-width fonts and that +old fashioned black terminal. + +tmux is to the console what a desktop is to gui apps. It's a world inside +the text dimension. Inside tmux you can: + +- multitask inside the terminal, run multiple applications. +- have multiple command lines (pane) in the same window +- have multiple windows (window) in the workspace (session) +- switch between multiple workspaces, like virtual desktops + +============= +Thinking Tmux +============= + +Text-based window manager +------------------------- + +=================== ====================== =============================== +**tmux** **"Desktop"-Speak** **Plain English** +------------------- ---------------------- ------------------------------- +Multiplexer Multi-tasking Multiple applications + simulataneously. +Session Desktop Applications are visible here +Window Virtual Desktop or A desktop that stores it own + applications screen +Pane Application Performs operations +=================== ====================== =============================== + +.. aafig:: + :textual: + + +----------------------------------------------------------------+ + | +--------+--------+ +-----------------+ +-----------------+ | + | | pane | pane | | pane | | pane | | + | | | | | | | | | + | | | | | | | | | + | +--------+--------+ | | +-----------------+ | + | | pane | pane | | | | pane | | + | | | | | | | | | + | | | | | | | | | + | +--------+--------+ +-----------------+ +-----------------+ | + | | window | | window | | window | | + | \--------+--------/ \-----------------/ \-----------------/ | + +----------------------------------------------------------------+ + | session | + \----------------------------------------------------------------/ + +- 1 :term:`Server`. + + - has 1 or more :term:`Session`. + + - has 1 or more :term:`Window`. + + - has 1 or more :term:`Pane`. + +.. seealso:: :ref:`glossary` has a dictionary of tmux words. + +CLI Power Tool +-------------- + +Multiple applications or terminals to run on the same screen by splitting +up 1 terminal into multiple. + +One screen can be used to edit a file, and another may be used to +``$ tail -F`` a logfile. + +.. aafig:: + + +--------+--------+ + | $ bash | $ bash | + | | | + | | | + | | | + | | | + | | | + | | | + +--------+--------+ + +.. aafig:: + + +--------+--------+ + | $ bash | $ bash | + | | | + | | | + +--------+--------+ + | $ vim | $ bash | + | | | + | | | + +--------+--------+ + +tmux supports as manys terminals as you want. + + +.. aafig:: + :textual: + + +---------+---------+ + | $ bash | $ bash | + | | | + | | | /-----------------\ + +---------+---------+ --> |'switch-window 2'| + | $ vim | $ bash | \-----------------/ + | | | | + | | | | + +---------+---------+ | + | '1:sys* 2:vim' | | + +-------------------+ | + /------------------------/ + | + v + +---------+---------+ + | $ bash | $ bash | + | | | + | | | + +---------+---------+ + | $ vim | $ bash | + | | | + | | | + +---------+---------+ + | '1:sys* 2:vim' | + +-------------------+ + +You can switch between the windows you create. + +Resume everything later +----------------------- + +You can leave tmux and all applications running (detach), log out, make a +sandwich, and re-(attach), all applications are still running! + +.. aafig:: + :textual: + + +--------+--------+ + | $ bash | $ bash | + | | | + | | | /------------\ + +--------+--------+ --> | detach | + | $ vim | $ bash | | 'Ctrl-b b' | + | | | \------------/ + | | | | + +--------+--------+ | + /------------------/ + | + v + +-----------------------+ + | $ [screen detached] | + | | + | | + | | + | | + | | + | | + +-----------------------+ + v + | + v + +-----------------------+ + | $ [screen detached] | + | $ tmux attach | + | | /------------\ + | | --> | attaching | + | | \------------/ + | | | + | | | + +-----------------------+ | + | + /---------------------------/ + | + v + +--------+--------+ + | $ bash | $ bash | + | | | + | | | + +--------+--------+ + | $ vim | $ bash | + | | | + | | | + +--------+--------+ + +Manage workflow +--------------- + +- System administrators monitor logs and services. +- Programmers like to have an editor open with a CLI nearby. + +Applications running on a remote server can be launched inside of a tmux +session, detached, and reattached next timeyour `"train of thought"`_ and +work. + +Multitasking. Preserving the thinking you have. + +.. _"train of thought": http://en.wikipedia.org/wiki/Train_of_thought + +=============== +Installing tmux +=============== + +Tmux is packaged on most Linux and BSD systems. + +For the freshest results on how to get tmux installed on your system, +"How to install tmux on " will do, as directions change and are +slightly different between distributions. + +This documentation is written for version **1.8**. It's important that +you have the latest stable release of tmux. The latest stable version is +viewable on the `tmux homepage`_. + +**Mac OS X** users may install that latest stable version of tmux through +`MacPorts`_, `fink`_ or `Homebrew`_ (aka brew). + +If **compiling from source**, the dependencies are `libevent`_ and +`ncurses`_. + +.. _tmux homepage: http://tmux.sourceforge.net/ +.. _libevent: http://www.monkey.org/~provos/libevent/ +.. _ncurses: http://invisible-island.net/ncurses/ +.. _MacPorts: http://www.macports.org/ +.. _Fink: http://fink.thetis.ig42.org/ +.. _Homebrew: http://www.brew.sh + +========== +Using tmux +========== + +Start a new session +------------------- + +.. code-block:: bash + + $ tmux + +That's all it takes to launch yourself into a tmux session. + +.. tip:: Common pitfall + + Running ``$ tmux list-sessions`` or any other command for listing tmux + entities (such as ``$ tmux list-windows`` or ``$ tmux list-panes``). + This can generate the error "failed to connect to server". + + This could be because: + + - tmux server has killed its' last session, killing the server. + - tmux server has encountered a crash. (tmux is highly stable, + this will rarely happen) + - tmux has not be launched yet at all. + +.. _Prefix key: + +The prefix key +-------------- + +Tmux hot keys have to be pressed in a special way. **Read this +carefully**, then try it yourself. + +First, you press the *prefix* key. This is ``C-b`` by default. + +Release. Then pause. For less than second. Then type what's next. + +``C-b o`` means: Press ``Ctrl`` and ``b`` at the same time. Release, +Then press ``o``. + +**Remember, prefix + short cut!** ``C`` is ``Ctrl`` key. + +Session Name +------------ + +Sessions can be *named upon creation*. + +.. code-block:: bash + + $ tmux new-session [-s session-name] + +Sessions can be *renamed after creation*. + +=============== ========================================================= +Command .. code-block:: bash + + $ tmux rename-session + +Short cut ``Prefix`` + ``$`` +=============== ========================================================= + +Window Name +----------- + +Windows can be *named upon creation*. + +.. code-block:: bash + + $ tmuxp new-window [-n window-name] + +Windows can be *renamed after creation*. + +=============== ========================================================== +Command .. code-block:: bash + + $ tmux rename-window + +Short cut ``Prefix`` + ``,`` +=============== ========================================================== + +Creating new windows +-------------------- + +=============== ========================================================= +Command .. code-block:: bash + + $ tmux new-window [-n window-name] + +Short cut ``Prefix`` + ``c`` + + You may then rename window. +=============== ========================================================= + +Traverse windows +---------------- + +By number + +.. code-block:: bash + + $ tmux select-window + +Next + +.. code-block:: bash + + $ tmux next-window + +Previous + +.. code-block:: bash + + $ tmux previous-window + +Last-window + +.. code-block:: bash + + $ tmux last-window + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``n`` Change to the next window. +``p`` Change to the previous window. +``w`` Choose the current window interactively. +``0 to 9`` Select windows 0 to 9. + +``M-n`` Move to the next window with a bell or activity + marker. +``M-p`` Move to the previous window with a bell or activity + marker. + +=================== ==================================================== + +Move windows +------------ + +Move window + +.. code-block:: bash + + $ tmux move-window [-t dst-window] + +Swap the window + +.. code-block:: bash + + $ tmux swap-window [-t dst-window] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``.`` Prompt for an index to move the current window. +=================== ==================================================== + + +Move panes +---------- + +.. code-block:: bash + + $ tmux move-pane [-t dst-pane] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``C-o`` Rotate the panes in the current window forwards. +``{`` Swap the current pane with the previous pane. +``}`` Swap the current pane with the next pane. +=================== ==================================================== + + +Traverse panes +-------------- + +Shortcut to move between panes. + +.. code-block:: bash + + $ tmux last-window + +.. code-block:: bash + + $ tmux next-window + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``Up, Down`` Change to the pane above, below, to the left, or to +``Left, Right`` the right of the current pane. +=================== ==================================================== + + +Recipe: tmux conf to ``hjkl`` commands, add this to your +``~/.tmux.conf``:: + + # hjkl pane traversal + bind h select-pane -L + bind j select-pane -D + bind k select-pane -U + bind l select-pane -R + +Kill window +----------- + +.. code-block:: bash + + $ tmux kill-window + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``&`` Kill the current window. +=================== ==================================================== + + +Kill pane +--------- + +.. code-block:: bash + + $ tmux kill-pane [-t target-pane] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``x`` Kill the current pane. +=================== ==================================================== + +Kill window +----------- + +.. code-block:: bash + + $ tmux kill-window [-t target-window] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``&`` Kill the current window. +=================== ==================================================== + +Splitting windows into panes +---------------------------- + +.. code-block:: bash + + $ tmux split-window [-c start-directory] + +Tmux windows can be split into multiple panes. + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``%`` Split the current pane into two, left and right. +``"`` Split the current pane into two, top and bottom. +=================== ==================================================== + +================ +Configuring Tmux +================ + +Tmux can be configured via a configuration at ``~/.tmux.conf``. + +Depending on your tmux version, there is different options available. + +Vi-style copy and paste +----------------------- + +.. code-block:: ini + + # Vi copypaste mode + set-window-option -g mode-keys vi + bind-key -t vi-copy 'v' begin-selection + bind-key -t vi-copy 'y' copy-selection + +Aggressive resizing for clients +------------------------------- + +.. code-block:: ini + + setw -g aggressive-resize on + +Reload config +------------- + +```` + ``r``. + +.. code-block:: ini + + bind r source-file ~/.tmux.conf \; display-message "Config reloaded." + +Status lines +------------ + +Tmux allows configuring a status line that displays system information, +window list, and even pipe in the ``stdout`` of an application. + +You can use `tmux-mem-cpu-load`_ to get stats (requires compilation) and +`basic-cpu-and-memory.tmux`_. You can pipe in a bash command to a tmux +status line like: + +.. code-block:: ini + + $(shell-command) + +So if ``/usr/local/bin/tmux-mem-cpu-load`` outputs stats to +``stdout``, then ``$(tmux-mem-cpu-load)`` is going to output the first +line to the status line. The interval is determined by the +``status-interval``:: + + set -g status-interval 1 + +.. _tmux-mem-cpu-load: https://github.com/thewtex/tmux-mem-cpu-load +.. _basic-cpu-and-memory.tmux: https://github.com/zaiste/tmuxified/blob/master/scripts/basic-cpu-and-memory.tmux + +Examples +-------- + +- https://github.com/tony/tmux-config - works with tmux 1.5+. Supports + screen's ``ctrl-a`` :ref:`Prefix key`. Support for system cpu, memory, + uptime stats. +- Add yours, edit this page on github. + +========= +Reference +========= + +Short cuts +---------- + +.. tip:: + + :ref:`Prefix key` is pressed before a short cut! + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``C-b`` Send the prefix key (C-b) through to the + application. +``C-o`` Rotate the panes in the current window forwards. +``C-z`` Suspend the tmux client. +``!`` Break the current pane out of the window. +``"`` Split the current pane into two, top and bottom. +``#`` List all paste buffers. +``$`` Rename the current session. +``%`` Split the current pane into two, left and right. +``&`` Kill the current window. +``'`` Prompt for a window index to select. +``,`` Rename the current window. +``-`` Delete the most recently copied buffer of text. +``.`` Prompt for an index to move the current window. +``0 to 9`` Select windows 0 to 9. +``:`` Enter the tmux command prompt. +``;`` Move to the previously active pane. +``=`` Choose which buffer to paste interactively from a + list. +``?`` List all key bindings. +``D`` Choose a client to detach. +``[`` Enter copy mode to copy text or view the history. +``]`` Paste the most recently copied buffer of text. +``c`` Create a new window. +``d`` Detach the current client. +``f`` Prompt to search for text in open windows. +``i`` Display some information about the current window. +``l`` Move to the previously selected window. +``n`` Change to the next window. +``o`` Select the next pane in the current window. +``p`` Change to the previous window. +``q`` Briefly display pane indexes. +``r`` Force redraw of the attached client. +``s`` Select a new session for the attached client + interactively. +``L`` Switch the attached client back to the last session. +``t`` Show the time. +``w`` Choose the current window interactively. +``x`` Kill the current pane. +``{`` Swap the current pane with the previous pane. +``}`` Swap the current pane with the next pane. +``~`` Show previous messages from tmux, if any. +``Page Up`` Enter copy mode and scroll one page up. +``Up, Down`` Change to the pane above, below, to the left, or to +``Left, Right`` the right of the current pane. +``M-1 to M-5`` Arrange panes in one of the five preset layouts: + even-horizontal, even-vertical, main-horizontal, + main-vertical, or tiled. +``M-n`` Move to the next window with a bell or activity + marker. +``M-o`` Rotate the panes in the current window backwards. +``M-p`` Move to the previous window with a bell or activity + marker. +``C-Up, C-Down`` Resize the current pane in steps of one cell. +``C-Left, C-Right`` +``M-Up, M-Down`` Resize the current pane in steps of five cells. +``M-Left, M-Right`` +=================== ==================================================== + +Source: tmux manpage [1]_. + +To get the text documentation of a ``.1`` manual file: + +.. code-block:: bash + + $ nroff -mdoc tmux.1|less + +.. [1] http://sourceforge.net/p/tmux/tmux-code/ci/master/tree/tmux.1 + +======= +License +======= + +This page is licensed `Creative Commons BY-NC-ND 3.0 US`_. + +.. _Creative Commons BY-NC-ND 3.0 US: http://creativecommons.org/licenses/by-nc-nd/3.0/us/ diff --git a/basic_usage.rst b/basic_usage.rst new file mode 100644 index 0000000..dcf95d7 --- /dev/null +++ b/basic_usage.rst @@ -0,0 +1,263 @@ +.. _basic_usage: + +=========== +Basic usage +=========== + +Start a new session +------------------- + +.. code-block:: bash + + $ tmux + +That's all it takes to launch yourself into a tmux session. + +.. tip:: Common pitfall + + Running ``$ tmux list-sessions`` or any other command for listing tmux + entities (such as ``$ tmux list-windows`` or ``$ tmux list-panes``). + This can generate the error "failed to connect to server". + + This could be because: + + - tmux server has killed its' last session, killing the server. + - tmux server has encountered a crash. (tmux is highly stable, + this will rarely happen) + - tmux has not be launched yet at all. + +.. _Prefix key: + +The prefix key +-------------- + +Tmux hot keys have to be pressed in a special way. **Read this +carefully**, then try it yourself. + +First, you press the *prefix* key. This is ``C-b`` by default. + +Release. Then pause. For less than second. Then type what's next. + +``C-b o`` means: Press ``Ctrl`` and ``b`` at the same time. Release, +Then press ``o``. + +**Remember, prefix + short cut!** ``C`` is ``Ctrl`` key. + +Session Name +------------ + +Sessions can be *named upon creation*. + +.. code-block:: bash + + $ tmux new-session [-s session-name] + +Sessions can be *renamed after creation*. + +=============== ========================================================= +Command .. code-block:: bash + + $ tmux rename-session + +Short cut ``Prefix`` + ``$`` +=============== ========================================================= + +Window Name +----------- + +Windows can be *named upon creation*. + +.. code-block:: bash + + $ tmuxp new-window [-n window-name] + +Windows can be *renamed after creation*. + +=============== ========================================================== +Command .. code-block:: bash + + $ tmux rename-window + +Short cut ``Prefix`` + ``,`` +=============== ========================================================== + +Creating new windows +-------------------- + +=============== ========================================================= +Command .. code-block:: bash + + $ tmux new-window [-n window-name] + +Short cut ``Prefix`` + ``c`` + + You may then rename window. +=============== ========================================================= + +Traverse windows +---------------- + +By number + +.. code-block:: bash + + $ tmux select-window + +Next + +.. code-block:: bash + + $ tmux next-window + +Previous + +.. code-block:: bash + + $ tmux previous-window + +Last-window + +.. code-block:: bash + + $ tmux last-window + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``n`` Change to the next window. +``p`` Change to the previous window. +``w`` Choose the current window interactively. +``0 to 9`` Select windows 0 to 9. + +``M-n`` Move to the next window with a bell or activity + marker. +``M-p`` Move to the previous window with a bell or activity + marker. + +=================== ==================================================== + +Move windows +------------ + +Move window + +.. code-block:: bash + + $ tmux move-window [-t dst-window] + +Swap the window + +.. code-block:: bash + + $ tmux swap-window [-t dst-window] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``.`` Prompt for an index to move the current window. +=================== ==================================================== + + +Move panes +---------- + +.. code-block:: bash + + $ tmux move-pane [-t dst-pane] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``C-o`` Rotate the panes in the current window forwards. +``{`` Swap the current pane with the previous pane. +``}`` Swap the current pane with the next pane. +=================== ==================================================== + + +Traverse panes +-------------- + +Shortcut to move between panes. + +.. code-block:: bash + + $ tmux last-window + +.. code-block:: bash + + $ tmux next-window + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``Up, Down`` Change to the pane above, below, to the left, or to +``Left, Right`` the right of the current pane. +=================== ==================================================== + + +Recipe: tmux conf to ``hjkl`` commands, add this to your +``~/.tmux.conf``:: + + # hjkl pane traversal + bind h select-pane -L + bind j select-pane -D + bind k select-pane -U + bind l select-pane -R + +Kill window +----------- + +.. code-block:: bash + + $ tmux kill-window + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``&`` Kill the current window. +=================== ==================================================== + + +Kill pane +--------- + +.. code-block:: bash + + $ tmux kill-pane [-t target-pane] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``x`` Kill the current pane. +=================== ==================================================== + +Kill window +----------- + +.. code-block:: bash + + $ tmux kill-window [-t target-window] + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``&`` Kill the current window. +=================== ==================================================== + +Splitting windows into panes +---------------------------- + +.. code-block:: bash + + $ tmux split-window [-c start-directory] + +Tmux windows can be split into multiple panes. + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``%`` Split the current pane into two, left and right. +``"`` Split the current pane into two, top and bottom. +=================== ==================================================== + + diff --git a/changes.rst b/changes.rst new file mode 100644 index 0000000..97d0c4e --- /dev/null +++ b/changes.rst @@ -0,0 +1,7 @@ +.. _changes: + +======= +Changes +======= + +stub diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..9041f16 --- /dev/null +++ b/conf.py @@ -0,0 +1,384 @@ +# -*- coding: utf-8 -*- +# +# The Tao of Tmux documentation build configuration file, created by +# sphinx-quickstart on Tue Nov 3 22:08:49 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# Get the project root dir, which is the parent dir of this +cwd = os.getcwd() +project_root = os.path.dirname(cwd) + +# Insert the project root dir as the first element in the PYTHONPATH. +# This lets us ensure that the source package is imported, and that its +# version is used. +sys.path.insert(0, project_root) +sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext"))) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'aafig', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'toc' + +# General information about the project. +project = u'The Tao of Tmux' +copyright = u'2015, Tony Narlock' +author = u'Tony Narlock' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'TheTaoofTmuxdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'TheTaoofTmux.tex', u'The Tao of Tmux Documentation', + u'Tony Narlock', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'thetaooftmux', u'The Tao of Tmux Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'TheTaoofTmux', u'The Tao of Tmux Documentation', + author, 'TheTaoofTmux', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +# aafig format, try to get working with pdf +aafig_format = dict(latex='pdf', html='png') + +aafig_default_options = dict( + scale=.75, + aspect=0.5, + proportional=True, +) diff --git a/configuration.rst b/configuration.rst new file mode 100644 index 0000000..0d8c560 --- /dev/null +++ b/configuration.rst @@ -0,0 +1,35 @@ +.. _configuration: + +============= +Configuration +============= + +Tmux can be configured via a configuration at ``~/.tmux.conf``. + +Depending on your tmux version, there is different options available. + +Vi-style copy and paste +----------------------- + +.. code-block:: ini + + # Vi copypaste mode + set-window-option -g mode-keys vi + bind-key -t vi-copy 'v' begin-selection + bind-key -t vi-copy 'y' copy-selection + +Aggressive resizing for clients +------------------------------- + +.. code-block:: ini + + setw -g aggressive-resize on + +Reload config +------------- + +```` + ``r``. + +.. code-block:: ini + + bind r source-file ~/.tmux.conf \; display-message "Config reloaded." diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..8fd02bd --- /dev/null +++ b/index.rst @@ -0,0 +1,264 @@ +.. The Tao of Tmux documentation master file, created by + sphinx-quickstart on Tue Nov 3 22:08:49 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +The Tao of Tmux +=============== + +.. figure:: _static/tao-tmux-screenshot.png + :scale: 60% + :align: center + + BSD-licensed terminal multiplexer. + +tmux is geared for developers and admins who interact regularly with +CLI (text-only interfaces) + +In the world of computers, there are 2 realms: + +1. The text realm +2. The graphical realm + +Tmux resides in the text realm. This is about fixed-width fonts and that +old fashioned black terminal. + +tmux is to the console what a desktop is to gui apps. It's a world inside +the text dimension. Inside tmux you can: + +- multitask inside the terminal, run multiple applications. +- have multiple command lines (pane) in the same window +- have multiple windows (window) in the workspace (session) +- switch between multiple workspaces, like virtual desktops + +============= +Thinking Tmux +============= + +Text-based window manager +------------------------- + +=================== ====================== =============================== +**tmux** **"Desktop"-Speak** **Plain English** +------------------- ---------------------- ------------------------------- +Multiplexer Multi-tasking Multiple applications + simulataneously. +Session Desktop Applications are visible here +Window Virtual Desktop or A desktop that stores it own + applications screen +Pane Application Performs operations +=================== ====================== =============================== + +.. aafig:: + :textual: + + +----------------------------------------------------------------+ + | +--------+--------+ +-----------------+ +-----------------+ | + | | pane | pane | | pane | | pane | | + | | | | | | | | | + | | | | | | | | | + | +--------+--------+ | | +-----------------+ | + | | pane | pane | | | | pane | | + | | | | | | | | | + | | | | | | | | | + | +--------+--------+ +-----------------+ +-----------------+ | + | | window | | window | | window | | + | \--------+--------/ \-----------------/ \-----------------/ | + +----------------------------------------------------------------+ + | session | + \----------------------------------------------------------------/ + +- 1 :term:`Server`. + + - has 1 or more :term:`Session`. + + - has 1 or more :term:`Window`. + + - has 1 or more :term:`Pane`. + +.. seealso:: :ref:`glossary` has a dictionary of tmux words. + +CLI Power Tool +-------------- + +Multiple applications or terminals to run on the same screen by splitting +up 1 terminal into multiple. + +One screen can be used to edit a file, and another may be used to +``$ tail -F`` a logfile. + +.. aafig:: + + +--------+--------+ + | $ bash | $ bash | + | | | + | | | + | | | + | | | + | | | + | | | + +--------+--------+ + +.. aafig:: + + +--------+--------+ + | $ bash | $ bash | + | | | + | | | + +--------+--------+ + | $ vim | $ bash | + | | | + | | | + +--------+--------+ + +tmux supports as manys terminals as you want. + + +.. aafig:: + :textual: + + +---------+---------+ + | $ bash | $ bash | + | | | + | | | /-----------------\ + +---------+---------+ --> |'switch-window 2'| + | $ vim | $ bash | \-----------------/ + | | | | + | | | | + +---------+---------+ | + | '1:sys* 2:vim' | | + +-------------------+ | + /------------------------/ + | + v + +---------+---------+ + | $ bash | $ bash | + | | | + | | | + +---------+---------+ + | $ vim | $ bash | + | | | + | | | + +---------+---------+ + | '1:sys* 2:vim' | + +-------------------+ + +You can switch between the windows you create. + +.. _resume: + +Resume everything later +----------------------- + +You can leave tmux and all applications running (detach), log out, make a +sandwich, and re-(attach), all applications are still running! + +.. aafig:: + :textual: + + +--------+--------+ + | $ bash | $ bash | + | | | + | | | /------------\ + +--------+--------+ --> | detach | + | $ vim | $ bash | | 'Ctrl-b b' | + | | | \------------/ + | | | | + +--------+--------+ | + /------------------/ + | + v + +-----------------------+ + | $ [screen detached] | + | | + | | + | | + | | + | | + | | + +-----------------------+ + v + | + v + +-----------------------+ + | $ [screen detached] | + | $ tmux attach | + | | /------------\ + | | --> | attaching | + | | \------------/ + | | | + | | | + +-----------------------+ | + | + /---------------------------/ + | + v + +--------+--------+ + | $ bash | $ bash | + | | | + | | | + +--------+--------+ + | $ vim | $ bash | + | | | + | | | + +--------+--------+ + +Manage workflow +--------------- + +- System administrators monitor logs and services. +- Programmers like to have an editor open with a CLI nearby. + +Applications running on a remote server can be launched inside of a tmux +session, detached, and reattached next timeyour `"train of thought"`_ and +work. + +Multitasking. Preserving the thinking you have. + +.. _"train of thought": http://en.wikipedia.org/wiki/Train_of_thought + +=============== +Installing tmux +=============== + +Tmux is packaged on most Linux and BSD systems. + +For the freshest results on how to get tmux installed on your system, +"How to install tmux on " will do, as directions change and are +slightly different between distributions. + +This documentation is written for version **1.8**. It's important that +you have the latest stable release of tmux. The latest stable version is +viewable on the `tmux homepage`_. + +**Mac OS X** users may install that latest stable version of tmux through +`MacPorts`_, `fink`_ or `Homebrew`_ (aka brew). + +If **compiling from source**, the dependencies are `libevent`_ and +`ncurses`_. + +.. _tmux homepage: http://tmux.sourceforge.net/ +.. _libevent: http://www.monkey.org/~provos/libevent/ +.. _ncurses: http://invisible-island.net/ncurses/ +.. _MacPorts: http://www.macports.org/ +.. _Fink: http://fink.thetis.ig42.org/ +.. _Homebrew: http://www.brew.sh + +======= +License +======= + +Copyright 2013-2015, Tony Narlock. All rights reserved. + +This page is licensed `Creative Commons BY-NC-ND 3.0 US`_. + +.. _Creative Commons BY-NC-ND 3.0 US: http://creativecommons.org/licenses/by-nc-nd/3.0/us/ + +================== +Indices and tables +================== + +* :ref:`table_of_contents` +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/internals.rst b/internals.rst new file mode 100644 index 0000000..a488a8e --- /dev/null +++ b/internals.rst @@ -0,0 +1,9 @@ +.. _internals: + +========= +Internals +========= + +``compat/queue.h`` -singly-linked lists, lists, simple queues, tail queues, +and circular queues + diff --git a/manual/0.8.txt b/manual/0.8.txt new file mode 100644 index 0000000..0550ae7 --- /dev/null +++ b/manual/0.8.txt @@ -0,0 +1,808 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28dqUuVv] [-f file] [-L socket-name] [-S socket-path] + [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer; it enables a number of terminals to be + accessed and controlled from a single terminal. + + tmux runs as a server-client system. A server is created automatically + when necessary and holds a number of sessions, each of which may have a + number of windows linked to it. A window may be split on screen into one + or more panes, each of which is a separate terminal. Any number of + clients may connect to a session, or the server may be controlled by + issuing commands with tmux. Communication takes place through a socket, + by default placed in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, indicates the terminal supports 88 colours. + + -d Force tmux to assume the terminal supports default colours. + + -f file Specify an alternative configuration file. By default, + tmux will look for a config file at ~/.tmux.conf. The con- + figuration file is a set of tmux commands which are exe- + cuted in sequence when the server is first started. + + -q Prevent the server sending various information messages, + for example when window flags are altered. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -U Unlock the server. + + -u Instruct tmux that the terminal support UTF-8. + + -V Print program version. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the pid of the + server or client process. + + command [flags] + This specifies one of a set of commands used to control + tmux, and described in the following sections. If no com- + mand and flags is specified, the new-session command is + assumed. + +QUICK START + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + $ + + Within an active session, a new window may be created by typing 'C-b' + (ctrl-b, known as the prefix key) followed by the 'c' key. + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'Q' to exit from it. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (ctrl-b) by default, followed by a command key. + + Some of the default key bindings include: + + 'd' Detach current client. + 'c' Create new window. + 'n' Change to next window in the current session. + 'p' Change to previous window in the current session. + 'l' Move to last (previously selected) window in the current session. + 't' Display a large clock. + '?' List current key bindings. + + A complete list may be obtained with the list-keys command (bound to '?' + by default). Key bindings may be changed with the bind-key and + unbind-key commands. + +HISTORY + tmux maintains a configurable history buffer for each window. By + default, up to 2000 lines are kept, this can be altered with the + history-limit option (see the set-option command below). + +MODES + A tmux window may be in one of several modes. The default permits direct + access to the terminal attached to the window. The others are: + + output mode + This is entered when a command which produces output, such as + list-keys, is executed from a key binding. + + scroll mode + This is entered with the scroll-mode command (bound to '=' by + default) and permits the window history buffer to be inspected. + + copy mode + This permits a section of a window or its history to be copied to + a paste buffer for later insertion into another window. This + mode is entered with the copy-mode command, bound to ['' by + default. + + The keys available depend on whether emacs(1) or vi(1) mode is selected + (see the mode-keys option). The following keys are supported as appro- + priate for the mode: + + Function vi emacs + Start of line 0 or ^ C-a + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + End of line $ C-e + Cursor left h Left + Next page C-f Page down + Next word w M-f + Previous page C-u Page up + Previous word b M-b + Quit mode q Escape + Cursor right l Right + Start selection Space C-Space + Cursor up k Up + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + +PANES AND LAYOUTS + Each window displayed by tmux may be split into one or more 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 split-window command. + + Panes are numbered beginning from zero; in horizontal layouts zero is the + leftmost pane and in vertical the topmost. + + Panes may be arranged using several layouts. The layout may be cycled + with the next-layout command (bound to 'C-space' by default), the current + pane may be changed with the up-pane and down-pane commands and the + rotate-window and swap-pane commands may be used to swap panes without + changing the window layout. + + The following layouts are supported: + + manual Manual layout splits windows vertically (running across); only + with this layout may panes be resized using the resize-pane-up + and resize-pane-down commands. + + active-only + Only the active pane is shown - all other panes are hidden. + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + left-vertical + A large (81 column) pane is shown on the left of the window and + the remaining panes are spread from top to bottom in the leftover + space to the right. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session or target-window. These specify the client, session or + window which a command should affect. target-client is the name of the + pty(4) file to which the client is connected, for example /dev/ttyp1. + Clients may be listed with the list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command); or the name of a client as for target-client, in + this case, the session attached to the client is used. An fnmatch(3) + pattern may be used to match the session name. If a session is omitted + when required, tmux attempts to use the current session; if no current + session is available, the most recently created is chosen. If no client + is specified, the current client is chosen, if possible, or an error is + reported. + + target-window specifies a window in the form session:index, for example + mysession:1. The session is in the same form as for target-session. + session, index or both may be omitted. If session is omitted, the same + rules as for target-session are followed; if index is not present, the + current window for the given session is used. When the argument does not + contain a colon (:), tmux first attempts to parse it as window index; if + that fails, an attempt is made to match a session or client name. + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon (' + ; '); commands are executed sequentially from left to right. A literal + semicolon may be included by escaping it with a backslash (for example, + when specifying a command sequence to bind-key). + + Examples include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + bind-key D detach-client \; lock-server + + The following commands are available: + + attach-session [-d] [-t target-session] + (alias: attach) + Create a new client in the current terminal and attach it to a + session. If -d is specified, any other clients attached to the + session are detached. + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + bind-key [-r] key command [arguments] + (alias: bind) + Bind key key to command. Keys may be specified prefixed with + 'C-' or '^' for ctrl keys, or 'M-' for alt (meta) keys. The -r + flag indicates this key may repeat, see the repeat-time option. + + break-pane [-d] [-p pane-index] [-t target-window] + Break the current pane off from its containing window to make it + the only pane in a new window. If -d is given, the new window + does not become the current window. + + choose-session [-t target-window] + Put a window into session choice mode, where the session for the + current client may be selected interactively from a list. This + command works only from inside tmux. + + choose-window [-t target-window] + Put a window into window choice mode, where the window for the + session attached to the current client may be selected interac- + tively from a list. This command works only from inside tmux. + + clock-mode [-t target-window] + Display a large clock. + + command-prompt [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command; any %% in the template will + be replaced by what is entered at the prompt. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + copy-mode [-u] [-t target-window] + Enter copy mode. The -u option scrolls one page up. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + down-pane [-p pane-index] [-t target-window] + (alias: downp) + Move down a pane. + + find-window [-t target-window] match-string + (alias: findw) + Search for match-string in window names, titles, and visible con- + tent (but not history). If only one window is matched, it'll be + automatically selected, otherwise a choice list is shown. This + command only works from inside tmux. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-pane [-p pane-index] [-t target-window] + (alias: killp) + Destroy the given pane. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-keys + (alias: lsk) + List all key bindings. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + lock-server + (alias: lock) + Lock the server until a password is entered. + + move-window [-d] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-session [-d] [-n window-name] [-s session-name] [command] + (alias: new) + Create a new session with name session-name. The new session is + attached to the current terminal unless -d is given. window-name + and command are the name of and command to execute in the initial + window. + + new-window [-d] [-n window-name] [-t target-window] [command] + (alias: neww) + Create a new window. If -d is given, the session does not make + the new window the current window. target-window represents the + window to be created. command is the command to execute. If + command is not specified, the default command is used. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-t target-session] + (alias: next) + Move to the next window in the session. + + paste-buffer [-d] [-b buffer-index] [-t target-window] + (alias: pasteb) + Insert the contents of a paste buffer into the current window. + + previous-window [-t target-session] + (alias: prev) + Move to the previous window in the session. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane-down [-p pane-index] [-t target-window] [adjustment] + (alias: resizep-down) + + resize-pane-up [-p pane-index] [-t target-window] [adjustment] + (alias: resizep-up) + Resize a pane. The adjustment is given in lines (the default is + 1). + + respawn-window [-k] [-t target-window] [command] + (alias: respawnw) + Reactive a window in which the command has exited (see the + remain-on-exit window option). If command is not given, the com- + mand used when the window was created is executed. The window + must be already inactive, unless -k is given, in which case any + existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + scroll-mode [-u] [-t target-window] + Enter scroll mode. The -u has the same meaning as in the + copy-mode command. + + select-pane [-p pane-index] [-t target-window] + (alias: selectp) + Make pane pane-index the active pane in window target-window. + + select-prompt [-t target-client] + Open a prompt inside target-client allowing a window index to be + entered interactively. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + send-keys [-t target-window] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-window] + Send the prefix key to a window as if it was pressed. + + server-info + (alias: info) + Show server information and terminal details. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + set-option [-gu] [-t target-session] option value + (alias: set) + Set an option. If -g is specified, the option is set as a global + option. Global options apply to all sessions which don't have + the option explicitly set. If -g is not used, the option applies + only to target-session. The -u flag unsets an option, so a ses- + sion inherits the option from the global options - it is not pos- + sible to unset a global option. + + Possible options are: + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command command + Set the command used for new windows (if not specified + when the window is created) to command. The default is + ``exec $SHELL''. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is the current working directory when the server is + started. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the server after number seconds of inactivity. The + default is off (set to 0). This has no effect as a ses- + sion option; it must be set as a global option using -g. + + message-attr attributes + Set status line message attributes, where attributes is + either default or a comma-delimited list of one or more + of: bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white or default. + + message-fg colour + Set status line message foreground colour. + + prefix key + Set the current prefix key. + + repeat-time number + Allow multiple commands to be entered without pressing + the prefix-key again in the specified number milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys of the up-pane, + down-pane, resize-pane-up, and resize-pane-down commands. + + set-remain-on-exit [on | off] + Set the remain-on-exit window option for any windows + first created in this session. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code and the terminal appears to be an xterm. This + option is enabled by default. Note that elinks(1) will + only attempt to set the window title if the STY environ- + ment variable is set. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-keys [vi | emacs] + Use vi(1) - or emacs(1) -style key bindings in the status + line, for example at the command prompt. Defaults to + emacs. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character pairs: + + Character pair Replaced with + #(command) First line of command's output + #H Hostname of local host + #S Session name + #T Current window title + ## A literal '#' + + Where appropriate, these may be prefixed with a number to + specify the maximum length, for example '#24T'. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display string to the right of the status bar. By + default, the date and time will be shown. As with + status-left, string will be passed to strftime(3) and + character pairs are replaced. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + set-password [-c] password + (alias: pass) + Set the server password. If the -c option is given, a pre- + encrypted password may be specified. By default, the password is + blank, thus any entered password will be accepted when unlocking + the server (see the lock-server command). To prevent variable + expansion when an encrypted password is read from a configuration + file, enclose it in single quotes ('). + + set-window-option [-gu] [-t target-window] option value + (alias: setw) + Set a window-specific option. The -g and -u flags work similarly + to the set-option command. + + Supported options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi(1) - or emacs(1) -style key bindings in scroll and + copy modes. Key bindings default to emacs. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as shift, meta or ctrl. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + + show-options [-t target-session] option value + (alias: show) + Show the currently set options. If a target-session is speci- + fied, the options for that session are shown; otherwise, the + global options are listed. + + show-window-options [-t target-window] option value + (alias: showw) + List the current options for the given window. + + source-file path + (alias: source) + Execute commands from path. + + split-window [-d] [-l lines | -p percentage] [-t target-window] [command] + (alias: splitw) + Creates a new window by splitting it vertically. The -l and -p + options specify the size of the new window in lines, or as a per- + centage, respectively. All other options have the same meaning + as in the new-window command. + + A few notes with regard to panes: + 1. If attempting to split a window with less than eight lines, + an error will be shown. + 2. If the window is resized, as many panes are shown as can fit + without reducing them below four lines. + 3. The minimum pane size is four lines (including the separator + line). + 4. The panes are indexed from top (0) to bottom, with no num- + bers skipped. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c -target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + swap-pane [-dDU] [-p src-index] [-t target-window] [-q dst-index] + (alias: swapp) + Swap two panes within a window. If -U is used, the pane is + swapped with the pane above (before it numerically); -D swaps + with the pane below (the next numerically); or dst-index may be + give to swap with a specific pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + switch-client [-c target-client -t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. + + unbind-key key + (alias: unbind) + Unbind the key bound to key. + + unlink-window [-t target-window] + (alias: unlinkw) + Unlink target-window. A window may be unlinked only if it is + linked to multiple sessions - windows may not be linked to no + sessions. + + up-pane [-p pane-index] [-t target-window] + (alias: upp) + Move up a pane. + +FILES + ~/.tmux.conf + default tmux configuration file + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD April 20, 2009 BSD diff --git a/manual/0.9.txt b/manual/0.9.txt new file mode 100644 index 0000000..e0fb1ee --- /dev/null +++ b/manual/0.9.txt @@ -0,0 +1,917 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28dqUuv] [-f file] [-L socket-name] [-S socket-path] + [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + accessed and controlled from a single terminal. + + tmux runs as a server-client system. A server is created automatically + when necessary and holds a number of sessions, each of which may have a + number of windows linked to it. A window may be split on screen into one + or more panes, each of which is a separate terminal. Any number of + clients may connect to a session, or the server may be controlled by + issuing commands with tmux. Communication takes place through a socket, + by default placed in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -d Force tmux to assume the terminal supports default colours. + + -f file Specify an alternative configuration file. By default, + tmux will look for a config file at ~/.tmux.conf. The con- + figuration file is a set of tmux commands which are exe- + cuted in sequence when the server is first started. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -q Prevent the server sending various informational messages, + for example when window flags are altered. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -U Unlock the server. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mand and flags are specified, the new-session command is + assumed. + +QUICK START + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + bind-key b set-option status + bind-key / command-prompt "split-window 'exec man %%'" + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + Some of the default key bindings include: + + c Create new window. + d Detach current client. + l Move to last (previously selected) window in the current ses- + sion. + n Change to next window in the current session. + p Change to previous window in the current session. + t Display a large clock. + ? List current key bindings. + + A complete list may be obtained with the list-keys command (bound to '?' + by default). Key bindings may be changed with the bind-key and + unbind-key commands. + +HISTORY + tmux maintains a configurable history buffer for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command below). + +MODES + A tmux window may be in one of several modes. The default permits direct + access to the terminal attached to the window. The others are: + + output mode + This is entered when a command which produces output, such as + list-keys, is executed from a key binding. + + scroll mode + This is entered with the scroll-mode command (bound to '=' by + default) and permits the window history buffer to be inspected. + + copy mode + This permits a section of a window or its history to be copied to + a paste buffer for later insertion into another window. This + mode is entered with the copy-mode command, bound to ['' by + default. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Start of line 0 or ^ C-a + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + End of line $ C-e + Cursor left h Left + Next page C-f Page down + Next word w M-f + Previous page C-u Page up + Previous word b M-b + Quit mode q Escape + Cursor right l Right + Start selection Space C-Space + Cursor up k Up + Paste buffer p C-y + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + +PANES AND LAYOUTS + Each window displayed by tmux may be split into one or more 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 split-window command. + + Panes are numbered beginning from zero; in horizontal layouts zero is the + leftmost pane and in vertical the topmost. + + Panes may be arranged using several layouts. The layout may be cycled + with the next-layout command (bound to 'C-space' by default), the current + pane may be changed with the up-pane and down-pane commands and the + rotate-window and swap-pane commands may be used to swap panes without + changing the window layout. + + The following layouts are supported: + + active-only + Only the active pane is shown - all other panes are hidden. + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + manual Manual layout splits windows vertically (running across); only + with this layout may panes be resized using the resize-pane com- + mand. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and status-right-length options below), and a central window list. The + window list shows the index, name and (if any) flag of the windows + present in the current session in ascending numerical order. The flag is + one of the following symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session or target-window. These specify the client, session or + window which a command should affect. target-client is the name of the + pty(4) file to which the client is connected, for example /dev/ttyp1. + Clients may be listed with the list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client, target-client, in which + case the session attached to the client is used. An fnmatch(3) pattern + may be used to match the session name. If a session is omitted when + required, tmux attempts to use the current session; if no current session + is available, the most recently created is chosen. If no client is spec- + ified, the current client is chosen, if possible, or an error is + reported. + + target-window specifies a window in the form session:index, for example + mysession:1. The session is in the same form as for target-session. + session, index or both may be omitted. If session is omitted, the same + rules as for target-session are followed; if index is not present, the + current window for the given session is used. When the argument does not + contain a colon, tmux first attempts to parse it as window index; if that + fails, an attempt is made to match a session or client name. + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Examples include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + bind-key D detach-client \; lock-server + + The following commands are available: + + attach-session [-d] [-t target-session] + (alias: attach) + Create a new client in the current terminal and attach it to a + session. If -d is specified, any other clients attached to the + session are detached. + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + bind-key [-r] key command [arguments] + (alias: bind) + Bind key key to command. Keys may be specified prefixed with + 'C-' or '^' for Ctrl keys, or 'M-' for Alt (meta) keys. The -r + flag indicates this key may repeat, see the repeat-time option. + + break-pane [-d] [-p pane-index] [-t target-window] + (alias: breakp) + Break the current pane off from its containing window to make it + the only pane in a new window. If -d is given, the new window + does not become the current window. + + choose-session [-t target-window] + Put a window into session choice mode, where the session for the + current client may be selected interactively from a list. This + command works only from inside tmux. + + choose-window [-t target-window] + Put a window into window choice mode, where the window for the + session attached to the current client may be selected interac- + tively from a list. This command works only from inside tmux. + + clear-history [-p pane-index] [-t target-window] + (alias: clearhist) + Remove and free the history for the specified pane. + + clock-mode [-t target-window] + Display a large clock. + + command-prompt [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command; any %% in the template will + be replaced by what is entered at the prompt. + + confirm-before [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. This command + works only from inside tmux. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + copy-mode [-u] [-t target-window] + Enter copy mode. The -u option scrolls one page up. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + down-pane [-p pane-index] [-t target-window] + (alias: downp) + Move down a pane. + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-pane [-p pane-index] [-t target-window] + (alias: killp) + Destroy the given pane. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-keys + (alias: lsk) + List all key bindings. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + lock-server + (alias: lock) + Lock the server until a password is entered. + + move-window [-d] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-session [-d] [-n window-name] [-s session-name] [command] + (alias: new) + Create a new session with name session-name. The new session is + attached to the current terminal unless -d is given. window-name + and command are the name of and command to execute in the initial + window. + + new-window [-d] [-n window-name] [-t target-window] [command] + (alias: neww) + Create a new window. If -d is given, the session does not make + the new window the current window. target-window represents the + window to be created. command is the command to execute. If + command is not specified, the default command is used. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + paste-buffer [-d] [-b buffer-index] [-t target-window] + (alias: pasteb) + Insert the contents of a paste buffer into the current window. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DU] [-p pane-index] [-t target-window] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default) or downward with -D. + The adjustment is given in lines (the default is 1). + + respawn-window [-k] [-t target-window] [command] + (alias: respawnw) + Reactive a window in which the command has exited (see the + remain-on-exit window option). If command is not given, the com- + mand used when the window was created is executed. The window + must be already inactive, unless -k is given, in which case any + existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + scroll-mode [-u] [-t target-window] + Enter scroll mode. The -u has the same meaning as in the + copy-mode command. + + select-layout [-t target-window] layout-name + (alias: selectl) + Choose a specific layout for a window. + + select-pane [-p pane-index] [-t target-window] + (alias: selectp) + Make pane pane-index the active pane in window target-window. + + select-prompt [-t target-client] + Open a prompt inside target-client allowing a window index to be + entered interactively. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + send-keys [-t target-window] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-window] + Send the prefix key to a window as if it was pressed. + + server-info + (alias: info) + Show server information and terminal details. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + set-option [-gu] [-t target-session] option value + (alias: set) + Set an option. If -g is specified, the option is set as a global + option. Global options apply to all sessions which don't have + the option explicitly set. If -g is not used, the option applies + only to target-session. The -u flag unsets an option, so a ses- + sion inherits the option from the global options - it is not pos- + sible to unset a global option. + + Possible options are: + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command command + Set the command used for new windows (if not specified + when the window is created) to command. The default is + an empty string, which instructs tmux to create a login + shell using the SHELL environment variable or, if it is + unset, the user's shell returned by getpwuid(3). + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is the current working directory when the server is + started. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the server after number seconds of inactivity. The + default is off (set to 0). This has no effect as a ses- + sion option; it must be set as a global option using -g. + + message-attr attributes + Set status line message attributes, where attributes is + either default or a comma-delimited list of one or more + of: bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white or default. + + message-fg colour + Set status line message foreground colour. + + prefix key + Set the current prefix key. + + repeat-time number + Allow multiple commands to be entered without pressing + the prefix-key again in the specified number milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys of the up-pane, + down-pane, resize-pane-up, and resize-pane-down commands. + + set-remain-on-exit [on | off] + Set the remain-on-exit window option for any windows + first created in this session. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code and 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. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. Defaults to emacs. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character pairs: + + Character pair Replaced with + #(command) First line of command's output + #H Hostname of local host + #S Session name + #T Current window title + ## A literal '#' + + Where appropriate, these may be prefixed with a number to + specify the maximum length, for example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display string to the right of the status bar. By + default, the date and time will be shown. As with + status-left, string will be passed to strftime(3), char- + acter pairs are replaced, and UTF-8 is dependent on the + status-utf8 option. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + set-password [-c] password + (alias: pass) + Set the server password. If the -c option is given, a pre- + encrypted password may be specified. By default, the password is + blank, thus any entered password will be accepted when unlocking + the server (see the lock-server command). To prevent variable + expansion when an encrypted password is read from a configuration + file, enclose it in single quotes ('). + + set-window-option [-gu] [-t target-window] option value + (alias: setw) + Set a window-specific option. The -g and -u flags work similarly + to the set-option command. + + Supported options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-width width + + main-pane-height height + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in scroll and copy + modes. Key bindings default to emacs. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + + show-options [-t target-session] option value + (alias: show) + Show the currently set options. If a target-session is speci- + fied, the options for that session are shown; otherwise, the + global options are listed. + + show-window-options [-t target-window] option value + (alias: showw) + List the current options for the given window. + + source-file path + (alias: source) + Execute commands from path. + + split-window [-d] [-l lines | -p percentage] [-t target-window] [command] + (alias: splitw) + Creates a new window by splitting it vertically. The -l and -p + options specify the size of the new window in lines, or as a per- + centage, respectively. All other options have the same meaning + as in the new-window command. + + A few notes with regard to panes: + 1. If attempting to split a window with less than eight lines, + an error will be shown. + 2. If the window is resized, as many panes are shown as can fit + without reducing them below four lines. + 3. The minimum pane size is four lines (including the separator + line). + 4. The panes are indexed from top (0) to bottom, with no num- + bers skipped. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c -target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + swap-pane [-dDU] [-p src-index] [-t target-window] [-q dst-index] + (alias: swapp) + Swap two panes within a window. If -U is used, the pane is + swapped with the pane above (before it numerically); -D swaps + with the pane below (the next numerically); or dst-index may be + give to swap with a specific pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + switch-client [-c target-client -t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. + + unbind-key key + (alias: unbind) + Unbind the key bound to key. + + unlink-window [-t target-window] + (alias: unlinkw) + Unlink target-window. A window may be unlinked only if it is + linked to multiple sessions - windows may not be linked to no + sessions. + + up-pane [-p pane-index] [-t target-window] + (alias: upp) + Move up a pane. + +FILES + ~/.tmux.conf Default tmux configuration file. + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.0.txt b/manual/1.0.txt new file mode 100644 index 0000000..83260ed --- /dev/null +++ b/manual/1.0.txt @@ -0,0 +1,1244 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28dlqUuv] [-f file] [-L socket-name] [-S socket-path] + [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -d Force tmux to assume the terminal supports default colours. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -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. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -q Prevent the server sending various informational messages, + for example when window flags are altered. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -U Unlock the server. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + Some of the default key bindings are: + + c Create a new window. + d Detach the current client. + l Move to the previously selected window. + n Change to the next window. + p Change to the previous window. + & Kill the current window. + , Rename the current window. + ? List all key bindings. + + A complete list may be obtained with the list-keys command (bound to '?' + by default). Key bindings may be changed with the bind-key and + unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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 created is chosen. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Examples include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + bind-key D detach-client \; lock-server + +CLIENTS AND SESSIONS + The following commands are available: + + attach-session [-d] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + new-session [-d] [-n window-name] [-s session-name] [command] + (alias: new) + Create a new session with name session-name. The new session is + attached to the current terminal unless -d is given. window-name + and command are the name of and command to execute in the initial + window. + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. + +WINDOWS AND PANES + A tmux window may be in one of several modes. The default permits direct + access to the terminal attached to the window. The others are: + + output mode + This is entered when a command which produces output, such as + list-keys, is executed from a key binding. + + scroll mode + This is entered with the scroll-mode command (bound to '=' by + default) and permits the window history buffer to be inspected. + + copy mode + This permits a section of a window or its history to be copied to + a paste buffer for later insertion into another window. This + mode is entered with the copy-mode command, bound to ['' by + default. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor up k Up + Delete entire line d C-u + Delete to end of line D C-k + End of line $ C-e + Goto line g g + Next page C-f Page down + Next word w M-f + Paste buffer p C-y + Previous page C-u Page up + Previous word b M-b + Quit mode q Escape + Search again n n + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Transpose chars C-t + + These key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the window-choose command) or in output mode; and vi-copy + and emacs-copy used in copy and scroll modes. The tables may be viewed + with the list-keys command and keys modified or removed with bind-key and + unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The mode commands are as follows: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + scroll-mode [-u] [-t target-pane] + Enter scroll mode. The -u has the same meaning as in the + copy-mode command. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + up-pane and down-pane commands and the rotate-window and swap-pane com- + mands may be used to swap panes without changing their position. Panes + are numbered beginning from zero in the order they are created. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'C-space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time and display-panes-colour session + options. While the indicator is on screen, a pane may be + selected with the '0' to '9' keys. + + down-pane [-t target-pane] + (alias: downp) + Move down a pane. + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + kill-pane [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + move-window [-d] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-dk] [-n window-name] [-t target-window] [command] + (alias: neww) + Create a new window. If -d is given, the session does not make + the new window the current window. target-window represents the + window to be created; if the target already exists an error is + shown, unless the -k flag is used, in which case it is destroyed. + command is the command to execute. If command is not specified, + the default command is used. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-window [-k] [-t target-window] [command] + (alias: respawnw) + Reactive a window in which the command has exited (see the + remain-on-exit window option). If command is not given, the com- + mand used when the window was created is executed. The window + must be already inactive, unless -k is given, in which case any + existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last layout used (if any) is reapplied. + + select-pane [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + split-window [-dhv] [-l size | -p percentage] [-t target-window] + [command] + (alias: splitw) + Creates a new pane by splitting the active pane: -h does a hori- + zontal split and -v a vertical split; if neither is specified, -v + is assumed. The -l and -p options specify the size of the new + window in lines (for vertical split) or in cells (for horizontal + split), or as a percentage, respectively. All other options have + the same meaning as in the new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + + up-pane [-t target-pane] + (alias: upp) + Move up a pane. + +KEY BINDINGS + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. Keys may be specified prefixed with + 'C-' or '^' for Ctrl keys, or 'M-' for Alt (meta) keys. + + By default (without -t) the primary key bindings are modified + (those normally activated with the prefix key); in this case, if + -n is specified, it is not necessary to use the prefix key, + command is bound to key alone. The -r flag indicates this key + may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are enclosed + in square brackets. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-pane] + Send the prefix key to a window as if it was pressed. + + unbind-key [-cn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are two types of option: session options + and window options. + + 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 set-option command + and may be listed with the show-options command. The available session + options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agu] [-t target-session] option value + (alias: set) + Set a session option. With -a, and if the option expects a + string, value is appended to the existing setting. If -g is + specified, the global session option is set. The -u flag unsets + an option, so a session inherits the option from the global + options - it is not possible to unset a global option. + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command command + Set the command used for new windows (if not specified + when the window is created) to command, which may be any + sh(1) command. The default is an empty string, which + instructs tmux to create a login shell using the value of + the default-shell option. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is the current working directory when the server is + started. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + display-panes-colour colour + Set the colour used for the display-panes command. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the server after number seconds of inactivity. The + default is off (set to 0). This has no effect as a ses- + sion option; it must be set as a global option using -g. + When passwords are entered incorrectly, tmux follows the + behaviour of login(1) and ignores further password + attempts for an increasing timeout. + + message-attr attributes + Set status line message attributes, where attributes is + either default or a comma-delimited list of one or more + of: bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, colour0 to colour255 from the 256-colour + palette, or default. + + message-fg colour + Set status line message foreground colour. + + prefix key + Set the current prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the remain-on-exit window option for any windows + first created in this session. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. Defaults to emacs. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(command) First line of command's output + #[attributes] Colour or attribute change + #H Hostname of local host + #I Current window index + #P Current pane index + #S Session name + #T Current window title + #W Current window name + ## A literal '#' + + The #(command) form executes 'command' as a shell command + and inserts the first line of its output. #[attributes] + allows a comma-separated list of attributes to be speci- + fied, these may be 'fg=colour' to set the foreground + colour, 'bg=colour' to set the background colour, or one + of the attributes described under the message-attr + option. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, these may be prefixed with a number to + specify the maximum length, for example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display string to the right of the status bar. By + default, the date and time will be shown. As with + status-left, string will be passed to strftime(3), char- + acter pairs are replaced, and UTF-8 is dependent on the + status-utf8 option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY WINDOWID SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-width width + main-pane-height height + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in scroll, copy and + choice modes. Key bindings default to emacs. + + mode-mouse [on | off] + Mouse state in modes. If on, tmux will respond to mouse + clicks by moving the cursor in copy mode or selecting an + option in choice mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. + + show-options [-g] [-t target-session] + (alias: show) + Show the session options for target session, or the global ses- + sion options with -g. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a session environment. When a + window is created, the session and global environments are merged with + the session environment overriding any variable present in both. This is + the initial environment passed to the new process. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and status-right-length options below), and a central window list. The + window list shows the index, name and (if any) flag of the windows + present in the current session in ascending numerical order. The flag is + one of the following symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command. If -p is given, prompts is + a comma-separated list of prompts which are displayed in order; + otherwise a single prompt is displayed, constructed from template + if it is present, or ':' if not. Before the command is executed, + the first occurrence of the string '%%' and all occurrences of + '%1' are replaced by the response to the first prompt, the second + '%%' and all '%2' are replaced with the response to the second + prompt, and so on for further prompts. Up to nine prompt + responses may be replaced ('%1' to '%9'). + + confirm-before [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. This command + works only from inside tmux. + + display-message [-t target-client] [message] + (alias: display) + Display a message (see the status-left option below) in the sta- + tus line. + + select-prompt [-t target-client] + Open a prompt inside target-client allowing a window index to be + entered interactively. + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-t target-window] + (alias: pasteb) + Insert the contents of a paste buffer into the current window. + With -d, also delete the paste buffer from the stack. When out- + put, any linefeed (LF) characters in the paste buffer are + replaced with carriage returns (CR). This translation may be + disabled with the -r flag. + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command + (alias: if) + Execute command if shell-command returns success. + + lock-server + (alias: lock) + Lock the server until a password is entered. + + server-info + (alias: info) + Show server information and terminal details. + + set-password [-c] password + (alias: pass) + Set the server password. If the -c option is given, a pre- + encrypted password may be specified. By default, the password is + blank, thus any entered password will be accepted when unlocking + the server (see the lock-server command). To prevent variable + expansion when an encrypted password is read from a configuration + file, enclose it in single quotes ('). + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.1.txt b/manual/1.1.txt new file mode 100644 index 0000000..ca93ff6 --- /dev/null +++ b/manual/1.1.txt @@ -0,0 +1,1313 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquv] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -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. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -q Prevent the server sending various informational messages, + for example when window flags are altered. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + Some of the default key bindings are: + + c Create a new window. + d Detach the current client. + l Move to the previously selected window. + n Change to the next window. + p Change to the previous window. + & Kill the current window. + , Rename the current window. + ? List all key bindings. + + A complete list may be obtained with the list-keys command (bound to '?' + by default). Key bindings may be changed with the bind-key and + unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Examples include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + +CLIENTS AND SESSIONS + The following commands are available: + + attach-session [-d] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + lock-client [-t target-client] + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [command] + (alias: new) + Create a new session with name session-name. The new session is + attached to the current terminal unless -d is given. window-name + and command are the name of and command to execute in the initial + window. + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or command are invalid if -t is used. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. + +WINDOWS AND PANES + A tmux window may be in one of several modes. The default permits direct + access to the terminal attached to the window. The others are: + + output mode + This is entered when a command which produces output, such as + list-keys, is executed from a key binding. + + copy mode + This permits a section of a window or its history to be copied to + a paste buffer for later insertion into another window. This + mode is entered with the copy-mode command, bound to '[' by + default. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete to end of line D C-k + End of line $ C-e + Goto line : g + Half page down C-d M-Down + Half page up C-u M-Up + Next page C-f Page down + Next word w M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Quit mode q Escape + Scroll down C-Down or J C-Down + Scroll up C-Up or K C-Up + Search again n n + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Transpose chars C-t + + These key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the window-choose command) or in output mode; and vi-copy + and emacs-copy used in copy mode. The tables may be viewed with the + list-keys command and keys modified or removed with bind-key and + unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The mode commands are as follows: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + up-pane and down-pane commands and the rotate-window and swap-pane com- + mands may be used to swap panes without changing their position. Panes + are numbered beginning from zero in the order they are created. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'C-space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time and display-panes-colour session + options. While the indicator is on screen, a pane may be + selected with the '0' to '9' keys. + + down-pane [-t target-pane] + (alias: downp) + Change the active pane to the next pane (higher index). + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-t target-window] + (alias: lsp) + List the panes in the current window or in target-window. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + move-window [-d] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-dk] [-n window-name] [-t target-window] [command] + (alias: neww) + Create a new window. If -d is given, the session does not make + the new window the current window. target-window represents the + window to be created; if the target already exists an error is + shown, unless the -k flag is used, in which case it is destroyed. + command is the command to execute. If command is not specified, + the default command is used. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + pipe-pane [-o] [-t target-pane] [command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before command is executed. If no + command is given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output' + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-window [-k] [-t target-window] [command] + (alias: respawnw) + Reactive a window in which the command has exited (see the + remain-on-exit window option). If command is not given, the com- + mand used when the window was created is executed. The window + must be already inactive, unless -k is given, in which case any + existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last layout used (if any) is reapplied. + + select-pane [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + split-window [-dhv] [-l size | -p percentage] [-t target-window] + [command] + (alias: splitw) + Creates a new pane by splitting the active pane: -h does a hori- + zontal split and -v a vertical split; if neither is specified, -v + is assumed. The -l and -p options specify the size of the new + window in lines (for vertical split) or in cells (for horizontal + split), or as a percentage, respectively. All other options have + the same meaning as in the new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + + up-pane [-t target-pane] + (alias: upp) + Change the active pane to the previous pane (lower index). + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: BSpace, + BTab, DC (Delete), End, Enter, Escape, F1 to F20, Home, IC (Insert), + NPage (Page Up), PPage (Page Down), Space, and Tab. Note that to bind + the '"' or ''' keys, quotation marks are necessary, for example: + + bind-key '"' split-window + bind-key "'" select-prompt + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are enclosed + in square brackets. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-pane] + Send the prefix key to a window as if it was pressed. If multi- + ple prefix keys are configured, only the first is sent. + + unbind-key [-cn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are two types of option: session options + and window options. + + 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 set-option command + and may be listed with the show-options command. The available session + options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agu] [-t target-session] option value + (alias: set) + Set a session option. With -a, and if the option expects a + string, value is appended to the existing setting. If -g is + specified, the global session option is set. The -u flag unsets + an option, so a session inherits the option from the global + options - it is not possible to unset a global option. + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command command + Set the command used for new windows (if not specified + when the window is created) to command, which may be any + sh(1) command. The default is an empty string, which + instructs tmux to create a login shell using the value of + the default-shell option. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is the current working directory when the server is + started. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + display-panes-colour colour + Set the colour used for the display-panes command. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either default or a comma-delimited list of one or more + of: bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, colour0 to colour255 from the 256-colour + palette, or default. + + message-fg colour + Set status line message foreground colour. + + mouse-select-pane [on | off] + If on, tmux 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. + + prefix keys + Set the keys accepted as a prefix key. keys is a comma- + separated list of key names, each of which individually + behave as the prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the remain-on-exit window option for any windows + first created in this session. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. Defaults to emacs. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(command) First line of command's output + #[attributes] Colour or attribute change + #H Hostname of local host + #I Current window index + #P Current pane index + #S Session name + #T Current window title + #W Current window name + ## A literal '#' + + The #(command) form executes 'command' as a shell command + and inserts the first line of its output. Note that + shell commands are only executed once at the interval + specified by the status-interval option: if the status + line is redrawn in the meantime, the previous result is + used. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display string to the right of the status bar. By + default, the date and time will be shown. As with + status-left, string will be passed to strftime(3), char- + acter pairs are replaced, and UTF-8 is dependent on the + status-utf8 option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY WINDOWID SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-width width + main-pane-height height + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. Key bindings default to emacs. + + mode-mouse [on | off] + Mouse state in modes. If on, tmux will respond to mouse + clicks by moving the cursor in copy mode or selecting an + option in choice mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window, except for panes that are not in output + mode. + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. + + show-options [-g] [-t target-session] + (alias: show) + Show the session options for target session, or the global ses- + sion options with -g. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a session environment. When a + window is created, the session and global environments are merged with + the session environment overriding any variable present in both. This is + the initial environment passed to the new process. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and status-right-length options below), and a central window list. The + window list shows the index, name and (if any) flag of the windows + present in the current session in ascending numerical order. The flag is + one of the following symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command. If -p is given, prompts is + a comma-separated list of prompts which are displayed in order; + otherwise a single prompt is displayed, constructed from template + if it is present, or ':' if not. Before the command is executed, + the first occurrence of the string '%%' and all occurrences of + '%1' are replaced by the response to the first prompt, the second + '%%' and all '%2' are replaced with the response to the second + prompt, and so on for further prompts. Up to nine prompt + responses may be replaced ('%1' to '%9'). + + confirm-before [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. This command + works only from inside tmux. + + display-message [-t target-client] [message] + (alias: display) + Display a message (see the status-left option below) in the sta- + tus line. + + select-prompt [-t target-client] + Open a prompt inside target-client allowing a window index to be + entered interactively. + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-t target-window] + (alias: pasteb) + Insert the contents of a paste buffer into the current window. + With -d, also delete the paste buffer from the stack. When out- + put, any linefeed (LF) characters in the paste buffer are + replaced with carriage returns (CR). This translation may be + disabled with the -r flag. + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command + (alias: if) + Execute command if shell-command returns success. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell command + (alias: run) + Execute command in the background without creating a window. + After the command finishes, any output to stdout is displayed in + output mode. If command doesn't return success, the exit status + is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.2.txt b/manual/1.2.txt new file mode 100644 index 0000000..c76e162 --- /dev/null +++ b/manual/1.2.txt @@ -0,0 +1,1473 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquv] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -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. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + Some of the default key bindings are: + + c Create a new window. + d Detach the current client. + l Move to the previously selected window. + n Change to the next window. + p Change to the previous window. + & Kill the current window. + , Rename the current window. + ? List all key bindings. + + A complete list may be obtained with the list-keys command (bound to '?' + by default). Key bindings may be changed with the bind-key and + unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. The special character '!' uses the last + (previously current) window, or '+' and '-' are the next window or the + previous window by number. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. One of the strings top, bottom, + left, right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Example tmux commands include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one of more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client command have any + effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + lock-client [-t target-client] + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. + +WINDOWS AND PANES + A tmux window may be in one of several modes. The default permits direct + access to the terminal attached to the window. The others are: + + output mode + This is entered when a command which produces output, such as + list-keys, is executed from a key binding. + + copy mode + This permits a section of a window or its history to be copied to + a paste buffer for later insertion into another window. This + mode is entered with the copy-mode command, bound to '[' by + default. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose chars C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the word-separators window 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. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command) or in output mode; and vi-copy + and emacs-copy used in copy mode. The tables may be viewed with the + list-keys command and keys modified or removed with bind-key and + unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The mode commands are as follows: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + up-pane and down-pane commands and the rotate-window and swap-pane com- + mands may be used to swap panes without changing their position. Panes + are numbered beginning from zero in the order they are created. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + capture-pane [-b buffer-index] [-t target-pane] + (alias: capturep) + Capture the contents of a pane to the specified buffer, or a new + buffer if none is specified. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + down-pane [-t target-pane] + (alias: downp) + Change the active pane to the next pane (higher index). + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + join-pane [-dhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-t target-window] + (alias: lsp) + List the panes in the current window or in target-window. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + move-window [-d] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-dk] [-n window-name] [-t target-window] [shell-command] + (alias: neww) + Create a new window. If -d is given, the session does not make + the new window the current window. target-window represents the + window to be created; if the target already exists an error is + shown, unless the -k flag is used, in which case it is destroyed. + shell-command is the command to execute. If shell-command is not + specified, the value of the default-command option is used. + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. If no + shell-command is given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output' + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last layout used (if any) is reapplied. + + select-pane [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + split-window [-dhv] [-l size | -p percentage] [-t target-pane] + [shell-command] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + + up-pane [-t target-pane] + (alias: upp) + Change the active pane to the previous pane (lower index). + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage (Page Up), PPage (Page Down), Space, and + Tab. Note that to bind the '"' or ''' keys, quotation marks are neces- + sary, for example: + + bind-key '"' split-window + bind-key "'" select-prompt + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are marked + with '(no prefix)'. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-pane] + Send the prefix key to a window as if it was pressed. If multi- + ple prefix keys are configured, only the first is sent. + + unbind-key [-cn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + Available window options are listed under set-window-option. + + Available server options are: + + escape-time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + quiet Enable or disable the display of various informational + messages (see also the -q command line flag). + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is the current working directory when the server is + started. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either default or a comma-delimited list of one or more + of: bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, colour0 to colour255 from the 256-colour + palette, or default. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-select-pane [on | off] + If on, tmux 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. + + pane-border-fg colour + + pane-border-bg colour + Set the pane border colour for panes aside from the + active pane. + + pane-active-border-fg colour + + pane-active-border-bg colour + Set the pane border colour for the currently active pane. + + prefix keys + Set the keys accepted as a prefix key. keys is a comma- + separated list of key names, each of which individually + behave as the prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. Defaults to emacs. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #F Current window flag + #I Current window index + #P Current pane index + #S Session name + #T Current window title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY WINDOWID SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-width width + main-pane-height height + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. Key bindings default to emacs. + + mode-mouse [on | off] + Mouse state in modes. If on, tmux will respond to mouse + clicks by moving the cursor in copy mode or selecting an + option in choice mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window, except for panes that are not in output + mode. + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup terminfo(5) capabilities to be + issued to preserve the existing window content on start + and restore it on exit. + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + word-separators string + Sets the window's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + show-options [-gsw] [-t target-session | target-window] + (alias: show) + Show the window options with -w (equivalent to + show-window-options), the server options with -s, otherwise the + session options for target session. Global session or window + options are listed if -g is used. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a session environment. When a + window is created, the session and global environments are merged with + the session environment overriding any variable present in both. This is + the initial environment passed to the new process. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command. If -p is given, prompts is + a comma-separated list of prompts which are displayed in order; + otherwise a single prompt is displayed, constructed from template + if it is present, or ':' if not. Before the command is executed, + the first occurrence of the string '%%' and all occurrences of + '%1' are replaced by the response to the first prompt, the second + '%%' and all '%2' are replaced with the response to the second + prompt, and so on for further prompts. Up to nine prompt + responses may be replaced ('%1' to '%9'). + + confirm-before [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. This command + works only from inside tmux. + + display-message [-p] [-t target-client] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is as for status-left, with the exception + that #() are not handled. + + select-prompt [-t target-client] + Open a prompt inside target-client allowing a window index to be + entered interactively. + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-t target-window] + (alias: pasteb) + Insert the contents of a paste buffer into the current window. + With -d, also delete the paste buffer from the stack. When out- + put, any linefeed (LF) characters in the paste buffer are + replaced with carriage returns (CR). This translation may be + disabled with the -r flag. + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command + (alias: if) + Execute command if shell-command returns success. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. After it finishes, any output to stdout is displayed in + output mode. If the command doesn't return success, the exit + status is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.3.txt b/manual/1.3.txt new file mode 100644 index 0000000..7397d6b --- /dev/null +++ b/manual/1.3.txt @@ -0,0 +1,1585 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquv] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -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. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the tmux client. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the tmux command prompt. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from tmux, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the bind-key and unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. The special character '!' uses the last + (previously current) window, or '+' and '-' are the next window or the + previous window by number. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. A '+' or '-' indicate the next or + previous pane index, respectively. One of the strings top, bottom, left, + right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + The special characters '+' and '-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Example tmux commands include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one of more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client command have any + effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + lock-client [-t target-client] + (alias: lockc) + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + (alias: locks) + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. + +WINDOWS AND PANES + A tmux 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 + paste buffer for later insertion into another window. This mode is + entered with the copy-mode command, bound to '[' by default. It is also + entered when a command that produces output, such as list-keys, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump backward F F + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose chars C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the word-separators window 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. + + The jump commands enable quick movement within a line. For instance, + typing 'f' followed by '/' will move the cursor to the next '/' character + on the current line. A ';' will then jump to the next occurrence. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command); and vi-copy and emacs-copy + used in copy mode. The tables may be viewed with the list-keys command + and keys modified or removed with bind-key and unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the copy-mode command is: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + select-pane command and the rotate-window and 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. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + tiled Panes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, select-layout may be used to apply a previously used layout + - the list-windows command displays the layout of each window in a form + suitable for use with select-layout. For example: + + $ 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} + tmux 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. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + capture-pane [-b buffer-index] [-t target-pane] + (alias: capturep) + Capture the contents of a pane to the specified buffer, or a new + buffer if none is specified. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + join-pane [-dhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-t target-window] + (alias: lsp) + List the panes in the current window or in target-window. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + move-window [-dk] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-adk] [-n window-name] [-t target-window] [shell-command] + (alias: neww) + Create a new window. With -a, the new window is inserted at the + next index up from the specified target-window, moving windows up + if necessary, otherwise target-window is the new window location. + + If -d is given, the session does not make the new window the cur- + rent window. target-window represents the window to be created; + if the target already exists an error is shown, unless the -k + flag is used, in which case it is destroyed. shell-command is + the command to execute. If shell-command is not specified, the + value of the default-command option is used. + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. The + shell-command string may contain the special character sequences + supported by the status-left command. If no shell-command is + given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + previous-layout [-t target-window] + (alias: prevl) + Move to the previous layout in the session. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last preset layout used (if any) is reapplied. + + select-pane [-DLRU] [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + If one of -D, -L, -R, or -U is used, respectively the pane below, + to the left, to the right, or above the target pane is used. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + split-window [-dhv] [-l size | -p percentage] [-t target-pane] + [shell-command] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage (Page Up), PPage (Page Down), Space, and + Tab. Note that to bind the '"' or ''' keys, quotation marks are neces- + sary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are marked + with '(no prefix)'. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-pane] + Send the prefix key to a window as if it was pressed. If multi- + ple prefix keys are configured, only the first is sent. + + unbind-key [-cn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + Available window options are listed under set-window-option. + + Available server options are: + + detach-on-destroy + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + escape-time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + quiet Enable or disable the display of various informational + messages (see also the -q command line flag). + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is empty, which means to use the working directory of the + shell from which the server was started if it is avail- + able or the user's home if not. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either none or a comma-delimited list of one or more of: + bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, colour0 to colour255 from the 256-colour + palette, or default. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-select-pane [on | off] + If on, tmux 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. + + pane-border-fg colour + + pane-border-bg colour + Set the pane border colour for panes aside from the + active pane. + + pane-active-border-fg colour + + pane-active-border-bg colour + Set the pane border colour for the currently active pane. + + prefix keys + Set the keys accepted as a prefix key. keys is a comma- + separated list of key names, each of which individually + behave as the prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. Defaults to emacs. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #F Current window flag + #I Current window index + #P Current pane index + #S Session name + #T Current window title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the tmux global environ- + ment set (see the ENVIRONMENT section). + + The window title (#T) is the title set by the program + running within the window using the OSC title setting + sequence, for example: + + $ printf '\033]2;My Title\033\\' + + When a window is first created, its title is the host- + name. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY WINDOWID SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-width width + main-pane-height height + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. Key bindings default to emacs. + + mode-mouse [on | off] + Mouse state in modes. If on, the mouse may be used to + copy a selection by dragging in copy mode, or to select + an option in choice mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup terminfo(5) capabilities to be + issued to preserve the existing window content on start + and restore it on exit. + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + window-status-alert-attr attributes + Set status line attributes for windows which have an + alert (bell, activity or content). + + window-status-alert-bg colour + Set status line background colour for windows with an + alert. + + window-status-alert-fg colour + Set status line foreground colour for windows with an + alert. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + word-separators string + Sets the window's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + show-options [-gsw] [-t target-session | target-window] + (alias: show) + Show the window options with -w (equivalent to + show-window-options), the server options with -s, otherwise the + session options for target session. Global session or window + options are listed if -g is used. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a session environment. When a + window is created, the session and global environments are merged with + the session environment overriding any variable present in both. This is + the initial environment passed to the new process. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command. If -p is given, prompts is + a comma-separated list of prompts which are displayed in order; + otherwise a single prompt is displayed, constructed from template + if it is present, or ':' if not. Before the command is executed, + the first occurrence of the string '%%' and all occurrences of + '%1' are replaced by the response to the first prompt, the second + '%%' and all '%2' are replaced with the response to the second + prompt, and so on for further prompts. Up to nine prompt + responses may be replaced ('%1' to '%9'). + + confirm-before [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. This command + works only from inside tmux. + + display-message [-p] [-t target-client] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is as for status-left, with the exception + that #() are not handled. + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + choose-buffer [-t target-window] [template] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, '%%' + is replaced by the buffer index in template and the result exe- + cuted as a command. If template is not given, "paste-buffer -b + '%%'" is used. This command works only from inside tmux. + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-s separator] [-t target-pane] + (alias: pasteb) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With -d, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the -s flag. The -r flag means to do no + replacement (equivalent to a separator of LF). + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command + (alias: if) + Execute command if shell-command returns success. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. After it finishes, any output to stdout is displayed in + copy mode. If the command doesn't return success, the exit sta- + tus is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.4.txt b/manual/1.4.txt new file mode 100644 index 0000000..534902a --- /dev/null +++ b/manual/1.4.txt @@ -0,0 +1,1633 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquvV] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -L socket-name + tmux stores the server socket in a directory under /tmp; + the default socket is named default. This option allows a + different socket name to be specified, allowing several + independent tmux servers to be run. Unlike -S a full path + is not necessary: the sockets are all created in the same + directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -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. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + -V Report the tmux version. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the tmux client. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the tmux command prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from tmux, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the bind-key and unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. The special character '!' uses the last + (previously current) window, or '+' and '-' are the next window or the + previous window by number. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. A '+' or '-' indicate the next or + previous pane index, respectively. One of the strings top, bottom, left, + right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + The special characters '+' and '-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Example tmux commands include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one or more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client command have any + effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + detach-client [-t target-client] + (alias: detach) + Detach the current client if bound to a key, or the specified + client with -t. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients + (alias: lsc) + List all clients attached to the server. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + lock-client [-t target-client] + (alias: lockc) + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + (alias: locks) + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-c target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-lnp] [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. If -l, -n or -p is used, the client is moved to + the last, next or previous session respectively. + +WINDOWS AND PANES + A tmux 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 + paste buffer for later insertion into another window. This mode is + entered with the copy-mode command, bound to '[' by default. It is also + entered when a command that produces output, such as list-keys, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump backward F F + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose chars C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the word-separators window 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. + + The jump commands enable quick movement within a line. For instance, + typing 'f' followed by '/' will move the cursor to the next '/' character + on the current line. A ';' will then jump to the next occurrence. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command); and vi-copy and emacs-copy + used in copy mode. The tables may be viewed with the list-keys command + and keys modified or removed with bind-key and unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the copy-mode command is: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + select-pane command and the rotate-window and 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. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + tiled Panes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, select-layout may be used to apply a previously used layout + - the list-windows command displays the layout of each window in a form + suitable for use with select-layout. For example: + + $ 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} + + tmux 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. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + capture-pane [-b buffer-index] [-t target-pane] + (alias: capturep) + Capture the contents of a pane to the specified buffer, or a new + buffer if none is specified. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + join-pane [-dhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-pane [-t target-window] + (alias: lastp) + Select the last (previously selected) pane. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-t target-window] + (alias: lsp) + List the panes in the current window or in target-window. + + list-windows [-t target-session] + (alias: lsw) + List windows in the current session or in target-session. + + move-window [-dk] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-adk] [-n window-name] [-t target-window] [shell-command] + (alias: neww) + Create a new window. With -a, the new window is inserted at the + next index up from the specified target-window, moving windows up + if necessary, otherwise target-window is the new window location. + + If -d is given, the session does not make the new window the cur- + rent window. target-window represents the window to be created; + if the target already exists an error is shown, unless the -k + flag is used, in which case it is destroyed. shell-command is + the command to execute. If shell-command is not specified, the + value of the default-command option is used. + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. The + shell-command string may contain the special character sequences + supported by the status-left command. If no shell-command is + given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + previous-layout [-t target-window] + (alias: prevl) + Move to the previous layout in the session. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last preset layout used (if any) is reapplied. + + select-pane [-DLRU] [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + If one of -D, -L, -R, or -U is used, respectively the pane below, + to the left, to the right, or above the target pane is used. + + select-window [-t target-window] + (alias: selectw) + Select the window at target-window. + + split-window [-dhv] [-l size | -p percentage] [-t target-pane] + [shell-command] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage (Page Up), PPage (Page Down), Space, and + Tab. Note that to bind the '"' or ''' keys, quotation marks are neces- + sary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are marked + with '(no prefix)'. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-pane] + Send the prefix key to a window as if it was pressed. If multi- + ple prefix keys are configured, only the first is sent. + + unbind-key [-acn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. If -a is + present, all key bindings are removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + Available window options are listed under set-window-option. + + Available server options are: + + escape-time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + exit-unattached + If enabled, the server will exit when there are no + attached clients, rather than when there are no attached + sessions. + + quiet Enable or disable the display of various informational + messages (see also the -q command line flag). + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + buffer-limit number + Set the number of buffers kept for each session; 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. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is empty, which means to use the working directory of the + shell from which the server was started if it is avail- + able or the user's home if not. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + destroy-unattached + If enabled and the session is no longer attached to any + clients, it is destroyed. + + detach-on-destroy + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either none or a comma-delimited list of one or more of: + bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, colour0 to colour255 from the 256-colour + palette, or default. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-select-pane [on | off] + If on, tmux 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. + + pane-active-border-bg colour + + pane-active-border-fg colour + Set the pane border colour for the currently active pane. + + pane-border-bg colour + + pane-border-fg colour + Set the pane border colour for panes aside from the + active pane. + + prefix keys + Set the keys accepted as a prefix key. keys is a comma- + separated list of key names, each of which individually + behave as the prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string 'vi'. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #F Current window flag + #I Current window index + #P Current pane index + #S Session name + #T Current window title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the tmux global environ- + ment set (see the ENVIRONMENT section). + + The window title (#T) is the title set by the program + running within the window using the OSC title setting + sequence, for example: + + $ printf '\033]2;My Title\033\\' + + When a window is first created, its title is the host- + name. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + visual-silence [on | off] + If monitor-silence is enabled, prints a message after the + interval has expired on a given window. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup terminfo(5) capabilities to be + issued to preserve the existing window content on start + and restore it on exit. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-height height + main-pane-width width + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. As with the status-keys option, the default is + emacs, unless VISUAL or EDITOR contains 'vi'. + + mode-mouse [on | off] + Mouse state in modes. If on, the mouse may be used to + copy a selection by dragging in copy mode, or to select + an option in choice mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + monitor-silence [interval] + Monitor for silence (no activity) in the window within + interval seconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + other-pane-height height + Set the height of the other panes (not the main pane) in + the main-horizontal layout. If this option is set to 0 + (the default), it will have no effect. If both the + main-pane-height and 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. + + other-pane-width width + Like other-pane-height, but set the width of other panes + in the main-vertical layout. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + window-status-alert-attr attributes + Set status line attributes for windows which have an + alert (bell, activity or content). + + window-status-alert-bg colour + Set status line background colour for windows with an + alert. + + window-status-alert-fg colour + Set status line foreground colour for windows with an + alert. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + word-separators string + Sets the window's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + show-options [-gsw] [-t target-session | target-window] + (alias: show) + Show the window options with -w (equivalent to + show-window-options), the server options with -s, otherwise the + session options for target session. Global session or window + options are listed if -g is used. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a 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. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. If template is + specified, it is used as the command. If -p is given, prompts is + a comma-separated list of prompts which are displayed in order; + otherwise a single prompt is displayed, constructed from template + if it is present, or ':' if not. Before the command is executed, + the first occurrence of the string '%%' and all occurrences of + '%1' are replaced by the response to the first prompt, the second + '%%' and all '%2' are replaced with the response to the second + prompt, and so on for further prompts. Up to nine prompt + responses may be replaced ('%1' to '%9'). + + confirm-before [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. This command + works only from inside tmux. + + display-message [-p] [-t target-client] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is as for status-left, with the exception + that #() are not handled. + +BUFFERS + tmux maintains a stack of paste buffers for each session. Up to the + value of the 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 copy-mode or the set-buffer command, and pasted into a window using + the paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + choose-buffer [-t target-window] [template] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, '%%' + is replaced by the buffer index in template and the result exe- + cuted as a command. If template is not given, "paste-buffer -b + '%%'" is used. This command works only from inside tmux. + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + copy-buffer [-a src-index] [-b dst-index] [-s src-session] [-t + dst-session] + (alias: copyb) + Copy a session paste buffer to another session. If no sessions + are specified, the current one is used instead. + + delete-buffer [-b buffer-index] [-t target-session] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-t target-session] + (alias: lsb) + List the buffers in the given session. + + load-buffer [-b buffer-index] [-t target-session] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-s separator] [-t target-pane] + (alias: pasteb) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With -d, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the -s flag. The -r flag means to do no + replacement (equivalent to a separator of LF). + + save-buffer [-a] [-b buffer-index] [-t target-session] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] [-t target-session] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] [-t target-session] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command + (alias: if) + Execute command if shell-command returns success. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. After it finishes, any output to stdout is displayed in + copy mode. If the command doesn't return success, the exit sta- + tus is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.5.txt b/manual/1.5.txt new file mode 100644 index 0000000..6e96fa9 --- /dev/null +++ b/manual/1.5.txt @@ -0,0 +1,1741 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquvV] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -L socket-name + tmux stores the server socket in a directory under /tmp (or + TMPDIR if set); the default socket is named default. This + option allows a different socket name to be specified, + allowing several independent tmux servers to be run. + Unlike -S a full path is not necessary: the sockets are all + created in the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -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. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + -V Report the tmux version. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the tmux client. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the tmux command prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from tmux, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the bind-key and unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. The special character '!' uses the last + (previously current) window, or '+' and '-' are the next window or the + previous window by number. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. A '+' or '-' indicate the next or + previous pane index, respectively. One of the strings top, bottom, left, + right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + The special characters '+' and '-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + tmux also gives each pane created in a server an identifier consisting of + a '%' and a number, starting from zero. A pane's identifier is unique + for the life of the tmux server and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a command + sequence. Each command should be separated by spaces and a semicolon; + commands are executed sequentially from left to right. A literal semi- + colon may be included by escaping it with a backslash (for example, when + specifying a command sequence to bind-key). + + Example tmux commands include: + + refresh-client -t/dev/ttyp2 + + rename-session -tfirst newname + + set-window-option -t:0 monitor-activity on + + new-window ; split-window -d + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one or more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client command have any + effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The target-session rules for attach-session are slightly + adjusted: if tmux needs to select the most recently used session, + it will prefer the most recently used unattached session. + + detach-client [-P] [-s target-session] [-t target-client] + (alias: detach) + Detach the current client if bound to a key, the client specified + with -t, or all clients currently attached to to the session + specified by -s. If -P is given, send SIGHUP to the parent + process of the client, typically causing it to exit. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients [-t target-session] + (alias: lsc) + List all clients attached to the server. If target-session is + specified, list only clients connected to that session. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions + (alias: ls) + List all sessions managed by the server. + + lock-client [-t target-client] + (alias: lockc) + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + (alias: locks) + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [-x width] [-y height] [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. If -d is used, -x and + -y specify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + refresh-client [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-t target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-lnp] [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. If -l, -n or -p is used, the client is moved to + the last, next or previous session respectively. + +WINDOWS AND PANES + A tmux 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 + paste buffer for later insertion into another window. This mode is + entered with the copy-mode command, bound to '[' by default. It is also + entered when a command that produces output, such as list-keys, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump backward F F + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose chars C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the word-separators window 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. + + The jump commands enable quick movement within a line. For instance, + typing 'f' followed by '/' will move the cursor to the next '/' character + on the current line. A ';' will then jump to the next occurrence. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command); and vi-copy and emacs-copy + used in copy mode. The tables may be viewed with the list-keys command + and keys modified or removed with bind-key and unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the copy-mode command is: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + select-pane command and the rotate-window and 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. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + tiled Panes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, select-layout may be used to apply a previously used layout + - the list-windows command displays the layout of each window in a form + suitable for use with select-layout. For example: + + $ 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} + + tmux 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. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + capture-pane [-b buffer-index] [-E end-line] [-S start-line] [-t + target-pane] + (alias: capturep) + Capture the contents of a pane to the specified buffer, or a new + buffer if none is specified. + + -S and -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 con- + tents of the pane. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + join-pane [-dhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-pane [-t target-window] + (alias: lastp) + Select the last (previously selected) pane. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-as] [-t target] + (alias: lsp) + If -a is given, target is ignored and all panes on the server are + listed. If -s is given, target is a session (or the current ses- + sion). If neither is given, target is a window (or the current + window). + + list-windows [-a] [-t target-session] + (alias: lsw) + If -a is given, list all windows on the server. Otherwise, list + windows in the current session or in target-session. + + move-window [-dk] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-adkP] [-n window-name] [-t target-window] [shell-command] + (alias: neww) + Create a new window. With -a, the new window is inserted at the + next index up from the specified target-window, moving windows up + if necessary, otherwise target-window is the new window location. + + If -d is given, the session does not make the new window the cur- + rent window. target-window represents the window to be created; + if the target already exists an error is shown, unless the -k + flag is used, in which case it is destroyed. shell-command is + the command to execute. If shell-command is not specified, the + value of the default-command option is used. + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The -P option prints the location of the new window after it has + been created. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. The + shell-command string may contain the special character sequences + supported by the status-left option. If no shell-command is + given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + previous-layout [-t target-window] + (alias: prevl) + Move to the previous layout in the session. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-pane [-k] [-t target-pane] [shell-command] + (alias: respawnp) + Reactivate a pane in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless -k is given, in which case any + existing command is killed. + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-np] [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last preset layout used (if any) is reapplied. -n and + -p are equivalent to the next-layout and previous-layout com- + mands. + + select-pane [-lDLRU] [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + If one of -D, -L, -R, or -U is used, respectively the pane below, + to the left, to the right, or above the target pane is used. -l + is the same as using the last-pane command. + + select-window [-lnp] [-t target-window] + (alias: selectw) + Select the window at target-window. -l, -n and -p are equivalent + to the last-window, next-window and previous-window commands. + + split-window [-dhvP] [-l size | -p percentage] [-t target-pane] + [shell-command] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage (Page Up), PPage (Page Down), Space, and + Tab. Note that to bind the '"' or ''' keys, quotation marks are neces- + sary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are marked + with '(no prefix)'. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. + + send-prefix [-t target-pane] + Send the prefix key to a window as if it was pressed. If multi- + ple prefix keys are configured, only the first is sent. + + unbind-key [-acn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. If -a is + present, all key bindings are removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + Available window options are listed under set-window-option. + + Available server options are: + + buffer-limit number + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + set-clipboard [on | off] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an Ms entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + escape-time time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + exit-unattached [on | off] + If enabled, the server will exit when there are no + attached clients. + + quiet [on | off] + Enable or disable the display of various informational + messages (see also the -q command line flag). + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + bell-on-alert [on | off] + If on, ring the terminal bell when an activity, content + or silence alert occurs. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-path path + Set the default working directory for processes created + from keys, or interactively from the prompt. The default + is empty, which means to use the working directory of the + shell from which the server was started if it is avail- + able or the user's home if not. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + destroy-unattached [on | off] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + detach-on-destroy [on | off] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either none or a comma-delimited list of one or more of: + bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, colour0 to colour255 from the 256-colour + set, default, or a hexadecimal RGB string such as + '#ffffff', which chooses the closest match from the + default 256-colour set. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-resize-pane [on | off] + If on, tmux captures the mouse and allows panes to be + resized by dragging on their borders. + + mouse-select-pane [on | off] + If on, tmux 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. + + mouse-select-window [on | off] + If on, clicking the mouse on a window name in the status + line will select that window. + + pane-active-border-bg colour + + pane-active-border-fg colour + Set the pane border colour for the currently active pane. + + pane-border-bg colour + + pane-border-fg colour + Set the pane border colour for panes aside from the + active pane. + + prefix keys + Set the keys accepted as a prefix key. keys is a comma- + separated list of key names, each of which individually + behave as the prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + mouse-utf8 [on | off] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the window title using the \e]2;...\007 + xterm code 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string 'vi'. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #h Hostname of local host without + the domain name + #F Current window flag + #I Current window index + #P Current pane index + #S Session name + #T Current window title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the tmux global environ- + ment set (see the ENVIRONMENT section). + + The window title (#T) is the title set by the program + running within the window using the OSC title setting + sequence, for example: + + $ printf '\033]2;My Title\033\\' + + When a window is first created, its title is the host- + name. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256,xterm*:XT" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + visual-silence [on | off] + If monitor-silence is enabled, prints a message after the + interval has expired on a given window. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup 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. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window. It may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-height height + main-pane-width width + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. As with the status-keys option, the default is + emacs, unless VISUAL or EDITOR contains 'vi'. + + mode-mouse [on | off] + 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. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + monitor-silence [interval] + Monitor for silence (no activity) in the window within + interval seconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + other-pane-height height + Set the height of the other panes (not the main pane) in + the main-horizontal layout. If this option is set to 0 + (the default), it will have no effect. If both the + main-pane-height and 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. + + other-pane-width width + Like other-pane-height, but set the width of other panes + in the main-vertical layout. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + window-status-alert-attr attributes + Set status line attributes for windows which have an + alert (bell, activity or content). + + window-status-alert-bg colour + Set status line background colour for windows with an + alert. + + window-status-alert-fg colour + Set status line foreground colour for windows with an + alert. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + word-separators string + Sets the window's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + show-options [-gsw] [-t target-session | target-window] + (alias: show) + Show the window options with -w (equivalent to + show-window-options), the server options with -s, otherwise the + session options for target session. Global session or window + options are listed if -g is used. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a 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. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 status session option) and contains, from left-to- + right: the name of the current session in square brackets; the window + list; the current window title in double quotes; and the time and date. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-I inputs] [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. + + If template is specified, it is used as the command. If present, + -I is a comma-separated list of the initial text for each prompt. + If -p is given, prompts is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from template if it is present, or ':' if + not. + + Both inputs and prompts may contain the special character + sequences supported by the status-left option. + + Before the command is executed, the first occurrence of the + string '%%' and all occurrences of '%1' are replaced by the + response to the first prompt, the second '%%' and all '%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + ('%1' to '%9'). + + confirm-before [-p prompt] [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. If -p is given, + prompt is the prompt to display; otherwise a prompt is con- + structed from command. It may contain the special character + sequences supported by the status-left option. + + This command works only from inside tmux. + + display-message [-p] [-c target-client] [-t target-pane] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is as for status-left, with the exception + that #() are not handled; information is taken from target-pane + if -t is given, otherwise the active pane for the session + attached to target-client. + +BUFFERS + tmux maintains a stack of paste buffers. Up to the value of the + 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 copy-mode + or the set-buffer command, and pasted into a window using the + paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + choose-buffer [-t target-window] [template] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, '%%' + is replaced by the buffer index in template and the result exe- + cuted as a command. If template is not given, "paste-buffer -b + '%%'" is used. This command works only from inside tmux. + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + delete-buffer [-b buffer-index] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers + (alias: lsb) + List the global buffers. + + load-buffer [-b buffer-index] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-s separator] [-t target-pane] + (alias: pasteb) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With -d, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the -s flag. The -r flag means to do no + replacement (equivalent to a separator of LF). + + save-buffer [-a] [-b buffer-index] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command + (alias: if) + Execute command if shell-command returns success. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. After it finishes, any output to stdout is displayed in + copy mode. If the command doesn't return success, the exit sta- + tus is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +TERMINFO EXTENSIONS + tmux understands some extensions to terminfo(5): + + 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 tmux: + + $ printf '\033]12;red\033\\' + + Cs, Csr + Change the cursor style. If set, a sequence such as this may be + used to change the cursor to an underline: + + $ printf '\033[4 q' + + If Csr is set, it will be used to reset the cursor style instead + of Cs. + + Ms This sequence can be used by tmux to store the current buffer in + the host terminal's selection (clipboard). See the set-clipboard + option above and the xterm(1) man page. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.6.txt b/manual/1.6.txt new file mode 100644 index 0000000..b3ecbd3 --- /dev/null +++ b/manual/1.6.txt @@ -0,0 +1,1891 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquvV] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -L socket-name + tmux stores the server socket in a directory under /tmp (or + TMPDIR if set); the default socket is named default. This + option allows a different socket name to be specified, + allowing several independent tmux servers to be run. + Unlike -S a full path is not necessary: the sockets are all + created in the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -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. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + -V Report the tmux version. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the tmux client. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the tmux command prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from tmux, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the bind-key and unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and window is looked for in + order: as a window index, for example mysession:1; as an exact window + name, such as mysession:mywindow; then as an 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 new-window and link-window commands) otherwise the current + window in session is chosen. The special character '!' uses the last + (previously current) window, or '+' and '-' are the next window or the + previous window by number. When the argument does not contain a colon, + tmux first attempts to parse it as window; if that fails, an attempt is + made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. A '+' or '-' indicate the next or + previous pane index, respectively. One of the strings top, bottom, left, + right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + The special characters '+' and '-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + tmux also gives each pane created in a server an identifier consisting of + a '%' and a number, starting from zero. A pane's identifier is unique + for the life of the tmux server and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 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. A literal semicolon may + be included by escaping it with a backslash (for example, when specifying + a command sequence to bind-key). + + Example tmux commands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one or more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client or switch-client + commands have any effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The target-session rules for attach-session are slightly + adjusted: if tmux needs to select the most recently used session, + it will prefer the most recently used unattached session. + + detach-client [-P] [-s target-session] [-t target-client] + (alias: detach) + Detach the current client if bound to a key, the client specified + with -t, or all clients currently attached to the session speci- + fied by -s. If -P is given, send SIGHUP to the parent process of + the client, typically causing it to exit. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session [-t target-session] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. + + list-clients [-F format] [-t target-session] + (alias: lsc) + List all clients attached to the server. For the meaning of the + -F flag, see the FORMATS section. If target-session is speci- + fied, list only clients connected to that session. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions [-F format] + (alias: ls) + List all sessions managed by the server. For the meaning of the + -F flag, see the FORMATS section. + + lock-client [-t target-client] + (alias: lockc) + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + (alias: locks) + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [-x width] [-y height] [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. If -d is used, -x and + -y specify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + refresh-client [-S] [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. If -S is specified, only update the + client's status bar. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-t target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-lnpr] [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. If -l, -n or -p is used, the client is moved to + the last, next or previous session respectively. -r toggles + whether a client is read-only (see the attach-session command). + +WINDOWS AND PANES + A tmux 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 + paste buffer for later insertion into another window. This mode is + entered with the copy-mode command, bound to '[' by default. It is also + entered when a command that produces output, such as list-keys, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump to forward t + Jump backward F F + Jump to backward T + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose chars C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 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. + + The jump commands enable quick movement within a line. For instance, + typing 'f' followed by '/' will move the cursor to the next '/' character + on the current line. A ';' will then jump to the next occurrence. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + When copying the selection, the repeat count indicates the buffer index + to replace, if used. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command); and vi-copy and emacs-copy + used in copy mode. The tables may be viewed with the list-keys command + and keys modified or removed with bind-key and unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the copy-mode command is: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + select-pane command and the rotate-window and 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. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + tiled Panes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, select-layout may be used to apply a previously used layout + - the list-windows command displays the layout of each window in a form + suitable for use with select-layout. For example: + + $ 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} + + tmux 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. + + Commands related to windows and panes are as follows: + + break-pane [-d] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. + + capture-pane [-b buffer-index] [-E end-line] [-S start-line] [-t + target-pane] + (alias: capturep) + Capture the contents of a pane to the specified buffer, or a new + buffer if none is specified. + + -S and -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 con- + tents of the pane. + + choose-client [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. This command works only from inside + tmux. + + choose-session [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. This command works only from inside tmux. + + choose-window [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. This command works only from + inside tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + find-window [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). If only one win- + dow is matched, it'll be automatically selected, otherwise a + choice list is shown. This command only works from inside tmux. + + join-pane [-dhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. + + last-pane [-t target-window] + (alias: lastp) + Select the last (previously selected) pane. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-as] [-F format] [-t target] + (alias: lsp) + If -a is given, target is ignored and all panes on the server are + listed. If -s is given, target is a session (or the current ses- + sion). If neither is given, target is a window (or the current + window). For the meaning of the -F flag, see the FORMATS sec- + tion. + + list-windows [-a] [-F format] [-t target-session] + (alias: lsw) + If -a is given, list all windows on the server. Otherwise, list + windows in the current session or in target-session. For the + meaning of the -F flag, see the FORMATS section. + + move-window [-dk] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. + + new-window [-adkP] [-n window-name] [-t target-window] [shell-command] + (alias: neww) + Create a new window. With -a, the new window is inserted at the + next index up from the specified target-window, moving windows up + if necessary, otherwise target-window is the new window location. + + If -d is given, the session does not make the new window the cur- + rent window. target-window represents the window to be created; + if the target already exists an error is shown, unless the -k + flag is used, in which case it is destroyed. shell-command is + the command to execute. If shell-command is not specified, the + value of the default-command option is used. + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The -P option prints the location of the new window after it has + been created. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with a bell, activity or content alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. The + shell-command string may contain the special character sequences + supported by the status-left option. If no shell-command is + given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + previous-layout [-t target-window] + (alias: prevl) + Move to the previous layout in the session. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with a bell, activity or content alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-pane [-k] [-t target-pane] [shell-command] + (alias: respawnp) + Reactivate a pane in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless -k is given, in which case any + existing command is killed. + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-np] [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last preset layout used (if any) is reapplied. -n and + -p are equivalent to the next-layout and previous-layout com- + mands. + + select-pane [-lDLRU] [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + If one of -D, -L, -R, or -U is used, respectively the pane below, + to the left, to the right, or above the target pane is used. -l + is the same as using the last-pane command. + + select-window [-lnp] [-t target-window] + (alias: selectw) + Select the window at target-window. -l, -n and -p are equivalent + to the last-window, next-window and previous-window commands. + + split-window [-dhvP] [-l size | -p percentage] [-t target-pane] + [shell-command] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space, + and Tab. Note that to bind the '"' or ''' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + Keys bound without the prefix key (see bind-key -n) are marked + with '(no prefix)'. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys -R [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. All + arguments are sent sequentially from first to last. The -R flag + causes the terminal state to be reset. + + send-prefix [-2] [-t target-pane] + Send the prefix key, or with -2 the secondary prefix key, to a + window as if it was pressed. + + unbind-key [-acn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. If -a is + present, all key bindings are removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + Available window options are listed under set-window-option. + + Available server options are: + + buffer-limit number + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + escape-time time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + exit-unattached [on | off] + If enabled, the server will exit when there are no + attached clients. + + quiet [on | off] + Enable or disable the display of various informational + messages (see also the -q command line flag). + + set-clipboard [on | off] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an Ms entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + bell-on-alert [on | off] + If on, ring the terminal bell when an activity, content + or silence alert occurs. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-path 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. If path is "$HOME" or + "~", the value of the HOME environment variable is used. + If path is ".", the working directory when tmux was + started is used. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + destroy-unattached [on | off] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + detach-on-destroy [on | off] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either none or a comma-delimited list of one or more of: + bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, aixterm bright variants (if supported: + brightred, brightgreen, and so on), colour0 to colour255 + from the 256-colour set, default, or a hexadecimal RGB + string such as '#ffffff', which chooses the closest match + from the default 256-colour set. + + message-command-attr attributes + Set status line message attributes when in command mode. + + message-command-bg colour + Set status line message background colour when in command + mode. + + message-command-fg colour + Set status line message foreground colour when in command + mode. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-resize-pane [on | off] + If on, tmux captures the mouse and allows panes to be + resized by dragging on their borders. + + mouse-select-pane [on | off] + If on, tmux 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. + + mouse-select-window [on | off] + If on, clicking the mouse on a window name in the status + line will select that window. + + mouse-utf8 [on | off] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + pane-active-border-bg colour + + pane-active-border-fg colour + Set the pane border colour for the currently active pane. + + pane-border-bg colour + + pane-border-fg colour + Set the pane border colour for panes aside from the + active pane. + + prefix key + Set the key accepted as a prefix key. + + prefix2 key + Set a secondary key accepted as a prefix key. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the client terminal title using the tsl + and fsl terminfo(5) entries if they exist. tmux automat- + ically sets these to the \e]2;...\007 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string 'vi'. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #h Hostname of local host without + the domain name + #F Current window flag + #I Current window index + #P Current pane index + #S Session name + #T Current pane title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the tmux global environ- + ment set (see the ENVIRONMENT section). + + For details on how the names and titles can be set see + the NAMES AND TITLES section. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256,xterm*:XT" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + visual-silence [on | off] + If monitor-silence is enabled, prints a message after the + interval has expired on a given window. + + word-separators string + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + set-window-option [-agu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g and -u flags work similarly to + the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + allow-rename [on | off] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup 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. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window, or with a terminal escape sequence. It + may be switched off globally with: + + set-window-option -g automatic-rename off + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-height height + main-pane-width width + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. As with the status-keys option, the default is + emacs, unless VISUAL or EDITOR contains 'vi'. + + mode-mouse [on | off | copy-mode] + 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 copy-mode, + the mouse behaves as set to on, but cannot be used to + enter copy mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + monitor-silence [interval] + Monitor for silence (no activity) in the window within + interval seconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + other-pane-height height + Set the height of the other panes (not the main pane) in + the main-horizontal layout. If this option is set to 0 + (the default), it will have no effect. If both the + main-pane-height and 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. + + other-pane-width width + Like other-pane-height, but set the width of other panes + in the main-vertical layout. + + pane-base-index index + Like base-index, but set the starting index for pane num- + bers. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-bell-attr attributes + Set status line attributes for windows which have a bell + alert. + + window-status-bell-bg colour + Set status line background colour for windows with a bell + alert. + + window-status-bell-fg colour + Set status line foreground colour for windows with a bell + alert. + + window-status-content-attr attributes + Set status line attributes for windows which have a con- + tent alert. + + window-status-content-bg colour + Set status line background colour for windows with a con- + tent alert. + + window-status-content-fg colour + Set status line foreground colour for windows with a con- + tent alert. + + window-status-activity-attr attributes + Set status line attributes for windows which have an + activity (or silence) alert. + + window-status-activity-bg colour + Set status line background colour for windows with an + activity alert. + + window-status-activity-fg colour + Set status line foreground colour for windows with an + activity alert. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + show-options [-gsw] [-t target-session | target-window] + (alias: show) + Show the window options with -w (equivalent to + show-window-options), the server options with -s, otherwise the + session options for target session. Global session or window + options are listed if -g is used. + + show-window-options [-g] [-t target-window] + (alias: showw) + List the window options for target-window, or the global window + options if -g is used. + +FORMATS + The list-clients, list-sessions, list-windows and list-panes commands + accept the -F flag with a format argument. This is a string which con- + trols the output format of the command. Special character sequences are + replaced as documented under the status-left option and an additional + long form is accepted. Replacement variables are enclosed in '#{' and + '}', for example '#{session_name}' is equivalent to '#S'. Conditionals + are also accepted by prefixing with '?' 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 + '#{?session_attached,attached,not attached}' will include the string + 'attached' if the session is attached and the string 'not attached' if it + is unattached. + + The following variables are available, where appropriate: + + Variable name Replaced with + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_cwd Working directory of client + client_height Height of client + client_readonly 1 if client is readonly + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + host Hostname of local host + line Line number in the list + pane_active 1 if active pane + pane_dead 1 if pane is dead + pane_height Height of pane + pane_id Unique pane id + pane_pid PID of first process in pane + pane_start_command Command pane started with + pane_start_path Path pane started with + pane_title Title of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + session_attached 1 if session attached + session_created Integer time session created + session_created_string String time session created + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_name Name of session + session_width Width of session + session_windows Number of windows in session + window_active 1 if window active + window_flags Window flags + window_height Height of window + window_index Index of window + window_layout Window layout description + window_name Name of window + window_width Width of window + +NAMES AND TITLES + tmux 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 tmux 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 tmux. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. tmux itself may set + the title of the terminal in which the client is running, see the + set-titles option. + + A session's name is set with the new-session and rename-session commands. + A window's name is set with one of: + + 1. A command argument (such as -n for new-window or new-session). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the automatic-rename option. + + 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: + + $ printf '\033]2;My Title\033\\' + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a 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. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. Variables removed from the environment are pre- + fixed with '-'. + +STATUS LINE + tmux 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 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-I inputs] [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. + + If template is specified, it is used as the command. If present, + -I is a comma-separated list of the initial text for each prompt. + If -p is given, prompts is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from template if it is present, or ':' if + not. + + Both inputs and prompts may contain the special character + sequences supported by the status-left option. + + Before the command is executed, the first occurrence of the + string '%%' and all occurrences of '%1' are replaced by the + response to the first prompt, the second '%%' and all '%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + ('%1' to '%9'). + + confirm-before [-p prompt] [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. If -p is given, + prompt is the prompt to display; otherwise a prompt is con- + structed from command. It may contain the special character + sequences supported by the status-left option. + + This command works only from inside tmux. + + display-message [-p] [-c target-client] [-t target-pane] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is as for status-left, with the exception + that #() are not handled; information is taken from target-pane + if -t is given, otherwise the active pane for the session + attached to target-client. + +BUFFERS + tmux maintains a stack of paste buffers. Up to the value of the + 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 copy-mode + or the set-buffer command, and pasted into a window using the + paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + choose-buffer [-t target-window] [template] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, '%%' + is replaced by the buffer index in template and the result exe- + cuted as a command. If template is not given, "paste-buffer -b + '%%'" is used. This command works only from inside tmux. + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + delete-buffer [-b buffer-index] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers + (alias: lsb) + List the global buffers. + + load-buffer [-b buffer-index] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dr] [-b buffer-index] [-s separator] [-t target-pane] + (alias: pasteb) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With -d, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the -s flag. The -r flag means to do no + replacement (equivalent to a separator of LF). + + save-buffer [-a] [-b buffer-index] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command [command] + (alias: if) + Execute the first command if shell-command returns success or the + second command otherwise. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. After it finishes, any output to stdout is displayed in + copy mode. If the command doesn't return success, the exit sta- + tus is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +TERMINFO EXTENSIONS + tmux understands some extensions to terminfo(5): + + 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 tmux: + + $ printf '\033]12;red\033\\' + + Cs, Csr + Change the cursor style. If set, a sequence such as this may be + used to change the cursor to an underline: + + $ printf '\033[4 q' + + If Csr is set, it will be used to reset the cursor style instead + of Cs. + + Ms This sequence can be used by tmux to store the current buffer in + the host terminal's selection (clipboard). See the set-clipboard + option above and the xterm(1) man page. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.7.txt b/manual/1.7.txt new file mode 100644 index 0000000..1a71642 --- /dev/null +++ b/manual/1.7.txt @@ -0,0 +1,2010 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lquvV] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. The configuration file is a + set of tmux commands which are executed in sequence when + the server is first started. + + If a command in the configuration file fails, tmux will + report an error and exit without executing further com- + mands. + + -L socket-name + tmux stores the server socket in a directory under /tmp (or + TMPDIR if set); the default socket is named default. This + option allows a different socket name to be specified, + allowing several independent tmux servers to be run. + Unlike -S a full path is not necessary: the sockets are all + created in the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -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. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + -V Report the tmux version. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the tmux client. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the tmux command prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from tmux, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the bind-key and unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is either the name of a session (as listed by the + list-sessions command) or the name of a client with the same syntax as + target-client, in which case the session attached to the client is used. + When looking for the session name, tmux initially searches for an exact + match; if none is found, the session names are checked for any for which + target-session is a prefix or for which it matches as an fnmatch(3) pat- + tern. If a single match is found, it is used as the target session; mul- + tiple 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. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and 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 + fnmatch(3) pattern or the start of a window name, such as myses- + sion:mywin* or mysession:mywin. An empty window name specifies the next + unused index if appropriate (for example the new-window and link-window + commands) otherwise the current window in session is chosen. The special + character '!' uses the last (previously current) window, or '+' and '-' + are the next window or the previous window by number. When the argument + does not contain a colon, tmux first attempts to parse it as window; if + that fails, an attempt is made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. A '+' or '-' indicate the next or + previous pane index, respectively. One of the strings top, bottom, left, + right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + The special characters '+' and '-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + tmux also gives each pane created in a server an identifier consisting of + a '%' and a number, starting from zero. A pane's identifier is unique + for the life of the tmux server and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 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 + bind-key). + + Example tmux commands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one or more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client or switch-client + commands have any effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The target-session rules for attach-session are slightly + adjusted: if tmux needs to select the most recently used session, + it will prefer the most recently used unattached session. + + detach-client [-P] [-a] [-s target-session] [-t target-client] + (alias: detach) + Detach the current client if bound to a key, the client specified + with -t, or all clients currently attached to the session speci- + fied by -s. The -a option kills all but the client given with + -t. If -P is given, send SIGHUP to the parent process of the + client, typically causing it to exit. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session + [-a] [-t target-session] Destroy the given session, closing any + windows linked to it and no other sessions, and detaching all + clients attached to it. If -a is given, all sessions but the + specified one is killed. + + list-clients [-F format] [-t target-session] + (alias: lsc) + List all clients attached to the server. For the meaning of the + -F flag, see the FORMATS section. If target-session is speci- + fied, list only clients connected to that session. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions [-F format] + (alias: ls) + List all sessions managed by the server. For the meaning of the + -F flag, see the FORMATS section. + + lock-client [-t target-client] + (alias: lockc) + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + (alias: locks) + Lock all clients attached to target-session. + + new-session [-d] [-n window-name] [-s session-name] [-t target-session] + [-x width] [-y height] [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. If -d is used, -x and + -y specify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + refresh-client [-S] [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. If -S is specified, only update the + client's status bar. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-t target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-lnpr] [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. If -l, -n or -p is used, the client is moved to + the last, next or previous session respectively. -r toggles + whether a client is read-only (see the attach-session command). + +WINDOWS AND PANES + A tmux 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 + paste buffer for later insertion into another window. This mode is + entered with the copy-mode command, bound to '[' by default. It is also + entered when a command that produces output, such as list-keys, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump to forward t + Jump backward F F + Jump to backward T + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose chars C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 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. + + The jump commands enable quick movement within a line. For instance, + typing 'f' followed by '/' will move the cursor to the next '/' character + on the current line. A ';' will then jump to the next occurrence. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + When copying the selection, the repeat count indicates the buffer index + to replace, if used. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command); and vi-copy and emacs-copy + used in copy mode. The tables may be viewed with the list-keys command + and keys modified or removed with bind-key and unbind-key. + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the copy-mode command is: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + select-pane command and the rotate-window and 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. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + tiled Panes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, select-layout may be used to apply a previously used layout + - the list-windows command displays the layout of each window in a form + suitable for use with select-layout. For example: + + $ 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} + + tmux 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. + + Commands related to windows and panes are as follows: + + break-pane [-dP] [-F format] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. The -P option prints information + about the new window after it has been created. By default, it + uses the format '#{session_name}:#{window_index}' but a different + format may be specified with -F. + + capture-pane [-b buffer-index] [-E end-line] [-S start-line] [-t + target-pane] + (alias: capturep) + Capture the contents of a pane to the specified buffer, or a new + buffer if none is specified. + + -S and -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 con- + tents of the pane. + + choose-client [-F format] [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. For the meaning of the -F flag, see the + FORMATS section. This command works only from inside tmux. + + choose-list [-l items] [-t target-window] [template] + Put a window into list choice mode, allowing items to be + selected. 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, '%%' is replaced by the chosen item in + the template and the result is executed as a command. If + template is not given, "run-shell '%%'" is used. items also + accepts format specifiers. For the meaning of this see the + FORMATS section. This command works only from inside tmux. + + choose-session [-F format] [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. For the meaning of the -F flag, see the FORMATS sec- + tion. This command works only from inside tmux. + + choose-tree [-s] [-w] [-b session-template] [-c window-template] [-S + format] [-W format] [-t target-window] + Put a window into tree choice mode, where either sessions or win- + dows may be selected interactively from a list. By default, win- + dows belonging to a session are indented to show their relation- + ship to a session. + + Note that the choose-window and choose-session commands are wrap- + pers around choose-tree. + + If -s is given, will show sessions. If -w is given, will show + windows. If -b is given, will override the default session com- + mand. Note that '%%' can be used, and will be replaced with the + session name. The default option if not specified is "switch- + client -t '%%'". If -c is given, will override the default win- + dow command. Note that '%%' can be used, and will be replaced + with the session name and window index. This command will run + session-template before it. If -S is given will display the + specified format instead of the default session format. If -W is + given will display the specified format instead of the default + window format. For the meaning of the -s and -w options, see the + FORMATS section. This command only works from inside tmux. + + choose-window [-F format] [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. For the meaning of the -F flag, + see the FORMATS section. This command works only from inside + tmux. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + find-window [-CNT] [-F format] [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). The flags control + matching behavior: -C matches only visible window contents, -N + matches only the window name and -T matches only the window + title. The default is -CNT. If only one window is matched, + it'll be automatically selected, otherwise a choice list is + shown. For the meaning of the -F flag, see the FORMATS section. + This command only works from inside tmux. + + join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. The -b option causes src-pane to + be joined to left of or above dst-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-a] [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. The -a option kills + all but the window given with -t. + + last-pane [-t target-window] + (alias: lastp) + Select the last (previously selected) pane. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-as] [-F format] [-t target] + (alias: lsp) + If -a is given, target is ignored and all panes on the server are + listed. If -s is given, target is a session (or the current ses- + sion). If neither is given, target is a window (or the current + window). For the meaning of the -F flag, see the FORMATS sec- + tion. + + list-windows [-a] [-F format] [-t target-session] + (alias: lsw) + If -a is given, list all windows on the server. Otherwise, list + windows in the current session or in target-session. For the + meaning of the -F flag, see the FORMATS section. + + move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: movep) + Like join-pane, but src-pane and dst-pane may belong to the same + window. + + move-window [-rdk] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. With -r, all windows in the session are + renumbered in sequential order, respecting the base-index option. + + new-window [-adkP] [-c start-directory] [-n window-name] [-t + target-window] [-F format] [shell-command] + (alias: neww) + Create a new window. With -a, the new window is inserted at the + next index up from the specified target-window, moving windows up + if necessary, otherwise target-window is the new window location. + + If -d is given, the session does not make the new window the cur- + rent window. target-window represents the window to be created; + if the target already exists an error is shown, unless the -k + flag is used, in which case it is destroyed. shell-command is + the command to execute. If shell-command is not specified, the + value of the default-command option is used. -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 subdi- + rectory): + + Empty string Current pane's directory + ~ User's home directory + - Where session was started + . Where server was started + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The -P option prints information about the new window after it + has been created. By default, it uses the format + '#{session_name}:#{window_index}' but a different format may be + specified with -F. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with an alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. The + shell-command string may contain the special character sequences + supported by the status-left option. If no shell-command is + given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + previous-layout [-t target-window] + (alias: prevl) + Move to the previous layout in the session. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with an alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRU] [-t target-pane] [adjustment] + (alias: resizep) + Resize a pane, upward with -U (the default), downward with -D, to + the left with -L and to the right with -R. The adjustment is + given in lines or cells (the default is 1). + + respawn-pane [-k] [-t target-pane] [shell-command] + (alias: respawnp) + Reactivate a pane in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless -k is given, in which case any + existing command is killed. + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-npUu] [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last preset layout used (if any) is reapplied. -n and + -p are equivalent to the next-layout and previous-layout com- + mands. + + -U and -u step forward and back through previous layouts, up to + the maximum set by the layout-history-limit option. + + select-pane [-lDLRU] [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + If one of -D, -L, -R, or -U is used, respectively the pane below, + to the left, to the right, or above the target pane is used. -l + is the same as using the last-pane command. + + select-window [-lnp] [-t target-window] + (alias: selectw) + Select the window at target-window. -l, -n and -p are equivalent + to the last-window, next-window and previous-window commands. + + split-window [-dhvP] [-c start-directory] [-l size | -p percentage] [-t + target-pane] [shell-command] [-F format] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space, + and Tab. Note that to bind the '"' or ''' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-lR] [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. The + -l flag disables key name lookup and sends the keys literally. + All arguments are sent sequentially from first to last. The -R + flag causes the terminal state to be reset. + + send-prefix [-2] [-t target-pane] + Send the prefix key, or with -2 the secondary prefix key, to a + window as if it was pressed. + + unbind-key [-acn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. If -a is + present, all key bindings are removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + Commands which set options are as follows: + + set-option [-agqsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + The -q flag suppresses the informational message (as if the quiet + server option was set). + + Available window options are listed under set-window-option. + + value depends on the option and may be a number, a string, or a + flag (on, off, or omitted to toggle). + + Available server options are: + + buffer-limit number + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + escape-time time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + exit-unattached [on | off] + If enabled, the server will exit when there are no + attached clients. + + quiet [on | off] + Enable or disable the display of various informational + messages (see also the -q command line flag). + + set-clipboard [on | off] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an Ms entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + Available session options are: + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bell in windows other than the current + window are ignored. + + bell-on-alert [on | off] + If on, ring the terminal bell when an alert occurs. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-path 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 -c flag to new-window. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + destroy-unattached [on | off] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + detach-on-destroy [on | off] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either none or a comma-delimited list of one or more of: + bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, aixterm bright variants (if supported: + brightred, brightgreen, and so on), colour0 to colour255 + from the 256-colour set, default, or a hexadecimal RGB + string such as '#ffffff', which chooses the closest match + from the default 256-colour set. + + message-command-attr attributes + Set status line message attributes when in command mode. + + message-command-bg colour + Set status line message background colour when in command + mode. + + message-command-fg colour + Set status line message foreground colour when in command + mode. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-resize-pane [on | off] + If on, tmux captures the mouse and allows panes to be + resized by dragging on their borders. + + mouse-select-pane [on | off] + If on, tmux 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. + + mouse-select-window [on | off] + If on, clicking the mouse on a window name in the status + line will select that window. + + mouse-utf8 [on | off] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + pane-active-border-bg colour + + pane-active-border-fg colour + Set the pane border colour for the currently active pane. + + pane-border-bg colour + + pane-border-fg colour + Set the pane border colour for panes aside from the + active pane. + + prefix key + Set the key accepted as a prefix key. + + prefix2 key + Set a secondary key accepted as a prefix key. + + renumber-windows [on | off] + If on, when a window is closed in a session, automati- + cally renumber the other windows in numerical order. + This respects the base-index option if it has been set. + If off, do not renumber the windows. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the client terminal title using the tsl + and fsl terminfo(5) entries if they exist. tmux automat- + ically sets these to the \e]2;...\007 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string 'vi'. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #h Hostname of local host without + the domain name + #F Current window flag + #I Current window index + #D Current pane unique identifier + #P Current pane index + #S Session name + #T Current pane title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the tmux global environ- + ment set (see the ENVIRONMENT section). + + For details on how the names and titles can be set see + the NAMES AND TITLES section. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-position [top | bottom] + Set the position of the status line. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256,xterm*:XT" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + visual-silence [on | off] + If monitor-silence is enabled, prints a message after the + interval has expired on a given window. + + word-separators string + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + set-window-option [-agqu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g, -q and -u flags work similarly + to the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + allow-rename [on | off] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup 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. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window, or with a terminal escape sequence. It + may be switched off globally with: + + set-window-option -g automatic-rename off + + c0-change-interval interval + c0-change-trigger trigger + These two options configure a simple form of rate limit- + ing for a pane. If tmux sees more than 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 interval milliseconds. This + helps to prevent fast output (such as 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. + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + layout-history-limit limit + Set the number of previous layouts stored for recovery + with select-layout -U and -u. + + main-pane-height height + main-pane-width width + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. As with the status-keys option, the default is + emacs, unless VISUAL or EDITOR contains 'vi'. + + mode-mouse [on | off | copy-mode] + 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 copy-mode, + the mouse behaves as set to on, but cannot be used to + enter copy mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + monitor-silence [interval] + Monitor for silence (no activity) in the window within + interval seconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + other-pane-height height + Set the height of the other panes (not the main pane) in + the main-horizontal layout. If this option is set to 0 + (the default), it will have no effect. If both the + main-pane-height and 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. + + other-pane-width width + Like other-pane-height, but set the width of other panes + in the main-vertical layout. + + pane-base-index index + Like base-index, but set the starting index for pane num- + bers. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-bell-attr attributes + Set status line attributes for windows which have a bell + alert. + + window-status-bell-bg colour + Set status line background colour for windows with a bell + alert. + + window-status-bell-fg colour + Set status line foreground colour for windows with a bell + alert. + + window-status-content-attr attributes + Set status line attributes for windows which have a con- + tent alert. + + window-status-content-bg colour + Set status line background colour for windows with a con- + tent alert. + + window-status-content-fg colour + Set status line foreground colour for windows with a con- + tent alert. + + window-status-activity-attr attributes + Set status line attributes for windows which have an + activity (or silence) alert. + + window-status-activity-bg colour + Set status line background colour for windows with an + activity alert. + + window-status-activity-fg colour + Set status line foreground colour for windows with an + activity alert. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + window-status-separator string + Sets the separator drawn between windows in the status + line. The default is a single space character. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + wrap-search [on | off] + If this option is set, searches will wrap around the end + of the pane contents. The default is on. + + show-options [-gsw] [-t target-session | target-window] [option] + (alias: show) + Show the window options (or a single window option if given) with + -w (equivalent to show-window-options), the server options with + -s, otherwise the session options for target session. Global + session or window options are listed if -g is used. + + show-window-options [-g] [-t target-window] [option] + (alias: showw) + List the window options or a single option for target-window, or + the global window options if -g is used. + +FORMATS + Certain commands accept the -F flag with a format argument. This is a + string which controls the output format of the command. Special charac- + ter sequences are replaced as documented under the status-left option and + an additional long form is accepted. Replacement variables are enclosed + in '#{' and '}', for example '#{session_name}' is equivalent to '#S'. + Conditionals are also accepted by prefixing with '?' 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 '#{?session_attached,attached,not attached}' will include the + string 'attached' if the session is attached and the string 'not + attached' if it is unattached. + + The following variables are available, where appropriate: + + Variable name Replaced with + buffer_sample First 50 characters from the specified + buffer + buffer_size Size of the specified buffer in bytes + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_cwd Working directory of client + client_height Height of client + client_readonly 1 if client is readonly + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + host Hostname of local host + history_bytes Number of bytes in window history + history_limit Maximum window history lines + history_size Size of history in bytes + line Line number in the list + pane_active 1 if active pane + pane_current_path Current path if available + pane_dead 1 if pane is dead + pane_height Height of pane + pane_id Unique pane ID + pane_index Index of pane + pane_pid PID of first process in pane + pane_start_command Command pane started with + pane_start_path Path pane started with + pane_title Title of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + session_attached 1 if session attached + session_created Integer time session created + session_created_string String time session created + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_name Name of session + session_width Width of session + session_windows Number of windows in session + window_active 1 if window active + window_find_matches Matched data from the find-window command + if available + window_flags Window flags + window_height Height of window + window_id Unique window ID + window_index Index of window + window_layout Window layout description + window_name Name of window + window_panes Number of panes in window + window_width Width of window + +NAMES AND TITLES + tmux 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 tmux 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 tmux. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. tmux itself may set + the title of the terminal in which the client is running, see the + set-titles option. + + A session's name is set with the new-session and rename-session commands. + A window's name is set with one of: + + 1. A command argument (such as -n for new-window or new-session). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the automatic-rename option. + + 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: + + $ printf '\033]2;My Title\033\\' + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a 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. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] [variable] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. If variable is omitted, all variables are shown. + Variables removed from the environment are prefixed with '-'. + +STATUS LINE + tmux 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 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-I inputs] [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. + + If template is specified, it is used as the command. If present, + -I is a comma-separated list of the initial text for each prompt. + If -p is given, prompts is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from template if it is present, or ':' if + not. + + Both inputs and prompts may contain the special character + sequences supported by the status-left option. + + Before the command is executed, the first occurrence of the + string '%%' and all occurrences of '%1' are replaced by the + response to the first prompt, the second '%%' and all '%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + ('%1' to '%9'). + + confirm-before [-p prompt] [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. If -p is given, + prompt is the prompt to display; otherwise a prompt is con- + structed from command. It may contain the special character + sequences supported by the status-left option. + + This command works only from inside tmux. + + display-message [-p] [-c target-client] [-t target-pane] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is described in the FORMATS section; infor- + mation is taken from target-pane if -t is given, otherwise the + active pane for the session attached to target-client. + +BUFFERS + tmux maintains a stack of paste buffers. Up to the value of the + 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 copy-mode + or the set-buffer command, and pasted into a window using the + paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + choose-buffer [-F format] [-t target-window] [template] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, '%%' + is replaced by the buffer index in template and the result exe- + cuted as a command. If template is not given, "paste-buffer -b + '%%'" is used. For the meaning of the -F flag, see the FORMATS + section. This command works only from inside tmux. + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + delete-buffer [-b buffer-index] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-F format] + (alias: lsb) + List the global buffers. For the meaning of the -F flag, see the + FORMATS section. + + load-buffer [-b buffer-index] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dpr] [-b buffer-index] [-s separator] [-t target-pane] + (alias: pasteb) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With -d, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the -s flag. The -r flag means to do no + replacement (equivalent to a separator of LF). If -p is speci- + fied, paste bracket control codes are inserted around the buffer + if the application has requested bracketed paste mode. + + save-buffer [-a] [-b buffer-index] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell shell-command command [command] + (alias: if) + Execute the first command if shell-command returns success or the + second command otherwise. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. After it finishes, any output to stdout is displayed in + copy mode. If the command doesn't return success, the exit sta- + tus is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + +TERMINFO EXTENSIONS + tmux understands some extensions to terminfo(5): + + 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 tmux: + + $ printf '\033]12;red\033\\' + + Cs, Csr + Change the cursor style. If set, a sequence such as this may be + used to change the cursor to an underline: + + $ printf '\033[4 q' + + If Csr is set, it will be used to reset the cursor style instead + of Cs. + + Ms This sequence can be used by tmux to store the current buffer in + the host terminal's selection (clipboard). See the set-clipboard + option above and the xterm(1) man page. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.8.txt b/manual/1.8.txt new file mode 100644 index 0000000..f8c7f06 --- /dev/null +++ b/manual/1.8.txt @@ -0,0 +1,2178 @@ +TMUX(1) BSD General Commands Manual TMUX(1) + +NAME + tmux -- terminal multiplexer + +SYNOPSIS + tmux [-28lCquvV] [-c shell-command] [-f file] [-L socket-name] + [-S socket-path] [command [flags]] + +DESCRIPTION + tmux is a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. tmux may be + detached from a screen and continue running in the background, then later + reattached. + + When tmux is started it creates a new session with a single 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 com- + mands. + + A session is a single collection of pseudo terminals under the management + of tmux. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of tmux instances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, tmux exits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + 'C-b d' key strokes). tmux may be reattached using: + + $ tmux attach + + In tmux, a session is displayed on screen by a client and all sessions + are managed by a single server. The server and each client are separate + processes which communicate through a socket in /tmp. + + The options are as follows: + + -2 Force tmux to assume the terminal supports 256 colours. + + -8 Like -2, but indicates that the terminal supports 88 + colours. + + -C Start in control mode. Given twice (-CC) disables echo. + + -c shell-command + Execute shell-command using the default shell. If neces- + sary, the tmux server will be started to retrieve the + default-shell option. This option is for compatibility + with sh(1) when tmux is used as a login shell. + + -f file Specify an alternative configuration file. By default, + tmux loads the system configuration file from + /etc/tmux.conf, if present, then looks for a user configu- + ration file at ~/.tmux.conf. + + The configuration file is a set of tmux commands which are + executed in sequence when the server is first started. + tmux loads configuration files once when the server process + has started. The source-file command may be used to load a + file later. + + tmux shows any error messages from commands in configura- + tion files in the first session created, and continues to + process the rest of the configuration file. + + -L socket-name + tmux stores the server socket in a directory under /tmp (or + TMPDIR if set); the default socket is named default. This + option allows a different socket name to be specified, + allowing several independent tmux servers to be run. + Unlike -S a full path is not necessary: the sockets are all + created in the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the tmux server process to recreate it. + + -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. + + -q Set the quiet server option to prevent the server sending + various informational messages. + + -S socket-path + Specify a full alternative path to the server socket. If + -S is specified, the default socket directory is not used + and any -L flag is ignored. + + -u tmux attempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the -u flag explic- + itly informs tmux that UTF-8 is supported. + + If the server is started from a client passed -u or where + UTF-8 is detected, the utf8 and status-utf8 options are + enabled in the global window and session options respec- + tively. + + -v Request verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into tmux-client-PID.log and tmux-server-PID.log + files in the current directory, where PID is the PID of the + server or client process. + + -V Report the tmux version. + + command [flags] + This specifies one of a set of commands used to control + tmux, as described in the following sections. If no com- + mands are specified, the new-session command is assumed. + +KEY BINDINGS + tmux may be controlled from an attached client by using a key combination + of a prefix key, 'C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the tmux client. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the tmux command prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from tmux, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the bind-key and unbind-key commands. + +COMMANDS + This section contains a list of the commands supported by tmux. Most + commands accept the optional -t argument with one of target-client, + target-session target-window, or target-pane. These specify the client, + session, window or pane which a command should affect. target-client is + the name of the pty(4) file to which the client is connected, for example + either of /dev/ttyp1 or ttyp1 for the client attached to /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 list-clients command. + + target-session is the session id prefixed with a $, the name of a session + (as listed by the list-sessions command), or the name of a client with + the same syntax as target-client, in which case the session attached to + the client is used. When looking for the session name, tmux initially + searches for an exact match; if none is found, the session names are + checked for any for which target-session is a prefix or for which it + matches as an 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 ses- + sion is available, the most recently used is chosen. + + target-window specifies a window in the form session:window. session + follows the same rules as for target-session, and 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 + fnmatch(3) pattern or the start of a window name, such as myses- + sion:mywin* or mysession:mywin. An empty window name specifies the next + unused index if appropriate (for example the new-window and link-window + commands) otherwise the current window in session is chosen. The special + character '!' uses the last (previously current) window, '^' selects the + highest numbered window, '$' selects the lowest numbered window, and '+' + and '-' select the next window or the previous window by number. When + the argument does not contain a colon, tmux first attempts to parse it as + window; if that fails, an attempt is made to match a session. + + target-pane takes a similar form to target-window but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + tmux first attempts to use the argument as a pane index; if that fails, + it is looked up as for target-window. A '+' or '-' indicate the next or + previous pane index, respectively. One of the strings top, bottom, left, + right, top-left, top-right, bottom-left or bottom-right may be used + instead of a pane index. + + The special characters '+' and '-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + tmux also gives each pane created in a server an identifier consisting of + a '%' and a number, starting from zero. A pane's identifier is unique + for the life of the tmux server and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + shell-command arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + command [arguments] refers to a tmux command, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 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 + bind-key). + + Example tmux commands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +CLIENTS AND SESSIONS + The tmux server manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the new-session command, or later with the attach-session com- + mand. Each session has one or more windows 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 WINDOWS AND PANES sec- + tion. + + The following commands are available to manage clients and sessions: + + attach-session [-dr] [-t target-session] + (alias: attach) + If run from outside tmux, create a new client in the current ter- + minal and attach it to target-session. If used from inside, + switch the current client. If -d is specified, any other clients + attached to the session are detached. -r signifies the client is + read-only (only keys bound to the detach-client or switch-client + commands have any effect) + + If no server is started, attach-session will attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The target-session rules for attach-session are slightly + adjusted: if tmux needs to select the most recently used session, + it will prefer the most recently used unattached session. + + detach-client [-P] [-a] [-s target-session] [-t target-client] + (alias: detach) + Detach the current client if bound to a key, the client specified + with -t, or all clients currently attached to the session speci- + fied by -s. The -a option kills all but the client given with + -t. If -P is given, send SIGHUP to the parent process of the + client, typically causing it to exit. + + has-session [-t target-session] + (alias: has) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + kill-server + Kill the tmux server and clients and destroy all sessions. + + kill-session + [-a] [-t target-session] Destroy the given session, closing any + windows linked to it and no other sessions, and detaching all + clients attached to it. If -a is given, all sessions but the + specified one is killed. + + list-clients [-F format] [-t target-session] + (alias: lsc) + List all clients attached to the server. For the meaning of the + -F flag, see the FORMATS section. If target-session is speci- + fied, list only clients connected to that session. + + list-commands + (alias: lscm) + List the syntax of all commands supported by tmux. + + list-sessions [-F format] + (alias: ls) + List all sessions managed by the server. For the meaning of the + -F flag, see the FORMATS section. + + lock-client [-t target-client] + (alias: lockc) + Lock target-client, see the lock-server command. + + lock-session [-t target-session] + (alias: locks) + Lock all clients attached to target-session. + + new-session [-AdDP] [-F format] [-n window-name] [-s session-name] [-t + target-session] [-x width] [-y height] [shell-command] + (alias: new) + Create a new session with name session-name. + + The new session is attached to the current terminal unless -d is + given. window-name and shell-command are the name of and shell + command to execute in the initial window. If -d is used, -x and + -y specify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + The -A flag makes new-session behave like attach-session if + session-name already exists; in the case, -D behaves like -d to + attach-session. + + If -t is given, the new session is grouped with target-session. + This means they share the same set of windows - all windows from + 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 -n or shell-command are invalid if -t is used. + + The -P option prints information about the new session after it + has been created. By default, it uses the format + '#{session_name}:' but a different format may be specified with + -F. + + refresh-client [-S] [-t target-client] + (alias: refresh) + Refresh the current client if bound to a key, or a single client + if one is given with -t. If -S is specified, only update the + client's status bar. + + rename-session [-t target-session] new-name + (alias: rename) + Rename the session to new-name. + + show-messages [-t target-client] + (alias: 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 + message-limit session option for the session attached to that + client. This command displays the log for target-client. + + source-file path + (alias: source) + Execute commands from path. + + start-server + (alias: start) + Start the tmux server, if not already running, without creating + any sessions. + + suspend-client [-t target-client] + (alias: suspendc) + Suspend a client by sending SIGTSTP (tty stop). + + switch-client [-lnpr] [-c target-client] [-t target-session] + (alias: switchc) + Switch the current session for client target-client to + target-session. If -l, -n or -p is used, the client is moved to + the last, next or previous session respectively. -r toggles + whether a client is read-only (see the attach-session command). + +WINDOWS AND PANES + A tmux 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 + paste buffer for later insertion into another window. This mode is + entered with the copy-mode command, bound to '[' by default. It is also + entered when a command that produces output, such as list-keys, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the mode-keys option). The following keys are supported as appropriate + for the mode: + + Function vi emacs + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump to forward t + Jump backward F F + Jump to backward T + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose characters C-t + + The next and previous word keys use space and the '-', '_' and '@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 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. + + The jump commands enable quick movement within a line. For instance, + typing 'f' followed by '/' will move the cursor to the next '/' character + on the current line. A ';' will then jump to the next occurrence. + + 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 'M-1 0 M-f' in emacs mode, and + '10w' in vi. + + When copying the selection, the repeat count indicates the buffer index + to replace, if used. + + Mode key bindings are defined in a set of named tables: vi-edit and + emacs-edit for keys used when line editing at the command prompt; + vi-choice and emacs-choice for keys used when choosing from lists (such + as produced by the choose-window command); and vi-copy and emacs-copy + used in copy mode. The tables may be viewed with the list-keys command + and keys modified or removed with bind-key and unbind-key. One command + accepts an argument, copy-pipe, which copies the selection and pipes it + to a command. For example the following will bind 'C-q' to copy the + selection into /tmp as well as the paste buffer: + + bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the copy-mode command is: + + copy-mode [-u] [-t target-pane] + Enter copy mode. The -u option scrolls one page up. + + Each window displayed by tmux may be split into one or more 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 split-window command. Windows + may be split horizontally (with the -h flag) or vertically. Panes may be + resized with the resize-pane command (bound to 'C-up', 'C-down' 'C-left' + and 'C-right' by default), the current pane may be changed with the + select-pane command and the rotate-window and 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. + + A number of preset layouts are available. These may be selected with the + select-layout command or cycled with next-layout (bound to 'Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + even-horizontal + Panes are spread out evenly from left to right across the window. + + even-vertical + Panes are spread evenly from top to bottom. + + 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 main-pane-height window option to + specify the height of the top pane. + + main-vertical + Similar to main-horizontal but the large pane is placed on the + left and the others spread from top to bottom along the right. + See the main-pane-width window option. + + tiled Panes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, select-layout may be used to apply a previously used layout + - the list-windows command displays the layout of each window in a form + suitable for use with select-layout. For example: + + $ 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} + + tmux 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. + + Commands related to windows and panes are as follows: + + break-pane [-dP] [-F format] [-t target-pane] + (alias: breakp) + Break target-pane off from its containing window to make it the + only pane in a new window. If -d is given, the new window does + not become the current window. The -P option prints information + about the new window after it has been created. By default, it + uses the format '#{session_name}:#{window_index}' but a different + format may be specified with -F. + + capture-pane [-aepPq] [-b buffer-index] [-E end-line] [-S start-line] [-t + target-pane] + (alias: capturep) + Capture the contents of a pane. If -p is given, the output goes + to stdout, otherwise to the buffer specified with -b or a new + buffer if omitted. If -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 -q is given. If -e is + given, the output includes escape sequences for text and back- + ground attributes. -C also escapes non-printable characters as + octal \xxx. -J joins wrapped lines and preserves trailing spaces + at each line's end. -P captures only any output that the pane + has received that is the beginning of an as-yet incomplete escape + sequence. + + -S and -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 con- + tents of the pane. + + choose-client [-F format] [-t target-window] [template] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + '%%' is replaced by the client pty(4) path in template and the + result executed as a command. If template is not given, "detach- + client -t '%%'" is used. For the meaning of the -F flag, see the + FORMATS section. This command works only if at least one client + is attached. + + choose-list [-l items] [-t target-window] [template] + Put a window into list choice mode, allowing items to be + selected. 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, '%%' is replaced by the chosen item in + the template and the result is executed as a command. If + template is not given, "run-shell '%%'" is used. items also + accepts format specifiers. For the meaning of this see the + FORMATS section. This command works only if at least one client + is attached. + + choose-session [-F format] [-t target-window] [template] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, '%%' is + replaced by the session name in template and the result executed + as a command. If template is not given, "switch-client -t '%%'" + is used. For the meaning of the -F flag, see the FORMATS sec- + tion. This command works only if at least one client is + attached. + + choose-tree [-suw] [-b session-template] [-c window-template] [-S format] + [-W format] [-t target-window] + Put a window into tree choice mode, where either sessions or win- + dows may be selected interactively from a list. By default, win- + dows belonging to a session are indented to show their relation- + ship to a session. + + Note that the choose-window and choose-session commands are wrap- + pers around choose-tree. + + If -s is given, will show sessions. If -w is given, will show + windows. + + By default, the tree is collapsed and sessions must be expanded + to windows with the right arrow key. The -u option will start + with all sessions expanded instead. + + If -b is given, will override the default session command. Note + that '%%' can be used and will be replaced with the session name. + The default option if not specified is "switch-client -t '%%'". + If -c is given, will override the default window command. Like + -b, '%%' 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. + + If -S is given will display the specified format instead of the + default session format. If -W is given will display the speci- + fied format instead of the default window format. For the mean- + ing of the -s and -w options, see the FORMATS section. + + This command works only if at least one client is attached. + + choose-window [-F format] [-t target-window] [template] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, '%%' + is replaced by the session name and window index in template and + the result executed as a command. If template is not given, + "select-window -t '%%'" is used. For the meaning of the -F flag, + see the FORMATS section. This command works only if at least one + client is attached. + + display-panes [-t target-client] + (alias: displayp) + Display a visible indicator of each pane shown by target-client. + See the display-panes-time, display-panes-colour, and + display-panes-active-colour session options. While the indicator + is on screen, a pane may be selected with the '0' to '9' keys. + + find-window [-CNT] [-F format] [-t target-window] match-string + (alias: findw) + Search for the fnmatch(3) pattern match-string in window names, + titles, and visible content (but not history). The flags control + matching behavior: -C matches only visible window contents, -N + matches only the window name and -T matches only the window + title. The default is -CNT. If only one window is matched, + it'll be automatically selected, otherwise a choice list is + shown. For the meaning of the -F flag, see the FORMATS section. + This command works only if at least one client is attached. + + join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: joinp) + Like split-window, but instead of splitting dst-pane and creating + a new pane, split it and move src-pane into the space. This can + be used to reverse break-pane. The -b option causes src-pane to + be joined to left of or above dst-pane. + + kill-pane [-a] [-t target-pane] + (alias: killp) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The -a option kills all but the + pane given with -t. + + kill-window [-a] [-t target-window] + (alias: killw) + Kill the current window or the window at target-window, removing + it from any sessions to which it is linked. The -a option kills + all but the window given with -t. + + last-pane [-t target-window] + (alias: lastp) + Select the last (previously selected) pane. + + last-window [-t target-session] + (alias: last) + Select the last (previously selected) window. If no + target-session is specified, select the last window of the cur- + rent session. + + link-window [-dk] [-s src-window] [-t dst-window] + (alias: linkw) + Link the window at src-window to the specified dst-window. If + dst-window is specified and no such window exists, the src-window + is linked there. If -k is given and dst-window exists, it is + killed, otherwise an error is generated. If -d is given, the + newly linked window is not selected. + + list-panes [-as] [-F format] [-t target] + (alias: lsp) + If -a is given, target is ignored and all panes on the server are + listed. If -s is given, target is a session (or the current ses- + sion). If neither is given, target is a window (or the current + window). For the meaning of the -F flag, see the FORMATS sec- + tion. + + list-windows [-a] [-F format] [-t target-session] + (alias: lsw) + If -a is given, list all windows on the server. Otherwise, list + windows in the current session or in target-session. For the + meaning of the -F flag, see the FORMATS section. + + move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane] + (alias: movep) + Like join-pane, but src-pane and dst-pane may belong to the same + window. + + move-window [-rdk] [-s src-window] [-t dst-window] + (alias: movew) + This is similar to link-window, except the window at src-window + is moved to dst-window. With -r, all windows in the session are + renumbered in sequential order, respecting the base-index option. + + new-window [-adkP] [-c start-directory] [-F format] [-n window-name] [-t + target-window] [shell-command] + (alias: neww) + Create a new window. With -a, the new window is inserted at the + next index up from the specified target-window, moving windows up + if necessary, otherwise target-window is the new window location. + + If -d is given, the session does not make the new window the cur- + rent window. target-window represents the window to be created; + if the target already exists an error is shown, unless the -k + flag is used, in which case it is destroyed. shell-command is + the command to execute. If shell-command is not specified, the + value of the default-command option is used. -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 subdi- + rectory): + + Empty string Current pane's directory + ~ User's home directory + - Where session was started + . Where server was started + + When the shell command completes, the window closes. See the + remain-on-exit option to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running inside tmux. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The -P option prints information about the new window after it + has been created. By default, it uses the format + '#{session_name}:#{window_index}' but a different format may be + specified with -F. + + next-layout [-t target-window] + (alias: nextl) + Move a window to the next layout and rearrange the panes to fit. + + next-window [-a] [-t target-session] + (alias: next) + Move to the next window in the session. If -a is used, move to + the next window with an alert. + + pipe-pane [-o] [-t target-pane] [shell-command] + (alias: pipep) + Pipe any output sent by the program in target-pane to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before shell-command is executed. The + shell-command string may contain the special character sequences + supported by the status-left option. If no shell-command is + given, the current pipe (if any) is closed. + + The -o option only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + previous-layout [-t target-window] + (alias: prevl) + Move to the previous layout in the session. + + previous-window [-a] [-t target-session] + (alias: prev) + Move to the previous window in the session. With -a, move to the + previous window with an alert. + + rename-window [-t target-window] new-name + (alias: renamew) + Rename the current window, or the window at target-window if + specified, to new-name. + + resize-pane [-DLRUZ] [-t target-pane] [-x width] [-y height] [adjustment] + (alias: resizep) + Resize a pane, up, down, left or right by adjustment with -U, -D, + -L or -R, or to an absolute size with -x or -y. The adjustment + is given in lines or cells (the default is 1). + + With -Z, the active pane is toggled between zoomed (occupying the + whole of the window) and unzoomed (its normal position in the + layout). + + respawn-pane [-k] [-t target-pane] [shell-command] + (alias: respawnp) + Reactivate a pane in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless -k is given, in which case any + existing command is killed. + + respawn-window [-k] [-t target-window] [shell-command] + (alias: respawnw) + Reactivate a window in which the command has exited (see the + remain-on-exit window option). If shell-command is not given, + the command used when the window was created is executed. The + window must be already inactive, unless -k is given, in which + case any existing command is killed. + + rotate-window [-DU] [-t target-window] + (alias: rotatew) + Rotate the positions of the panes within a window, either upward + (numerically lower) with -U or downward (numerically higher). + + select-layout [-np] [-t target-window] [layout-name] + (alias: selectl) + Choose a specific layout for a window. If layout-name is not + given, the last preset layout used (if any) is reapplied. -n and + -p are equivalent to the next-layout and previous-layout com- + mands. + + select-pane [-lDLRU] [-t target-pane] + (alias: selectp) + Make pane target-pane the active pane in window target-window. + If one of -D, -L, -R, or -U is used, respectively the pane below, + to the left, to the right, or above the target pane is used. -l + is the same as using the last-pane command. + + select-window [-lnpT] [-t target-window] + (alias: selectw) + Select the window at target-window. -l, -n and -p are equivalent + to the last-window, next-window and previous-window commands. If + -T is given and the selected window is already the current win- + dow, the command behaves like last-window. + + split-window [-dhvP] [-c start-directory] [-l size | -p percentage] [-t + target-pane] [shell-command] [-F format] + (alias: splitw) + Create a new pane by splitting target-pane: -h does a horizontal + split and -v a vertical split; if neither is specified, -v is + assumed. The -l and -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 new-window command. + + swap-pane [-dDU] [-s src-pane] [-t dst-pane] + (alias: swapp) + Swap two panes. If -U is used and no source pane is specified + with -s, dst-pane is swapped with the previous pane (before it + numerically); -D swaps with the next pane (after it numerically). + -d instructs tmux not to change the active pane. + + swap-window [-d] [-s src-window] [-t dst-window] + (alias: swapw) + This is similar to link-window, except the source and destination + windows are swapped. It is an error if no window exists at + src-window. + + unlink-window [-k] [-t target-window] + (alias: unlinkw) + Unlink target-window. Unless -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 -k is specified and the window + is linked to only one session, it is unlinked and destroyed. + +KEY BINDINGS + tmux allows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example 'A' to + 'Z'). Ctrl keys may be prefixed with 'C-' or '^', and Alt (meta) with + 'M-'. In addition, the following special key names are accepted: Up, + Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to + F20, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space, + and Tab. Note that to bind the '"' or ''' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + bind-key [-cnr] [-t key-table] key command [arguments] + (alias: bind) + Bind key key to command. By default (without -t) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if -n is specified, it is not necessary to + use the prefix key, command is bound to key alone. The -r flag + indicates this key may repeat, see the repeat-time option. + + If -t is present, key is bound in key-table: the binding for com- + mand mode with -c or for normal mode without. To view the + default bindings and possible commands, see the list-keys com- + mand. + + list-keys [-t key-table] + (alias: lsk) + List all key bindings. Without -t the primary key bindings - + those executed when preceded by the prefix key - are printed. + + With -t, the key bindings in key-table are listed; this may be + one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or + emacs-copy. + + send-keys [-lR] [-t target-pane] key ... + (alias: send) + Send a key or keys to a window. Each argument key is the name of + the key (such as 'C-a' or 'npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. The + -l flag disables key name lookup and sends the keys literally. + All arguments are sent sequentially from first to last. The -R + flag causes the terminal state to be reset. + + send-prefix [-2] [-t target-pane] + Send the prefix key, or with -2 the secondary prefix key, to a + window as if it was pressed. + + unbind-key [-acn] [-t key-table] key + (alias: unbind) + Unbind the command bound to key. Without -t the primary key + bindings are modified; in this case, if -n is specified, the com- + mand bound to key without a prefix (if any) is removed. If -a is + present, all key bindings are removed. + + If -t is present, key in key-table is unbound: the binding for + command mode with -c or for normal mode without. + +OPTIONS + The appearance and behaviour of tmux may be modified by changing the + value of various options. There are three types of option: server + options, session options and window options. + + The tmux server has a set of global options which do not apply to any + particular window or session. These are altered with the set-option -s + command, or displayed with the show-options -s command. + + 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 set-option + command and may be listed with the show-options command. The available + server and session options are listed under the set-option command. + + 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 inher- + ited. Window options are altered with the set-window-option command and + can be listed with the show-window-options command. All window options + are documented with the set-window-option command. + + tmux also supports user options which are prefixed with a '@'. User + options may have any name, so long as they are prefixed with '@', and be + set to any string. For example + + $ tmux setw -q @foo "abc123" + $ tmux showw -v @foo + abc123 + + Commands which set options are as follows: + + set-option [-agoqsuw] [-t target-session | target-window] option value + (alias: set) + Set a window option with -w (equivalent to the set-window-option + command), a server option with -s, otherwise a session option. + + If -g is specified, the global session or window option is set. + With -a, and if the option expects a string, value is appended to + the existing setting. The -u flag unsets an option, so a session + inherits the option from the global options. It is not possible + to unset a global option. + + The -o flag prevents setting an option that is already set. + + The -q flag suppresses the informational message (as if the quiet + server option was set). + + Available window options are listed under set-window-option. + + value depends on the option and may be a number, a string, or a + flag (on, off, or omitted to toggle). + + Available server options are: + + buffer-limit number + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + escape-time time + Set the time in milliseconds for which tmux waits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + exit-unattached [on | off] + If enabled, the server will exit when there are no + attached clients. + + quiet [on | off] + Enable or disable the display of various informational + messages (see also the -q command line flag). + + set-clipboard [on | off] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an Ms entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + Available session options are: + + assume-paste-time milliseconds + If keys are entered faster than one in milliseconds, they + are assumed to have been pasted rather than typed and + tmux key bindings are not processed. The default is one + millisecond and zero disables. + + base-index index + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + bell-action [any | none | current] + Set action on window bell. any means a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, none means all bells are ignored and + current means only bells in windows other than the cur- + rent window are ignored. + + bell-on-alert [on | off] + If on, ring the terminal bell when an alert occurs. + + default-command shell-command + Set the command used for new windows (if not specified + when the window is created) to shell-command, which may + be any sh(1) command. The default is an empty string, + which instructs tmux to create a login shell using the + value of the default-shell option. + + default-path 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 -c flag to new-window. + + default-shell path + Specify the default shell. This is used as the login + shell for new windows when the default-command option is + set to empty, and must be the full path of the exe- + cutable. When started tmux tries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or /bin/sh. + This option should be configured when tmux is used as a + login shell. + + default-terminal terminal + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For tmux to work correctly, this must be set to + 'screen' or a derivative of it. + + destroy-unattached [on | off] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + detach-on-destroy [on | off] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + display-panes-active-colour colour + Set the colour used by the display-panes command to show + the indicator for the active pane. + + display-panes-colour colour + Set the colour used by the display-panes command to show + the indicators for inactive panes. + + display-panes-time time + Set the time in milliseconds for which the indicators + shown by the display-panes command appear. + + display-time time + Set the amount of time for which status line messages and + other on-screen indicators are displayed. time is in + milliseconds. + + history-limit lines + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + lock-after-time number + Lock the session (like the lock-session command) after + number seconds of inactivity, or the entire server (all + sessions) if the lock-server option is set. The default + is not to lock (set to 0). + + lock-command shell-command + Command to run when locking each client. The default is + to run lock(1) with -np. + + lock-server [on | off] + If this option is on (the default), instead of each ses- + sion locking individually as each has been idle for + lock-after-time, the entire server will lock after all + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + message-attr attributes + Set status line message attributes, where attributes is + either none or a comma-delimited list of one or more of: + bright (or bold), dim, underscore, blink, reverse, + hidden, or italics. + + message-bg colour + Set status line message background colour, where colour + is one of: black, red, green, yellow, blue, magenta, + cyan, white, aixterm bright variants (if supported: + brightred, brightgreen, and so on), colour0 to colour255 + from the 256-colour set, default, or a hexadecimal RGB + string such as '#ffffff', which chooses the closest match + from the default 256-colour set. + + message-command-attr attributes + Set status line message attributes when in command mode. + + message-command-bg colour + Set status line message background colour when in command + mode. + + message-command-fg colour + Set status line message foreground colour when in command + mode. + + message-fg colour + Set status line message foreground colour. + + message-limit number + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + mouse-resize-pane [on | off] + If on, tmux captures the mouse and allows panes to be + resized by dragging on their borders. + + mouse-select-pane [on | off] + If on, tmux 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. + + mouse-select-window [on | off] + If on, clicking the mouse on a window name in the status + line will select that window. + + mouse-utf8 [on | off] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + pane-active-border-bg colour + + pane-active-border-fg colour + Set the pane border colour for the currently active pane. + + pane-border-bg colour + + pane-border-fg colour + Set the pane border colour for panes aside from the + active pane. + + prefix key + Set the key accepted as a prefix key. + + prefix2 key + Set a secondary key accepted as a prefix key. + + renumber-windows [on | off] + If on, when a window is closed in a session, automati- + cally renumber the other windows in numerical order. + This respects the base-index option if it has been set. + If off, do not renumber the windows. + + repeat-time time + Allow multiple commands to be entered without pressing + the prefix-key again in the specified time milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the -r flag to bind-key. Repeat + is enabled for the default keys bound to the resize-pane + command. + + set-remain-on-exit [on | off] + Set the 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 + respawn-window command to reactivate such a window, or + the kill-window command to destroy it. + + set-titles [on | off] + Attempt to set the client terminal title using the tsl + and fsl terminfo(5) entries if they exist. tmux automat- + ically sets these to the \e]2;...\007 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. + + set-titles-string string + String used to set the window title if set-titles is on. + Character sequences are replaced as for the status-left + option. + + status [on | off] + Show or hide the status line. + + status-attr attributes + Set status line attributes. + + status-bg colour + Set status line background colour. + + status-fg colour + Set status line foreground colour. + + status-interval interval + Update the status bar every interval seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + status-justify [left | centre | right] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + status-keys [vi | emacs] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string 'vi'. + + status-left string + Display string to the left of the status bar. string + will be passed through strftime(3) before being used. By + default, the session name is shown. string may contain + any of the following special character sequences: + + Character pair Replaced with + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + #H Hostname of local host + #h Hostname of local host without + the domain name + #F Current window flag + #I Current window index + #D Current pane unique identifier + #P Current pane index + #S Session name + #T Current pane title + #W Current window name + ## A literal '#' + + The #(shell-command) form executes 'shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the status-interval option: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the tmux global environ- + ment set (see the ENVIRONMENT section). + + For details on how the names and titles can be set see + the NAMES AND TITLES section. + + #[attributes] allows a comma-separated list of attributes + to be specified, these may be 'fg=colour' to set the + foreground colour, 'bg=colour' to set the background + colour, the name of one of the attributes (listed under + the message-attr option) to turn an attribute on, or an + attribute prefixed with 'no' to turn one off, for example + nobright. Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example '#24T'. + + By default, UTF-8 in string is not interpreted, to enable + UTF-8, use the status-utf8 option. + + status-left-attr attributes + Set the attribute of the left part of the status line. + + status-left-bg colour + Set the background colour of the left part of the status + line. + + status-left-fg colour + Set the foreground colour of the left part of the status + line. + + status-left-length length + Set the maximum length of the left component of the sta- + tus bar. The default is 10. + + status-position [top | bottom] + Set the position of the status line. + + status-right string + Display 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 status-left, string + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the status-utf8 + option. + + status-right-attr attributes + Set the attribute of the right part of the status line. + + status-right-bg colour + Set the background colour of the right part of the status + line. + + status-right-fg colour + Set the foreground colour of the right part of the status + line. + + status-right-length length + Set the maximum length of the right component of the sta- + tus bar. The default is 40. + + status-utf8 [on | off] + Instruct tmux to treat top-bit-set characters in the + status-left and status-right strings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + terminal-overrides string + Contains a list of entries which override terminal + descriptions read using terminfo(5). string is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of name=value entries. + + For example, to set the 'clear' terminfo(5) entry to + '\e[H\e[2J' for all terminal types and the 'dch1' entry + to '\e[P' for the 'rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the 'colors' entry for terminals which support 88 + or 256 colours: + + "*88col*:colors=88,*256col*:colors=256,xterm*:XT" + + update-environment variables + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 -r was given to the set-environment + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + visual-activity [on | off] + If on, display a status line message when activity occurs + in a window for which the monitor-activity window option + is enabled. + + visual-bell [on | off] + 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 bell-action + option. + + visual-content [on | off] + Like visual-activity, display a message when content is + present in a window for which the monitor-content window + option is enabled. + + visual-silence [on | off] + If monitor-silence is enabled, prints a message after the + interval has expired on a given window. + + word-separators string + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ' -_@'. + + set-window-option [-agqu] [-t target-window] option value + (alias: setw) + Set a window option. The -a, -g, -q and -u flags work similarly + to the set-option command. + + Supported window options are: + + aggressive-resize [on | off] + Aggressively resize the chosen window. This means that + tmux 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 SIGWINCH and poor for interactive programs + such as shells. + + allow-rename [on | off] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + alternate-screen [on | off] + This option configures whether programs running inside + tmux may use the terminal alternate screen feature, which + allows the smcup and rmcup 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. + + automatic-rename [on | off] + Control automatic window renaming. When this setting is + enabled, tmux will attempt - on supported platforms - to + rename the window to reflect the command currently run- + ning in it. This flag is automatically disabled for an + individual window when a name is specified at creation + with new-window or new-session, or later with + rename-window, or with a terminal escape sequence. It + may be switched off globally with: + + set-window-option -g automatic-rename off + + c0-change-interval interval + c0-change-trigger trigger + These two options configure a simple form of rate limit- + ing for a pane. If tmux sees more than 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 interval milliseconds. This + helps to prevent fast output (such as 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. + + clock-mode-colour colour + Set clock colour. + + clock-mode-style [12 | 24] + Set clock hour format. + + force-height height + force-width width + Prevent tmux from resizing a window to greater than width + or height. A value of zero restores the default unlim- + ited setting. + + main-pane-height height + main-pane-width width + Set the width or height of the main (left or top) pane in + the main-horizontal or main-vertical layouts. + + mode-attr attributes + Set window modes attributes. + + mode-bg colour + Set window modes background colour. + + mode-fg colour + Set window modes foreground colour. + + mode-keys [vi | emacs] + Use vi or emacs-style key bindings in copy and choice + modes. As with the status-keys option, the default is + emacs, unless VISUAL or EDITOR contains 'vi'. + + mode-mouse [on | off | copy-mode] + 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 copy-mode, + the mouse behaves as set to on, but cannot be used to + enter copy mode. + + monitor-activity [on | off] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + monitor-content match-string + Monitor content in the window. When fnmatch(3) pattern + match-string appears in the window, it is highlighted in + the status line. + + monitor-silence [interval] + Monitor for silence (no activity) in the window within + interval seconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + other-pane-height height + Set the height of the other panes (not the main pane) in + the main-horizontal layout. If this option is set to 0 + (the default), it will have no effect. If both the + main-pane-height and 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. + + other-pane-width width + Like other-pane-height, but set the width of other panes + in the main-vertical layout. + + pane-base-index index + Like base-index, but set the starting index for pane num- + bers. + + remain-on-exit [on | off] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the respawn-window command. + + synchronize-panes [on | off] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + utf8 [on | off] + Instructs tmux to expect UTF-8 sequences to appear in + this window. + + window-status-bell-attr attributes + Set status line attributes for windows which have a bell + alert. + + window-status-bell-bg colour + Set status line background colour for windows with a bell + alert. + + window-status-bell-fg colour + Set status line foreground colour for windows with a bell + alert. + + window-status-content-attr attributes + Set status line attributes for windows which have a con- + tent alert. + + window-status-content-bg colour + Set status line background colour for windows with a con- + tent alert. + + window-status-content-fg colour + Set status line foreground colour for windows with a con- + tent alert. + + window-status-activity-attr attributes + Set status line attributes for windows which have an + activity (or silence) alert. + + window-status-activity-bg colour + Set status line background colour for windows with an + activity alert. + + window-status-activity-fg colour + Set status line foreground colour for windows with an + activity alert. + + window-status-attr attributes + Set status line attributes for a single window. + + window-status-bg colour + Set status line background colour for a single window. + + window-status-current-attr attributes + Set status line attributes for the currently active win- + dow. + + window-status-current-bg colour + Set status line background colour for the currently + active window. + + window-status-current-fg colour + Set status line foreground colour for the currently + active window. + + window-status-current-format string + Like window-status-format, but is the format used when + the window is the current window. + + window-status-last-attr attributes + Set status line attributes for the last active window. + + window-status-last-bg colour + Set status line background colour for the last active + window. + + window-status-last-fg colour + Set status line foreground colour for the last active + window. + + window-status-fg colour + Set status line foreground colour for a single window. + + window-status-format string + Set the format in which the window is displayed in the + status line window list. See the status-left option for + details of special character sequences available. The + default is '#I:#W#F'. + + window-status-separator string + Sets the separator drawn between windows in the status + line. The default is a single space character. + + xterm-keys [on | off] + If this option is set, tmux will generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + wrap-search [on | off] + If this option is set, searches will wrap around the end + of the pane contents. The default is on. + + show-options [-gqsvw] [-t target-session | target-window] [option] + (alias: show) + Show the window options (or a single window option if given) with + -w (equivalent to show-window-options), the server options with + -s, otherwise the session options for target session. Global + session or window options are listed if -g is used. -v shows + only the option value, not the name. If -q is set, no error will + be returned if option is unset. + + show-window-options [-gv] [-t target-window] [option] + (alias: showw) + List the window options or a single option for target-window, or + the global window options if -g is used. -v shows only the + option value, not the name. + +FORMATS + Certain commands accept the -F flag with a format argument. This is a + string which controls the output format of the command. Special charac- + ter sequences are replaced as documented under the status-left option and + an additional long form is accepted. Replacement variables are enclosed + in '#{' and '}', for example '#{session_name}' is equivalent to '#S'. + Conditionals are also accepted by prefixing with '?' 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 '#{?session_attached,attached,not attached}' will include the + string 'attached' if the session is attached and the string 'not + attached' if it is unattached. + + The following variables are available, where appropriate: + + Variable name Replaced with + alternate_on If pane is in alternate screen + alternate_saved_x Saved cursor X in alternate screen + alternate_saved_y Saved cursor Y in alternate screen + buffer_sample First 50 characters from the specified + buffer + buffer_size Size of the specified buffer in bytes + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_cwd Working directory of client + client_height Height of client + client_last_session Name of the client's last session + client_prefix 1 if prefix key has been pressed + client_readonly 1 if client is readonly + client_session Name of the client's session + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + cursor_flag Pane cursor flag + cursor_x Cursor X position in pane + cursor_y Cursor Y position in pane + history_bytes Number of bytes in window history + history_limit Maximum window history lines + history_size Size of history in bytes + host Hostname of local host + insert_flag Pane insert flag + keypad_cursor_flag Pane keypad cursor flag + keypad_flag Pane keypad flag + line Line number in the list + mouse_any_flag Pane mouse any flag + mouse_button_flag Pane mouse button flag + mouse_standard_flag Pane mouse standard flag + mouse_utf8_flag Pane mouse UTF-8 flag + pane_active 1 if active pane + pane_current_command Current command if available + pane_current_path Current path if available + pane_dead 1 if pane is dead + pane_height Height of pane + pane_id Unique pane ID + pane_in_mode If pane is in a mode + pane_index Index of pane + pane_pid PID of first process in pane + pane_start_command Command pane started with + pane_start_path Path pane started with + pane_tabs Pane tab positions + pane_title Title of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + saved_cursor_x Saved cursor X in pane + saved_cursor_y Saved cursor Y in pane + scroll_region_lower Bottom of scroll region in pane + scroll_region_upper Top of scroll region in pane + session_attached 1 if session attached + session_created Integer time session created + session_created_string String time session created + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_id Unique session ID + session_name Name of session + session_width Width of session + session_windows Number of windows in session + window_active 1 if window active + window_find_matches Matched data from the find-window command + if available + window_flags Window flags + window_height Height of window + window_id Unique window ID + window_index Index of window + window_layout Window layout description + window_name Name of window + window_panes Number of panes in window + window_width Width of window + wrap_flag Pane wrap flag + +NAMES AND TITLES + tmux 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 tmux 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 tmux. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. tmux itself may set + the title of the terminal in which the client is running, see the + set-titles option. + + A session's name is set with the new-session and rename-session commands. + A window's name is set with one of: + + 1. A command argument (such as -n for new-window or new-session). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the automatic-rename option. + + 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: + + $ printf '\033]2;My Title\033\\' + +ENVIRONMENT + When the server is started, tmux copies the environment into the global + environment; in addition, each session has a 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. + + The update-environment session option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. tmux also initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of 'screen'. + + Commands to alter and view the environment are: + + set-environment [-gru] [-t target-session] name [value] + (alias: setenv) + Set or unset an environment variable. If -g is used, the change + is made in the global environment; otherwise, it is applied to + the session environment for target-session. The -u flag unsets a + variable. -r indicates the variable is to be removed from the + environment before starting a new process. + + show-environment [-g] [-t target-session] [variable] + (alias: showenv) + Display the environment for target-session or the global environ- + ment with -g. If variable is omitted, all variables are shown. + Variables removed from the environment are prefixed with '-'. + +STATUS LINE + tmux 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 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the status-left, status-left-length, status-right, + and 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 window-status-format and + window-status-current-format options. The flag is one of the following + symbols appended to the window name: + + Symbol Meaning + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + Z The window's active pane is zoomed. + + The # symbol relates to the monitor-activity and + to the monitor-content + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the status-attr, status-fg and status-bg session + options and individual windows using the window-status-attr, + window-status-fg and window-status-bg window options. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the status-interval session option. + + Commands related to the status line are as follows: + + command-prompt [-I inputs] [-p prompts] [-t target-client] [template] + Open the command prompt in a client. This may be used from + inside tmux to execute commands interactively. + + If template is specified, it is used as the command. If present, + -I is a comma-separated list of the initial text for each prompt. + If -p is given, prompts is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from template if it is present, or ':' if + not. + + Both inputs and prompts may contain the special character + sequences supported by the status-left option. + + Before the command is executed, the first occurrence of the + string '%%' and all occurrences of '%1' are replaced by the + response to the first prompt, the second '%%' and all '%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + ('%1' to '%9'). + + confirm-before [-p prompt] [-t target-client] command + (alias: confirm) + Ask for confirmation before executing command. If -p is given, + prompt is the prompt to display; otherwise a prompt is con- + structed from command. It may contain the special character + sequences supported by the status-left option. + + This command works only from inside tmux. + + display-message [-p] [-c target-client] [-t target-pane] [message] + (alias: display) + Display a message. If -p is given, the output is printed to std- + out, otherwise it is displayed in the target-client status line. + The format of message is described in the FORMATS section; infor- + mation is taken from target-pane if -t is given, otherwise the + active pane for the session attached to target-client. + +BUFFERS + tmux maintains a stack of paste buffers. Up to the value of the + 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 copy-mode + or the set-buffer command, and pasted into a window using the + paste-buffer command. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + history-limit option (see the set-option command above). + + The buffer commands are as follows: + + choose-buffer [-F format] [-t target-window] [template] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, '%%' + is replaced by the buffer index in template and the result exe- + cuted as a command. If template is not given, "paste-buffer -b + '%%'" is used. For the meaning of the -F flag, see the FORMATS + section. This command works only if at least one client is + attached. + + clear-history [-t target-pane] + (alias: clearhist) + Remove and free the history for the specified pane. + + delete-buffer [-b buffer-index] + (alias: deleteb) + Delete the buffer at buffer-index, or the top buffer if not spec- + ified. + + list-buffers [-F format] + (alias: lsb) + List the global buffers. For the meaning of the -F flag, see the + FORMATS section. + + load-buffer [-b buffer-index] path + (alias: loadb) + Load the contents of the specified paste buffer from path. + + paste-buffer [-dpr] [-b buffer-index] [-s separator] [-t target-pane] + (alias: pasteb) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With -d, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the -s flag. The -r flag means to do no + replacement (equivalent to a separator of LF). If -p is speci- + fied, paste bracket control codes are inserted around the buffer + if the application has requested bracketed paste mode. + + save-buffer [-a] [-b buffer-index] path + (alias: saveb) + Save the contents of the specified paste buffer to path. The -a + option appends to rather than overwriting the file. + + set-buffer [-b buffer-index] data + (alias: setb) + Set the contents of the specified buffer to data. + + show-buffer [-b buffer-index] + (alias: showb) + Display the contents of the specified buffer. + +MISCELLANEOUS + Miscellaneous commands are as follows: + + clock-mode [-t target-pane] + Display a large clock. + + if-shell [-b] [-t target-pane] shell-command command [command] + (alias: if) + Execute the first command if shell-command returns success or the + second command otherwise. Before being executed, shell-command + is expanded using the rules specified in the FORMATS section, + including those relevant to target-pane. With -b, shell-command + is run in the background. + + lock-server + (alias: lock) + Lock each client individually by running the command specified by + the lock-command option. + + run-shell -b [-t target-pane] shell-command + (alias: run) + Execute shell-command in the background without creating a win- + dow. Before being executed, shell-command is expanded using the + rules specified in the FORMATS section. With -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 -t or the + current pane if omitted). If the command doesn't return success, + the exit status is also displayed. + + server-info + (alias: info) + Show server information and terminal details. + + wait-for -LSU channel + (alias: wait) + When used without options, prevents the client from exiting until + woken using wait-for -S with the same channel. When -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 + wait-for -U. This command only works from outside tmux. + +TERMINFO EXTENSIONS + tmux understands some extensions to terminfo(5): + + 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 tmux: + + $ printf '\033]12;red\033\\' + + Cs, Csr + Change the cursor style. If set, a sequence such as this may be + used to change the cursor to an underline: + + $ printf '\033[4 q' + + If Csr is set, it will be used to reset the cursor style instead + of Cs. + + Ms This sequence can be used by tmux to store the current buffer in + the host terminal's selection (clipboard). See the set-clipboard + option above and the xterm(1) man page. + +CONTROL MODE + tmux offers a textual interface called control mode. This allows appli- + cations to communicate with tmux using a simple text-only protocol. + + In control mode, a client sends tmux commands or command sequences termi- + nated by newlines on standard input. Each command will produce one block + of output on standard output. An output block consists of a %begin line + followed by the output (which may be empty). The output block ends with + a %end or %error. %begin and matching %end or %error have two arguments: + an integer time (as seconds from epoch) and command number. For example: + + %begin 1363006971 2 + 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) + %end 1363006971 2 + + In control mode, tmux outputs notifications. A notification will never + occur inside an output block. + + The following notifications are defined: + + %exit [reason] + The tmux client is exiting immediately, either because it is not + attached to any session or an error occurred. If present, reason + describes why the client exited. + + %layout-change window-id window-layout + The layout of a window with ID window-id changed. The new layout + is window-layout. + + %output pane-id value + A window pane produced output. value escapes non-printable char- + acters and backslash as octal \xxx. + + %session-changed session-id name + The client is now attached to the session with ID session-id, + which is named name. + + %session-renamed name + The current session was renamed to name. + + %sessions-changed + A session was created or destroyed. + + %unlinked-window-add window-id + The window with ID window-id was created but is not linked to the + current session. + + %window-add window-id + The window with ID window-id was linked to the current session. + + %window-close window-id + The window with ID window-id closed. + + %window-renamed window-id name + The window with ID window-id was renamed to name. + +FILES + ~/.tmux.conf Default tmux configuration file. + /etc/tmux.conf System-wide configuration file. + +EXAMPLES + To create a new tmux session running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is new: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing 'C-b c' + (Ctrl followed by the 'b' key followed by the 'c' key). + + Windows may be navigated with: 'C-b 0' (to select window 0), 'C-b 1' (to + select window 1), and so on; 'C-b n' to select the next window; and 'C-b + p' to select the previous window. + + A session may be detached using 'C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing 'C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or 'q' to exit from it. + + Commands to be run when the tmux server is started may be placed in the + ~/.tmux.conf configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-bg blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +SEE ALSO + pty(4) + +AUTHORS + Nicholas Marriott + +BSD October 19, 2013 BSD diff --git a/manual/1.9.txt b/manual/1.9.txt new file mode 100644 index 0000000..6cfe254 --- /dev/null +++ b/manual/1.9.txt @@ -0,0 +1,2117 @@ +TMUX(1) FreeBSD General Commands Manual TMUX(1) + +1mNAME0m + 1mtmux 22m-- terminal multiplexer + +1mSYNOPSIS0m + 1mtmux 22m[1m-2lCquvV22m] [1m-c 4m22mshell-command24m] [1m-f 4m22mfile24m] [1m-L 4m22msocket-name24m] + [1m-S 4m22msocket-path24m] [4mcommand24m [4mflags24m]] + +1mDESCRIPTION0m + 1mtmux 22mis a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. 1mtmux 22mmay be + detached from a screen and continue running in the background, then later + reattached. + + When 1mtmux 22mis started it creates a new 4msession24m with a single 4mwindow24m 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 com- + mands. + + A session is a single collection of 4mpseudo24m 4mterminals24m under the management + of 1mtmux22m. 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 pty(4) manual page documents + the technical details of pseudo terminals). Any number of 1mtmux 22minstances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, 1mtmux 22mexits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + `C-b d' key strokes). 1mtmux 22mmay be reattached using: + + $ tmux attach + + In 1mtmux22m, a session is displayed on screen by a 4mclient24m and all sessions + are managed by a single 4mserver24m. The server and each client are separate + processes which communicate through a socket in 4m/tmp24m. + + The options are as follows: + + 1m-2 22mForce 1mtmux 22mto assume the terminal supports 256 colours. + + 1m-C 22mStart in control mode (see the 4mCONTROL24m 4mMODE24m section). + Given twice (1m-CC22m) disables echo. + + 1m-c 4m22mshell-command0m + Execute 4mshell-command24m using the default shell. If neces- + sary, the 1mtmux 22mserver will be started to retrieve the + 1mdefault-shell 22moption. This option is for compatibility + with sh(1) when 1mtmux 22mis used as a login shell. + + 1m-f 4m22mfile24m Specify an alternative configuration file. By default, + 1mtmux 22mloads the system configuration file from + 4m@SYSCONFDIR@/tmux.conf24m, if present, then looks for a user + configuration file at 4m~/.tmux.conf24m. + + The configuration file is a set of 1mtmux 22mcommands which are + executed in sequence when the server is first started. + 1mtmux 22mloads configuration files once when the server process + has started. The 1msource-file 22mcommand may be used to load a + file later. + + 1mtmux 22mshows any error messages from commands in configura- + tion files in the first session created, and continues to + process the rest of the configuration file. + + 1m-L 4m22msocket-name0m + 1mtmux 22mstores the server socket in a directory under + TMUX_TMPDIR, TMPDIR if it is unset, or 4m/tmp24m if both are + unset. The default socket is named 4mdefault24m. This option + allows a different socket name to be specified, allowing + several independent 1mtmux 22mservers to be run. Unlike 1m-S 22ma + full path is not necessary: the sockets are all created in + the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the 1mtmux 22mserver process to recreate it. + + 1m-l 22mBehave as a login shell. This flag currently has no effect + and is for compatibility with other shells when using tmux + as a login shell. + + 1m-q 22mSet the 1mquiet 22mserver option to prevent the server sending + various informational messages. + + 1m-S 4m22msocket-path0m + Specify a full alternative path to the server socket. If + 1m-S 22mis specified, the default socket directory is not used + and any 1m-L 22mflag is ignored. + + 1m-u tmux 22mattempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the 1m-u 22mflag explic- + itly informs 1mtmux 22mthat UTF-8 is supported. + + If the server is started from a client passed 1m-u 22mor where + UTF-8 is detected, the 1mutf8 22mand 1mstatus-utf8 22moptions are + enabled in the global window and session options respec- + tively. + + 1m-v 22mRequest verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into 4mtmux-client-PID.log24m and 4mtmux-server-PID.log0m + files in the current directory, where 4mPID24m is the PID of the + server or client process. + + 1m-V 22mReport the 1mtmux 22mversion. + + 4mcommand24m [4mflags24m] + This specifies one of a set of commands used to control + 1mtmux22m, as described in the following sections. If no com- + mands are specified, the 1mnew-session 22mcommand is assumed. + +1mKEY BINDINGS0m + 1mtmux 22mmay be controlled from an attached client by using a key combination + of a prefix key, `C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the 1mtmux 22mclient. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the 1mtmux 22mcommand prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from 1mtmux22m, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the 1mbind-key 22mand 1munbind-key 22mcommands. + +1mCOMMANDS0m + This section contains a list of the commands supported by 1mtmux22m. Most + commands accept the optional 1m-t 22margument with one of 4mtarget-client24m, + 4mtarget-session24m 4mtarget-window24m, or 4mtarget-pane24m. These specify the client, + session, window or pane which a command should affect. 4mtarget-client24m is + the name of the pty(4) file to which the client is connected, for example + either of 4m/dev/ttyp124m or 4mttyp124m for the client attached to 4m/dev/ttyp124m. If + no client is specified, the current client is chosen, if possible, or an + error is reported. Clients may be listed with the 1mlist-clients 22mcommand. + + 4mtarget-session24m is the session id prefixed with a $, the name of a session + (as listed by the 1mlist-sessions 22mcommand), or the name of a client with + the same syntax as 4mtarget-client24m, in which case the session attached to + the client is used. When looking for the session name, 1mtmux 22minitially + searches for an exact match; if none is found, the session names are + checked for any for which 4mtarget-session24m is a prefix or for which it + matches as an 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 ses- + sion is available, the most recently used is chosen. + + 4mtarget-window24m specifies a window in the form 4msession24m:4mwindow24m. 4msession0m + follows the same rules as for 4mtarget-session24m, and 4mwindow24m 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 + fnmatch(3) pattern or the start of a window name, such as myses- + sion:mywin* or mysession:mywin. An empty window name specifies the next + unused index if appropriate (for example the 1mnew-window 22mand 1mlink-window0m + commands) otherwise the current window in 4msession24m is chosen. The special + character `!' uses the last (previously current) window, `^' selects the + highest numbered window, `$' selects the lowest numbered window, and `+' + and `-' select the next window or the previous window by number. When + the argument does not contain a colon, 1mtmux 22mfirst attempts to parse it as + window; if that fails, an attempt is made to match a session. + + 4mtarget-pane24m takes a similar form to 4mtarget-window24m but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + 1mtmux 22mfirst attempts to use the argument as a pane index; if that fails, + it is looked up as for 4mtarget-window24m. A `+' or `-' indicate the next or + previous pane index, respectively. One of the strings 4mtop24m, 4mbottom24m, 4mleft24m, + 4mright24m, 4mtop-left24m, 4mtop-right24m, 4mbottom-left24m or 4mbottom-right24m may be used + instead of a pane index. + + The special characters `+' and `-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + 1mtmux 22malso gives each pane created in a server an identifier consisting of + a `%' and a number, starting from zero. A pane's identifier is unique + for the life of the 1mtmux 22mserver and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + 4mshell-command24m arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + 4mcommand24m [4marguments24m] refers to a 1mtmux 22mcommand, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 4mcommand0m + 4msequence24m. 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 + 1mbind-key22m). + + Example 1mtmux 22mcommands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +1mCLIENTS AND SESSIONS0m + The 1mtmux 22mserver manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the 1mnew-session 22mcommand, or later with the 1mattach-session 22mcom- + mand. Each session has one or more windows 4mlinked24m 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 4mWINDOWS24m 4mAND24m 4mPANES24m sec- + tion. + + The following commands are available to manage clients and sessions: + + 1mattach-session 22m[1m-dr22m] [1m-c 4m22mworking-directory24m] [1m-t 4m22mtarget-session24m] + (alias: 1mattach22m) + If run from outside 1mtmux22m, create a new client in the current ter- + minal and attach it to 4mtarget-session24m. If used from inside, + switch the current client. If 1m-d 22mis specified, any other clients + attached to the session are detached. 1m-r 22msignifies the client is + read-only (only keys bound to the 1mdetach-client 22mor 1mswitch-client0m + commands have any effect) + + If no server is started, 1mattach-session 22mwill attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The 4mtarget-session24m rules for 1mattach-session 22mare slightly + adjusted: if 1mtmux 22mneeds to select the most recently used session, + it will prefer the most recently used 4munattached24m session. + + 1m-c 22mwill set the session working directory (used for new windows) + to 4mworking-directory24m. + + 1mdetach-client 22m[1m-P22m] [1m-a22m] [1m-s 4m22mtarget-session24m] [1m-t 4m22mtarget-client24m] + (alias: 1mdetach22m) + Detach the current client if bound to a key, the client specified + with 1m-t22m, or all clients currently attached to the session speci- + fied by 1m-s22m. The 1m-a 22moption kills all but the client given with + 1m-t22m. If 1m-P 22mis given, send SIGHUP to the parent process of the + client, typically causing it to exit. + + 1mhas-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mhas22m) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + 1mkill-server0m + Kill the 1mtmux 22mserver and clients and destroy all sessions. + + 1mkill-session 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. If + 1m-a 22mis given, all sessions but the specified one is killed. + + 1mlist-clients 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsc22m) + List all clients attached to the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. If 4mtarget-session24m is speci- + fied, list only clients connected to that session. + + 1mlist-commands0m + (alias: 1mlscm22m) + List the syntax of all commands supported by 1mtmux22m. + + 1mlist-sessions 22m[1m-F 4m22mformat24m] + (alias: 1mls22m) + List all sessions managed by the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mlock-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1mlockc22m) + Lock 4mtarget-client24m, see the 1mlock-server 22mcommand. + + 1mlock-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlocks22m) + Lock all clients attached to 4mtarget-session24m. + + 1mnew-session 22m[1m-AdDP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-s0m + 4msession-name24m] [1m-t 4m22mtarget-session24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] + [4mshell-command24m] + (alias: 1mnew22m) + Create a new session with name 4msession-name24m. + + The new session is attached to the current terminal unless 1m-d 22mis + given. 4mwindow-name24m and 4mshell-command24m are the name of and shell + command to execute in the initial window. If 1m-d 22mis used, 1m-x 22mand + 1m-y 22mspecify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(4) special characters are + saved and used for new windows in the new session. + + The 1m-A 22mflag makes 1mnew-session 22mbehave like 1mattach-session 22mif + 4msession-name24m already exists; in the case, 1m-D 22mbehaves like 1m-d 22mto + 1mattach-session22m. + + If 1m-t 22mis given, the new session is 4mgrouped24m with 4mtarget-session24m. + This means they share the same set of windows - all windows from + 4mtarget-session24m 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 1m-n 22mor 4mshell-command24m are invalid if 1m-t 22mis used. + + The 1m-P 22moption prints information about the new session after it + has been created. By default, it uses the format + `#{session_name}:' but a different format may be specified with + 1m-F22m. + + 1mrefresh-client 22m[1m-S22m] [1m-t 4m22mtarget-client24m] + (alias: 1mrefresh22m) + Refresh the current client if bound to a key, or a single client + if one is given with 1m-t22m. If 1m-S 22mis specified, only update the + client's status bar. + + 1mrename-session 22m[1m-t 4m22mtarget-session24m] 4mnew-name0m + (alias: 1mrename22m) + Rename the session to 4mnew-name24m. + + 1mshow-messages 22m[1m-IJT22m] [1m-t 4m22mtarget-client24m] + (alias: 1mshowmsgs22m) + Show client messages or server information. Any messages dis- + played on the status line are saved in a per-client message log, + up to a maximum of the limit set by the 4mmessage-limit24m session + option for the session attached to that client. With 1m-t22m, display + the log for 4mtarget-client24m. 1m-I22m, 1m-J 22mand 1m-T 22mshow debugging informa- + tion about the running server, jobs and terminals. + + 1msource-file 4m22mpath0m + (alias: 1msource22m) + Execute commands from 4mpath24m. + + 1mstart-server0m + (alias: 1mstart22m) + Start the 1mtmux 22mserver, if not already running, without creating + any sessions. + + 1msuspend-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1msuspendc22m) + Suspend a client by sending SIGTSTP (tty stop). + + 1mswitch-client 22m[1m-lnpr22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-session24m] + (alias: 1mswitchc22m) + Switch the current session for client 4mtarget-client24m to + 4mtarget-session24m. If 1m-l22m, 1m-n 22mor 1m-p 22mis used, the client is moved to + the last, next or previous session respectively. 1m-r 22mtoggles + whether a client is read-only (see the 1mattach-session 22mcommand). + +1mWINDOWS AND PANES0m + A 1mtmux 22mwindow 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 + 4mpaste24m 4mbuffer24m for later insertion into another window. This mode is + entered with the 1mcopy-mode 22mcommand, bound to `[' by default. It is also + entered when a command that produces output, such as 1mlist-keys22m, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the 1mmode-keys 22moption). The following keys are supported as appropriate + for the mode: + + 1mFunction vi emacs0m + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump to forward t + Jump backward F F + Jump to backward T + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Other end of selection o + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose characters C-t + + The next and previous word keys use space and the `-', `_' and `@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 4mword-separators24m 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. + + The jump commands enable quick movement within a line. For instance, + typing `f' followed by `/' will move the cursor to the next `/' character + on the current line. A `;' will then jump to the next occurrence. + + 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 `M-1 0 M-f' in emacs mode, and + `10w' in vi. + + When copying the selection, the repeat count indicates the buffer index + to replace, if used. + + Mode key bindings are defined in a set of named tables: 4mvi-edit24m and + 4memacs-edit24m for keys used when line editing at the command prompt; + 4mvi-choice24m and 4memacs-choice24m for keys used when choosing from lists (such + as produced by the 1mchoose-window 22mcommand); and 4mvi-copy24m and 4memacs-copy0m + used in copy mode. The tables may be viewed with the 1mlist-keys 22mcommand + and keys modified or removed with 1mbind-key 22mand 1munbind-key22m. One command + accepts an argument, 1mcopy-pipe22m, which copies the selection and pipes it + to a command. For example the following will bind `C-q' to copy the + selection into 4m/tmp24m as well as the paste buffer: + + bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the 1mcopy-mode 22mcommand is: + + 1mcopy-mode 22m[1m-u22m] [1m-t 4m22mtarget-pane24m] + Enter copy mode. The 1m-u 22moption scrolls one page up. + + Each window displayed by 1mtmux 22mmay be split into one or more 4mpanes24m; each + pane takes up a certain area of the display and is a separate terminal. + A window may be split into panes using the 1msplit-window 22mcommand. Windows + may be split horizontally (with the 1m-h 22mflag) or vertically. Panes may be + resized with the 1mresize-pane 22mcommand (bound to `C-up', `C-down' `C-left' + and `C-right' by default), the current pane may be changed with the + 1mselect-pane 22mcommand and the 1mrotate-window 22mand 1mswap-pane 22mcommands may be + used to swap panes without changing their position. Panes are numbered + beginning from zero in the order they are created. + + A number of preset 4mlayouts24m are available. These may be selected with the + 1mselect-layout 22mcommand or cycled with 1mnext-layout 22m(bound to `Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + 1meven-horizontal0m + Panes are spread out evenly from left to right across the window. + + 1meven-vertical0m + Panes are spread evenly from top to bottom. + + 1mmain-horizontal0m + 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 4mmain-pane-height24m window option to + specify the height of the top pane. + + 1mmain-vertical0m + Similar to 1mmain-horizontal 22mbut the large pane is placed on the + left and the others spread from top to bottom along the right. + See the 4mmain-pane-width24m window option. + + 1mtiled 22mPanes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, 1mselect-layout 22mmay be used to apply a previously used layout + - the 1mlist-windows 22mcommand displays the layout of each window in a form + suitable for use with 1mselect-layout22m. For example: + + $ 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} + + 1mtmux 22mautomatically 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. + + Commands related to windows and panes are as follows: + + 1mbreak-pane 22m[1m-dP22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mbreakp22m) + Break 4mtarget-pane24m off from its containing window to make it the + only pane in a new window. If 1m-d 22mis given, the new window does + not become the current window. The 1m-P 22moption prints information + about the new window after it has been created. By default, it + uses the format `#{session_name}:#{window_index}' but a different + format may be specified with 1m-F22m. + + 1mcapture-pane 22m[1m-aepPq22m] [1m-b 4m22mbuffer-index24m] [1m-E 4m22mend-line24m] [1m-S 4m22mstart-line24m] [1m-t0m + 4mtarget-pane24m] + (alias: 1mcapturep22m) + Capture the contents of a pane. If 1m-p 22mis given, the output goes + to stdout, otherwise to the buffer specified with 1m-b 22mor a new + buffer if omitted. If 1m-a 22mis given, the alternate screen is used, + and the history is not accessible. If no alternate screen + exists, an error will be returned unless 1m-q 22mis given. If 1m-e 22mis + given, the output includes escape sequences for text and back- + ground attributes. 1m-C 22malso escapes non-printable characters as + octal \xxx. 1m-J 22mjoins wrapped lines and preserves trailing spaces + at each line's end. 1m-P 22mcaptures only any output that the pane + has received that is the beginning of an as-yet incomplete escape + sequence. + + 1m-S 22mand 1m-E 22mspecify 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 con- + tents of the pane. + + 1mchoose-client 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + `%%' is replaced by the client pty(4) path in 4mtemplate24m and the + result executed as a command. If 4mtemplate24m is not given, "detach- + client -t '%%'" is used. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. This command works only if at least one client + is attached. + + 1mchoose-list 22m[1m-l 4m22mitems24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into list choice mode, allowing 4mitems24m to be + selected. 4mitems24m 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, `%%' is replaced by the chosen item in + the 4mtemplate24m and the result is executed as a command. If + 4mtemplate24m is not given, "run-shell '%%'" is used. 4mitems24m also + accepts format specifiers. For the meaning of this see the + 4mFORMATS24m section. This command works only if at least one client + is attached. + + 1mchoose-session 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, `%%' is + replaced by the session name in 4mtemplate24m and the result executed + as a command. If 4mtemplate24m is not given, "switch-client -t '%%'" + is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. This command works only if at least one client is + attached. + + 1mchoose-tree 22m[1m-suw22m] [1m-b 4m22msession-template24m] [1m-c 4m22mwindow-template24m] [1m-S 4m22mformat24m] + [1m-W 4m22mformat24m] [1m-t 4m22mtarget-window24m] + Put a window into tree choice mode, where either sessions or win- + dows may be selected interactively from a list. By default, win- + dows belonging to a session are indented to show their relation- + ship to a session. + + Note that the 1mchoose-window 22mand 1mchoose-session 22mcommands are wrap- + pers around 1mchoose-tree22m. + + If 1m-s 22mis given, will show sessions. If 1m-w 22mis given, will show + windows. + + By default, the tree is collapsed and sessions must be expanded + to windows with the right arrow key. The 1m-u 22moption will start + with all sessions expanded instead. + + If 1m-b 22mis given, will override the default session command. Note + that `%%' can be used and will be replaced with the session name. + The default option if not specified is "switch-client -t '%%'". + If 1m-c 22mis given, will override the default window command. Like + 1m-b22m, `%%' 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. + + If 1m-S 22mis given will display the specified format instead of the + default session format. If 1m-W 22mis given will display the speci- + fied format instead of the default window format. For the mean- + ing of the 1m-s 22mand 1m-w 22moptions, see the 4mFORMATS24m section. + + This command works only if at least one client is attached. + + 1mchoose-window 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, `%%' + is replaced by the session name and window index in 4mtemplate24m and + the result executed as a command. If 4mtemplate24m is not given, + "select-window -t '%%'" is used. For the meaning of the 1m-F 22mflag, + see the 4mFORMATS24m section. This command works only if at least one + client is attached. + + 1mdisplay-panes 22m[1m-t 4m22mtarget-client24m] + (alias: 1mdisplayp)0m + Display a visible indicator of each pane shown by 4mtarget-client24m. + See the 1mdisplay-panes-time22m, 1mdisplay-panes-colour22m, and + 1mdisplay-panes-active-colour 22msession options. While the indicator + is on screen, a pane may be selected with the `0' to `9' keys. + + 1mfind-window 22m[1m-CNT22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] 4mmatch-string0m + (alias: 1mfindw22m) + Search for the fnmatch(3) pattern 4mmatch-string24m in window names, + titles, and visible content (but not history). The flags control + matching behavior: 1m-C 22mmatches only visible window contents, 1m-N0m + matches only the window name and 1m-T 22mmatches only the window + title. The default is 1m-CNT22m. If only one window is matched, + it'll be automatically selected, otherwise a choice list is + shown. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + This command works only if at least one client is attached. + + 1mjoin-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mjoinp22m) + Like 1msplit-window22m, but instead of splitting 4mdst-pane24m and creating + a new pane, split it and move 4msrc-pane24m into the space. This can + be used to reverse 1mbreak-pane22m. The 1m-b 22moption causes 4msrc-pane24m to + be joined to left of or above 4mdst-pane24m. + + 1mkill-pane 22m[1m-a22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mkillp22m) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The 1m-a 22moption kills all but the + pane given with 1m-t22m. + + 1mkill-window 22m[1m-a22m] [1m-t 4m22mtarget-window24m] + (alias: 1mkillw22m) + Kill the current window or the window at 4mtarget-window24m, removing + it from any sessions to which it is linked. The 1m-a 22moption kills + all but the window given with 1m-t22m. + + 1mlast-pane 22m[1m-t 4m22mtarget-window24m] + (alias: 1mlastp22m) + Select the last (previously selected) pane. + + 1mlast-window 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlast22m) + Select the last (previously selected) window. If no + 4mtarget-session24m is specified, select the last window of the cur- + rent session. + + 1mlink-window 22m[1m-dk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mlinkw22m) + Link the window at 4msrc-window24m to the specified 4mdst-window24m. If + 4mdst-window24m is specified and no such window exists, the 4msrc-window0m + is linked there. If 1m-k 22mis given and 4mdst-window24m exists, it is + killed, otherwise an error is generated. If 1m-d 22mis given, the + newly linked window is not selected. + + 1mlist-panes 22m[1m-as22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget24m] + (alias: 1mlsp22m) + If 1m-a 22mis given, 4mtarget24m is ignored and all panes on the server are + listed. If 1m-s 22mis given, 4mtarget24m is a session (or the current ses- + sion). If neither is given, 4mtarget24m is a window (or the current + window). For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. + + 1mlist-windows 22m[1m-a22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsw22m) + If 1m-a 22mis given, list all windows on the server. Otherwise, list + windows in the current session or in 4mtarget-session24m. For the + meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mmove-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mmovep22m) + Like 1mjoin-pane22m, but 4msrc-pane24m and 4mdst-pane24m may belong to the same + window. + + 1mmove-window 22m[1m-rdk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mmovew22m) + This is similar to 1mlink-window22m, except the window at 4msrc-window0m + is moved to 4mdst-window24m. With 1m-r22m, all windows in the session are + renumbered in sequential order, respecting the 1mbase-index 22moption. + + 1mnew-window 22m[1m-adkP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-t0m + 4mtarget-window24m] [4mshell-command24m] + (alias: 1mneww22m) + Create a new window. With 1m-a22m, the new window is inserted at the + next index up from the specified 4mtarget-window24m, moving windows up + if necessary, otherwise 4mtarget-window24m is the new window location. + + If 1m-d 22mis given, the session does not make the new window the cur- + rent window. 4mtarget-window24m represents the window to be created; + if the target already exists an error is shown, unless the 1m-k0m + flag is used, in which case it is destroyed. 4mshell-command24m is + the command to execute. If 4mshell-command24m is not specified, the + value of the 1mdefault-command 22moption is used. 1m-c 22mspecifies the + working directory in which the new window is created. + + When the shell command completes, the window closes. See the + 1mremain-on-exit 22moption to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running 4minside24m 1mtmux22m. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The 1m-P 22moption prints information about the new window after it + has been created. By default, it uses the format + `#{session_name}:#{window_index}' but a different format may be + specified with 1m-F22m. + + 1mnext-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mnextl22m) + Move a window to the next layout and rearrange the panes to fit. + + 1mnext-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mnext22m) + Move to the next window in the session. If 1m-a 22mis used, move to + the next window with an alert. + + 1mpipe-pane 22m[1m-o22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mpipep22m) + Pipe any output sent by the program in 4mtarget-pane24m to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before 4mshell-command24m is executed. The + 4mshell-command24m string may contain the special character sequences + supported by the 1mstatus-left 22moption. If no 4mshell-command24m is + given, the current pipe (if any) is closed. + + The 1m-o 22moption only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + 1mprevious-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mprevl22m) + Move to the previous layout in the session. + + 1mprevious-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mprev22m) + Move to the previous window in the session. With 1m-a22m, move to the + previous window with an alert. + + 1mrename-window 22m[1m-t 4m22mtarget-window24m] 4mnew-name0m + (alias: 1mrenamew22m) + Rename the current window, or the window at 4mtarget-window24m if + specified, to 4mnew-name24m. + + 1mresize-pane 22m[1m-DLRUZ22m] [1m-t 4m22mtarget-pane24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] [4madjustment24m] + (alias: 1mresizep22m) + Resize a pane, up, down, left or right by 4madjustment24m with 1m-U22m, 1m-D22m, + 1m-L 22mor 1m-R22m, or to an absolute size with 1m-x 22mor 1m-y22m. The 4madjustment0m + is given in lines or cells (the default is 1). + + With 1m-Z22m, the active pane is toggled between zoomed (occupying the + whole of the window) and unzoomed (its normal position in the + layout). + + 1mrespawn-pane 22m[1m-k22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mrespawnp22m) + Reactivate a pane in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless 1m-k 22mis given, in which case any + existing command is killed. + + 1mrespawn-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] [4mshell-command24m] + (alias: 1mrespawnw22m) + Reactivate a window in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the window was created is executed. The + window must be already inactive, unless 1m-k 22mis given, in which + case any existing command is killed. + + 1mrotate-window 22m[1m-DU22m] [1m-t 4m22mtarget-window24m] + (alias: 1mrotatew22m) + Rotate the positions of the panes within a window, either upward + (numerically lower) with 1m-U 22mor downward (numerically higher). + + 1mselect-layout 22m[1m-np22m] [1m-t 4m22mtarget-window24m] [4mlayout-name24m] + (alias: 1mselectl22m) + Choose a specific layout for a window. If 4mlayout-name24m is not + given, the last preset layout used (if any) is reapplied. 1m-n 22mand + 1m-p 22mare equivalent to the 1mnext-layout 22mand 1mprevious-layout 22mcom- + mands. + + 1mselect-pane 22m[1m-lDLRU22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mselectp22m) + Make pane 4mtarget-pane24m the active pane in window 4mtarget-window24m. + If one of 1m-D22m, 1m-L22m, 1m-R22m, or 1m-U 22mis used, respectively the pane below, + to the left, to the right, or above the target pane is used. 1m-l0m + is the same as using the 1mlast-pane 22mcommand. + + 1mselect-window 22m[1m-lnpT22m] [1m-t 4m22mtarget-window24m] + (alias: 1mselectw22m) + Select the window at 4mtarget-window24m. 1m-l22m, 1m-n 22mand 1m-p 22mare equivalent + to the 1mlast-window22m, 1mnext-window 22mand 1mprevious-window 22mcommands. If + 1m-T 22mis given and the selected window is already the current win- + dow, the command behaves like 1mlast-window22m. + + 1msplit-window 22m[1m-dhvP22m] [1m-c 4m22mstart-directory24m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-t0m + 4mtarget-pane24m] [4mshell-command24m] [1m-F 4m22mformat24m] + (alias: 1msplitw22m) + Create a new pane by splitting 4mtarget-pane24m: 1m-h 22mdoes a horizontal + split and 1m-v 22ma vertical split; if neither is specified, 1m-v 22mis + assumed. The 1m-l 22mand 1m-p 22moptions 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 1mnew-window 22mcommand. + + 1mswap-pane 22m[1m-dDU22m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mswapp22m) + Swap two panes. If 1m-U 22mis used and no source pane is specified + with 1m-s22m, 4mdst-pane24m is swapped with the previous pane (before it + numerically); 1m-D 22mswaps with the next pane (after it numerically). + 1m-d 22minstructs 1mtmux 22mnot to change the active pane. + + 1mswap-window 22m[1m-d22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mswapw22m) + This is similar to 1mlink-window22m, except the source and destination + windows are swapped. It is an error if no window exists at + 4msrc-window24m. + + 1munlink-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] + (alias: 1munlinkw22m) + Unlink 4mtarget-window24m. Unless 1m-k 22mis given, a window may be + unlinked only if it is linked to multiple sessions - windows may + not be linked to no sessions; if 1m-k 22mis specified and the window + is linked to only one session, it is unlinked and destroyed. + +1mKEY BINDINGS0m + 1mtmux 22mallows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example `A' to + `Z'). Ctrl keys may be prefixed with `C-' or `^', and Alt (meta) with + `M-'. In addition, the following special key names are accepted: 4mUp24m, + 4mDown24m, 4mLeft24m, 4mRight24m, 4mBSpace24m, 4mBTab24m, 4mDC24m (Delete), 4mEnd24m, 4mEnter24m, 4mEscape24m, 4mF124m to + 4mF2024m, 4mHome24m, 4mIC24m (Insert), 4mNPage/PageDown/PgDn24m, 4mPPage/PageUp/PgUp24m, 4mSpace24m, + and 4mTab24m. Note that to bind the `"' or `'' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + 1mbind-key 22m[1m-cnr22m] [1m-t 4m22mkey-table24m] 4mkey24m 4mcommand24m [4marguments24m] + (alias: 1mbind22m) + Bind key 4mkey24m to 4mcommand24m. By default (without 1m-t22m) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if 1m-n 22mis specified, it is not necessary to + use the prefix key, 4mcommand24m is bound to 4mkey24m alone. The 1m-r 22mflag + indicates this key may repeat, see the 1mrepeat-time 22moption. + + If 1m-t 22mis present, 4mkey24m is bound in 4mkey-table24m: the binding for com- + mand mode with 1m-c 22mor for normal mode without. To view the + default bindings and possible commands, see the 1mlist-keys 22mcom- + mand. + + 1mlist-keys 22m[1m-t 4m22mkey-table24m] + (alias: 1mlsk22m) + List all key bindings. Without 1m-t 22mthe primary key bindings - + those executed when preceded by the prefix key - are printed. + + With 1m-t22m, the key bindings in 4mkey-table24m are listed; this may be + one of: 4mvi-edit24m, 4memacs-edit24m, 4mvi-choice24m, 4memacs-choice24m, 4mvi-copy24m or + 4memacs-copy24m. + + 1msend-keys 22m[1m-lR22m] [1m-t 4m22mtarget-pane24m] 4mkey24m 4m...0m + (alias: 1msend22m) + Send a key or keys to a window. Each argument 4mkey24m is the name of + the key (such as `C-a' or `npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. The + 1m-l 22mflag disables key name lookup and sends the keys literally. + All arguments are sent sequentially from first to last. The 1m-R0m + flag causes the terminal state to be reset. + + 1msend-prefix 22m[1m-222m] [1m-t 4m22mtarget-pane24m] + Send the prefix key, or with 1m-2 22mthe secondary prefix key, to a + window as if it was pressed. + + 1munbind-key 22m[1m-acn22m] [1m-t 4m22mkey-table24m] 4mkey0m + (alias: 1munbind22m) + Unbind the command bound to 4mkey24m. Without 1m-t 22mthe primary key + bindings are modified; in this case, if 1m-n 22mis specified, the com- + mand bound to 4mkey24m without a prefix (if any) is removed. If 1m-a 22mis + present, all key bindings are removed. + + If 1m-t 22mis present, 4mkey24m in 4mkey-table24m is unbound: the binding for + command mode with 1m-c 22mor for normal mode without. + +1mOPTIONS0m + The appearance and behaviour of 1mtmux 22mmay be modified by changing the + value of various options. There are three types of option: 4mserver0m + 4moptions24m, 4msession24m 4moptions24m and 4mwindow24m 4moptions24m. + + The 1mtmux 22mserver has a set of global options which do not apply to any + particular window or session. These are altered with the 1mset-option -s0m + command, or displayed with the 1mshow-options -s 22mcommand. + + 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 1mset-option0m + command and may be listed with the 1mshow-options 22mcommand. The available + server and session options are listed under the 1mset-option 22mcommand. + + 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 inher- + ited. Window options are altered with the 1mset-window-option 22mcommand and + can be listed with the 1mshow-window-options 22mcommand. All window options + are documented with the 1mset-window-option 22mcommand. + + 1mtmux 22malso supports user options which are prefixed with a `@'. User + options may have any name, so long as they are prefixed with `@', and be + set to any string. For example + + $ tmux setw -q @foo "abc123" + $ tmux showw -v @foo + abc123 + + Commands which set options are as follows: + + 1mset-option 22m[1m-agoqsuw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1mset22m) + Set a window option with 1m-w 22m(equivalent to the 1mset-window-option0m + command), a server option with 1m-s22m, otherwise a session option. + + If 1m-g 22mis specified, the global session or window option is set. + The 1m-u 22mflag unsets an option, so a session inherits the option + from the global options. It is not possible to unset a global + option. + + The 1m-o 22mflag prevents setting an option that is already set. + + The 1m-q 22mflag suppresses the informational message (as if the 1mquiet0m + server option was set). + + With 1m-a22m, and if the option expects a string or a style, 4mvalue24m is + appended to the existing setting. For example: + + set -g status-left "foo" + set -ag status-left "bar" + + Will result in `foobar'. And: + + set -g status-style "bg=red" + set -ag status-style "fg=blue" + + Will result in a red background 4mand24m blue foreground. Without 1m-a22m, + the result would be the default background and a blue foreground. + + Available window options are listed under 1mset-window-option22m. + + 4mvalue24m depends on the option and may be a number, a string, or a + flag (on, off, or omitted to toggle). + + Available server options are: + + 1mbuffer-limit 4m22mnumber0m + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + 1mescape-time 4m22mtime0m + Set the time in milliseconds for which 1mtmux 22mwaits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + 1mexit-unattached 22m[1mon 22m| 1moff22m] + If enabled, the server will exit when there are no + attached clients. + + 1mfocus-events 22m[1mon 22m| 1moff22m] + When enabled, focus events are requested from the termi- + nal if supported and passed through to applications run- + ning in 1mtmux22m. Attached clients should be detached and + attached again after changing this option. + + 1mquiet 22m[1mon 22m| 1moff22m] + Enable or disable the display of various informational + messages (see also the 1m-q 22mcommand line flag). + + 1mset-clipboard 22m[1mon 22m| 1moff22m] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an 4mMs24m entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + Available session options are: + + 1massume-paste-time 4m22mmilliseconds0m + If keys are entered faster than one in 4mmilliseconds24m, they + are assumed to have been pasted rather than typed and + 1mtmux 22mkey bindings are not processed. The default is one + millisecond and zero disables. + + 1mbase-index 4m22mindex0m + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + 1mbell-action 22m[1many 22m| 1mnone 22m| 1mcurrent22m] + Set action on window bell. 1many 22mmeans a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, 1mnone 22mmeans all bells are ignored and + 1mcurrent 22mmeans only bells in windows other than the cur- + rent window are ignored. + + 1mbell-on-alert 22m[1mon 22m| 1moff22m] + If on, ring the terminal bell when an alert occurs. + + 1mdefault-command 4m22mshell-command0m + Set the command used for new windows (if not specified + when the window is created) to 4mshell-command24m, which may + be any sh(1) command. The default is an empty string, + which instructs 1mtmux 22mto create a login shell using the + value of the 1mdefault-shell 22moption. + + 1mdefault-shell 4m22mpath0m + Specify the default shell. This is used as the login + shell for new windows when the 1mdefault-command 22moption is + set to empty, and must be the full path of the exe- + cutable. When started 1mtmux 22mtries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or 4m/bin/sh24m. + This option should be configured when 1mtmux 22mis used as a + login shell. + + 1mdefault-terminal 4m22mterminal0m + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For 1mtmux 22mto work correctly, this 4mmust24m be set to + `screen' or a derivative of it. + + 1mdestroy-unattached 22m[1mon 22m| 1moff22m] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + 1mdetach-on-destroy 22m[1mon 22m| 1moff22m] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + 1mdisplay-panes-active-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicator for the active pane. + + 1mdisplay-panes-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicators for inactive panes. + + 1mdisplay-panes-time 4m22mtime0m + Set the time in milliseconds for which the indicators + shown by the 1mdisplay-panes 22mcommand appear. + + 1mdisplay-time 4m22mtime0m + Set the amount of time for which status line messages and + other on-screen indicators are displayed. 4mtime24m is in + milliseconds. + + 1mhistory-limit 4m22mlines0m + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + 1mlock-after-time 4m22mnumber0m + Lock the session (like the 1mlock-session 22mcommand) after + 4mnumber24m seconds of inactivity, or the entire server (all + sessions) if the 1mlock-server 22moption is set. The default + is not to lock (set to 0). + + 1mlock-command 4m22mshell-command0m + Command to run when locking each client. The default is + to run lock(1) with 1m-np22m. + + 1mlock-server 22m[1mon 22m| 1moff22m] + If this option is 1mon 22m(the default), instead of each ses- + sion locking individually as each has been idle for + 1mlock-after-time22m, the entire server will lock after 4mall0m + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + 1mmessage-command-style 4m22mstyle0m + Set status line message command style, where 4mstyle24m is a + comma-separated list of characteristics to be specified. + + These may be `bg=colour' to set the background colour, + `fg=colour' to set the foreground colour, and a list of + attributes as specified below. + + The colour is one of: 1mblack22m, 1mred22m, 1mgreen22m, 1myellow22m, 1mblue22m, + 1mmagenta22m, 1mcyan22m, 1mwhite22m, aixterm bright variants (if sup- + ported: 1mbrightred22m, 1mbrightgreen22m, and so on), 1mcolour0 22mto + 1mcolour255 22mfrom the 256-colour set, 1mdefault22m, or a hexadec- + imal RGB string such as `#ffffff', which chooses the + closest match from the default 256-colour set. + + The attributes is either 1mnone 22mor a comma-delimited list + of one or more of: 1mbright 22m(or 1mbold22m), 1mdim22m, 1munderscore22m, + 1mblink22m, 1mreverse22m, 1mhidden22m, or 1mitalics22m, to turn an attribute + on, or an attribute prefixed with `no' to turn one off. + + Examples are: + + fg=yellow,bold,underscore,blink + bg=black,fg=default,noreverse + + With the 1m-a 22mflag to the 1mset-option 22mcommand the new style + is added otherwise the existing style is replaced. + + 1mmessage-limit 4m22mnumber0m + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + 1mmessage-style 4m22mstyle0m + Set status line message style. For how to specify 4mstyle24m, + see the 1mmessage-command-style 22moption. + + 1mmouse-resize-pane 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures the mouse and allows panes to be + resized by dragging on their borders. + + 1mmouse-select-pane 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures 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. + + 1mmouse-select-window 22m[1mon 22m| 1moff22m] + If on, clicking the mouse on a window name in the status + line will select that window. + + 1mmouse-utf8 22m[1mon 22m| 1moff22m] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + 1mpane-active-border-style 4m22mstyle0m + Set the pane border style for the currently active pane. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. Attributes are ignored. + + 1mpane-border-style 4m22mstyle0m + Set the pane border style for paneas aside from the + active pane. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. Attributes are ignored. + + 1mprefix 4m22mkey0m + Set the key accepted as a prefix key. + + 1mprefix2 4m22mkey0m + Set a secondary key accepted as a prefix key. + + 1mrenumber-windows 22m[1mon 22m| 1moff22m] + If on, when a window is closed in a session, automati- + cally renumber the other windows in numerical order. + This respects the 1mbase-index 22moption if it has been set. + If off, do not renumber the windows. + + 1mrepeat-time 4m22mtime0m + Allow multiple commands to be entered without pressing + the prefix-key again in the specified 4mtime24m milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the 1m-r 22mflag to 1mbind-key22m. Repeat + is enabled for the default keys bound to the 1mresize-pane0m + command. + + 1mset-remain-on-exit 22m[1mon 22m| 1moff22m] + Set the 1mremain-on-exit 22mwindow 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 + 1mrespawn-window 22mcommand to reactivate such a window, or + the 1mkill-window 22mcommand to destroy it. + + 1mset-titles 22m[1mon 22m| 1moff22m] + Attempt to set the client terminal title using the 4mtsl0m + and 4mfsl24m terminfo(5) entries if they exist. 1mtmux 22mautomat- + ically sets these to the \e]2;...\007 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. + + 1mset-titles-string 4m22mstring0m + String used to set the window title if 1mset-titles 22mis on. + Character sequences are replaced as for the 1mstatus-left0m + option. + + 1mstatus 22m[1mon 22m| 1moff22m] + Show or hide the status line. + + 1mstatus-interval 4m22minterval0m + Update the status bar every 4minterval24m seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + 1mstatus-justify 22m[1mleft 22m| 1mcentre 22m| 1mright22m] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + 1mstatus-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string `vi'. + + 1mstatus-left 4m22mstring0m + Display 4mstring24m (by default the session name) to the left + of the status bar. 4mstring24m will be passed through + strftime(3) and formats (see 4mFORMATS24m) will be expanded. + It may also contain any of the following special charac- + ter sequences: + + 1mCharacter pair Replaced with0m + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + ## A literal `#' + + The #(shell-command) form executes `shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the 1mstatus-interval 22moption: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the 1mtmux 22mglobal environ- + ment set (see the 4mENVIRONMENT24m section). + + For details on how the names and titles can be set see + the 4mNAMES24m 4mAND24m 4mTITLES24m section. For a list of allowed + attributes see the 1mmessage-command-style 22moption. + + Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example `#24T'. + + By default, UTF-8 in 4mstring24m is not interpreted, to enable + UTF-8, use the 1mstatus-utf8 22moption. + + 1mstatus-left-length 4m22mlength0m + Set the maximum 4mlength24m of the left component of the sta- + tus bar. The default is 10. + + 1mstatus-left-style 4m22mstyle0m + Set the style of the left part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-position 22m[1mtop 22m| 1mbottom22m] + Set the position of the status line. + + 1mstatus-right 4m22mstring0m + Display 4mstring24m 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 1mstatus-left22m, 4mstring0m + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the 1mstatus-utf80m + option. + + 1mstatus-right-length 4m22mlength0m + Set the maximum 4mlength24m of the right component of the sta- + tus bar. The default is 40. + + 1mstatus-right-style 4m22mstyle0m + Set the style of the right part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-style 4m22mstyle0m + Set status line style. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. + + 1mstatus-utf8 22m[1mon 22m| 1moff22m] + Instruct 1mtmux 22mto treat top-bit-set characters in the + 1mstatus-left 22mand 1mstatus-right 22mstrings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + 1mterminal-overrides 4m22mstring0m + Contains a list of entries which override terminal + descriptions read using terminfo(5). 4mstring24m is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of 4mname=value24m entries. + + For example, to set the `clear' terminfo(5) entry to + `\e[H\e[2J' for all terminal types and the `dch1' entry + to `\e[P' for the `rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the `colors' entry for terminals which support 256 + colours: + + "*256col*:colors=256,xterm*:XT" + + 1mupdate-environment 4m22mvariables0m + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 1m-r 22mwas given to the 1mset-environment0m + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + 1mvisual-activity 22m[1mon 22m| 1moff22m] + If on, display a status line message when activity occurs + in a window for which the 1mmonitor-activity 22mwindow option + is enabled. + + 1mvisual-bell 22m[1mon 22m| 1moff22m] + 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 1mbell-action0m + option. + + 1mvisual-content 22m[1mon 22m| 1moff22m] + Like 1mvisual-activity22m, display a message when content is + present in a window for which the 1mmonitor-content 22mwindow + option is enabled. + + 1mvisual-silence 22m[1mon 22m| 1moff22m] + If 1mmonitor-silence 22mis enabled, prints a message after the + interval has expired on a given window. + + 1mword-separators 4m22mstring0m + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ` -_@'. + + 1mset-window-option 22m[1m-agoqu22m] [1m-t 4m22mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1msetw22m) + Set a window option. The 1m-a22m, 1m-g22m, 1m-o22m, 1m-q 22mand 1m-u 22mflags work simi- + larly to the 1mset-option 22mcommand. + + Supported window options are: + + 1maggressive-resize 22m[1mon 22m| 1moff22m] + Aggressively resize the chosen window. This means that + 1mtmux 22mwill 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 SIGWINCH and poor for interactive programs + such as shells. + + 1mallow-rename 22m[1mon 22m| 1moff22m] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + 1malternate-screen 22m[1mon 22m| 1moff22m] + This option configures whether programs running inside + 1mtmux 22mmay use the terminal alternate screen feature, which + allows the 4msmcup24m and 4mrmcup24m 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. + + 1mautomatic-rename 22m[1mon 22m| 1moff22m] + Control automatic window renaming. When this setting is + enabled, 1mtmux 22mwill rename the window automatically using + the format specified by 1mautomatic-rename-format22m. This + flag is automatically disabled for an individual window + when a name is specified at creation with 1mnew-window 22mor + 1mnew-session22m, or later with 1mrename-window22m, or with a ter- + minal escape sequence. It may be switched off globally + with: + + set-window-option -g automatic-rename off + + 1mautomatic-rename-format 4m22mformat0m + The format (see 4mFORMATS24m) used when the 1mautomatic-rename0m + option is enabled. + + 1mc0-change-interval 4m22minterval0m + 1mc0-change-trigger 4m22mtrigger0m + These two options configure a simple form of rate limit- + ing for a pane. If 1mtmux 22msees more than 4mtrigger24m 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 4minterval24m milliseconds. This + helps to prevent fast output (such as yes(1)) overwhelm- + ing the terminal. The default is a trigger of 250 and an + interval of 100. A trigger of zero disables the rate + limiting. + + 1mclock-mode-colour 4m22mcolour0m + Set clock colour. + + 1mclock-mode-style 22m[1m12 22m| 1m2422m] + Set clock hour format. + + 1mforce-height 4m22mheight0m + 1mforce-width 4m22mwidth0m + Prevent 1mtmux 22mfrom resizing a window to greater than 4mwidth0m + or 4mheight24m. A value of zero restores the default unlim- + ited setting. + + 1mmain-pane-height 4m22mheight0m + 1mmain-pane-width 4m22mwidth0m + Set the width or height of the main (left or top) pane in + the 1mmain-horizontal 22mor 1mmain-vertical 22mlayouts. + + 1mmode-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in copy and choice + modes. As with the 1mstatus-keys 22moption, the default is + emacs, unless VISUAL or EDITOR contains `vi'. + + 1mmode-mouse 22m[1mon 22m| 1moff 22m| 1mcopy-mode22m] + 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 4mcopy-mode24m, + the mouse behaves as set to on, but cannot be used to + enter copy mode. + + 1mmode-style 4m22mstyle0m + Set window modes style. For how to specify 4mstyle24m, see + the 1mmessage-command-style 22moption. + + 1mmonitor-activity 22m[1mon 22m| 1moff22m] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + 1mmonitor-content 4m22mmatch-string0m + Monitor content in the window. When fnmatch(3) pattern + 4mmatch-string24m appears in the window, it is highlighted in + the status line. + + 1mmonitor-silence 22m[1minterval22m] + Monitor for silence (no activity) in the window within + 1minterval 22mseconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + 1mother-pane-height 4m22mheight0m + Set the height of the other panes (not the main pane) in + the 1mmain-horizontal 22mlayout. If this option is set to 0 + (the default), it will have no effect. If both the + 1mmain-pane-height 22mand 1mother-pane-height 22moptions are set, + the main pane will grow taller to make the other panes + the specified height, but will never shrink to do so. + + 1mother-pane-width 4m22mwidth0m + Like 1mother-pane-height22m, but set the width of other panes + in the 1mmain-vertical 22mlayout. + + 1mpane-base-index 4m22mindex0m + Like 1mbase-index22m, but set the starting index for pane num- + bers. + + 1mremain-on-exit 22m[1mon 22m| 1moff22m] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the 1mrespawn-window 22mcommand. + + 1msynchronize-panes 22m[1mon 22m| 1moff22m] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + 1mutf8 22m[1mon 22m| 1moff22m] + Instructs 1mtmux 22mto expect UTF-8 sequences to appear in + this window. + + 1mwindow-status-activity-style 4m22mstyle0m + Set status line style for windows with an activity alert. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-bell-style 4m22mstyle0m + Set status line style for windows with a bell alert. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-content-style 4m22mstyle0m + Set status line style for windows with a content alert. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-current-format 4m22mstring0m + Like 4mwindow-status-format24m, but is the format used when + the window is the current window. + + 1mwindow-status-current-style 4m22mstyle0m + Set status line style for the currently active window. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-format 4m22mstring0m + Set the format in which the window is displayed in the + status line window list. See the 4mstatus-left24m option for + details of special character sequences available. The + default is `#I:#W#F'. + + 1mwindow-status-last-style 4m22mstyle0m + Set status line style for the last active window. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-separator 4m22mstring0m + Sets the separator drawn between windows in the status + line. The default is a single space character. + + 1mwindow-status-style 4m22mstyle0m + Set status line style for a single window. For how to + specify 4mstyle24m, see the 1mmessage-command-style 22moption. + + 1mxterm-keys 22m[1mon 22m| 1moff22m] + If this option is set, 1mtmux 22mwill generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + 1mwrap-search 22m[1mon 22m| 1moff22m] + If this option is set, searches will wrap around the end + of the pane contents. The default is on. + + 1mshow-options 22m[1m-gqsvw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] [4moption24m] + (alias: 1mshow22m) + Show the window options (or a single window option if given) with + 1m-w 22m(equivalent to 1mshow-window-options22m), the server options with + 1m-s22m, otherwise the session options for 4mtarget24m 4msession24m. Global + session or window options are listed if 1m-g 22mis used. 1m-v 22mshows + only the option value, not the name. If 1m-q 22mis set, no error will + be returned if 4moption24m is unset. + + 1mshow-window-options 22m[1m-gv22m] [1m-t 4m22mtarget-window24m] [4moption24m] + (alias: 1mshoww22m) + List the window options or a single option for 4mtarget-window24m, or + the global window options if 1m-g 22mis used. 1m-v 22mshows only the + option value, not the name. + +1mFORMATS0m + Certain commands accept the 1m-F 22mflag with a 4mformat24m argument. This is a + string which controls the output format of the command. Replacement + variables are enclosed in `#{' and `}', for example `#{session_name}'. + Some variables also have an shorter alias such as `#S'. `##' is replaced + by a single `#'. Conditionals are also accepted by prefixing with `?' + 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 `#{?session_attached,attached,not attached}' + will include the string `attached' if the session is attached and the + string `not attached' if it is unattached. A limit may be placed on the + length of the resultant string by prefixing it by an `=', a number and a + colon, so `#{=10:pane_title}' will include at most the first 10 charac- + ters of the pane title. + + The following variables are available, where appropriate: + + 1mVariable name Alias Replaced with0m + alternate_on If pane is in alternate screen + alternate_saved_x Saved cursor X in alternate screen + alternate_saved_y Saved cursor Y in alternate screen + buffer_sample First 50 characters from buffer + buffer_size Size of the specified buffer in bytes + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_height Height of client + client_last_session Name of the client's last session + client_prefix 1 if prefix key has been pressed + client_readonly 1 if client is readonly + client_session Name of the client's session + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + cursor_flag Pane cursor flag + cursor_x Cursor X position in pane + cursor_y Cursor Y position in pane + history_bytes Number of bytes in window history + history_limit Maximum window history lines + history_size Size of history in bytes + host #H Hostname of local host + host_short #h Hostname of local host (no domain name) + insert_flag Pane insert flag + keypad_cursor_flag Pane keypad cursor flag + keypad_flag Pane keypad flag + line Line number in the list + mouse_any_flag Pane mouse any flag + mouse_button_flag Pane mouse button flag + mouse_standard_flag Pane mouse standard flag + mouse_utf8_flag Pane mouse UTF-8 flag + pane_active 1 if active pane + pane_current_command Current command if available + pane_current_path Current path if available + pane_dead 1 if pane is dead + pane_height Height of pane + pane_id #D Unique pane ID + pane_in_mode If pane is in a mode + pane_synchronized If pane is synchronized + pane_index #P Index of pane + pane_pid PID of first process in pane + pane_start_command Command pane started with + pane_start_path Path pane started with + pane_tabs Pane tab positions + pane_title #T Title of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + saved_cursor_x Saved cursor X in pane + saved_cursor_y Saved cursor Y in pane + scroll_region_lower Bottom of scroll region in pane + scroll_region_upper Top of scroll region in pane + session_attached 1 if session attached + session_created Integer time session created + session_created_string String time session created + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_id Unique session ID + session_name #S Name of session + session_width Width of session + session_windows Number of windows in session + window_active 1 if window active + window_activity_flag 1 if window has activity alert + window_bell_flag 1 if window has bell + window_content_flag 1 if window has content alert + window_find_matches Matched data from the find-window + window_flags #F Window flags + window_height Height of window + window_id Unique window ID + window_index #I Index of window + window_layout Window layout description + window_name #W Name of window + window_panes Number of panes in window + window_silence_flag 1 if window has silence alert + window_width Width of window + wrap_flag Pane wrap flag + +1mNAMES AND TITLES0m + 1mtmux 22mdistinguishes 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 1mtmux 22midentifier 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 1mtmux22m. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. 1mtmux 22mitself may set + the title of the terminal in which the client is running, see the + 1mset-titles 22moption. + + A session's name is set with the 1mnew-session 22mand 1mrename-session 22mcommands. + A window's name is set with one of: + + 1. A command argument (such as 1m-n 22mfor 1mnew-window 22mor 1mnew-session22m). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the 1mautomatic-rename 22moption. + + 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: + + $ printf '\033]2;My Title\033\\' + +1mENVIRONMENT0m + When the server is started, 1mtmux 22mcopies the environment into the 4mglobal0m + 4menvironment24m; in addition, each session has a 4msession24m 4menvironment24m. 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. + + The 1mupdate-environment 22msession option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. 1mtmux 22malso initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of `screen'. + + Commands to alter and view the environment are: + + 1mset-environment 22m[1m-gru22m] [1m-t 4m22mtarget-session24m] 4mname24m [4mvalue24m] + (alias: 1msetenv22m) + Set or unset an environment variable. If 1m-g 22mis used, the change + is made in the global environment; otherwise, it is applied to + the session environment for 4mtarget-session24m. The 1m-u 22mflag unsets a + variable. 1m-r 22mindicates the variable is to be removed from the + environment before starting a new process. + + 1mshow-environment 22m[1m-g22m] [1m-t 4m22mtarget-session24m] [4mvariable24m] + (alias: 1mshowenv22m) + Display the environment for 4mtarget-session24m or the global environ- + ment with 1m-g22m. If 4mvariable24m is omitted, all variables are shown. + Variables removed from the environment are prefixed with `-'. + +1mSTATUS LINE0m + 1mtmux 22mincludes 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 1mstatus 22msession 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the 1mstatus-left22m, 1mstatus-left-length22m, 1mstatus-right22m, + and 1mstatus-right-length 22moptions 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 4mwindow-status-format24m and + 4mwindow-status-current-format24m options. The flag is one of the following + symbols appended to the window name: + + 1mSymbol Meaning0m + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + Z The window's active pane is zoomed. + + The # symbol relates to the 1mmonitor-activity 22mand + to the 1mmonitor-content0m + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the 1mstatus-style 22msession option and individual + windows using the 1mwindow-status-style 22mwindow option. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the 1mstatus-interval 22msession option. + + Commands related to the status line are as follows: + + 1mcommand-prompt 22m[1m-I 4m22minputs24m] [1m-p 4m22mprompts24m] [1m-t 4m22mtarget-client24m] [4mtemplate24m] + Open the command prompt in a client. This may be used from + inside 1mtmux 22mto execute commands interactively. + + If 4mtemplate24m is specified, it is used as the command. If present, + 1m-I 22mis a comma-separated list of the initial text for each prompt. + If 1m-p 22mis given, 4mprompts24m is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from 4mtemplate24m if it is present, or `:' if + not. + + Both 4minputs24m and 4mprompts24m may contain the special character + sequences supported by the 1mstatus-left 22moption. + + Before the command is executed, the first occurrence of the + string `%%' and all occurrences of `%1' are replaced by the + response to the first prompt, the second `%%' and all `%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + (`%1' to `%9'). + + 1mconfirm-before 22m[1m-p 4m22mprompt24m] [1m-t 4m22mtarget-client24m] 4mcommand0m + (alias: 1mconfirm22m) + Ask for confirmation before executing 4mcommand24m. If 1m-p 22mis given, + 4mprompt24m is the prompt to display; otherwise a prompt is con- + structed from 4mcommand24m. It may contain the special character + sequences supported by the 1mstatus-left 22moption. + + This command works only from inside 1mtmux22m. + + 1mdisplay-message 22m[1m-p22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-pane24m] [4mmessage24m] + (alias: 1mdisplay22m) + Display a message. If 1m-p 22mis given, the output is printed to std- + out, otherwise it is displayed in the 4mtarget-client24m status line. + The format of 4mmessage24m is described in the 4mFORMATS24m section; infor- + mation is taken from 4mtarget-pane24m if 1m-t 22mis given, otherwise the + active pane for the session attached to 4mtarget-client24m. + +1mBUFFERS0m + 1mtmux 22mmaintains a stack of 4mpaste24m 4mbuffers24m. Up to the value of the + 1mbuffer-limit 22moption are kept; when a new buffer is added, the buffer at + the bottom of the stack is removed. Buffers may be added using 1mcopy-mode0m + or the 1mset-buffer 22mcommand, and pasted into a window using the + 1mpaste-buffer 22mcommand. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + 1mhistory-limit 22moption (see the 1mset-option 22mcommand above). + + The buffer commands are as follows: + + 1mchoose-buffer 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, `%%' + is replaced by the buffer index in 4mtemplate24m and the result exe- + cuted as a command. If 4mtemplate24m is not given, "paste-buffer -b + '%%'" is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS0m + section. This command works only if at least one client is + attached. + + 1mclear-history 22m[1m-t 4m22mtarget-pane24m] + (alias: 1mclearhist22m) + Remove and free the history for the specified pane. + + 1mdelete-buffer 22m[1m-b 4m22mbuffer-index24m] + (alias: 1mdeleteb22m) + Delete the buffer at 4mbuffer-index24m, or the top buffer if not spec- + ified. + + 1mlist-buffers 22m[1m-F 4m22mformat24m] + (alias: 1mlsb22m) + List the global buffers. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. + + 1mload-buffer 22m[1m-b 4m22mbuffer-index24m] 4mpath0m + (alias: 1mloadb22m) + Load the contents of the specified paste buffer from 4mpath24m. + + 1mpaste-buffer 22m[1m-dpr22m] [1m-b 4m22mbuffer-index24m] [1m-s 4m22mseparator24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mpasteb22m) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With 1m-d22m, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the 1m-s 22mflag. The 1m-r 22mflag means to do no + replacement (equivalent to a separator of LF). If 1m-p 22mis speci- + fied, paste bracket control codes are inserted around the buffer + if the application has requested bracketed paste mode. + + 1msave-buffer 22m[1m-a22m] [1m-b 4m22mbuffer-index24m] 4mpath0m + (alias: 1msaveb22m) + Save the contents of the specified paste buffer to 4mpath24m. The 1m-a0m + option appends to rather than overwriting the file. + + 1mset-buffer 22m[1m-b 4m22mbuffer-index24m] 4mdata0m + (alias: 1msetb22m) + Set the contents of the specified buffer to 4mdata24m. + + 1mshow-buffer 22m[1m-b 4m22mbuffer-index24m] + (alias: 1mshowb22m) + Display the contents of the specified buffer. + +1mMISCELLANEOUS0m + Miscellaneous commands are as follows: + + 1mclock-mode 22m[1m-t 4m22mtarget-pane24m] + Display a large clock. + + 1mif-shell 22m[1m-b22m] [1m-t 4m22mtarget-pane24m] 4mshell-command24m 4mcommand24m [4mcommand24m] + (alias: 1mif22m) + Execute the first 4mcommand24m if 4mshell-command24m returns success or the + second 4mcommand24m otherwise. Before being executed, shell-command + is expanded using the rules specified in the 4mFORMATS24m section, + including those relevant to 4mtarget-pane24m. With 1m-b22m, 4mshell-command0m + is run in the background. + + 1mlock-server0m + (alias: 1mlock22m) + Lock each client individually by running the command specified by + the 1mlock-command 22moption. + + 1mrun-shell 22m[1m-b22m] [1m-t 4m22mtarget-pane24m] 4mshell-command0m + (alias: 1mrun22m) + Execute 4mshell-command24m in the background without creating a win- + dow. Before being executed, shell-command is expanded using the + rules specified in the 4mFORMATS24m section. With 1m-b22m, the command is + run in the background. After it finishes, any output to stdout + is displayed in copy mode (in the pane specified by 1m-t 22mor the + current pane if omitted). If the command doesn't return success, + the exit status is also displayed. + + 1mwait-for 22m[1m-L 22m| 1m-S 22m| 1m-U22m] 4mchannel0m + (alias: 1mwait22m) + When used without options, prevents the client from exiting until + woken using 1mwait-for -S 22mwith the same channel. When 1m-L 22mis 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 + 1mwait-for -U22m. This command only works from outside 1mtmux22m. + +1mTERMINFO EXTENSIONS0m + 1mtmux 22munderstands some extensions to terminfo(5): + + 4mCs24m, 4mCr24m 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 1mtmux22m: + + $ printf '\033]12;red\033\\' + + 4mSs24m, 4mSe24m Change the cursor style. If set, a sequence such as this may be + used to change the cursor to an underline: + + $ printf '\033[4 q' + + If 4mCsr24m is set, it will be used to reset the cursor style instead + of 4mCs24m. + + 4mMs24m This sequence can be used by 1mtmux 22mto store the current buffer in + the host terminal's selection (clipboard). See the 4mset-clipboard0m + option above and the xterm(1) man page. + +1mCONTROL MODE0m + 1mtmux 22moffers a textual interface called 4mcontrol24m 4mmode24m. This allows appli- + cations to communicate with 1mtmux 22musing a simple text-only protocol. + + In control mode, a client sends 1mtmux 22mcommands or command sequences termi- + nated by newlines on standard input. Each command will produce one block + of output on standard output. An output block consists of a 4m%begin24m line + followed by the output (which may be empty). The output block ends with + a 4m%end24m or 4m%error24m. 4m%begin24m and matching 4m%end24m or 4m%error24m have two arguments: + an integer time (as seconds from epoch) and command number. For example: + + %begin 1363006971 2 + 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) + %end 1363006971 2 + + In control mode, 1mtmux 22moutputs notifications. A notification will never + occur inside an output block. + + The following notifications are defined: + + 1m%exit 22m[4mreason24m] + The 1mtmux 22mclient is exiting immediately, either because it is not + attached to any session or an error occurred. If present, 4mreason0m + describes why the client exited. + + 1m%layout-change 4m22mwindow-id24m 4mwindow-layout0m + The layout of a window with ID 4mwindow-id24m changed. The new layout + is 4mwindow-layout24m. + + 1m%output 4m22mpane-id24m 4mvalue0m + A window pane produced output. 4mvalue24m escapes non-printable char- + acters and backslash as octal \xxx. + + 1m%session-changed 4m22msession-id24m 4mname0m + The client is now attached to the session with ID 4msession-id24m, + which is named 4mname24m. + + 1m%session-renamed 4m22mname0m + The current session was renamed to 4mname24m. + + 1m%sessions-changed0m + A session was created or destroyed. + + 1m%unlinked-window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was created but is not linked to the + current session. + + 1m%window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was linked to the current session. + + 1m%window-close 4m22mwindow-id0m + The window with ID 4mwindow-id24m closed. + + 1m%window-renamed 4m22mwindow-id24m 4mname0m + The window with ID 4mwindow-id24m was renamed to 4mname24m. + +1mFILES0m + ~/.tmux.conf Default 1mtmux 22mconfiguration file. + @SYSCONFDIR@/tmux.conf System-wide configuration file. + +1mEXAMPLES0m + To create a new 1mtmux 22msession running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is 1mnew22m: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing `C-b c' + (Ctrl followed by the `b' key followed by the `c' key). + + Windows may be navigated with: `C-b 0' (to select window 0), `C-b 1' (to + select window 1), and so on; `C-b n' to select the next window; and `C-b + p' to select the previous window. + + A session may be detached using `C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing `C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or `q' to exit from it. + + Commands to be run when the 1mtmux 22mserver is started may be placed in the + 4m~/.tmux.conf24m configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-style bg=blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +1mSEE ALSO0m + pty(4) + +1mAUTHORS0m + Nicholas Marriott <4mnicm@users.sourceforge.net24m> + +FreeBSD 11.0 November 6, 2015 FreeBSD 11.0 diff --git a/manual/1.9a.txt b/manual/1.9a.txt new file mode 100644 index 0000000..ad8a165 --- /dev/null +++ b/manual/1.9a.txt @@ -0,0 +1,2117 @@ +TMUX(1) FreeBSD General Commands Manual TMUX(1) + +1mNAME0m + 1mtmux 22m-- terminal multiplexer + +1mSYNOPSIS0m + 1mtmux 22m[1m-2lCquvV22m] [1m-c 4m22mshell-command24m] [1m-f 4m22mfile24m] [1m-L 4m22msocket-name24m] + [1m-S 4m22msocket-path24m] [4mcommand24m [4mflags24m]] + +1mDESCRIPTION0m + 1mtmux 22mis a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. 1mtmux 22mmay be + detached from a screen and continue running in the background, then later + reattached. + + When 1mtmux 22mis started it creates a new 4msession24m with a single 4mwindow24m 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 com- + mands. + + A session is a single collection of 4mpseudo24m 4mterminals24m under the management + of 1mtmux22m. 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 pty(7) manual page documents + the technical details of pseudo terminals). Any number of 1mtmux 22minstances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, 1mtmux 22mexits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + `C-b d' key strokes). 1mtmux 22mmay be reattached using: + + $ tmux attach + + In 1mtmux22m, a session is displayed on screen by a 4mclient24m and all sessions + are managed by a single 4mserver24m. The server and each client are separate + processes which communicate through a socket in 4m/tmp24m. + + The options are as follows: + + 1m-2 22mForce 1mtmux 22mto assume the terminal supports 256 colours. + + 1m-C 22mStart in control mode (see the 4mCONTROL24m 4mMODE24m section). + Given twice (1m-CC22m) disables echo. + + 1m-c 4m22mshell-command0m + Execute 4mshell-command24m using the default shell. If neces- + sary, the 1mtmux 22mserver will be started to retrieve the + 1mdefault-shell 22moption. This option is for compatibility + with sh(1) when 1mtmux 22mis used as a login shell. + + 1m-f 4m22mfile24m Specify an alternative configuration file. By default, + 1mtmux 22mloads the system configuration file from + 4m@SYSCONFDIR@/tmux.conf24m, if present, then looks for a user + configuration file at 4m~/.tmux.conf24m. + + The configuration file is a set of 1mtmux 22mcommands which are + executed in sequence when the server is first started. + 1mtmux 22mloads configuration files once when the server process + has started. The 1msource-file 22mcommand may be used to load a + file later. + + 1mtmux 22mshows any error messages from commands in configura- + tion files in the first session created, and continues to + process the rest of the configuration file. + + 1m-L 4m22msocket-name0m + 1mtmux 22mstores the server socket in a directory under + TMUX_TMPDIR, TMPDIR if it is unset, or 4m/tmp24m if both are + unset. The default socket is named 4mdefault24m. This option + allows a different socket name to be specified, allowing + several independent 1mtmux 22mservers to be run. Unlike 1m-S 22ma + full path is not necessary: the sockets are all created in + the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the 1mtmux 22mserver process to recreate it. + + 1m-l 22mBehave as a login shell. This flag currently has no effect + and is for compatibility with other shells when using tmux + as a login shell. + + 1m-q 22mSet the 1mquiet 22mserver option to prevent the server sending + various informational messages. + + 1m-S 4m22msocket-path0m + Specify a full alternative path to the server socket. If + 1m-S 22mis specified, the default socket directory is not used + and any 1m-L 22mflag is ignored. + + 1m-u tmux 22mattempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the 1m-u 22mflag explic- + itly informs 1mtmux 22mthat UTF-8 is supported. + + If the server is started from a client passed 1m-u 22mor where + UTF-8 is detected, the 1mutf8 22mand 1mstatus-utf8 22moptions are + enabled in the global window and session options respec- + tively. + + 1m-v 22mRequest verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into 4mtmux-client-PID.log24m and 4mtmux-server-PID.log0m + files in the current directory, where 4mPID24m is the PID of the + server or client process. + + 1m-V 22mReport the 1mtmux 22mversion. + + 4mcommand24m [4mflags24m] + This specifies one of a set of commands used to control + 1mtmux22m, as described in the following sections. If no com- + mands are specified, the 1mnew-session 22mcommand is assumed. + +1mKEY BINDINGS0m + 1mtmux 22mmay be controlled from an attached client by using a key combination + of a prefix key, `C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the 1mtmux 22mclient. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the 1mtmux 22mcommand prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + L Switch the attached client back to the last session. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from 1mtmux22m, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the 1mbind-key 22mand 1munbind-key 22mcommands. + +1mCOMMANDS0m + This section contains a list of the commands supported by 1mtmux22m. Most + commands accept the optional 1m-t 22margument with one of 4mtarget-client24m, + 4mtarget-session24m 4mtarget-window24m, or 4mtarget-pane24m. These specify the client, + session, window or pane which a command should affect. 4mtarget-client24m is + the name of the pty(7) file to which the client is connected, for example + either of 4m/dev/ttyp124m or 4mttyp124m for the client attached to 4m/dev/ttyp124m. If + no client is specified, the current client is chosen, if possible, or an + error is reported. Clients may be listed with the 1mlist-clients 22mcommand. + + 4mtarget-session24m is the session id prefixed with a $, the name of a session + (as listed by the 1mlist-sessions 22mcommand), or the name of a client with + the same syntax as 4mtarget-client24m, in which case the session attached to + the client is used. When looking for the session name, 1mtmux 22minitially + searches for an exact match; if none is found, the session names are + checked for any for which 4mtarget-session24m is a prefix or for which it + matches as an 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 ses- + sion is available, the most recently used is chosen. + + 4mtarget-window24m specifies a window in the form 4msession24m:4mwindow24m. 4msession0m + follows the same rules as for 4mtarget-session24m, and 4mwindow24m 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 + fnmatch(3) pattern or the start of a window name, such as myses- + sion:mywin* or mysession:mywin. An empty window name specifies the next + unused index if appropriate (for example the 1mnew-window 22mand 1mlink-window0m + commands) otherwise the current window in 4msession24m is chosen. The special + character `!' uses the last (previously current) window, `^' selects the + highest numbered window, `$' selects the lowest numbered window, and `+' + and `-' select the next window or the previous window by number. When + the argument does not contain a colon, 1mtmux 22mfirst attempts to parse it as + window; if that fails, an attempt is made to match a session. + + 4mtarget-pane24m takes a similar form to 4mtarget-window24m but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + 1mtmux 22mfirst attempts to use the argument as a pane index; if that fails, + it is looked up as for 4mtarget-window24m. A `+' or `-' indicate the next or + previous pane index, respectively. One of the strings 4mtop24m, 4mbottom24m, 4mleft24m, + 4mright24m, 4mtop-left24m, 4mtop-right24m, 4mbottom-left24m or 4mbottom-right24m may be used + instead of a pane index. + + The special characters `+' and `-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + 1mtmux 22malso gives each pane created in a server an identifier consisting of + a `%' and a number, starting from zero. A pane's identifier is unique + for the life of the 1mtmux 22mserver and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + 4mshell-command24m arguments are sh(1) commands. These must be passed as a + single item, which typically means quoting them, for example: + + new-window 'vi /etc/passwd' + + 4mcommand24m [4marguments24m] refers to a 1mtmux 22mcommand, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 4mcommand0m + 4msequence24m. 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 + 1mbind-key22m). + + Example 1mtmux 22mcommands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +1mCLIENTS AND SESSIONS0m + The 1mtmux 22mserver manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the 1mnew-session 22mcommand, or later with the 1mattach-session 22mcom- + mand. Each session has one or more windows 4mlinked24m 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 4mWINDOWS24m 4mAND24m 4mPANES24m sec- + tion. + + The following commands are available to manage clients and sessions: + + 1mattach-session 22m[1m-dr22m] [1m-c 4m22mworking-directory24m] [1m-t 4m22mtarget-session24m] + (alias: 1mattach22m) + If run from outside 1mtmux22m, create a new client in the current ter- + minal and attach it to 4mtarget-session24m. If used from inside, + switch the current client. If 1m-d 22mis specified, any other clients + attached to the session are detached. 1m-r 22msignifies the client is + read-only (only keys bound to the 1mdetach-client 22mor 1mswitch-client0m + commands have any effect) + + If no server is started, 1mattach-session 22mwill attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The 4mtarget-session24m rules for 1mattach-session 22mare slightly + adjusted: if 1mtmux 22mneeds to select the most recently used session, + it will prefer the most recently used 4munattached24m session. + + 1m-c 22mwill set the session working directory (used for new windows) + to 4mworking-directory24m. + + 1mdetach-client 22m[1m-P22m] [1m-a22m] [1m-s 4m22mtarget-session24m] [1m-t 4m22mtarget-client24m] + (alias: 1mdetach22m) + Detach the current client if bound to a key, the client specified + with 1m-t22m, or all clients currently attached to the session speci- + fied by 1m-s22m. The 1m-a 22moption kills all but the client given with + 1m-t22m. If 1m-P 22mis given, send SIGHUP to the parent process of the + client, typically causing it to exit. + + 1mhas-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mhas22m) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + 1mkill-server0m + Kill the 1mtmux 22mserver and clients and destroy all sessions. + + 1mkill-session 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. If + 1m-a 22mis given, all sessions but the specified one is killed. + + 1mlist-clients 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsc22m) + List all clients attached to the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. If 4mtarget-session24m is speci- + fied, list only clients connected to that session. + + 1mlist-commands0m + (alias: 1mlscm22m) + List the syntax of all commands supported by 1mtmux22m. + + 1mlist-sessions 22m[1m-F 4m22mformat24m] + (alias: 1mls22m) + List all sessions managed by the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mlock-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1mlockc22m) + Lock 4mtarget-client24m, see the 1mlock-server 22mcommand. + + 1mlock-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlocks22m) + Lock all clients attached to 4mtarget-session24m. + + 1mnew-session 22m[1m-AdDP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-s0m + 4msession-name24m] [1m-t 4m22mtarget-session24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] + [4mshell-command24m] + (alias: 1mnew22m) + Create a new session with name 4msession-name24m. + + The new session is attached to the current terminal unless 1m-d 22mis + given. 4mwindow-name24m and 4mshell-command24m are the name of and shell + command to execute in the initial window. If 1m-d 22mis used, 1m-x 22mand + 1m-y 22mspecify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(3) special characters are + saved and used for new windows in the new session. + + The 1m-A 22mflag makes 1mnew-session 22mbehave like 1mattach-session 22mif + 4msession-name24m already exists; in the case, 1m-D 22mbehaves like 1m-d 22mto + 1mattach-session22m. + + If 1m-t 22mis given, the new session is 4mgrouped24m with 4mtarget-session24m. + This means they share the same set of windows - all windows from + 4mtarget-session24m 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 1m-n 22mor 4mshell-command24m are invalid if 1m-t 22mis used. + + The 1m-P 22moption prints information about the new session after it + has been created. By default, it uses the format + `#{session_name}:' but a different format may be specified with + 1m-F22m. + + 1mrefresh-client 22m[1m-S22m] [1m-t 4m22mtarget-client24m] + (alias: 1mrefresh22m) + Refresh the current client if bound to a key, or a single client + if one is given with 1m-t22m. If 1m-S 22mis specified, only update the + client's status bar. + + 1mrename-session 22m[1m-t 4m22mtarget-session24m] 4mnew-name0m + (alias: 1mrename22m) + Rename the session to 4mnew-name24m. + + 1mshow-messages 22m[1m-IJT22m] [1m-t 4m22mtarget-client24m] + (alias: 1mshowmsgs22m) + Show client messages or server information. Any messages dis- + played on the status line are saved in a per-client message log, + up to a maximum of the limit set by the 4mmessage-limit24m session + option for the session attached to that client. With 1m-t22m, display + the log for 4mtarget-client24m. 1m-I22m, 1m-J 22mand 1m-T 22mshow debugging informa- + tion about the running server, jobs and terminals. + + 1msource-file 4m22mpath0m + (alias: 1msource22m) + Execute commands from 4mpath24m. + + 1mstart-server0m + (alias: 1mstart22m) + Start the 1mtmux 22mserver, if not already running, without creating + any sessions. + + 1msuspend-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1msuspendc22m) + Suspend a client by sending SIGTSTP (tty stop). + + 1mswitch-client 22m[1m-lnpr22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-session24m] + (alias: 1mswitchc22m) + Switch the current session for client 4mtarget-client24m to + 4mtarget-session24m. If 1m-l22m, 1m-n 22mor 1m-p 22mis used, the client is moved to + the last, next or previous session respectively. 1m-r 22mtoggles + whether a client is read-only (see the 1mattach-session 22mcommand). + +1mWINDOWS AND PANES0m + A 1mtmux 22mwindow 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 + 4mpaste24m 4mbuffer24m for later insertion into another window. This mode is + entered with the 1mcopy-mode 22mcommand, bound to `[' by default. It is also + entered when a command that produces output, such as 1mlist-keys22m, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the 1mmode-keys 22moption). The following keys are supported as appropriate + for the mode: + + 1mFunction vi emacs0m + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump forward f f + Jump to forward t + Jump backward F F + Jump to backward T + Jump again ; ; + Jump again in reverse , , + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Other end of selection o + Paste buffer p C-y + Previous page C-b Page up + Previous word b M-b + Previous space B + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose characters C-t + + The next and previous word keys use space and the `-', `_' and `@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 4mword-separators24m 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. + + The jump commands enable quick movement within a line. For instance, + typing `f' followed by `/' will move the cursor to the next `/' character + on the current line. A `;' will then jump to the next occurrence. + + 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 `M-1 0 M-f' in emacs mode, and + `10w' in vi. + + When copying the selection, the repeat count indicates the buffer index + to replace, if used. + + Mode key bindings are defined in a set of named tables: 4mvi-edit24m and + 4memacs-edit24m for keys used when line editing at the command prompt; + 4mvi-choice24m and 4memacs-choice24m for keys used when choosing from lists (such + as produced by the 1mchoose-window 22mcommand); and 4mvi-copy24m and 4memacs-copy0m + used in copy mode. The tables may be viewed with the 1mlist-keys 22mcommand + and keys modified or removed with 1mbind-key 22mand 1munbind-key22m. One command + accepts an argument, 1mcopy-pipe22m, which copies the selection and pipes it + to a command. For example the following will bind `C-q' to copy the + selection into 4m/tmp24m as well as the paste buffer: + + bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the 1mcopy-mode 22mcommand is: + + 1mcopy-mode 22m[1m-u22m] [1m-t 4m22mtarget-pane24m] + Enter copy mode. The 1m-u 22moption scrolls one page up. + + Each window displayed by 1mtmux 22mmay be split into one or more 4mpanes24m; each + pane takes up a certain area of the display and is a separate terminal. + A window may be split into panes using the 1msplit-window 22mcommand. Windows + may be split horizontally (with the 1m-h 22mflag) or vertically. Panes may be + resized with the 1mresize-pane 22mcommand (bound to `C-up', `C-down' `C-left' + and `C-right' by default), the current pane may be changed with the + 1mselect-pane 22mcommand and the 1mrotate-window 22mand 1mswap-pane 22mcommands may be + used to swap panes without changing their position. Panes are numbered + beginning from zero in the order they are created. + + A number of preset 4mlayouts24m are available. These may be selected with the + 1mselect-layout 22mcommand or cycled with 1mnext-layout 22m(bound to `Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + 1meven-horizontal0m + Panes are spread out evenly from left to right across the window. + + 1meven-vertical0m + Panes are spread evenly from top to bottom. + + 1mmain-horizontal0m + 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 4mmain-pane-height24m window option to + specify the height of the top pane. + + 1mmain-vertical0m + Similar to 1mmain-horizontal 22mbut the large pane is placed on the + left and the others spread from top to bottom along the right. + See the 4mmain-pane-width24m window option. + + 1mtiled 22mPanes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, 1mselect-layout 22mmay be used to apply a previously used layout + - the 1mlist-windows 22mcommand displays the layout of each window in a form + suitable for use with 1mselect-layout22m. For example: + + $ 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} + + 1mtmux 22mautomatically 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. + + Commands related to windows and panes are as follows: + + 1mbreak-pane 22m[1m-dP22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mbreakp22m) + Break 4mtarget-pane24m off from its containing window to make it the + only pane in a new window. If 1m-d 22mis given, the new window does + not become the current window. The 1m-P 22moption prints information + about the new window after it has been created. By default, it + uses the format `#{session_name}:#{window_index}' but a different + format may be specified with 1m-F22m. + + 1mcapture-pane 22m[1m-aepPq22m] [1m-b 4m22mbuffer-index24m] [1m-E 4m22mend-line24m] [1m-S 4m22mstart-line24m] [1m-t0m + 4mtarget-pane24m] + (alias: 1mcapturep22m) + Capture the contents of a pane. If 1m-p 22mis given, the output goes + to stdout, otherwise to the buffer specified with 1m-b 22mor a new + buffer if omitted. If 1m-a 22mis given, the alternate screen is used, + and the history is not accessible. If no alternate screen + exists, an error will be returned unless 1m-q 22mis given. If 1m-e 22mis + given, the output includes escape sequences for text and back- + ground attributes. 1m-C 22malso escapes non-printable characters as + octal \xxx. 1m-J 22mjoins wrapped lines and preserves trailing spaces + at each line's end. 1m-P 22mcaptures only any output that the pane + has received that is the beginning of an as-yet incomplete escape + sequence. + + 1m-S 22mand 1m-E 22mspecify 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 con- + tents of the pane. + + 1mchoose-client 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + `%%' is replaced by the client pty(7) path in 4mtemplate24m and the + result executed as a command. If 4mtemplate24m is not given, "detach- + client -t '%%'" is used. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. This command works only if at least one client + is attached. + + 1mchoose-list 22m[1m-l 4m22mitems24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into list choice mode, allowing 4mitems24m to be + selected. 4mitems24m 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, `%%' is replaced by the chosen item in + the 4mtemplate24m and the result is executed as a command. If + 4mtemplate24m is not given, "run-shell '%%'" is used. 4mitems24m also + accepts format specifiers. For the meaning of this see the + 4mFORMATS24m section. This command works only if at least one client + is attached. + + 1mchoose-session 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, `%%' is + replaced by the session name in 4mtemplate24m and the result executed + as a command. If 4mtemplate24m is not given, "switch-client -t '%%'" + is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. This command works only if at least one client is + attached. + + 1mchoose-tree 22m[1m-suw22m] [1m-b 4m22msession-template24m] [1m-c 4m22mwindow-template24m] [1m-S 4m22mformat24m] + [1m-W 4m22mformat24m] [1m-t 4m22mtarget-window24m] + Put a window into tree choice mode, where either sessions or win- + dows may be selected interactively from a list. By default, win- + dows belonging to a session are indented to show their relation- + ship to a session. + + Note that the 1mchoose-window 22mand 1mchoose-session 22mcommands are wrap- + pers around 1mchoose-tree22m. + + If 1m-s 22mis given, will show sessions. If 1m-w 22mis given, will show + windows. + + By default, the tree is collapsed and sessions must be expanded + to windows with the right arrow key. The 1m-u 22moption will start + with all sessions expanded instead. + + If 1m-b 22mis given, will override the default session command. Note + that `%%' can be used and will be replaced with the session name. + The default option if not specified is "switch-client -t '%%'". + If 1m-c 22mis given, will override the default window command. Like + 1m-b22m, `%%' 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. + + If 1m-S 22mis given will display the specified format instead of the + default session format. If 1m-W 22mis given will display the speci- + fied format instead of the default window format. For the mean- + ing of the 1m-s 22mand 1m-w 22moptions, see the 4mFORMATS24m section. + + This command works only if at least one client is attached. + + 1mchoose-window 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, `%%' + is replaced by the session name and window index in 4mtemplate24m and + the result executed as a command. If 4mtemplate24m is not given, + "select-window -t '%%'" is used. For the meaning of the 1m-F 22mflag, + see the 4mFORMATS24m section. This command works only if at least one + client is attached. + + 1mdisplay-panes 22m[1m-t 4m22mtarget-client24m] + (alias: 1mdisplayp)0m + Display a visible indicator of each pane shown by 4mtarget-client24m. + See the 1mdisplay-panes-time22m, 1mdisplay-panes-colour22m, and + 1mdisplay-panes-active-colour 22msession options. While the indicator + is on screen, a pane may be selected with the `0' to `9' keys. + + 1mfind-window 22m[1m-CNT22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] 4mmatch-string0m + (alias: 1mfindw22m) + Search for the fnmatch(3) pattern 4mmatch-string24m in window names, + titles, and visible content (but not history). The flags control + matching behavior: 1m-C 22mmatches only visible window contents, 1m-N0m + matches only the window name and 1m-T 22mmatches only the window + title. The default is 1m-CNT22m. If only one window is matched, + it'll be automatically selected, otherwise a choice list is + shown. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + This command works only if at least one client is attached. + + 1mjoin-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mjoinp22m) + Like 1msplit-window22m, but instead of splitting 4mdst-pane24m and creating + a new pane, split it and move 4msrc-pane24m into the space. This can + be used to reverse 1mbreak-pane22m. The 1m-b 22moption causes 4msrc-pane24m to + be joined to left of or above 4mdst-pane24m. + + 1mkill-pane 22m[1m-a22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mkillp22m) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The 1m-a 22moption kills all but the + pane given with 1m-t22m. + + 1mkill-window 22m[1m-a22m] [1m-t 4m22mtarget-window24m] + (alias: 1mkillw22m) + Kill the current window or the window at 4mtarget-window24m, removing + it from any sessions to which it is linked. The 1m-a 22moption kills + all but the window given with 1m-t22m. + + 1mlast-pane 22m[1m-t 4m22mtarget-window24m] + (alias: 1mlastp22m) + Select the last (previously selected) pane. + + 1mlast-window 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlast22m) + Select the last (previously selected) window. If no + 4mtarget-session24m is specified, select the last window of the cur- + rent session. + + 1mlink-window 22m[1m-dk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mlinkw22m) + Link the window at 4msrc-window24m to the specified 4mdst-window24m. If + 4mdst-window24m is specified and no such window exists, the 4msrc-window0m + is linked there. If 1m-k 22mis given and 4mdst-window24m exists, it is + killed, otherwise an error is generated. If 1m-d 22mis given, the + newly linked window is not selected. + + 1mlist-panes 22m[1m-as22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget24m] + (alias: 1mlsp22m) + If 1m-a 22mis given, 4mtarget24m is ignored and all panes on the server are + listed. If 1m-s 22mis given, 4mtarget24m is a session (or the current ses- + sion). If neither is given, 4mtarget24m is a window (or the current + window). For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. + + 1mlist-windows 22m[1m-a22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsw22m) + If 1m-a 22mis given, list all windows on the server. Otherwise, list + windows in the current session or in 4mtarget-session24m. For the + meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mmove-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mmovep22m) + Like 1mjoin-pane22m, but 4msrc-pane24m and 4mdst-pane24m may belong to the same + window. + + 1mmove-window 22m[1m-rdk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mmovew22m) + This is similar to 1mlink-window22m, except the window at 4msrc-window0m + is moved to 4mdst-window24m. With 1m-r22m, all windows in the session are + renumbered in sequential order, respecting the 1mbase-index 22moption. + + 1mnew-window 22m[1m-adkP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-t0m + 4mtarget-window24m] [4mshell-command24m] + (alias: 1mneww22m) + Create a new window. With 1m-a22m, the new window is inserted at the + next index up from the specified 4mtarget-window24m, moving windows up + if necessary, otherwise 4mtarget-window24m is the new window location. + + If 1m-d 22mis given, the session does not make the new window the cur- + rent window. 4mtarget-window24m represents the window to be created; + if the target already exists an error is shown, unless the 1m-k0m + flag is used, in which case it is destroyed. 4mshell-command24m is + the command to execute. If 4mshell-command24m is not specified, the + value of the 1mdefault-command 22moption is used. 1m-c 22mspecifies the + working directory in which the new window is created. + + When the shell command completes, the window closes. See the + 1mremain-on-exit 22moption to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running 4minside24m 1mtmux22m. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The 1m-P 22moption prints information about the new window after it + has been created. By default, it uses the format + `#{session_name}:#{window_index}' but a different format may be + specified with 1m-F22m. + + 1mnext-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mnextl22m) + Move a window to the next layout and rearrange the panes to fit. + + 1mnext-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mnext22m) + Move to the next window in the session. If 1m-a 22mis used, move to + the next window with an alert. + + 1mpipe-pane 22m[1m-o22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mpipep22m) + Pipe any output sent by the program in 4mtarget-pane24m to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before 4mshell-command24m is executed. The + 4mshell-command24m string may contain the special character sequences + supported by the 1mstatus-left 22moption. If no 4mshell-command24m is + given, the current pipe (if any) is closed. + + The 1m-o 22moption only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + 1mprevious-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mprevl22m) + Move to the previous layout in the session. + + 1mprevious-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mprev22m) + Move to the previous window in the session. With 1m-a22m, move to the + previous window with an alert. + + 1mrename-window 22m[1m-t 4m22mtarget-window24m] 4mnew-name0m + (alias: 1mrenamew22m) + Rename the current window, or the window at 4mtarget-window24m if + specified, to 4mnew-name24m. + + 1mresize-pane 22m[1m-DLRUZ22m] [1m-t 4m22mtarget-pane24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] [4madjustment24m] + (alias: 1mresizep22m) + Resize a pane, up, down, left or right by 4madjustment24m with 1m-U22m, 1m-D22m, + 1m-L 22mor 1m-R22m, or to an absolute size with 1m-x 22mor 1m-y22m. The 4madjustment0m + is given in lines or cells (the default is 1). + + With 1m-Z22m, the active pane is toggled between zoomed (occupying the + whole of the window) and unzoomed (its normal position in the + layout). + + 1mrespawn-pane 22m[1m-k22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mrespawnp22m) + Reactivate a pane in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless 1m-k 22mis given, in which case any + existing command is killed. + + 1mrespawn-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] [4mshell-command24m] + (alias: 1mrespawnw22m) + Reactivate a window in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the window was created is executed. The + window must be already inactive, unless 1m-k 22mis given, in which + case any existing command is killed. + + 1mrotate-window 22m[1m-DU22m] [1m-t 4m22mtarget-window24m] + (alias: 1mrotatew22m) + Rotate the positions of the panes within a window, either upward + (numerically lower) with 1m-U 22mor downward (numerically higher). + + 1mselect-layout 22m[1m-np22m] [1m-t 4m22mtarget-window24m] [4mlayout-name24m] + (alias: 1mselectl22m) + Choose a specific layout for a window. If 4mlayout-name24m is not + given, the last preset layout used (if any) is reapplied. 1m-n 22mand + 1m-p 22mare equivalent to the 1mnext-layout 22mand 1mprevious-layout 22mcom- + mands. + + 1mselect-pane 22m[1m-lDLRU22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mselectp22m) + Make pane 4mtarget-pane24m the active pane in window 4mtarget-window24m. + If one of 1m-D22m, 1m-L22m, 1m-R22m, or 1m-U 22mis used, respectively the pane below, + to the left, to the right, or above the target pane is used. 1m-l0m + is the same as using the 1mlast-pane 22mcommand. + + 1mselect-window 22m[1m-lnpT22m] [1m-t 4m22mtarget-window24m] + (alias: 1mselectw22m) + Select the window at 4mtarget-window24m. 1m-l22m, 1m-n 22mand 1m-p 22mare equivalent + to the 1mlast-window22m, 1mnext-window 22mand 1mprevious-window 22mcommands. If + 1m-T 22mis given and the selected window is already the current win- + dow, the command behaves like 1mlast-window22m. + + 1msplit-window 22m[1m-dhvP22m] [1m-c 4m22mstart-directory24m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-t0m + 4mtarget-pane24m] [4mshell-command24m] [1m-F 4m22mformat24m] + (alias: 1msplitw22m) + Create a new pane by splitting 4mtarget-pane24m: 1m-h 22mdoes a horizontal + split and 1m-v 22ma vertical split; if neither is specified, 1m-v 22mis + assumed. The 1m-l 22mand 1m-p 22moptions 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 1mnew-window 22mcommand. + + 1mswap-pane 22m[1m-dDU22m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mswapp22m) + Swap two panes. If 1m-U 22mis used and no source pane is specified + with 1m-s22m, 4mdst-pane24m is swapped with the previous pane (before it + numerically); 1m-D 22mswaps with the next pane (after it numerically). + 1m-d 22minstructs 1mtmux 22mnot to change the active pane. + + 1mswap-window 22m[1m-d22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mswapw22m) + This is similar to 1mlink-window22m, except the source and destination + windows are swapped. It is an error if no window exists at + 4msrc-window24m. + + 1munlink-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] + (alias: 1munlinkw22m) + Unlink 4mtarget-window24m. Unless 1m-k 22mis given, a window may be + unlinked only if it is linked to multiple sessions - windows may + not be linked to no sessions; if 1m-k 22mis specified and the window + is linked to only one session, it is unlinked and destroyed. + +1mKEY BINDINGS0m + 1mtmux 22mallows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example `A' to + `Z'). Ctrl keys may be prefixed with `C-' or `^', and Alt (meta) with + `M-'. In addition, the following special key names are accepted: 4mUp24m, + 4mDown24m, 4mLeft24m, 4mRight24m, 4mBSpace24m, 4mBTab24m, 4mDC24m (Delete), 4mEnd24m, 4mEnter24m, 4mEscape24m, 4mF124m to + 4mF2024m, 4mHome24m, 4mIC24m (Insert), 4mNPage/PageDown/PgDn24m, 4mPPage/PageUp/PgUp24m, 4mSpace24m, + and 4mTab24m. Note that to bind the `"' or `'' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + 1mbind-key 22m[1m-cnr22m] [1m-t 4m22mkey-table24m] 4mkey24m 4mcommand24m [4marguments24m] + (alias: 1mbind22m) + Bind key 4mkey24m to 4mcommand24m. By default (without 1m-t22m) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if 1m-n 22mis specified, it is not necessary to + use the prefix key, 4mcommand24m is bound to 4mkey24m alone. The 1m-r 22mflag + indicates this key may repeat, see the 1mrepeat-time 22moption. + + If 1m-t 22mis present, 4mkey24m is bound in 4mkey-table24m: the binding for com- + mand mode with 1m-c 22mor for normal mode without. To view the + default bindings and possible commands, see the 1mlist-keys 22mcom- + mand. + + 1mlist-keys 22m[1m-t 4m22mkey-table24m] + (alias: 1mlsk22m) + List all key bindings. Without 1m-t 22mthe primary key bindings - + those executed when preceded by the prefix key - are printed. + + With 1m-t22m, the key bindings in 4mkey-table24m are listed; this may be + one of: 4mvi-edit24m, 4memacs-edit24m, 4mvi-choice24m, 4memacs-choice24m, 4mvi-copy24m or + 4memacs-copy24m. + + 1msend-keys 22m[1m-lR22m] [1m-t 4m22mtarget-pane24m] 4mkey24m 4m...0m + (alias: 1msend22m) + Send a key or keys to a window. Each argument 4mkey24m is the name of + the key (such as `C-a' or `npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. The + 1m-l 22mflag disables key name lookup and sends the keys literally. + All arguments are sent sequentially from first to last. The 1m-R0m + flag causes the terminal state to be reset. + + 1msend-prefix 22m[1m-222m] [1m-t 4m22mtarget-pane24m] + Send the prefix key, or with 1m-2 22mthe secondary prefix key, to a + window as if it was pressed. + + 1munbind-key 22m[1m-acn22m] [1m-t 4m22mkey-table24m] 4mkey0m + (alias: 1munbind22m) + Unbind the command bound to 4mkey24m. Without 1m-t 22mthe primary key + bindings are modified; in this case, if 1m-n 22mis specified, the com- + mand bound to 4mkey24m without a prefix (if any) is removed. If 1m-a 22mis + present, all key bindings are removed. + + If 1m-t 22mis present, 4mkey24m in 4mkey-table24m is unbound: the binding for + command mode with 1m-c 22mor for normal mode without. + +1mOPTIONS0m + The appearance and behaviour of 1mtmux 22mmay be modified by changing the + value of various options. There are three types of option: 4mserver0m + 4moptions24m, 4msession24m 4moptions24m and 4mwindow24m 4moptions24m. + + The 1mtmux 22mserver has a set of global options which do not apply to any + particular window or session. These are altered with the 1mset-option -s0m + command, or displayed with the 1mshow-options -s 22mcommand. + + 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 1mset-option0m + command and may be listed with the 1mshow-options 22mcommand. The available + server and session options are listed under the 1mset-option 22mcommand. + + 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 inher- + ited. Window options are altered with the 1mset-window-option 22mcommand and + can be listed with the 1mshow-window-options 22mcommand. All window options + are documented with the 1mset-window-option 22mcommand. + + 1mtmux 22malso supports user options which are prefixed with a `@'. User + options may have any name, so long as they are prefixed with `@', and be + set to any string. For example + + $ tmux setw -q @foo "abc123" + $ tmux showw -v @foo + abc123 + + Commands which set options are as follows: + + 1mset-option 22m[1m-agoqsuw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1mset22m) + Set a window option with 1m-w 22m(equivalent to the 1mset-window-option0m + command), a server option with 1m-s22m, otherwise a session option. + + If 1m-g 22mis specified, the global session or window option is set. + The 1m-u 22mflag unsets an option, so a session inherits the option + from the global options. It is not possible to unset a global + option. + + The 1m-o 22mflag prevents setting an option that is already set. + + The 1m-q 22mflag suppresses the informational message (as if the 1mquiet0m + server option was set). + + With 1m-a22m, and if the option expects a string or a style, 4mvalue24m is + appended to the existing setting. For example: + + set -g status-left "foo" + set -ag status-left "bar" + + Will result in `foobar'. And: + + set -g status-style "bg=red" + set -ag status-style "fg=blue" + + Will result in a red background 4mand24m blue foreground. Without 1m-a22m, + the result would be the default background and a blue foreground. + + Available window options are listed under 1mset-window-option22m. + + 4mvalue24m depends on the option and may be a number, a string, or a + flag (on, off, or omitted to toggle). + + Available server options are: + + 1mbuffer-limit 4m22mnumber0m + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + 1mescape-time 4m22mtime0m + Set the time in milliseconds for which 1mtmux 22mwaits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + 1mexit-unattached 22m[1mon 22m| 1moff22m] + If enabled, the server will exit when there are no + attached clients. + + 1mfocus-events 22m[1mon 22m| 1moff22m] + When enabled, focus events are requested from the termi- + nal if supported and passed through to applications run- + ning in 1mtmux22m. Attached clients should be detached and + attached again after changing this option. + + 1mquiet 22m[1mon 22m| 1moff22m] + Enable or disable the display of various informational + messages (see also the 1m-q 22mcommand line flag). + + 1mset-clipboard 22m[1mon 22m| 1moff22m] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an 4mMs24m entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + Available session options are: + + 1massume-paste-time 4m22mmilliseconds0m + If keys are entered faster than one in 4mmilliseconds24m, they + are assumed to have been pasted rather than typed and + 1mtmux 22mkey bindings are not processed. The default is one + millisecond and zero disables. + + 1mbase-index 4m22mindex0m + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + 1mbell-action 22m[1many 22m| 1mnone 22m| 1mcurrent22m] + Set action on window bell. 1many 22mmeans a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, 1mnone 22mmeans all bells are ignored and + 1mcurrent 22mmeans only bells in windows other than the cur- + rent window are ignored. + + 1mbell-on-alert 22m[1mon 22m| 1moff22m] + If on, ring the terminal bell when an alert occurs. + + 1mdefault-command 4m22mshell-command0m + Set the command used for new windows (if not specified + when the window is created) to 4mshell-command24m, which may + be any sh(1) command. The default is an empty string, + which instructs 1mtmux 22mto create a login shell using the + value of the 1mdefault-shell 22moption. + + 1mdefault-shell 4m22mpath0m + Specify the default shell. This is used as the login + shell for new windows when the 1mdefault-command 22moption is + set to empty, and must be the full path of the exe- + cutable. When started 1mtmux 22mtries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or 4m/bin/sh24m. + This option should be configured when 1mtmux 22mis used as a + login shell. + + 1mdefault-terminal 4m22mterminal0m + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For 1mtmux 22mto work correctly, this 4mmust24m be set to + `screen' or a derivative of it. + + 1mdestroy-unattached 22m[1mon 22m| 1moff22m] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + 1mdetach-on-destroy 22m[1mon 22m| 1moff22m] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + 1mdisplay-panes-active-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicator for the active pane. + + 1mdisplay-panes-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicators for inactive panes. + + 1mdisplay-panes-time 4m22mtime0m + Set the time in milliseconds for which the indicators + shown by the 1mdisplay-panes 22mcommand appear. + + 1mdisplay-time 4m22mtime0m + Set the amount of time for which status line messages and + other on-screen indicators are displayed. 4mtime24m is in + milliseconds. + + 1mhistory-limit 4m22mlines0m + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + 1mlock-after-time 4m22mnumber0m + Lock the session (like the 1mlock-session 22mcommand) after + 4mnumber24m seconds of inactivity, or the entire server (all + sessions) if the 1mlock-server 22moption is set. The default + is not to lock (set to 0). + + 1mlock-command 4m22mshell-command0m + Command to run when locking each client. The default is + to run lock(1) with 1m-np22m. + + 1mlock-server 22m[1mon 22m| 1moff22m] + If this option is 1mon 22m(the default), instead of each ses- + sion locking individually as each has been idle for + 1mlock-after-time22m, the entire server will lock after 4mall0m + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + 1mmessage-command-style 4m22mstyle0m + Set status line message command style, where 4mstyle24m is a + comma-separated list of characteristics to be specified. + + These may be `bg=colour' to set the background colour, + `fg=colour' to set the foreground colour, and a list of + attributes as specified below. + + The colour is one of: 1mblack22m, 1mred22m, 1mgreen22m, 1myellow22m, 1mblue22m, + 1mmagenta22m, 1mcyan22m, 1mwhite22m, aixterm bright variants (if sup- + ported: 1mbrightred22m, 1mbrightgreen22m, and so on), 1mcolour0 22mto + 1mcolour255 22mfrom the 256-colour set, 1mdefault22m, or a hexadec- + imal RGB string such as `#ffffff', which chooses the + closest match from the default 256-colour set. + + The attributes is either 1mnone 22mor a comma-delimited list + of one or more of: 1mbright 22m(or 1mbold22m), 1mdim22m, 1munderscore22m, + 1mblink22m, 1mreverse22m, 1mhidden22m, or 1mitalics22m, to turn an attribute + on, or an attribute prefixed with `no' to turn one off. + + Examples are: + + fg=yellow,bold,underscore,blink + bg=black,fg=default,noreverse + + With the 1m-a 22mflag to the 1mset-option 22mcommand the new style + is added otherwise the existing style is replaced. + + 1mmessage-limit 4m22mnumber0m + Set the number of error or information messages to save + in the message log for each client. The default is 20. + + 1mmessage-style 4m22mstyle0m + Set status line message style. For how to specify 4mstyle24m, + see the 1mmessage-command-style 22moption. + + 1mmouse-resize-pane 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures the mouse and allows panes to be + resized by dragging on their borders. + + 1mmouse-select-pane 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures 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. + + 1mmouse-select-window 22m[1mon 22m| 1moff22m] + If on, clicking the mouse on a window name in the status + line will select that window. + + 1mmouse-utf8 22m[1mon 22m| 1moff22m] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + 1mpane-active-border-style 4m22mstyle0m + Set the pane border style for the currently active pane. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. Attributes are ignored. + + 1mpane-border-style 4m22mstyle0m + Set the pane border style for paneas aside from the + active pane. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. Attributes are ignored. + + 1mprefix 4m22mkey0m + Set the key accepted as a prefix key. + + 1mprefix2 4m22mkey0m + Set a secondary key accepted as a prefix key. + + 1mrenumber-windows 22m[1mon 22m| 1moff22m] + If on, when a window is closed in a session, automati- + cally renumber the other windows in numerical order. + This respects the 1mbase-index 22moption if it has been set. + If off, do not renumber the windows. + + 1mrepeat-time 4m22mtime0m + Allow multiple commands to be entered without pressing + the prefix-key again in the specified 4mtime24m milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the 1m-r 22mflag to 1mbind-key22m. Repeat + is enabled for the default keys bound to the 1mresize-pane0m + command. + + 1mset-remain-on-exit 22m[1mon 22m| 1moff22m] + Set the 1mremain-on-exit 22mwindow 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 + 1mrespawn-window 22mcommand to reactivate such a window, or + the 1mkill-window 22mcommand to destroy it. + + 1mset-titles 22m[1mon 22m| 1moff22m] + Attempt to set the client terminal title using the 4mtsl0m + and 4mfsl24m terminfo(5) entries if they exist. 1mtmux 22mautomat- + ically sets these to the \e]2;...\007 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. + + 1mset-titles-string 4m22mstring0m + String used to set the window title if 1mset-titles 22mis on. + Character sequences are replaced as for the 1mstatus-left0m + option. + + 1mstatus 22m[1mon 22m| 1moff22m] + Show or hide the status line. + + 1mstatus-interval 4m22minterval0m + Update the status bar every 4minterval24m seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + 1mstatus-justify 22m[1mleft 22m| 1mcentre 22m| 1mright22m] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + 1mstatus-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string `vi'. + + 1mstatus-left 4m22mstring0m + Display 4mstring24m (by default the session name) to the left + of the status bar. 4mstring24m will be passed through + strftime(3) and formats (see 4mFORMATS24m) will be expanded. + It may also contain any of the following special charac- + ter sequences: + + 1mCharacter pair Replaced with0m + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + ## A literal `#' + + The #(shell-command) form executes `shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the 1mstatus-interval 22moption: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the 1mtmux 22mglobal environ- + ment set (see the 4mENVIRONMENT24m section). + + For details on how the names and titles can be set see + the 4mNAMES24m 4mAND24m 4mTITLES24m section. For a list of allowed + attributes see the 1mmessage-command-style 22moption. + + Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + Where appropriate, special character sequences may be + prefixed with a number to specify the maximum length, for + example `#24T'. + + By default, UTF-8 in 4mstring24m is not interpreted, to enable + UTF-8, use the 1mstatus-utf8 22moption. + + 1mstatus-left-length 4m22mlength0m + Set the maximum 4mlength24m of the left component of the sta- + tus bar. The default is 10. + + 1mstatus-left-style 4m22mstyle0m + Set the style of the left part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-position 22m[1mtop 22m| 1mbottom22m] + Set the position of the status line. + + 1mstatus-right 4m22mstring0m + Display 4mstring24m 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 1mstatus-left22m, 4mstring0m + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the 1mstatus-utf80m + option. + + 1mstatus-right-length 4m22mlength0m + Set the maximum 4mlength24m of the right component of the sta- + tus bar. The default is 40. + + 1mstatus-right-style 4m22mstyle0m + Set the style of the right part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-style 4m22mstyle0m + Set status line style. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. + + 1mstatus-utf8 22m[1mon 22m| 1moff22m] + Instruct 1mtmux 22mto treat top-bit-set characters in the + 1mstatus-left 22mand 1mstatus-right 22mstrings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + 1mterminal-overrides 4m22mstring0m + Contains a list of entries which override terminal + descriptions read using terminfo(5). 4mstring24m is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of 4mname=value24m entries. + + For example, to set the `clear' terminfo(5) entry to + `\e[H\e[2J' for all terminal types and the `dch1' entry + to `\e[P' for the `rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the `colors' entry for terminals which support 256 + colours: + + "*256col*:colors=256,xterm*:XT" + + 1mupdate-environment 4m22mvariables0m + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 1m-r 22mwas given to the 1mset-environment0m + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + 1mvisual-activity 22m[1mon 22m| 1moff22m] + If on, display a status line message when activity occurs + in a window for which the 1mmonitor-activity 22mwindow option + is enabled. + + 1mvisual-bell 22m[1mon 22m| 1moff22m] + 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 1mbell-action0m + option. + + 1mvisual-content 22m[1mon 22m| 1moff22m] + Like 1mvisual-activity22m, display a message when content is + present in a window for which the 1mmonitor-content 22mwindow + option is enabled. + + 1mvisual-silence 22m[1mon 22m| 1moff22m] + If 1mmonitor-silence 22mis enabled, prints a message after the + interval has expired on a given window. + + 1mword-separators 4m22mstring0m + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ` -_@'. + + 1mset-window-option 22m[1m-agoqu22m] [1m-t 4m22mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1msetw22m) + Set a window option. The 1m-a22m, 1m-g22m, 1m-o22m, 1m-q 22mand 1m-u 22mflags work simi- + larly to the 1mset-option 22mcommand. + + Supported window options are: + + 1maggressive-resize 22m[1mon 22m| 1moff22m] + Aggressively resize the chosen window. This means that + 1mtmux 22mwill 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 SIGWINCH and poor for interactive programs + such as shells. + + 1mallow-rename 22m[1mon 22m| 1moff22m] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + 1malternate-screen 22m[1mon 22m| 1moff22m] + This option configures whether programs running inside + 1mtmux 22mmay use the terminal alternate screen feature, which + allows the 4msmcup24m and 4mrmcup24m 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. + + 1mautomatic-rename 22m[1mon 22m| 1moff22m] + Control automatic window renaming. When this setting is + enabled, 1mtmux 22mwill rename the window automatically using + the format specified by 1mautomatic-rename-format22m. This + flag is automatically disabled for an individual window + when a name is specified at creation with 1mnew-window 22mor + 1mnew-session22m, or later with 1mrename-window22m, or with a ter- + minal escape sequence. It may be switched off globally + with: + + set-window-option -g automatic-rename off + + 1mautomatic-rename-format 4m22mformat0m + The format (see 4mFORMATS24m) used when the 1mautomatic-rename0m + option is enabled. + + 1mc0-change-interval 4m22minterval0m + 1mc0-change-trigger 4m22mtrigger0m + These two options configure a simple form of rate limit- + ing for a pane. If 1mtmux 22msees more than 4mtrigger24m 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 4minterval24m milliseconds. This + helps to prevent fast output (such as yes(1)) overwhelm- + ing the terminal. The default is a trigger of 250 and an + interval of 100. A trigger of zero disables the rate + limiting. + + 1mclock-mode-colour 4m22mcolour0m + Set clock colour. + + 1mclock-mode-style 22m[1m12 22m| 1m2422m] + Set clock hour format. + + 1mforce-height 4m22mheight0m + 1mforce-width 4m22mwidth0m + Prevent 1mtmux 22mfrom resizing a window to greater than 4mwidth0m + or 4mheight24m. A value of zero restores the default unlim- + ited setting. + + 1mmain-pane-height 4m22mheight0m + 1mmain-pane-width 4m22mwidth0m + Set the width or height of the main (left or top) pane in + the 1mmain-horizontal 22mor 1mmain-vertical 22mlayouts. + + 1mmode-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in copy and choice + modes. As with the 1mstatus-keys 22moption, the default is + emacs, unless VISUAL or EDITOR contains `vi'. + + 1mmode-mouse 22m[1mon 22m| 1moff 22m| 1mcopy-mode22m] + 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 4mcopy-mode24m, + the mouse behaves as set to on, but cannot be used to + enter copy mode. + + 1mmode-style 4m22mstyle0m + Set window modes style. For how to specify 4mstyle24m, see + the 1mmessage-command-style 22moption. + + 1mmonitor-activity 22m[1mon 22m| 1moff22m] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + 1mmonitor-content 4m22mmatch-string0m + Monitor content in the window. When fnmatch(3) pattern + 4mmatch-string24m appears in the window, it is highlighted in + the status line. + + 1mmonitor-silence 22m[1minterval22m] + Monitor for silence (no activity) in the window within + 1minterval 22mseconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + 1mother-pane-height 4m22mheight0m + Set the height of the other panes (not the main pane) in + the 1mmain-horizontal 22mlayout. If this option is set to 0 + (the default), it will have no effect. If both the + 1mmain-pane-height 22mand 1mother-pane-height 22moptions are set, + the main pane will grow taller to make the other panes + the specified height, but will never shrink to do so. + + 1mother-pane-width 4m22mwidth0m + Like 1mother-pane-height22m, but set the width of other panes + in the 1mmain-vertical 22mlayout. + + 1mpane-base-index 4m22mindex0m + Like 1mbase-index22m, but set the starting index for pane num- + bers. + + 1mremain-on-exit 22m[1mon 22m| 1moff22m] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the 1mrespawn-window 22mcommand. + + 1msynchronize-panes 22m[1mon 22m| 1moff22m] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + 1mutf8 22m[1mon 22m| 1moff22m] + Instructs 1mtmux 22mto expect UTF-8 sequences to appear in + this window. + + 1mwindow-status-activity-style 4m22mstyle0m + Set status line style for windows with an activity alert. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-bell-style 4m22mstyle0m + Set status line style for windows with a bell alert. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-content-style 4m22mstyle0m + Set status line style for windows with a content alert. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-current-format 4m22mstring0m + Like 4mwindow-status-format24m, but is the format used when + the window is the current window. + + 1mwindow-status-current-style 4m22mstyle0m + Set status line style for the currently active window. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-format 4m22mstring0m + Set the format in which the window is displayed in the + status line window list. See the 4mstatus-left24m option for + details of special character sequences available. The + default is `#I:#W#F'. + + 1mwindow-status-last-style 4m22mstyle0m + Set status line style for the last active window. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-separator 4m22mstring0m + Sets the separator drawn between windows in the status + line. The default is a single space character. + + 1mwindow-status-style 4m22mstyle0m + Set status line style for a single window. For how to + specify 4mstyle24m, see the 1mmessage-command-style 22moption. + + 1mxterm-keys 22m[1mon 22m| 1moff22m] + If this option is set, 1mtmux 22mwill generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + 1mwrap-search 22m[1mon 22m| 1moff22m] + If this option is set, searches will wrap around the end + of the pane contents. The default is on. + + 1mshow-options 22m[1m-gqsvw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] [4moption24m] + (alias: 1mshow22m) + Show the window options (or a single window option if given) with + 1m-w 22m(equivalent to 1mshow-window-options22m), the server options with + 1m-s22m, otherwise the session options for 4mtarget24m 4msession24m. Global + session or window options are listed if 1m-g 22mis used. 1m-v 22mshows + only the option value, not the name. If 1m-q 22mis set, no error will + be returned if 4moption24m is unset. + + 1mshow-window-options 22m[1m-gv22m] [1m-t 4m22mtarget-window24m] [4moption24m] + (alias: 1mshoww22m) + List the window options or a single option for 4mtarget-window24m, or + the global window options if 1m-g 22mis used. 1m-v 22mshows only the + option value, not the name. + +1mFORMATS0m + Certain commands accept the 1m-F 22mflag with a 4mformat24m argument. This is a + string which controls the output format of the command. Replacement + variables are enclosed in `#{' and `}', for example `#{session_name}'. + Some variables also have an shorter alias such as `#S'. `##' is replaced + by a single `#'. Conditionals are also accepted by prefixing with `?' + 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 `#{?session_attached,attached,not attached}' + will include the string `attached' if the session is attached and the + string `not attached' if it is unattached. A limit may be placed on the + length of the resultant string by prefixing it by an `=', a number and a + colon, so `#{=10:pane_title}' will include at most the first 10 charac- + ters of the pane title. + + The following variables are available, where appropriate: + + 1mVariable name Alias Replaced with0m + alternate_on If pane is in alternate screen + alternate_saved_x Saved cursor X in alternate screen + alternate_saved_y Saved cursor Y in alternate screen + buffer_sample First 50 characters from buffer + buffer_size Size of the specified buffer in bytes + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_height Height of client + client_last_session Name of the client's last session + client_prefix 1 if prefix key has been pressed + client_readonly 1 if client is readonly + client_session Name of the client's session + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + cursor_flag Pane cursor flag + cursor_x Cursor X position in pane + cursor_y Cursor Y position in pane + history_bytes Number of bytes in window history + history_limit Maximum window history lines + history_size Size of history in bytes + host #H Hostname of local host + host_short #h Hostname of local host (no domain name) + insert_flag Pane insert flag + keypad_cursor_flag Pane keypad cursor flag + keypad_flag Pane keypad flag + line Line number in the list + mouse_any_flag Pane mouse any flag + mouse_button_flag Pane mouse button flag + mouse_standard_flag Pane mouse standard flag + mouse_utf8_flag Pane mouse UTF-8 flag + pane_active 1 if active pane + pane_current_command Current command if available + pane_current_path Current path if available + pane_dead 1 if pane is dead + pane_height Height of pane + pane_id #D Unique pane ID + pane_in_mode If pane is in a mode + pane_synchronized If pane is synchronized + pane_index #P Index of pane + pane_pid PID of first process in pane + pane_start_command Command pane started with + pane_start_path Path pane started with + pane_tabs Pane tab positions + pane_title #T Title of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + saved_cursor_x Saved cursor X in pane + saved_cursor_y Saved cursor Y in pane + scroll_region_lower Bottom of scroll region in pane + scroll_region_upper Top of scroll region in pane + session_attached 1 if session attached + session_created Integer time session created + session_created_string String time session created + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_id Unique session ID + session_name #S Name of session + session_width Width of session + session_windows Number of windows in session + window_active 1 if window active + window_activity_flag 1 if window has activity alert + window_bell_flag 1 if window has bell + window_content_flag 1 if window has content alert + window_find_matches Matched data from the find-window + window_flags #F Window flags + window_height Height of window + window_id Unique window ID + window_index #I Index of window + window_layout Window layout description + window_name #W Name of window + window_panes Number of panes in window + window_silence_flag 1 if window has silence alert + window_width Width of window + wrap_flag Pane wrap flag + +1mNAMES AND TITLES0m + 1mtmux 22mdistinguishes 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 1mtmux 22midentifier 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 1mtmux22m. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. 1mtmux 22mitself may set + the title of the terminal in which the client is running, see the + 1mset-titles 22moption. + + A session's name is set with the 1mnew-session 22mand 1mrename-session 22mcommands. + A window's name is set with one of: + + 1. A command argument (such as 1m-n 22mfor 1mnew-window 22mor 1mnew-session22m). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the 1mautomatic-rename 22moption. + + 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: + + $ printf '\033]2;My Title\033\\' + +1mENVIRONMENT0m + When the server is started, 1mtmux 22mcopies the environment into the 4mglobal0m + 4menvironment24m; in addition, each session has a 4msession24m 4menvironment24m. 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. + + The 1mupdate-environment 22msession option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. 1mtmux 22malso initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of `screen'. + + Commands to alter and view the environment are: + + 1mset-environment 22m[1m-gru22m] [1m-t 4m22mtarget-session24m] 4mname24m [4mvalue24m] + (alias: 1msetenv22m) + Set or unset an environment variable. If 1m-g 22mis used, the change + is made in the global environment; otherwise, it is applied to + the session environment for 4mtarget-session24m. The 1m-u 22mflag unsets a + variable. 1m-r 22mindicates the variable is to be removed from the + environment before starting a new process. + + 1mshow-environment 22m[1m-g22m] [1m-t 4m22mtarget-session24m] [4mvariable24m] + (alias: 1mshowenv22m) + Display the environment for 4mtarget-session24m or the global environ- + ment with 1m-g22m. If 4mvariable24m is omitted, all variables are shown. + Variables removed from the environment are prefixed with `-'. + +1mSTATUS LINE0m + 1mtmux 22mincludes 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 1mstatus 22msession 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the 1mstatus-left22m, 1mstatus-left-length22m, 1mstatus-right22m, + and 1mstatus-right-length 22moptions 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 4mwindow-status-format24m and + 4mwindow-status-current-format24m options. The flag is one of the following + symbols appended to the window name: + + 1mSymbol Meaning0m + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + + Window is monitored for content and it has appeared. + ~ The window has been silent for the monitor-silence + interval. + Z The window's active pane is zoomed. + + The # symbol relates to the 1mmonitor-activity 22mand + to the 1mmonitor-content0m + window options. The window name is printed in inverted colours if an + alert (bell, activity or content) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the 1mstatus-style 22msession option and individual + windows using the 1mwindow-status-style 22mwindow option. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the 1mstatus-interval 22msession option. + + Commands related to the status line are as follows: + + 1mcommand-prompt 22m[1m-I 4m22minputs24m] [1m-p 4m22mprompts24m] [1m-t 4m22mtarget-client24m] [4mtemplate24m] + Open the command prompt in a client. This may be used from + inside 1mtmux 22mto execute commands interactively. + + If 4mtemplate24m is specified, it is used as the command. If present, + 1m-I 22mis a comma-separated list of the initial text for each prompt. + If 1m-p 22mis given, 4mprompts24m is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from 4mtemplate24m if it is present, or `:' if + not. + + Both 4minputs24m and 4mprompts24m may contain the special character + sequences supported by the 1mstatus-left 22moption. + + Before the command is executed, the first occurrence of the + string `%%' and all occurrences of `%1' are replaced by the + response to the first prompt, the second `%%' and all `%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + (`%1' to `%9'). + + 1mconfirm-before 22m[1m-p 4m22mprompt24m] [1m-t 4m22mtarget-client24m] 4mcommand0m + (alias: 1mconfirm22m) + Ask for confirmation before executing 4mcommand24m. If 1m-p 22mis given, + 4mprompt24m is the prompt to display; otherwise a prompt is con- + structed from 4mcommand24m. It may contain the special character + sequences supported by the 1mstatus-left 22moption. + + This command works only from inside 1mtmux22m. + + 1mdisplay-message 22m[1m-p22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-pane24m] [4mmessage24m] + (alias: 1mdisplay22m) + Display a message. If 1m-p 22mis given, the output is printed to std- + out, otherwise it is displayed in the 4mtarget-client24m status line. + The format of 4mmessage24m is described in the 4mFORMATS24m section; infor- + mation is taken from 4mtarget-pane24m if 1m-t 22mis given, otherwise the + active pane for the session attached to 4mtarget-client24m. + +1mBUFFERS0m + 1mtmux 22mmaintains a stack of 4mpaste24m 4mbuffers24m. Up to the value of the + 1mbuffer-limit 22moption are kept; when a new buffer is added, the buffer at + the bottom of the stack is removed. Buffers may be added using 1mcopy-mode0m + or the 1mset-buffer 22mcommand, and pasted into a window using the + 1mpaste-buffer 22mcommand. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + 1mhistory-limit 22moption (see the 1mset-option 22mcommand above). + + The buffer commands are as follows: + + 1mchoose-buffer 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, `%%' + is replaced by the buffer index in 4mtemplate24m and the result exe- + cuted as a command. If 4mtemplate24m is not given, "paste-buffer -b + '%%'" is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS0m + section. This command works only if at least one client is + attached. + + 1mclear-history 22m[1m-t 4m22mtarget-pane24m] + (alias: 1mclearhist22m) + Remove and free the history for the specified pane. + + 1mdelete-buffer 22m[1m-b 4m22mbuffer-index24m] + (alias: 1mdeleteb22m) + Delete the buffer at 4mbuffer-index24m, or the top buffer if not spec- + ified. + + 1mlist-buffers 22m[1m-F 4m22mformat24m] + (alias: 1mlsb22m) + List the global buffers. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. + + 1mload-buffer 22m[1m-b 4m22mbuffer-index24m] 4mpath0m + (alias: 1mloadb22m) + Load the contents of the specified paste buffer from 4mpath24m. + + 1mpaste-buffer 22m[1m-dpr22m] [1m-b 4m22mbuffer-index24m] [1m-s 4m22mseparator24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mpasteb22m) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With 1m-d22m, also + delete the paste buffer from the stack. When output, any line- + feed (LF) characters in the paste buffer are replaced with a sep- + arator, by default carriage return (CR). A custom separator may + be specified using the 1m-s 22mflag. The 1m-r 22mflag means to do no + replacement (equivalent to a separator of LF). If 1m-p 22mis speci- + fied, paste bracket control codes are inserted around the buffer + if the application has requested bracketed paste mode. + + 1msave-buffer 22m[1m-a22m] [1m-b 4m22mbuffer-index24m] 4mpath0m + (alias: 1msaveb22m) + Save the contents of the specified paste buffer to 4mpath24m. The 1m-a0m + option appends to rather than overwriting the file. + + 1mset-buffer 22m[1m-b 4m22mbuffer-index24m] 4mdata0m + (alias: 1msetb22m) + Set the contents of the specified buffer to 4mdata24m. + + 1mshow-buffer 22m[1m-b 4m22mbuffer-index24m] + (alias: 1mshowb22m) + Display the contents of the specified buffer. + +1mMISCELLANEOUS0m + Miscellaneous commands are as follows: + + 1mclock-mode 22m[1m-t 4m22mtarget-pane24m] + Display a large clock. + + 1mif-shell 22m[1m-b22m] [1m-t 4m22mtarget-pane24m] 4mshell-command24m 4mcommand24m [4mcommand24m] + (alias: 1mif22m) + Execute the first 4mcommand24m if 4mshell-command24m returns success or the + second 4mcommand24m otherwise. Before being executed, shell-command + is expanded using the rules specified in the 4mFORMATS24m section, + including those relevant to 4mtarget-pane24m. With 1m-b22m, 4mshell-command0m + is run in the background. + + 1mlock-server0m + (alias: 1mlock22m) + Lock each client individually by running the command specified by + the 1mlock-command 22moption. + + 1mrun-shell 22m[1m-b22m] [1m-t 4m22mtarget-pane24m] 4mshell-command0m + (alias: 1mrun22m) + Execute 4mshell-command24m in the background without creating a win- + dow. Before being executed, shell-command is expanded using the + rules specified in the 4mFORMATS24m section. With 1m-b22m, the command is + run in the background. After it finishes, any output to stdout + is displayed in copy mode (in the pane specified by 1m-t 22mor the + current pane if omitted). If the command doesn't return success, + the exit status is also displayed. + + 1mwait-for 22m[1m-L 22m| 1m-S 22m| 1m-U22m] 4mchannel0m + (alias: 1mwait22m) + When used without options, prevents the client from exiting until + woken using 1mwait-for -S 22mwith the same channel. When 1m-L 22mis 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 + 1mwait-for -U22m. This command only works from outside 1mtmux22m. + +1mTERMINFO EXTENSIONS0m + 1mtmux 22munderstands some extensions to terminfo(5): + + 4mCs24m, 4mCr24m 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 1mtmux22m: + + $ printf '\033]12;red\033\\' + + 4mSs24m, 4mSe24m Change the cursor style. If set, a sequence such as this may be + used to change the cursor to an underline: + + $ printf '\033[4 q' + + If 4mCsr24m is set, it will be used to reset the cursor style instead + of 4mCs24m. + + 4mMs24m This sequence can be used by 1mtmux 22mto store the current buffer in + the host terminal's selection (clipboard). See the 4mset-clipboard0m + option above and the xterm(1) man page. + +1mCONTROL MODE0m + 1mtmux 22moffers a textual interface called 4mcontrol24m 4mmode24m. This allows appli- + cations to communicate with 1mtmux 22musing a simple text-only protocol. + + In control mode, a client sends 1mtmux 22mcommands or command sequences termi- + nated by newlines on standard input. Each command will produce one block + of output on standard output. An output block consists of a 4m%begin24m line + followed by the output (which may be empty). The output block ends with + a 4m%end24m or 4m%error24m. 4m%begin24m and matching 4m%end24m or 4m%error24m have two arguments: + an integer time (as seconds from epoch) and command number. For example: + + %begin 1363006971 2 + 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) + %end 1363006971 2 + + In control mode, 1mtmux 22moutputs notifications. A notification will never + occur inside an output block. + + The following notifications are defined: + + 1m%exit 22m[4mreason24m] + The 1mtmux 22mclient is exiting immediately, either because it is not + attached to any session or an error occurred. If present, 4mreason0m + describes why the client exited. + + 1m%layout-change 4m22mwindow-id24m 4mwindow-layout0m + The layout of a window with ID 4mwindow-id24m changed. The new layout + is 4mwindow-layout24m. + + 1m%output 4m22mpane-id24m 4mvalue0m + A window pane produced output. 4mvalue24m escapes non-printable char- + acters and backslash as octal \xxx. + + 1m%session-changed 4m22msession-id24m 4mname0m + The client is now attached to the session with ID 4msession-id24m, + which is named 4mname24m. + + 1m%session-renamed 4m22mname0m + The current session was renamed to 4mname24m. + + 1m%sessions-changed0m + A session was created or destroyed. + + 1m%unlinked-window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was created but is not linked to the + current session. + + 1m%window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was linked to the current session. + + 1m%window-close 4m22mwindow-id0m + The window with ID 4mwindow-id24m closed. + + 1m%window-renamed 4m22mwindow-id24m 4mname0m + The window with ID 4mwindow-id24m was renamed to 4mname24m. + +1mFILES0m + ~/.tmux.conf Default 1mtmux 22mconfiguration file. + @SYSCONFDIR@/tmux.conf System-wide configuration file. + +1mEXAMPLES0m + To create a new 1mtmux 22msession running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is 1mnew22m: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing `C-b c' + (Ctrl followed by the `b' key followed by the `c' key). + + Windows may be navigated with: `C-b 0' (to select window 0), `C-b 1' (to + select window 1), and so on; `C-b n' to select the next window; and `C-b + p' to select the previous window. + + A session may be detached using `C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing `C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or `q' to exit from it. + + Commands to be run when the 1mtmux 22mserver is started may be placed in the + 4m~/.tmux.conf24m configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-style bg=blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +1mSEE ALSO0m + pty(7) + +1mAUTHORS0m + Nicholas Marriott <4mnicm@users.sourceforge.net24m> + +FreeBSD 11.0 November 6, 2015 FreeBSD 11.0 diff --git a/manual/2.0.txt b/manual/2.0.txt new file mode 100644 index 0000000..d845218 --- /dev/null +++ b/manual/2.0.txt @@ -0,0 +1,2126 @@ +TMUX(1) FreeBSD General Commands Manual TMUX(1) + +1mNAME0m + 1mtmux 22m-- terminal multiplexer + +1mSYNOPSIS0m + 1mtmux 22m[1m-2lCquvV22m] [1m-c 4m22mshell-command24m] [1m-f 4m22mfile24m] [1m-L 4m22msocket-name24m] + [1m-S 4m22msocket-path24m] [4mcommand24m [4mflags24m]] + +1mDESCRIPTION0m + 1mtmux 22mis a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. 1mtmux 22mmay be + detached from a screen and continue running in the background, then later + reattached. + + When 1mtmux 22mis started it creates a new 4msession24m with a single 4mwindow24m 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 com- + mands. + + A session is a single collection of 4mpseudo24m 4mterminals24m under the management + of 1mtmux22m. 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 pty(7) manual page documents + the technical details of pseudo terminals). Any number of 1mtmux 22minstances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, 1mtmux 22mexits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + `C-b d' key strokes). 1mtmux 22mmay be reattached using: + + $ tmux attach + + In 1mtmux22m, a session is displayed on screen by a 4mclient24m and all sessions + are managed by a single 4mserver24m. The server and each client are separate + processes which communicate through a socket in 4m/tmp24m. + + The options are as follows: + + 1m-2 22mForce 1mtmux 22mto assume the terminal supports 256 colours. + + 1m-C 22mStart in control mode (see the 4mCONTROL24m 4mMODE24m section). + Given twice (1m-CC22m) disables echo. + + 1m-c 4m22mshell-command0m + Execute 4mshell-command24m using the default shell. If neces- + sary, the 1mtmux 22mserver will be started to retrieve the + 1mdefault-shell 22moption. This option is for compatibility + with sh(1) when 1mtmux 22mis used as a login shell. + + 1m-f 4m22mfile24m Specify an alternative configuration file. By default, + 1mtmux 22mloads the system configuration file from + 4m@SYSCONFDIR@/tmux.conf24m, if present, then looks for a user + configuration file at 4m~/.tmux.conf24m. + + The configuration file is a set of 1mtmux 22mcommands which are + executed in sequence when the server is first started. + 1mtmux 22mloads configuration files once when the server process + has started. The 1msource-file 22mcommand may be used to load a + file later. + + 1mtmux 22mshows any error messages from commands in configura- + tion files in the first session created, and continues to + process the rest of the configuration file. + + 1m-L 4m22msocket-name0m + 1mtmux 22mstores the server socket in a directory under + TMUX_TMPDIR, TMPDIR if it is unset, or 4m/tmp24m if both are + unset. The default socket is named 4mdefault24m. This option + allows a different socket name to be specified, allowing + several independent 1mtmux 22mservers to be run. Unlike 1m-S 22ma + full path is not necessary: the sockets are all created in + the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the 1mtmux 22mserver process to recreate it. + + 1m-l 22mBehave as a login shell. This flag currently has no effect + and is for compatibility with other shells when using tmux + as a login shell. + + 1m-S 4m22msocket-path0m + Specify a full alternative path to the server socket. If + 1m-S 22mis specified, the default socket directory is not used + and any 1m-L 22mflag is ignored. + + 1m-u tmux 22mattempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the 1m-u 22mflag explic- + itly informs 1mtmux 22mthat UTF-8 is supported. + + If the server is started from a client passed 1m-u 22mor where + UTF-8 is detected, the 1mutf8 22mand 1mstatus-utf8 22moptions are + enabled in the global window and session options respec- + tively. + + 1m-v 22mRequest verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into 4mtmux-client-PID.log24m and 4mtmux-server-PID.log0m + files in the current directory, where 4mPID24m is the PID of the + server or client process. + + 1m-V 22mReport the 1mtmux 22mversion. + + 4mcommand24m [4mflags24m] + This specifies one of a set of commands used to control + 1mtmux22m, as described in the following sections. If no com- + mands are specified, the 1mnew-session 22mcommand is assumed. + +1mKEY BINDINGS0m + 1mtmux 22mmay be controlled from an attached client by using a key combination + of a prefix key, `C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the 1mtmux 22mclient. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + ( Switch the attached client to the previous session. + ) Switch the attached client to the next session. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the 1mtmux 22mcommand prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + L Switch the attached client back to the last session. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + s Select a new session for the attached client interac- + tively. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + z Toggle zoom state of the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from 1mtmux22m, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + Space Arrange the current window in the next preset layout. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the 1mbind-key 22mand 1munbind-key 22mcommands. + +1mCOMMANDS0m + This section contains a list of the commands supported by 1mtmux22m. Most + commands accept the optional 1m-t 22margument with one of 4mtarget-client24m, + 4mtarget-session24m 4mtarget-window24m, or 4mtarget-pane24m. These specify the client, + session, window or pane which a command should affect. 4mtarget-client24m is + the name of the pty(7) file to which the client is connected, for example + either of 4m/dev/ttyp124m or 4mttyp124m for the client attached to 4m/dev/ttyp124m. If + no client is specified, the current client is chosen, if possible, or an + error is reported. Clients may be listed with the 1mlist-clients 22mcommand. + + 4mtarget-session24m is the session id prefixed with a $, the name of a session + (as listed by the 1mlist-sessions 22mcommand), or the name of a client with + the same syntax as 4mtarget-client24m, in which case the session attached to + the client is used. When looking for the session name, 1mtmux 22minitially + searches for an exact match; if none is found, the session names are + checked for any for which 4mtarget-session24m is a prefix or for which it + matches as an 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 ses- + sion is available, the most recently used is chosen. + + 4mtarget-window24m specifies a window in the form 4msession24m:4mwindow24m. 4msession0m + follows the same rules as for 4mtarget-session24m, and 4mwindow24m 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 + fnmatch(3) pattern or the start of a window name, such as myses- + sion:mywin* or mysession:mywin. An empty window name specifies the next + unused index if appropriate (for example the 1mnew-window 22mand 1mlink-window0m + commands) otherwise the current window in 4msession24m is chosen. The special + character `!' uses the last (previously current) window, `^' selects the + highest numbered window, `$' selects the lowest numbered window, and `+' + and `-' select the next window or the previous window by number. When + the argument does not contain a colon, 1mtmux 22mfirst attempts to parse it as + window; if that fails, an attempt is made to match a session. + + 4mtarget-pane24m takes a similar form to 4mtarget-window24m but with the optional + addition of a period followed by a pane index, for example: myses- + sion: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, + 1mtmux 22mfirst attempts to use the argument as a pane index; if that fails, + it is looked up as for 4mtarget-window24m. A `+', `-' or `!' indicate the + next, previous or last pane. One of the strings 4mtop24m, 4mbottom24m, 4mleft24m, + 4mright24m, 4mtop-left24m, 4mtop-right24m, 4mbottom-left24m or 4mbottom-right24m may be used + instead of a pane index. + + The special characters `+' and `-' may be followed by an offset, for + example: + + select-window -t:+2 + + When dealing with a session that doesn't contain sequential window + indexes, they will be correctly skipped. + + 1mtmux 22malso gives each pane created in a server an identifier consisting of + a `%' and a number, starting from zero. A pane's identifier is unique + for the life of the 1mtmux 22mserver and is passed to the child process of the + pane in the TMUX_PANE environment variable. It may be used alone to tar- + get a pane or the window containing it. + + 4mshell-command24m arguments are sh(1) commands. This may be a single argu- + ment passed to the shell, for example: + + new-window 'vi /etc/passwd' + + Will run: + + /bin/sh -c 'vi /etc/passwd' + + Additionally, the 1mnew-window22m, 1mnew-session22m, 1msplit-window22m, 1mrespawn-window0m + and 1mrespawn-pane 22mcommands allow 4mshell-command24m to be given as multiple + arguments and executed directly (without `sh -c'). This can avoid issues + with shell quoting. For example: + + $ tmux new-window vi /etc/passwd + + Will run vi(1) directly without invoking the shell. + + 4mcommand24m [4marguments24m] refers to a 1mtmux 22mcommand, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 4mcommand0m + 4msequence24m. 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 + 1mbind-key22m). + + Example 1mtmux 22mcommands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +1mCLIENTS AND SESSIONS0m + The 1mtmux 22mserver manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the 1mnew-session 22mcommand, or later with the 1mattach-session 22mcom- + mand. Each session has one or more windows 4mlinked24m 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 4mWINDOWS24m 4mAND24m 4mPANES24m sec- + tion. + + The following commands are available to manage clients and sessions: + + 1mattach-session 22m[1m-dr22m] [1m-c 4m22mworking-directory24m] [1m-t 4m22mtarget-session24m] + (alias: 1mattach22m) + If run from outside 1mtmux22m, create a new client in the current ter- + minal and attach it to 4mtarget-session24m. If used from inside, + switch the current client. If 1m-d 22mis specified, any other clients + attached to the session are detached. 1m-r 22msignifies the client is + read-only (only keys bound to the 1mdetach-client 22mor 1mswitch-client0m + commands have any effect) + + If no server is started, 1mattach-session 22mwill attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The 4mtarget-session24m rules for 1mattach-session 22mare slightly + adjusted: if 1mtmux 22mneeds to select the most recently used session, + it will prefer the most recently used 4munattached24m session. + + 1m-c 22mwill set the session working directory (used for new windows) + to 4mworking-directory24m. + + 1mdetach-client 22m[1m-P22m] [1m-a22m] [1m-s 4m22mtarget-session24m] [1m-t 4m22mtarget-client24m] + (alias: 1mdetach22m) + Detach the current client if bound to a key, the client specified + with 1m-t22m, or all clients currently attached to the session speci- + fied by 1m-s22m. The 1m-a 22moption kills all but the client given with + 1m-t22m. If 1m-P 22mis given, send SIGHUP to the parent process of the + client, typically causing it to exit. + + 1mhas-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mhas22m) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + 1mkill-server0m + Kill the 1mtmux 22mserver and clients and destroy all sessions. + + 1mkill-session 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. If + 1m-a 22mis given, all sessions but the specified one is killed. + + 1mlist-clients 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsc22m) + List all clients attached to the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. If 4mtarget-session24m is speci- + fied, list only clients connected to that session. + + 1mlist-commands0m + (alias: 1mlscm22m) + List the syntax of all commands supported by 1mtmux22m. + + 1mlist-sessions 22m[1m-F 4m22mformat24m] + (alias: 1mls22m) + List all sessions managed by the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mlock-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1mlockc22m) + Lock 4mtarget-client24m, see the 1mlock-server 22mcommand. + + 1mlock-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlocks22m) + Lock all clients attached to 4mtarget-session24m. + + 1mnew-session 22m[1m-AdDP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-s0m + 4msession-name24m] [1m-t 4m22mtarget-session24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] + [4mshell-command24m] + (alias: 1mnew22m) + Create a new session with name 4msession-name24m. + + The new session is attached to the current terminal unless 1m-d 22mis + given. 4mwindow-name24m and 4mshell-command24m are the name of and shell + command to execute in the initial window. If 1m-d 22mis used, 1m-x 22mand + 1m-y 22mspecify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(3) special characters are + saved and used for new windows in the new session. + + The 1m-A 22mflag makes 1mnew-session 22mbehave like 1mattach-session 22mif + 4msession-name24m already exists; in the case, 1m-D 22mbehaves like 1m-d 22mto + 1mattach-session22m. + + If 1m-t 22mis given, the new session is 4mgrouped24m with 4mtarget-session24m. + This means they share the same set of windows - all windows from + 4mtarget-session24m 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 1m-n 22mor 4mshell-command24m are invalid if 1m-t 22mis used. + + The 1m-P 22moption prints information about the new session after it + has been created. By default, it uses the format + `#{session_name}:' but a different format may be specified with + 1m-F22m. + + 1mrefresh-client 22m[1m-S22m] [1m-t 4m22mtarget-client24m] + (alias: 1mrefresh22m) + Refresh the current client if bound to a key, or a single client + if one is given with 1m-t22m. If 1m-S 22mis specified, only update the + client's status bar. + + 1mrename-session 22m[1m-t 4m22mtarget-session24m] 4mnew-name0m + (alias: 1mrename22m) + Rename the session to 4mnew-name24m. + + 1mshow-messages 22m[1m-IJT22m] [1m-t 4m22mtarget-client24m] + (alias: 1mshowmsgs22m) + Show client messages or server information. Any messages dis- + played on the status line are saved in a per-client message log, + up to a maximum of the limit set by the 4mmessage-limit24m server + option. With 1m-t22m, display the log for 4mtarget-client24m. 1m-I22m, 1m-J 22mand + 1m-T 22mshow debugging information about the running server, jobs and + terminals. + + 1msource-file 4m22mpath0m + (alias: 1msource22m) + Execute commands from 4mpath24m. + + 1mstart-server0m + (alias: 1mstart22m) + Start the 1mtmux 22mserver, if not already running, without creating + any sessions. + + 1msuspend-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1msuspendc22m) + Suspend a client by sending SIGTSTP (tty stop). + + 1mswitch-client 22m[1m-lnpr22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-session24m] + (alias: 1mswitchc22m) + Switch the current session for client 4mtarget-client24m to + 4mtarget-session24m. If 1m-l22m, 1m-n 22mor 1m-p 22mis used, the client is moved to + the last, next or previous session respectively. 1m-r 22mtoggles + whether a client is read-only (see the 1mattach-session 22mcommand). + +1mWINDOWS AND PANES0m + A 1mtmux 22mwindow 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 + 4mpaste24m 4mbuffer24m for later insertion into another window. This mode is + entered with the 1mcopy-mode 22mcommand, bound to `[' by default. It is also + entered when a command that produces output, such as 1mlist-keys22m, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the 1mmode-keys 22moption). The following keys are supported as appropriate + for the mode: + + 1mFunction vi emacs0m + Append selection A + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Copy to named buffer " + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump again ; ; + Jump again in reverse , , + Jump backward F F + Jump forward f f + Jump to backward T + Jump to forward t + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Other end of selection o + Paste buffer p C-y + Previous page C-b Page up + Previous space B + Previous word b M-b + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Select line V + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose characters C-t + + The next and previous word keys use space and the `-', `_' and `@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 4mword-separators24m 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. + + The jump commands enable quick movement within a line. For instance, + typing `f' followed by `/' will move the cursor to the next `/' character + on the current line. A `;' will then jump to the next occurrence. + + 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 `M-1 0 M-f' in emacs mode, and + `10w' in vi. + + Mode key bindings are defined in a set of named tables: 4mvi-edit24m and + 4memacs-edit24m for keys used when line editing at the command prompt; + 4mvi-choice24m and 4memacs-choice24m for keys used when choosing from lists (such + as produced by the 1mchoose-window 22mcommand); and 4mvi-copy24m and 4memacs-copy0m + used in copy mode. The tables may be viewed with the 1mlist-keys 22mcommand + and keys modified or removed with 1mbind-key 22mand 1munbind-key22m. One command + accepts an argument, 1mcopy-pipe22m, which copies the selection and pipes it + to a command. For example the following will bind `C-q' to copy the + selection into 4m/tmp24m as well as the paste buffer: + + bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the 1mcopy-mode 22mcommand is: + + 1mcopy-mode 22m[1m-u22m] [1m-t 4m22mtarget-pane24m] + Enter copy mode. The 1m-u 22moption scrolls one page up. + + Each window displayed by 1mtmux 22mmay be split into one or more 4mpanes24m; each + pane takes up a certain area of the display and is a separate terminal. + A window may be split into panes using the 1msplit-window 22mcommand. Windows + may be split horizontally (with the 1m-h 22mflag) or vertically. Panes may be + resized with the 1mresize-pane 22mcommand (bound to `C-up', `C-down' `C-left' + and `C-right' by default), the current pane may be changed with the + 1mselect-pane 22mcommand and the 1mrotate-window 22mand 1mswap-pane 22mcommands may be + used to swap panes without changing their position. Panes are numbered + beginning from zero in the order they are created. + + A number of preset 4mlayouts24m are available. These may be selected with the + 1mselect-layout 22mcommand or cycled with 1mnext-layout 22m(bound to `Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + 1meven-horizontal0m + Panes are spread out evenly from left to right across the window. + + 1meven-vertical0m + Panes are spread evenly from top to bottom. + + 1mmain-horizontal0m + 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 4mmain-pane-height24m window option to + specify the height of the top pane. + + 1mmain-vertical0m + Similar to 1mmain-horizontal 22mbut the large pane is placed on the + left and the others spread from top to bottom along the right. + See the 4mmain-pane-width24m window option. + + 1mtiled 22mPanes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, 1mselect-layout 22mmay be used to apply a previously used layout + - the 1mlist-windows 22mcommand displays the layout of each window in a form + suitable for use with 1mselect-layout22m. For example: + + $ 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} + + 1mtmux 22mautomatically 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. + + Commands related to windows and panes are as follows: + + 1mbreak-pane 22m[1m-dP22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mbreakp22m) + Break 4mtarget-pane24m off from its containing window to make it the + only pane in a new window. If 1m-d 22mis given, the new window does + not become the current window. The 1m-P 22moption prints information + about the new window after it has been created. By default, it + uses the format `#{session_name}:#{window_index}' but a different + format may be specified with 1m-F22m. + + 1mcapture-pane 22m[1m-aepPq22m] [1m-b 4m22mbuffer-name24m] [1m-E 4m22mend-line24m] [1m-S 4m22mstart-line24m] [1m-t0m + 4mtarget-pane24m] + (alias: 1mcapturep22m) + Capture the contents of a pane. If 1m-p 22mis given, the output goes + to stdout, otherwise to the buffer specified with 1m-b 22mor a new + buffer if omitted. If 1m-a 22mis given, the alternate screen is used, + and the history is not accessible. If no alternate screen + exists, an error will be returned unless 1m-q 22mis given. If 1m-e 22mis + given, the output includes escape sequences for text and back- + ground attributes. 1m-C 22malso escapes non-printable characters as + octal \xxx. 1m-J 22mjoins wrapped lines and preserves trailing spaces + at each line's end. 1m-P 22mcaptures only any output that the pane + has received that is the beginning of an as-yet incomplete escape + sequence. + + 1m-S 22mand 1m-E 22mspecify the starting and ending line numbers, zero is + the first line of the visible pane and negative numbers are lines + in the history. `-' to 1m-S 22mis the start of the history and to 1m-E0m + the end of the visible pane. The default is to capture only the + visible contents of the pane. + + 1mchoose-client 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + `%%' is replaced by the client pty(7) path in 4mtemplate24m and the + result executed as a command. If 4mtemplate24m is not given, "detach- + client -t '%%'" is used. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. This command works only if at least one client + is attached. + + 1mchoose-session 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, `%%' is + replaced by the session name in 4mtemplate24m and the result executed + as a command. If 4mtemplate24m is not given, "switch-client -t '%%'" + is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. This command works only if at least one client is + attached. + + 1mchoose-tree 22m[1m-suw22m] [1m-b 4m22msession-template24m] [1m-c 4m22mwindow-template24m] [1m-S 4m22mformat24m] + [1m-W 4m22mformat24m] [1m-t 4m22mtarget-window24m] + Put a window into tree choice mode, where either sessions or win- + dows may be selected interactively from a list. By default, win- + dows belonging to a session are indented to show their relation- + ship to a session. + + Note that the 1mchoose-window 22mand 1mchoose-session 22mcommands are wrap- + pers around 1mchoose-tree22m. + + If 1m-s 22mis given, will show sessions. If 1m-w 22mis given, will show + windows. + + By default, the tree is collapsed and sessions must be expanded + to windows with the right arrow key. The 1m-u 22moption will start + with all sessions expanded instead. + + If 1m-b 22mis given, will override the default session command. Note + that `%%' can be used and will be replaced with the session name. + The default option if not specified is "switch-client -t '%%'". + If 1m-c 22mis given, will override the default window command. Like + 1m-b22m, `%%' 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. + + If 1m-S 22mis given will display the specified format instead of the + default session format. If 1m-W 22mis given will display the speci- + fied format instead of the default window format. For the mean- + ing of the 1m-s 22mand 1m-w 22moptions, see the 4mFORMATS24m section. + + This command works only if at least one client is attached. + + 1mchoose-window 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, `%%' + is replaced by the session name and window index in 4mtemplate24m and + the result executed as a command. If 4mtemplate24m is not given, + "select-window -t '%%'" is used. For the meaning of the 1m-F 22mflag, + see the 4mFORMATS24m section. This command works only if at least one + client is attached. + + 1mdisplay-panes 22m[1m-t 4m22mtarget-client24m] + (alias: 1mdisplayp22m) + Display a visible indicator of each pane shown by 4mtarget-client24m. + See the 1mdisplay-panes-time22m, 1mdisplay-panes-colour22m, and + 1mdisplay-panes-active-colour 22msession options. While the indicator + is on screen, a pane may be selected with the `0' to `9' keys. + + 1mfind-window 22m[1m-CNT22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] 4mmatch-string0m + (alias: 1mfindw22m) + Search for the fnmatch(3) pattern 4mmatch-string24m in window names, + titles, and visible content (but not history). The flags control + matching behavior: 1m-C 22mmatches only visible window contents, 1m-N0m + matches only the window name and 1m-T 22mmatches only the window + title. The default is 1m-CNT22m. If only one window is matched, + it'll be automatically selected, otherwise a choice list is + shown. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + This command works only if at least one client is attached. + + 1mjoin-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mjoinp22m) + Like 1msplit-window22m, but instead of splitting 4mdst-pane24m and creating + a new pane, split it and move 4msrc-pane24m into the space. This can + be used to reverse 1mbreak-pane22m. The 1m-b 22moption causes 4msrc-pane24m to + be joined to left of or above 4mdst-pane24m. + + 1mkill-pane 22m[1m-a22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mkillp22m) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The 1m-a 22moption kills all but the + pane given with 1m-t22m. + + 1mkill-window 22m[1m-a22m] [1m-t 4m22mtarget-window24m] + (alias: 1mkillw22m) + Kill the current window or the window at 4mtarget-window24m, removing + it from any sessions to which it is linked. The 1m-a 22moption kills + all but the window given with 1m-t22m. + + 1mlast-pane 22m[1m-de22m] [1m-t 4m22mtarget-window24m] + (alias: 1mlastp22m) + Select the last (previously selected) pane. 1m-e 22menables or 1m-d0m + disables input to the pane. + + 1mlast-window 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlast22m) + Select the last (previously selected) window. If no + 4mtarget-session24m is specified, select the last window of the cur- + rent session. + + 1mlink-window 22m[1m-dk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mlinkw22m) + Link the window at 4msrc-window24m to the specified 4mdst-window24m. If + 4mdst-window24m is specified and no such window exists, the 4msrc-window0m + is linked there. If 1m-k 22mis given and 4mdst-window24m exists, it is + killed, otherwise an error is generated. If 1m-d 22mis given, the + newly linked window is not selected. + + 1mlist-panes 22m[1m-as22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget24m] + (alias: 1mlsp22m) + If 1m-a 22mis given, 4mtarget24m is ignored and all panes on the server are + listed. If 1m-s 22mis given, 4mtarget24m is a session (or the current ses- + sion). If neither is given, 4mtarget24m is a window (or the current + window). For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. + + 1mlist-windows 22m[1m-a22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsw22m) + If 1m-a 22mis given, list all windows on the server. Otherwise, list + windows in the current session or in 4mtarget-session24m. For the + meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mmove-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mmovep22m) + Like 1mjoin-pane22m, but 4msrc-pane24m and 4mdst-pane24m may belong to the same + window. + + 1mmove-window 22m[1m-rdk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mmovew22m) + This is similar to 1mlink-window22m, except the window at 4msrc-window0m + is moved to 4mdst-window24m. With 1m-r22m, all windows in the session are + renumbered in sequential order, respecting the 1mbase-index 22moption. + + 1mnew-window 22m[1m-adkP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-t0m + 4mtarget-window24m] [4mshell-command24m] + (alias: 1mneww22m) + Create a new window. With 1m-a22m, the new window is inserted at the + next index up from the specified 4mtarget-window24m, moving windows up + if necessary, otherwise 4mtarget-window24m is the new window location. + + If 1m-d 22mis given, the session does not make the new window the cur- + rent window. 4mtarget-window24m represents the window to be created; + if the target already exists an error is shown, unless the 1m-k0m + flag is used, in which case it is destroyed. 4mshell-command24m is + the command to execute. If 4mshell-command24m is not specified, the + value of the 1mdefault-command 22moption is used. 1m-c 22mspecifies the + working directory in which the new window is created. + + When the shell command completes, the window closes. See the + 1mremain-on-exit 22moption to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running 4minside24m 1mtmux22m. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The 1m-P 22moption prints information about the new window after it + has been created. By default, it uses the format + `#{session_name}:#{window_index}' but a different format may be + specified with 1m-F22m. + + 1mnext-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mnextl22m) + Move a window to the next layout and rearrange the panes to fit. + + 1mnext-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mnext22m) + Move to the next window in the session. If 1m-a 22mis used, move to + the next window with an alert. + + 1mpipe-pane 22m[1m-o22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mpipep22m) + Pipe any output sent by the program in 4mtarget-pane24m to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before 4mshell-command24m is executed. The + 4mshell-command24m string may contain the special character sequences + supported by the 1mstatus-left 22moption. If no 4mshell-command24m is + given, the current pipe (if any) is closed. + + The 1m-o 22moption only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + 1mprevious-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mprevl22m) + Move to the previous layout in the session. + + 1mprevious-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mprev22m) + Move to the previous window in the session. With 1m-a22m, move to the + previous window with an alert. + + 1mrename-window 22m[1m-t 4m22mtarget-window24m] 4mnew-name0m + (alias: 1mrenamew22m) + Rename the current window, or the window at 4mtarget-window24m if + specified, to 4mnew-name24m. + + 1mresize-pane 22m[1m-DLRUZ22m] [1m-t 4m22mtarget-pane24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] [4madjustment24m] + (alias: 1mresizep22m) + Resize a pane, up, down, left or right by 4madjustment24m with 1m-U22m, 1m-D22m, + 1m-L 22mor 1m-R22m, or to an absolute size with 1m-x 22mor 1m-y22m. The 4madjustment0m + is given in lines or cells (the default is 1). + + With 1m-Z22m, the active pane is toggled between zoomed (occupying the + whole of the window) and unzoomed (its normal position in the + layout). + + 1mrespawn-pane 22m[1m-k22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mrespawnp22m) + Reactivate a pane in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless 1m-k 22mis given, in which case any + existing command is killed. + + 1mrespawn-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] [4mshell-command24m] + (alias: 1mrespawnw22m) + Reactivate a window in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the window was created is executed. The + window must be already inactive, unless 1m-k 22mis given, in which + case any existing command is killed. + + 1mrotate-window 22m[1m-DU22m] [1m-t 4m22mtarget-window24m] + (alias: 1mrotatew22m) + Rotate the positions of the panes within a window, either upward + (numerically lower) with 1m-U 22mor downward (numerically higher). + + 1mselect-layout 22m[1m-np22m] [1m-t 4m22mtarget-window24m] [4mlayout-name24m] + (alias: 1mselectl22m) + Choose a specific layout for a window. If 4mlayout-name24m is not + given, the last preset layout used (if any) is reapplied. 1m-n 22mand + 1m-p 22mare equivalent to the 1mnext-layout 22mand 1mprevious-layout 22mcom- + mands. + + 1mselect-pane 22m[1m-DdeLlRU22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mselectp22m) + Make pane 4mtarget-pane24m the active pane in window 4mtarget-window24m. + If one of 1m-D22m, 1m-L22m, 1m-R22m, or 1m-U 22mis used, respectively the pane below, + to the left, to the right, or above the target pane is used. 1m-l0m + is the same as using the 1mlast-pane 22mcommand. 1m-e 22menables or 1m-d0m + disables input to the pane. + + 1mselect-window 22m[1m-lnpT22m] [1m-t 4m22mtarget-window24m] + (alias: 1mselectw22m) + Select the window at 4mtarget-window24m. 1m-l22m, 1m-n 22mand 1m-p 22mare equivalent + to the 1mlast-window22m, 1mnext-window 22mand 1mprevious-window 22mcommands. If + 1m-T 22mis given and the selected window is already the current win- + dow, the command behaves like 1mlast-window22m. + + 1msplit-window 22m[1m-bdhvP22m] [1m-c 4m22mstart-directory24m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-t0m + 4mtarget-pane24m] [4mshell-command24m] [1m-F 4m22mformat24m] + (alias: 1msplitw22m) + Create a new pane by splitting 4mtarget-pane24m: 1m-h 22mdoes a horizontal + split and 1m-v 22ma vertical split; if neither is specified, 1m-v 22mis + assumed. The 1m-l 22mand 1m-p 22moptions specify the size of the new pane + in lines (for vertical split) or in cells (for horizontal split), + or as a percentage, respectively. The 1m-b 22moption causes the new + pane to be created to the left of or above 4mtarget-pane24m. All + other options have the same meaning as for the 1mnew-window 22mcom- + mand. + + 1mswap-pane 22m[1m-dDU22m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mswapp22m) + Swap two panes. If 1m-U 22mis used and no source pane is specified + with 1m-s22m, 4mdst-pane24m is swapped with the previous pane (before it + numerically); 1m-D 22mswaps with the next pane (after it numerically). + 1m-d 22minstructs 1mtmux 22mnot to change the active pane. + + 1mswap-window 22m[1m-d22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mswapw22m) + This is similar to 1mlink-window22m, except the source and destination + windows are swapped. It is an error if no window exists at + 4msrc-window24m. + + 1munlink-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] + (alias: 1munlinkw22m) + Unlink 4mtarget-window24m. Unless 1m-k 22mis given, a window may be + unlinked only if it is linked to multiple sessions - windows may + not be linked to no sessions; if 1m-k 22mis specified and the window + is linked to only one session, it is unlinked and destroyed. + +1mKEY BINDINGS0m + 1mtmux 22mallows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example `A' to + `Z'). Ctrl keys may be prefixed with `C-' or `^', and Alt (meta) with + `M-'. In addition, the following special key names are accepted: 4mUp24m, + 4mDown24m, 4mLeft24m, 4mRight24m, 4mBSpace24m, 4mBTab24m, 4mDC24m (Delete), 4mEnd24m, 4mEnter24m, 4mEscape24m, 4mF124m to + 4mF1224m, 4mHome24m, 4mIC24m (Insert), 4mNPage/PageDown/PgDn24m, 4mPPage/PageUp/PgUp24m, 4mSpace24m, + and 4mTab24m. Note that to bind the `"' or `'' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + 1mbind-key 22m[1m-cnr22m] [1m-t 4m22mmode-table24m] 4mkey24m 4mcommand24m [4marguments24m] + (alias: 1mbind22m) + Bind key 4mkey24m to 4mcommand24m. By default (without 1m-t22m) the primary key + bindings are modified (those normally activated with the prefix + key); in this case, if 1m-n 22mis specified, it is not necessary to + use the prefix key, 4mcommand24m is bound to 4mkey24m alone. The 1m-r 22mflag + indicates this key may repeat, see the 1mrepeat-time 22moption. + + If 1m-t 22mis present, 4mkey24m is bound in 4mmode-table24m: the binding for + command mode with 1m-c 22mor for normal mode without. To view the + default bindings and possible commands, see the 1mlist-keys 22mcom- + mand. + + 1mlist-keys 22m[1m-t 4m22mkey-table24m] + (alias: 1mlsk22m) + List all key bindings. Without 1m-t 22mthe primary key bindings - + those executed when preceded by the prefix key - are printed. + + With 1m-t22m, the key bindings in 4mkey-table24m are listed; this may be + one of: 4mvi-edit24m, 4memacs-edit24m, 4mvi-choice24m, 4memacs-choice24m, 4mvi-copy24m or + 4memacs-copy24m. + + 1msend-keys 22m[1m-lR22m] [1m-t 4m22mtarget-pane24m] 4mkey24m 4m...0m + (alias: 1msend22m) + Send a key or keys to a window. Each argument 4mkey24m is the name of + the key (such as `C-a' or `npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. The + 1m-l 22mflag disables key name lookup and sends the keys literally. + All arguments are sent sequentially from first to last. The 1m-R0m + flag causes the terminal state to be reset. + + 1msend-prefix 22m[1m-222m] [1m-t 4m22mtarget-pane24m] + Send the prefix key, or with 1m-2 22mthe secondary prefix key, to a + window as if it was pressed. + + 1munbind-key 22m[1m-acn22m] [1m-t 4m22mmode-table24m] 4mkey0m + (alias: 1munbind22m) + Unbind the command bound to 4mkey24m. Without 1m-t 22mthe primary key + bindings are modified; in this case, if 1m-n 22mis specified, the com- + mand bound to 4mkey24m without a prefix (if any) is removed. If 1m-a 22mis + present, all key bindings are removed. + + If 1m-t 22mis present, 4mkey24m in 4mmode-table24m is unbound: the binding for + command mode with 1m-c 22mor for normal mode without. + +1mOPTIONS0m + The appearance and behaviour of 1mtmux 22mmay be modified by changing the + value of various options. There are three types of option: 4mserver0m + 4moptions24m, 4msession24m 4moptions24m and 4mwindow24m 4moptions24m. + + The 1mtmux 22mserver has a set of global options which do not apply to any + particular window or session. These are altered with the 1mset-option -s0m + command, or displayed with the 1mshow-options -s 22mcommand. + + 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 1mset-option0m + command and may be listed with the 1mshow-options 22mcommand. The available + server and session options are listed under the 1mset-option 22mcommand. + + 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 inher- + ited. Window options are altered with the 1mset-window-option 22mcommand and + can be listed with the 1mshow-window-options 22mcommand. All window options + are documented with the 1mset-window-option 22mcommand. + + 1mtmux 22malso supports user options which are prefixed with a `@'. User + options may have any name, so long as they are prefixed with `@', and be + set to any string. For example + + $ tmux setw -q @foo "abc123" + $ tmux showw -v @foo + abc123 + + Commands which set options are as follows: + + 1mset-option 22m[1m-agoqsuw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1mset22m) + Set a window option with 1m-w 22m(equivalent to the 1mset-window-option0m + command), a server option with 1m-s22m, otherwise a session option. + + If 1m-g 22mis specified, the global session or window option is set. + The 1m-u 22mflag unsets an option, so a session inherits the option + from the global options. It is not possible to unset a global + option. + + The 1m-o 22mflag prevents setting an option that is already set. + + The 1m-q 22mflag suppresses errors about unknown options. + + With 1m-a22m, and if the option expects a string or a style, 4mvalue24m is + appended to the existing setting. For example: + + set -g status-left "foo" + set -ag status-left "bar" + + Will result in `foobar'. And: + + set -g status-style "bg=red" + set -ag status-style "fg=blue" + + Will result in a red background 4mand24m blue foreground. Without 1m-a22m, + the result would be the default background and a blue foreground. + + Available window options are listed under 1mset-window-option22m. + + 4mvalue24m depends on the option and may be a number, a string, or a + flag (on, off, or omitted to toggle). + + Available server options are: + + 1mbuffer-limit 4m22mnumber0m + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + 1mescape-time 4m22mtime0m + Set the time in milliseconds for which 1mtmux 22mwaits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + 1mexit-unattached 22m[1mon 22m| 1moff22m] + If enabled, the server will exit when there are no + attached clients. + + 1mfocus-events 22m[1mon 22m| 1moff22m] + When enabled, focus events are requested from the termi- + nal if supported and passed through to applications run- + ning in 1mtmux22m. Attached clients should be detached and + attached again after changing this option. + + 1mmessage-limit 4m22mnumber0m + Set the number of error or information messages to save + in the message log for each client. The default is 100. + + 1mset-clipboard 22m[1mon 22m| 1moff22m] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an 4mMs24m entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + 1mterminal-overrides 4m22mstring0m + Contains a list of entries which override terminal + descriptions read using terminfo(5). 4mstring24m is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of 4mname=value24m entries. + + For example, to set the `clear' terminfo(5) entry to + `\e[H\e[2J' for all terminal types and the `dch1' entry + to `\e[P' for the `rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the `colors' entry for terminals which support 256 + colours: + + "*256col*:colors=256,xterm*:XT" + + Available session options are: + + 1massume-paste-time 4m22mmilliseconds0m + If keys are entered faster than one in 4mmilliseconds24m, they + are assumed to have been pasted rather than typed and + 1mtmux 22mkey bindings are not processed. The default is one + millisecond and zero disables. + + 1mbase-index 4m22mindex0m + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + 1mbell-action 22m[1many 22m| 1mnone 22m| 1mcurrent22m] + Set action on window bell. 1many 22mmeans a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, 1mnone 22mmeans all bells are ignored and + 1mcurrent 22mmeans only bells in windows other than the cur- + rent window are ignored. + + 1mbell-on-alert 22m[1mon 22m| 1moff22m] + If on, ring the terminal bell when an alert occurs. + + 1mdefault-command 4m22mshell-command0m + Set the command used for new windows (if not specified + when the window is created) to 4mshell-command24m, which may + be any sh(1) command. The default is an empty string, + which instructs 1mtmux 22mto create a login shell using the + value of the 1mdefault-shell 22moption. + + 1mdefault-shell 4m22mpath0m + Specify the default shell. This is used as the login + shell for new windows when the 1mdefault-command 22moption is + set to empty, and must be the full path of the exe- + cutable. When started 1mtmux 22mtries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or 4m/bin/sh24m. + This option should be configured when 1mtmux 22mis used as a + login shell. + + 1mdefault-terminal 4m22mterminal0m + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For 1mtmux 22mto work correctly, this 4mmust24m be set to + `screen' or a derivative of it. + + 1mdestroy-unattached 22m[1mon 22m| 1moff22m] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + 1mdetach-on-destroy 22m[1mon 22m| 1moff22m] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + 1mdisplay-panes-active-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicator for the active pane. + + 1mdisplay-panes-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicators for inactive panes. + + 1mdisplay-panes-time 4m22mtime0m + Set the time in milliseconds for which the indicators + shown by the 1mdisplay-panes 22mcommand appear. + + 1mdisplay-time 4m22mtime0m + Set the amount of time for which status line messages and + other on-screen indicators are displayed. 4mtime24m is in + milliseconds. + + 1mhistory-limit 4m22mlines0m + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + 1mlock-after-time 4m22mnumber0m + Lock the session (like the 1mlock-session 22mcommand) after + 4mnumber24m seconds of inactivity, or the entire server (all + sessions) if the 1mlock-server 22moption is set. The default + is not to lock (set to 0). + + 1mlock-command 4m22mshell-command0m + Command to run when locking each client. The default is + to run lock(1) with 1m-np22m. + + 1mlock-server 22m[1mon 22m| 1moff22m] + If this option is 1mon 22m(the default), instead of each ses- + sion locking individually as each has been idle for + 1mlock-after-time22m, the entire server will lock after 4mall0m + sessions would have locked. This has no effect as a ses- + sion option; it must be set as a global option. + + 1mmessage-command-style 4m22mstyle0m + Set status line message command style, where 4mstyle24m is a + comma-separated list of characteristics to be specified. + + These may be `bg=colour' to set the background colour, + `fg=colour' to set the foreground colour, and a list of + attributes as specified below. + + The colour is one of: 1mblack22m, 1mred22m, 1mgreen22m, 1myellow22m, 1mblue22m, + 1mmagenta22m, 1mcyan22m, 1mwhite22m, aixterm bright variants (if sup- + ported: 1mbrightred22m, 1mbrightgreen22m, and so on), 1mcolour0 22mto + 1mcolour255 22mfrom the 256-colour set, 1mdefault22m, or a hexadec- + imal RGB string such as `#ffffff', which chooses the + closest match from the default 256-colour set. + + The attributes is either 1mnone 22mor a comma-delimited list + of one or more of: 1mbright 22m(or 1mbold22m), 1mdim22m, 1munderscore22m, + 1mblink22m, 1mreverse22m, 1mhidden22m, or 1mitalics22m, to turn an attribute + on, or an attribute prefixed with `no' to turn one off. + + Examples are: + + fg=yellow,bold,underscore,blink + bg=black,fg=default,noreverse + + With the 1m-a 22mflag to the 1mset-option 22mcommand the new style + is added otherwise the existing style is replaced. + + 1mmessage-style 4m22mstyle0m + Set status line message style. For how to specify 4mstyle24m, + see the 1mmessage-command-style 22moption. + + 1mmouse-resize-pane 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures the mouse and allows panes to be + resized by dragging on their borders. + + 1mmouse-select-pane 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures 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. + + 1mmouse-select-window 22m[1mon 22m| 1moff22m] + If on, clicking the mouse on a window name in the status + line will select that window. + + 1mmouse-utf8 22m[1mon 22m| 1moff22m] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + 1mprefix 4m22mkey0m + Set the key accepted as a prefix key. + + 1mprefix2 4m22mkey0m + Set a secondary key accepted as a prefix key. + + 1mrenumber-windows 22m[1mon 22m| 1moff22m] + If on, when a window is closed in a session, automati- + cally renumber the other windows in numerical order. + This respects the 1mbase-index 22moption if it has been set. + If off, do not renumber the windows. + + 1mrepeat-time 4m22mtime0m + Allow multiple commands to be entered without pressing + the prefix-key again in the specified 4mtime24m milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the 1m-r 22mflag to 1mbind-key22m. Repeat + is enabled for the default keys bound to the 1mresize-pane0m + command. + + 1mset-remain-on-exit 22m[1mon 22m| 1moff22m] + Set the 1mremain-on-exit 22mwindow 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 + 1mrespawn-window 22mcommand to reactivate such a window, or + the 1mkill-window 22mcommand to destroy it. + + 1mset-titles 22m[1mon 22m| 1moff22m] + Attempt to set the client terminal title using the 4mtsl0m + and 4mfsl24m terminfo(5) entries if they exist. 1mtmux 22mautomat- + ically sets these to the \e]2;...\007 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. + + 1mset-titles-string 4m22mstring0m + String used to set the window title if 1mset-titles 22mis on. + Character sequences are replaced as for the 1mstatus-left0m + option. + + 1mstatus 22m[1mon 22m| 1moff22m] + Show or hide the status line. + + 1mstatus-interval 4m22minterval0m + Update the status bar every 4minterval24m seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + 1mstatus-justify 22m[1mleft 22m| 1mcentre 22m| 1mright22m] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + 1mstatus-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string `vi'. + + 1mstatus-left 4m22mstring0m + Display 4mstring24m (by default the session name) to the left + of the status bar. 4mstring24m will be passed through + strftime(3) and formats (see 4mFORMATS24m) will be expanded. + It may also contain any of the following special charac- + ter sequences: + + 1mCharacter pair Replaced with0m + #(shell-command) First line of the command's + output + #[attributes] Colour or attribute change + ## A literal `#' + + The #(shell-command) form executes `shell-command' and + inserts the first line of its output. Note that shell + commands are only executed once at the interval specified + by the 1mstatus-interval 22moption: if the status line is + redrawn in the meantime, the previous result is used. + Shell commands are executed with the 1mtmux 22mglobal environ- + ment set (see the 4mENVIRONMENT24m section). + + For details on how the names and titles can be set see + the 4mNAMES24m 4mAND24m 4mTITLES24m section. For a list of allowed + attributes see the 1mmessage-command-style 22moption. + + Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + By default, UTF-8 in 4mstring24m is not interpreted, to enable + UTF-8, use the 1mstatus-utf8 22moption. + + The default is `[#S] '. + + 1mstatus-left-length 4m22mlength0m + Set the maximum 4mlength24m of the left component of the sta- + tus bar. The default is 10. + + 1mstatus-left-style 4m22mstyle0m + Set the style of the left part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-position 22m[1mtop 22m| 1mbottom22m] + Set the position of the status line. + + 1mstatus-right 4m22mstring0m + Display 4mstring24m 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 1mstatus-left22m, 4mstring0m + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the 1mstatus-utf80m + option. + + 1mstatus-right-length 4m22mlength0m + Set the maximum 4mlength24m of the right component of the sta- + tus bar. The default is 40. + + 1mstatus-right-style 4m22mstyle0m + Set the style of the right part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-style 4m22mstyle0m + Set status line style. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. + + 1mstatus-utf8 22m[1mon 22m| 1moff22m] + Instruct 1mtmux 22mto treat top-bit-set characters in the + 1mstatus-left 22mand 1mstatus-right 22mstrings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + 1mupdate-environment 4m22mvariables0m + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 1m-r 22mwas given to the 1mset-environment0m + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + 1mvisual-activity 22m[1mon 22m| 1moff22m] + If on, display a status line message when activity occurs + in a window for which the 1mmonitor-activity 22mwindow option + is enabled. + + 1mvisual-bell 22m[1mon 22m| 1moff22m] + 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 1mbell-action0m + option. + + 1mvisual-silence 22m[1mon 22m| 1moff22m] + If 1mmonitor-silence 22mis enabled, prints a message after the + interval has expired on a given window. + + 1mword-separators 4m22mstring0m + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ` -_@'. + + 1mset-window-option 22m[1m-agoqu22m] [1m-t 4m22mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1msetw22m) + Set a window option. The 1m-a22m, 1m-g22m, 1m-o22m, 1m-q 22mand 1m-u 22mflags work simi- + larly to the 1mset-option 22mcommand. + + Supported window options are: + + 1maggressive-resize 22m[1mon 22m| 1moff22m] + Aggressively resize the chosen window. This means that + 1mtmux 22mwill 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 SIGWINCH and poor for interactive programs + such as shells. + + 1mallow-rename 22m[1mon 22m| 1moff22m] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + 1malternate-screen 22m[1mon 22m| 1moff22m] + This option configures whether programs running inside + 1mtmux 22mmay use the terminal alternate screen feature, which + allows the 4msmcup24m and 4mrmcup24m 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. + + 1mautomatic-rename 22m[1mon 22m| 1moff22m] + Control automatic window renaming. When this setting is + enabled, 1mtmux 22mwill rename the window automatically using + the format specified by 1mautomatic-rename-format22m. This + flag is automatically disabled for an individual window + when a name is specified at creation with 1mnew-window 22mor + 1mnew-session22m, or later with 1mrename-window22m, or with a ter- + minal escape sequence. It may be switched off globally + with: + + set-window-option -g automatic-rename off + + 1mautomatic-rename-format 4m22mformat0m + The format (see 4mFORMATS24m) used when the 1mautomatic-rename0m + option is enabled. + + 1mc0-change-interval 4m22minterval0m + 1mc0-change-trigger 4m22mtrigger0m + These two options configure a simple form of rate limit- + ing for a pane. If 1mtmux 22msees more than 4mtrigger24m 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 4minterval24m milliseconds. This + helps to prevent fast output (such as yes(1)) overwhelm- + ing the terminal. The default is a trigger of 250 and an + interval of 100. A trigger of zero disables the rate + limiting. + + 1mclock-mode-colour 4m22mcolour0m + Set clock colour. + + 1mclock-mode-style 22m[1m12 22m| 1m2422m] + Set clock hour format. + + 1mforce-height 4m22mheight0m + 1mforce-width 4m22mwidth0m + Prevent 1mtmux 22mfrom resizing a window to greater than 4mwidth0m + or 4mheight24m. A value of zero restores the default unlim- + ited setting. + + 1mmain-pane-height 4m22mheight0m + 1mmain-pane-width 4m22mwidth0m + Set the width or height of the main (left or top) pane in + the 1mmain-horizontal 22mor 1mmain-vertical 22mlayouts. + + 1mmode-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in copy and choice + modes. As with the 1mstatus-keys 22moption, the default is + emacs, unless VISUAL or EDITOR contains `vi'. + + 1mmode-mouse 22m[1mon 22m| 1moff 22m| 1mcopy-mode22m] + 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 4mcopy-mode24m, + the mouse behaves as set to on, but cannot be used to + enter copy mode. + + 1mmode-style 4m22mstyle0m + Set window modes style. For how to specify 4mstyle24m, see + the 1mmessage-command-style 22moption. + + 1mmonitor-activity 22m[1mon 22m| 1moff22m] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + 1mmonitor-silence 22m[1minterval22m] + Monitor for silence (no activity) in the window within + 1minterval 22mseconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + 1mother-pane-height 4m22mheight0m + Set the height of the other panes (not the main pane) in + the 1mmain-horizontal 22mlayout. If this option is set to 0 + (the default), it will have no effect. If both the + 1mmain-pane-height 22mand 1mother-pane-height 22moptions are set, + the main pane will grow taller to make the other panes + the specified height, but will never shrink to do so. + + 1mother-pane-width 4m22mwidth0m + Like 1mother-pane-height22m, but set the width of other panes + in the 1mmain-vertical 22mlayout. + + 1mpane-active-border-style 4m22mstyle0m + Set the pane border style for the currently active pane. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. Attributes are ignored. + + 1mpane-base-index 4m22mindex0m + Like 1mbase-index22m, but set the starting index for pane num- + bers. + + 1mpane-border-style 4m22mstyle0m + Set the pane border style for panes aside from the active + pane. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. Attributes are ignored. + + 1mremain-on-exit 22m[1mon 22m| 1moff22m] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the 1mrespawn-window 22mcommand. + + 1msynchronize-panes 22m[1mon 22m| 1moff22m] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + 1mutf8 22m[1mon 22m| 1moff22m] + Instructs 1mtmux 22mto expect UTF-8 sequences to appear in + this window. + + 1mwindow-status-activity-style 4m22mstyle0m + Set status line style for windows with an activity alert. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-bell-style 4m22mstyle0m + Set status line style for windows with a bell alert. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-current-format 4m22mstring0m + Like 4mwindow-status-format24m, but is the format used when + the window is the current window. + + 1mwindow-status-current-style 4m22mstyle0m + Set status line style for the currently active window. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-format 4m22mstring0m + Set the format in which the window is displayed in the + status line window list. See the 4mstatus-left24m option for + details of special character sequences available. The + default is `#I:#W#F'. + + 1mwindow-status-last-style 4m22mstyle0m + Set status line style for the last active window. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-separator 4m22mstring0m + Sets the separator drawn between windows in the status + line. The default is a single space character. + + 1mwindow-status-style 4m22mstyle0m + Set status line style for a single window. For how to + specify 4mstyle24m, see the 1mmessage-command-style 22moption. + + 1mxterm-keys 22m[1mon 22m| 1moff22m] + If this option is set, 1mtmux 22mwill generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + 1mwrap-search 22m[1mon 22m| 1moff22m] + If this option is set, searches will wrap around the end + of the pane contents. The default is on. + + 1mshow-options 22m[1m-gqsvw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] [4moption24m] + (alias: 1mshow22m) + Show the window options (or a single window option if given) with + 1m-w 22m(equivalent to 1mshow-window-options22m), the server options with + 1m-s22m, otherwise the session options for 4mtarget24m 4msession24m. Global + session or window options are listed if 1m-g 22mis used. 1m-v 22mshows + only the option value, not the name. If 1m-q 22mis set, no error will + be returned if 4moption24m is unset. + + 1mshow-window-options 22m[1m-gv22m] [1m-t 4m22mtarget-window24m] [4moption24m] + (alias: 1mshoww22m) + List the window options or a single option for 4mtarget-window24m, or + the global window options if 1m-g 22mis used. 1m-v 22mshows only the + option value, not the name. + +1mFORMATS0m + Certain commands accept the 1m-F 22mflag with a 4mformat24m argument. This is a + string which controls the output format of the command. Replacement + variables are enclosed in `#{' and `}', for example `#{session_name}'. + The possible variables are listed in the table below, or the name of a + 1mtmux 22moption may be used for an option's value. Some variables have a + shorter alias such as `#S', and `##' is replaced by a single `#'. + + Conditionals are available by prefixing with `?' 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 `#{?session_attached,attached,not attached}' will include the + string `attached' if the session is attached and the string `not + attached' if it is unattached, or `#{?automatic-rename,yes,no}' will + include `yes' if 1mautomatic-rename 22mis enabled, or `no' if not. A limit + may be placed on the length of the resultant string by prefixing it by an + `=', a number and a colon, so `#{=10:pane_title}' will include at most + the first 10 characters of the pane title. + + The following variables are available, where appropriate: + + 1mVariable name Alias Replaced with0m + alternate_on If pane is in alternate screen + alternate_saved_x Saved cursor X in alternate screen + alternate_saved_y Saved cursor Y in alternate screen + buffer_sample Sample of start of buffer + buffer_size Size of the specified buffer in bytes + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_height Height of client + client_last_session Name of the client's last session + client_prefix 1 if prefix key has been pressed + client_readonly 1 if client is readonly + client_session Name of the client's session + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + cursor_flag Pane cursor flag + cursor_x Cursor X position in pane + cursor_y Cursor Y position in pane + history_bytes Number of bytes in window history + history_limit Maximum window history lines + history_size Size of history in bytes + host #H Hostname of local host + host_short #h Hostname of local host (no domain name) + insert_flag Pane insert flag + keypad_cursor_flag Pane keypad cursor flag + keypad_flag Pane keypad flag + line Line number in the list + mouse_any_flag Pane mouse any flag + mouse_button_flag Pane mouse button flag + mouse_standard_flag Pane mouse standard flag + mouse_utf8_flag Pane mouse UTF-8 flag + pane_active 1 if active pane + pane_bottom Bottom of pane + pane_current_command Current command if available + pane_current_path Current path if available + pane_dead 1 if pane is dead + pane_dead_status Exit status of process in dead pane + pane_height Height of pane + pane_id #D Unique pane ID + pane_in_mode If pane is in a mode + pane_input_off If input to pane is disabled + pane_index #P Index of pane + pane_left Left of pane + pane_pid PID of first process in pane + pane_right Right of pane + pane_start_command Command pane started with + pane_synchronized If pane is synchronized + pane_tabs Pane tab positions + pane_title #T Title of pane + pane_top Top of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + saved_cursor_x Saved cursor X in pane + saved_cursor_y Saved cursor Y in pane + scroll_region_lower Bottom of scroll region in pane + scroll_region_upper Top of scroll region in pane + session_attached Number of clients session is attached to + session_created Integer time session created + session_created_string String time session created + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_id Unique session ID + session_many_attached 1 if multiple clients attached + session_name #S Name of session + session_width Width of session + session_windows Number of windows in session + window_active 1 if window active + window_activity_flag 1 if window has activity alert + window_bell_flag 1 if window has bell + window_find_matches Matched data from the find-window + window_flags #F Window flags + window_height Height of window + window_id Unique window ID + window_index #I Index of window + window_last_flag 1 if window is the last used + window_layout Window layout description + window_name #W Name of window + window_panes Number of panes in window + window_silence_flag 1 if window has silence alert + window_width Width of window + window_zoomed_flag 1 if window is zoomed + wrap_flag Pane wrap flag + +1mNAMES AND TITLES0m + 1mtmux 22mdistinguishes 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 1mtmux 22midentifier 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 1mtmux22m. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. 1mtmux 22mitself may set + the title of the terminal in which the client is running, see the + 1mset-titles 22moption. + + A session's name is set with the 1mnew-session 22mand 1mrename-session 22mcommands. + A window's name is set with one of: + + 1. A command argument (such as 1m-n 22mfor 1mnew-window 22mor 1mnew-session22m). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the 1mautomatic-rename 22moption. + + 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: + + $ printf '\033]2;My Title\033\\' + +1mENVIRONMENT0m + When the server is started, 1mtmux 22mcopies the environment into the 4mglobal0m + 4menvironment24m; in addition, each session has a 4msession24m 4menvironment24m. 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. + + The 1mupdate-environment 22msession option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. 1mtmux 22malso initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of `screen'. + + Commands to alter and view the environment are: + + 1mset-environment 22m[1m-gru22m] [1m-t 4m22mtarget-session24m] 4mname24m [4mvalue24m] + (alias: 1msetenv22m) + Set or unset an environment variable. If 1m-g 22mis used, the change + is made in the global environment; otherwise, it is applied to + the session environment for 4mtarget-session24m. The 1m-u 22mflag unsets a + variable. 1m-r 22mindicates the variable is to be removed from the + environment before starting a new process. + + 1mshow-environment 22m[1m-g22m] [1m-t 4m22mtarget-session24m] [4mvariable24m] + (alias: 1mshowenv22m) + Display the environment for 4mtarget-session24m or the global environ- + ment with 1m-g22m. If 4mvariable24m is omitted, all variables are shown. + Variables removed from the environment are prefixed with `-'. + +1mSTATUS LINE0m + 1mtmux 22mincludes 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 1mstatus 22msession 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the 1mstatus-left22m, 1mstatus-left-length22m, 1mstatus-right22m, + and 1mstatus-right-length 22moptions 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 4mwindow-status-format24m and + 4mwindow-status-current-format24m options. The flag is one of the following + symbols appended to the window name: + + 1mSymbol Meaning0m + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + ~ The window has been silent for the monitor-silence + interval. + Z The window's active pane is zoomed. + + The # symbol relates to the 1mmonitor-activity 22mwindow option. The window + name is printed in inverted colours if an alert (bell, activity or + silence) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the 1mstatus-style 22msession option and individual + windows using the 1mwindow-status-style 22mwindow option. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the 1mstatus-interval 22msession option. + + Commands related to the status line are as follows: + + 1mcommand-prompt 22m[1m-I 4m22minputs24m] [1m-p 4m22mprompts24m] [1m-t 4m22mtarget-client24m] [4mtemplate24m] + Open the command prompt in a client. This may be used from + inside 1mtmux 22mto execute commands interactively. + + If 4mtemplate24m is specified, it is used as the command. If present, + 1m-I 22mis a comma-separated list of the initial text for each prompt. + If 1m-p 22mis given, 4mprompts24m is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from 4mtemplate24m if it is present, or `:' if + not. + + Both 4minputs24m and 4mprompts24m may contain the special character + sequences supported by the 1mstatus-left 22moption. + + Before the command is executed, the first occurrence of the + string `%%' and all occurrences of `%1' are replaced by the + response to the first prompt, the second `%%' and all `%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + (`%1' to `%9'). + + 1mconfirm-before 22m[1m-p 4m22mprompt24m] [1m-t 4m22mtarget-client24m] 4mcommand0m + (alias: 1mconfirm22m) + Ask for confirmation before executing 4mcommand24m. If 1m-p 22mis given, + 4mprompt24m is the prompt to display; otherwise a prompt is con- + structed from 4mcommand24m. It may contain the special character + sequences supported by the 1mstatus-left 22moption. + + This command works only from inside 1mtmux22m. + + 1mdisplay-message 22m[1m-p22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-pane24m] [4mmessage24m] + (alias: 1mdisplay22m) + Display a message. If 1m-p 22mis given, the output is printed to std- + out, otherwise it is displayed in the 4mtarget-client24m status line. + The format of 4mmessage24m is described in the 4mFORMATS24m section; infor- + mation is taken from 4mtarget-pane24m if 1m-t 22mis given, otherwise the + active pane for the session attached to 4mtarget-client24m. + +1mBUFFERS0m + 1mtmux 22mmaintains a set of named 4mpaste24m 4mbuffers24m. Each buffer may be either + explicitly or automatically named. Explicitly named buffers are named + when created with the 1mset-buffer 22mor 1mload-buffer 22mcommands, or by renaming + an automatically named buffer with 1mset-buffer -n22m. Automatically named + buffers are given a name such as `buffer0001', `buffer0002' and so on. + When the 1mbuffer-limit 22moption is reached, the oldest automatically named + buffer is deleted. Explicitly named are not subject to 1mbuffer-limit 22mand + may be deleted with 1mdelete-buffer 22mcommand. + + Buffers may be added using 1mcopy-mode 22mor the 1mset-buffer 22mand 1mload-buffer0m + commands, and pasted into a window using the 1mpaste-buffer 22mcommand. If a + buffer command is used and no buffer is specified, the most recently + added automatically named buffer is assumed. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + 1mhistory-limit 22moption (see the 1mset-option 22mcommand above). + + The buffer commands are as follows: + + 1mchoose-buffer 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, `%%' + is replaced by the buffer name in 4mtemplate24m and the result exe- + cuted as a command. If 4mtemplate24m is not given, "paste-buffer -b + '%%'" is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS0m + section. This command works only if at least one client is + attached. + + 1mclear-history 22m[1m-t 4m22mtarget-pane24m] + (alias: 1mclearhist22m) + Remove and free the history for the specified pane. + + 1mdelete-buffer 22m[1m-b 4m22mbuffer-name24m] + (alias: 1mdeleteb22m) + Delete the buffer named 4mbuffer-name24m, or the most recently added + automatically named buffer if not specified. + + 1mlist-buffers 22m[1m-F 4m22mformat24m] + (alias: 1mlsb22m) + List the global buffers. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. + + 1mload-buffer 22m[1m-b 4m22mbuffer-name24m] 4mpath0m + (alias: 1mloadb22m) + Load the contents of the specified paste buffer from 4mpath24m. + + 1mpaste-buffer 22m[1m-dpr22m] [1m-b 4m22mbuffer-name24m] [1m-s 4m22mseparator24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mpasteb22m) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With 1m-d22m, also + delete the paste buffer. When output, any linefeed (LF) charac- + ters in the paste buffer are replaced with a separator, by + default carriage return (CR). A custom separator may be speci- + fied using the 1m-s 22mflag. The 1m-r 22mflag means to do no replacement + (equivalent to a separator of LF). If 1m-p 22mis specified, paste + bracket control codes are inserted around the buffer if the + application has requested bracketed paste mode. + + 1msave-buffer 22m[1m-a22m] [1m-b 4m22mbuffer-name24m] 4mpath0m + (alias: 1msaveb22m) + Save the contents of the specified paste buffer to 4mpath24m. The 1m-a0m + option appends to rather than overwriting the file. + + 1mset-buffer 22m[1m-a22m] [1m-b 4m22mbuffer-name24m] [1m-n 4m22mnew-buffer-name24m] 4mdata0m + (alias: 1msetb22m) + Set the contents of the specified buffer to 4mdata24m. The 1m-a 22moption + appends to rather than overwriting the buffer. The 1m-n 22moption + renames the buffer to 4mnew-buffer-name24m. + + 1mshow-buffer 22m[1m-b 4m22mbuffer-name24m] + (alias: 1mshowb22m) + Display the contents of the specified buffer. + +1mMISCELLANEOUS0m + Miscellaneous commands are as follows: + + 1mclock-mode 22m[1m-t 4m22mtarget-pane24m] + Display a large clock. + + 1mif-shell 22m[1m-bF22m] [1m-t 4m22mtarget-pane24m] 4mshell-command24m 4mcommand24m [4mcommand24m] + (alias: 1mif22m) + Execute the first 4mcommand24m if 4mshell-command24m returns success or the + second 4mcommand24m otherwise. Before being executed, 4mshell-command0m + is expanded using the rules specified in the 4mFORMATS24m section, + including those relevant to 4mtarget-pane24m. With 1m-b22m, 4mshell-command0m + is run in the background. + + If 1m-F 22mis given, 4mshell-command24m is not executed but considered suc- + cess if neither empty nor zero (after formats are expanded). + + 1mlock-server0m + (alias: 1mlock22m) + Lock each client individually by running the command specified by + the 1mlock-command 22moption. + + 1mrun-shell 22m[1m-b22m] [1m-t 4m22mtarget-pane24m] 4mshell-command0m + (alias: 1mrun22m) + Execute 4mshell-command24m in the background without creating a win- + dow. Before being executed, shell-command is expanded using the + rules specified in the 4mFORMATS24m section. With 1m-b22m, the command is + run in the background. After it finishes, any output to stdout + is displayed in copy mode (in the pane specified by 1m-t 22mor the + current pane if omitted). If the command doesn't return success, + the exit status is also displayed. + + 1mwait-for 22m[1m-L 22m| 1m-S 22m| 1m-U22m] 4mchannel0m + (alias: 1mwait22m) + When used without options, prevents the client from exiting until + woken using 1mwait-for -S 22mwith the same channel. When 1m-L 22mis 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 + 1mwait-for -U22m. This command only works from outside 1mtmux22m. + +1mTERMINFO EXTENSIONS0m + 1mtmux 22munderstands some extensions to terminfo(5): + + 4mCs24m, 4mCr24m 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 1mtmux22m: + + $ printf '\033]12;red\033\\' + + 4mSs24m, 4mSe24m Set or reset the cursor style. If set, a sequence such as this + may be used to change the cursor to an underline: + + $ printf '\033[4 q' + + If 4mSe24m is not set, Ss with argument 0 will be used to reset the + cursor style instead. + + 4mMs24m This sequence can be used by 1mtmux 22mto store the current buffer in + the host terminal's selection (clipboard). See the 4mset-clipboard0m + option above and the xterm(1) man page. + +1mCONTROL MODE0m + 1mtmux 22moffers a textual interface called 4mcontrol24m 4mmode24m. This allows appli- + cations to communicate with 1mtmux 22musing a simple text-only protocol. + + In control mode, a client sends 1mtmux 22mcommands or command sequences termi- + nated by newlines on standard input. Each command will produce one block + of output on standard output. An output block consists of a 4m%begin24m line + followed by the output (which may be empty). The output block ends with + a 4m%end24m or 4m%error24m. 4m%begin24m and matching 4m%end24m or 4m%error24m have two arguments: + an integer time (as seconds from epoch) and command number. For example: + + %begin 1363006971 2 + 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) + %end 1363006971 2 + + In control mode, 1mtmux 22moutputs notifications. A notification will never + occur inside an output block. + + The following notifications are defined: + + 1m%exit 22m[4mreason24m] + The 1mtmux 22mclient is exiting immediately, either because it is not + attached to any session or an error occurred. If present, 4mreason0m + describes why the client exited. + + 1m%layout-change 4m22mwindow-id24m 4mwindow-layout0m + The layout of a window with ID 4mwindow-id24m changed. The new layout + is 4mwindow-layout24m. + + 1m%output 4m22mpane-id24m 4mvalue0m + A window pane produced output. 4mvalue24m escapes non-printable char- + acters and backslash as octal \xxx. + + 1m%session-changed 4m22msession-id24m 4mname0m + The client is now attached to the session with ID 4msession-id24m, + which is named 4mname24m. + + 1m%session-renamed 4m22mname0m + The current session was renamed to 4mname24m. + + 1m%sessions-changed0m + A session was created or destroyed. + + 1m%unlinked-window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was created but is not linked to the + current session. + + 1m%window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was linked to the current session. + + 1m%window-close 4m22mwindow-id0m + The window with ID 4mwindow-id24m closed. + + 1m%window-renamed 4m22mwindow-id24m 4mname0m + The window with ID 4mwindow-id24m was renamed to 4mname24m. + +1mFILES0m + ~/.tmux.conf Default 1mtmux 22mconfiguration file. + @SYSCONFDIR@/tmux.conf System-wide configuration file. + +1mEXAMPLES0m + To create a new 1mtmux 22msession running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is 1mnew22m: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing `C-b c' + (Ctrl followed by the `b' key followed by the `c' key). + + Windows may be navigated with: `C-b 0' (to select window 0), `C-b 1' (to + select window 1), and so on; `C-b n' to select the next window; and `C-b + p' to select the previous window. + + A session may be detached using `C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing `C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or `q' to exit from it. + + Commands to be run when the 1mtmux 22mserver is started may be placed in the + 4m~/.tmux.conf24m configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-style bg=blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +1mSEE ALSO0m + pty(7) + +1mAUTHORS0m + Nicholas Marriott <4mnicm@users.sourceforge.net24m> + +FreeBSD 11.0 November 6, 2015 FreeBSD 11.0 diff --git a/manual/2.1.txt b/manual/2.1.txt new file mode 100644 index 0000000..c399f6c --- /dev/null +++ b/manual/2.1.txt @@ -0,0 +1,2250 @@ +TMUX(1) FreeBSD General Commands Manual TMUX(1) + +1mNAME0m + 1mtmux 22m-- terminal multiplexer + +1mSYNOPSIS0m + 1mtmux 22m[1m-2CluvV22m] [1m-c 4m22mshell-command24m] [1m-f 4m22mfile24m] [1m-L 4m22msocket-name24m] + [1m-S 4m22msocket-path24m] [4mcommand24m [4mflags24m]] + +1mDESCRIPTION0m + 1mtmux 22mis a terminal multiplexer: it enables a number of terminals to be + created, accessed, and controlled from a single screen. 1mtmux 22mmay be + detached from a screen and continue running in the background, then later + reattached. + + When 1mtmux 22mis started it creates a new 4msession24m with a single 4mwindow24m 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 com- + mands. + + A session is a single collection of 4mpseudo24m 4mterminals24m under the management + of 1mtmux22m. 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 pty(7) manual page documents + the technical details of pseudo terminals). Any number of 1mtmux 22minstances + may connect to the same session, and any number of windows may be present + in the same session. Once all sessions are killed, 1mtmux 22mexits. + + Each session is persistent and will survive accidental disconnection + (such as ssh(1) connection timeout) or intentional detaching (with the + `C-b d' key strokes). 1mtmux 22mmay be reattached using: + + $ tmux attach + + In 1mtmux22m, a session is displayed on screen by a 4mclient24m and all sessions + are managed by a single 4mserver24m. The server and each client are separate + processes which communicate through a socket in 4m/tmp24m. + + The options are as follows: + + 1m-2 22mForce 1mtmux 22mto assume the terminal supports 256 colours. + + 1m-C 22mStart in control mode (see the 4mCONTROL24m 4mMODE24m section). + Given twice (1m-CC22m) disables echo. + + 1m-c 4m22mshell-command0m + Execute 4mshell-command24m using the default shell. If neces- + sary, the 1mtmux 22mserver will be started to retrieve the + 1mdefault-shell 22moption. This option is for compatibility + with sh(1) when 1mtmux 22mis used as a login shell. + + 1m-f 4m22mfile24m Specify an alternative configuration file. By default, + 1mtmux 22mloads the system configuration file from + 4m@SYSCONFDIR@/tmux.conf24m, if present, then looks for a user + configuration file at 4m~/.tmux.conf24m. + + The configuration file is a set of 1mtmux 22mcommands which are + executed in sequence when the server is first started. + 1mtmux 22mloads configuration files once when the server process + has started. The 1msource-file 22mcommand may be used to load a + file later. + + 1mtmux 22mshows any error messages from commands in configura- + tion files in the first session created, and continues to + process the rest of the configuration file. + + 1m-L 4m22msocket-name0m + 1mtmux 22mstores the server socket in a directory under + TMUX_TMPDIR, TMPDIR if it is unset, or 4m/tmp24m if both are + unset. The default socket is named 4mdefault24m. This option + allows a different socket name to be specified, allowing + several independent 1mtmux 22mservers to be run. Unlike 1m-S 22ma + full path is not necessary: the sockets are all created in + the same directory. + + If the socket is accidentally removed, the SIGUSR1 signal + may be sent to the 1mtmux 22mserver process to recreate it (note + that this will fail if any parent directories are missing). + + 1m-l 22mBehave as a login shell. This flag currently has no effect + and is for compatibility with other shells when using tmux + as a login shell. + + 1m-S 4m22msocket-path0m + Specify a full alternative path to the server socket. If + 1m-S 22mis specified, the default socket directory is not used + and any 1m-L 22mflag is ignored. + + 1m-u tmux 22mattempts to guess if the terminal is likely to support + UTF-8 by checking the first of the LC_ALL, LC_CTYPE and + LANG environment variables to be set for the string + "UTF-8". This is not always correct: the 1m-u 22mflag explic- + itly informs 1mtmux 22mthat UTF-8 is supported. + + If the server is started from a client passed 1m-u 22mor where + UTF-8 is detected, the 1mutf8 22mand 1mstatus-utf8 22moptions are + enabled in the global window and session options respec- + tively. + + 1m-v 22mRequest verbose logging. This option may be specified mul- + tiple times for increasing verbosity. Log messages will be + saved into 4mtmux-client-PID.log24m and 4mtmux-server-PID.log0m + files in the current directory, where 4mPID24m is the PID of the + server or client process. + + 1m-V 22mReport the 1mtmux 22mversion. + + 4mcommand24m [4mflags24m] + This specifies one of a set of commands used to control + 1mtmux22m, as described in the following sections. If no com- + mands are specified, the 1mnew-session 22mcommand is assumed. + +1mKEY BINDINGS0m + 1mtmux 22mmay be controlled from an attached client by using a key combination + of a prefix key, `C-b' (Ctrl-b) by default, followed by a command key. + + The default command key bindings are: + + C-b Send the prefix key (C-b) through to the application. + C-o Rotate the panes in the current window forwards. + C-z Suspend the 1mtmux 22mclient. + ! Break the current pane out of the window. + " Split the current pane into two, top and bottom. + # List all paste buffers. + $ Rename the current session. + % Split the current pane into two, left and right. + & Kill the current window. + ' Prompt for a window index to select. + ( Switch the attached client to the previous session. + ) Switch the attached client to the next session. + , Rename the current window. + - Delete the most recently copied buffer of text. + . Prompt for an index to move the current window. + 0 to 9 Select windows 0 to 9. + : Enter the 1mtmux 22mcommand prompt. + ; Move to the previously active pane. + = Choose which buffer to paste interactively from a list. + ? List all key bindings. + D Choose a client to detach. + L Switch the attached client back to the last session. + [ Enter copy mode to copy text or view the history. + ] Paste the most recently copied buffer of text. + c Create a new window. + d Detach the current client. + f Prompt to search for text in open windows. + i Display some information about the current window. + l Move to the previously selected window. + n Change to the next window. + o Select the next pane in the current window. + p Change to the previous window. + q Briefly display pane indexes. + r Force redraw of the attached client. + m Mark the current pane (see 1mselect-pane -m22m). + M Clear the marked pane. + s Select a new session for the attached client interac- + tively. + t Show the time. + w Choose the current window interactively. + x Kill the current pane. + z Toggle zoom state of the current pane. + { Swap the current pane with the previous pane. + } Swap the current pane with the next pane. + ~ Show previous messages from 1mtmux22m, if any. + Page Up Enter copy mode and scroll one page up. + Up, Down + Left, Right + Change to the pane above, below, to the left, or to the + right of the current pane. + M-1 to M-5 Arrange panes in one of the five preset layouts: even- + horizontal, even-vertical, main-horizontal, main-verti- + cal, or tiled. + Space Arrange the current window in the next preset layout. + M-n Move to the next window with a bell or activity marker. + M-o Rotate the panes in the current window backwards. + M-p Move to the previous window with a bell or activity + marker. + C-Up, C-Down + C-Left, C-Right + Resize the current pane in steps of one cell. + M-Up, M-Down + M-Left, M-Right + Resize the current pane in steps of five cells. + + Key bindings may be changed with the 1mbind-key 22mand 1munbind-key 22mcommands. + +1mCOMMANDS0m + This section contains a list of the commands supported by 1mtmux22m. Most + commands accept the optional 1m-t 22m(and sometimes 1m-s22m) argument with one of + 4mtarget-client24m, 4mtarget-session24m 4mtarget-window24m, or 4mtarget-pane24m. These spec- + ify the client, session, window or pane which a command should affect. + + 4mtarget-client24m is the name of the pty(7) file to which the client is con- + nected, for example either of 4m/dev/ttyp124m or 4mttyp124m for the client attached + to 4m/dev/ttyp124m. If no client is specified, 1mtmux 22mattempts to work out the + client currently in use; if that fails, an error is reported. Clients + may be listed with the 1mlist-clients 22mcommand. + + 4mtarget-session24m is tried as, in order: + + 1. A session ID prefixed with a $. + + 2. An exact name of a session (as listed by the 1mlist-sessions0m + command). + + 3. The start of a session name, for example `mysess' would match + a session named `mysession'. + + 4. An fnmatch(3) pattern which is matched against the session + name. + + If the session name is prefixed with an `=', only an exact match is + accepted (so `=mysess' will only match exactly `mysess', not + `mysession'). + + If a single session 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. + + 4mtarget-window24m specifies a window in the form 4msession24m:4mwindow24m. 4msession0m + follows the same rules as for 4mtarget-session24m, and 4mwindow24m is looked for in + order as: + + 1. A special token, listed below. + + 2. A window index, for example `mysession:1' is window 1 in ses- + sion `mysession'. + + 3. A window ID, such as @1. + + 4. An exact window name, such as `mysession:mywindow'. + + 5. The start of a window name, such as `mysession:mywin'. + + 6. As an fnmatch(3) pattern matched against the window name. + + Like sessions, a `=' prefix will do an exact match only. An empty window + name specifies the next unused index if appropriate (for example the + 1mnew-window 22mand 1mlink-window 22mcommands) otherwise the current window in + 4msession24m is chosen. + + The following special tokens are available to indicate particular win- + dows. Each has a single-character alternative form. + + 1mToken Meaning0m + {start} ^ The lowest-numbered window + {end} $ The highest-numbered window + {last} ! The last (previously current) window + {next} + The next window by number + {previous} - The previous window by number + + 4mtarget-pane24m may be a pane ID or takes a similar form to 4mtarget-window24m but + with the optional addition of a period followed by a pane index or pane + ID, for example: `mysession:mywindow.1'. If the pane index is omitted, + the currently active pane in the specified window is used. The following + special tokens are available for the pane index: + + 1mToken Meaning0m + {last} ! The last (previously active) pane + {next} + The next pane by number + {previous} - The previous pane by number + {top} The top pane + {bottom} The bottom pane + {left} The leftmost pane + {right} The rightmost pane + {top-left} The top-left pane + {top-right} The top-right pane + {bottom-left} The bottom-left pane + {bottom-right} The bottom-right pane + {up-of} The pane above the active pane + {down-of} The pane below the active pane + {left-of} The pane to the left of the active pane + {right-of} The pane to the right of the active pane + + The tokens `+' and `-' may be followed by an offset, for example: + + select-window -t:+2 + + In addition, 4mtarget-session24m, 4mtarget-window24m or 4mtarget-pane24m may consist + entirely of the token `{mouse}' (alternative form `=') to specify the + most recent mouse event (see the 4mMOUSE24m 4mSUPPORT24m section) or `{marked}' + (alternative form `~') to specify the marked pane (see 1mselect-pane -m22m). + + Sessions, window and panes are each numbered with a unique ID; session + IDs are prefixed with a `$', windows with a `@', and panes with a `%'. + These are unique and are unchanged for the life of the session, window or + pane in the 1mtmux 22mserver. The pane ID is passed to the child process of + the pane in the TMUX_PANE environment variable. IDs may be displayed + using the `session_id', `window_id', or `pane_id' formats (see the + 4mFORMATS24m section) and the 1mdisplay-message22m, 1mlist-sessions22m, 1mlist-windows 22mor + 1mlist-panes 22mcommands. + + 4mshell-command24m arguments are sh(1) commands. This may be a single argu- + ment passed to the shell, for example: + + new-window 'vi /etc/passwd' + + Will run: + + /bin/sh -c 'vi /etc/passwd' + + Additionally, the 1mnew-window22m, 1mnew-session22m, 1msplit-window22m, 1mrespawn-window0m + and 1mrespawn-pane 22mcommands allow 4mshell-command24m to be given as multiple + arguments and executed directly (without `sh -c'). This can avoid issues + with shell quoting. For example: + + $ tmux new-window vi /etc/passwd + + Will run vi(1) directly without invoking the shell. + + 4mcommand24m [4marguments24m] refers to a 1mtmux 22mcommand, passed with the command and + arguments separately, for example: + + bind-key F1 set-window-option force-width 81 + + Or if using sh(1): + + $ tmux bind-key F1 set-window-option force-width 81 + + Multiple commands may be specified together as part of a 4mcommand0m + 4msequence24m. 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 + 1mbind-key22m). + + Example 1mtmux 22mcommands include: + + 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 \; \ + display-message "source-file done" + + Or from sh(1): + + $ tmux kill-window -t :1 + + $ tmux new-window \; split-window -d + + $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach + +1mCLIENTS AND SESSIONS0m + The 1mtmux 22mserver manages clients, sessions, windows and panes. Clients + are attached to sessions to interact with them, either when they are cre- + ated with the 1mnew-session 22mcommand, or later with the 1mattach-session 22mcom- + mand. Each session has one or more windows 4mlinked24m 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 4mWINDOWS24m 4mAND24m 4mPANES24m sec- + tion. + + The following commands are available to manage clients and sessions: + + 1mattach-session 22m[1m-dEr22m] [1m-c 4m22mworking-directory24m] [1m-t 4m22mtarget-session24m] + (alias: 1mattach22m) + If run from outside 1mtmux22m, create a new client in the current ter- + minal and attach it to 4mtarget-session24m. If used from inside, + switch the current client. If 1m-d 22mis specified, any other clients + attached to the session are detached. 1m-r 22msignifies the client is + read-only (only keys bound to the 1mdetach-client 22mor 1mswitch-client0m + commands have any effect) + + If no server is started, 1mattach-session 22mwill attempt to start it; + this will fail unless sessions are created in the configuration + file. + + The 4mtarget-session24m rules for 1mattach-session 22mare slightly + adjusted: if 1mtmux 22mneeds to select the most recently used session, + it will prefer the most recently used 4munattached24m session. + + 1m-c 22mwill set the session working directory (used for new windows) + to 4mworking-directory24m. + + If 1m-E 22mis used, 1mupdate-environment 22moption will not be applied. + + 1mdetach-client 22m[1m-P22m] [1m-a22m] [1m-s 4m22mtarget-session24m] [1m-t 4m22mtarget-client24m] + (alias: 1mdetach22m) + Detach the current client if bound to a key, the client specified + with 1m-t22m, or all clients currently attached to the session speci- + fied by 1m-s22m. The 1m-a 22moption kills all but the client given with + 1m-t22m. If 1m-P 22mis given, send SIGHUP to the parent process of the + client, typically causing it to exit. + + 1mhas-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mhas22m) + Report an error and exit with 1 if the specified session does not + exist. If it does exist, exit with 0. + + 1mkill-server0m + Kill the 1mtmux 22mserver and clients and destroy all sessions. + + 1mkill-session 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + Destroy the given session, closing any windows linked to it and + no other sessions, and detaching all clients attached to it. If + 1m-a 22mis given, all sessions but the specified one is killed. + + 1mlist-clients 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsc22m) + List all clients attached to the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. If 4mtarget-session24m is speci- + fied, list only clients connected to that session. + + 1mlist-commands0m + (alias: 1mlscm22m) + List the syntax of all commands supported by 1mtmux22m. + + 1mlist-sessions 22m[1m-F 4m22mformat24m] + (alias: 1mls22m) + List all sessions managed by the server. For the meaning of the + 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mlock-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1mlockc22m) + Lock 4mtarget-client24m, see the 1mlock-server 22mcommand. + + 1mlock-session 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlocks22m) + Lock all clients attached to 4mtarget-session24m. + + 1mnew-session 22m[1m-AdDEP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] + [1m-s 4m22msession-name24m] [1m-t 4m22mtarget-session24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] + [4mshell-command24m] + (alias: 1mnew22m) + Create a new session with name 4msession-name24m. + + The new session is attached to the current terminal unless 1m-d 22mis + given. 4mwindow-name24m and 4mshell-command24m are the name of and shell + command to execute in the initial window. If 1m-d 22mis used, 1m-x 22mand + 1m-y 22mspecify the size of the initial window (80 by 24 if not + given). + + If run from a terminal, any termios(3) special characters are + saved and used for new windows in the new session. + + The 1m-A 22mflag makes 1mnew-session 22mbehave like 1mattach-session 22mif + 4msession-name24m already exists; in this case, 1m-D 22mbehaves like 1m-d 22mto + 1mattach-session22m. + + If 1m-t 22mis given, the new session is 4mgrouped24m with 4mtarget-session24m. + This means they share the same set of windows - all windows from + 4mtarget-session24m 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 1m-n 22mor 4mshell-command24m are invalid if 1m-t 22mis used. + + The 1m-P 22moption prints information about the new session after it + has been created. By default, it uses the format + `#{session_name}:' but a different format may be specified with + 1m-F22m. + + If 1m-E 22mis used, 1mupdate-environment 22moption will not be applied. + 1mupdate-environment22m. + + 1mrefresh-client 22m[1m-S22m] [1m-t 4m22mtarget-client24m] + (alias: 1mrefresh22m) + Refresh the current client if bound to a key, or a single client + if one is given with 1m-t22m. If 1m-S 22mis specified, only update the + client's status bar. + + 1mrename-session 22m[1m-t 4m22mtarget-session24m] 4mnew-name0m + (alias: 1mrename22m) + Rename the session to 4mnew-name24m. + + 1mshow-messages 22m[1m-IJT22m] [1m-t 4m22mtarget-client24m] + (alias: 1mshowmsgs22m) + Show client messages or server information. Any messages dis- + played on the status line are saved in a per-client message log, + up to a maximum of the limit set by the 4mmessage-limit24m server + option. With 1m-t22m, display the log for 4mtarget-client24m. 1m-I22m, 1m-J 22mand + 1m-T 22mshow debugging information about the running server, jobs and + terminals. + + 1msource-file 4m22mpath0m + (alias: 1msource22m) + Execute commands from 4mpath24m. + + 1mstart-server0m + (alias: 1mstart22m) + Start the 1mtmux 22mserver, if not already running, without creating + any sessions. + + 1msuspend-client 22m[1m-t 4m22mtarget-client24m] + (alias: 1msuspendc22m) + Suspend a client by sending SIGTSTP (tty stop). + + 1mswitch-client 22m[1m-Elnpr22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-session24m] [1m-T0m + 4mkey-table24m] + (alias: 1mswitchc22m) + Switch the current session for client 4mtarget-client24m to + 4mtarget-session24m. If 1m-l22m, 1m-n 22mor 1m-p 22mis used, the client is moved to + the last, next or previous session respectively. 1m-r 22mtoggles + whether a client is read-only (see the 1mattach-session 22mcommand). + + If 1m-E 22mis used, 1mupdate-environment 22moption will not be applied. + + 1m-T 22msets the client's key table; the next key from the client will + be interpreted from 4mkey-table24m. This may be used to configure + multiple prefix keys, or to bind commands to sequences of keys. + For example, to make typing `abc' run the 1mlist-keys 22mcommand: + + bind-key -Ttable2 c list-keys + bind-key -Ttable1 b switch-client -Ttable2 + bind-key -Troot a switch-client -Ttable1 + +1mWINDOWS AND PANES0m + A 1mtmux 22mwindow 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 + 4mpaste24m 4mbuffer24m for later insertion into another window. This mode is + entered with the 1mcopy-mode 22mcommand, bound to `[' by default. It is also + entered when a command that produces output, such as 1mlist-keys22m, is exe- + cuted from a key binding. + + The keys available depend on whether emacs or vi mode is selected (see + the 1mmode-keys 22moption). The following keys are supported as appropriate + for the mode: + + 1mFunction vi emacs0m + Append selection A + Back to indentation ^ M-m + Bottom of history G M-< + Clear selection Escape C-g + Copy selection Enter M-w + Copy to named buffer " + Cursor down j Down + Cursor left h Left + Cursor right l Right + Cursor to bottom line L + Cursor to middle line M M-r + Cursor to top line H M-R + Cursor up k Up + Delete entire line d C-u + Delete/Copy to end of line D C-k + End of line $ C-e + Go to line : g + Half page down C-d M-Down + Half page up C-u M-Up + Jump again ; ; + Jump again in reverse , , + Jump backward F F + Jump forward f f + Jump to backward T + Jump to forward t + Next page C-f Page down + Next space W + Next space, end of word E + Next word w + Next word end e M-f + Other end of selection o + Paste buffer p C-y + Previous page C-b Page up + Previous space B + Previous word b M-b + Quit mode q Escape + Rectangle toggle v R + Scroll down C-Down or C-e C-Down + Scroll up C-Up or C-y C-Up + Search again n n + Search again in reverse N N + Search backward ? C-r + Search forward / C-s + Select line V + Start of line 0 C-a + Start selection Space C-Space + Top of history g M-> + Transpose characters C-t + + The next and previous word keys use space and the `-', `_' and `@' char- + acters as word delimiters by default, but this can be adjusted by setting + the 4mword-separators24m 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. + + The jump commands enable quick movement within a line. For instance, + typing `f' followed by `/' will move the cursor to the next `/' character + on the current line. A `;' will then jump to the next occurrence. + + 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 `M-1 0 M-f' in emacs mode, and + `10w' in vi. + + Mode key bindings are defined in a set of named tables: 4mvi-edit24m and + 4memacs-edit24m for keys used when line editing at the command prompt; + 4mvi-choice24m and 4memacs-choice24m for keys used when choosing from lists (such + as produced by the 1mchoose-window 22mcommand); and 4mvi-copy24m and 4memacs-copy0m + used in copy mode. The tables may be viewed with the 1mlist-keys 22mcommand + and keys modified or removed with 1mbind-key 22mand 1munbind-key22m. If + 1mappend-selection22m, 1mcopy-selection22m, or 1mstart-named-buffer 22mare given the 1m-x0m + flag, 1mtmux 22mwill not exit copy mode after copying. 1mcopy-pipe 22mcopies the + selection and pipes it to a command. For example the following will bind + `C-w' not to exit after copying and `C-q' to copy the selection into 4m/tmp0m + as well as the paste buffer: + + bind-key -temacs-copy C-w copy-selection -x + bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out" + + The paste buffer key pastes the first line from the top paste buffer on + the stack. + + The synopsis for the 1mcopy-mode 22mcommand is: + + 1mcopy-mode 22m[1m-Meu22m] [1m-t 4m22mtarget-pane24m] + Enter copy mode. The 1m-u 22moption scrolls one page up. 1m-M 22mbegins a + mouse drag (only valid if bound to a mouse key binding, see 4mMOUSE0m + 4mSUPPORT24m). 1m-e 22mspecifies that scrolling to the bottom of the his- + tory (to the visible screen) should exit copy mode. While in + copy mode, pressing a key other than those used for scrolling + will disable this behaviour. This is intended to allow fast + scrolling through a pane's history, for example with: + + bind PageUp copy-mode -eu + + Each window displayed by 1mtmux 22mmay be split into one or more 4mpanes24m; each + pane takes up a certain area of the display and is a separate terminal. + A window may be split into panes using the 1msplit-window 22mcommand. Windows + may be split horizontally (with the 1m-h 22mflag) or vertically. Panes may be + resized with the 1mresize-pane 22mcommand (bound to `C-up', `C-down' `C-left' + and `C-right' by default), the current pane may be changed with the + 1mselect-pane 22mcommand and the 1mrotate-window 22mand 1mswap-pane 22mcommands may be + used to swap panes without changing their position. Panes are numbered + beginning from zero in the order they are created. + + A number of preset 4mlayouts24m are available. These may be selected with the + 1mselect-layout 22mcommand or cycled with 1mnext-layout 22m(bound to `Space' by + default); once a layout is chosen, panes within it may be moved and + resized as normal. + + The following layouts are supported: + + 1meven-horizontal0m + Panes are spread out evenly from left to right across the window. + + 1meven-vertical0m + Panes are spread evenly from top to bottom. + + 1mmain-horizontal0m + 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 4mmain-pane-height24m window option to + specify the height of the top pane. + + 1mmain-vertical0m + Similar to 1mmain-horizontal 22mbut the large pane is placed on the + left and the others spread from top to bottom along the right. + See the 4mmain-pane-width24m window option. + + 1mtiled 22mPanes are spread out as evenly as possible over the window in + both rows and columns. + + In addition, 1mselect-layout 22mmay be used to apply a previously used layout + - the 1mlist-windows 22mcommand displays the layout of each window in a form + suitable for use with 1mselect-layout22m. For example: + + $ 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} + + 1mtmux 22mautomatically 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. + + Commands related to windows and panes are as follows: + + 1mbreak-pane 22m[1m-dP22m] [1m-F 4m22mformat24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mbreakp22m) + Break 4msrc-pane24m off from its containing window to make it the only + pane in 4mdst-window24m. If 1m-d 22mis given, the new window does not + become the current window. The 1m-P 22moption prints information + about the new window after it has been created. By default, it + uses the format `#{session_name}:#{window_index}' but a different + format may be specified with 1m-F22m. + + 1mcapture-pane 22m[1m-aepPq22m] [1m-b 4m22mbuffer-name24m] [1m-E 4m22mend-line24m] [1m-S 4m22mstart-line24m] [1m-t0m + 4mtarget-pane24m] + (alias: 1mcapturep22m) + Capture the contents of a pane. If 1m-p 22mis given, the output goes + to stdout, otherwise to the buffer specified with 1m-b 22mor a new + buffer if omitted. If 1m-a 22mis given, the alternate screen is used, + and the history is not accessible. If no alternate screen + exists, an error will be returned unless 1m-q 22mis given. If 1m-e 22mis + given, the output includes escape sequences for text and back- + ground attributes. 1m-C 22malso escapes non-printable characters as + octal \xxx. 1m-J 22mjoins wrapped lines and preserves trailing spaces + at each line's end. 1m-P 22mcaptures only any output that the pane + has received that is the beginning of an as-yet incomplete escape + sequence. + + 1m-S 22mand 1m-E 22mspecify the starting and ending line numbers, zero is + the first line of the visible pane and negative numbers are lines + in the history. `-' to 1m-S 22mis the start of the history and to 1m-E0m + the end of the visible pane. The default is to capture only the + visible contents of the pane. + + 1mchoose-client 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into client choice mode, allowing a client to be + selected interactively from a list. After a client is chosen, + `%%' is replaced by the client pty(7) path in 4mtemplate24m and the + result executed as a command. If 4mtemplate24m is not given, "detach- + client -t '%%'" is used. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. This command works only if at least one client + is attached. + + 1mchoose-session 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into session choice mode, where a session may be + selected interactively from a list. When one is chosen, `%%' is + replaced by the session name in 4mtemplate24m and the result executed + as a command. If 4mtemplate24m is not given, "switch-client -t '%%'" + is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. This command works only if at least one client is + attached. + + 1mchoose-tree 22m[1m-suw22m] [1m-b 4m22msession-template24m] [1m-c 4m22mwindow-template24m] [1m-S 4m22mformat24m] + [1m-W 4m22mformat24m] [1m-t 4m22mtarget-window24m] + Put a window into tree choice mode, where either sessions or win- + dows may be selected interactively from a list. By default, win- + dows belonging to a session are indented to show their relation- + ship to a session. + + Note that the 1mchoose-window 22mand 1mchoose-session 22mcommands are wrap- + pers around 1mchoose-tree22m. + + If 1m-s 22mis given, will show sessions. If 1m-w 22mis given, will show + windows. + + By default, the tree is collapsed and sessions must be expanded + to windows with the right arrow key. The 1m-u 22moption will start + with all sessions expanded instead. + + If 1m-b 22mis given, will override the default session command. Note + that `%%' can be used and will be replaced with the session name. + The default option if not specified is "switch-client -t '%%'". + If 1m-c 22mis given, will override the default window command. Like + 1m-b22m, `%%' 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. + + If 1m-S 22mis given will display the specified format instead of the + default session format. If 1m-W 22mis given will display the speci- + fied format instead of the default window format. For the mean- + ing of the 1m-s 22mand 1m-w 22moptions, see the 4mFORMATS24m section. + + This command works only if at least one client is attached. + + 1mchoose-window 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into window choice mode, where a window may be cho- + sen interactively from a list. After a window is selected, `%%' + is replaced by the session name and window index in 4mtemplate24m and + the result executed as a command. If 4mtemplate24m is not given, + "select-window -t '%%'" is used. For the meaning of the 1m-F 22mflag, + see the 4mFORMATS24m section. This command works only if at least one + client is attached. + + 1mdisplay-panes 22m[1m-t 4m22mtarget-client24m] + (alias: 1mdisplayp22m) + Display a visible indicator of each pane shown by 4mtarget-client24m. + See the 1mdisplay-panes-time22m, 1mdisplay-panes-colour22m, and + 1mdisplay-panes-active-colour 22msession options. While the indicator + is on screen, a pane may be selected with the `0' to `9' keys. + + 1mfind-window 22m[1m-CNT22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] 4mmatch-string0m + (alias: 1mfindw22m) + Search for the fnmatch(3) pattern 4mmatch-string24m in window names, + titles, and visible content (but not history). The flags control + matching behavior: 1m-C 22mmatches only visible window contents, 1m-N0m + matches only the window name and 1m-T 22mmatches only the window + title. The default is 1m-CNT22m. If only one window is matched, + it'll be automatically selected, otherwise a choice list is + shown. For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + This command works only if at least one client is attached. + + 1mjoin-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mjoinp22m) + Like 1msplit-window22m, but instead of splitting 4mdst-pane24m and creating + a new pane, split it and move 4msrc-pane24m into the space. This can + be used to reverse 1mbreak-pane22m. The 1m-b 22moption causes 4msrc-pane24m to + be joined to left of or above 4mdst-pane24m. + + If 1m-s 22mis omitted and a marked pane is present (see 1mselect-pane0m + 1m-m22m), the marked pane is used rather than the current pane. + + 1mkill-pane 22m[1m-a22m] [1m-t 4m22mtarget-pane24m] + (alias: 1mkillp22m) + Destroy the given pane. If no panes remain in the containing + window, it is also destroyed. The 1m-a 22moption kills all but the + pane given with 1m-t22m. + + 1mkill-window 22m[1m-a22m] [1m-t 4m22mtarget-window24m] + (alias: 1mkillw22m) + Kill the current window or the window at 4mtarget-window24m, removing + it from any sessions to which it is linked. The 1m-a 22moption kills + all but the window given with 1m-t22m. + + 1mlast-pane 22m[1m-de22m] [1m-t 4m22mtarget-window24m] + (alias: 1mlastp22m) + Select the last (previously selected) pane. 1m-e 22menables or 1m-d0m + disables input to the pane. + + 1mlast-window 22m[1m-t 4m22mtarget-session24m] + (alias: 1mlast22m) + Select the last (previously selected) window. If no + 4mtarget-session24m is specified, select the last window of the cur- + rent session. + + 1mlink-window 22m[1m-adk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mlinkw22m) + Link the window at 4msrc-window24m to the specified 4mdst-window24m. If + 4mdst-window24m is specified and no such window exists, the 4msrc-window0m + is linked there. With 1m-a22m, the window is moved to the next index + up (following windows are moved if necessary). If 1m-k 22mis given + and 4mdst-window24m exists, it is killed, otherwise an error is gener- + ated. If 1m-d 22mis given, the newly linked window is not selected. + + 1mlist-panes 22m[1m-as22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget24m] + (alias: 1mlsp22m) + If 1m-a 22mis given, 4mtarget24m is ignored and all panes on the server are + listed. If 1m-s 22mis given, 4mtarget24m is a session (or the current ses- + sion). If neither is given, 4mtarget24m is a window (or the current + window). For the meaning of the 1m-F 22mflag, see the 4mFORMATS24m sec- + tion. + + 1mlist-windows 22m[1m-a22m] [1m-F 4m22mformat24m] [1m-t 4m22mtarget-session24m] + (alias: 1mlsw22m) + If 1m-a 22mis given, list all windows on the server. Otherwise, list + windows in the current session or in 4mtarget-session24m. For the + meaning of the 1m-F 22mflag, see the 4mFORMATS24m section. + + 1mmove-pane 22m[1m-bdhv22m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mmovep22m) + Like 1mjoin-pane22m, but 4msrc-pane24m and 4mdst-pane24m may belong to the same + window. + + 1mmove-window 22m[1m-ardk22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mmovew22m) + This is similar to 1mlink-window22m, except the window at 4msrc-window0m + is moved to 4mdst-window24m. With 1m-r22m, all windows in the session are + renumbered in sequential order, respecting the 1mbase-index 22moption. + + 1mnew-window 22m[1m-adkP22m] [1m-c 4m22mstart-directory24m] [1m-F 4m22mformat24m] [1m-n 4m22mwindow-name24m] [1m-t0m + 4mtarget-window24m] [4mshell-command24m] + (alias: 1mneww22m) + Create a new window. With 1m-a22m, the new window is inserted at the + next index up from the specified 4mtarget-window24m, moving windows up + if necessary, otherwise 4mtarget-window24m is the new window location. + + If 1m-d 22mis given, the session does not make the new window the cur- + rent window. 4mtarget-window24m represents the window to be created; + if the target already exists an error is shown, unless the 1m-k0m + flag is used, in which case it is destroyed. 4mshell-command24m is + the command to execute. If 4mshell-command24m is not specified, the + value of the 1mdefault-command 22moption is used. 1m-c 22mspecifies the + working directory in which the new window is created. + + When the shell command completes, the window closes. See the + 1mremain-on-exit 22moption to change this behaviour. + + The TERM environment variable must be set to ``screen'' for all + programs running 4minside24m 1mtmux22m. New windows will automatically + have ``TERM=screen'' added to their environment, but care must be + taken not to reset this in shell start-up files. + + The 1m-P 22moption prints information about the new window after it + has been created. By default, it uses the format + `#{session_name}:#{window_index}' but a different format may be + specified with 1m-F22m. + + 1mnext-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mnextl22m) + Move a window to the next layout and rearrange the panes to fit. + + 1mnext-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mnext22m) + Move to the next window in the session. If 1m-a 22mis used, move to + the next window with an alert. + + 1mpipe-pane 22m[1m-o22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mpipep22m) + Pipe any output sent by the program in 4mtarget-pane24m to a shell + command. A pane may only be piped to one command at a time, any + existing pipe is closed before 4mshell-command24m is executed. The + 4mshell-command24m string may contain the special character sequences + supported by the 1mstatus-left 22moption. If no 4mshell-command24m is + given, the current pipe (if any) is closed. + + The 1m-o 22moption only opens a new pipe if no previous pipe exists, + allowing a pipe to be toggled with a single key, for example: + + bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P' + + 1mprevious-layout 22m[1m-t 4m22mtarget-window24m] + (alias: 1mprevl22m) + Move to the previous layout in the session. + + 1mprevious-window 22m[1m-a22m] [1m-t 4m22mtarget-session24m] + (alias: 1mprev22m) + Move to the previous window in the session. With 1m-a22m, move to the + previous window with an alert. + + 1mrename-window 22m[1m-t 4m22mtarget-window24m] 4mnew-name0m + (alias: 1mrenamew22m) + Rename the current window, or the window at 4mtarget-window24m if + specified, to 4mnew-name24m. + + 1mresize-pane 22m[1m-DLMRUZ22m] [1m-t 4m22mtarget-pane24m] [1m-x 4m22mwidth24m] [1m-y 4m22mheight24m] + [4madjustment24m] + (alias: 1mresizep22m) + Resize a pane, up, down, left or right by 4madjustment24m with 1m-U22m, 1m-D22m, + 1m-L 22mor 1m-R22m, or to an absolute size with 1m-x 22mor 1m-y22m. The 4madjustment0m + is given in lines or cells (the default is 1). + + With 1m-Z22m, the active pane is toggled between zoomed (occupying the + whole of the window) and unzoomed (its normal position in the + layout). + + 1m-M 22mbegins mouse resizing (only valid if bound to a mouse key + binding, see 4mMOUSE24m 4mSUPPORT24m). + + 1mrespawn-pane 22m[1m-k22m] [1m-t 4m22mtarget-pane24m] [4mshell-command24m] + (alias: 1mrespawnp22m) + Reactivate a pane in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the pane was created is executed. The pane + must be already inactive, unless 1m-k 22mis given, in which case any + existing command is killed. + + 1mrespawn-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] [4mshell-command24m] + (alias: 1mrespawnw22m) + Reactivate a window in which the command has exited (see the + 1mremain-on-exit 22mwindow option). If 4mshell-command24m is not given, + the command used when the window was created is executed. The + window must be already inactive, unless 1m-k 22mis given, in which + case any existing command is killed. + + 1mrotate-window 22m[1m-DU22m] [1m-t 4m22mtarget-window24m] + (alias: 1mrotatew22m) + Rotate the positions of the panes within a window, either upward + (numerically lower) with 1m-U 22mor downward (numerically higher). + + 1mselect-layout 22m[1m-nop22m] [1m-t 4m22mtarget-window24m] [4mlayout-name24m] + (alias: 1mselectl22m) + Choose a specific layout for a window. If 4mlayout-name24m is not + given, the last preset layout used (if any) is reapplied. 1m-n 22mand + 1m-p 22mare equivalent to the 1mnext-layout 22mand 1mprevious-layout 22mcom- + mands. 1m-o 22mapplies the last set layout if possible (undoes the + most recent layout change). + + 1mselect-pane 22m[1m-DdegLlMmRU22m] [1m-P 4m22mstyle24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mselectp22m) + Make pane 4mtarget-pane24m the active pane in window 4mtarget-window24m, or + set its style (with 1m-P22m). If one of 1m-D22m, 1m-L22m, 1m-R22m, or 1m-U 22mis used, + respectively the pane below, to the left, to the right, or above + the target pane is used. 1m-l 22mis the same as using the 1mlast-pane0m + command. 1m-e 22menables or 1m-d 22mdisables input to the pane. + + 1m-m 22mand 1m-M 22mare used to set and clear the 4mmarked24m 4mpane24m. There is + one marked pane at a time, setting a new marked pane clears the + last. The marked pane is the default target for 1m-s 22mto 1mjoin-pane22m, + 1mswap-pane 22mand 1mswap-window22m. + + Each pane has a style: by default the 1mwindow-style 22mand + 1mwindow-active-style 22moptions are used, 1mselect-pane -P 22msets the + style for a single pane. For example, to set the pane 1 back- + ground to red: + + select-pane -t:.1 -P 'bg=red' + + 1m-g 22mshows the current pane style. + + 1mselect-window 22m[1m-lnpT22m] [1m-t 4m22mtarget-window24m] + (alias: 1mselectw22m) + Select the window at 4mtarget-window24m. 1m-l22m, 1m-n 22mand 1m-p 22mare equivalent + to the 1mlast-window22m, 1mnext-window 22mand 1mprevious-window 22mcommands. If + 1m-T 22mis given and the selected window is already the current win- + dow, the command behaves like 1mlast-window22m. + + 1msplit-window 22m[1m-bdhvP22m] [1m-c 4m22mstart-directory24m] [1m-l 4m22msize24m | 1m-p 4m22mpercentage24m] [1m-t0m + 4mtarget-pane24m] [4mshell-command24m] [1m-F 4m22mformat24m] + (alias: 1msplitw22m) + Create a new pane by splitting 4mtarget-pane24m: 1m-h 22mdoes a horizontal + split and 1m-v 22ma vertical split; if neither is specified, 1m-v 22mis + assumed. The 1m-l 22mand 1m-p 22moptions specify the size of the new pane + in lines (for vertical split) or in cells (for horizontal split), + or as a percentage, respectively. The 1m-b 22moption causes the new + pane to be created to the left of or above 4mtarget-pane24m. All + other options have the same meaning as for the 1mnew-window 22mcom- + mand. + + 1mswap-pane 22m[1m-dDU22m] [1m-s 4m22msrc-pane24m] [1m-t 4m22mdst-pane24m] + (alias: 1mswapp22m) + Swap two panes. If 1m-U 22mis used and no source pane is specified + with 1m-s22m, 4mdst-pane24m is swapped with the previous pane (before it + numerically); 1m-D 22mswaps with the next pane (after it numerically). + 1m-d 22minstructs 1mtmux 22mnot to change the active pane. + + If 1m-s 22mis omitted and a marked pane is present (see 1mselect-pane0m + 1m-m22m), the marked pane is used rather than the current pane. + + 1mswap-window 22m[1m-d22m] [1m-s 4m22msrc-window24m] [1m-t 4m22mdst-window24m] + (alias: 1mswapw22m) + This is similar to 1mlink-window22m, except the source and destination + windows are swapped. It is an error if no window exists at + 4msrc-window24m. + + Like 1mswap-pane22m, if 1m-s 22mis omitted and a marked pane is present + (see 1mselect-pane -m22m), the window containing the marked pane is + used rather than the current window. + + 1munlink-window 22m[1m-k22m] [1m-t 4m22mtarget-window24m] + (alias: 1munlinkw22m) + Unlink 4mtarget-window24m. Unless 1m-k 22mis given, a window may be + unlinked only if it is linked to multiple sessions - windows may + not be linked to no sessions; if 1m-k 22mis specified and the window + is linked to only one session, it is unlinked and destroyed. + +1mKEY BINDINGS0m + 1mtmux 22mallows a command to be bound to most keys, with or without a prefix + key. When specifying keys, most represent themselves (for example `A' to + `Z'). Ctrl keys may be prefixed with `C-' or `^', and Alt (meta) with + `M-'. In addition, the following special key names are accepted: 4mUp24m, + 4mDown24m, 4mLeft24m, 4mRight24m, 4mBSpace24m, 4mBTab24m, 4mDC24m (Delete), 4mEnd24m, 4mEnter24m, 4mEscape24m, 4mF124m to + 4mF1224m, 4mHome24m, 4mIC24m (Insert), 4mNPage/PageDown/PgDn24m, 4mPPage/PageUp/PgUp24m, 4mSpace24m, + and 4mTab24m. Note that to bind the `"' or `'' keys, quotation marks are nec- + essary, for example: + + bind-key '"' split-window + bind-key "'" new-window + + Commands related to key bindings are as follows: + + 1mbind-key 22m[1m-cnr22m] [1m-t 4m22mmode-table24m] [1m-T 4m22mkey-table24m] 4mkey24m 4mcommand24m [4marguments24m] + (alias: 1mbind22m) + Bind key 4mkey24m to 4mcommand24m. Keys are bound in a key table. By + default (without -T), the key is bound in the 4mprefix24m key table. + This table is used for keys pressed after the prefix key (for + example, by default `c' is bound to 1mnew-window 22min the 4mprefix24m ta- + ble, so `C-b c' creates a new window). The 4mroot24m table is used + for keys pressed without the prefix key: binding `c' to + 1mnew-window 22min the 4mroot24m table (not recommended) means a plain `c' + will create a new window. 1m-n 22mis an alias for 1m-T 4m22mroot24m. Keys may + also be bound in custom key tables and the 1mswitch-client -T 22mcom- + mand used to switch to them from a key binding. The 1m-r 22mflag + indicates this key may repeat, see the 1mrepeat-time 22moption. + + If 1m-t 22mis present, 4mkey24m is bound in 4mmode-table24m: the binding for + command mode with 1m-c 22mor for normal mode without. See the 4mWINDOWS0m + 4mAND24m 4mPANES24m section and the 1mlist-keys 22mcommand for information on + mode key bindings. + + To view the default bindings and possible commands, see the + 1mlist-keys 22mcommand. + + 1mlist-keys 22m[1m-t 4m22mmode-table24m] [1m-T 4m22mkey-table24m] + (alias: 1mlsk22m) + List all key bindings. Without 1m-T 22mall key tables are printed. + With 1m-T 22monly 4mkey-table24m. + + With 1m-t22m, the key bindings in 4mmode-table24m are listed; this may be + one of: 4mvi-edit24m, 4memacs-edit24m, 4mvi-choice24m, 4memacs-choice24m, 4mvi-copy24m or + 4memacs-copy24m. + + 1msend-keys 22m[1m-lMR22m] [1m-t 4m22mtarget-pane24m] 4mkey24m 4m...0m + (alias: 1msend22m) + Send a key or keys to a window. Each argument 4mkey24m is the name of + the key (such as `C-a' or `npage' ) to send; if the string is not + recognised as a key, it is sent as a series of characters. The + 1m-l 22mflag disables key name lookup and sends the keys literally. + All arguments are sent sequentially from first to last. The 1m-R0m + flag causes the terminal state to be reset. + + 1m-M 22mpasses through a mouse event (only valid if bound to a mouse + key binding, see 4mMOUSE24m 4mSUPPORT24m). + + 1msend-prefix 22m[1m-222m] [1m-t 4m22mtarget-pane24m] + Send the prefix key, or with 1m-2 22mthe secondary prefix key, to a + window as if it was pressed. + + 1munbind-key 22m[1m-acn22m] [1m-t 4m22mmode-table24m] [1m-T 4m22mkey-table24m] 4mkey0m + (alias: 1munbind22m) + Unbind the command bound to 4mkey24m. 1m-c22m, 1m-n22m, 1m-T 22mand 1m-t 22mare the same + as for 1mbind-key22m. If 1m-a 22mis present, all key bindings are removed. + +1mOPTIONS0m + The appearance and behaviour of 1mtmux 22mmay be modified by changing the + value of various options. There are three types of option: 4mserver0m + 4moptions24m, 4msession24m 4moptions24m and 4mwindow24m 4moptions24m. + + The 1mtmux 22mserver has a set of global options which do not apply to any + particular window or session. These are altered with the 1mset-option -s0m + command, or displayed with the 1mshow-options -s 22mcommand. + + 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 1mset-option0m + command and may be listed with the 1mshow-options 22mcommand. The available + server and session options are listed under the 1mset-option 22mcommand. + + 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 inher- + ited. Window options are altered with the 1mset-window-option 22mcommand and + can be listed with the 1mshow-window-options 22mcommand. All window options + are documented with the 1mset-window-option 22mcommand. + + 1mtmux 22malso supports user options which are prefixed with a `@'. User + options may have any name, so long as they are prefixed with `@', and be + set to any string. For example: + + $ tmux setw -q @foo "abc123" + $ tmux showw -v @foo + abc123 + + Commands which set options are as follows: + + 1mset-option 22m[1m-agoqsuw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1mset22m) + Set a window option with 1m-w 22m(equivalent to the 1mset-window-option0m + command), a server option with 1m-s22m, otherwise a session option. + If 1m-g 22mis given, the global session or window option is set. The + 1m-u 22mflag unsets an option, so a session inherits the option from + the global options (or with 1m-g22m, restores a global option to the + default). + + The 1m-o 22mflag prevents setting an option that is already set and + the 1m-q 22mflag suppresses errors about unknown or ambiguous options. + + With 1m-a22m, and if the option expects a string or a style, 4mvalue24m is + appended to the existing setting. For example: + + set -g status-left "foo" + set -ag status-left "bar" + + Will result in `foobar'. And: + + set -g status-style "bg=red" + set -ag status-style "fg=blue" + + Will result in a red background 4mand24m blue foreground. Without 1m-a22m, + the result would be the default background and a blue foreground. + + Available window options are listed under 1mset-window-option22m. + + 4mvalue24m depends on the option and may be a number, a string, or a + flag (on, off, or omitted to toggle). + + Available server options are: + + 1mbuffer-limit 4m22mnumber0m + Set the number of buffers; as new buffers are added to + the top of the stack, old ones are removed from the bot- + tom if necessary to maintain this maximum length. + + 1mdefault-terminal 4m22mterminal0m + Set the default terminal for new windows created in this + session - the default value of the TERM environment vari- + able. For 1mtmux 22mto work correctly, this 4mmust24m be set to + `screen', `tmux' or a derivative of them. + + 1mescape-time 4m22mtime0m + Set the time in milliseconds for which 1mtmux 22mwaits after + an escape is input to determine if it is part of a func- + tion or meta key sequences. The default is 500 millisec- + onds. + + 1mexit-unattached 22m[1mon 22m| 1moff22m] + If enabled, the server will exit when there are no + attached clients. + + 1mfocus-events 22m[1mon 22m| 1moff22m] + When enabled, focus events are requested from the termi- + nal if supported and passed through to applications run- + ning in 1mtmux22m. Attached clients should be detached and + attached again after changing this option. + + 1mhistory-file 4m22mpath0m + If not empty, a file to which 1mtmux 22mwill write command + prompt history on exit and load it from on start. + + 1mmessage-limit 4m22mnumber0m + Set the number of error or information messages to save + in the message log for each client. The default is 100. + + 1mset-clipboard 22m[1mon 22m| 1moff22m] + Attempt to set the terminal clipboard content using the + \e]52;...\007 xterm(1) escape sequences. This option is + on by default if there is an 4mMs24m entry in the terminfo(5) + description for the client terminal. Note that this fea- + ture needs to be enabled in xterm(1) by setting the + resource: + + disallowedWindowOps: 20,21,SetXprop + + Or changing this property from the xterm(1) interactive + menu when required. + + 1mterminal-overrides 4m22mstring0m + Contains a list of entries which override terminal + descriptions read using terminfo(5). 4mstring24m is a comma- + separated list of items each a colon-separated string + made up of a terminal type pattern (matched using + fnmatch(3)) and a set of 4mname=value24m entries. + + For example, to set the `clear' terminfo(5) entry to + `\e[H\e[2J' for all terminal types and the `dch1' entry + to `\e[P' for the `rxvt' terminal type, the option could + be set to the string: + + "*:clear=\e[H\e[2J,rxvt:dch1=\e[P" + + The terminal entry value is passed through strunvis(3) + before interpretation. The default value forcibly cor- + rects the `colors' entry for terminals which support 256 + colours: + + "*256col*:colors=256,xterm*:XT" + + Available session options are: + + 1massume-paste-time 4m22mmilliseconds0m + If keys are entered faster than one in 4mmilliseconds24m, they + are assumed to have been pasted rather than typed and + 1mtmux 22mkey bindings are not processed. The default is one + millisecond and zero disables. + + 1mbase-index 4m22mindex0m + Set the base index from which an unused index should be + searched when a new window is created. The default is + zero. + + 1mbell-action 22m[1many 22m| 1mnone 22m| 1mcurrent 22m| 1mother22m] + Set action on window bell. 1many 22mmeans a bell in any win- + dow linked to a session causes a bell in the current win- + dow of that session, 1mnone 22mmeans all bells are ignored, + 1mcurrent 22mmeans only bells in windows other than the cur- + rent window are ignored and 1mother 22mmeans bells in the cur- + rent window are ignored but not those in other windows. + + 1mbell-on-alert 22m[1mon 22m| 1moff22m] + If on, ring the terminal bell when an alert occurs. + + 1mdefault-command 4m22mshell-command0m + Set the command used for new windows (if not specified + when the window is created) to 4mshell-command24m, which may + be any sh(1) command. The default is an empty string, + which instructs 1mtmux 22mto create a login shell using the + value of the 1mdefault-shell 22moption. + + 1mdefault-shell 4m22mpath0m + Specify the default shell. This is used as the login + shell for new windows when the 1mdefault-command 22moption is + set to empty, and must be the full path of the exe- + cutable. When started 1mtmux 22mtries to set a default value + from the first suitable of the SHELL environment vari- + able, the shell returned by getpwuid(3), or 4m/bin/sh24m. + This option should be configured when 1mtmux 22mis used as a + login shell. + + 1mdestroy-unattached 22m[1mon 22m| 1moff22m] + If enabled and the session is no longer attached to any + clients, it is destroyed. + + 1mdetach-on-destroy 22m[1mon 22m| 1moff22m] + If on (the default), the client is detached when the ses- + sion it is attached to is destroyed. If off, the client + is switched to the most recently active of the remaining + sessions. + + 1mdisplay-panes-active-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicator for the active pane. + + 1mdisplay-panes-colour 4m22mcolour0m + Set the colour used by the 1mdisplay-panes 22mcommand to show + the indicators for inactive panes. + + 1mdisplay-panes-time 4m22mtime0m + Set the time in milliseconds for which the indicators + shown by the 1mdisplay-panes 22mcommand appear. + + 1mdisplay-time 4m22mtime0m + Set the amount of time for which status line messages and + other on-screen indicators are displayed. 4mtime24m is in + milliseconds. + + 1mhistory-limit 4m22mlines0m + Set the maximum number of lines held in window history. + This setting applies only to new windows - existing win- + dow histories are not resized and retain the limit at the + point they were created. + + 1mlock-after-time 4m22mnumber0m + Lock the session (like the 1mlock-session 22mcommand) after + 4mnumber24m seconds of inactivity. The default is not to lock + (set to 0). + + 1mlock-command 4m22mshell-command0m + Command to run when locking each client. The default is + to run lock(1) with 1m-np22m. + + 1mmessage-command-style 4m22mstyle0m + Set status line message command style, where 4mstyle24m is a + comma-separated list of characteristics to be specified. + + These may be `bg=colour' to set the background colour, + `fg=colour' to set the foreground colour, and a list of + attributes as specified below. + + The colour is one of: 1mblack22m, 1mred22m, 1mgreen22m, 1myellow22m, 1mblue22m, + 1mmagenta22m, 1mcyan22m, 1mwhite22m, aixterm bright variants (if sup- + ported: 1mbrightred22m, 1mbrightgreen22m, and so on), 1mcolour0 22mto + 1mcolour255 22mfrom the 256-colour set, 1mdefault22m, or a hexadec- + imal RGB string such as `#ffffff', which chooses the + closest match from the default 256-colour set. + + The attributes is either 1mnone 22mor a comma-delimited list + of one or more of: 1mbright 22m(or 1mbold22m), 1mdim22m, 1munderscore22m, + 1mblink22m, 1mreverse22m, 1mhidden22m, or 1mitalics22m, to turn an attribute + on, or an attribute prefixed with `no' to turn one off. + + Examples are: + + fg=yellow,bold,underscore,blink + bg=black,fg=default,noreverse + + With the 1m-a 22mflag to the 1mset-option 22mcommand the new style + is added otherwise the existing style is replaced. + + 1mmessage-style 4m22mstyle0m + Set status line message style. For how to specify 4mstyle24m, + see the 1mmessage-command-style 22moption. + + 1mmouse 22m[1mon 22m| 1moff22m] + If on, 1mtmux 22mcaptures the mouse and allows mouse events to + be bound as key bindings. See the 4mMOUSE24m 4mSUPPORT24m section + for details. + + 1mmouse-utf8 22m[1mon 22m| 1moff22m] + If enabled, request mouse input as UTF-8 on UTF-8 termi- + nals. + + 1mprefix 4m22mkey0m + Set the key accepted as a prefix key. + + 1mprefix2 4m22mkey0m + Set a secondary key accepted as a prefix key. + + 1mrenumber-windows 22m[1mon 22m| 1moff22m] + If on, when a window is closed in a session, automati- + cally renumber the other windows in numerical order. + This respects the 1mbase-index 22moption if it has been set. + If off, do not renumber the windows. + + 1mrepeat-time 4m22mtime0m + Allow multiple commands to be entered without pressing + the prefix-key again in the specified 4mtime24m milliseconds + (the default is 500). Whether a key repeats may be set + when it is bound using the 1m-r 22mflag to 1mbind-key22m. Repeat + is enabled for the default keys bound to the 1mresize-pane0m + command. + + 1mset-remain-on-exit 22m[1mon 22m| 1moff22m] + Set the 1mremain-on-exit 22mwindow 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 + 1mrespawn-window 22mcommand to reactivate such a window, or + the 1mkill-window 22mcommand to destroy it. + + 1mset-titles 22m[1mon 22m| 1moff22m] + Attempt to set the client terminal title using the 4mtsl0m + and 4mfsl24m terminfo(5) entries if they exist. 1mtmux 22mautomat- + ically sets these to the \e]0;...\007 sequence if the + terminal appears to be xterm(1). This option is off by + default. + + 1mset-titles-string 4m22mstring0m + String used to set the window title if 1mset-titles 22mis on. + Formats are expanded, see the 4mFORMATS24m section. + + 1mstatus 22m[1mon 22m| 1moff22m] + Show or hide the status line. + + 1mstatus-interval 4m22minterval0m + Update the status bar every 4minterval24m seconds. By + default, updates will occur every 15 seconds. A setting + of zero disables redrawing at interval. + + 1mstatus-justify 22m[1mleft 22m| 1mcentre 22m| 1mright22m] + Set the position of the window list component of the sta- + tus line: left, centre or right justified. + + 1mstatus-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in the status line, + for example at the command prompt. The default is emacs, + unless the VISUAL or EDITOR environment variables are set + and contain the string `vi'. + + 1mstatus-left 4m22mstring0m + Display 4mstring24m (by default the session name) to the left + of the status bar. 4mstring24m will be passed through + strftime(3) and formats (see 4mFORMATS24m) will be expanded. + It may also contain any of the following special charac- + ter sequences: + + 1mCharacter pair Replaced with0m + #[attributes] Colour or attribute change + ## A literal `#' + + For details on how the names and titles can be set see + the 4mNAMES24m 4mAND24m 4mTITLES24m section. For a list of allowed + attributes see the 1mmessage-command-style 22moption. + + Examples are: + + #(sysctl vm.loadavg) + #[fg=yellow,bold]#(apm -l)%%#[default] [#S] + + By default, UTF-8 in 4mstring24m is not interpreted, to enable + UTF-8, use the 1mstatus-utf8 22moption. + + The default is `[#S] '. + + 1mstatus-left-length 4m22mlength0m + Set the maximum 4mlength24m of the left component of the sta- + tus bar. The default is 10. + + 1mstatus-left-style 4m22mstyle0m + Set the style of the left part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-position 22m[1mtop 22m| 1mbottom22m] + Set the position of the status line. + + 1mstatus-right 4m22mstring0m + Display 4mstring24m 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 1mstatus-left22m, 4mstring0m + will be passed to strftime(3), character pairs are + replaced, and UTF-8 is dependent on the 1mstatus-utf80m + option. + + 1mstatus-right-length 4m22mlength0m + Set the maximum 4mlength24m of the right component of the sta- + tus bar. The default is 40. + + 1mstatus-right-style 4m22mstyle0m + Set the style of the right part of the status line. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mstatus-style 4m22mstyle0m + Set status line style. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. + + 1mstatus-utf8 22m[1mon 22m| 1moff22m] + Instruct 1mtmux 22mto treat top-bit-set characters in the + 1mstatus-left 22mand 1mstatus-right 22mstrings as UTF-8; notably, + this is important for wide characters. This option + defaults to off. + + 1mupdate-environment 4m22mvariables0m + Set a space-separated string containing a list of envi- + ronment variables to be copied into the session environ- + ment 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 1m-r 22mwas given to the 1mset-environment0m + command). The default is "DISPLAY SSH_ASKPASS + SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU- + THORITY". + + 1mvisual-activity 22m[1mon 22m| 1moff22m] + If on, display a status line message when activity occurs + in a window for which the 1mmonitor-activity 22mwindow option + is enabled. + + 1mvisual-bell 22m[1mon 22m| 1moff22m] + 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 1mbell-action0m + option. + + 1mvisual-silence 22m[1mon 22m| 1moff22m] + If 1mmonitor-silence 22mis enabled, prints a message after the + interval has expired on a given window. + + 1mword-separators 4m22mstring0m + Sets the session's conception of what characters are con- + sidered word separators, for the purposes of the next and + previous word commands in copy mode. The default is + ` -_@'. + + 1mset-window-option 22m[1m-agoqu22m] [1m-t 4m22mtarget-window24m] 4moption24m 4mvalue0m + (alias: 1msetw22m) + Set a window option. The 1m-a22m, 1m-g22m, 1m-o22m, 1m-q 22mand 1m-u 22mflags work simi- + larly to the 1mset-option 22mcommand. + + Supported window options are: + + 1maggressive-resize 22m[1mon 22m| 1moff22m] + Aggressively resize the chosen window. This means that + 1mtmux 22mwill 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 SIGWINCH and poor for interactive programs + such as shells. + + 1mallow-rename 22m[1mon 22m| 1moff22m] + Allow programs to change the window name using a terminal + escape sequence (\033k...\033\\). The default is on. + + 1malternate-screen 22m[1mon 22m| 1moff22m] + This option configures whether programs running inside + 1mtmux 22mmay use the terminal alternate screen feature, which + allows the 4msmcup24m and 4mrmcup24m 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. + + 1mautomatic-rename 22m[1mon 22m| 1moff22m] + Control automatic window renaming. When this setting is + enabled, 1mtmux 22mwill rename the window automatically using + the format specified by 1mautomatic-rename-format22m. This + flag is automatically disabled for an individual window + when a name is specified at creation with 1mnew-window 22mor + 1mnew-session22m, or later with 1mrename-window22m, or with a ter- + minal escape sequence. It may be switched off globally + with: + + set-window-option -g automatic-rename off + + 1mautomatic-rename-format 4m22mformat0m + The format (see 4mFORMATS24m) used when the 1mautomatic-rename0m + option is enabled. + + 1mclock-mode-colour 4m22mcolour0m + Set clock colour. + + 1mclock-mode-style 22m[1m12 22m| 1m2422m] + Set clock hour format. + + 1mforce-height 4m22mheight0m + 1mforce-width 4m22mwidth0m + Prevent 1mtmux 22mfrom resizing a window to greater than 4mwidth0m + or 4mheight24m. A value of zero restores the default unlim- + ited setting. + + 1mmain-pane-height 4m22mheight0m + 1mmain-pane-width 4m22mwidth0m + Set the width or height of the main (left or top) pane in + the 1mmain-horizontal 22mor 1mmain-vertical 22mlayouts. + + 1mmode-keys 22m[1mvi 22m| 1memacs22m] + Use vi or emacs-style key bindings in copy and choice + modes. As with the 1mstatus-keys 22moption, the default is + emacs, unless VISUAL or EDITOR contains `vi'. + + 1mmode-style 4m22mstyle0m + Set window modes style. For how to specify 4mstyle24m, see + the 1mmessage-command-style 22moption. + + 1mmonitor-activity 22m[1mon 22m| 1moff22m] + Monitor for activity in the window. Windows with activ- + ity are highlighted in the status line. + + 1mmonitor-silence 22m[1minterval22m] + Monitor for silence (no activity) in the window within + 1minterval 22mseconds. Windows that have been silent for the + interval are highlighted in the status line. An interval + of zero disables the monitoring. + + 1mother-pane-height 4m22mheight0m + Set the height of the other panes (not the main pane) in + the 1mmain-horizontal 22mlayout. If this option is set to 0 + (the default), it will have no effect. If both the + 1mmain-pane-height 22mand 1mother-pane-height 22moptions are set, + the main pane will grow taller to make the other panes + the specified height, but will never shrink to do so. + + 1mother-pane-width 4m22mwidth0m + Like 1mother-pane-height22m, but set the width of other panes + in the 1mmain-vertical 22mlayout. + + 1mpane-active-border-style 4m22mstyle0m + Set the pane border style for the currently active pane. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. Attributes are ignored. + + 1mpane-base-index 4m22mindex0m + Like 1mbase-index22m, but set the starting index for pane num- + bers. + + 1mpane-border-style 4m22mstyle0m + Set the pane border style for panes aside from the active + pane. For how to specify 4mstyle24m, see the + 1mmessage-command-style 22moption. Attributes are ignored. + + 1mremain-on-exit 22m[1mon 22m| 1moff22m] + A window with this flag set is not destroyed when the + program running in it exits. The window may be reacti- + vated with the 1mrespawn-window 22mcommand. + + 1msynchronize-panes 22m[1mon 22m| 1moff22m] + Duplicate input to any pane to all other panes in the + same window (only for panes that are not in any special + mode). + + 1mutf8 22m[1mon 22m| 1moff22m] + Instructs 1mtmux 22mto expect UTF-8 sequences to appear in + this window. + + 1mwindow-active-style 4m22mstyle0m + Set the style for the window's active pane. For how to + specify 4mstyle24m, see the 1mmessage-command-style 22moption. + + 1mwindow-status-activity-style 4m22mstyle0m + Set status line style for windows with an activity alert. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-bell-style 4m22mstyle0m + Set status line style for windows with a bell alert. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-current-format 4m22mstring0m + Like 4mwindow-status-format24m, but is the format used when + the window is the current window. + + 1mwindow-status-current-style 4m22mstyle0m + Set status line style for the currently active window. + For how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-format 4m22mstring0m + Set the format in which the window is displayed in the + status line window list. See the 4mstatus-left24m option for + details of special character sequences available. The + default is `#I:#W#F'. + + 1mwindow-status-last-style 4m22mstyle0m + Set status line style for the last active window. For + how to specify 4mstyle24m, see the 1mmessage-command-style0m + option. + + 1mwindow-status-separator 4m22mstring0m + Sets the separator drawn between windows in the status + line. The default is a single space character. + + 1mwindow-status-style 4m22mstyle0m + Set status line style for a single window. For how to + specify 4mstyle24m, see the 1mmessage-command-style 22moption. + + 1mwindow-style 4m22mstyle0m + Set the default window style. For how to specify 4mstyle24m, + see the 1mmessage-command-style 22moption. + + 1mxterm-keys 22m[1mon 22m| 1moff22m] + If this option is set, 1mtmux 22mwill generate xterm(1) -style + function key sequences; these have a number included to + indicate modifiers such as Shift, Alt or Ctrl. The + default is off. + + 1mwrap-search 22m[1mon 22m| 1moff22m] + If this option is set, searches will wrap around the end + of the pane contents. The default is on. + + 1mshow-options 22m[1m-gqsvw22m] [1m-t 4m22mtarget-session24m | 4mtarget-window24m] [4moption24m] + (alias: 1mshow22m) + Show the window options (or a single window option if given) with + 1m-w 22m(equivalent to 1mshow-window-options22m), the server options with + 1m-s22m, otherwise the session options for 4mtarget24m 4msession24m. Global + session or window options are listed if 1m-g 22mis used. 1m-v 22mshows + only the option value, not the name. If 1m-q 22mis set, no error will + be returned if 4moption24m is unset. + + 1mshow-window-options 22m[1m-gv22m] [1m-t 4m22mtarget-window24m] [4moption24m] + (alias: 1mshoww22m) + List the window options or a single option for 4mtarget-window24m, or + the global window options if 1m-g 22mis used. 1m-v 22mshows only the + option value, not the name. + +1mMOUSE SUPPORT0m + If the 1mmouse 22moption is on (the default is off), 1mtmux 22mallows mouse events + to be bound as keys. The name of each key is made up of a mouse event + (such as `MouseUp1') and a location suffix (one of `Pane' for the con- + tents of a pane, `Border' for a pane border or `Status' for the status + line). The following mouse events are available: + + MouseDown1 MouseUp1 MouseDrag1 + MouseDown2 MouseUp2 MouseDrag2 + MouseDown3 MouseUp3 MouseDrag3 + WheelUp WheelDown + + Each should be suffixed with a location, for example `MouseDown1Status'. + + The special token `{mouse}' or `=' may be used as 4mtarget-window24m or + 4mtarget-pane24m in commands bound to mouse key bindings. It resolves to the + window or pane over which the mouse event took place (for example, the + window in the status line over which button 1 was released for a + `MouseUp1Status' binding, or the pane over which the wheel was scrolled + for a `WheelDownPane' binding). + + The 1msend-keys -M 22mflag may be used to forward a mouse event to a pane. + + The default key bindings allow the mouse to be used to select and resize + panes, to copy text and to change window using the status line. These + take effect if the 1mmouse 22moption is turned on. + +1mFORMATS0m + Certain commands accept the 1m-F 22mflag with a 4mformat24m argument. This is a + string which controls the output format of the command. Replacement + variables are enclosed in `#{' and `}', for example `#{session_name}'. + The possible variables are listed in the table below, or the name of a + 1mtmux 22moption may be used for an option's value. Some variables have a + shorter alias such as `#S', and `##' is replaced by a single `#'. + + Conditionals are available by prefixing with `?' 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 `#{?session_attached,attached,not attached}' will include the + string `attached' if the session is attached and the string `not + attached' if it is unattached, or `#{?automatic-rename,yes,no}' will + include `yes' if 1mautomatic-rename 22mis enabled, or `no' if not. A limit + may be placed on the length of the resultant string by prefixing it by an + `=', a number and a colon, so `#{=10:pane_title}' will include at most + the first 10 characters of the pane title. + + In addition, the first line of a shell command's output may be inserted + using `#()'. For example, `#(uptime)' will insert the system's uptime. + When constructing formats, 1mtmux 22mdoes not wait for `#()' commands to fin- + ish; instead, the previous result from running the same command is used, + or a placeholder if the command has not been run before. Commands are + executed with the 1mtmux 22mglobal environment set (see the 4mENVIRONMENT24m sec- + tion). + + The following variables are available, where appropriate: + + 1mVariable name Alias Replaced with0m + alternate_on If pane is in alternate screen + alternate_saved_x Saved cursor X in alternate screen + alternate_saved_y Saved cursor Y in alternate screen + buffer_sample Sample of start of buffer + buffer_size Size of the specified buffer in bytes + client_activity Integer time client last had activity + client_activity_string String time client last had activity + client_created Integer time client created + client_created_string String time client created + client_control_mode 1 if client is in control mode + client_height Height of client + client_last_session Name of the client's last session + client_pid PID of client process + client_prefix 1 if prefix key has been pressed + client_readonly 1 if client is readonly + client_session Name of the client's session + client_termname Terminal name of client + client_tty Pseudo terminal of client + client_utf8 1 if client supports utf8 + client_width Width of client + cursor_flag Pane cursor flag + cursor_x Cursor X position in pane + cursor_y Cursor Y position in pane + history_bytes Number of bytes in window history + history_limit Maximum window history lines + history_size Size of history in bytes + host #H Hostname of local host + host_short #h Hostname of local host (no domain name) + insert_flag Pane insert flag + keypad_cursor_flag Pane keypad cursor flag + keypad_flag Pane keypad flag + line Line number in the list + mouse_any_flag Pane mouse any flag + mouse_button_flag Pane mouse button flag + mouse_standard_flag Pane mouse standard flag + mouse_utf8_flag Pane mouse UTF-8 flag + pane_active 1 if active pane + pane_bottom Bottom of pane + pane_current_command Current command if available + pane_current_path Current path if available + pane_dead 1 if pane is dead + pane_dead_status Exit status of process in dead pane + pane_height Height of pane + pane_id #D Unique pane ID + pane_in_mode If pane is in a mode + pane_input_off If input to pane is disabled + pane_index #P Index of pane + pane_left Left of pane + pane_pid PID of first process in pane + pane_right Right of pane + pane_start_command Command pane started with + pane_synchronized If pane is synchronized + pane_tabs Pane tab positions + pane_title #T Title of pane + pane_top Top of pane + pane_tty Pseudo terminal of pane + pane_width Width of pane + pid Server PID + scroll_region_lower Bottom of scroll region in pane + scroll_region_upper Top of scroll region in pane + session_alerts List of window indexes with alerts + session_attached Number of clients session is attached to + session_activity Integer time of session last activity + session_activity_string String time of session last activity + session_created Integer time session created + session_created_string String time session created + session_last_attached Integer time session last attached + session_last_attached_string String time session last attached + session_group Number of session group + session_grouped 1 if session in a group + session_height Height of session + session_id Unique session ID + session_many_attached 1 if multiple clients attached + session_name #S Name of session + session_width Width of session + session_windows Number of windows in session + window_activity Integer time of window last activity + window_activity_string String time of window last activity + window_active 1 if window active + window_activity_flag 1 if window has activity alert + window_bell_flag 1 if window has bell + window_find_matches Matched data from the find-window + window_flags #F Window flags + window_height Height of window + window_id Unique window ID + window_index #I Index of window + window_last_flag 1 if window is the last used + window_layout Window layout description + window_linked 1 if window is linked across sessions + window_name #W Name of window + window_panes Number of panes in window + window_silence_flag 1 if window has silence alert + window_width Width of window + window_zoomed_flag 1 if window is zoomed + wrap_flag Pane wrap flag + +1mNAMES AND TITLES0m + 1mtmux 22mdistinguishes 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 1mtmux 22midentifier 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 1mtmux22m. + It is the same mechanism used to set for example the xterm(1) window + title in an X(7) window manager. Windows themselves do not have titles - + a window's title is the title of its active pane. 1mtmux 22mitself may set + the title of the terminal in which the client is running, see the + 1mset-titles 22moption. + + A session's name is set with the 1mnew-session 22mand 1mrename-session 22mcommands. + A window's name is set with one of: + + 1. A command argument (such as 1m-n 22mfor 1mnew-window 22mor 1mnew-session22m). + + 2. An escape sequence: + + $ printf '\033kWINDOW_NAME\033\\' + + 3. Automatic renaming, which sets the name to the active command in + the window's active pane. See the 1mautomatic-rename 22moption. + + 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: + + $ printf '\033]2;My Title\033\\' + +1mENVIRONMENT0m + When the server is started, 1mtmux 22mcopies the environment into the 4mglobal0m + 4menvironment24m; in addition, each session has a 4msession24m 4menvironment24m. 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. + + The 1mupdate-environment 22msession option may be used to update the session + environment from the client when a new session is created or an old reat- + tached. 1mtmux 22malso initialises the TMUX variable with some internal + information to allow commands to be executed from inside, and the TERM + variable with the correct terminal setting of `screen'. + + Commands to alter and view the environment are: + + 1mset-environment 22m[1m-gru22m] [1m-t 4m22mtarget-session24m] 4mname24m [4mvalue24m] + (alias: 1msetenv22m) + Set or unset an environment variable. If 1m-g 22mis used, the change + is made in the global environment; otherwise, it is applied to + the session environment for 4mtarget-session24m. The 1m-u 22mflag unsets a + variable. 1m-r 22mindicates the variable is to be removed from the + environment before starting a new process. + + 1mshow-environment 22m[1m-gs22m] [1m-t 4m22mtarget-session24m] [4mvariable24m] + (alias: 1mshowenv22m) + Display the environment for 4mtarget-session24m or the global environ- + ment with 1m-g22m. If 4mvariable24m is omitted, all variables are shown. + Variables removed from the environment are prefixed with `-'. If + 1m-s 22mis used, the output is formatted as a set of Bourne shell com- + mands. + +1mSTATUS LINE0m + 1mtmux 22mincludes 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 1mstatus 22msession 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. + + The status line is made of three parts: configurable left and right sec- + tions (which may contain dynamic content such as the time or output from + a shell command, see the 1mstatus-left22m, 1mstatus-left-length22m, 1mstatus-right22m, + and 1mstatus-right-length 22moptions 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 4mwindow-status-format24m and + 4mwindow-status-current-format24m options. The flag is one of the following + symbols appended to the window name: + + 1mSymbol Meaning0m + * Denotes the current window. + - Marks the last window (previously selected). + # Window is monitored and activity has been detected. + ! A bell has occurred in the window. + ~ The window has been silent for the monitor-silence + interval. + M The window contains the marked pane. + Z The window's active pane is zoomed. + + The # symbol relates to the 1mmonitor-activity 22mwindow option. The window + name is printed in inverted colours if an alert (bell, activity or + silence) is present. + + The colour and attributes of the status line may be configured, the + entire status line using the 1mstatus-style 22msession option and individual + windows using the 1mwindow-status-style 22mwindow option. + + The status line is automatically refreshed at interval if it has changed, + the interval may be controlled with the 1mstatus-interval 22msession option. + + Commands related to the status line are as follows: + + 1mcommand-prompt 22m[1m-I 4m22minputs24m] [1m-p 4m22mprompts24m] [1m-t 4m22mtarget-client24m] [4mtemplate24m] + Open the command prompt in a client. This may be used from + inside 1mtmux 22mto execute commands interactively. + + If 4mtemplate24m is specified, it is used as the command. If present, + 1m-I 22mis a comma-separated list of the initial text for each prompt. + If 1m-p 22mis given, 4mprompts24m is a comma-separated list of prompts + which are displayed in order; otherwise a single prompt is dis- + played, constructed from 4mtemplate24m if it is present, or `:' if + not. + + Both 4minputs24m and 4mprompts24m may contain the special character + sequences supported by the 1mstatus-left 22moption. + + Before the command is executed, the first occurrence of the + string `%%' and all occurrences of `%1' are replaced by the + response to the first prompt, the second `%%' and all `%2' are + replaced with the response to the second prompt, and so on for + further prompts. Up to nine prompt responses may be replaced + (`%1' to `%9'). + + 1mconfirm-before 22m[1m-p 4m22mprompt24m] [1m-t 4m22mtarget-client24m] 4mcommand0m + (alias: 1mconfirm22m) + Ask for confirmation before executing 4mcommand24m. If 1m-p 22mis given, + 4mprompt24m is the prompt to display; otherwise a prompt is con- + structed from 4mcommand24m. It may contain the special character + sequences supported by the 1mstatus-left 22moption. + + This command works only from inside 1mtmux22m. + + 1mdisplay-message 22m[1m-p22m] [1m-c 4m22mtarget-client24m] [1m-t 4m22mtarget-pane24m] [4mmessage24m] + (alias: 1mdisplay22m) + Display a message. If 1m-p 22mis given, the output is printed to std- + out, otherwise it is displayed in the 4mtarget-client24m status line. + The format of 4mmessage24m is described in the 4mFORMATS24m section; infor- + mation is taken from 4mtarget-pane24m if 1m-t 22mis given, otherwise the + active pane for the session attached to 4mtarget-client24m. + +1mBUFFERS0m + 1mtmux 22mmaintains a set of named 4mpaste24m 4mbuffers24m. Each buffer may be either + explicitly or automatically named. Explicitly named buffers are named + when created with the 1mset-buffer 22mor 1mload-buffer 22mcommands, or by renaming + an automatically named buffer with 1mset-buffer -n22m. Automatically named + buffers are given a name such as `buffer0001', `buffer0002' and so on. + When the 1mbuffer-limit 22moption is reached, the oldest automatically named + buffer is deleted. Explicitly named are not subject to 1mbuffer-limit 22mand + may be deleted with 1mdelete-buffer 22mcommand. + + Buffers may be added using 1mcopy-mode 22mor the 1mset-buffer 22mand 1mload-buffer0m + commands, and pasted into a window using the 1mpaste-buffer 22mcommand. If a + buffer command is used and no buffer is specified, the most recently + added automatically named buffer is assumed. + + A configurable history buffer is also maintained for each window. By + default, up to 2000 lines are kept; this can be altered with the + 1mhistory-limit 22moption (see the 1mset-option 22mcommand above). + + The buffer commands are as follows: + + 1mchoose-buffer 22m[1m-F 4m22mformat24m] [1m-t 4m22mtarget-window24m] [4mtemplate24m] + Put a window into buffer choice mode, where a buffer may be cho- + sen interactively from a list. After a buffer is selected, `%%' + is replaced by the buffer name in 4mtemplate24m and the result exe- + cuted as a command. If 4mtemplate24m is not given, "paste-buffer -b + '%%'" is used. For the meaning of the 1m-F 22mflag, see the 4mFORMATS0m + section. This command works only if at least one client is + attached. + + 1mclear-history 22m[1m-t 4m22mtarget-pane24m] + (alias: 1mclearhist22m) + Remove and free the history for the specified pane. + + 1mdelete-buffer 22m[1m-b 4m22mbuffer-name24m] + (alias: 1mdeleteb22m) + Delete the buffer named 4mbuffer-name24m, or the most recently added + automatically named buffer if not specified. + + 1mlist-buffers 22m[1m-F 4m22mformat24m] + (alias: 1mlsb22m) + List the global buffers. For the meaning of the 1m-F 22mflag, see the + 4mFORMATS24m section. + + 1mload-buffer 22m[1m-b 4m22mbuffer-name24m] 4mpath0m + (alias: 1mloadb22m) + Load the contents of the specified paste buffer from 4mpath24m. + + 1mpaste-buffer 22m[1m-dpr22m] [1m-b 4m22mbuffer-name24m] [1m-s 4m22mseparator24m] [1m-t 4m22mtarget-pane24m] + (alias: 1mpasteb22m) + Insert the contents of a paste buffer into the specified pane. + If not specified, paste into the current one. With 1m-d22m, also + delete the paste buffer. When output, any linefeed (LF) charac- + ters in the paste buffer are replaced with a separator, by + default carriage return (CR). A custom separator may be speci- + fied using the 1m-s 22mflag. The 1m-r 22mflag means to do no replacement + (equivalent to a separator of LF). If 1m-p 22mis specified, paste + bracket control codes are inserted around the buffer if the + application has requested bracketed paste mode. + + 1msave-buffer 22m[1m-a22m] [1m-b 4m22mbuffer-name24m] 4mpath0m + (alias: 1msaveb22m) + Save the contents of the specified paste buffer to 4mpath24m. The 1m-a0m + option appends to rather than overwriting the file. + + 1mset-buffer 22m[1m-a22m] [1m-b 4m22mbuffer-name24m] [1m-n 4m22mnew-buffer-name24m] 4mdata0m + (alias: 1msetb22m) + Set the contents of the specified buffer to 4mdata24m. The 1m-a 22moption + appends to rather than overwriting the buffer. The 1m-n 22moption + renames the buffer to 4mnew-buffer-name24m. + + 1mshow-buffer 22m[1m-b 4m22mbuffer-name24m] + (alias: 1mshowb22m) + Display the contents of the specified buffer. + +1mMISCELLANEOUS0m + Miscellaneous commands are as follows: + + 1mclock-mode 22m[1m-t 4m22mtarget-pane24m] + Display a large clock. + + 1mif-shell 22m[1m-bF22m] [1m-t 4m22mtarget-pane24m] 4mshell-command24m 4mcommand24m [4mcommand24m] + (alias: 1mif22m) + Execute the first 4mcommand24m if 4mshell-command24m returns success or the + second 4mcommand24m otherwise. Before being executed, 4mshell-command0m + is expanded using the rules specified in the 4mFORMATS24m section, + including those relevant to 4mtarget-pane24m. With 1m-b22m, 4mshell-command0m + is run in the background. + + If 1m-F 22mis given, 4mshell-command24m is not executed but considered suc- + cess if neither empty nor zero (after formats are expanded). + + 1mlock-server0m + (alias: 1mlock22m) + Lock each client individually by running the command specified by + the 1mlock-command 22moption. + + 1mrun-shell 22m[1m-b22m] [1m-t 4m22mtarget-pane24m] 4mshell-command0m + (alias: 1mrun22m) + Execute 4mshell-command24m in the background without creating a win- + dow. Before being executed, shell-command is expanded using the + rules specified in the 4mFORMATS24m section. With 1m-b22m, the command is + run in the background. After it finishes, any output to stdout + is displayed in copy mode (in the pane specified by 1m-t 22mor the + current pane if omitted). If the command doesn't return success, + the exit status is also displayed. + + 1mwait-for 22m[1m-L 22m| 1m-S 22m| 1m-U22m] 4mchannel0m + (alias: 1mwait22m) + When used without options, prevents the client from exiting until + woken using 1mwait-for -S 22mwith the same channel. When 1m-L 22mis 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 + 1mwait-for -U22m. This command only works from outside 1mtmux22m. + +1mTERMINFO EXTENSIONS0m + 1mtmux 22munderstands some extensions to terminfo(5): + + 4mCs24m, 4mCr24m 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 1mtmux22m: + + $ printf '\033]12;red\033\\' + + 4mSs24m, 4mSe24m Set or reset the cursor style. If set, a sequence such as this + may be used to change the cursor to an underline: + + $ printf '\033[4 q' + + If 4mSe24m is not set, Ss with argument 0 will be used to reset the + cursor style instead. + + 4mMs24m This sequence can be used by 1mtmux 22mto store the current buffer in + the host terminal's selection (clipboard). See the 4mset-clipboard0m + option above and the xterm(1) man page. + +1mCONTROL MODE0m + 1mtmux 22moffers a textual interface called 4mcontrol24m 4mmode24m. This allows appli- + cations to communicate with 1mtmux 22musing a simple text-only protocol. + + In control mode, a client sends 1mtmux 22mcommands or command sequences termi- + nated by newlines on standard input. Each command will produce one block + of output on standard output. An output block consists of a 4m%begin24m line + followed by the output (which may be empty). The output block ends with + a 4m%end24m or 4m%error24m. 4m%begin24m and matching 4m%end24m or 4m%error24m have two arguments: + an integer time (as seconds from epoch) and command number. For example: + + %begin 1363006971 2 + 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active) + %end 1363006971 2 + + In control mode, 1mtmux 22moutputs notifications. A notification will never + occur inside an output block. + + The following notifications are defined: + + 1m%exit 22m[4mreason24m] + The 1mtmux 22mclient is exiting immediately, either because it is not + attached to any session or an error occurred. If present, 4mreason0m + describes why the client exited. + + 1m%layout-change 4m22mwindow-id24m 4mwindow-layout0m + The layout of a window with ID 4mwindow-id24m changed. The new layout + is 4mwindow-layout24m. + + 1m%output 4m22mpane-id24m 4mvalue0m + A window pane produced output. 4mvalue24m escapes non-printable char- + acters and backslash as octal \xxx. + + 1m%session-changed 4m22msession-id24m 4mname0m + The client is now attached to the session with ID 4msession-id24m, + which is named 4mname24m. + + 1m%session-renamed 4m22mname0m + The current session was renamed to 4mname24m. + + 1m%sessions-changed0m + A session was created or destroyed. + + 1m%unlinked-window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was created but is not linked to the + current session. + + 1m%window-add 4m22mwindow-id0m + The window with ID 4mwindow-id24m was linked to the current session. + + 1m%window-close 4m22mwindow-id0m + The window with ID 4mwindow-id24m closed. + + 1m%window-renamed 4m22mwindow-id24m 4mname0m + The window with ID 4mwindow-id24m was renamed to 4mname24m. + +1mFILES0m + ~/.tmux.conf Default 1mtmux 22mconfiguration file. + @SYSCONFDIR@/tmux.conf System-wide configuration file. + +1mEXAMPLES0m + To create a new 1mtmux 22msession running vi(1): + + $ tmux new-session vi + + Most commands have a shorter form, known as an alias. For new-session, + this is 1mnew22m: + + $ tmux new vi + + Alternatively, the shortest unambiguous form of a command is accepted. + If there are several options, they are listed: + + $ tmux n + ambiguous command: n, could be: new-session, new-window, next-window + + Within an active session, a new window may be created by typing `C-b c' + (Ctrl followed by the `b' key followed by the `c' key). + + Windows may be navigated with: `C-b 0' (to select window 0), `C-b 1' (to + select window 1), and so on; `C-b n' to select the next window; and `C-b + p' to select the previous window. + + A session may be detached using `C-b d' (or by an external event such as + ssh(1) disconnection) and reattached with: + + $ tmux attach-session + + Typing `C-b ?' lists the current key bindings in the current window; up + and down may be used to navigate the list or `q' to exit from it. + + Commands to be run when the 1mtmux 22mserver is started may be placed in the + 4m~/.tmux.conf24m configuration file. Common examples include: + + Changing the default prefix key: + + set-option -g prefix C-a + unbind-key C-b + bind-key C-a send-prefix + + Turning the status line off, or changing its colour: + + set-option -g status off + set-option -g status-style bg=blue + + Setting other options, such as the default command, or locking after 30 + minutes of inactivity: + + set-option -g default-command "exec /bin/ksh" + set-option -g lock-after-time 1800 + + Creating new key bindings: + + 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'" + +1mSEE ALSO0m + pty(7) + +1mAUTHORS0m + Nicholas Marriott <4mnicm@users.sourceforge.net24m> + +FreeBSD 11.0 November 6, 2015 FreeBSD 11.0 diff --git a/manual/NOTES.rst b/manual/NOTES.rst new file mode 100644 index 0000000..080d4bf --- /dev/null +++ b/manual/NOTES.rst @@ -0,0 +1,88 @@ +=================== +Compatibility notes +=================== + +master +------ + +src: http://sourceforge.net/p/tmux/tmux-code/ci/master/tree/ + +1.8 +--- + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.8/tree/ + +1.7 +--- + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.7/tree/ + +1.6 +--- + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.6/tree/ + +new-window +"""""""""" + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.6/tree/cmd-new-window.c + +.. code-block:: c + + if (args_has(args, 'P')) + ctx->print(ctx, "%s:%u", s->name, wl->idx); + return (0); + +split-window +"""""""""""" + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.6/tree/cmd-split-window.c + +.. code-block:: c + + if (args_has(args, 'P')) { + if (window_pane_index(new_wp, &paneidx) != 0) + fatalx("index not found"); + ctx->print(ctx, "%s:%u.%u", s->name, wl->idx, paneidx); + } + return (0); + +list-sessions +""""""""""""" + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.6/tree/cmd-list-sessions.c + +.. code-block:: c + + template = "#{session_name}: #{session_windows} windows " + "(created #{session_created_string}) [#{session_width}x" + "#{session_height}]#{?session_grouped, (group ,}" + "#{session_group}#{?session_grouped,),}" + "#{?session_attached, (attached),}"; + +list-windows +"""""""""""" + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.6/tree/cmd-list-windows.c + +.. code-block:: c + + template = "#{session_name}:#{window_index}: " + "#{window_name} " + "[#{window_width}x#{window_height}] " + "[layout #{window_layout}]" + "#{?window_active, (active),}"; + + +list-panes +"""""""""" + +src: http://sourceforge.net/p/tmux/tmux-code/ci/1.6/tree/cmd-list-panes.c + +.. code-block:: c + + template = "#{session_name}:#{window_index}.#{pane_index}: " + "[#{pane_width}x#{pane_height}] [history " + "#{history_size}/#{history_limit}, " + "#{history_bytes} bytes] #{pane_id}" + "#{?pane_active, (active),}#{?pane_dead, (dead),}"; diff --git a/manual/README.rst b/manual/README.rst new file mode 100644 index 0000000..161af64 --- /dev/null +++ b/manual/README.rst @@ -0,0 +1,26 @@ +For studying the differences between prior tmux versions to check +compatibility with legacy versions. + +Get source: + +.. code-block:: bash + + $ git clone git://git.code.sf.net/p/tmux/tmux-code tmux-tmux-code tmux + $ cd tmux + +Converted with: + +.. code-block:: bash + + $ git checkout + $ ./configure + $ make + $ groff -t -e -mandoc -Tascii tmux.1 | col -bx > manpage.txt + +repeat for versions. + +Create a git-diff style diff of version manuals: + +.. code-block:: bash + + $ diff -u 1.6 1.8 > 1_6__1_8.diff diff --git a/pane.rst b/pane.rst new file mode 100644 index 0000000..4a64ddd --- /dev/null +++ b/pane.rst @@ -0,0 +1,8 @@ +.. _pane: + +==== +Pane +==== + +A ptty. + diff --git a/plugins.rst b/plugins.rst new file mode 100644 index 0000000..e93e1f2 --- /dev/null +++ b/plugins.rst @@ -0,0 +1,40 @@ +.. _plugins: + +======= +Plugins +======= + +There are a plethora of plugins available for tmux + +Status lines +------------ + +Tmux allows configuring a status line that displays system information, +window list, and even pipe in the ``stdout`` of an application. + +You can use `tmux-mem-cpu-load`_ to get stats (requires compilation) and +`basic-cpu-and-memory.tmux`_. You can pipe in a bash command to a tmux +status line like: + +.. code-block:: ini + + $(shell-command) + +So if ``/usr/local/bin/tmux-mem-cpu-load`` outputs stats to +``stdout``, then ``$(tmux-mem-cpu-load)`` is going to output the first +line to the status line. The interval is determined by the +``status-interval``:: + + set -g status-interval 1 + +.. _tmux-mem-cpu-load: https://github.com/thewtex/tmux-mem-cpu-load +.. _basic-cpu-and-memory.tmux: https://github.com/zaiste/tmuxified/blob/master/scripts/basic-cpu-and-memory.tmux + +Examples +-------- + +- https://github.com/tony/tmux-config - works with tmux 1.5+. Supports + screen's ``ctrl-a`` :ref:`Prefix key`. Support for system cpu, memory, + uptime stats. +- Add yours, edit this page on github. + diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..0211b2e --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +docutils +sphinx +pillow +aafigure diff --git a/server.rst b/server.rst new file mode 100644 index 0000000..7c41976 --- /dev/null +++ b/server.rst @@ -0,0 +1,15 @@ +.. _server: + +====== +Server +====== + +tmux automatically starts a background server upon starting. + +Contains one or more :ref:`session`\s. + +There is no init / service / upstart script so to speak. It's done for you +in the background. + +This is how you're able :ref:`resume your command line session `. + diff --git a/session.rst b/session.rst new file mode 100644 index 0000000..9478427 --- /dev/null +++ b/session.rst @@ -0,0 +1,8 @@ +.. _session: + +======= +Session +======= + +Contains one or more :ref:`window`\s. + diff --git a/shortcuts.rst b/shortcuts.rst new file mode 100644 index 0000000..52ddb59 --- /dev/null +++ b/shortcuts.rst @@ -0,0 +1,83 @@ +.. _shortcuts: +.. _keybindings: + +========= +Shortcuts +========= + +.. tip:: + + :ref:`Prefix key` is pressed before a short cut! + +=================== ==================================================== +Short cut Action +------------------- ---------------------------------------------------- +``C-b`` Send the prefix key (C-b) through to the + application. +``C-o`` Rotate the panes in the current window forwards. +``C-z`` Suspend the tmux client. +``!`` Break the current pane out of the window. +``"`` Split the current pane into two, top and bottom. +``#`` List all paste buffers. +``$`` Rename the current session. +``%`` Split the current pane into two, left and right. +``&`` Kill the current window. +``'`` Prompt for a window index to select. +``,`` Rename the current window. +``-`` Delete the most recently copied buffer of text. +``.`` Prompt for an index to move the current window. +``0 to 9`` Select windows 0 to 9. +``:`` Enter the tmux command prompt. +``;`` Move to the previously active pane. +``=`` Choose which buffer to paste interactively from a + list. +``?`` List all key bindings. +``D`` Choose a client to detach. +``[`` Enter copy mode to copy text or view the history. +``]`` Paste the most recently copied buffer of text. +``c`` Create a new window. +``d`` Detach the current client. +``f`` Prompt to search for text in open windows. +``i`` Display some information about the current window. +``l`` Move to the previously selected window. +``n`` Change to the next window. +``o`` Select the next pane in the current window. +``p`` Change to the previous window. +``q`` Briefly display pane indexes. +``r`` Force redraw of the attached client. +``s`` Select a new session for the attached client + interactively. +``L`` Switch the attached client back to the last session. +``t`` Show the time. +``w`` Choose the current window interactively. +``x`` Kill the current pane. +``{`` Swap the current pane with the previous pane. +``}`` Swap the current pane with the next pane. +``~`` Show previous messages from tmux, if any. +``Page Up`` Enter copy mode and scroll one page up. +``Up, Down`` Change to the pane above, below, to the left, or to +``Left, Right`` the right of the current pane. +``M-1 to M-5`` Arrange panes in one of the five preset layouts: + even-horizontal, even-vertical, main-horizontal, + main-vertical, or tiled. +``M-n`` Move to the next window with a bell or activity + marker. +``M-o`` Rotate the panes in the current window backwards. +``M-p`` Move to the previous window with a bell or activity + marker. +``C-Up, C-Down`` Resize the current pane in steps of one cell. +``C-Left, C-Right`` +``M-Up, M-Down`` Resize the current pane in steps of five cells. +``M-Left, M-Right`` +=================== ==================================================== + +Source: tmux manpage [1]_. + +To get the text documentation of a ``.1`` manual file: + +.. code-block:: bash + + $ nroff -mdoc tmux.1|less + +.. [1] http://sourceforge.net/p/tmux/tmux-code/ci/master/tree/tmux.1 + diff --git a/toc.rst b/toc.rst new file mode 100644 index 0000000..87bd9e7 --- /dev/null +++ b/toc.rst @@ -0,0 +1,20 @@ +.. _toc: +.. _table_of_contents: + +================= +Table of Contents +================= + +.. toctree:: + :maxdepth: 2 + + basic_usage + configuration + shortcuts + server + session + window + pane + plugins + changes + internals diff --git a/window.rst b/window.rst new file mode 100644 index 0000000..8e3549d --- /dev/null +++ b/window.rst @@ -0,0 +1,8 @@ +.. _window: + +====== +Window +====== + +Contains one or more :ref:`pane`\s. +