Hjson or TOML

Two formats are allowed: TOML and Hjson.

This documentation will often show you the same setting in both formats, with two tabs, like this:

// setting to use if your config file is in .hjson

# setting to use if your config file is in .toml

Opening the config files

The main configuration file is called either conf.toml or conf.hjson.

This default file's location follows the XDG convention, which depends on your system settings. This location in your case can be found on the help screen (use ?).

The default configuration file contains several example sections that you may uncomment and modify for your goals.

It typically imports other files in the same directory.

Imports

A configuration file can import some other files. This eases management, as you may for example define your skin in a file, or the list of verbs in another one.

An import can have as condition whether the terminal is in dark or light mode, so that broot can take the most suitable skin on launch.

All imports are defined in an imports array.

For example:

imports: [

    verbs.toml

    {
        luma: light
        file: white-skin.hjson
    }

    {
        luma: [
            dark
            unknown
        ]
        file: dark-blue-skin.hjson
    }

]

This example defines 3 imports.

The first one has the simplest form: just a (relative or absolute) path. This import isn't conditional.

The second import is done only if the terminal's luma is determined to be light.

And the third one is done when the terminal's luma is either dark or couldn't be determined.

Starting from version 1.14, the default configuration is released in several files.

Note

Be careful when installing a configuration file from an unknown source: it may contain an arbitrary command to execute. Check it before importing it

Note

Background color determination is currently disabled (always "unknown") on non linux systems. This is expected to be fixed.

Default flags

Broot accepts a few flags at launch (the complete list is available with broot --help.

For example, if you want to see hidden files (the ones whose name starts with a dot) and the status of files related to git, you launch broot with

br -gh

If you almost always want those flags, you may define them as default in the configuration file file, with the default_flags setting.

default_flags: gh

default_flags = "gh"

Those flags can still be overridden at launch with the negating ones. For example if you don't want to see hidden files at a specific launch, do

br -H

Special Paths

You may map special paths to specific behaviors. You may especially want

Example configuration:

special_paths: {
    "/media/slow-backup-disk"             : no-enter
    "/home/dys/useless"                   : hide
    "/home/dys/my-link-I-want-to-explore" : enter
}

[special-paths]
"/media/slow-backup-disk" = "no-enter"
"/home/dys/useless" = "hide"
"/home/dys/my-link-I-want-to-explore" = "enter"

Be careful that those paths (globs, in fact) are checked a lot when broot builds trees and that defining a lot of paths will impact the overall speed.

Search Modes

It's possible to redefine the mode mappings, for example if you usually prefer to do exact searches:

"search-modes": {
    <empty>: regex name
    /: fuzzy path
    z/: regex path
}

[search-modes]
"<empty>" = "regex name"
"/" = "fuzzy path"
"z/" = "regex path"

The search mode must be made of two parts :

Selection Mark

When the background colors aren't rendered in your terminal, aren't visible enough, or just aren't clear enough for you, you may have the selected lines marked with triangles with

show_selection_mark: true

show_selection_mark = true

Columns order

You may change the order of file attributes in file lists:

For example, if you prefer to have the branches left of the tree (as was the default in broot prior 0.18.1) you can use

cols_order: [
    mark
    git
    branch
    permission
    date
    size
    count
    name
]

cols_order = [
    "mark",
    "git",
    "branch",
    "permission",
    "date",
    "size",
    "count",
    "name",
]

The name should be kept at end as it's the only one with a variable size.

Colors by file extension

broot doesn't support LS_COLORS which isn't available on all systems and is limited to 16 system dependent colors.

But you can still give a color to files by extension:

ext_colors: {
    png: "rgb(255, 128, 75)"
    rs: "yellow"
    toml: "ansi(105)"
}

[ext-colors]
png = "rgb(255, 128, 75)"
rs = "yellow"
toml = "ansi(105)"

(see here for precision about the color syntax in broot)

Syntax Theme

You can choose any of the following syntaxic coloring themes for previewed files:

syntax_theme: OceanLight

syntax_theme = "OceanLight"

Those themes come from syntect and are bundled in broot.

Miscellaneous

Maximal number of files added by a :stage_all_files command

max_staged_count: 1234

max_staged_count = 1234

Mouse Capture

Broot usually captures the mouse so that you can click or double click on items. If you want to disable this capture, you may add this:

capture_mouse: false

capture_mouse = false

Number of threads for directory size computation

Most users should not change this. In my measurements a number of 4 to 6 looks optimal.

file_sum_threads_count: 10,

file_sum_threads_count = 10

Quit on last cancel

You can usually cancel the last state change on escape. If you want the escape key to quit broot when there's nothing to cancel (for example when you just opened broot), you can set quit_on_last_cancel to true. this parameter

quit_on_last_cancel: true

quit_on_last_cancel = true

Only show file name even when the pattern is on paths

When your search pattern is applied to a path, the path is shown on each line so that you see why the line matches:

shown

If you don't really need to see matching characters, you may get a cleaner display with just file names with this option:

show_matching_characters_on_path_searches: false

show_matching_characters_on_path_searches = false

which gives this:

not shown