Als lists files, directory contents… It supports several powerful options for the selection of entries, for the output format of each entry, and general formatting options.

1. General syntax

Usage: als [ { <option> } ] [ { <file_or_dir_name> } ]
or   : als -h | --help | -v | --version

List file or directory contents.

Note
 The arguments <file_or_dir_name> must denote existing files or directories.
Wildcards are not supported for these arguments, but often the shell expands the wildcards before providing the arguments to the program. This is why, for example, "als *.xml" may work while "als '*.xml'" will fail. On this respect als behaves like ls.
Prefer the option <match_name> for specifying target names with wildcards. For example, "als -m '*.xml' subdir" will list the files with suffix xml in the subdirectory subdir.

2. Detailed options

2.1. Specify which entry to select

-a (--all)                 Show all entries including hidden ones (i.e. starting with '.')
-A (--All)                 Show all entries except "." and ".."
-D (--directories)         Show only directories
-L (--links)               Show only symbolic links
-F (--files)               Show only regular files
-O (--others)              Show only other entries (character or block device, pipe, socket)
-B (--broken-links)        Show only broken symbolic links
-R (--recursive)           Scan directories recursively
--depth=<positive>         Scan only to given depth (needs "-R")
--skip-dirs                Skip directories from arguments (useful when calling "als *")
--access=<rights>          Show only file with the given access for current user
                             ex: "rw*" read and write, exec or not
                                 "r-x" read, not write, exec
--follow-links             Follow symbolic links that finally denote a directory
<match_name> ::= -m <criteria> | --match=<criteria>
  <criteria> ::= <templates> | @<regex>
  <templates> ::= <template> [ { ,<template> } ]
                           Keep only files that match the criteria
                            (name matches one template or the regular expression)
<exclude_name> ::= -e <criteria> | --exclude=<criteria>
                           Exclude files that match the criteria
<match_dir> ::= --match-dir=<criteria>
                           Scan only directories that match the criteria
<exclude_dir> ::= --exclude-dir=<criteria>
                           Don't show directories that match the criteria
<discard_dir> ::= --discard-dir=<criteria>
                           Discard directories that match the criteria
<date_spec> [ <date_spec> ]
  <date_spec> ::= -d <date_comp><date> | --date=<date_comp><date>
  <date_comp> ::= eq | lt | le | gt | ge
  <date>      ::= yyyy-mm-ddThh:mm:ss | yyyy-mm-dd | Thh:mm:ss
                | <positive_duration>
  <duration>  ::= Y | M | D | h | m | s
                           Keep files that match the date specification
                            (before, after or equal to a given date or delay)
  -n <date> (--newer=<date>) is a shortcut to "-d ge<date>"

2.2. Specify how to show each entry selected

-l (--list)                Show rights, owner, size, modification date, symbolic link target
-1 (--1row)                One name per line
-c (--classify)            Append '/' to dirs, '@' to symbolic links
-H (--human)               Show sizes in friendly format (e.g. 1K, 2G)
-p | --path                Always show path of entries (default: when needed)
-b | --basename            Always show only name of entries
-P | --full-path           Always show full path of entries
<separator> ::= -S <string> | --separator=<string>
                           Insert <string> between each entry
--date-iso                 Show date in strict ISO format (<date>T<time>)
--show-targets             Show final target of symbolic links and consider its size

2.3. Specify general formatting options

-s (--size)                Sort by decreasing size (see also "-r")
-t (--time)                Sort by decreasing time (see also "-r")
--len-alpha                Sort by increasing name length (see also "-r")
-r (--reverse)             Sort (by name, size, time, or len) in reverse order
-N (--no-sort)             Keep order same as in the directory structure
-M (--merge)               Show a global list of entries (not dir names)
--dir-name=always|never    Show names of directories (default=when not empty)
--nodir                    Do not show names of directories (--dir-name=never)
-T (--total)               Also show number and total size of listed entries
-U (--utc)                 Use UTC i.o. local time for date spec and output
-q (--quiet)               Do not show entries

2.4. Other options

-h (--help)                Show online help
-v (--version)             Show current version of Als

2.5. Environment Variables

The variable ALS_MAX_TO_SORT can be set to define the number of entries above which als does not apply the default sorting policy (alphanum) or the sorting options. Set it to 0 for always sorting (1 leads to never sort).
The default is 5000.

2.6. Notes on compatibility between options

Some options are ignored when alone

Some options are meaningful only when some other option is provided. They are accepted and silently ignored when provided alone.

Example:

Option -H is useful only when -l is provided. So "als -H" is the same as "als".

Some options are ignored when combined with some other options

Some options are meaningless when some other option is provided. They are accepted and silently ignored in thses cases.

Example:

Many formating options ares meaningless when option -q is provided. So "als -qlr" is the same as "als -q".

Some options are mutually exclusive

Providing these options together is reported as an error.

Examples:

  • Sorting criteria are mutually exclusive.

  • -d and -n are mutually exclusive.

  • -S is not compatible with some other formatting options (-l, -1 and -c).

