fex

A command-line file explorer.

---

fex is a command-line file explorer inspired by Vim, exa and fzf, built with quick exploration and navigation in mind.

By using Vim-like keybindings, fex ends up being a near-effortless tool to zip around a file system:

• j, k to move to the previous and next item
• h, l to move up or drop down a directory
• / to search for items
• : to run commands on the selected item

Show Fex Demo

Fex.Demo.webm

Index

• Installation
  • Using install.sh
  • From Source
    • macOS
    • Linux
• Setup
  • Zsh Setup
  • fex Default Command
• Config
  • Display Config
  • Search Config
  • Other Args
• Controls
  • Navigation Controls
  • Action Controls
  • File System Controls
  • Search Mode Controls
  • Command Mode Controls
  • Display Toggle Controls
  • Sort Controls
• Platform Support

Installation

The most convenient way is by running the following bash one-liner:

curl -O https://raw.githubusercontent.com/18alantom/fex/master/install.sh && bash install.sh

Getting fex running involves:

1. Installing the fex executable.
2. Setting up the shell integration.

To get install the fex executable follow this section. For the shell integration go to the Setup section.

Note

🚧 Installation using package managers (Homebrew, apt, etc) will be added.

Using install.sh

You can use the install.sh script to download and setup the latest version of fex.

Run the following bash one-liner to setup fex:

curl -O https://raw.githubusercontent.com/18alantom/fex/master/install.sh && bash install.sh

Tip

The same bash one-liner can be used to update your fex install.

Note

To uninstall fex:

1. Remove the $HOME/.fex directory.
2. Delete the lines pertaining to fex from your .bashrc or .zshrc file.

From Source

To install fex from source, you will need version zig version 0.13.0 installed. You can get it from here.

Once you had done that, compile the executable by using the following commands:

# Clone the fex repository
git clone https://github.com/18alantom/fex && cd fex

macOS

# Compile the fex executable for your system
zig build-exe -O ReleaseSafe main.zig

# Move the executable to usr bin
mv main /usr/local/bin/fex

Linux

# To be able to open files, you will need xdg-open from xdg-utils
sudo apt install xdg-utils

# Compile the fex executable for your system
zig build-exe -O ReleaseSafe main.zig -lc

# Move the executable to usr bin
mv main /usr/bin/fex

Setup

To use fex to its full extent it needs to be set up as a shell widget. This allows fex to:

• Be invoked using a key binding.
• Execute shell commands. For example cd to quit and change directory.

These are shell specific so you will need to set it up separately depending on the shell you use.

Note

🚧 bash shell support will be added.

Zsh Setup

To setup the Zsh widget for fex, first copy the file shell/.fex.zsh to your home directory. Then copy the following lines into your .zshrc:

# Source .fex.zsh if it's present
[ -f ~/.fex.zsh ] && source ~/.fex.zsh

# Bind CTRL-F to invoke fex (key binds can be custom)
bindkey '^f' fex-widget

Tip

You can change which shortcut is used to invoke fex by using the Zsh bindkey command. For example if you use Zsh vi mode, you can use bindkey -a 'f' fex-widget to invoke fex using the 'f' key when in command mode.

Reference:

• ZLE manpage (man zshzle), the ZLE BUILTINS section.
• Binding Keys and handling keymaps

Fish Setup

To setup the fex key bind for Fish, copy shell/.fex.fish into to home directory. Then copy the following lines below into your $HOME/.config/fish/config.fish.

# Source .fex.fish if it's present
[ -f ~/.fex.fish ] && source ~/.fex.fish

# Bind CTRL-F to invoke fex (key binds can be custom)
bind \cf fex-widget

Once you're done, restart your shell to see it working!

Tip

You can change which shortcut is used to invoke fex by using the Fish bind command.

Reference: bind - handle fish key bindings

fex Default Command

After you have set up fex for your shell, you can FEX_DEFAULT_COMMAND to change what flags fex is invoked using. For example:

