Awesome

This project is for creating a file manager using web technologies. My original design was based on NW.js and can be found here. This version uses the same Svelte based frontend code, but the backend is a Wails 2 implementation. By using this implementation, I no longer use command line rm, cp, etc. commands. It is fully coded using Go and runs much faster than the previous versions.

Currently, it can't transfer files to other programs with Drag and Drop due to a limitation of the web technologies used. I should be able to get past this limitation soon by using lower level commands to the operating system which I will be exploring with this new Wails 2 implementation.

This file manager is designed around the same principle as Vim: a state controlled keyboard actions. The number of states isn't fixed, but very programmable. Therefore, an infinite number of keyboard configurations can be created and used. This is the main difference from other file managers. The Favorites extensions shows a good example of extending the number of states by adding a “fav” state.

This picture shows Modal File Manager in it's default theme.

A small gif showing Modal File Manager in action.

Disclamer: This program can permanently delete directories and files. Use at your own risk! I accept no liability for lost information from the use of this software. User beware! But, if you have a major problem, please let me know so that I can look for solutions. Deletions currently default to moving to the trashcan on new installations.

Table of Contents

• Philosophy
• Current Feature Set
• Some Limitations
• Installation
• Command Line
• Upgrading
• Command Line Programs Used
• Configuration Files
• Source File Layout
• Editing Files
• Preferences
• Things in the Works
• Default Key Bindings
  • Normal Mode
  • Visual Mode
  • Insert Mode
• Command Prompt Commands
• Extension Commands
• Creating Themes
• Creating Extensions
• Tutorials on Modal File Manager
• Icon
• Sponsor this project

Philosophy

I started my programming career with Emacs as my main text editor on a main frame computer in college (after they quit using punch cards!). I really loved Emacs, but had a very hard time remembering all the key commands. I ended up using Vim once for a class I had (the teacher loved Vim) and hit the perverbial Vim wall -- How do I exit this thing! I finally had to kill the process. So, I went back to Emacs.

With Spacemacs and Doom-emacs, I learned that the Vim style keyboard was much more efficient. But, I kept going back to the Emacs key memory. I finally decided to really give Vim a run with neovim on my MacBook Air. I even installed Spacevim and really liked it. Now, I'm fully comfortable in the Vim style keyboard (but far from mastering it completely) and have adapted it to many other programs along the way. My current editor of choice is NeoVim with the LazyVim configuration which is the fastest programming editor I've ever used. It is great!

But, I've never been happy with the file managers I've used. fman is great, but it is no longer actively being maintained and expanded upon. It is very slow in large directories and I also don't really like python: it's API language. So, I decided to jump in and make one to suit me better. This is how Modal File Manager was started. I wanted something that was as configurable as TkDesk was (if anyone remembers it), but with a modal keyboard model for hotkeys. To take it even further, new modes and keymaps can be added with extensions.

Modal File Manager is also somewhat minimal in the UI. Many graphical file managers have buttons, shelves, etc. all over the place with information everywhere. I decided to make the main interface as low keyed as possible with all other information in the status line or extras panel. Extra file information is on the status line for the current cursor location. More information is displayed in the extras panel as well (the side opposite the current pointer shows extra information instead of the other file pane. When turned off, it automatically goes back to the file pane that was showing before switching.).

Since there are so many dual pane file managers available, I knew this would never be a marketable product (and I did not want the hassle of endless customer complaint over a feature not working the way they want it). Therefore, I'm making this an open source project to hopefully get some help from others to help really make this thing shine. To date, I haven't received any comments or help with this program. But, my number of stars on GitHub climb every week!

Therefore, I hope you enjoy this little program as much as I have. Feel free to sponsor the project, help code some of it (just send in the pull requests), or just give me some tips along the way. Any help is appreciated.

I've created multiple open source resources (I have around 80 GitHub repositories), but this is the first full product. Therefore, please bear with me as I learn about maintaining and supporting an open source project.

Current Feature Set

