From c8a20dbe582650beec95f79b095e0e635655b61b Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 16 Jul 2025 06:16:38 +0530 Subject: [PATCH] Start documenting the choose-files kitten --- docs/kittens/choose-files.rst | 19 +++++++++++++++++++ kittens/choose_files/main.py | 4 ++++ 2 files changed, 23 insertions(+) diff --git a/docs/kittens/choose-files.rst b/docs/kittens/choose-files.rst index eaef88580..52431bea7 100644 --- a/docs/kittens/choose-files.rst +++ b/docs/kittens/choose-files.rst @@ -6,6 +6,25 @@ Selecting files, fast Overview -------------- +.. versionadded:: 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 :guilabel:`File open and save` +dialog boxes common to GUI programs. On Linux, with the help of the +:doc:`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. Configuration ------------------------ diff --git a/kittens/choose_files/main.py b/kittens/choose_files/main.py index db6eec450..164dc3e54 100644 --- a/kittens/choose_files/main.py +++ b/kittens/choose_files/main.py @@ -149,6 +149,10 @@ Path to a file to which to write the process ID (PID) of this process to. help_text = '''\ +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 :kbd:`Enter` +to select. The :kbd:`Tab` key can be used to change to a sub-folder. See the :doc:`online docs ` +for full details. '''