************* Configuration ************* Powerline is configured with one main configuration file, and with separate configuration files for themes and colorschemes. All configuration files are written in JSON, with the exception of segment definitions, which are written in Python. Powerline provides default configurations in the following locations: `Main configuration`_ :file:`powerline/config.json` `Colorschemes`_ :file:`powerline/colorschemes/default.json` `Themes`_ :file:`powerline/themes/{extension}/default.json` The default configuration files are stored in the main package. User configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for Linux users, and in :file:`~/.config/powerline` for OS X users. This usually corresponds to :file:`~/.config/powerline` on both platforms. The easiest way of creating your own version of any configuration file is to copy the configuration file from the main package to the corresponding path in your user-specific config directory and make your changes to the new file. Example: .. code-block:: sh $ cp /path/to/powerline/colorschemes/default.json \ ~/.config/powerline/colorschemes/mycolorscheme.json $ vim ~/.config/powerline/colorschemes/mycolorscheme.json .. note:: If you're creating a custom colorscheme or theme, remember to rename it and update your main configuration to use the new colorscheme/theme! Main configuration ================== :Location: :file:`powerline/config.json` The main configuration file defines some common options that applies to all extensions, as well as some extension-specific options like themes and colorschemes. Common configuration -------------------- Common configuration is a subdictionary that is a value of ``common`` key in :file:`powerline/config.json` file. ``dividers`` Defines the dividers used in all Powerline extensions. This option should usually only be changed if you don't have a patched font, or if you use a font patched with the legacy font patcher. The ``hard`` dividers are used to divide segments with different background colors, while the ``soft`` dividers are used to divide segments with the same background color. ``paths`` .. _config-common-paths: Defines additional paths which will be searched for modules when using :ref:`module segment option `. Paths defined here have priority when searching for modules. Extension-specific configuration -------------------------------- Common configuration is a subdictionary that is a value of ``ext`` key in :file:`powerline/config.json` file. ``colorscheme`` Defines the colorscheme used for this extension. ``theme`` Defines the theme used for this extension. ``local_themes`` Defines themes used when certain conditions are met, e.g. for buffer-specific statuslines in vim. Requires a custom matcher and theme. Colorschemes ============ :Location: :file:`powerline/colorschemes/{extension}/{name}.json` ``name`` Name of the colorscheme. ``colors`` .. _config-colorscheme-colors: Color definitions, consisting of a dict where the key is the name of the color, and the value is one of the following: * A cterm color index. * A list of two integers, where the first integer is a cterm color index, and the second is an RGB/hex color. This is useful for colorschemes that use colors that aren't available in color terminals. ``groups`` .. _config-colorscheme-groups: Segment highlighting groups, consisting of a dict where the key is the name of the highlighting group (usually the function name for function segments), and the value is a dict that defines the foreground color, background color and optional attributes: ``fg`` Foreground color. Must be defined in :ref:`colors `. ``bg`` Background color. Must be defined in :ref:`colors `. ``attr`` Optional list of attributes. Valid values are one or more of ``bold``, ``italic`` and ``underline``. Note that some attributes may be unavailable in some applications or terminal emulators. ``mode_translations`` Mode-specific highlighting for extensions that support it (e.g. the vim extension). It's an easy way of changing a color in a specific mode. Consists of a dict where the key is the mode and the value is a dict with the following options: ``colors`` A dict where the key is the color to be translated in this mode, and the value is the new color. Both the key and the value must be defined in :ref:`colors `. ``groups`` Segment highlighting groups for this mode. Same syntax as the main :ref:`groups ` option. Themes ====== :Location: :file:`powerline/themes/{extension}/{name}.json` ``name`` Name of the theme. ``default_module`` .. _config-themes-default_module: Python module where segments will be looked by default. ``segments`` A dict with a ``left`` and a ``right`` list, consisting of segment dicts. Each segment has the following options: ``type`` The segment type. Can be one of ``function`` (default), ``string`` or ``filler``: ``function`` The segment contents is the return value of the function defined in the :ref:`name option `. ``string`` A static string segment where the contents is defined in the :ref:`contents option `, and the highlighting group is defined in the :ref:`highlight_group option `. ``filler`` If the statusline is rendered with a specific width, remaining whitespace is distributed among filler segments. The highlighting group is defined in the :ref:`highlight_group option `. ``module`` .. _config-themes-seg-module: Function module, only required for function segments. Defaults to ``powerline.ext.{extension}.segments``. Default is overriden by :ref:`default_module theme option `. ``name`` .. _config-themes-seg-name: Function name, only required for function segments. ``highlight_group`` .. _config-themes-seg-highlight_group: Highlighting group for this segment. Consists of a prioritized list of highlighting groups, where the first highlighting group that is available in the colorscheme is used. ``before`` A string which will be prepended to the segment contents. ``after`` A string which will be appended to the segment contents. ``contents`` .. _config-themes-seg-contents: Segment contents, only required for ``string`` segments. ``args`` A dict of arguments to be passed to a ``function`` segment. ``ljust`` If set, the segment will be left justified to the width specified by this option. ``rjust`` If set, the segment will be right justified to the width specified by this option. ``priority`` Optional segment priority. Segments with priority ``-1`` (the default priority) will always be included, regardless of the width of the prompt/statusline. If the priority is ``0`` or more, the segment may be removed if the prompt/statusline width is too small for all the segments to be rendered. A lower number means that the segment has a higher priority. Segments are removed according to their priority, with low priority segments being removed first. ``draw_divider`` Whether to draw a divider between this and the adjacent segment. The adjacent segment is to the *right* for segments on the *left* side, and vice versa. ``exclude_modes`` A list of modes where this segment will be excluded: The segment is included in all modes, *except* for the modes in this list. ``include_modes`` A list of modes where this segment will be included: The segment is *not* included in any modes, *except* for the modes in this list. Segments ======== Segments are written in Python, and the default segments provided with Powerline are located in :file:`powerline/segments/{extension}.py`. User-defined segments can be defined in any module in ``sys.path`` or :ref:`paths common configuration option `, import is always absolute. Segments are regular Python functions, and they may accept arguments. All arguments should have a default value which will be used for themes that don't provide an ``args`` dict. A segment function must return one of the following values: * ``None``, which will remove the segment from the prompt/statusline. * A string, which will be the segment contents. * A list of dicts consisting of a ``contents`` string, and a ``highlight_group`` list. This is useful for providing a particular highlighting group depending on the segment contents.