Some options are combined according to a specific logic

  • Matching applies to the target of the link (if --follow-links).

  • Several matching criteria are usually combined with operator and, except that:

    • several kinds are combined with or,

    • several name matching patterns or regex are combined with or.

Merge mode leads to specific outpout

This mode shows all (and only) the matching entries, one per row. For example, when combined with the recursive mode, it does not show the directory names as specific entries.
By default it shows the full relative path of each entry when needed (implicit -p), except if the "-b" or -P option is provided.

2.7. Criteria

The criteria (provided for <match_name>, <exclude_name>, <match_dir>, <exclude_dir> and <discard_dir>) follows the following syntax:

  • '@<text>' considers <text> as a regular expression (possibly empty),

  • '\@<text>' considers @<text> as a series of file templates, the first template starting by "@",

  • '\\@<text>' considers \@<text> as a series of file templates, the first template starting by "\@",
    …

  • other '<text>' is considered as templates (possibly empty), <template>,<template>….

Also beware that template matching function considers the character '\' as an escape character, so "\x" in the template matches the character 'x' in the file, whatever 'x', including the character '\'.

Examples:

"toto"    will match "@t.t."        (regex "t.t.")
"@toto"   will match "\@toto"       (patern "@toto",     checks "@toto")
"@toto"   will match "\\@toto"      (patern "\@toto",    checks "@toto")
"\@toto"  will match "\\\@toto"     (patern "\\@toto",   checks "\@toto")
"\@toto"  will match "\\\\@toto"    (patern "\\\@toto",  checks "\@toto"))
"\\@toto" will match "\\\\\@toto"   (patern "\\\\@toto", checks "\\@toto"))
"\toto"   will match "\\toto"       (pattern "\\toto",   checks "\toto"))
"\toto"   will match "\\\toto"      (pattern "\\\toto",  checks "\toto"))
"\\toto"  will match "\\\\toto"     (pattern "\\\\toto", checks "\\toto"))

2.8. Name matching

The general rule is that, if at least one matching criteria is provided, then the name (wthout path) must match at least one of them. No criteria means "all names match".
Conversely, if at least one exclusion criteria is provided, then the name must not match any of them. No criteria means "all names match" as well.

The matching of directory name in recursive mode is handled a specific way. If the current directory name matches a discard-dir criteria, then its content and subdirectories are skipped, otherwise:

  • If the current directory name matches a exclude-dir criteria (if there are some), or if it does not match any match-dir criteria (if there are some), then the content of the directory is skipped but its subdirectories are scanned.

  • If the name matches a match-dir criteria (or if there is none) and does not match any exclude-dir criteria (or if there is none), then the content of the directory is listed and the subdirectories are scanned.

2.9. Access rights

The general syntax for specifying the access rights is:

--access=rwx

where any of the three letters 'r', 'w' and 'x' can be replaced by '-' or '*'.

  • r means that the entry must be readable

  • w means that the entry must be writable

  • x means that the entry must be executable

  • - instead of a letter means that the entry must not have the corresponding access right

  • * instead of a letter means that the entry can have or can not have the corresponding access right

So the default mode (no criteria) corresponds to: --access=***, the list of read-only items is specified with --access=r-- and the list of readable and executable items is specified with --access=r*x.

2.10. Date criteria

These criteria allow selecting the entries based on the modification time.

One date or duration

When one criteria is set, it defines a comparison operator and a date or a duration:

  • A full date and time at format yyyy-mm-ddThh:mm:ss (with the T letter) specifies the year, month .. minutes and seconds.

  • A partial date without time (yyyy-mm-dd) stands for 00:00:00

  • A partial date with only a time (hh:mm:ss) stands for the current day

  • A positive duration and a qualifier letter (Y, M, D, h, m or s) stands for "sometimes ago".

Newer and older

The newer criteria can be used as a shortcut for "date ge", and the older criteria can be used as a shortcut for "date lt".

Two dates or durations

Two creteria can be combined (one being be le or lt and the other being ge or gt) in order to select files within a given time slice.

Examples:

-n 2h -o 1D                  // Files modified between 2 and 1 hour ago
-n 2022/04/01 -o 2022/04/02  // Files modifed the 1st of April
-d gt2022-03-25T10:21:03     // Files modified after a given date and time
-d ge1h                      // Files modified during last hour

2.11. Symbolic links

Links and broken links

Option -L leads als to select all the symbolic links.
Option -B leads als to list only the broken links, i.e. the one for which the final target (possibly following recursive links) cannot be read.

Following links

When --follow-links option is set and in recursive mode, if the target of a symbolic link is a directory, then this directory is added to the scan.

Showing target of links

When --show-targets is set, then als shows (when -l) the final target and its size, instead of the initial target of the symbolic links.

Note
 The options --follow-links and --show-targets are not used for assessing if a link is valid or broken (in any case, the link is valid only if the final target exists and is readable).
Detailed list

With option -l, the target of valid links is preceeded by →, while the target of broken link is preceeded by ⇒. With option --show-targets the target that is shown is the one on which the reading error occured.

3. Als exit codes

Als exits with 0 if a file or a dir has been shown, with 1 otherwise, and with 2 on error.