Awesome

DirX - the dir command, extended

Displays a list of file and subdirectories in a directory.

The demo image above was produced using the following:

set DIRX_COLORS=di=1;33:ro=32:ro ex=1;32:ex=1:co=35:hi=38;2;204;64;64:sy=38;2;204;64;64:*.zip=36:da=38;5;33:sc=33:bu=33;4
set DIRX_COLORS=%DIRX_COLORS%:sn=38;5;244:nt=38;2;239;65;54:ng=38;2;252;176;64:nm=38;2;240;230;50:nk=38;2;142;198;64:nb=38;2;1;148;68:sb=38;5;240

set DIRXCMD=--icons

doskey d=dirx.exe --compact -Qv -whjv -Z -a- -f "F19 S D T? G?" $*

d -k

Usage

DIRX [options] [drive:][path][filename]

DirX is designed so that most command line options from the CMD dir command work the same, to make DirX mostly a drop-in replacement for dir.

Arguments

  [drive:][path][filename]

Specifies drive, directory, and/or files to list. Use as many arguments as desired (or none, in which case the current directory is assumed).

Prefix the filename part with :: to use a regular expression.

Options

Display Options

Filtering and Sorting Options

Field Options

Formatting Options

Long options that can be used without an argument also accept a no- prefix to disable them. For example, the --fit-columns option is enabled by default, and using --no-fit-columns disables it.

Environment Variables

Set DIRXCMD to preset options to use by default. To override any on/off option, add a hyphen (-k- overrides -k). Or for long options insert no- (--no-attributes overrides --attributes). For interop compatibility with the CMD dir command, slash options may also be used, for example /w. Unlike the CMD dir command, use /w- instead of /-w to override the slash option.

Set DIRX_COLORS to specify colors to use in the file list display. Use -? colors or see Colors for more info on color coding rules.

Colors

Set the DIRX_COLORS environment variable to control how files and directories are colored. The format is:

  condition=color: condition=color: ...

Any number of pairs of conditions and colors can be given. Use colons to separate them and build a list of many coloring rules.

The list can start with the special keyword reset to clear all default color rules and any rules that may have been provided in the LS_COLORS environment variable.

Examples:

set DIRX_COLORS=sc=93:bu=93;4:cm=38;5;172

• Source code files in yellow.
• Build system files in yellow with underline.
• Compiled files in orange.

set DIRX_COLORS=ro=32:ex=1:ro ex=1;31:ln=target

• Read-only files in green.
• Executable files in bright white.
• Files that are both read-only and executable in bright green.
• Symlinks colored by the type of the target of the symlink.

CONDITION syntax

Each condition can specify two-letter types, or patterns to match. If more than one are specified then all of them must match, and rules with multiple types and/or patterns are evaluated in the order they are listed.

Negation:

• not negates the next type or pattern (not hi means not hidden).
• ! negates the next type or pattern (!hi means not hidden).

File attribute names:

• ar Archive attribute (ready for archiving).
• cT Compressed attribute.
• di Directory.
• en Encrypted attribute.
• fi File.
• hi Hidden.
• ln Symlink.
• NI Not content indexed attribute.
• of Offline attribute.
• or Orphaned symlink.
• ro Read-only attribute.
• SP Sparse file.
• sy System attribute.
• tT Temporary attribute.

Setting ro by itself applies only to files, not directories.<br/> Setting ln=target or ln=: colors symlinks by the type of the target of the symlink.<br/> Setting hi=50% colors hidden files and directories at 50% luminance of whatever color the file or directory would have had. Specify any percentage between 30% and 90%. This can only be used with the hi attribute name.

File groups:

• ex Executable files.
• do Document files.
• im Image files.
• vi Video files.
• mu Music files.
• lo Lossless music files.
• cR Compressed type files (like *.zip).
• tX Temporary type files (like *.tmp).
• cm Compiled files.
• bu Build files (like *.sln).
• sc Source code (like *.cpp).
• cr Cryptography files.

Special groups:

• co Compressed; includes both cR and cT.
• tm Temporary; includes both tX and tT.

Color element names:

These let you define colors of various elements of the output.

• sn File size (sets nb, nk, nm, ng and nt).
• nb File size if less than 1 KB.
• nk File size if between 1 KB and 1 MB.
• nm File size if between 1 MB and 1 GB.
• ng File size if between 1 GB and 1 TB.
• nt File size if 1 TB or greater.
• sb Units of a file’s size (sets ub, uk, um, ug and ut).
• ub Units of a file’s size if less than 1 KB.
• uk Units of a file’s size if between 1 KB and 1 MB.
• um Units of a file’s size if between 1 MB and 1 GB.
• ug Units of a file’s size if between 1 GB and 1 TB.
• ut Units of a file’s size if 1 TB or greater.
• da File date and time.
• cF File compression ratio.
• oF File owner.
• ga New file in git.
• gm Modified file in git.
• gd Deleted file in git.
• gv Renamed file in git.
• gt Type change in git.
• gi Ignored file in git.
• gc Unmerged file in git (conflicted).
• Gm Git repo main branch name.
• Go Git repo other branch name.
• Gc Git repo is clean.
• Gd Git repo is dirty.
• GO Overlay style for dirty git repo.
• xx Punctuation (for example _ in the attributes field).
• hM The directory name with --mini-header.
• ur The read-only attribute letter in the attributes field.
• su The hidden attribute letter in the attributes field.
• sf The system attribute letter in the attributes field.
• pi The junction attribute letter in the attributes field.
• lp The symlink path when showing symlink targets.
• bO Overlay style for broken symlink paths when showing symlink targets.

