Skip to content
Back to top

# Selecting files, fast

Added in version 0.45.0.

The choose-files kitten is designed to allow you to select files, very fast, with just a few key strokes. It operates like fzf and similar fuzzy finders, except that it is specialised for finding files. As such it supports features such as filtering by file type, file type icons, content previews and so on, out of the box. It can be used as a drop in (but much more efficient and keyboard friendly) replacement for the File open and save dialog boxes common to GUI programs. On Linux, with the help of the desktop-ui kitten, you can even convince most GUI programs on your computer to use this kitten instead of regular file dialogs.

Simply run it as:

    kitten choose-files

to select a single file from the tree rooted at the current working directory.

Type a few letters from the filename and once it becomes the top selection, press `Enter`. You can change the current directory by selecting a directory and pressing the `Tab` key. `Shift`+`Tab` goes up one directory level.

If you want to choose a file and insert it into your shell prompt at the current cursor position, press `ctrl+shift+p>c` for files or `ctrl+shift+p>d` for directories. Similarly, to have a file chosen in a command line, use, for example:

    some-command $(kitten choose-file)

Note that the above may not work in a complicated pipeline as it performs terminal I/O and needs exclusive access to the tty device while choosing a file.

Note

For content previews, this kitten uses some external programs. In particular ffmpeg is needed for video previews and calibre is needed for ebook metadata and cover preiews.

## Creating shortcuts to favorite/frequently used directories

You can create keyboard shortcuts to quickly switch to any directory in `choose-files.conf`. For example:

    map ctrl+t cd /tmp
    map alt+p  cd ~/my/project

## Selecting multiple files

When you wish to select multiple files, start the kitten with `--mode``=files`. Then instead of pressing `Enter`, press `Shift`+`Enter` instead and the file will be added to the list of selections. You can also hold the `Ctrl` key and click on files to add them to the selections. Similarly, you can hold the `Alt` key and click to select ranges of files (similar to using `Shift`+`click` in a GUI app). Press `Enter` on the last selected file to finish. The list of selected files is displayed at the bottom of the kitten and you can click on them to deselect a file. Similarly, pressing `Shift`+`Enter` will un-select a previously selected file.

## Hidden and ignored files

By default, the kitten does not process hidden files and directories (whose names start with a period). This can be `changed in the configuration` and also at runtime via the clickable link to the right of the search input.

Similarly, the kitten respects both `.gitignore` and `.ignore` files, by default. This can also be changed both `in configuration` or at runtime. Note that `.gitignore` files are only respected if there is also a `.git` directory present. The kitten also supports the global `.gitignore` file, though it applies only inside git working trees. You can specify `global ignore patterns`, that apply everywhere in `choose-files.conf`.

## Selecting non-existent files (save file names)

This kitten can also be used to select non-existent files, that is a new file for a Save file type of dialog using `--mode``=save-file`. Once you have changed to the directory you want the file to be in (using the `Tab` key), press `Ctrl`+`Enter` and you will be able to type in the file name. If you wish to modify an existing file name use `Alt`+`Enter` to modify the filename of the current top match instead.

## Selecting directories

This kitten can also be used to select directories, for an Open directory type of dialog using `--mode``=dir`. Once you have changed to the directory you want, press `Ctrl`+`Enter` to accept it. Or if you are in a parent directory you can select a descendant directory by pressing `Enter`, the same as you would for selecting a file to open.

## Selecting files or directories

To select any existing path, whether it is a file or a directory, use `--mode``=all`. Press `Enter` to select the highlighted path. You can still use `Tab` to change into a highlighted directory and `Ctrl`+`Enter` to select the current directory itself.

## Editing the search text

The search/filter text box uses the same line editing engine as the shell prompt kitten, supporting the usual Emacs-style editing shortcuts such as `Ctrl`+`A`/`Ctrl`+`E` to move to the start/end of the text, `Ctrl`+`Left`/`Ctrl`+`Right` to move by a word, `Ctrl`+`K`/`Ctrl`+`U` to delete to the end/start of the line, `Ctrl`+`W`/`Alt`+`D` to delete the previous/next word and so on.

However, by default, the arrow keys as well as `Home`, `End`, `Ctrl`+`Home` and `Ctrl`+`End` are bound to actions that navigate the list of matched results, rather than moving the cursor within the search text, since that is the more frequently needed behavior when quickly filtering a list of files. If you prefer these keys to edit the search text instead, as in a regular text input, you can rebind them to one of the following actions in `choose-files.conf`, which forward the key press to the search text editor:

Action | Editing operation it performs
--- | ---
`edit_cursor_left` | Move the cursor one character to the left
`edit_cursor_right` | Move the cursor one character to the right
`edit_start_of_line` | Move the cursor to the start of the search text
`edit_end_of_line` | Move the cursor to the end of the search text
`edit_start_of_document` | Same as `edit_start_of_line`, provided for symmetry with the shell prompt’s line editor
`edit_end_of_document` | Same as `edit_end_of_line`, provided for symmetry with the shell prompt’s line editor
`edit_forward_word` | Move the cursor forward by one word
`edit_backward_word` | Move the cursor backward by one word
`edit_backspace` | Delete the character before the cursor
`edit_delete` | Delete the character after the cursor
`edit_kill_to_start_of_line` | Delete everything from the start of the line to the cursor
`edit_kill_to_end_of_line` | Delete everything from the cursor to the end of the line
`edit_kill_word_left` | Delete the word before the cursor
`edit_kill_word_right` | Delete the word after the cursor
`edit_yank` | Insert the most recently deleted text

For example, to make the arrow keys, `Home` and `End` edit the search text instead of navigating the results list:

    map left    edit_cursor_left
    map right   edit_cursor_right
    map home    edit_start_of_line
    map end     edit_end_of_line
    map ctrl+home edit_start_of_document
    map ctrl+end  edit_end_of_document

Note that `Up`, `Down` and other keys not listed above continue to be usable for navigating the results list even after applying the above overrides. Also note that any key not bound to an action at all is automatically forwarded to the search text editor, which is why keys such as `Backspace`, `Delete`, `Ctrl`+`K`, `Ctrl`+`W` etc. already edit the search text, without needing any of the above actions.

## Configuration

You can configure various aspects of the kitten’s operation by creating a `choose-files.conf` in your kitty config folder. See below for the supported configuration directives.

## Filesystem scanning

show_hidden

    show_hidden last

Whether to show hidden files. The default value of `last` means remember the last used value. This setting can be toggled within the program.

sort_by_last_modified

    sort_by_last_modified last

Whether to sort the list of entries by last modified, instead of name. Note that sorting only applies before any query is entered. Once a query is entered entries are sorted by their matching score. The default value of `last` means remember the last used value. This setting can be toggled within the program.

respect_ignores

    respect_ignores last

Whether to respect .gitignore and .ignore files and the `ignore` setting. The default value of `last` means remember the last used value. This setting can be toggled within the program.

ignore

An ignore pattern to ignore matched files. Uses the same sytax as `.gitignore` files (see `man gitignore`). Anchored patterns match with respect to whatever directory is currently being displayed. Can be specified multiple times to use multiple patterns. Note that every pattern has to be checked against every file, so use sparingly.

## Appearance

show_preview

    show_preview last

Whether to show a preview of the current file/directory. The default value of `last` means remember the last used value. This setting can be toggled within the program.

pygments_style

    pygments_style default

The pygments color scheme to use for syntax highlighting of file previews. See pygments builtin styles for a list of schemes. This sets the colors used for light color schemes, use `dark_pygments_style` to change the colors for dark color schemes.

dark_pygments_style

    dark_pygments_style github-dark

The pygments color scheme to use for syntax highlighting with dark colors. See pygments builtin styles for a list of schemes. This sets the colors used for dark color schemes, use `pygments_style` to change the colors for light color schemes.

cache_size

    cache_size 0.5

The maximum size of the disk cache, in gigabytes, used for previews. Zero or negative values mean no limit.

syntax_aliases

    syntax_aliases pyj:py pyi:py recipe:py

File extension aliases for syntax highlight. For example, to syntax highlight `file.xyz` as `file.abc` use a setting of `xyz:abc`. Multiple aliases must be separated by spaces.

video_preview

    video_preview width=480 fps=10 duration=5

Control how videos are sampled for previwing. The width controls the size of the generated thumbnail from the video. Duration controls how long the generated thumbnail plays for, in seconds. Note that when changing these you should also use the `--clear-cache` flag otherwise it will not affect already cached previews.

previewer

Specify an arbitrary program based preview generator. The syntax is:

    pattern program arguments...

Here, pattern can be used to match file names or mimetypes. For example: `name:*.doc` matches files with the extension `.doc`. Similarly, `mime:image/*` matches all image files. `program` can be any executable program in PATH. It will be run with the supplied arguments. The last argument will be the path to the file for which a preview must be generated.

Can be specified multiple times to setup different previewers for different types of files. Note that previewers specified using this option take precedence over the builtin previewers.

The command must output preview data to STDOUT, as a JSON object:

    {
        "lines": ["line1", "line2", "..."],
        "image": "absolute path to generated image preview",
        "title_extra": "some text to show on the first line",
    }

The lines can contain SGR formatting escape codes and will be displayed as is at the top of the preview panel. The image is optional and must be in one of the JPEG, PNG, GIF, WEBP, APNG formats.

## Keyboard shortcuts

Quit

    map esc quit
    map ctrl+c quit

Accept current result

    map enter accept

Select current result

    map shift+enter select

When selecting multiple files, this will add the current file to the list of selected files. You can also toggle the selected status of a file by holding down the `Ctrl` key and clicking on it. Similarly, the `Alt` key can be held to click and extend the range of selected files.

Type file name

    map ctrl+enter typename