• Dual pane file manager with vim style model hotkeys for navigation and action launching.
• Drag and Drop works for copying or moving the current cursor and all selected files or directories (the current cursor location) within the application itself. If no keys pressed, it will be copied. If shift key is pressed, it will be moved. The drag begins with the current cursor.
• Command Prompt for executing commands (: in any mode or <ctrl>p in normal mode).
• Fully extendable with extensions using the extensions API
• Fully theme-able.
• Launching with paths on the command line will open in the specified directories. See Command Line.
• A file details side panel can be shown to overlay the panel not currently focused (toggleExtraPanel command or “s” in normal mode). It is fairly bare right now due to changing from NW.js to the Wails 2. I have lot of ideals, but haven't added them yet. Extensions can place special content in this panel as well (Project Manager extension is a good example).
• Hot keys are programmable. Currently by editing the key map files, or writing an extension.
• Select entries by regular expressions. The regular expressions are saved and can be reused.
• A number before a hot key runs it's associated command that many times (ex: 5j will move the cursor 5 entries down the list).
• Watches for changes in the current directory and updates accordingly.
• Changing directories in the Directory Bar (normal mode q) shows a list of matching entries from history and then below the current directory. Pressing Escape leaves the Directory Bar in the original location. If you type letters after the current directory, all subdirectories are searched to match that grouping of letters and added to the dropdown list after directories in the history are displayed.
• File editor is configurable by the ~/.myeditorchoice file (see Editing Files below). Otherwise, the system editor for the file type will be used.
• Quick Search - an input to type text so that any entry at that level is removed that doesn't have that text in it. Just refresh the pane to get back to normal. I think of it as a quick filter more than a quick search.
• Toggle System files/folders visibility
• Optionally deletes to the OS's trashcan (external program has to be installed)
• Change the environment used to execute external programs using the Show Preferences Command Prompt command.
• Theme Creator/Editor
• Center bar separating panels can be dragged back and forth to change it's location.
• Extensions and Themes can be viewed and downloaded from GitHub inside of Modal File Manager. Just use the Toggle GitHub Importer command on the command prompt.
• Extension Creator/Editor with template.
• Extensions controled content in the Extras Panel.
• Extensions currently created and downloadable from GitHub:
  • Copy to Clipboard: copy file name or path to clipboard with command prompt.
  • Alfred: Launch Afred Browser on the current cursor location
  • Move to Dir: Selected files are moved to the folder under the cursor in the same panel
  • iTerm: open the current cursor directory in iTerm2
  • Favorites: An extension to mark favorite directories to be able to go back to easily, back up directories previously entered, six directory registers to quickly hop around using the fav mode, and much more.
  • User Scripts: Create and run scripts from mfm.
  • Project Manager: A set of functions to work with projects, project templates, run project scripts for npm and mask, and creating/editing of project notes.
• Themes currently created and downloadable from GitHub:
  • Dracula Pro
  • Dracula "Buffy"
  • Dracula "Van Helsing"

All Dracula based themes are here with permission from the author. Please support his great work at Dracula Themes. The Dracula "Buffy" theme is my preferred theme for everything.

Some Limitations

Because this is a web technologies application, there are certain things that it just can't do and I'm not sure if they can be done at this level. Therefore, this will not completely remove your dependency on using the Finder application. But, these instances are not everyday items for which we use a file manager. As I see it, these items are not doable, but I would love for someone to prove me wrong:

• Install applications that the macOS Gatekeeper will allow.
• Drag and drop with other programs.
• Git command line needs to be installed for downloading extensions and themes.

Installation

This project is a Wails 2 project. If you want to compile the program yourself, you will need to have Wails, go language from Google, and Node installed on your computer. You will also need a working git command line to download extensions and themes. The most recent version is what is compiled from these sources. When I have tested many changes, I will release a new version for downloading. So, if you like being on the bleeding edge, clone this repo with:

git clone https://github.com/raguay/ModalFileManager.git

