Detail view

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.

Arguments

--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.

Caution

Note that the detail view is incompatible with the grid view. In case of conflict, the detail view will be used and the grid view will be turned off.

Mechanism

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 flag
• all can be used to show every available metadata field

For example, consider the pls invocation below.

pls --det=dev --det=ino --det=none --det=std --det=git

• dev is added to the list.
• ino is added to the list.
• All entries so far are dropped when none is encountered.
• nlink, typ, perm, user, group, size and mtime are added to the list when std is encountered
• git 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.

Examples

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-Apr-22 05:23am   dir/
    1 l rwx rwx rwx runner docker 10.0   B 2024-Apr-22 05:23am 󰌹  block_dev@ 󱞣 /dev/disk0
    1 l rwx rwx rwx runner docker  9.0   B 2024-Apr-22 05:23am 󰌹  char_dev@ 󰁔 /dev/null
    1 p rw- r-- r-- runner docker  0.0   B 2024-Apr-22 05:23am    fifo|
    1 f rw- r-- r-- runner docker  1.0 MiB 2024-Apr-22 05:23am    file
    1 s rwx r-x r-x runner docker  0.0   B 2024-Apr-22 05:23am    socket=
    1 l rwx rwx rwx runner docker  5.0   B 2024-Apr-22 05:23am 󰌹  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
  2049 555639     2 d rwx r-x r-x  755 runner 1001 docker 127                         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am       dir/
  2049 555644     1 l rwx rwx rwx  777 runner 1001 docker 127 10.0   B      0         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am     󰌹  block_dev@ 󱞣 /dev/disk0
  2049 555643     1 l rwx rwx rwx  777 runner 1001 docker 127  9.0   B      0         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am     󰌹  char_dev@ 󰁔 /dev/null
  2049 555641     1 p rw- r-- r--  644 runner 1001 docker 127  0.0   B      0         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am        fifo|
  2049 555645     1 f rw- r-- r--  644 runner 1001 docker 127  1.0 MiB      8         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am        file
  2049 555642     1 s rwx r-x r-x  755 runner 1001 docker 127  0.0   B      0         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am        socket=
  2049 555640     1 l rwx rwx rwx  777 runner 1001 docker 127  5.0   B      0         2024-Apr-22 05:23am 2024-Apr-22 05:23am 2024-Apr-22 05:23am     󰌹  sym@ 󰁔 ./dir

 

Configuration

Each of the detail fields is deeply customisable. Read on to know more the customisation options supported by each field.

Fields

dev - Device ID

This 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 number

This 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 links

This 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 character

pls 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 permissions

This 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 permissions

An 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/UID

pls 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/GID

pls 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 space

pls 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 blocks

pls 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".

Note

On macOS, the minimum block size is generally 4096 bytes so any file smaller than 4KiB will still take 8 blocks, and the number of blocks will also be a multiple of 8.

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 - Timestamps

pls 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.

Examples

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).

.pls.yml

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
  2049 555639     2 d rwx r-x r-x   755 runner 1001 docker 127                             22 Apr 05:23 22 Apr 05:23  22 Apr 05:23        dir/
  2049 555644     1 l rwx rwx rwx   777 runner 1001 docker 127 10.0         0              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23      󰌹  block_dev@ 󱞣 /dev/disk0
  2049 555643     1 l rwx rwx rwx   777 runner 1001 docker 127  9.0         0              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23      󰌹  char_dev@ 󰁔 /dev/null
  2049 555641     1 | rw- r-- r--   644 runner 1001 docker 127  0.0         0              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23         fifo|
  2049 555645     1 . rw- r-- r--   644 runner 1001 docker 127  1.0 Mi      8              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23         file
  2049 555651     1 . rw- r-- r--   644 runner 1001 docker 127  1.6 Ki      8              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23       .pls.yml
  2049 555642     1 s rwx r-x r-x   755 runner 1001 docker 127  0.0         0              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23         socket=
  2049 555640     1 l rwx rwx rwx   777 runner 1001 docker 127  5.0         0              22 Apr 05:23 22 Apr 05:23  22 Apr 05:23      󰌹  sym@ 󰁔 ./dir