# Sets time displayed to access time and hides icons
export FEX_DEFAULT_COMMAND="fex --time-type accessed --no-icons"

Config

You can configure fex by passing it args.

Note

Config is picked up from the FEX_DEFAULT_COMMAND envvar and CLI args passed when calling fex. CLI args take precedence.

Display Config

Changes values displayed in an item line.

arg	description
--[no-]dotfiles	Show or hide dotfiles (hidden by default).
--[no-]icons	Show or hide icons. Note: icons need a patched font to work.
--[no-]size	Show or hide item sizes
--[no-]time	Show or hide time
--[no-]perm	Show or hide permission info
--[no-]link	Show or hide link target
--[no-]user	Show or hide user name
--[no-]group	Show or hide group name
--time-type VALUE	Set which time is displayed. VALUE: modified, accessed, changed. Default: modified
--[no-]fullscreen	Enable or disable full screen mode. Previous screen is restored on quit.

Search Config

This changes search behavior.

arg	description
--regular-search	Uses regular search, instead of fuzzy search
--match-case	Match search query case, instead of ignoring

Tip

fex uses smart case matching by default i.e case is ignored until you enter an upper case character.

Other Args

arg	description
--help	Prints the help message and quits.
--version	Prints the version and quits.

Controls

fex has three modes:

• Default: used to navigate around a file system and enter one of the other modes.
• Search: toggled with /, used to accept a query and find matching items in expanded directories.
• Command: toggled with :, used to accept a shell command that is executed on enter. fex needs to be setup as a shell widget for this to work, see Setup.

Important

Keys mentioned in angle-brackets such as <enter> show which key has to be pressed. Keys mentioned without such as cd are sequences that have to be typed.

Navigation Controls

key	action
j, <down-arrow>	Cursor down
k, <up-arrow>	Cursor up
h, <left-arrow>	Up a dir
l, <right-arrow>	Down a dir (if item is a dir)
gg	Jump to first item in the list
G	Jump to last item in the list
{	Jump to prev item with a different level
}	Jump to next item with a different level

Action Controls

key	action
<enter>	Toggle directory or open file
o	Open item
E	Expand all directories under root
C	Collapse all directories
R	Change root to item under cursor (if dir)
I	Toggle item stat info
1..9	Expand all directories up to $NUM depth
q, <ctrl-d>	Quit
<tab>	Toggle item selection under cursor
/	Toggle search mode
:	Toggle command mode

File System Controls

key	action
cd	Quit and change directory to item under cursor (needs setup)

Search Mode Controls

Type / in regular mode to initiate search mode.

key	action
<escape>	Quit search, restore cursor to pre-search position
<enter>	Quit search, cursor stays on found item

Command Mode Controls

Type : in regular mode to initiate command mode.

key	action
<escape>	Quit command mode
<enter>	Quit fex, execute command with selected items or item under cursor as arg(s)

Display Toggle Controls

Toggle displayed information.

key	action
.	Toggle dotfile display
I	Toggle item stat info
ti	Toggle icon display
tp	Toggle permission info display
ts	Toggle size display
tt	Toggle time display
tl	Toggle link target display
tu	Toggle user name display
tg	Toggle group name display
tm	Display modified time
ta	Display accessed time
tc	Display changed time

Sort Controls

Sort entries in a directory.

key	action
sn	Sort in ascending order by name
ss	Sort in ascending order by size
st	Sort in ascending order by displayed time
sdn	Sort in descending order by name
sds	Sort in descending order by size
sdt	Sort in descending order by displayed time

Platform Support

fex should ideally compile and run on all macOS and Linux targets supported by Zig. Some features such as opening fs items work only on macOS for now.

Portions of fex code is platform specific and Windows compatibility has not been accounted for. This may be added in later.

arch	macOS	Linux	Windows
arm	works	does not compile	does not compile
x86	works*	works	does not compile

Currently fex only has shell integration for Zsh. Fish and Bash integrations will be added.

works*: uses stat instead of lstat for macOS x86 so links may not be shown.