docs/kittens/choose-files.rst
.. only:: man
Overview
--------------
.. versionadded:: 0.45.0
.. only:: not man
.. figure:: /screenshots/choose-files.webp
:alt: The choose files kitten, showing metadata and title from an e-book file
:align: center
:width: 100%
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 :guilabel:File open and save
dialog boxes common to GUI programs. On Linux, with the help of the
:doc:desktop-ui </kittens/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 :kbd:Enter. You can change the current directory by selecting a
directory and pressing the :kbd:Tab key. :kbd: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 :sc:insert_chosen_file for files or
:sc:insert_chosen_directory 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 <https://www.ffmpeg.org/>__ is needed for video
previews and calibre <https://calibre-ebook.com>__ is needed
for ebook metadata and cover preiews.
You can create keyboard shortcuts to quickly switch to any directory in
:file:choose-files.conf. For example:
.. code-block:: conf
map ctrl+t cd /tmp map alt+p cd ~/my/project
When you wish to select multiple files, start the kitten with :option:--mode <kitty +kitten choose_files --mode>:code:=files. Then instead of pressing
:kbd:Enter, press :kbd:Shift+Enter instead and the file will be added to the list
of selections. You can also hold the :kbd:Ctrl key and click on files to add
them to the selections. Similarly, you can hold the :kbd:Alt key and click to
select ranges of files (similar to using :kbd:Shift+click in a GUI app).
Press :kbd: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 :kbd:Shift+Enter will un-select a
previously selected file.
By default, the kitten does not process hidden files and directories (whose
names start with a period). This can be :opt:changed in the configuration <kitten-choose_files.show_hidden>
and also at runtime via the clickable link to the right of the search input.
Similarly, the kitten respects both :file:.gitignore and :file:.ignore
files, by default. This can also be changed both :opt:in configuration <kitten-choose_files.respect_ignores> or at runtime. Note that
:file:.gitignore files are only respected if there is also a :file:.git
directory present. The kitten also supports the global :file:.gitignore file,
though it applies only inside git working trees. You can specify :opt:global ignore patterns <kitten-choose_files.ignore>, that apply everywhere in :file:choose-files.conf.
This kitten can also be used to select non-existent files, that is a new file
for a :guilabel:Save file type of dialog using :option:--mode <kitty +kitten choose_files --mode>:code:=save-file. Once you have changed to the directory
you want the file to be in (using the :kbd:Tab key),
press :kbd:Ctrl+Enter and you will be able to type in the file name. If you
wish to modify an existing file name use :kbd:Alt+Enter to modify the
filename of the current top match instead.
This kitten can also be used to select directories,
for an :guilabel:Open directory type of dialog using :option:--mode <kitty +kitten choose_files --mode>:code:=dir. Once you have changed to the directory
you want, press :kbd:Ctrl+Enter to accept it. Or if you are in a parent
directory you can select a descendant directory by pressing :kbd:Enter, the
same as you would for selecting a file to open.
You can configure various aspects of the kitten's operation by creating a
:file:choose-files.conf in your :ref:kitty config folder <confloc>.
See below for the supported configuration directives.
.. include:: /generated/conf-kitten-choose_files.rst
.. include:: /generated/cli-kitten-choose_files.rst