Pretty
pls output is cleaner, friendlier and more colorful. Who doesn't like a
+little color in their terminal?
404
Page not found. Check the URL or try using the search bar.
pls has the distinction of being an ls(1) replacement specifically
+targeted a pro audience. This leads to different motivations, different
+decisions, different choices and different defaults. This also gives us the
+advantage of being able to provide features that are powerful but complex.
There are other ls(1) alternatives that have been around for longer and have
+sizeable user bases.
| Tool | Language | GitHub stars |
|---|---|---|
| exa | Rust | |
| eza | Rust | |
lsd | Rust | |
colorls | Ruby |
pls strives to provide all the features expected from these tools, and more.
+For an idea, here is a comparison between pls and the most popular
+alternatives, eza and its predecessor
+exa.
eza hides files with a leading dot by default, an approach it inherits from
+ls(1). pls dims or hides files based on their
+importance, making it suitable for modern dev
+workflows involving tooling configs.
eza uses arcane environment variables for customisation. pls uses
+cascading YAML files to enable per-project configuration
+that's also more readable, maintainable and ergonomic. You can also check
+these config files into your VCS and share them with your team.
eza uses globs which limits the match to simple queries. pls uses
+specs which match files using the full power of regex and
+then provide both styling and icons for their matches.
+These specs can also be cascaded.
eza output is very colorful, but limited to customisation using ANSI escape
+codes. pls employs sparse color and formatting, to add meaning or context,
+and these styles can be customised using English names or
+even RGB notation.
pls has more metadata fields compared to eza. It
+also allows the user to view some metadata fields in multiple ways (including
+simultaneously), which eza cannot do.
eza provides filtering by glob matches and sorting by one field. pls
+provides filtering (by regex or
+type) and sorting (by multiple
+selections out of over 18 bases ร 2 directions).
eza can dim a small list of generated files. pls has a much more powerful
+collapse feature that can render generated files
+differently and can be extended with specs.
eza defaults to no icons, grid view, files mixed with folders and sorting by
+name. pls defaults to showing icons, list view, folders listed first and
+leading dots aligned and sorting by canonical name.
eza's interface is much more compatible with ls(1) in the base case. A lot
+of ls(1) options map 1:1 with eza. pls does not maintain compatibility
+with ls(1) CLI flags.
eza is a mature product with a large contributor base. pls is a young
+project with a novice ๐ฆ Rustacean maintainer.
+Contributions, both in code and as
+sponsorship, are welcome!
The spec system pls uses might be slow when listing lots of files due to
+its Cartesian product complexity. Also, pls lacks the speed optimisations
+that a mature tool like eza has built over time.
eza can show if a file has extended attributes. pls opted not to do this
+because it's not a common use case.
eza has a long grid view (which is a combination of pls 's
+detail and grid views) that
+are not yet present in pls .
eza has a tree mode that pls does not yet have.
eza supports Windows which pls does not yet do.
Here are some questions you might have about pls , and the answers to those
+questions.
Why the name pls ?
The name pls is a play on the ls(1) command. I picked it because it was
+short, memorable and only one keypress away from
+ls(1). If you prefer a different name you can always alias it.
alias rls="pls"Does pls support Windows?
No. pls , being a tool for pros, favours operating systems that are popular
+with those users, which Windows is not. This may change in the future if there
+is considerable demand and there are
+open-source contributions towards that goal.
Is pls a replacement for ls(1)?
No. pls is an alternative, not a replacement, for ls(1). It some more
+features, prints prettier output and offers a lot of customisation, which make
+it ideal for human usage, but for scripts, ls(1) is still a better choice
+because it is tried, tested and trusted, not to mention ubiquitous.
Why build an ls(1) alternative?
IDEs and code editors use helpful UI patterns like icons and colors to
+disambiguate files and provide more information about them like their file type
+and VCS status. pls brings these features to the terminal.
Why build another ls(1) alternative?
None of the existing ls(1) alternatives have features that make pro workflows
+easier or more pleasant. pls is the first ls(1) alternative that focuses
+on the niche demographic of pros who will appreciate a powerful feature set and
+deep customisation.
Why Rust and not <language>?
+Rust is a good choice for CLI utilities because it enables them to be very +performant. The pros don't want to see lag in a core part of your workflow.
+Before I learned Rust, pls was written in Python (which was another reason
+it's called pls ). It seemed like a good fit at the time because it was
+decently fast and easy to develop and distribute, but at a certain point Python
+started becoming a speed bottleneck. The point being, give me a good reason, and
+I'll rewrite it.
Is pls better than <alternative>?
pls makes no claim of being better than any other tool, although we do try!
+Our claim is that pls is a better fit for developers and pros because it has
+some powerful, and thus complex, features that not everyone will use. If another
+tool has a feature you miss, feel free to open an issue or better yet, a pull
+request! See how pls compares to other ls(1)
+alternatives.
Is pls free?
pls is free in both senses of the word. It does not cost anything to
+download and install and the source code is freely available to read, modify and
+distribute. pls is licensed under version 3, or later, of the GNU
+GPL.
pls is a prettier and powerful ls(1) for the pros. It is a modern
+alternative to ls(1), which has been around for over half a century.
For developers who spend a lot of time in the terminal, pls is a
+game-changer. It brings a touch of joy to an essential and routine task you
+perform hundreds of times a day. By utilising the full capabilities of a
+terminal, pls can alleviate cognitive strain, making both tasks of exploring
+your directories, and searching for specific files, effortless.
pls is a prettier and powerful ls(1) for the pros. The "p" stands for:
Pretty
pls output is cleaner, friendlier and more colorful. Who doesn't like a
+little color in their terminal?
Powerful
pls providers more features than the competition. It uses a cascading
+config system with specs.
Performant
pls is speedy and performant (written in Rust). It continues to be fast
+even with all features enabled.
Practical
pls has sensible defaults and an effortless interface. The CLI is
+fluent, intuitive and memorable.
Petite
pls is a small, single-file, binary executable. It supports both Mac and
+Linux.
Pliable
pls can be extensively tweaked by power users and pros. Personalise it
+exactly how you like it.
Personable
pls prioritises consumption by humans over scripts. The output is pretty
+and readable, by default.
You can refer to our comparison of pls to other
+ls(1) alternatives, notably exa/eza.
For more information, take a look at the FAQs. If your question +isn't answered there, feel free to start a +GitHub discussion.
pls uses simple YAML-based config files. This makes it
+easy to
This page consists of some configs to get you started. If you have a config that +you'd like to share with others, please share with us.
+Since pls comes with a very minimal configuration out-of-the-box, you can
+use this to set up pls for most common file types.
icons: pdf: "๎ฝ" # nf-seti-pdf image: "๏ฅ" # nf-oct-image audio: "๎ธ" # nf-seti-audio video: "๏ฌ" # nf-oct-video text: "๎" # nf-seti-text table: "๓ฐซ" # nf-md-tablespecs: - pattern: \.pdf$ icon: pdf - pattern: \.(txt|rtf)$ icon: text - pattern: \.(csv|tsv)$ icon: table - pattern: \.(mp3|wav|aac)$ icon: audio - pattern: \.(png|jpg|bmp|webp)$ icon: image - pattern: \.(mp4|mov|avi|mkv|webm)$ icon: videoIf you work with a lot of Microsoft Office apps, you can use this config to have +pretty and consistent icons for all your work files.
+icons: word: "๓ฑ" # nf-md-microsoft_word excel: "๓ฑ" # nf-md-microsoft_excel powerpoint: "๓ฑ" # nf-md-microsoft_powerpointspecs: - pattern: \.docx?$ icon: word - pattern: \.xlsx?$ icon: excel - pattern: \.pptx?$ icon: powerpointpls being a Rust project, comes with the configuration for Rust projects
+baked-in.
If you build Python projects using Pipenv, Poetry or PDM, this config is for +you.
+icons: python: "๎" # nf-seti-pythonspecs: - pattern: \.py$ icon: python style: rgb(255,212,59) - pattern: requirements.*\.txt$ icon: lock - pattern: ^(pyproject\.toml|Pipfile)$ icon: package - pattern: ^(poetry|pdm)\.lock$ icon: lock importance: -1 collapse: name: pyproject.toml - pattern: ^Pipfile.lock$ icon: lock importance: -1 collapse: name: PipfileIf you build web applications without any of the major JavaScript frameworks, +this config is for you.
+icons: html: "๎" # nf-seti-html css: "๎" # nf-seti-css sass: "๎" # nf-seti-sass less: "๎" # nf-seti-less markdown: "๎บซ" # nf-fa-markdownspecs: - pattern: \.md$ icon: markdown - pattern: \.x?html?$ icon: html style: rgb(255,212,59) - pattern: \.s[ac]ss$ icon: sass style: rgb(255,212,59) - pattern: \.less$ icon: less style: rgb(255,212,59) - pattern: \.css$ icon: css style: rgb(79,192,141) collapse: ext: scssIf you build JavaScript/TypeScript projects, this config is for you. It supports +npm and pnpm as package managers, and Vue and React frameworks as well. If you +use JavaScript for frontend development, you should also inherit the web dev +config above.
+icons: javascript: "๓ฐ" # nf-md-language_javascript typescript: "๓ฐฆ" # nf-md-language_typescript vue: "๎ " # nf-seti-vue react: "๎ฅ" # nf-seti-reactspecs: - pattern: \.ts$ icon: typescript style: rgb(49,120,198) - pattern: \.(c|m)?js$ icon: javascript style: rgb(247,223,30) collapse: ext: ts - pattern: \.vue$ icon: vue style: rgb(79,192,141) - pattern: \.(j|t)sx$ icon: react style: rgb(97,218,251) - pattern: ^package-lock\.json$ icon: package - pattern: ^(pnpm-lock.yaml|package-lock.json)$ icon: lock importance: -1 collapse: name: package.jsonpls performs slight tweaks to alignment to account for leading dots. When
+alignment is enabled, the leading dots are moved one position to the left, so
+that the actual file names are aligned. Also the leading dots are slightly
+dimmed to reduce their visual prominence.
--align/-a can be used to turn alignment on or off. File names are aligned
+by default because usually it's the name that's important.
pls # or --align=true or -a=true+ +โ๓ฐข .gitignore +๏ LICENSE +๏ .pls.yml +๏ญ README.md
pls --align=false # or -a=false+โ๓ฐข .gitignore +๏ LICENSE +๏ .pls.yml +๏ญ README.md
In software development it is a common occurrence to have files that are +generated from other files.
+pls has the novel ability for you to define the collapsing rules for these
+derived files so that they are both listed together with their source, and also
+depicted in a way that emphasises their dependency relationship.
pls can also nest collapsed nodes into other collapsed nodes, forming a full
+tree of collapses.
--collapse/-c can be used to turn collapsing on or off. pls enables this
+collapsing behaviour by default.
pls # or --collapse=true or -c=true+ +โ๏ Cargo.toml +ย โโ ๏ Cargo.lock
pls --collapse=false # or -c=false+ +โ๏ Cargo.lock +๏ Cargo.toml
Using the configuration system, you can both change the appearance of the tree +and also define additional rules for collapsing in addition to the built-in +ones.
+Here is an example showing nested collapses. It uses simple ASCII characters to +render colorful collapse trees.
+app_const: tree: pipe_space: "<magenta>|</> " space_space: " " # should be as wide as the other entries for alignment tee_dash: "<green>+--</> " bend_dash: "<blue>+--</> "specs: - pattern: ^\.?\w{1}$ icon: file - pattern: b collapse: name: a - pattern: c collapse: name: b - pattern: \.d collapse: name: b - pattern: e collapse: name: a+โย a +ย +-- b +ย | +-- c +ย | +-- .d +ย +-- e +๏ .pls.yml
pls makes a lot of use of colors throughout the output. This makes it very
+easy to grok the output and also makes it look pretty.
By default pls will display colors if the terminal supports it and will
+disable colors if the output is being piped to another command.
pls also respects the NO_COLOR and CLICOLOR_FORCE environment variables
+that can be used forcefully disable or enable colors respectively.
env NO_COLOR=true pls # or pls | cat+ +โLink# T Permissions User Group Size Modified Name +ย 2 d rwx r-x r-x runner docker 2024-Oct-07 12:26pm ๏ป dir/ +ย 1 l rwx rwx rwx runner docker 10.0 B 2024-Oct-07 12:26pm ๓ฐน block_dev@ ๓ฑฃ /dev/disk0 +ย 1 l rwx rwx rwx runner docker 9.0 B 2024-Oct-07 12:26pm ๓ฐน char_dev@ ๓ฐ /dev/null +ย 1 p rw- r-- r-- runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐฅ fifo| +ย 1 f rw- r-- r-- runner docker 1.0 MiB 2024-Oct-07 12:26pm file +ย 1 s rwx r-x r-x runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐจ socket= +ย 1 l rwx rwx rwx runner docker 5.0 B 2024-Oct-07 12:26pm ๓ฐน sym@ ๓ฐ ./dir
pls # or env CLICOLOR_FORCE=true pls | cat+โLink# T Permissions User Group Size Modified Name +ย 2 d rwx r-x r-x runner docker 2024-Oct-07 12:26pm ๏ป dir/ +ย 1 l rwx rwx rwx runner docker 10.0 B 2024-Oct-07 12:26pm ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+ย 1 l rwx rwx rwx runner docker 9.0 B 2024-Oct-07 12:26pm ๓ฐน char_dev@ ๓ฐ /dev/null +ย 1 p rw- r-- r-- runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐฅ fifo| +ย 1 f rw- r-- r-- runner docker 1.0 MiB 2024-Oct-07 12:26pm file +ย 1 s rwx r-x r-x runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐจ socket= +ย 1 l rwx rwx rwx runner docker 5.0 B 2024-Oct-07 12:26pm ๓ฐน sym@ ๓ฐ ./dir
pls can stat the nodes to derive more information, called metadata, about
+them, which it can then present in a tabular format. This is called the detail
+view.
--det/-d can be used to select the detail columns the user wants to see, and
+indirectly turn the detail view on or off. The detail view is considered to be
+turned off if no detail field is chosen.
The --det/-d flag can be specified multiple times to enable multiple fields.
+Each time it can take one of these values.
| Value | Description | Standard |
|---|---|---|
dev | device ID | |
ino | inode number | |
nlink | number of hard links | Yes |
typ | node type | Yes |
perm | symbolic permissions | Yes |
oct | octal permissions | |
user | owner user name | Yes |
uid | owner user ID | |
group | owner group name | Yes |
gid | owner group ID | |
size | storage space | Yes |
blocks | number of blocks | |
btime | created at; "b" for birth | |
ctime | changed at; originally meant "created at" | |
mtime | modified at | Yes |
atime | accessed at | |
git | Git status | |
none | shorthand: no details | |
std | shorthand: the standard set of details | |
all | shorthand: all details |
The column headers for the detail view can be toggled using the
+--header/-H flag.
When parsing the --det/-d argument, values are read from the CLI, in order,
+and added to a vector of fields till we encounter a shorthand value. If the
+shorthand value is none, the vector is cleared. The other two shorthands are
+expanded and added to the vector.
std can be used to show the fields shown by ls(1) with the -l flagall can be used to show every available metadata fieldFor example, consider the pls invocation below.
pls --det=dev --det=ino --det=none --det=std --det=gitdev is added to the list.ino is added to the list.none is encountered.nlink, typ, perm, user, group, size and mtime are added to the
+list when std is encounteredgit is added to the list.The final set is thus nlink, typ, perm, user, group, size, mtime
+and git. Since this is more than zero, pls will activate the detail view.
pls # or --det=none or -d=none+ +โ๏ป dir/ +๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+๓ฐน char_dev@ ๓ฐ /dev/null +๓ฐฅ fifo| +ย file +๓ฐจ socket= +๓ฐน sym@ ๓ฐ ./dir
pls --det=user --det=group # or -d=user -d=group+ +โUser Group Name +runner docker ๏ป dir/ +runner docker ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+runner docker ๓ฐน char_dev@ ๓ฐ /dev/null +runner docker ๓ฐฅ fifo| +runner docker file +runner docker ๓ฐจ socket= +runner docker ๓ฐน sym@ ๓ฐ ./dir
pls --det=std # or -d=std+ +โLink# T Permissions User Group Size Modified Name +ย 2 d rwx r-x r-x runner docker 2024-Oct-07 12:26pm ๏ป dir/ +ย 1 l rwx rwx rwx runner docker 10.0 B 2024-Oct-07 12:26pm ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+ย 1 l rwx rwx rwx runner docker 9.0 B 2024-Oct-07 12:26pm ๓ฐน char_dev@ ๓ฐ /dev/null +ย 1 p rw- r-- r-- runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐฅ fifo| +ย 1 f rw- r-- r-- runner docker 1.0 MiB 2024-Oct-07 12:26pm file +ย 1 s rwx r-x r-x runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐจ socket= +ย 1 l rwx rwx rwx runner docker 5.0 B 2024-Oct-07 12:26pm ๓ฐน sym@ ๓ฐ ./dir
pls --det=all # or -d=all+ +โDevice inode Link# T Permissions SUGO User UID Group GID Size Blocks Created Changed Modified Accessed Git Name +ย 2065 551545 2 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ป dir/ +ย 2065 551759 1 l rwx rwx rwx 777 runner 1001 docker 127 10.0 B 0 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+ย 2065 551613 1 l rwx rwx rwx 777 runner 1001 docker 127 9.0 B 0 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐน char_dev@ ๓ฐ /dev/null +ย 2065 551584 1 p rw- r-- r-- 644 runner 1001 docker 127 0.0 B 0 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐฅ fifo| +ย 2065 551763 1 f rw- r-- r-- 644 runner 1001 docker 127 1.0 MiB 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm file +ย 2065 551605 1 s rwx r-x r-x 755 runner 1001 docker 127 0.0 B 0 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐจ socket= +ย 2065 551580 1 l rwx rwx rwx 777 runner 1001 docker 127 5.0 B 0 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐน sym@ ๓ฐ ./dir
Each of the detail fields is deeply customisable. Read on to know more the +customisation options supported by each field.
+dev - Device IDThis field can by styled by specifying entry_const.dev_style. pls does not
+style this field by default, because a style would not add any meaning.
ino - Inode numberThis field can by styled by specifying entry_const.ino_style. pls does not
+style this field by default, because a style would not add any meaning.
nlink - Number of hard linksThis field can be styled different based on the type of the node and the number
+of hard links the node has. pls allows files with more than one hard link
+and directories with only one hard link to be styled differently because these
+are peculiar cases. The opposite scenario is more common.
| Type | nlink | Style |
|---|---|---|
| file | 1 | entry_const.nlink_styles.file_sing |
| file | >1 | entry_const.nlink_styles.file_plur |
| dir | 1 | entry_const.nlink_styles.dir_sing |
| dir | >1 | entry_const.nlink_styles.dir_plur |
typ - Node type characterpls allows you to completely change the type character to whatever makes you
+think of the node's type.
| Type | Character |
|---|---|
| Dir | entry_const.typ.dir.ch |
| Symlink | entry_const.typ.symlink.ch |
| FIFO | entry_const.typ.fifo.ch |
| Socket | entry_const.typ.socket.ch |
| Block device | entry_const.typ.block_device.ch |
| Char device | entry_const.typ.char_device.ch |
| File | entry_const.typ.file.ch |
| Unknown | entry_const.typ.unknown.ch |
perm - Symbolic permissionsThis field can by styled by specifying entry_const.perm_style. pls allows
+individual customisation of each of the permission characters for read (r),
+write (w), execute (x), special (s/S/t/T) and none (-).
| Bit | Style | | ------- | entry_const | | Read |
+entry_const.perm_styles.read | | Write | entry_const.perm_styles.write | |
+Execute | entry_const.perm_styles.execute | | Special |
+entry_const.perm_styles.special | | None | entry_const.perm_styles.none |
oct - Octal permissionsAn octal permission has either three (user, group, other) or four (special, plus
+the previous three) digits. pls allows customisation of each of these digits
+individually.
| Digit | Style |
|---|---|
| Special | entry_const.oct_styles.special |
| User | entry_const.oct_styles.user |
| Group | entry_const.oct_styles.group |
| Other | entry_const.oct_styles.other |
user/uid - Owner user name/UIDpls styles the name or UID of the user that owns the node differently based
+on whether the user is the current user or not. These styles apply identically
+to the user name and the UID.
| User | Style |
|---|---|
| Current | entry_const.user_styles.curr |
| Other | entry_const.user_styles.other |
group/gid - Owner group name/GIDpls styles the name or GID of the group that owns the node differently based
+on whether the current user belongs to the group or not. These styles apply
+identically to the group name and the GID.
| Group | Style |
|---|---|
| Current | entry_const.group_styles.curr |
| Other | entry_const.group_styles.other |
size - Storage spacepls shows the size of the node in human readable format by default, while
+allowing the user to choose between three unit systems. See
+units for more information about unit systems.
You can style the three components of a size value independently. Ideally, you +want to emphasise magnitude and prefix and de-emphasise the base (which is +always "B" for bytes).
+ + + + + + + + + + + + + + + + + + + + + +| Component | Style |
|---|---|
| Magnitude | entry_const.size_styles.mag |
| Prefix | entry_const.size_styles.prefix |
| Base unit | entry_const.size_styles.base |
blocks - Storage blockspls shows the total number of physical blocks of size 512 bytes actually
+allocated on the disk for the node. This can be more than what the actual size
+on disk indicates if the node has "holes".
This field can by styled by specifying entry_const.blocks_style. pls does
+not style this field by default, because a style would not add any meaning.
btime/ctime/mtime/atime - Timestampspls can display the four common timestamps of a file. pls allows you to
+choose the exact format in which you prefer the timestamps to be.
| Timestamp | Format |
|---|---|
| Created at | entry_const.timestamp_formats.btime |
| Changed at | entry_const.timestamp_formats.ctime |
| Modified at | entry_const.timestamp_formats.mtime |
| Accessed at | entry_const.timestamp_formats.atime |
The timestamp can use components from the time crate's
+format description
+freely mixed with markup tags.
git - Git status๐ง This feature is a work in progress and will be coming in a future version.
+Here is a custom config that approximately matches the output of
+eza or exa at least for the
+columns that they have in common with pls (pls has more, in case you
+were wondering).
entry_const: dev_style: magenta ino_style: magenta nlink_styles: file_sing: red bold file_plur: red bold dir_sing: red bold dir_plur: red bold typ: dir: ch: <bold cyan>d</> symlink: ch: <magenta>l</> fifo: ch: <yellow>|</> socket: ch: <green>s</> char_device: ch: <blue bg:green>b</> block_device: ch: <blue bg:yellow>c</> file: ch: "." oct_styles: special: magenta user: magenta group: magenta other: magenta user_styles: curr: bold yellow other: "" group_styles: curr: bold yellow other: "" size_styles: mag: green bold prefix: green base: hidden blocks_style: cyan timestamp_formats: btime: <blue>[day] [month repr:short] [hour repr:24]:[minute]</> ctime: <blue>[day] [month repr:short] [hour repr:24]:[minute]</> mtime: <blue>[day] [month repr:short] [hour repr:24]:[minute]</> atime: <blue>[day] [month repr:short] [hour repr:24]:[minute]</>app_const: table: header_style: clear column_names: dev: <underline>Device</> ino: <underline>inode</> nlink: <underline>Links</> perm: <underline>Permissions</> oct: <underline>Octal</> user: <underline>User</> uid: <underline>UID</> group: <underline>Group</> gid: <underline>GID</> size: <underline>Size</> blocks: <underline>Blocks</> btime: <underline>Date Created</> ctime: <underline>Date Changed</> mtime: <underline>Date Modified</> atime: <underline>Date Accessed</> git: <underline>Git</> name: <underline>Name</>+โDevice inode Links T Permissions Octal User UID Group GID Size Blocks Date Created Date Changed Date Modified Date Accessed Git Name +ย 2065 551545 2 d rwx r-x r-x 755 runner 1001 docker 127 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๏ป dir/ +ย 2065 551759 1 l rwx rwx rwx 777 runner 1001 docker 127 10.0 0 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+ย 2065 551613 1 l rwx rwx rwx 777 runner 1001 docker 127 9.0 0 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๓ฐน char_dev@ ๓ฐ /dev/null +ย 2065 551584 1 | rw- r-- r-- 644 runner 1001 docker 127 0.0 0 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๓ฐฅ fifo| +ย 2065 551763 1 . rw- r-- r-- 644 runner 1001 docker 127 1.0 Mi 8 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 file +ย 2065 551871 1 . rw- r-- r-- 644 runner 1001 docker 127 1.6 Ki 8 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๏ .pls.yml +ย 2065 551605 1 s rwx r-x r-x 755 runner 1001 docker 127 0.0 0 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๓ฐจ socket= +ย 2065 551580 1 l rwx rwx rwx 777 runner 1001 docker 127 5.0 0 07 Oct 12:26 07 Oct 12:26 07 Oct 12:26 ๓ฐน sym@ ๓ฐ ./dir
In the grid view, pls can position nodes in one of two ways.
Down: pls will place nodes along a column and move on to the next column
+once the current one has been filled with a specific number of rows.
Across: pls will place nodes along a row and move on to the next row once
+the current one has been filled with a specific number of columns.
--down/-D can be used to turn the downward direction on or off. It is turned
+off by default because writing row-wise requires fewer steps.
pls --grid=true # or --down=false or -D=false+ +โย file_abcd file_efgh +ย file_ijkl ๓ฐน .file_mnop@
pls --grid=true --down=true # or -D=true+โย file_abcd file_ijkl +ย file_efgh ๓ฐน .file_mnop@
pls can reduce the amount of vertical space taken by the output, thus
+reducing the amount of strolling required, by placing the node names in a grid
+instead of a column.
--grid/-g can be used to turn the grid mode on or off. Grid mode is turned
+off by default because it reduces the amount of info shown per file.
The direction of the grid can be changed with the
+--down/-D flag.
All these incompatibilities are the reason why the grid view is not the default +view.
+pls # or --grid=false or -g=false+ +โย file_abcd +ย file_efgh +ย file_ijkl +๓ฐน .file_mnop@ ๓ฐ file_abcd
pls --grid=true # or -g=true+โย file_abcd file_efgh +ย file_ijkl ๓ฐน .file_mnop@
pls shows headers above columns to help understand the output better. If not
+set, these headers intelligently appear when they are needed.
--header/-H can be used to turn headers on or off. It is turned on by
+default if the details view is enabled.
pls --det=std # or --header=true or -H=true+ +โLink# T Permissions User Group Size Modified Name +ย 2 d rwx r-x r-x runner docker 2024-Oct-07 12:26pm ๏ป dir/ +ย 1 l rwx rwx rwx runner docker 10.0 B 2024-Oct-07 12:26pm ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+ย 1 l rwx rwx rwx runner docker 9.0 B 2024-Oct-07 12:26pm ๓ฐน char_dev@ ๓ฐ /dev/null +ย 1 p rw- r-- r-- runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐฅ fifo| +ย 1 f rw- r-- r-- runner docker 1.0 MiB 2024-Oct-07 12:26pm file +ย 1 s rwx r-x r-x runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐจ socket= +ย 1 l rwx rwx rwx runner docker 5.0 B 2024-Oct-07 12:26pm ๓ฐน sym@ ๓ฐ ./dir
pls --det=std --header=false # or -H=false+ +โ2 d rwx r-x r-x runner docker 2024-Oct-07 12:26pm ๏ป dir/ +1 l rwx rwx rwx runner docker 10.0 B 2024-Oct-07 12:26pm ๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+1 l rwx rwx rwx runner docker 9.0 B 2024-Oct-07 12:26pm ๓ฐน char_dev@ ๓ฐ /dev/null +1 p rw- r-- r-- runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐฅ fifo| +1 f rw- r-- r-- runner docker 1.0 MiB 2024-Oct-07 12:26pm file +1 s rwx r-x r-x runner docker 0.0 B 2024-Oct-07 12:26pm ๓ฐจ socket= +1 l rwx rwx rwx runner docker 5.0 B 2024-Oct-07 12:26pm ๓ฐน sym@ ๓ฐ ./dir
Using the configuration system, you can modify the column headers and change +their appearance using styling rules.
+See the detail view configuration for an +example.
pls shows pretty and helpful icons next to files by default. These icons can
+help when visually searching for a specific type of file.
--icon/-i can be used to turn icons on or off. Icons are shown by default
+because they're so pretty and helpful.
pls # or --icon=true or -i=true+ +โ๏ป dir/ +๓ฐฅ fifo| +๓ฐข .gitignore +๏ .pls.yml +๏ญ README.md +๓ฐจ socket= +๓ฐน sym@ ๓ฐ ./dir
pls --icon=false # or -i=false+ +โย dir/ +ย fifo| +.gitignore +.pls.yml +ย README.md +ย socket= +ย sym@ ๓ฐ ./dir
Using the configuration system, you can add more icons, in addition to the
+default set included with pls , and change the default glyphs of built-in
+icons.
Icons are defined in two steps.
+Map an icon name to a glyph.
+If you map a built-in name, you can change default glyphs shown by pls
+for that node. You can use the
+Nerd Fonts reference to find your
+preferred icons.
Associate file name patterns to icon names.
+Refer to the specs guide to learn how to do that.
+pls shows a default icon for some file types (like directory and symlink)
+but comes with dormant mappings for every file type. See the example below for
+how to enable the default icon or use a custom one.
icons: pls: "๓ฐฑซ" # Override the built-in glyph for 'pls'. sock: "๓ฐ" # Define new icon-glyph mapping.entry_const: typ: fifo: icon: fifo # Enable and use the built-in glyph for FIFO pipes. socket: icon: sock # Enable and use a custom icon for sockets.+โ๏ป dir/ +๓ฐฅ fifo| +๓ฐข .gitignore +๓ฐฑซ .pls.yml +๏ญ README.md +๓ฐจ socket= +๓ฐน sym@ ๓ฐ ./dir
pls uses an importance system to both hide certain unimportant nodes as well
+as emphasize certain important ones.
Each node has a default importance of -1 if it starts with a leading dot, and 0 +otherwise. This importance can be overridden using specs.
+An importance scale maps importance levels to styling attributes. Any files with +importance below the scale are hidden.
+--imp/-I can be used to set the baseline importance level. This affects the
+relative importance of all nodes. The default is 0. Setting a higher number will
+reduce the importance level of nodes and hide more of them.
At --imp=-2, a node with importance -2 behaves as it has an importance of 0, a
+node with importance -1 behaves as it has an importance of 1, and so on.
pls --imp=-2 # or -I=-2+ +โ๏ป dir/ +๓ฐข .git/ +๏ .github/ +ย file +๏ญ README.md +๏ src
pls --imp=-1 # or -I=-1+ +โ๏ป dir/ +๓ฐข .git/ +๏ .github/ +ย file +๏ญ README.md +๏ src
pls # or --imp=0 or -I=0+ +โ๏ป dir/ +๏ .github/ +ย file +๏ญ README.md +๏ src
pls --imp=1 # or -I=1+ +โ๏ป dir/ + file +๏ญ README.md +๏ src
pls --imp=2 # or -I=2+ +โ๏ญ README.md +๏ src
pls --imp=2 file # `--imp` has no effect+ +โ file
Using the configuration system, you can extend the importance scale to higher or +lower levels and change the default styles applicable at each level.
+app_const: imp_styles: - [-2, "red"] - [-1, "yellow"] - [1, "green"] - [2, "bright_magenta"]+โ๏ป dir/ +๓ฐข .git/ +๏ .github/ +ย file +๏ .pls.yml +๏ญ README.md +๏ src
pls allows the user to filter the contents by regex matching on names. Name
+matching can be used to exclude the names that match a certain pattern or only
+include the names that match a certain pattern. Both can be used in tandem to
+perform very powerful filtering.
--exclude/-e can be used to remove the files that match the given pattern.
+--only/-o can be used to remove the files that do not match the given
+pattern.
pls # or --only='.*' --exclude='$^'+ +โ๓ฐฉ a.jpg +๎ a.rs +๓ฐฉ b.jpg +๎ b.rs +๓ฐฉ c.jpeg +๎ c.rs
pls --only='(a|c)' --exclude='\.jpe?g$'+ +โ๎ a.rs +๎ c.rs
pls --exclude='\.jpe?g$' a.jpg # `--exclude` has no effect+โ๓ฐฉ a.jpg
pls offers the ability to sort the output in your preferred order by
+choosing as many as you prefer from 18 bases ร 2 directions per base.
--sort/-s can be used to select the sort bases. The flag can be specified
+multiple times to sort by multiple bases. Each time it can take one of these
+values. All values except none can optionally suffixed with an underscore _
+to reverse their direction.
| Name | Description |
|---|---|
| dev | device ID |
| ino | inode number |
| nlink | number of hard links |
| typ | node type |
| cat | node category (directory or file) |
| user | user name |
| uid | user ID |
| group | group name |
| gid | group ID |
| size | storage space |
| blocks | number of blocks |
| btime | created at; "b" for birth |
| ctime | changed at; originally meant "created at" |
| mtime | modified at |
| atime | accessed at |
| name | node name |
| cname | canonical name (name in lower case with leading symbols stripped) |
| ext | file extension |
| none | shorthand: no sorting |
By default, pls sorts file by cat and cname, which means
cat)cname)When sorting by multiple sort bases, the first listed basis is the primary sort +basis, the second is the tie-breaker for the first, the third is the tie-breaker +for the second and so on.
+ +When parsing the --sort/-s flag, values are read from the CLI, in order, and
+added to a vector of sort bases till we encounter the shorthand value none,
+which clears the vector.
For example, consider the pls invocation below.
pls --sort=cat --sort=cname --sort=none --sort=mtime_cat is added to the list.cname is added to the list.none is encountered.mtime_ is added to the list.pls # or --sort=cat --sort=cname or -s=cat -s=cname+ +โ๏ป dir_a/ +๏ป dir_c/ +๏ป dir_e/ +๎ file_b.txt +๎ file_d.txt +๎ file_f.txt
pls --det=ino --det=typ --det=size --sort=cat_ --sort=size_ --sort=ino+ +โ inode T Size Name +554697 f 1.0 MiB ๎ file_d.txt +551580 f 1.0 KiB ๎ file_b.txt +554724 f 14.0 B ๎ file_f.txt +551545 d ๏ป dir_a/ +554696 d ๏ป dir_c/ +554723 d ๏ป dir_e/
Here the --sort/-s arguments have this effect:
cat_ sorts directories before files.size_ sorts nodes by size in descending order.ino sorts nodes by inode number in ascending order.pls shows suffixes for many common file types. This is usually helpful to
+identify file types by just looking at the name. The suffixes are generally
+dimmed so as to not appear like they're actually a part of the file name.
--suffix/-S can be used to turn suffixes on or off. Suffixes are shown by
+default because of their utility.
pls # or --suffix=true or -S=true+ +โ๏ป dir/ +๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+๓ฐน char_dev@ ๓ฐ /dev/null +๓ฐฅ fifo| +ย file +๓ฐจ socket= +๓ฐน sym@ ๓ฐ ./dir
pls --suffix=false # or -S=false+ +โ๏ป dir +๓ฐน block_dev ๓ฑฃ
/dev/disk0+๓ฐน char_dev ๓ฐ /dev/null +๓ฐฅ fifo +ย file +๓ฐจ socket +๓ฐน sym ๓ฐ ./dir
Using the configuration system, you can add suffixes for more file types, in
+addition to the default set included with pls , and change the existing
+suffixes to your liking.
entry_const: typ: file: suffix: "<dimmed>!</>" dir: suffix: "<dimmed>></>" symlink: suffix: "<dimmed>โ</>" fifo: suffix: "<dimmed>-</>" socket: suffix: "<dimmed>โ</>" char_device: suffix: "<dimmed>๓ฐง</>" block_device: suffix: "<dimmed>๏
</>"+โ๏ป dir> +๓ฐน block_devโ ๓ฑฃ
/dev/disk0+๓ฐน char_devโ ๓ฐ /dev/null +๓ฐฅ fifo- +ย file! +๏ .pls.yml! +๓ฐจ socketโ +๓ฐน symโ ๓ฐ ./dir
pls can trace symlinks to their targets, and in the process identify broken
+or circular symlinks. pls will also expand chains of symlinks.
--sym/-l can be used to turn symlink tracing on or off. It is turned on by
+default but disabled in grid view due to space constraints.
pls # or --sym=true or -l=true+ +โ๏ป dir/ +๓ฐน a@ ๓ฐ a +๓ฐน b@ ๓ฐ c +๓ฐน c@ ๓ฐ b +๓ฐน d@ ๓ฑฃ
nonexistent+๓ฐน e@ ๓ฐ dir +๓ฐน f@ ๓ฐ dir +๓ฐน g@ ๓ฐ f ๓ฐ dir
pls --sym=false # or -l=false+ +โ๏ป dir/ +๓ฐน a@ +๓ฐน b@ +๓ฐน c@ +๓ฐน d@ +๓ฐน e@ +๓ฐน f@ +๓ฐน g@
Using the configuration system, you can customise the symlink styles and arrows. +Note that for valid symlinks, the style is only applied to the arrow and not the +target.
+entry_const: symlink: ok: sep: --> style: green broken: sep: ~~> style: red bold cyclic: sep: \<-> # '<' must be escaped style: yellow italic error: sep: -x- style: red italic+โ๏ป dir/ +๓ฐน a@ <-> a +๓ฐน b@ <-> c +๓ฐน c@ <-> b +๓ฐน d@ ~~>
nonexistent+๓ฐน e@ --> dir +๓ฐน f@ --> dir +๓ฐน g@ --> f --> dir +๏ .pls.yml
pls allows the user to only list specific node types in the output.
--typ/-t can be used to select the node types the user wants to see. The
+flag can be specified multiple times to enable multiple file types. Each time it
+can take one of these values.
| Value | Description |
|---|---|
| dir | regular folder |
| symlink | symbolic link |
| fifo | named pipe |
| socket | file-based socket |
| block_device | block special device file |
| char_device | character special device file |
| file | regular file |
| none | shorthand: no node types |
| all | shorthand: all node types |
When parsing the --typ/-t flag, values are read from the CLI, in order, and
+added to a vector of node types till we encounter a shorthand value. If the
+shorthand value is none, the vector is cleared. If the shorthand value is
+all, the vector is filled with all the node types.
For example, consider the pls invocation below.
pls --typ=symlink --typ=all --typ=none --typ=dirsymlink is added to the list.symlink.none is encountered.dir is added to the list.The final set contains only dir and so pls will only list the directories.
pls # or --typ=all or --t=all+ +โ๏ป dir/ +๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+๓ฐน char_dev@ ๓ฐ /dev/null +๓ฐฅ fifo| +ย file +๓ฐจ socket= +๓ฐน sym@ ๓ฐ ./dir
pls --typ=dir --typ=symlink # or -t=dir -t=symlink+ +โ๏ป dir/ +๓ฐน block_dev@ ๓ฑฃ
/dev/disk0+๓ฐน char_dev@ ๓ฐ /dev/null +๓ฐน sym@ ๓ฐ ./dir
pls --typ=dir --typ=symlink fifo # `--typ` has no effect+โ๓ฐฅ fifo|
pls can show the sizes of files in three unit systems.
--unit/-u can be used to set the unit system to use. pls uses the binary
+unit system by default.
pls --det=size # or --unit=binary or --u=binary+ +โ Size Name +1.0 MiB a +1.0 MiB b +1.0 MiB c
pls --det=size --unit=decimal # or --u=decimal+ +โ Size Name +1.0 MB a +1.0 MB b +1.0 MB c
pls --det=size --unit=none # or --u=binary+ +โ Size Name +1048589 B a +1048589 B b +1048589 B c
Using the configuration system, you can modify the appearance of size magnitude, +prefix and base unit.
+See the detail view configuration for an +example.
pls is constantly evolving with new features added, existing ones refined
+and bugs fixed. We have bold plans for pls to make it the best ls(1)
+alternative out there. To that end, here are some features that pls could
+support soon.
Git integration
+Git integration is coming soon and will enable the following sub-features:
+.gitignore parsing for importance levels--det=gitSpec layers
+Currently, custom specs always have higher precedence than built-in ones. +Defining specs in layers will enable them to be injected between, instead of +after, the built-in specs.
+Feature parity
+We are working on bringing feature parity between pls and
+its competition.
To make these features a reality, we need your help. If you are interested in
+contributing to pls , please see the
+contribution guide.
pls accepts contributions in many forms, ranging from direct code
+contributions to sponsorships.
Reporting bugs
+Reporting bugs helps make pls more stable and reliable. If you find a bug,
+or if something breaks, please
+open an issue.
Suggesting features
+pls aims to be a capable alternative to ls(1). If a feature you need is
+absent from pls , please open an
+issue.
Submitting code
+We welcome your code contributions towards bug fixes, new features and other +enhancements at our +GitHub repository.
+Writing docs
+If you can improve this documentation, please do so. The docs are
+co-located with the code
+inside the docs/ directory.
Starring the repo
+Be sure to star the GitHub repo as a gesture
+of appreciation if pls is an improvement to your workflow.
Spreading the word
+If you like pls , you should tell your friends, post about it to social
+media and convince others to try it.
Sponsoring me
+You can sponsor me, or another
+contributor, to contribute to pls in any of the ways above.
Thanks for giving pls a try. We hope you like using it as much as we do.
pls features.These are the different ways you can install pls on your machine.
pls is available to install for macOS and Linux via our official Homebrew
+tap. Currently pls is not available
+through Homebrew core, but it is planned for the future.
brew install pls-rs/pls/plsThis command will fetch and install the latest release of pls from GitHub.
If you have the Rust toolchain installed on your computer, you can build from +source locally for your operating system and architecture. Also, we welcome your +contributions!
+cargo install --git https://github.com/pls-rs/plsYou can use --tag to install a specific version, The current latest version is
+v--branch main to get the latest, unreleased
+version.
The CI + CD job compiles binaries for each supported OS on every code push.
+Additionally, we also cut periodic releases from the main branch of the
+repository. You can download the binary for your operating system and
+architecture by following these steps.
Download the binary file. You can either download the binary associated with +a release or a commit.
+Release
+pls .Commit
+pls 's
+CI + CD workflow.Download the binary as per your operating system.
+pls-x86_64-apple-darwin for macOSpls-x86_64-unknown-linux-musl for LinuxUnzip the archive and find the single pls executable.
Place the executable on your $PATH. To do this, you can either add the
+directory that contains it to the path, or move/symlink the binary to a
+directory that is already on your $PATH.
You can check if pls was installed correctly and present on your $PATH by
+running the following command. If you see a version number, you're good to go!
pls --version # or -V+pls
0.0.0
To run pls , type the following command into any terminal.
plsBy default, pls lists the contents of the current working directory, but you
+can pass any number of different files or directories as
+positional arguments.
If a directory path is passed, all the files and directories within that
+directory are listed. This is useful to see what's in the folder. If a file path
+is passed, only the file itself is listed. On its own, that's not very useful
+except to see if that file exists. But with the
+--det/-d flag, pls can display quite a lot of
+metadata for the file.
To see what pls is capable of, and how to use those features, check out the
+built-in help. You can see the detailed help or a quick reference using the
+--help/-h flags respectively.
pls --help # or -h+
plsis a prettier and powerfullsfor the pros. +ย +Usage: pls [OPTIONS] [PATHS]... +...
The terminal is a unique interface. It is purely text-based yet capable of
+displaying colors and formatting, using ANSI escape codes. These codes are
+difficult to remember and use, so pls uses a custom approach.
The markup language used by pls is similar to XML. The directives are
+written inside < and > and wrapped around the text to style. The closing tag
+always matches the last opened tag, regardless of the text inside it, so it's
+customary to leave it blank.
You can use a single directive, or a combination of directives, separated by +spaces.
+<bold>bold text</> <bold italic>bold italic text</>bold text bold italic text+
Tags can be nested inside each other and will be joined in order.
+<bold><italic>bold italic text</> only bold text</>+bold italic text only bold text
To overwrite all outer tags and start a fresh context, use clear.
<bold><clear blue><clear>plain text</> only blue text</> only bold text</>plain text only blue text only bold text+
Terminals can style text in many ways. pls allows you to use any permutation
+of these styles in your configs.
You can use a single style directive.
+<bold>bold text</>bold text+
You can use any combination of style directives.
+<bold italic underline strikethrough>BIUS text</>+BIUS text
Color support in terminals can range from 16 named colors to 16 million RGB
+colors! pls allows you to use all the colors supported by your terminal.
Named colors consist of 8 regular colors and 8 bright colors (one for each of +the regular ones).
+To use the named colors in pls you can use the color name directly as a
+directive in the tag.
<blue>blue text</>blue text
+To use the bright variant, you can prefix bright_ before the color name.
<bright_red>orange text</> <bright_magenta>violet text</>orange text violet text+
To use a color as the background, you can prefix bg: before the color name.
<bg:blue><black>black text</> <white>white text</></>black text white text
+pls also supports using RGB colors. These colors can be specified using a
+triplet of three u8 numbers, each between 0 and 255, both inclusive.
<rgb(0,255,0)>pure green text</>pure green text
+To use a color as the background, you can prefix bg: before the color name.
<bg:rgb(255,0,0)><black>black text</> <white>white text</></>black text white text First pls organises paths supplied as CLI arguments into groups of solo
+files and individual directories. Then it prints each group one by one.
pls README.md Cargo.toml Cargo.lock src docs+ +โ๏ญ README.md +๏ Cargo.toml +๏ Cargo.lock + +src: +๏ป args/ +ย โโ ๎ args.rs +๏ป config/ +ย โโ ๎ config.rs +๏ป enums/ +ย โโ ๎ enums.rs +๏ป ext/ +ย โโ ๎ ext.rs +๏ป fmt/ +ย โโ ๎ fmt.rs +๏ป gfx/ +ย โโ ๎ gfx.rs +๏ป models/ +ย โโ ๎ models.rs +๏ป output/ +ย โโ ๎ output.rs +๏ป traits/ +ย โโ ๎ traits.rs +๏ป utils/ +ย โโ ๎ utils.rs +๎ exc.rs +๎ main.rs +๏ .pls.yml + +docs: +๏ป node_modules/ +๏ป public/ +๏ src/ + astro.config.mjs +๓ฐข .gitignore +๓ฐ justfile +๎ package.json +ย โโ ๎ pnpm-lock.yaml +๏ .pls.yml +๎ tsconfig.json
The solo files group consists of all files supplied individually. These files
+are collected into one group. Each of the files in this group comes with its own
+separate configuration derived from .pls.yml files.
The special thing here is that the group also has its own configuration +determined from the common ancestor of all these files. This group-level +configuration sets top-level options such as table headings, box-drawing +characters and importance scales.
+Consider the following filesystem tree:
+file_groupโโโ .pls.ymlโโโ aโโโ subdir โโโ .pls.yml โโโ bapp_const: table: header_style: red bold underlineentry_const: user_styles: curr: green bold other: green boldspecs: - pattern: ^a$ style: red underlineapp_const: table: header_style: blueentry_const: nlink_styles: file_sing: blue timestamp_formats: mtime: "<bold blue>[year]-[month]-[day]</>"specs: - pattern: ^a$ style: blue icon: filepls a ./../file_group/./subdir/a+ +โLink# T Permissions User Group Size Modified Name +ย 1 f rw- r-- r-- runner docker 0.0 B 2024-Oct-07 12:26pm a +ย 1 f rw- r-- r-- runner docker 0.0 B 2024-10-07 ./../file_group/./subdir/a
Note how both files retain their individual configurations for the row, but the
+table settings come from the outer .pls.yml file. Also note that the file
+names are shown exactly as they were passed on the command line.
By default, pls does not follow symlinks in the arguments provided to it. So
+a symlink to a directory will be treated as a file input and will not list the
+contents of the target directory.
pls sym+ +โ๓ฐน sym@ ๓ฐ ./dir
pls ./dir+โ๏ LICENSE +๏ญ README.md
At its core, the output of pls is a list of nodes. Each node in the list has
+a specific color, style and importance, all of which collectively determine how
+it is rendered and displayed.
pls uses specs to match each node to its visual properties, using a powerful
+regex matching system, which allows nodes to be matched by their name, extension
+or even fragments of both.
A spec consists of four components, of which only the first is mandatory.
+pattern:
+regex::bytes::Regex
This is a regex pattern that will be compared against the node name. If the +node matches this regex, this spec will be associated with the node.
+icon: String
This is the name, and not the actual glyph, of the icon to +use for nodes matching this spec. When specs cascade, the last defined icon +definition is used. If no specs match a node, the default icon for the node +type is used.
+style: String
This is a markup directive that must be applied to the nodes +that match this spec. When specs cascade, their directives are combined with +latter rules overriding previous ones if they conflict.
+importance: i8
This defines the importance level of the file and +overrides the default value (determined by the leading dot).
+collapse: Collapse
The goal of collapsing is to indicate that a node is a derivative of another +adjacent node. Collapsing can be performed in two ways.
+name
+In this case, a node with a specific name is collapsed into another with a
+specific name. For example, Cargo.lock collapses into Cargo.toml.
ext
+In this case, every node with a specific extension is collapsed into another
+node with the same stem but different extension. For example, index.js and
+lib.js collapse into index.ts and lib.ts respectively.
Specs are configured in the .pls.yml file.
Consider a typical JavaScript project. When listing it with pls the output
+is very plain. That's because pls ships with a very lean config out of the
+box.
pls+ +โ๏ src/ +๓ฐข .gitignore +๓ฐ justfile +๎ package.json +๎ pnpm-lock.yaml +ย prettier.config.js + .prettierignore +๏ญ README.md +๎ tsconfig.json
But we can make some things better here.
+package.json and pnpm-lock.yaml.pnpm-lock.yaml collapse into package.json.README.md and justfile as they are starting files.Let's add a spec file to it.
+icons: javascript: "๓ฐ" # nf-md-language_javascript typescript: "๓ฐฆ" # nf-md-language_typescriptspecs: - pattern: \.ts$ icon: typescript style: rgb(49,120,198) - pattern: \.js$ icon: javascript style: rgb(247,223,30) importance: -1 collapse: ext: ts - pattern: prettier icon: broom - pattern: ^package\.json$ icon: package - pattern: ^pnpm-lock\.yaml$ icon: lock importance: -1 collapse: name: package.json - pattern: ^(justfile|README.md)$ style: green bold importance: 2+ +โ๏ src/ +๓ฐข .gitignore +๓ฐ justfile +๎ package.json +ย โโ ๎ pnpm-lock.yaml +๏ .pls.yml + prettier.config.js + .prettierignore +๏ญ README.md +๎ tsconfig.json
pls src/+โ index.ts +ย โโ index.js + lib.ts +ย โโ lib.js + no_child.ts + no_parent.js
pls is a prettier and powerful ls(1) for the pros.pls --det all+ +โDevice inode Link# T Permissions SUGO User UID Group GID Size Blocks Created Changed Modified Accessed Git Name +ย 2065 520355 5 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ป docs/ +ย 2065 520539 4 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ป examples/ +ย 2065 520335 5 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ .github/ +ย 2065 520758 3 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ป pkg/ +ย 2065 520763 2 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ป readme_assets/ +ย 2065 520765 12 d rwx r-x r-x 755 runner 1001 docker 127 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ src/ +ย 2065 520352 1 f rw- r-- r-- 644 runner 1001 docker 127 1.9 KiB 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ Cargo.toml +ย 2065 520351 1 f rw- r-- r-- 644 runner 1001 docker 127 32.3 KiB 72 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm โโ ๏ Cargo.lock +ย 2065 520334 1 f rw- r-- r-- 644 runner 1001 docker 127 124.0 B 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm .editorconfig +ย 2065 520346 1 f rw- r-- r-- 644 runner 1001 docker 127 153.0 B 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐข .gitignore +ย 2065 520757 1 f rw- r-- r-- 644 runner 1001 docker 127 1.7 KiB 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๓ฐ justfile +ย 2065 520353 1 f rw- r-- r-- 644 runner 1001 docker 127 34.3 KiB 72 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ LICENSE +ย 2065 520347 1 f rw- r-- r-- 644 runner 1001 docker 127 642.0 B 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ .pls.yml +ย 2065 520348 1 f rw- r-- r-- 644 runner 1001 docker 127 2.1 KiB 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๎ .pre-commit-config.yaml +ย 2065 520762 1 f rw- r-- r-- 644 runner 1001 docker 127 43.0 B 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm prettier.config.mjs +ย 2065 520349 1 f rw- r-- r-- 644 runner 1001 docker 127 31.0 B 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm .prettierignore +ย 2065 520354 1 f rw- r-- r-- 644 runner 1001 docker 127 1.6 KiB 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๏ญ README.md +ย 2065 520350 1 f rw- r-- r-- 644 runner 1001 docker 127 28.0 B 8 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm 2024-Oct-07 12:26pm ๎ .rustfmt.toml
${i(30)}
+${i(40)}
+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).
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.
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.
iconsicons: python: "๎" # nf-seti-python javascript: "๓ฐ" # nf-md-language_javascript applescript: "๐" specs
seq<Spec> list of node specs, in ascending order of specificity
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
CollapseCollapse 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.
collapsecollapse: name: package.json # matches exactly `package.json`collapse: ext: ts # matches file with same base name and `.ts` extensionspecsspecs: - pattern: ^(pnpm-lock.yaml|package-lock.json)$ icon: lock importance: -1 collapse: name: package.json - pattern: \.(c|m)?js$ icon: javascript style: rgb(247,223,30) collapse: ext: ts entry_const
EntryConst constants that determine the appearance and styling of each entry
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
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
nlink_stylesnlink_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'.
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.
typtyp: dir: ch: <bold cyan>d</> suffix: <dimmed>/</> icon: dir style: blue symlink: ch: <magenta>l</> suffix: <dimmed>@</> icon: 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'.
perm_stylesExample:
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'.
oct_stylesoct_styles: special: magenta user: blue group: blue dimmed other: dimmed user_styles OwnerStyles styles for the owner user
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
user_stylesuser_styles: curr: blue bold other: dimmed group_styles OwnerStyles styles for the owner group
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
group_stylesgroup_styles: curr: blue other: dimmed size_styles SizeStyles style for magnitude and unit (prefix and base) of node size
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
size_stylessize_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.
timestamp_formatstimestamp_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'.
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.
symlinksymlink: ok: sep: ๓ฐ style: magenta broken: sep: ๓ฑฃ style: red ref_style: strikethroughentry_constentry_const: dev_style: magenta ino_style: magenta blocks_style: cyan app_const
AppConst constants that determine the appearance and styling of the entire UI
AppConst table TableInfo configuration for the table view
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'.
column_namescolumn_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
tabletable: header_style: clear underline tree TreeInfo shapes to use to print trees
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 "โโ "
treetree: pipe_space: "โ " space_space: " " tee_dash: "โ โ " bend_dash: "โโ " imp_styles seq<(int, string)> pairings of importance levels with styling directives
(int, str) 0 int the importance level
1 str the style to use for nodes of a particular importance level
imp_stylesimp_styles: - [-1, "dimmed"] - [1, "italic"] - [2, "underline"]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.