dfm (Dylan's File Manager)

A powerful, simple and snappy terminal file manager with minimal resource usage.

<a href="https://asciinema.org/a/mjFhlSN0VsV1Xt59" target="_blank"><img src="https://asciinema.org/a/mjFhlSN0VsV1Xt59.svg" alt="img" height="213px" align="right"/></a>

Initial Announcement: https://dylan.gr/1772192922

• Tiny (CONFIG_SMALL: ~90KiB, CONFIG_TINY: ~40KiB, CONFIG_TINY+ -static: ~150KiB)
• Fast (should only be limited by IO)
• No dynamic memory allocation (~1.5MiB static)
• Does nothing unless a key is pressed
• No dependencies outside of POSIX/libc
• Manually implemented TUI <img src="https://dylan.gr/img/dfm1.png" alt="screenshot" height="213px" align="right"/>
• Manually implemented interactive line editor
• Efficient low-bandwidth partial rendering
• UTF8 support (minus grapheme clusters and other unruly things)
• Inline image viewing (sixel, kitty)
• Multiple view modes (name, size, permissions, mtime, ...)
• Multiple sort modes (name, extension, size, mtime, reverse, ...)
• Ranger-style bulk rename <img src="https://dylan.gr/img/dfm2.png" alt="screenshot" height="213px" align="right"/>
• Incremental as-you-type search
• Bookmarks
• Vim-like keybindings
• Customizable keybindings
• Command system
• Multi-entry marking
• Basic operations (open, copy, move, remove, link, etc)
• Watches filesystem for changes
• CD on exit
• And more...

Table of Contents

<!-- vim-markdown-toc GFM -->

• Dependencies
• Building
• Configuration
  • DPP (Dylan's Preprocessor)
  • Command-line
  • Environment
  • CD On Exit
• Usage
  • Statusline
  • View Modes
  • Sort Modes
  • Prompt
  • Images
  • Searching
  • Marking
  • Commands
  • Privilege Escalation
  • Bound Commands
• Design Considerations
• Conclusion

<!-- vim-markdown-toc -->

Dependencies

Required:

• POSIX cat, cp, date, mkdir, printf, rm, sh
• POSIX make
• POSIX libc
• C99 compiler

Optional:

• strip (for CONFIG_SMALL and CONFIG_TINY)
• clang (for CONFIG_TINY)
• chafa (for image view using sixel)
• kitty (for image view kitty)

Building

$ ./configure --prefix=/usr
$ make
$ make DESTDIR="" install

The configure script takes three forms of arguments.

1. Long-opts: --prefix=/usr, --help
2. Variables: CC=/bin/cc, CFLAGS="-O3", LDFLAGS=" "
3. C macro definitions: -DMACRO, -DMACRO=VALUE, -UMACRO

There are three different build configurations.

1. Default: -O2
2. CONFIG_SMALL: -Os + aggressive compiler flags
3. CONFIG_TINY: -Oz + CONFIG_SMALL + (you must set CC=clang)

• To produce a static binary, pass -static via CFLAGS.
• To enable LTO, pass -flto via CFLAGS.

Everything contained within ./configure, Makefile.in, config.h.in, config_cmd.h.in and config_key.h.in can be configured on the command-line via ./configure. See ./configure --help and also refer to these files for more information.

Bonus example:

./configure \
  --prefix=/usr \
  -DCONFIG_TINY=1 \
  CC=clang \
  CFLAGS="$CFLAGS -flto -static" \
  -DDFM_NO_COLOR \
  -DDFM_COL_NAV="VT_SGR(34,7)"

NOTE: If you are building for an environment without support for the XTerm alternate screen, add -DDFM_CLEAR_EDIT to your configure flags.

Configuration

dfm is configured at compile-time via its config files.

• ./configure: Build system, compilation and installation.
• config.h.in: Default settings, colors, etc.
• config_key.h.in: Keybindings.
• config_cmd.h.in: Commands.

Refer to these files for more information.

DPP (Dylan's Preprocessor)

The config*.in files are processed by dpp (see bin/dpp) so POSIX shell code can be used within them. Everything defined by ./configure is also accessible within these files as variables.

See https://github.com/dylanaraps/dpp for more information.

Command-line

usage: dfm [options] [path]

options:
-H | +H        toggle hidden files (-H off, +H on)
-p             picker mode (print selected path to stdout and exit)
-o <opener>    program to use when opening files (default: xdg-open)
-c <name>      position cursor over 'name' instead of first entry
-q <query>     start in search results ("*query" for substring)
-s <mode>      change default sort
  n  name
  N  name reverse
  e  extension
  s  size
  S  size reverse
  d  date
  D  date reverse
-v <mode>      change default view
  n  name only
  s  size
  p  permissions
  t  time
  a  all

--help         show this help
--version      show version

path:
directory to open (default: ".")

Environment

A few things can be set at runtime via environment variables. If unset in the environment, default values are derived from the config.h.in file.

- DFM_COPYER         (The clipboard tool to use when copying PWD or file
                      contents. The tool is fed the data via <stdin>)

- DFM_BOOKMARK_[0-9] (Directory bookmarks. set DFM_BOOKMARK_[0-9] and then
                      bind act_cd_bookmark_[0-9] to the keys of your choosing)

- DFM_OPENER         (Opener script to use when opening files. This could be
                      xdg-open or a custom script (see the script/ directory))

- DFM_TRASH          (Program to use when trashing files)

- DFM_TRASH_DIR      (Path to trash directory)

- DFM_IMG_MODE       (Image mode to use: 'chafa' (default), 'kitty')

- DFM_SU             (Privilege escalation tool to use: 'sudo' (default))

CD On Exit

There are two ways to exit dfm.

1) act_quit           (default 'q')
2) act_quit_print_pwd (default 'Q')

Exiting with 2) will make dfm output the absolute path to the directory it was in. This output can be passed to cd to change directory automatically on exit.

