summaryrefslogtreecommitdiffstats
path: root/docs/source/troubleshooting.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/source/troubleshooting.rst333
1 files changed, 333 insertions, 0 deletions
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
new file mode 100644
index 0000000..2b91747
--- /dev/null
+++ b/docs/source/troubleshooting.rst
@@ -0,0 +1,333 @@
+***************
+Troubleshooting
+***************
+
+System-specific issues
+======================
+
+.. toctree::
+
+ Linux <troubleshooting/linux>
+ OS X <troubleshooting/osx>
+
+Common issues
+=============
+
+After an update something stopped working
+-----------------------------------------
+
+Assuming powerline was working before update and stopped only after there are
+two possible explanations:
+
+* You have more then one powerline installation (e.g. ``pip`` and ``Vundle``
+ installations) and you have updated only one.
+* Update brought some bug to powerline.
+
+In the second case you, of course, should report the bug to `powerline bug
+tracker <https://github.com/powerline/powerline>`_. In the first you should
+make sure you either have only one powerline installation or you update all of
+them simultaneously (beware that in the second case you are not supported). To
+diagnose this problem you may do the following:
+
+#) If this problem is observed within the shell make sure that
+
+ .. code-block:: sh
+
+ python -c 'import powerline; print (powerline.__file__)'
+
+ which should report something like
+ :file:`/usr/lib64/python2.7/site-packages/powerline/__init__.pyc` (if
+ powerline is installed system-wide) or
+ :file:`/home/USER/.../powerline/__init__.pyc` (if powerline was cloned
+ somewhere, e.g. in :file:`/home/USER/.vim/bundle/powerline`) reports the same
+ location you use to source in your shell configuration: in first case it
+ should be some location in :file:`/usr` (e.g.
+ :file:`/usr/share/zsh/site-contrib/powerline.zsh`), in the second it should
+ be something like
+ :file:`/home/USER/.../powerline/bindings/zsh/powerline.zsh`. If this is true
+ it may be a powerline bug, but if locations do not match you should not
+ report the bug until you observe it on configuration where locations do
+ match.
+#) If this problem is observed specifically within bash make sure that you clean
+ ``$POWERLINE_COMMAND`` and ``$PROMPT_COMMAND`` environment variables on
+ startup or, at least, that it was cleaned after update. While different
+ ``$POWERLINE_COMMAND`` variable should not cause any troubles most of time
+ (and when it will cause troubles are rather trivial) spoiled
+ ``$PROMPT_COMMAND`` may lead to strange error messages or absence of exit
+ code reporting.
+
+ These are the sources which may keep outdated environment variables:
+
+ * Any command launched from any application inherits its environment unless
+ callee explicitly requests to use specific environment. So if you did
+ ``exec bash`` after update it is rather unlikely to fix the problem.
+ * More interesting: `tmux` is a client-server application, it keeps one
+ server instance per one user. You probably already knew that, but there is
+ an interesting consequence: once `tmux` server was started it inherits its
+ environment from the callee and keeps it *forever* (i.e. until server is
+ killed). This environment is then inherited by applications you start with
+ ``tmux new-session``. Easiest solution is to kill tmux with ``tmux
+ kill-server``, but you may also use ``tmux set-environment -u`` to unset
+ offending variables.
+ * Also check `When using z powerline shows wrong number of jobs`_: though
+ this problem should not be seen after update only, it contains another
+ example of ``$PROMPT_COMMAND`` spoiling results.
+
+#) If this problem is observed within the vim instance you should check out the
+ output of the following Ex mode commands
+
+ .. code-block:: vim
+
+ python import powerline as pl ; print (pl.__file__)
+ python3 import powerline as pl ; print (pl.__file__)
+
+ One (but not both) of them will most likely error out, this is OK. The same
+ rules apply as in the 1), but in place of sourcing you should seek for the
+ place where you modify `runtimepath` vim option. If you install powerline
+ using `VAM <https://github.com/MarcWeber/vim-addon-manager>`_ then no
+ explicit modifications of runtimpath were performed in your vimrc
+ (runtimepath is modified by VAM in this case), but powerline will be placed
+ in :file:`{plugin_root_dir}/powerline` where `{plugin_root_dir}` is stored in
+ VAM settings dictionary: do `echo g:vim_addon_manager.plugin_root_dir`.
+
+There is a hint if you want to place powerline repository somewhere, but still
+make powerline package importable anywhere: use
+
+ .. code-block:: sh
+
+ pip install --user --editable path/to/powerline
+
+Tmux/screen-related issues
+==========================
+
+I’m using tmux and Powerline looks like crap, what’s wrong?
+-----------------------------------------------------------
+
+* You need to tell tmux that it has 256-color capabilities. Add this to your
+ :file:`.tmux.conf` to solve this issue::
+
+ set -g default-terminal "screen-256color"
+* If you’re using iTerm2, make sure that you have enabled the setting
+ :guilabel:`Set locale variables automatically` in :menuselection:`Profiles -->
+ Terminal --> Environment`.
+* Make sure tmux knows that terminal it is running in support 256 colors. You
+ may tell it tmux by using ``-2`` option when launching it.
+
+I’m using tmux/screen and Powerline is colorless
+------------------------------------------------
+
+* If the above advices do not help, then you need to disable
+ :ref:`term_truecolor <config-common-term_truecolor>`.
+* Alternative: set :ref:`additional_escapes <config-common-additional_escapes>`
+ to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in
+ screen, but in tmux it may produce ugly spaces.
+
+ .. warning::
+ Both tmux and screen are not resending sequences escaped in such a way. Thus
+ even though additional escaping will work for the last shown prompt,
+ highlighting will eventually go away when tmux or screen will redraw screen
+ for some reason.
+
+ E.g. in screen it will go away when you used copy mode and prompt got out of
+ screen and in tmux it will go away immediately after you press ``<Enter>``.
+
+In tmux there is a green bar in place of powerline
+--------------------------------------------------
+
+In order for tmux bindings to work ``powerline-config`` script is required to be
+present in ``$PATH``. Alternatively one may define ``$POWERLINE_CONFIG_COMMAND``
+environment variable pointing to the location of the script. *This variable must
+be defined prior to launching tmux server and in the environment where server is
+started from.*
+
+Shell issues
+============
+
+Pipe status segment displays only last value in bash
+----------------------------------------------------
+
+Make sure that powerline command that sets prompt appears the very first in
+``$PROMPT_COMMAND``. To do this ``powerline.sh`` needs to be sourced the very
+last, after all other users of ``$PROMPT_COMMAND``.
+
+Bash prompt stopped updating
+----------------------------
+
+Make sure that powerline commands appear in ``$PROMPT_COMMAND``: some users of
+``$PROMPT_COMMAND`` have a habit of overwriting the value instead of
+prepending/appending to it. All powerline commands start with ``_powerline`` or
+``powerline``, e.g. ``_powerline_set_prompt``.
+
+Bash prompt does not show last exit code
+----------------------------------------
+
+There are two possibilities here:
+
+* You are using ``default`` theme in place of ``default_leftonly``. Unlike
+ ``default_leftonly`` ``default`` theme was designed for shells with right
+ prompt support (e.g. zsh, tcsh, fish) and status in question is supposed to be
+ shown on the right side which bash cannot display.
+
+* There is some other user of ``$PROMPT_COMMAND`` which prepended to this
+ variable, but did not bother keeping the exit code. For the best experience
+ powerline must appear first in ``$PROMPT_COMMAND`` which may be achieved by
+ sourcing powerline bindings the last.
+
+ .. note::
+ Resourcing bash bindings will not resolve the problem unless you clear
+ powerline commands from ``$PROMPT_COMMAND`` first.
+
+When sourcing shell bindings it complains about missing command or file
+-----------------------------------------------------------------------
+
+If you are using ``pip`` based installation do not forget to add pip-specific
+executable path to ``$PATH`` environment variable. This path usually looks
+something like ``$HOME/.local/bin`` (linux) or
+``$HOME/Library/Python/{python_version}/bin`` (OS X). One may check out where
+``powerline-config`` script was installed by using ``pip show -f
+powerline-status | grep powerline-config`` (does not always work).
+
+I am suffering bad lags before displaying shell prompt
+------------------------------------------------------
+
+To get rid of these lags there currently are two options:
+
+* Run ``powerline-daemon``. Powerline does not automatically start it for you.
+ See installation instructions for more details.
+* Compile and install ``libzpython`` module that lives in
+ https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.
+* If you are a python package manager, be sure to set ``POWERLINE_COMMAND``
+ to your Powerline command. See installation instructions for details.
+
+
+Prompt is spoiled after completing files in ksh
+-----------------------------------------------
+
+This is exactly why powerline has official mksh support, but not official ksh
+support. If you know the solution feel free to share it in `powerline bug
+tracker`_.
+
+When using z powerline shows wrong number of jobs
+-------------------------------------------------
+
+This happens because `z <https://github.com/rupa/z>`_ is launching some jobs in
+the background from ``$POWERLINE_COMMAND`` and these jobs fail to finish before
+powerline prompt is run.
+
+Solution to this problem is simple: be sure that :file:`z.sh` is sourced
+strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background
+jobs are spawned by `z <https://github.com/rupa/z>`_ after powerline has done
+its job.
+
+When using shell I do not see powerline fancy characters
+--------------------------------------------------------
+
+If your locale encoding is not unicode (any encoding that starts with “utf” or
+“ucs” will work, case is ignored) powerline falls back to ascii-only theme. You
+should set up your system to use unicode locale or forget about powerline fancy
+characters.
+
+Urxvt unicode3 and frills
+-------------------------
+
+Make sure that, whatever urxvt package you're installing, both the `unicode3`
+and `frills` features are enabled at compile time. Run
+``urxvt --help 2>&1 | grep options:`` to get a list of enabled options.
+This should contain at least `frills`, `unicode3` and optionally `iso14755`
+if you want to input Unicode characters as well.
+
+Compiler flags example:
+
+ --enable-frills \
+ --enable-unicode3
+
+As long as your terminal emulator is compiled without unicode rendering,
+no amount of configuration will make it display unicode characters.
+They're being considered 'unnecessary features', but they add negligible
+overhead to the size of the installed package (~100KB).
+
+Vim issues
+==========
+
+My vim statusline has strange characters like ``^B`` in it!
+-----------------------------------------------------------
+
+* Please add ``set encoding=utf-8`` to your :file:`vimrc`.
+
+My vim statusline has a lot of ``^`` or underline characters in it!
+-------------------------------------------------------------------
+
+* You need to configure the ``fillchars`` setting to disable statusline
+ fillchars (see ``:h 'fillchars'`` for details). Add this to your :file:`vimrc`
+ to solve this issue:
+
+ .. code-block:: vim
+
+ set fillchars+=stl:\ ,stlnc:\
+
+My vim statusline is hidden/only appears in split windows!
+----------------------------------------------------------
+
+* Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
+
+My vim statusline is not displayed completely and has too much spaces
+---------------------------------------------------------------------
+
+* Be sure you have ``ambiwidth`` option set to ``single``.
+* Alternative: set :ref:`ambiwidth <config-common-ambiwidth>` to 2, remove fancy
+ dividers (they suck when ``ambiwidth`` is set to double).
+
+Powerline loses color after editing vimrc
+-----------------------------------------
+
+If your vimrc has something like
+
+.. code-block:: vim
+
+ autocmd! BufWritePost ~/.vimrc :source ~/.vimrc
+
+used to automatically source vimrc after saving it then you must add ``nested``
+after pattern (``vimrc`` in this case):
+
+.. code-block:: vim
+
+ autocmd! BufWritePost ~/.vimrc nested :source ~/.vimrc
+
+. Alternatively move ``:colorscheme`` command out of the vimrc to the file which
+will not be automatically resourced.
+
+Observed problem is that when you use ``:colorscheme`` command existing
+highlighting groups are usually cleared, including those defined by powerline.
+To workaround this issue powerline hooks ``Colorscheme`` event, but when you
+source vimrc with ``BufWritePost`` (or any other) event, but without ``nested``
+this event is not launched. See also `autocmd-nested
+<http://vimcommunity.bitbucket.org/doc/autocmd.txt.html#autocmd-nested>`_ Vim
+documentation.
+
+Powerline loses color after saving any file
+-------------------------------------------
+
+It may be one of the incarnations of the above issue: specifically minibufexpl
+is known to trigger it. If you are using minibufexplorer you should set
+
+.. code-block:: vim
+
+ let g:miniBufExplForceSyntaxEnable = 1
+
+variable so that this issue is not triggered. Complete explanation:
+
+#. When MBE autocommand is executed it launches ``:syntax enable`` Vim command…
+#. … which makes Vim source :file:`syntax/syntax.vim` file …
+#. … which in turn sources :file:`syntax/synload.vim` …
+#. … which executes ``:colorscheme`` command. Normally this command triggers
+ ``Colorscheme`` event, but in the first point minibufexplorer did set up
+ autocommands that miss ``nested`` attribute meaning that no events will be
+ triggered when processing MBE events.
+
+.. note::
+ This setting was introduced in version 6.3.1 of `minibufexpl
+ <http://www.vim.org/scripts/script.php?script_id=159>`_ and removed in
+ version 6.5.0 of its successor `minibufexplorer
+ <http://www.vim.org/scripts/script.php?script_id=3239>`_. It is highly
+ advised to use the latter because `minibufexpl`_ was last updated late in
+ 2004.