And follow these instructions for compiling the sources. I'm currently building Modal File Manager using macOS and Debian Linux Arm Achitecture, but it should build as is on other Linuxes as well. I haven't fully debugged the Linux build yet (deleting to trash isn't working for example) and therefore I'm not giving a compiled release for it. I'm working on making this available for Windows, Linux, and macOS.

Once you have the prerequisites installed, to build the program, simply type:

wails build 

The fully compiled program should be in the build/bin directory.

You can run in developer mode in which you can debug the frontend code by running:

wails dev 

If you right click on the background of a dev build, the popup menu has the entry to 'inspect'. Clicking on it will open the developer tools to debug the frontend code.

Once Modal File Manager is installed, you will have to give mfm permission to access directories on your system.

Command Line

Modal File Manager takes command line arguments as well. I will be expanding this feature more and more to help with automation. On the macOS, you need to create an alias in your shell for the command line program. If you place the mfm.app file in your /Applications folder on a macOS system, you would add this to your .zshrc file in your home directory:

alias mfm='/Applications/mfm.app/Contents/MacOS/mfm'

Once you reload the shell, you can give one or two file/directory paths to open Modal File Manager in those directories. For example:

mfm '/User/raguay/Dropbox (Personal)'

will open the Modal File Manager in my personal dropbox folder in the left pane. Notice, you have to give the quote marks because of the spaces and parentheses. If you give two paths, then the first is the left pane while the second is the right pane.

Upgrading

If a new version comes out with new default key mappings, you will either have to manually alter the key maps or delete the keyMaps directory in the Modal File Manager configuration directory. Since I haven't ever changed the default key maps, this is rarely ever needed. Just check the change log for the new version to see if you need to do that or not.

Command Line Programs Used

There are a few command line programs I use with Modal File Manager. They are:

• git for downloading extensions and themes.
• ffmpeg for getting and using video information in the Extra Panel.
• For using the macOS trashcan, you have to have (trash)[https://github.com/andreafrancia/trash-cli] command line program installed using brew install trash-cli. You have to have HomeBrew installed on your system to use the brew command line program. If the program isn't installed before installing mfm, then you will need to adjust the environment variable for PATH in the preferences to make sure it is in the path.

All of the programs should be downloaded and in your shell's path. Modal File Manager doesn't assume location for anything except for it's own configuration files. But, if Modal File Manager can't find the program, you can adjust the path used in the preferences general tab (Command Prompt command is Show Preferences).

Configuration Files

All extensions, themes, keyboard layouts, and anything else for configuring the Modal File Manager is found in it's main configuration directory. On Linux and macOS, it is located at: ~/.config/modalfilemanager. It will be in the Windows User directory, but I haven't really looked at Windows functionality yet.

In this configuration directory, there are the themes, extensions, and keyMaps directories that contain their respective subfolders and files. Please refer the specific section for each directory for more details.

There is the history.json file, config.json file, and the theme.json files in the configuration directory. Also, extensions will create and store their configuration files in this directory as well (at least, that is what I advise extension authors).

The history.json file contains a list of directories that the Modal File Manager has visited. I use this to quickly pull up possible paths to go to in the file manager.

The config.json file contains the environment variables used to launch command line commands and whether or not to use the trash-cli program to delete files and directories.

Modal File Manager doesn't use the actual theme files downloaded from GitHub. Those are stored in the themes directory and are just referenced. All actually used theming is in the theme.json file. When a user changes themes, that file is changed. Therefore, be careful if you manually change this file and want to keep it. It is best to create a theme in the theme directory and load it in the program. My tutorial Modal File Manager: Update and Extensions walks through creating a theme using the Preferences Panel.

All configuration files should be edited from the Show Preferences command prompt command.

Source File Layout

The directory structure is:

- modalfilemanager
  |
  - frontend
    |
    - src 
      |
      - components                  Here are all the Svelte components for the UI
      - modules                     These are JavaScript Helper files with the data structures used.
      - stores                      This directory contains all the Svelte Store items
      - Start.svelte                This is the main program to start MFM.
      - main.js                     This installs the main program into the HTML
  - app.go                          This is the go language application backend
  - main.go                         This is the go language main routine.
  - wailsjs                         This is the JavaScript backend routines generated by wails.
  - build                           This is the build directory that wails compiles everything into 
  - appicon.png                     The application icon 

All low level functions are in the modules/OS.js and accesses all the functions defined in the app.go file.

Editing files

Files will be edited (normal mode key e) using editor specified in the xBar plugin currentFiles.1h.rb.

To use with the xBar plugin, you will need to have xBar installed and the currentFiles.1h.rb plugin installed and configured. You can also use the Alfred BitBar Workflow to control the plugin.

Alternatively, you can use the TextBar program with the Current Files and Editor plugin installed.

You can use the Alfred with the My Editor Workflow to control the editor and edit files.

If the above editor setup isn't on the system, it will use the operating system defaults to open the file in the default file editor.

Preferences

With the command prompt command of Show Preferences, you can now open a new panel over the file manager that shows all the program preferences. It is setup as a tab system with a General, Theme, and Extension tab.

The General tab allows the user to delete, edit, or add environment variables to the running of command line programs. This give the user complete control over the environment variables used in launching commands from Modal File Manager. You can also turn on/off the use of the trashcan for deletions.

The Theme tab allows you to create, update, and delete themes from the Modal File Manager. My tutorial Modal File Manager: Update and Extensions walks through creating a theme using the Preferences Panel.

The Extension tab allows you to create, edit, and delete extensions from the Modal File Manager. The creation and editing of an extension will open the main file for the extension in the code editor that has been setup and moves the Modal File Manager to the extension's directory in the pane opposite the current cursor.

Things in the Works

• Getting all the functionality as in the original program.
  • Mostly still working on items in the Extra Panel working again.
• Translating my fman extensions to work with Modal File Manager
  • Dropbox File System
  • Zip Selected Entries
• Drag and drop with external programs
• Add more file views for the Extra Panel
• Multiple windows (waiting on Wails 3)
• Get Windows working
• Get Linux tested and working
• Get audio listening in the Extras Panel.
• Documentation!
• Of course, bug fixing!
• More and more features!

Default Key Bindings

Normal Mode

Visual Mode

Insert Mode

Command Prompt Commands

These commands can be ran from the command prompt. They all act upon the current cursor.

Extension Commands

These commands require inputs and supply results. Therefore these commands can`t be used in hotkeys or the command prompt. They are loaded and used in a different way as well. Please refer to the Creating Extensions Section for more details.

Creating Themes

A theme is a GitHub repository or a repository on your system. It is setup as a normal npm project with a package.json file. The package.json file should be similar to this:

{
  "name": "dracula-ThemeModalFileManager",
  "version": "1.0.0",
  "description": "The Dracula theme for Modal File Manager.",
  "keywords": [
    "modalfilemanager"
  ],
  "author": "Richard Guay",
  "license": "MIT",
  "mfmtheme": {
    "name": "dracula-ThemeModalFileManager",
    "description": "Dracula theme for Modal File Manager.",
    "type": 0,
    "github": "",
    "main": "dracula.json"
  }
}

The subheading mfmtheme contains the information the program will use to load the theme. The main is set to the path of the JSON file containing the themes values. If it's in the top of the directory, then use just the file name as seen above.

The type is 0 for local only and 1 for a GitHub download. The github value is the URL to the repository on GitHub. The description is shown to the user that should accurately describe the theme.

The Theme JSON file is like this one:

{
  "font":"Fira Code, Menlo",
  "fontSize":"12pt",
  "cursorColor": "#363443",
  "selectedColor": "#FFCA80",
  "backgroundColor": "#22212C",
  "textColor": "#F8F8F2",
  "borderColor": "#1B1A23",
  "normalbackgroundColor": "#80FFEA",
  "insertbackgroundColor": "#8AFF80",
  "visualbackgroundColor": "#FF80BF",
  "Cyan": "#80FFEA",
  "Green": "#8AFF80",
  "Orange": "#FFCA80",
  "Pink": "#FF80BF",
  "Purple": "#9580FF",
  "Red": "#FF9580",
  "Yellow": "#FFFF80"
}

It should be a proper JSON structure with these definitions. Change the color values as you want.

Creating Extensions

TODO: Documentation Coming Soon.

Tutorials on Modal File Manager

These tutorials are based on using my original, NW.js version of the Modal File Manager:

• My Side Project: Modal File Manager
• Modal File Manager: Update and Extensions

This list of tutorials are with the latest version of Modal File Manager:

• First Release of the New Modal File Manager

Icon

I finally made my first attempt at an icon for Modal File Manager. The files are in the frontend/icons directory. Any constructive criticizm is welcome.

Sponsor this project

You can now sponsor my work on this project. The more sponsors I get, the more time I'll focus on development.