FAQ ⏐ INSTALL ⏐ CUSTOMIZE ⏐ MORE DETAILS
This package provides indentation guide bars in Emacs, with optional tree-sitter enhancement:
indent-bars-ts-styling-scope
to swap the roles of in-scope and out-of-scope style.indent-bars-depth-update-delay
. go-mode
, go-ts-mode
, cobol-mode
:blend
value in indent-bars-color
closer to zero. Consider disabling indent-bars-color-by-depth
.:blend
value in indent-bars-color
closer to one.indent-bars
will just work for you (though you don't get any fancy bar patterns).│
characters with indent-bars-prefer-character
.indent-bars-no-descend-lists
or even use tree-sitter to help.indent-bars-starting-column
to 0.indent-bars-depth-update-delay
to a comfortable number like 0.1s (0.075s is the default). If you like the crazy-fast updates, set this to 0.indent-bars-treesit-scope
(and possibly wrap
) for your language(s) of interest. More info.ts-
customizations.indent-bars-ts-styling-scope
to 'in-scope
. indent-bars-treesit-scope
variable. Start small, with thing you know you want (function, method, class, etc.).Not yet in a package database; simply clone and point use-package
at the correct path. You can also simply use the vc-package-install
command newly released with Emacs 29.
(use-package indent-bars
:load-path "~/code/emacs/indent-bars"
:hook ((python-mode yaml-mode) . indent-bars-mode)) ; or whichever modes you prefer
To clone with use-package
and straight
:
(use-package indent-bars
:straight (indent-bars :type git :host github :repo "jdtsmith/indent-bars")
:hook ((python-mode yaml-mode) . indent-bars-mode)) ; or whichever modes you prefer
(use-package indent-bars
:load-path "~/code/emacs/indent-bars"
:config
(require 'indent-bars-ts) ; not needed with straight
:custom
(indent-bars-treesit-support t)
(indent-bars-treesit-ignore-blank-lines-types '("module"))
;; Add other languages as needed
(indent-bars-treesit-scope '((python function_definition class_definition for_statement
if_statement with_statement while_statement)))
;; wrap may not be needed if no-descend-list is enough
;;(indent-bars-treesit-wrap '((python argument_list parameters ; for python, as an example
;; list list_comprehension
;; dictionary dictionary_comprehension
;; parenthesized_expression subscript)))
:hook ((python-base-mode yaml-mode) . indent-bars-mode))
See tree-sitter, and also the Wiki page.
[!IMPORTANT] For
indent-bars
to display fancy guide bars, your port and version of emacs must correctly display the:stipple
face attribute. Most do, but some do not.
Known :stipple
support, by Emacs build:
--with-pgtk
build flag) versions support stipples, but had a display bug that caused them to appear incorrectly (as reverse video) and lead to crashes; these issues were fixed in Emacs here and will presumably be released with Emacs 30.--with-cairo
) have been reported not to display stipples.M-x version
should say Carbon
, not NS
.[^1]: Most easily installed with brew.
Please open an issue with any updates/corrections to this list. See also Testing Stipples.
indent-bars
can also be used without stipples, drawing a simple vertical character (like │
) instead. It automatically does this in non-graphical displays (terminals), but this can be made the default; see Character Display.
M-x customize-group indent-bars
is the easiest way to customize everything about the appearance and function of indent-bars
(check sub-groups too). There are many customization variables and bar styling in particular is highly configurable, so use Customize!
[!TIP] The easiest way to achieve a particular style is to customize the groups
indent-bars
, sub-groupindent-bars-style
and (if you use TS)indent-bars-ts
+indent-bars-ts-style
. While in the Customize interface, pull up one of your buffers with bars in another window on the same frame. When you make changes to variables (C-c C-c
is convenient in custom buffers), the bar style/etc. will automatically update. When you are happy, you can either "Set for Future Sessions", or "Show Saved Lisp Expression" for the variables you changed and copy them into your init file.
See some examples with relevant settings.
The main customization variables are categorized below. See the documentation of each variable for more details.
Custom variables for configuring bar color, including depth-based palettes:
indent-bars-color
: The main bar color, either a color name or face, from which foreground or background color will be taken. Also used to set a :blend
factor, to blend colors into the frame's background color.indent-bars-color-by-depth
: How and whether to alter the color of the indent bars by their indentation depth. Defaults to using the foreground of the outline-*
faces, but many options are possible, including face sets or a custom color palette.Variables affecting the visual appearance of bars (color aside):
indent-bars-width-frac
: The fractional width of the bar ([0-1], a fraction of a single character's width).indent-bars-pad-frac
: The fractional padding offset of the bar from the left edge of the character. indent-bars-pattern
: A string specifying the vertical structure of the bar (space=blank, non-space=filled). Scaled to the height of one character.indent-bars-zigzag
: A fractional left-right zigzag to apply to consecutive groups of identical non-space characters in pattern
.Configuration for highlighting the current indentation bar depth:
indent-bars-highlight-current-depth
: How and whether to highlight the bars at the indentation depth of the current line. The current depth bar can change color (including blending with the pre-existing color), as well as appearance (size, pad, pattern, zigzag).indent-bars-highlight-selection-method
: Method used to select which bar is highlighted as the current depth. The default ('context
) considers surrounding lines for a more natural selection depth.indent-bars-depth-update-delay
: Command delay in seconds after which depth highlighting occurs. Configuration variables for bar position and line locations (including on blank lines):
indent-bars-starting-column
: column to use for the first bar. Can be set in special modes which start at an unusual fixed offset, or set to 0 to get "column 0" bars.indent-bars-spacing-override
: Normally the number of spaces for indentation is automatically discovered from the mode and other variables. If that doesn't work for any reason, it can be explicitly set using this variable.indent-bars-display-on-blank-lines
: Whether to display bars on blank lines.indent-bars-no-descend-string
: Whether to inhibit increasing depth inside of strings. indent-bars-no-descend-list
: Whether to inhibit increasing depth inside of lists. Custom variables affecting character-based bar display, e.g. in the terminal:
indent-bars-prefer-character
: Use characters to display the vertical bar instead of stipples. This occurs automatically on non-graphical displays (terminals), but this variable can be used to always prefer character-based display.indent-bars-no-stipple-char
: The character to use when stipples are unavailable or disabled. Defaults to the vertical box character │
. Other good options include ┃
, ┋
, and ║
.indent-bars-no-stipple-char-font-weight
: Optional font weight to use for the face displaying the no-stipple character.indent-bars-unspecified-bg|fg-color
: Colors to use for the frame background and default foreground when they are unspecified (e.g. in terminals). If you intend to use indent-bars
in the terminal, set to the terminal background/foreground colors you use. For more information, check the details.
indent-bars-treesit-support
: Whether to use tree-sitter (if available) to (optionally) highlight the current scope and help determine bar depth.indent-bars-treesit-scope
: A mapping of language to tree-sitter scope node types (as symbols), for local scope highlight (aka scope focus).indent-bars-treesit-scope-min-lines
: The minimum number of lines a scope node must occupy to be considered a valid containing scope.indent-bars-treesit-update-delay
: Delay in seconds for updating the treesitter scope highlight.indent-bars-treesit-wrap
: A mapping of language to tree-sitter wrap types (as symbols), to avoid adding extra bars e.g. in wrapped function arguments. Note that this is considered only after the no-descend
options above (which may be sufficient on their own).indent-bars-treesit-ignore-blank-lines-types
: A list of tree-sitter node types (as strings) inside of which to inhibit styling blank lines, like "module". indent-bars-ts-styling-scope
: Determine whether the *-ts-*
variables apply to in-scope or (by default) out-of-scope styling. This is important because one of these styles is shared with the bar style in non-TS buffers. This allows the default style in non-TS buffers to match either the in-scope (default) or out-of-scope styling.By default, if tree-sitter and scope focus are active (indent-bars-treesit-scope
), the style and highlight settings above apply only to the in-scope bars[^2]. You can separately configure an alternate style for the appearance of the out-of-scope bars — i.e. the bars outside the current tree-sitter scope[^2]. Usually you'd want to de-emphasize out-of-scope bars somehow, but that's not required (go crazy).
[^2]: Or visa versa if indent-bars-ts-styling-scope
is set to in-scope
.
To customize the alternate bar appearance, you use the parallel set of custom variables with an indent-bars-ts-
prefix. Each of these variables can be set similarly to their default counterparts to fully configure alternate bar appearance, including color, depth highlighting, bar pattern, etc.
You can interchange the role of in-scope and out-of-scope using indent-bars-ts-styling-scope
. This is useful if you prefer to have the default style (e.g. the bar style in non-tree-sitter-enabled buffers) match the out-of-scope style within tree-sitter buffers (i.e. if you want to emphasize scope, not de-emphasize out-of-scope).
[!NOTE] Scope focus highlighting is completely independent of current depth highlighting, and you can style them separately, or enable one or the other, both, or neither.
The ts
custom variables for configuring the alternate styling are:
indent-bars-ts-color
indent-bars-ts-width-frac
indent-bars-ts-pad-frac
indent-bars-ts-pattern
indent-bars-ts-zigzag
indent-bars-ts-no-stipple-char-font-weight
indent-bars-ts-color-by-depth
indent-bars-ts-highlight-current-depth
Each of these parallel variables has the same form as their equivalent non-ts
version (the "parent" variable), with two difference:
:key
based elements are inherited from the in-scope (parent) style. To configure their inheritance, you can optionally set these variable values to a cons cell of the form ([no-]inherit . value)
, where value
has the normal format for the parent variable. inherit
(the default, if the cons cell is omitted and value
is simply used as-is) means that any unspecified :key
values are inherited from the parent variable. The symbol no-inherit
means to omit any missing key values for the alternate styling.:key
type values, the specific symbol value 'unspecified
can be set to indicate using the parent's value for that slot.For example, a setting of:
(setopt indent-bars-ts-color '(inherit unspecified :blend 0.15))
means to configure the color of alternate style bars as follows:
indent-bars-color
(since it is unspecified
here):blend
to 0.15indent-bars-color
The easiest way to configure inheritance and unspecified values in the ts
variables is via the customize interface; see the customize group indent-bars-ts-style
.
indent-bars
works with either space- or tab-based indentation. If possible, prefer space indentation, as it is faster. Note that some modes explicitly enable or disable indent-tabs-mode
.
indent-bars
can highlight the bar at the current depth, and supports a few different ways to determine which bar gets selected for highlight (see indent-bars-highlight-selection-method
):
nil
: The simplest version selects the depth of the last-visible bar on the current line for highlight.on-bar
: The old default, which selects the depth of the "unseen" bar that the first character of text on the current line covers up.context
: The new default, a blend of these two. It selects the last-visible bar unless an adjacent non-blank line is indented deeper by at least one indent spacing, in which case the on-bar
approach is used.Experiment with these to see what you prefer.
indent-bars
can optionally use tree-sitter in supported files to enable several features:
indent-bars
displays bars on blank lines (though this can be configured), so that they remain continuous. It can be nice to omit the display of blank lines bars at the top structural level (e.g. in a module), to make divisions between top-level constructs more visible. Tree-sitter can help indent-bars
identify those lines.indent-bars-no-descend-string/list
, which do not require tree-sitter).[!NOTE]
indent-bars
' tree-sitter capabilities require Emacs 29 or later built with tree-sitter support, and the appropriate tree-sitter grammars installed for your languages of interest. Additional node type configuration by language is required; see below.
Simply configure indent-bars-treesit-scope
with the languages and node types for which "local scope" highlighting nodes are of interest. This must be done for each tree-sitter language you use. This scope could be as granular as classes and functions, or include detailed block statements. You can disable scoping for "short blocks" using indent-bars-treesit-scope-min-lines
, so that, e.g., a quick if
statement does not capture scope. I recommend starting with the minimal possible set of scope node types, adding as needed.
[TIP] If you don't know the name treesitter uses for your language, evaluate
(treesit-language-at (point-min))
in a ts-enabled buffer.
indent-bars-treesit-wrap
can be configured in a similar manner (mapping language to wrapping node types). Note that indent-bars-no-descend-list
, which does not require tree-sitter and is on by default, may be sufficient for your uses.
You can assign a single (usually top-level) node type to ignore when drawing bars on blanks linkes; see indent-bars-treesit-ignore-blank-lines-types
(which, please note, is configured as a list of strings, unlike indent-bars-treesit-wrap/scope
).
The easiest way to discover node types of interest (in a buffer with working treesit support) is to M-x treesit-explore-mode
. Then simply highlight the beginning of a line of interest, and look in the treesitter explorer
buffer which pops up for the names of obvious nodes in the tree. Add these types to indent-bars-treesit-scope/wrap
for the language of interest, then M-x indent-bars-reset
and see how you did (this will happen automatically if you make the change in the Customize interface).
Please document good tree-sitter settings for other languages in the Wiki.
If indent-bars-display-on-blank-lines
is set, the newline at the end of blank lines may have a 'display
property set to show the bars. Emacs does not deal correctly with display properties containing newlines when moving by columns. This is not normally a problem, but in one instance it is a nuisance: evil-mode
tries to "preserve" column during line moves, so can trigger this emacs misfeature. The symptom is that point jumps a line and moves over as you move down with evil. A workaround is here.
Stipples are repeating bitmap patterns anchored to the full emacs frame. indent-bars
basically "opens windows" on this fixed pattern to "reveal" the bars.
The fast stipple method used for drawing bars enables lots of interesting patterns.
If you are experiencing issues with stipple bar display (missing, garbled, etc.), and would like to determine if stipples are working correctly in your build of emacs, you can test it as follows.
*scratch*
buffer, use first M-x font-lock-mode
to disable fontificationC-x C-e
just after the last )
in the following code:
(let* ((w (window-font-width))
(stipple `(,w 1 ,(apply #'unibyte-string
(append (make-list (1- (/ (+ w 7) 8)) ?\0)
'(1))))))
(insert "\n" (propertize (concat (make-string 15 ?\s)
"THIS IS A TEST"
(make-string 15 ?\s))
'face `(:background "red" :foreground "blue" :stipple ,stipple))))
This should then look something like (note the blue vertical bars):
If you determine that stipples do not work in your version of Emacs, consider upgrading to a version which supports them, reporting the bug, or setting indent-bars-prefer-character=t
.
To get the stipple bars to appear in the correct location within their column, indent-bars
must consider the starting horizontal pixel position of the current window, and "rotate" the stipple pattern accordingly. It does this automatically, per buffer, so you shouldn't ever notice problems, even when re-sizing or re-arranging windows, changing font size, etc. Until v0.5, showing the same buffer side by side in Emacs versions which support pixel-level window width/offsets could lead to unexpected bar artifacts, since the offset applies per-buffer, not per-window. In v0.5, an alternate method for applying per-window stipple patterns was used to solve this.
For terminals, (and everywhere, if indent-bars-prefer-character
is set), indent-bars
will not attempt stipple display, but instead use simple characters (e.g. │
; see an example).
Note that in mixed gui/terminal sessions of the same Emacs process, you may need to M-x indent-bars-reset
when switching a given buffer between graphical and terminal frames.
line-spacing
is non-nil (vs. gaps with box characters and additional line spacing).indent-bars
was in part motivated by the inefficiency of older indentation highlight modes, and is designed for speed. It uses stipples (fixed bitmap patterns) and font-lock for fast and efficient bar drawing — simply faces on spaces. Highlighting the current indentation level is essentially free, since it works by filtered remapping of the relevant face.
The heaviest operations are tree-sitter support (especially scope highlighting), and blank-line highlighting. If you experience any speed issues, these are the first settings to experiment with. Using with tab-based indentation may also be slightly (but likely imperceptibly) slower than with space-based.
Both indentation-depth highlighting and current-tree-sitter-scope highlighting are protected by timers to avoid unnecessary loads (e.g. when pixel-scrolling). Note that indentation-depth highlighting is very fast and can safely be set to 0 seconds (though bars will then flash rapidly as you scroll). Tree-sitter scope requires querying the tree-sitter core, which can be somewhat slower, so be careful setting its timer too low.
|
characters. Some reports of performance concerns. Incompatible with company and other related in-buffer modes.None of the existing packages:
I'm grateful for in-depth advice and input on the design of indent-bars
from Eli Zaretski, Stefan Monnier, Dmitry Gutov and many other who opened issues and PRs.
highlight-indentation-mode was a source of good ideas, and indent-bars
adapts the indentation guessing function from this mode. The original idea of using stipples for "better" indent-bars came from this comment by @vlcek.