= F image:https://img.shields.io/github/v/release/gokulsoumya/f?label=&style=flat-square[link="https://github.com/gokulsoumya/f/releases/latest"] image:https://img.shields.io/github/license/gokulsoumya/f?style=flat-square[link="LICENSE"] :toc: macro :experimental:

ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

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 https://www.github.com/rupa/z[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 https://github.com/jethrokuan[jethrokuan's] https://github.com/jethrokuan/z[z] port from bash to pure fish. Many, many thanks to him and the original author of z, https://github.com/rupa[rupa].

toc::[]

== 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 https://github.com/jorgebucaran/fisher[fisher]:

fisher install gokulsoumya/f

It is recommended to install https://github.com/junegunn/fzf[`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:

$ f con fish

$ f --recent

$ f --pick

$ f --pick somestring

$ f --pick --delete

$ f --picker 'tail -n1'

$ f --app --pick

$ f --with less --pick

$ f --with rm --pick

NOTE: When using --picker or if <<Configuration,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]]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, kbd:[Tab] can be used to select multiple files.

TIP: 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 kbd:[Alt+K] keybinding. This opens fzf and the filename you choose will be inserted into the commandline.

TIP: You can select and insert <<multiple-files,multiple files>> using the picker.

If kbd:[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:

== 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.

// The backslash is needed only feore the first * here to render correctly

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

NOTE: 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

[qanda]

Backgrounding with & is not working with f --with cmd:: https://github.com/fish-shell/fish-shell/issues/238[Functions cannot be backgrounded in fish], so something like f --with gedit --pick & won't work as expected.

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.