Configuration

pls supports a powerful, and complex, configuration system that offers a lot of powerful customization options. Configuration is specified in the form of a .pls.yml YAML file (which means you can just use JSON if you hate YAML so much).

Placement

pls uses a cascading system for multiple config files. You can have config files at the directory level, at the repository level and at the global level.

The global config file can be placed in the home directory at ~/.pls.yml. If you prefer a clean home directory, you can set the PLS_CONFIG environment variable to a point to a config file placed elsewhere on your computer, in which case pls will not look for one in the home directory.

Schema

This is the schema of the file.

mapping of icon names to actual glyphs from Nerd Fonts

You can also use emojis as the glyphs but it's not recommended as you can run into issues regarding character width in some terminals.

Examples of icons

icons:
  python: "" # nf-seti-python
  javascript: "󰌞" # nf-md-language_javascript
  applescript: "🍎"

list of node specs, in ascending order of specificity

Properties of Spec

a regex pattern to match against the node's name; In YAML this can be specified more clearly if the quotes are omitted.

the names of the icons to use for the node; Each should be a key from the built-in icons or from the icons section.

styles to apply to the node name and icon

the importance level of the node

the rule for determining the parent node, if any, for this node

Properties of Collapse

Collapse is an enum type so exactly one of name, ext or sub should be specified.

the exact name of the parent file; Name-based collapsing matches this node with another having the exact given name.

the extension of the parent file; Extension-based collapsing matches this node with another having the same base name and the given extension.

a replacement template for the parent's name; Substitution-based collapsing builds the name by expanding the template against the capture groups of the spec's own pattern. Both $name/${name} and numbered $1 references are supported.

Examples of collapse

collapse:
  name: package.json # matches exactly `package.json`

collapse:
  ext: ts # matches file with same base name and `.ts` extension

collapse:
  sub: $base.js # with pattern `^(?<base>.+)\.min\.js$`, collapses `app.min.js` into `app.js`

Examples of specs

specs:
  - pattern: ^(pnpm-lock.yaml|package-lock.json)$
    icons:
     - lock
    importance: -1
    collapse:
      name: package.json
  - pattern: \.(c|m)?js$
    icons:
      - javascript
    style: rgb(247,223,30)
    collapse:
      ext: ts

constants that determine the appearance and styling of each entry

Properties of EntryConst

style for the device number

style for the inode number

styles for the number of hard links

Properties of NlinkStyles

style to use when file has one hard link

style to use when file has more than one hard link

style to use when directory has one hard link

style to use when directory has more than one hard link

Examples of nlink_styles

nlink_styles:
  file_sing: ""
  file_plur: yellow
  dir_sing: yellow
  dir_plur: ""

mapping of node type to node type info (including style)

The key for the map i.e. Typ can be any of the following strings: 'dir', 'symlink', 'fifo', 'socket', 'block_device', 'char_device', 'file' or 'unknown'.

Properties of TypInfo

the character for a node type, used in the 'T' column

the suffix for a node type, placed after the node name

the fallback icons for the node type, used if no other icon is found; Not all node types need to have an icon.

the style to use for nodes of a particular node type; This applies to name, ch, suffix and icon as well.

Examples of typ

typ:
  dir:
    ch: <bold cyan>d</>
    suffix: <dimmed>/</>
    icons:
      - dir
    style: blue
  symlink:
    ch: <magenta>l</>
    suffix: <dimmed>@</>
    icons:
      - symlink
  char_device:
    ch: <blue bg:green>c</>
  block_device:
    ch: <blue bg:yellow>b</>

mapping of symbolic permission bits to style

The key for the map i.e. Sym can be any of the following strings: 'none', 'read', 'write', 'execute', or 'special'.

Examples of perm_styles

Example:

perm_styles:
  none: dimmed
  read: yellow
  write: red
  execute: green
  special: magenta

mapping of octal permission bits to style

The key for the map i.e. Oct can be any of the following strings: 'special', 'user', 'group' or 'other'.

Examples of oct_styles

oct_styles:
  special: magenta
  user: blue
  group: blue dimmed
  other: dimmed

styles for the owner user

Properties of OwnerStyles

style for when the node is owned by the current user/group

style for when the node is owned by a different user/group

Examples of user_styles

user_styles:
  curr: blue bold
  other: dimmed

styles for the owner group

Properties of OwnerStyles

style for when the node is owned by the current user/group

style for when the node is owned by a different user/group

Examples of group_styles

group_styles:
  curr: blue
  other: dimmed

style for magnitude and unit (prefix and base) of node size

Properties of SizeStyles

the style for the node size magnitude

the style for the node size unit prefix

the style for the node size base unit

Examples of size_styles

size_styles:
  mag: bold
  prefix: italic
  base: dimmed

style for the number of blocks occupied by the file

mapping of timestamp fields to the human-readable format

The key for the map i.e. DetailField can be any of the following strings: 'btime', 'ctime', 'mtime' or 'atime'.

The format string should contain format description components from the time crate.

Examples of timestamp_formats

timestamp_formats:
  btime: <bold green>[day] [month repr:short]</> [hour repr:24]:[minute]
  ctime: <bold yellow>[day] [month repr:short]</> [hour repr:24]:[minute]
  mtime: <bold yellow>[day] [month repr:short]</> [hour repr:24]:[minute]
  atime: <bold blue>[day] [month repr:short]</> [hour repr:24]:[minute]

mapping of symlink state to more symlink state info (including style)

The key for the map i.e. SymState can be any of the following strings: 'ok', 'broken', 'cyclic' or 'error'.

Properties of SymlinkInfo

the separator to show between the node and its target

the style to use for symlinks in a particular symlink state; This applies to both the name and the separator.

the style to use for the symlink reference; This applies to the reference only.

Examples of symlink

symlink:
  ok:
    sep: 󰁔
    style: magenta
  broken:
    sep: 󱞣
    style: red
    ref_style: strikethrough

Examples of entry_const

entry_const:
  dev_style: magenta
  ino_style: magenta
  blocks_style: cyan

constants that determine the appearance and styling of the entire UI

Properties of AppConst

configuration for the table view

Properties of TableInfo

mapping of detail field to column name

The key for the map i.e. DetailField can be any of the following: strings: 'dev', 'ino', 'nlink', 'typ', 'perm', 'oct', 'user', 'uid', 'group', 'gid', 'size', 'blocks', 'btime', 'ctime', 'mtime', 'atime', 'git' or 'name'.

Examples of column_names

column_names:
  btime: <green>Date Created</>
  ctime: <yellow>Date Changed</>
  mtime: <yellow>Date Modified</>
  atime: <blue>Date Accessed</>

styles to apply to the text in the header row

Examples of table

table:
  header_style: clear underline

shapes to use to print trees

Properties of TreeInfo

the shape to use an alternative to "│ "

the shape to use an alternative to " "

the shape to use an alternative to "├─ "

the shape to use an alternative to "└─ "

Examples of tree

tree:
  pipe_space: "║  "
  space_space: "   "
  tee_dash: "╠═ "
  bend_dash: "╚═ "

pairings of importance levels with styling directives

Properties of (int, str)

the importance level

the style to use for nodes of a particular importance level

Examples of imp_styles

imp_styles:
  - [-1, "dimmed"]
  - [1, "italic"]
  - [2, "underline"]

Examples

You can see the .pls.yml files from pls's source code itself to get a feel for how these configurations work. Feel free to copy them or use as inspiration for your own projects.

Configuration

Placement

Schema

icons

specs

entry_const

app_const

Examples