kitten-choose-files - Man Page

Added in version 0.43.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 (coming soon) 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.

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.

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

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 name for saving that does not yet exist. 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 current

Change to parent directory

map shift+tab cd up

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 ctrl+t cd /tmp

Next filter

map ctrl+f 1

Previous filter

map alt+f -1

Toggle showing dotfiles

map alt+h toggle dotfiles

Toggle showing ignored files

map alt+d toggle ignorefiles

Toggle sorting by dates

map alt+d toggle sort_by_dates

The source code for this kitten is available on GitHub.

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.

Kovid Goyal

2025, Kovid Goyal

kitten(1).