$ cd "$(dfm)"
$ var=$(dfm)
$ dfm > file

Usage

dfm is a single column file-manager with VIM like keybindings. Its basic usage is pretty straightforward and anything non-obvious can be divined by looking at the actions each key is bound to.

Statusline

The statusline is as follows:

1 1/1 [RnHE] [1+] ~0B /path/to/current/directory/<query>

 1          - Shows nest level of dfm. Only shown if > 0.
 1/1        - The entry number under the cursor and the total visible entries.

 [RnHE]     - Indicators.

              R - Shown when dfm is running as root.
              n - Current sort mode: [n]ame, [N]ame reverse, [s]ize,
                  [S]ize reverse, [d]ate modified, [D]ate modified reverse,
                  [e]xtension. If the current directory is too large, in place
                  of sort mode, [T] is shown.
              H - Shown when hidden files are enabled.
              E - Shown when a command fails. This indicates that the user must
                  check the alternate buffer (bound to 'z' by default) to see
                  the error messages left by the command failure.

 [1+]       - Number of marked files, hidden when 0.

 ~0B        - Approximate size of directory (shallow, excludes sub-directories).

 /path/to   - The current directory.
 /<query>   - The search query if the list was filtered.

View Modes

There are five view modes: Normal, Size, Permissions, Date Modified and All. The view mode can be cycled by pressing <Tab> by default.

All is the sum of the other view modes and gives an idea of what is shown:

-rwxr-xr-x    16m    4.0K .git/
-rwxr-xr-x     2h    4.0K bin/
-rwxr-xr-x     4d    4.0K script/
-rwxr-xr-x    32m    4.0K lib/
-rwxr-xr-x    16h    4.0K platform/
-rw-r--r--    16m      0B .config_macro.h
-rw-r--r--    16m     62B .gitignore
-rw-r--r--     4d    1.0K LICENSE.md
-rw-r--r--    16m    1.8K Makefile
-rw-r--r--     8h    1.8K Makefile.in
-rw-r--r--    32s    6.6K README.txt
-rw-r--r--    16m    4.0K config.h
-rw-r--r--    32m    4.0K config.h.in
-rw-r--r--    32m    6.5K config_cmd.h
-rw-r--r--    32m    6.5K config_cmd.h.in
-rw-r--r--    16m    6.5K config_key.h
-rw-r--r--    32m    6.5K config_key.h.in
-rwxr-xr-x    16m    3.5K configure*
-rwxr-xr-x    16m    130K dfm*
-rw-r--r--    32m     72K dfm.c

 2/20 [nH] ~268K /home/dylan/kiss/fork/dfm

Sort Modes

There are seven sort modes: name, name reverse, size, size reverse, date modified, date modified reverse, extension. The sort mode can be cycled by pressing '`' (backtick) by default.

The name sort performs a natural/human sort and puts directories before files.

Prompt

The area where searches and commands are inputted is a complete interactive line editor supporting all the usual actions (left/right scroll, insert, bracketed clipboard paste, backspace, delete, prev/next word, etc). The default keybindings match what is found in readline and POSIXy shells.

As of now there is no <Tab> complete or up/down arrow history cycling.

NOTE: The prompt is implemented as a gap buffer. There are two buffers, cursor left and cursor right with the cursor sitting inbetween both buffers. When it comes time to commit the input it is simply joined together. Make not of this detail as it is necessary to know it when creating your own bound commands.

Images

Images can be viewed inside of dfm by pressing i by default. This will display the image and wait for a keypress before returning to the directory listing. Two backends are supported: sixel (via chafa) and kitty.

The mode can be set in config.h.in or at runtime via an environment variable.

Searching

There are two search modes: startswith (default /) and substring (default ?). They each perform a case-sensitive and incremen