Type a file name/path rather than filtering the list of existing files. Useful when specifying a file or directory name for saving that does not yet exist. When choosing existing directories, will accept the directory whoose contents are being currently displayed as the choice. Does not work when selecting files to open rather than to save.

Modify file name

    map alt+enter modifyname

Modify the name of an existing file and select it for saving. Useful when specifying a file or directory name for saving that does not yet exist, but is based on an existing file name. Does not work when selecting files to open rather than to save.

Next result

    map down next 1

Previous result

    map up next -1

Left result

    map left next left

Right result

    map right next right

First result on screen

    map home next first_on_screen
    map ctrl+home next first

Last result on screen

    map end next last_on_screen
    map ctrl+end next last

Change to currently selected dir

    map tab cd .

Change to parent directory

    map shift+tab cd ..

Change to root directory

    map ctrl+/ cd /

Change to home directory

    map ctrl+~ cd ~
    map ctrl+` cd ~
    map ctrl+shift+` cd ~

Change to temp directory

    map --allow-fallback=shifted,ascii ctrl+t cd /tmp

Next filter

    map --allow-fallback=shifted,ascii ctrl+f 1

Previous filter

    map --allow-fallback=shifted,ascii alt+f -1

Toggle showing dotfiles

    map --allow-fallback=shifted,ascii alt+h toggle dotfiles

Toggle showing ignored files

    map --allow-fallback=shifted,ascii alt+i toggle ignorefiles

Toggle sorting by dates

    map --allow-fallback=shifted,ascii alt+d toggle sort_by_dates

Toggle showing preview

    map --allow-fallback=shifted,ascii alt+p toggle preview

## Source code for choose_files

The source code for this kitten is available on GitHub.

## Command Line Interface

    kitten choose_files [options] [directory to start choosing files in]

Select one or more files, quickly, using fuzzy finding, by typing just a few characters from the file name. Browse matching files, using the arrow keys to navigate matches and press `Enter` to select. The `Tab` key can be used to change to a sub-folder. See the online docs for full details.

### Options

--mode <MODE>

  The type of object(s) to select Default: `file` Choices: `all`, `dir`, `dirs`, `file`, `files`, `save-dir`, `save-file`, `save-files`

--file-filter <FILE_FILTER>

  A list of filters to restrict the displayed files. Can be either mimetypes, or glob style patterns. Can be specified multiple times. The syntax is `type:expression:Descriptive Name`. For example: `mime:image/png:Images` and `mime:image/gif:Images` and `glob:*.[tT][xX][Tt]:Text files`. Note that glob patterns are case-sensitive. The mimetype specification is treated as a glob expressions as well, so you can, for example, use `mime:text/*` to match all text files. The first filter in the list will be applied by default. Use a filter such as `glob:*:All` to match all files. Note that filtering only appies to files, not directories.

--suggested-save-file-name <SUGGESTED_SAVE_FILE_NAME>

  A suggested name when picking a save file.

--suggested-save-file-path <SUGGESTED_SAVE_FILE_PATH>

  Path to an existing file to use as the save file.

--title <TITLE>

  Window title to use for this chooser

--display-title [=no]

  Show the window title at the top, useful when this kitten is used in an OS window without a title bar.

--override <OVERRIDE>, -o <OVERRIDE>

  Override individual configuration options, can be specified multiple times. Syntax: name=value.

--config <CONFIG>

  Specify a path to the configuration file(s) to use. All configuration files are merged onto the builtin `choose-files.conf`, overriding the builtin values. This option can be specified multiple times to read multiple configuration files in sequence, which are merged. Use the special value `NONE` to not load any config file.

  If this option is not specified, config files are searched for in the order: `$XDG_CONFIG_HOME/kitty/choose-files.conf`, `~/.config/kitty/choose-files.conf`, `$XDG_CONFIG_DIRS/kitty/choose-files.conf`. The first one that exists is used as the config file.

  If the environment variable `KITTY_CONFIG_DIRECTORY` is specified, that directory is always used and the above searching does not happen.

  If `/etc/xdg/kitty/choose-files.conf` exists, it is merged before (i.e. with lower priority) than any user config files. It can be used to specify system-wide defaults for all users. You can use either `-` or `/dev/stdin` to read the config from STDIN.

--write-output-to <WRITE_OUTPUT_TO>

  Path to a file to which the output is written in addition to STDOUT.

--output-format <OUTPUT_FORMAT>

  The format in which to write the output. The `text` format is absolute paths separated by newlines, with a trailing newline. The `shell` format is quoted absolute paths separated by spaces, quoting is done only if needed. The `shell-relative` format is the same as `shell` except that it returns paths relative to the starting directory. Note that when invoked from a mapping, this option is ignored, and either text or shell format is used automatically based on whether the cursor is at a shell prompt or not. Default: `text` Choices: `json`, `shell`, `shell-relative`, `text`

--write-pid-to <WRITE_PID_TO>

  Path to a file to which to write the process ID (PID) of this process to.

--clear-cache [=no]

  Clear the caches used by this kitten.