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> to specify 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
                             (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)                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>)
-b (--basename)            In Merge mode, show only the basename of each entry
--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 som 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 criterai 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, except if the "-b" option is provided (meaningfull only when merging).

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.

Links and broken links

Option -L leads als to select all the symbolic links.
Option -B leads leads to 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 dir has been shown, with 1 otherwise and with 2 on error.