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

-?, --help	Display the help text.
-? colors	Display help text on color coding the file list.
-? colorsamples	Display samples of the supported color codes.
-? defaultcolors	Print the default DIRX_COLORS string.
-? icons	Display help text on file icons and Nerd Fonts.
-? pictures	Display help text on format pictures.
-? printallicons	Print a list of all icons.
-? regex	Display help text on regular expression syntax.
-V, --version	Display version information.

Display Options

-1	Display one column per line.
-2	Display two columns per line (more in wide consoles).
-4	Display four columns per line (more in wide consoles).
-a, --all	Display all files (include hidden and system files).
-b, --bare	Bare mode; only display names, no header/detail/etc.
-c, --color	Display with colors (see Colors for more info).
-g, --git	List each file's git status.
-gg, --git-repos	List status of git repo roots and each file's git status (or --git-repos-no-status to omit file status).
-G, --grid	Synonym for --wide.
-i, --icons[=WHEN]	Display file icons (use Icons for more info). WHEN can be always, auto, never (default).
-k, --color-scale[=FIELD]	Highlight levels of certain fields distinctly. FIELD can be all, age, size, none (default).
-l, --long	Long mode; display one file per line, plus attributes.
-n, --normal	Force normal list format even on FAT volumes.
-Q, --quash[=TYPES]	Quash types of output. Use -Q by itself as a synonym for -Q+v+h+s. TYPES can be: v Suppress the volume information. h Suppress the header. s Suppress the summary. - Prefix to suppress next type (the default). + Prefix to un-suppress next type.
-p, --paginate	Pause after each screen full of information.
-R	Synonym for --recurse.
-s, --recurse	Subdirectories; recursively display files in specified directory and all subdirectories.
-u, --usage	Display directory size usage data.
-v, --vertical	Sort columns vertically.
--horizontal	Sort columns horizontally (the default).
-w, --wide	Wide mode; show as many columns as fit.
-z, --fat	Force FAT list format even on non-FAT volumes.
--color-scale-mode=MODE	Mode for --color-scale (see Colors for more info). MODE can be fixed, gradient (default).
--hyperlinks	Display entries as hyperlinks.
--tree	Tree mode; recursively display files and directories in a tree layout.

Filtering and Sorting Options

-a[...]	Display files with the specified attributes. If attributes are combined, all attributes must match (-arhs only lists files with all three attributes set). The - prefix excludes files with that attribute (-arh-s lists files that are read-only and hidden and not system). The + prefix includes files that have any of the + attributes set (-ar+h+s lists files that are read-only and are hidden or system). r Read-only files h Hidden files s System files a Ready for archiving d Directories i Not content indexed files j Reparse points (mnemonic for junction) l Reparse points (mnemonic for link) e Encrypted files t Temporary files p Sparse files c Compressed files o Offline files + Prefix meaning any - Prefix meaning not
-A, --almost-all	Display all files, except hide . and .. directories.
-h	Hide . and .. directories.
-I, --ignore-glob=GLOB	Glob patterns of files to ignore; the syntax is the same as in .gitignore. The / is used as the directory separator. An optional ! prefix negates a pattern; any matching file excluded by a previous pattern will be included again. Multiple patterns may be specified separated by a ; or | character.
-L, --levels=DEPTH	Limit the depth of recursion with -s.
-o[...]	Sort the list by the specified options: n Name [and extension if e omitted] (alphabetic) e Extension (alphabetic) g Group directories first d Date/time (oldest first) s Size (smallest first) c Compression ratio a Simple ASCII order (sort 10 before 2) u Unsorted r Reverse order for all options - Prefix to reverse order
-X, --skip=TYPES	Skip types during -s. Use -X by itself as a synonym for -X+d+j+r. d Skip hidden directories (when used with -s) j Skip junctions (when used with -s) r Skip files with no alternate data streams - Prefix to skip next type (this is the default) + Prefix to un-skip next type
--git-ignore	Ignore files mentioned in .gitignore files.
--hide-dot-files	Hide file and directory names starting with . or _. Using -a overrides this and shows them anyway.
--reverse	Reverse the selected sort order.
--string-sort	Sort punctuation as symbols.
--word-sort	Sort punctuation as part of the word (default).

