Skip to content
/ fex Public

A command-line file explorer prioritizing quick navigation.

License

Notifications You must be signed in to change notification settings

18alantom/fex

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

fex logo bar

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.

fex screenshot

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 pervious 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

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:

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.