نام (NAME)

kitten-choose-files - ابزار انتخاب سریع پرونده‌ها و پوشه‌ها در ترمینال Kitty

نمای کلی (OVERVIEW)

افزوده‌شده در نسخه 0.45.0.

کیتن choose-files به منظور فراهم ساختن امکان انتخاب بسیار سریع پرونده‌ها تنها با چند فشردن کلید طراحی شده است. عملکرد آن مانند fzf %https://github.com/junegunn/fzf و سایر یابنده‌های فازی (fuzzy finders) است، با این تفاوت که به طور خاص برای یافتن پرونده‌ها تخصص یافته است. از این رو، به صورت پیش‌فرض از ویژگی‌هایی نظیر پالایش بر اساس نوع پرونده، آیکون انواع پرونده، پیش‌نمایش محتوا و مواردی از این دست پشتیبانی می‌کند. این ابزار می‌تواند به عنوان جایگزینی سرراست (اما بسیار کارآمدتر و سازگارتر با صفحه‌کلید) برای کادرهای محاوره‌ای متداول باز کردن و ذخیره پرونده در برنامه‌های گرافیکی (GUI) استفاده شود. در لینوکس، با کمک کیتن desktop-ui %<> حتی می‌توانید اکثر برنامه‌های گرافیکی رایانه خود را وادار کنید به جای کادرهای گفتگوی معمولی پرونده از این کیتن استفاده کنند.

تنها کافی است آن را به صورت زیر اجرا کنید:

kitten choose-files

تا یک پرونده واحد را از درخت ریشه‌گرفته از دایرکتوری کاری جاری انتخاب کنید.

چند حرف از نام پرونده را تایپ کنید و هنگامی که به بالاترین گزینه انتخابی تبدیل شد، کلید Enter را بفشارید. می‌توانید با انتخاب یک دایرکتوری و زدن کلید Tab دایرکتوری جاری را تغییر دهید. فشردن Shift+Tab یک سطح دایرکتوری به بالا می‌رود.

اگر مایلید پرونده‌ای را انتخاب کرده و آن را در اعلان شل در موقعیت مکان‌نمای جاری درج نمایید، برای پرونده‌ها ctrl+shift+p>c %<#shortcut-kitty.Insert-chosen-file> یا برای دایرکتوری‌ها ctrl+shift+p>d %<#shortcut-kitty.Insert-chosen-directory> را بفشارید. به طور مشابه، برای درج پرونده انتخاب‌شده در یک خط فرمان، به عنوان مثال استفاده کنید از:

some-command $(kitten choose-file)

توجه داشته باشید که مورد بالا ممکن است در پایپ‌لاین‌های پیچیده کار نکند، چرا که ورودی/خروجی ترمینال انجام می‌دهد و هنگام انتخاب پرونده نیازمند دسترسی انحصاری به دستگاه tty است.

نکته:

ایجاد میان‌بر برای دایرکتوری‌های برگزیده/پرکاربرد (Creating shortcuts to favorite/frequently used directories)

می‌توانید در choose-files.conf میان‌برهای صفحه‌کلید ایجاد کنید تا به سرعت به هر دایرکتوری دلخواه جابه‌جا شوید. به عنوان مثال:

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

انتخاب چندین پرونده (Selecting multiple files)

هنگامی که مایل به انتخاب چند پرونده هستید، کیتن را با --mode=files اجرا کنید. سپس به جای فشردن Enter، کلید Shift+Enter را بفشارید تا پرونده به فهرست انتخاب‌ها اضافه شود. همچنین می‌توانید کلید Ctrl را نگه داشته و روی پرونده‌ها کلیک کنید تا به گزینه‌های انتخابی افزوده شوند. به طور مشابه، می‌توانید کلید Alt را نگه داشته و کلیک کنید تا دامنه‌ای از پرونده‌ها انتخاب شوند (مشابه استفاده از Shift+click در برنامه‌های گرافیکی). برای پایان کار، روی آخرین پرونده انتخاب‌شده Enter را بفشارید. فهرست پرونده‌های انتخاب‌شده در پایین کیتن نمایش داده می‌شود و می‌توانید با کلیک روی هر یک، آن را از حالت انتخاب خارج کنید. به طور مشابه، فشردن Shift+Enter پرونده‌ای را که قبلاً انتخاب شده از حالت انتخاب خارج می‌کند.

پرونده‌های پنهان و نادیده‌گرفته‌شده (Hidden and ignored files)

