sudormrfbin / f

Quickly get to a previously mentioned file in fish shell -- z for files !

F

f lets you open files whose names you typed in the commandline some time before. The filenames will be recognized and stored by f, which you can then use in the future. It’s like the famous rupa/z plugin and uses the frecency concept, but for files. Similar to it, f also needs some time to learn the files you access the most and build a database. Usage is fairly similar, but with some added niceties.

Most of the f source code has been modified from jethrokuan’s z port from bash to pure fish. Many, many thanks to him and the original author of z, rupa.

Table of Contents

• Installation
• Usage
  • Notable flags and examples
  • Keybindings
• Configuration
• FAQ

Installation

f has been tested only on fish version 3, specifically 3.1.2. Other versions should work as the code is based on the fish port of z which works on fish >=2.7.0, though it is possible that there is some compatibility issue. Please open an issue if you have trouble installing.

Recommended installation is through fisher:

fisher install gokulsoumya/f

It is recommended to install fzf or any other fuzzy filter of your choice which can be used to fuzzily open (multiple) files, delete entries from the database, etc.

Usage

The files are opened by default with $VISUAL. If not set, $EDITOR will be used. One of these variables has to be set. Use --with to open the files with another command. All files are stored and retrieved as absolute paths.

$ f --help

Usage: f [-d] [-r|-t] [-w cmd|-a|-o] [-K cmd] [-k] [query] ...
       f [-r|-t] [-K cmd] [-k] -x [query] ...
       f [-r|-t] -l [query] ...
       f -c|-p|-h

        -k --pick       Launch fzf for selection and then open with $EDITOR
        -K --picker cmd Command to be used as picker program; implies -k
        -w --with cmd   Open the file with command cmd rather than $EDITOR
        -d --cd         cd to the file directory after selection
        -a --app        Open with default app, using xdg-open or open
        -c --clean      Remove files that no longer exist from $F_DATA
        -o --echo       Print match and return
        -l --list       List matches and scores
        -p --purge      Delete all entries from $F_DATA
        -r --rank       Search by rank
        -t --recent     Search by recency
        -x --delete     Remove selected file from database
        -h --help       Print this help

Notable flags and examples

Let’s look at some interesting examples:

# Open the best matched file that has "con" and "fish" somewhere in it's name
$ f con fish

# Open the most recently mentioned file
$ f --recent

# Launch fzf to select a file from all files and open it
$ f --pick

# Launch fzf with "somestring" prefilled as query
$ f --pick somestring

# Interactlively delete an entry
$ f --pick --delete

# Pick using alternative fuzzy filter or command
$ f --picker 'tail -n1'

# Open with default app, uses xdg-open on Linux and open on OSX internally
$ f --app --pick

# Pick a file using fzf and view it using less
$ f --with less --pick

# Filenames are simply passed as arguments to the --with command
$ f --with rm --pick

# Pick a file using fzf, cd to it's parent directory and run ls -l on the file
$ f --cd --with 'ls -l' --pick

ℹ️	When using --picker or if F_PICKER is set, the arguments to f are discarded (the flags are still used). When using the default fzf picker, the arguments are used as a query to start fzf with.

Multiple files can be selected using the picker program; they should be printed to stdout with one file per line. With the default fzf picker, Tab can be used to select multiple files.

💡	Use f --pick --delete to interactively delete [multiple] files from the database.

Keybindings

The whole reason I wrote this plugin was for this one feature — insert filenames into the command line without hitting tab a thousand times or doing a token search with part of the filename. You can do this using the Alt+K keybinding. This opens fzf and the filename you choose will be inserted into the commandline.

💡	You can select and insert multiple files using the picker.

If Alt+K is already bound to something, it will not be overridden. Instead you can bind __f_insert_from_picker to any key you wish:

$ bind \eu __f_insert_from_picker  # bind Alt-u
$ bind -M insert \eu __f_insert_from_picker  # for vim insert mode

Configuration

• set -U F_CMD "p"
  Change command from f to p.

• set -U F_DATA "$HOME/.foo"
  Set data file to $HOME/.foo instead of $XDG_DATA_HOME/f/data.

• set -U F_EXCLUDE ".*password.*" ".*\.txt"
  List of regex patterns to use to exlude files from being added to f database.

ℹ️	If not set by the user, F_EXCLUDE is set to a list with "^/tmp/.+" as the only item.

• set -U F_PICKER "skim"
  Command to use as interactive filtering program. Must be a string, not a list.

• set -U F_OWNER "username"
  Ensure data file is owned by username. This prevents usage of f with sudo to cause file to be inaccessible in non-sudo sessions.

FAQ

1. Backgrounding with & is not working with f --with cmd

   Functions cannot be backgrounded in fish, so something like f --with gedit --pick & won’t work as expected.

2. Filenames I haven’t typed in are showing up in the list

   f works by scanning the command line and looking for valid filenames after each time a command is executed. If by some chance a file in a directory has the same name as some random token in the commandline, a false positive may be recorded.
   Consider that a file called status is present in the directory you’re currently in. Now if you execute the status command, f will record the absolute path of the file status in it’s database. If you see this often with a particular file, you can make use of the F_EXCLUDE configuration variable.