Field Options

-C, --ratio	List the compression ratio.
-q, --owner	List the owner of the file.
-r, --streams	List alternate data streams of the file.
-S, --size	List the file size even in multple column formats.
-S[acf], --size=acf	Which size field to display or use for sorting: a Allocation size. c Compressed size. f File size (default).
-t, --attributes	List the file attributes (use the flag twice to list all attributes, e.g. -tt).
-T, --time	List the file time even in multiple column formats.
-T[acw], --time=acw	Which time field to display or use for sorting: a Access time. c Creation time. w Write time (default).
-x, --short-names	Show 8.3 short file names.

Formatting Options

-,	Show the thousand separator in sizes (the default).
-f[...]	Use the specified format picture. You can greatly customize how the list is display (see Pictures for more info).
-F, --full-paths	Show full file paths in the file name column.
-j	Justify file names in FAT list format.
-J	Justify file names in non-FAT list formats.
--justify[=WHEN]	Justify file names, in which list formats. If WHEN is omitted, always is assumed. WHEN can be always, fat, normal, never (default).
-SS	Show long file sizes (implies -S). Note that some list formats limit the file size width.
-TT	Show long dates and times (implies -T). Note that some list formats limit the date and time width.
-W, --width=COLS	Override the screen width.
-Y	Abbreviate dates and times (implies -T).
-Z	Abbreviate file sizes as 1K, 15M, etc (implies -S).
--bare-relative	When listing subdirectories recursively, print paths relative to the specified patterns instead of expanding them to fully qualified paths (implies --bare).
--classify	Print \ by dir names and @ by symlink names.
--compact	Use compact time style (short for --time and --time-style=compact).
--escape-codes[=WHEN]	For colors and hyperlinks in modern terminals. WHEN can be always, auto (default), never.
--fit-columns	Fit more columns in -w mode by compacting column widths to fit their content (this is the default; use --no-fit-columns to disable it).
--lower	Show file names using lower case.
--mini-bytes	Show bytes in the mini size format when less than 1000.
--mini-header	Show a mini header of just the directory name above each directory listing (if more than one directory).
--more-colors=LIST	Add color rules in the same format as the DIRX_COLORS environment variable (see Colors for more info).
--nerd-fonts=VER	Select which Nerd Fonts version to use (see Colors for more info).
--nix	Selects default options that are similar to Unix and Linux systems. Hides files starting with ., skips recursing into hidden directories, sorts vertically, displays the file list in wide mode, selects compact time style, shows a mini directory header above file lists, quashes volume/header/summary output, disables filename justify, shows long file names, shows - as size for dirs, and suppresses thousands separators.
--pad-icons=SPACES	Number of spaces to print after an icon.
--relative	Use relative time style (short for --time and --time-style=relative).
--size-style=STYLE	Which size format to use for display by default when not overridden by other format options. STYLE can be mini, short, normal (default).
--time-style=STYLE	Which time format to use for display by default when not overridden by other format options. STYLE can be locale (default), mini, compact, short, normal, full, iso, long-iso, relative.
--truncate-char=HEX	Set the truncation character for file names that don't fit in the allotted space. Specify a Unicode character value in hexadecimal (e.g. 2192 is a right-pointing arrow →, 25b8 is a right-pointing triangle ▸). Or specify 002e to use .. (two periods).
--utf8	When output is redirected, produce UTF8 output instead of using the system codepage.

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.
Setting ln=target or ln=: colors symlinks by the type of the target of the symlink.
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:

Code	Description		Code	Description
1	bold (bright)		22	not bold and not faint
2	faint
3	italic		23	not italic
4	underline		24	not underline (or double underline)
7	reverse		27	not reverse
9	strikethrough		29	not strikethrough
21	double underline
53	overline (line above)		55	not overline

Text colors:

Code	Description		Code	Description
39	default text color
30	black		90	bright black (dark gray)
31	dark red		91	bright red
32	dark green		92	bright green
33	dark yellow		93	bright yellow
34	dark blue		94	bright blue
35	dark magenta		95	bright magenta
36	dark cyan		96	bright cyan
37	dark white (gray)		97	bright white

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

Extended colors:

Code	Description
38;2;n;n;n	Specify a 24-bit color where each n is from 0 to 255, and the order is red;green;blue.
38;5;n	Specify an 8-bit color where n is from 0 to 255. Refer to the wikipedia link above for details.

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:

Picture	Example
"F Sm"	Filename  3.2M
"Ds Sm Trh F18"	10/04/09  13:45  123K r_ SomeVeryLongFilen…

Format picture field types

F[#flx]	Filename field. By default this automatically chooses the field width and style based on the other options used. # A number indicating the width for the field. If a file name is wider, it is truncated. If a file name is narrower, it is padded with spaces to the right. f Use FAT name format. l Show the long file name. x Show the short file name.
S[msacf]	Size field. By default this automatically chooses the field width and style based on the other options used. m Use mini format (use 4 characters, always abbreviate). s Use short format (use 9 characters, abbreviate when necessary). a Show the file allocation size. c Show the compressed file size. f Show the file data size.
D[lmsxacw]	Date and time field. By default this automatically chooses the field width and style based on the other options used. l Use locale format (like CMD with extensions enabled). m Use mini format (11 characters with time for recent files or year for older files). i Use iso format (11 characters; excludes year). p Use compact format (12 characters with time for recent files or year for older files; includes month name). s Use short format (15 characters with 2 digit year). o Use long iso format (16 characters with 4 digit year). n Use normal format (17 characters with 4 digit year). x Use extended format (24 characters with 4 digit year, plus minutes and milliseconds). a Show the last access time. c Show the creation time. w Show the last write time.
C[?]	Compression ratio field. By default this shows the field even if the corresponding option was not specified. ? Show only if the corresponding option was specified.
O[?]	Owner field. By default this shows the field even if the corresponding option was not specified. ? Show only if the corresponding option was specified.
X[?]	Short name field. By default this shows the field even if the corresponding option was not specified. ? Show only if the corresponding option was specified.
T[...]	Attributes field. By default this shows the field even if the corresponding option was not specified, and shows all file attributes. Control which attributes are listed as follows: ? Show only if the corresponding option was specified. r Read-only	e Encrypted h Hidden	t Temporary s System	p Sparse a Ready for archiving	c Compressed d Directory	o Offline i Not content indexed j Reparse point (mnemonic for junction) l Reparse point (mnemonic for link)
G[?]	Git file status field. When in a git repo, this shows two letters corresponding to the git file status.
R[?]	Git repo field. When listing a directory that is a git repo, this shows the status and branch name.

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.

Operator	Description
^	Matches the null string at the beginning of a line.
$	Matches the null string at the end of a line.
.	Matches any character.
[set]	Matches any characters in the set. The - character selects a range of characters. The expression [a-z] matches any lowercase letter from a to z. To select the ] character, put it at the beginning of the set. To select the - character, put it at the end of the set. To select the ^ character, put it anywhere except immediately after the opening bracket (which selects the complement of the set; see below)
[^set]	any characters not in the set (matches the complement of the set). The syntax for a complement set is the same as the syntax for a normal set (above), except that it is preceded by a ^ character.
[:class:]	Matches any character in the class (alnum, alpha, blank, cntrl, digit, graph, lower, print, punct, space, upper, xdigit).
(abc)	Matches abc, and tags it as a sub-expression for retrieval.
abc|def	Matches abc or def.
x?	Matches 0 or 1 occurrences of the character x (or set, or tagged sub-expression).
x+	Matches 1 or more occurrences of the character x (or set, or tagged sub-expression). x+? uses non-greedy repetition.
x*	Matches 0 or more occurrences of the character x (or set, or tagged sub-expression). x*? uses non-greedy repitition.
!x	Matches anything but x.
\b	Matches the null string at a word boundary (\babc\b matches abc but not abcx or xabc or xabcx).
\B	Matches the null string not at a word boundary (\Babc matches xabc but not abc).
\x	Some x characters have special meaning (refer to the full documentation). For other characters, \x literally matches the character x. Some characters require \x to match them, including ^, $, ., [, (, ), |, !, ?, +, *, and \.

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 premake5.exe toolchain (where toolchain is one of Premake's actions - see premake5.exe --help).
3. Build scripts will be generated in .build\toolchain. 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