The color element names above cannot be combined with types or patterns; they're for setting general colors, and don't affect how file names are colored.

Anything else:

Anything else in a condition is interpreted as a pattern to match against the file name. The patterns use the fnmatch glob syntax, which is also used by .gitignore.

The most common use is to match a file extension, for example *.txt matches files whose name ends with .txt.

Patterns can include ? and * wildcards, and can also include character sets enclosed in []. For example ab[xyz] matches abx, aby, and abz. A set can include ranges, for example [a-z] matches any lowercase letter. If the first character in the set is ! or ^ the set excludes the listed characters, for example [!0-9] matches anything except digits. The ? character in a set matches any character but only if there's a character to match, for example ab[?] matches abc, but not ab. Character sets can use [:class:] to specify a class of characters; class can be one of alnum, alpha, blank, cntrl, digit, graph, lower, print, punct, space, xdigit, upper.

Anything quoted is treated as a pattern, for example ro refers to a file named ro instead of read-only files.

A pattern by itself with no types applies only to files, not directories. To specify a pattern that matches anything, combine di and the pattern.

COLOR syntax

Colors are the SGR parameter from ANSI color escape codes.

The following color parameters are allowed. Note that the color parameters are just sent to the terminal, and it is the terminal's responsibility to draw them properly. Some parameters might not work in all terminal programs.

Run dirx -? colorsamples to display a chart of the 8-bit color codes and the available styles.

Styles:

Text colors:

To make a background color, add 10 to the text color values above.

Extended colors:

To make a background color, add 10 to the extended color values above.

Environment Variables

Set NO_COLOR to any non-empty value to completely disable colors. See https://no-color.org/ for more info.

Set DIRX_COLOR_SCALE to any value accepted by the --color-scale flag to control the default behavior. If it's not set, then %EZA_COLOR_SCALE% and %EXA_COLOR_SCALE% are also checked.

Set DIRX_COLOR_SCALE_MODE to any value accepted by the --color-scale-mode flag to control the default behavior. If it's not set, then %EZA_COLOR_SCALE_MODE% and %EXA_COLOR_SCALE_MODE% are also checked.

Set DIRX_MIN_LUMINANCE to a value from -100 to 100 to control the range of intensity decay in the gradient color scale mode. If it's not set, then %EZA_MIN_LUMINANCE% and %EXA_MIN_LUMINANCE% are also checked.

If the DIRX_COLORS environment variable is not set, then LS_COLORS is also checked. DirX enhancements are ignored when parsing %LS_COLORS%.

Icons

To see icons, a Nerd Font is required; visit https://nerdfonts.com for more info and to choose from many available fonts.

By default, a Nerd Fonts v3 font is assumed.

A few quick examples:

Icons are selected based on the name of the file or folder, or the extension of the file name. The icon mappings are hard-coded and aren't configurable at this time.

Environment Variables

Set DIRX_NERD_FONTS_VERSION=2 to select icons compatible with v2 Nerd Fonts.

Set DIRX_ICON_SPACING=n to specify the number of spaces to print after an icon. n can be from 1 to 4. The default is 1, but some terminals or fonts may need a different number of spaces for icons to look good. If it's not set, then %EZA_ICON_SPACING% and %EXA_ICON_SPACING% are checked as well.

Format Pictures

Use the -f option to specify a custom format picture to list files. Format picture field types and styles are case sensitive: field types are uppercase and field styles are lowercase.

Examples:

Format picture field types

Other characters in the format picture are output as-is. To ensure a character is output as-is rather than being treated as a field type (etc), use \ to escape the character (e.g. "\F:F" shows F:MyFile.doc).

For some field types ? suppresses the field if the corresponding option was not specified. When a field is suppressed, normally the field and the spaces immediately preceding it are omitted from the resulting format picture. For finer control over what part of the format picture is omitted, surround the text to be omitted using the [ and ] characters. Everything between the brackets will be shown or omitted as a unit, and the brackets themselves are not shown (e.g. "F [(C?) ]Sm" shows File (12%) 1.2M or File 1.2M).

The -F option fits the full path name into the filename field, if the field is at the end of the format picture.

The -w option fits as many files as possible onto each line, using the custom format picture. The -2 option is incompatible with format pictures (because it selects a specific format picture that's 38 characters wide).

The -r option forces a single column list, but fits the stream name into the filename field(s). If the filename field is at the end of the format picture then the entire stream names are shown; otherwise the stream names are truncated to the width of the longest file name.

Regular Expressions

Regular expressions specify a substring to find. In addition, several special operators perform advanced searches.

To use a regular expression as a filename pattern, use :: followed by the regular expression. When specifying both a path and a regular expression, the :: must precede the regular expression, for example folder\\::regex. If the regular expression contains spaces or characters with special meaning to the shell (such as |, <, >) then enclose the expression in double quotes.

Note that regular expressions are not natively supported by the OS, so all filenames must be retrieved and compared with the regular expression. This can make using regular expressions much slower than using ? and * wildcards.

The regular expression is the ECMAScript syntax.

Here is a quick summary; for details about the full syntax available, refer to the documentation link above.

Building DirX

DirX uses Premake to generate Visual Studio solutions. Note that Premake >= 5.0.0-beta1 is required.

1. Cd to your clone of dirx.
2. Run <code>premake5.exe <em>toolchain</em></code> (where <em>toolchain</em> is one of Premake's actions - see premake5.exe --help).
3. Build scripts will be generated in <code>.build\<em>toolchain</em></code>. For example .build\vs2022\dirx.sln.
4. Call your toolchain of choice (Visual Studio, msbuild.exe, etc).

License

Copyright (c) 2024 by Christopher Antos License: http://opensource.org/licenses/MIT