به صورت پیش‌فرض، این کیتن پرونده‌ها و دایرکتوری‌های پنهان (که نام آن‌ها با یک نقطه آغاز می‌شود) را پردازش نمی‌کند. این رفتار را می‌توان در پیکربندی تغییر داد و همچنین در حین اجرا از طریق پیوند قابل‌کلیک در سمت راست ورودی جستجو تغییر داد.

به طور مشابه، این کیتن به طور پیش‌فرض پرونده‌های .gitignore و .ignore را رعایت می‌کند. این مورد نیز هم در پیکربندی و هم در حین اجرا قابل تغییر است. توجه داشته باشید که پرونده‌های .gitignore تنها در صورتی رعایت می‌شوند که یک دایرکتوری .git نیز وجود داشته باشد. این کیتن همچنین از پرونده سراسری .gitignore پشتیبانی می‌کند، هرچند فقط در درخت‌های کاری گیت اعمال می‌شود. می‌توانید الگوهای نادیده‌گیری سراسری را که در همه‌جا اعمال می‌شوند در choose-files.conf مشخص کنید.

انتخاب پرونده‌های ناموجود (نام‌های ذخیره پرونده) (Selecting non-existent files (save file names))

از این کیتن همچنین می‌توان برای انتخاب پرونده‌های ناموجود استفاده کرد، یعنی پرونده‌ای جدید برای کادر محاوره‌ای نوع «ذخیره پرونده» با استفاده از --mode=save-file. پس از رفتن به دایرکتوری مورد نظر (با استفاده از کلید Tab)، کلید Ctrl+Enter را بفشارید تا بتوانید نام پرونده را تایپ کنید. اگر می‌خواهید نام یک پرونده موجود را ویرایش کنید، به جای آن از Alt+Enter استفاده کنید تا نام منطبق‌ترین گزینه فعلی ویرایش شود.

انتخاب دایرکتوری‌ها (Selecting directories)

از این کیتن می‌توان برای انتخاب دایرکتوری‌ها نیز استفاده کرد، برای کادر محاوره‌ای نوع «باز کردن دایرکتوری» با استفاده از --mode=dir. پس از رفتن به دایرکتوری مورد نظر، کلید Ctrl+Enter را بفشارید تا پذیرفته شود. یا اگر در دایرکتوری والد هستید، می‌توانید با فشردن Enter یک زیردایرکتوری را انتخاب کنید، دقیقاً همانند انتخاب پرونده برای باز کردن.

انتخاب پرونده‌ها یا دایرکتوری‌ها (Selecting files or directories)

برای انتخاب هر مسیر موجودی، خواه پرونده باشد یا دایرکتوری، از --mode=all استفاده کنید. برای انتخاب مسیر برجسته‌شده، کلید Enter را بفشارید. همچنان می‌توانید از Tab برای ورود به دایرکتوری برجسته‌شده و از Ctrl+Enter برای انتخاب خود دایرکتوری جاری استفاده کنید.

ویرایش متن جستجو (Editing the search text)

کادر متن جستجو/پالایش از همان موتور ویرایش خط کیتن اعلان شل استفاده می‌کند و از میان‌برهای ویرایشی متداول به سبک Emacs پشتیبانی می‌کند، مانند Ctrl+A/Ctrl+E برای رفتن به ابتدا/انتهای متن، Ctrl+Left/Ctrl+Right برای حرکت به اندازه یک کلمه، Ctrl+K/Ctrl+U برای حذف تا انتها/ابتدای خط، Ctrl+W/Alt+D برای حذف کلمه قبلی/بعدی و مواردی از این دست.

با این حال، به طور پیش‌فرض کلیدهای جهت‌نما و همچنین Home، End، Ctrl+Home و Ctrl+End به عملیات پیمایش فهرست نتایج منطبق مقید شده‌اند، نه جابه‌جایی مکان‌نما در متن جستجو، چرا که این رفتار هنگام پالایش سریع فهرست پرونده‌ها کاربرد بیشتری دارد. اگر ترجیح می‌دهید این کلیدها به جای آن متن جستجو را ویرایش کنند (همانند یک ورودی متنی معمولی)، می‌توانید آن‌ها را در choose-files.conf به یکی از کنش‌های زیر مقید کنید که فشردن کلید را به ویرایشگر متن جستجو ارسال می‌کند:

به عنوان مثال، برای اینکه کلیدهای جهت‌نما، Home و End به جای پیمایش فهرست نتایج، متن جستجو را ویرایش کنند:

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

