Name¶

kitten-choose-files - Choose files, fast

Overview¶

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 <https://github.com/junegunn/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 instead selecting a directory and pressing the Tab key. Shift+Tab goes up one directory level.

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.

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.

Configuration¶

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

Filesystem scanning¶

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

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

pygments_style default

The pygments color scheme to use for syntax highlighting of file previews. See pygments builtin styles <https://pygments.org/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 github-dark

The pygments color scheme to use for syntax highlighting with dark colors. See pygments builtin styles <https://pygments.org/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.

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.

Keyboard shortcuts¶

map esc quit
map ctrl+c quit

map enter accept

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.

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.

map down next 1

map up next -1

map left next left

map right next right

map home next first_on_screen
map ctrl+home next first

map end next last_on_screen
map ctrl+end next last

map tab cd .

map shift+tab cd ..

map ctrl+/ cd /

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

map ctrl+t cd /tmp

map ctrl+f 1

map alt+f -1

map alt+h toggle dotfiles

map alt+i toggle ignorefiles

map alt+d toggle sort_by_dates

map alt+p toggle preview

Source code for choose_files¶

The source code for this kitten is available on GitHub <https://github.com/kovidgoyal/kitty/tree/master/kittens/choose_files>.

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.

Author¶

Kovid Goyal

Copyright¶

2025, Kovid Goyal