From ead3ff33f3b2984f16892e1fff0c494209b51b01 Mon Sep 17 00:00:00 2001 From: Foo Date: Thu, 14 Jul 2016 01:25:10 +0300 Subject: [PATCH] Add warning regarding segments that use cwd to tmux usage docs --- docs/source/configuration/reference.rst | 2 ++ docs/source/usage/other.rst | 23 +++++++++++++++++++++++ docs/source/usage/shell-prompts.rst | 2 ++ 3 files changed, 27 insertions(+) diff --git a/docs/source/configuration/reference.rst b/docs/source/configuration/reference.rst index 99b32be1..c93cc0ce 100644 --- a/docs/source/configuration/reference.rst +++ b/docs/source/configuration/reference.rst @@ -191,6 +191,8 @@ Common configuration is a subdictionary that is a value of ``ext`` key in ``{output : theme_name}`` that maps the ``xrandr`` output names to the local themes to use on that output. +.. _config-ext-components: + ``components`` Determines which extension components should be enabled. This key is highly extension-specific, here is the table of extensions and corresponding diff --git a/docs/source/usage/other.rst b/docs/source/usage/other.rst index 1215dd91..18d25d99 100644 --- a/docs/source/usage/other.rst +++ b/docs/source/usage/other.rst @@ -100,6 +100,29 @@ root `):: to :file:`.tmux.conf`. +.. warning:: + Segments which depend on current working directory (e.g. + :py:func:`powerline.segments.common.vcs.branch`) require also setting up + :ref:`shell bindings `. It is not required to use powerline + shell prompt, :ref:`components setting ` allows to + set up only powerline bindings for tmux without altering your prompt. + Without setting up shell bindings powerline will use current working + directory of *tmux server* which is probably not what you need. + + Segments which depend on environment like + :py:func:`powerline.segments.common.env.virtualenv` will not work at all + (i.e. they will use environment of the tmux server), tracking environment + changes is going to slow down shell a lot. + + In any case it is suggested to avoid both kinds of segments in tmux + :ref:`themes ` because even support for tracking current + directory is very limited: + + #. It works only in shell. Should you e.g. run Vim and run ``:cd`` there you + will get current working directory from shell. + #. It works only in local shell and requires configuring it. + #. Some shells are not supported at all. + IPython prompt ============== diff --git a/docs/source/usage/shell-prompts.rst b/docs/source/usage/shell-prompts.rst index 2ad85365..0a5c1f38 100644 --- a/docs/source/usage/shell-prompts.rst +++ b/docs/source/usage/shell-prompts.rst @@ -1,3 +1,5 @@ +.. _usage-shell: + ************* Shell prompts *************