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.
icons
map<str, str> 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: "🍎" specs
seq<Spec> list of node specs, in ascending order of specificity
Properties of Spec
pattern * str(Regex) a regex pattern to match against the node's name; In YAML this can be specified more clearly if the quotes are omitted.
icon str the name of the icon to use for the node; It should be a key from the
built-in icons or from the icons section.
style str styles to apply to the node name and icon
importance int the importance level of the node
collapse Collapse 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 or ext should be
specified.
name str the exact name of the parent file; Name-based collapsing matches this node with another having the exact given name.
ext str the extension of the parent file; Extension-based collapsing matches this node with another having the same base name and the given extension.
Examples of collapse
collapse: name: package.json # matches exactly `package.json`collapse: ext: ts # matches file with same base name and `.ts` extensionExamples 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 entry_const
EntryConst constants that determine the appearance and styling of each entry
Properties of EntryConst
dev_style str style for the device number
ino_style str style for the inode number
nlink_styles NlinkStyles styles for the number of hard links
Properties of NlinkStyles
file_sing str style to use when file has one hard link
file_plur str style to use when file has more than one hard link
dir_sing str style to use when directory has one hard link
dir_plur str 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: "" typ map<str(Typ), TypInfo> 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
ch str the character for a node type, used in the 'T' column
suffix str the suffix for a node type, placed after the node name
icon str the fallback icon for the node type, used if no other icon is found; Not all node types need to have an icon.
style str 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>b</> block_device: ch: <blue bg:yellow>c</> perm_styles map<str(Sym), str> 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 oct_styles map<str(Oct), str> 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 user_styles OwnerStyles styles for the owner user
Properties of OwnerStyles
curr str style for when the node is owned by the current user/group
other str style for when the node is owned by a different user/group
Examples of user_styles
user_styles: curr: blue bold other: dimmed group_styles OwnerStyles styles for the owner group
Properties of OwnerStyles
curr str style for when the node is owned by the current user/group
other str style for when the node is owned by a different user/group
Examples of group_styles
group_styles: curr: blue other: dimmed size_styles SizeStyles style for magnitude and unit (prefix and base) of node size
Properties of SizeStyles
mag str the style for the node size magnitude
prefix str the style for the node size unit prefix
base str the style for the node size base unit
Examples of size_styles
size_styles: mag: bold prefix: italic base: dimmed blocks_style str style for the number of blocks occupied by the file
timestamp_formats map<str(DetailField), str> 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] symlink map<str(SymState), SymlinkInfo> 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
sep str the separator to show between the node and its target
style str the style to use for symlinks in a particular symlink state; This applies to both the name and the separator.
ref_style str 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: strikethroughExamples of entry_const
entry_const: dev_style: magenta ino_style: magenta blocks_style: cyan app_const
AppConst constants that determine the appearance and styling of the entire UI
Properties of AppConst
table TableInfo configuration for the table view
Properties of TableInfo
column_names map<str(DetailField), str> 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</> header_style str styles to apply to the text in the header row
Examples of table
table: header_style: clear underline tree TreeInfo shapes to use to print trees
Properties of TreeInfo
pipe_space str the shape to use an alternative to "│ "
space_space str the shape to use an alternative to " "
tee_dash str the shape to use an alternative to "├─ "
bend_dash str the shape to use an alternative to "└─ "
Examples of tree
tree: pipe_space: "║ " space_space: " " tee_dash: "╠═ " bend_dash: "╚═ " imp_styles seq<(int, string)> pairings of importance levels with styling directives
Properties of (int, str)
0 int the importance level
1 str 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.