توجه داشته باشید که Up، Down و سایر کلیدهایی که در بالا ذکر نشده‌اند، حتی پس از اعمال بازتعریف‌های فوق همچنان برای پیمایش فهرست نتایج قابل استفاده هستند. همچنین توجه داشته باشید که هر کلیدی که به هیچ کنشی مقید نشده باشد به طور خودکار به ویرایشگر متن جستجو هدایت می‌شود؛ به همین دلیل کلیدهایی نظیر Backspace، Delete، Ctrl+K، Ctrl+W و غیره از قبل متن جستجو را بدون نیاز به هیچ‌یک از کنش‌های بالا ویرایش می‌کنند.

پیکربندی (CONFIGURATION)

می‌توانید جنبه‌های گوناگون عملکرد کیتن را با ایجاد یک choose-files.conf در پوشه پیکربندی kitty خود %<#confloc> پیکربندی کنید. برای دستورالعمل‌های پیکربندی پشتیبانی‌شده به موارد زیر مراجعه کنید.

پویش سیستم پرونده (Filesystem scanning)

show_hidden last

نمایش یا عدم نمایش پرونده‌های پنهان. مقدار پیش‌فرض last به معنای به‌خاطرسپاری آخرین مقدار استفاده‌شده است. این تنظیم را می‌توان در داخل برنامه تغییر وضعیت داد (toggle).

sort_by_last_modified last

مرتب‌سازی فهرست ورودی‌ها بر اساس آخرین تاریخ تغییر، به جای نام. توجه داشته باشید که مرتب‌سازی فقط پیش از وارد کردن هرگونه عبارت جستجو اعمال می‌شود. به محض وارد شدن عبارت، ورودی‌ها بر اساس امتیاز تطابق مرتب می‌شوند. مقدار پیش‌فرض last به معنای به‌خاطرسپاری آخرین مقدار استفاده‌شده است. این تنظیم را می‌توان در داخل برنامه تغییر وضعیت داد.

respect_ignores last

رعایت یا عدم رعایت پرونده‌های gitignore. و ignore. و تنظیم ignore. مقدار پیش‌فرض last به معنای به‌خاطرسپاری آخرین مقدار استفاده‌شده است. این تنظیم را می‌توان در داخل برنامه تغییر وضعیت داد.

یک الگوی نادیده‌گیری برای نادیده گرفتن پرونده‌های منطبق. از ساختار مشابه پرونده‌های .gitignore استفاده می‌کند (به man gitignore مراجعه کنید). الگوهای مقید (Anchored) با توجه به هر دایرکتوری که در حال حاضر نمایش داده می‌شود مطابقت داده می‌شوند. برای استفاده از چندین الگو می‌توان این گزینه را چندین بار مشخص کرد. توجه داشته باشید که هر الگو باید در برابر تک‌تک پرونده‌ها بررسی شود، بنابراین در استفاده از آن صرفه‌جویی کنید.

ظاهر (Appearance)

show_preview last

نمایش یا عدم نمایش پیش‌نمایش پرونده/دایرکتوری جاری. مقدار پیش‌فرض last به معنای به‌خاطرسپاری آخرین مقدار استفاده‌شده است. این تنظیم را می‌توان در داخل برنامه تغییر وضعیت داد.

pygments_style default

طرح‌واره رنگی pygments برای برجسته‌سازی نحوی (syntax highlighting) پیش‌نمایش پرونده‌ها. برای فهرست طرح‌واره‌ها به سبک‌های درونی pygments %https://pygments.org/styles مراجعه کنید. این گزینه رنگ‌های مورد استفاده برای طرح‌واره‌های روشن را تنظیم می‌کند؛ از dark_pygments_style برای تغییر رنگ‌ها در طرح‌واره‌های تیره استفاده کنید.

dark_pygments_style github-dark

طرح‌واره رنگی pygments برای برجسته‌سازی نحوی با رنگ‌های تیره. برای فهرست طرح‌واره‌ها به سبک‌های درونی pygments %https://pygments.org/styles مراجعه کنید. این گزینه رنگ‌های مورد استفاده برای طرح‌واره‌های تیره را تنظیم می‌کند؛ از pygments_style برای تغییر رنگ‌ها در طرح‌واره‌های روشن استفاده کنید.

cache_size 0.5

حداکثر اندازه حافظه موقت (کش) دیسک بر حسب گیگابایت برای پیش‌نمایش‌ها. مقادیر صفر یا منفی به معنای بدون محدودیت است.

syntax_aliases pyj:py pyi:py recipe:py

نام‌های مستعار پسوند پرونده برای برجسته‌سازی نحوی. به عنوان مثال، برای برجسته‌سازی نحوی file.xyz همانند file.abc از تنظیم xyz:abc استفاده کنید. چندین نام مستعار باید با فاصله جدا شوند.

video_preview width=480 fps=10 duration=5

