path: root/lr.1

.Dd July 27, 2017
.Dt LR 1
.Os
.Sh NAME
.Nm lr
.Nd list files, recursively
.Sh SYNOPSIS
.Nm
.Op Fl 0 | Fl F | Fl l Oo Fl TA | Fl TC | Fl TM Oc | Fl S | Fl f Ar fmt
.br
.Op Fl D
.Op Fl H | Fl L
.Op Fl 1AGQXdhsx
.Op Fl U | Fl o Ar ord
.br
.Op Fl e Ar regex
.Op Fl t Ar test
.Op Fl C Oo Ar color Ns Li \&: Oc Ns Ar path
.Ar path\ ...
.Sh DESCRIPTION
.Nm
is a versatile tool to generate file listings with configurable
formatting, ordering and filtering.
.Pp
When no
.Ar path
is given or
.Ar path
is an empty string, the current directory is used by default.
.Pp
The special
.Ar path
argument
.Sq Ic \&\-
makes
.Nm
read file names from standard input,
instead of traversing
.Ar path .
Likewise, the special
.Ar path
argument
.Ic \&@ Ns Ar file
makes
.Nm
read file names from
.Ar file .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 0
Output filenames separated by NUL bytes.
Likewise, read input filenames separated by NUL bytes.
.It Fl F
Output filenames and an indicator of their file type (one of
.Sq Li */=>@| ) .
.It Fl l
Long output a la
.Sq Ic ls -l
(implies
.Fl Q ) .
.It Fl TA
With
.Fl l ,
print atime.
.It Fl TC
With
.Fl l ,
print ctime.
.It Fl TM
With
.Fl l ,
print mtime.
This is the default.
.It Fl S
Output inspired by
BSD
.Xr stat 1
(implies
.Fl Q ) .
.It Fl f Ar fmt
Custom formatting, see
.Sx FORMATTING .
.It Fl D
Use depth first traversal.
.Ic prune
will not work, but
.Ic entries
and
.Ic total
are computed on the fly.
.It Fl H
Only follow symlinks on command line (default: don't follow symlinks).
.It Fl L
Follow all symlinks.
.It Fl 1
Don't go below one level of directories.
.It Fl A
Don't list files starting with a dot.
.It Fl Q
Quote file names (default for output to TTY).
.It Fl d
Don't enter directories.
.It Fl G
Colorize output to TTY.
Use twice to force colorized output.
.It Fl X
Output OSC 8 hyperlinks to TTY.
Use twice to force hyperlinks.
.It Fl h
Print human readable size for
.Fl l
(also
.Ic %s ) .
.It Fl s
Strip directory prefix passed on command line.
.It Fl x
Don't enter other filesystems.
.It Fl U
Don't sort results.
.It Fl o Ar ord
Sort according to
.Ar ord ,
see
.Sx SORT ORDER .
.It Fl e Ar regex
Only show files where basename matches the POSIX ERE
.Ar regex .
.It Fl t Ar test
Only show files matching the expression
.Ar test ,
see
.Sx TESTS .
Multiple occurrences of
.Fl t
and
.Fl e
are regarded as a conjunction.
.It Fl C Oo Ar color Ns Li \&: Oc Ns Ar path
Behaves as if
.Ar path
was passed like an ordinary argument,
but overrides the color of the file names to the number
.Ar color
which must be between 0 and 255 (default: 2, green).
.Pp
Implies
.Fl GG .
.El
.Sh FORMATTING
.Nm
format strings support the following escape sequences:
.Pp
.Bl -tag -compact -width Ds
.It Ic \ea , \eb , \ef , \en , \er , \ev , \e0
Special characters as in C.
.It Ic \&%%
A plain
.Sq % .
.It Ic \&%s
File size in bytes
.It Ic \&%S
File size, with human readable unit
.It Ic \&%b
File size in 512-byte blocks
.It Ic \&%k
File size in 1024-byte blocks
.It Ic \&%d
Path depth
.It Ic \&%D
Device number
.Va ( stat.st_dev )
.It Ic \&%R
Device ID for special files
.Va ( stat.st_rdev )
.It Ic \&%i
Inode number
.It Ic \&%I
One space character for every depth level
.It Ic \&%p
Full path
.Ic ( \&%P
if
.Fl s
is used)
.It Ic \&%P
Full path without command line argument prefix
.It Ic \&%l
Symlink target
.It Ic \&%n
Number of hardlinks
.It Ic \&%F
File indicator type symbol (one of
.Sq Li */=>@| )
.It Ic \&%f
File basename (everything after last
.Li / )
.It Ic \&%A- , %C- , %T-
relative age for atime/ctime/mtime.
.It Ic \&%A Ns Ar x , Ic \&%C Ns Ar x , Ic \&%T Ns Ar x
result of
.Xr strftime 3
for
.Ic \&% Ns Ar x
on atime/ctime/mtime
.It Ic \&%m
Octal file permissions
.It Ic \&%M
ls-style symbolic file permissions
.It Ic \&%y
ls-style symbolic file type
.Sq ( Li bcdfls )
.It Ic \&%g
Group name
.It Ic \&%G
Numeric gid
.It Ic \&%u
User name
.It Ic \&%U
Numeric uid
.It Ic \&%e
Number of entries in directories
.It Ic \&%t
Total size used by accepted files in directories (only with
.Fl D )
.It Ic \&%Y
Type of the filesystem the file resides on
.It Ic \&%x
Linux-only:
Print a combination of
.Sq Li \&#
for files with security capabilities,
.Sq Li \&+
for files with an ACL,
.Sq Li \&@
for files with other extended attributes.
.El
.Sh SORT ORDER
Sort order is string consisting of the following letters.
Uppercase letters reverse sorting.
Default sort order is
.Sq Ic n .
.Pp
.Bl -tag -compact -width Ds
.It Ic a
atime
.It Ic c
ctime
.It Ic d
path depth
.It Ic e
file extension
.It Ic i
inode number
.It Ic m
mtime
.It Ic n
file name
.It Ic p
directory name
.It Ic s
file size
.It Ic t
file type.
This sorts all directories before other files.
.It Ic v
File name as version numbers (sorts
.Sq 2
before
.Sq 10 ) .
.El
.Pp
E.g.\&
.Sq Ic Sn
sorts first by size, smallest last, and then by name
(in case sizes are equal).
.Sh TESTS
.Nm
tests are given by the following EBNF:
.Bd -literal
<expr>     ::= <expr> || <expr>  -- disjunction
             | <expr> && <expr>  -- conjunction
             | ! <expr>          -- negation
             | ( <expr )
             | <timeprop> <numop> <dur>
             | <numprop> <numop> <num>
             | <strprop> <strop> <str>
             | <typetest>
             | <modetest>
             | prune             -- do not traverse into subdirectories
             | print             -- always true value
             | color <num>       -- always true value, override 256-color

<timeprop> ::= atime | ctime | mtime

<numprop>  ::= depth | dev | entries | gid | inode
             | links | mode | rdev | size | total | uid

<numop>    ::= <= | < | >= | > | == | = | !=

<dur>      ::= "./path"          -- mtime of relative path
             | "/path"           -- mtime of absolute path
             | "YYYY-MM-DD HH:MM:SS"
             | "YYYY-MM-DD"      -- at midnight
             | "HH:MM:SS"        -- today
             | "HH:MM"           -- today
             | "-[0-9]+d"        -- n days ago at midnight
             | "-[0-9]+h"        -- n hours before now
             | "-[0-9]+m"        -- n minutes before now
             | "-[0-9]+s"        -- n seconds before now
             | [0-9]+            -- absolute epoch time

<num>      ::= [0-9]+ ( c        -- *1
                      | b        -- *512
                      | k        -- *1024
                      | M        -- *1024*1024
                      | G        -- *1024*1024*1024
                      | T )?     -- *1024*1024*1024*1024

<strprop>  ::= fstype | group | name | path | target | user | xattr

<strop>    ::= == | = | !=       -- string (in)equality
             | ===    | !===     -- case insensitive string (in)equality
             | ~~     | !~~      -- glob (fnmatch)
             | ~~~    | !~~~     -- case insensitive glob (fnmatch)
             | =~     | !=~ | !~ -- POSIX Extended Regular Expressions
             | =~~    | !=~~     -- case insensitive POSIX Extended Regular Expressions

<str>      ::= " ([^"] | "")+ "  -- use "" for a single " inside "
             | $[A-Za-z0-9_]+    -- environment variable

<typetest> ::= type ( == | = | != ) ( b | c | d | p | f | l )

<modetest> ::= mode ( == | =     -- exact permissions
                    | &          -- check if all bits of <octal> set
                    | |          -- check if any bit of <octal> set
                    ) <octal>
             | mode = "<chmod>"  -- check if symbolic mode is satisfied

<octal> ::= [0-7]+

<chmod> ::= <clause> (, <clause>)+

<clause> ::= [guoa]* [+-=] [rwxXstugo]*  -- see chmod(1)
.Ed
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr du 1 ,
.Xr find 1 ,
.Xr ls 1 ,
.Xr stat 1
.Sh AUTHORS
.An Leah Neukirchen Aq Mt leah@vuxu.org
.Sh LICENSE
.Nm
is licensed under the terms of the MIT license.