کنترل نحوه نمونه‌برداری از ویدیوها برای پیش‌نمایش. گزینه width اندازه بندانگشتی تولیدشده از ویدیو را کنترل می‌کند. گزینه duration مشخص می‌کند که بندانگشتی تولیدشده چند ثانیه پخش شود. توجه داشته باشید که هنگام تغییر این مقادیر باید از فلگ --clear-cache نیز استفاده کنید، در غیر این صورت روی پیش‌نمایش‌هایی که از قبل کش شده‌اند اعمال نخواهد شد.

مشخص کردن یک برنامه دلخواه به عنوان تولیدکننده پیش‌نمایش. ساختار دستوری به صورت زیر است:

pattern program arguments...

در اینجا، pattern می‌تواند برای تطابق نام پرونده‌ها یا انواع MIME استفاده شود. به عنوان مثال: name:*.doc پرونده‌های دارای پسوند .doc را تطبیق می‌دهد. به طور مشابه، mime:image/* تمام پرونده‌های تصویری را تطبیق می‌دهد. گزینه program می‌تواند هر برنامه اجرایی موجود در PATH باشد. این برنامه با آرگومان‌های داده‌شده اجرا خواهد شد. آخرین آرگومان مسیر پرونده‌ای خواهد بود که باید پیش‌نمایش برای آن تولید شود.

این گزینه را می‌توان چندین بار مشخص کرد تا پیش‌نمایش‌گرهای مختلف برای انواع مختلف پرونده‌ها تنظیم شوند. توجه داشته باشید که پیش‌نمایش‌گرهای مشخص‌شده با این گزینه بر پیش‌نمایش‌گرهای درونی اولویت دارند.

دستور باید داده‌های پیش‌نمایش را به عنوان یک شیء JSON در STDOUT خروجی دهد:

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

خطوط می‌توانند شامل کدهای گریز قالب‌بندی SGR باشند و به همان صورت در بالای پانل پیش‌نمایش نمایش داده خواهند شد. تصویر اختیاری است و باید در یکی از قالب‌های JPEG، PNG، GIF، WEBP یا APNG باشد.

کلیدهای میان‌بر (Keyboard shortcuts)

map esc quit
map ctrl+c quit

map enter accept

map shift+enter select

هنگام انتخاب چندین پرونده، این کار پرونده جاری را به فهرست پرونده‌های انتخاب‌شده اضافه می‌کند. همچنین می‌توانید با نگه داشتن کلید Ctrl و کلیک روی یک پرونده، وضعیت انتخاب آن را تغییر دهید. به طور مشابه، می‌توان کلید Alt را نگه داشت و با کلیک، دامنه پرونده‌های انتخابی را گسترش داد.

map ctrl+enter typename

تایپ یک نام/مسیر پرونده به جای پالایش فهرست پرونده‌های موجود. هنگام تعیین نام پرونده یا دایرکتوری برای ذخیره‌سازی که هنوز وجود ندارد مفید است. هنگام انتخاب دایرکتوری‌های موجود، دایرکتوری‌ای را که محتویات آن در حال حاضر نمایش داده می‌شود به عنوان انتخاب می‌پذیرد. هنگام انتخاب پرونده‌ها برای باز کردن (به جای ذخیره) کارایی ندارد.

map alt+enter modifyname

ویرایش نام یک پرونده موجود و انتخاب آن برای ذخیره‌سازی. هنگام تعیین نام پرونده یا دایرکتوری برای ذخیره‌سازی که هنوز وجود ندارد اما بر اساس نام یک پرونده موجود است، مفید خواهد بود. هنگام انتخاب پرونده‌ها برای باز کردن (به جای ذخیره) کارایی ندارد.

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 --allow-fallback=shifted,ascii ctrl+t cd /tmp

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

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

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

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

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

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

کد منبع choose_files (Source code for choose_files)

کد منبع این کیتن در گیت‌هاب %https://github.com/kovidgoyal/kitty/tree/master/kittens/choose_files در دسترس است.

رابط خط فرمان (Command line interface)

kitten choose_files [گزینه‌ها] [دایرکتوری شروع برای انتخاب پرونده‌ها]

انتخاب سریع یک یا چند پرونده با استفاده از جستجوی فازی، تنها با تایپ چند نویسه از نام پرونده. مرور پرونده‌های منطبق با استفاده از کلیدهای جهت‌نما برای پیمایش و فشردن Enter برای انتخاب. کلید Tab می‌تواند برای رفتن به یک زیرپوشه استفاده شود. برای جزئیات کامل به اسناد برخط %<> مراجعه کنید.

نویسنده (AUTHOR)

Kovid Goyal

حق نشر (COPYRIGHT)

2026, Kovid Goyal