.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "FISH-PROMPT-TUTORIAL" "1" "Sep 07, 2026" "4.9" "fish-shell"
.SH "نام (NAME)"
fish\-prompt\-tutorial \- راهنمای گام‌به‌گام نوشتن اعلان (پرامپت) سفارشی در fish
.SH "توضیحات (DESCRIPTION)"
.sp
\fBهشدار:\fP
.INDENT 0.0
.INDENT 3.5
این سند از قالب‌بندی برای نمایش شکل ظاهری اعلان استفاده می‌کند. اگر این صفحه را در صفحه راهنما (man page) می‌بینید، احتمالاً ترجیح می‌دهید نسخه HTML آن را مشاهده کنید. برای مشاهده آن در مرورگر وب، دستور \fBhelp custom\-prompt\fP را اجرا کنید.
.UNINDENT
.UNINDENT
.sp
پوسته fish تعدادی اعلان آماده به همراه دارد که می‌توانید با دستور \fBfish_config\fP آن‌ها را مشاهده کنید، و بسیاری از کاربران نیز اعلان‌های خود را به صورت آنلاین به اشتراک گذاشته‌اند.
.sp
با این حال، شما می‌توانید اعلان اختصاصی خود را بنویسید یا یک اعلان موجود را سفارشی‌سازی کنید. این یک روش عالی برای آشنایی و عادت به زبان اسکریپت‌نویسی fish است.
.sp
برخلاف سایر پوسته‌ها، اعلان در fish با اجرای یک تابع ساخته می‌شود \- تابع \fBfish_prompt\fP. یا دقیق‌تر بگوییم، سه تابع:
.INDENT 0.0
.IP \(bu 2
\fBfish_prompt\fP که تابع اصلی اعلان است.
.IP \(bu 2
\fBfish_right_prompt\fP که در سمت راست ترمینال نمایش داده می‌شود.
.IP \(bu 2
\fBfish_mode_prompt\fP که در صورت استفاده از حالت vi نمایش داده می‌شود.
.UNINDENT
.sp
این توابع اجرا می‌شوند و هر آنچه در خروجی چاپ کنند، به عنوان اعلان نمایش داده می‌شود (به جز یک نویسه خط جدید پایانی).
.sp
اگر متغیرهای محیطی \fBSHELL_PROMPT_PREFIX\fP یا \fBSHELL_PROMPT_SUFFIX\fP تنظیم شده باشند، به طور خودکار به ابتدا و انتهای اعلان سمت چپ اضافه می‌شوند.
.sp
در اینجا، ما به نوشتن یک \fBfish_prompt\fP ساده می‌پردازیم.
.SH "نخستین اعلان ما (OUR FIRST PROMPT)"
.sp
بیایید به یک مثال بسیار ساده نگاه کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    echo $PWD \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
این تابع، دایرکتوری کاری جاری (\fBPWD\fP) و یک نماد \fB>\fP را برای نشان دادن انتهای اعلان چاپ می‌کند. نماد \fB>\fP درون کوتیشن قرار گرفته است زیرا در غیر این صورت به معنای تغییرمسیر (redirection) خواهد بود.
.sp
از آنجا که از \fBecho\fP استفاده کرده‌ایم، میان این دو فاصله اضافه می‌شود، بنابراین نتیجه به این شکل خواهد بود (با فرض اینکه \fB_\fP مکان‌نمای شما باشد):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/home/tutorial >_
.EE
.UNINDENT
.UNINDENT
.SH "قالب‌بندی (FORMATTING)"
.sp
دستور \fBecho\fP میان آرگومان‌های خود فاصله می‌گذارد. اگر مایل به وجود این فاصله‌ها نیستید، می‌توانید از \fBstring join\fP به شکل زیر استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- $PWD \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
نماد \fB\-\-\fP به دستور \fBstring\fP اعلام می‌کند که هیچ گزینه‌ای پس از آن نمی‌آید، تا در صورتی که این اعلان را با مقداری که با \fB\-\fP آغاز می‌شود گسترش دهیم، تداخلی رخ ندهد.
.sp
روش‌های دیگری نیز برای حذف فاصله وجود دارد، از جمله \fBecho \-s\fP و \fBprintf\fP.
.SH "افزودن رنگ (ADDING COLOR)"
.sp
این اعلان کاربردی است، اما کمی خسته‌کننده به نظر می‌رسد. می‌توانیم مقداری رنگ به آن اضافه کنیم.
.sp
خوشبختانه، fish دستور \fBset_color\fP را ارائه می‌دهد، بنابراین می‌توانید بنویسید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo (set_color red)foo
.EE
.UNINDENT
.UNINDENT
.sp
دستور \fBset_color\fP همچنین از رنگ‌های RGB مانند \fBset_color 23b455\fP و سایر گزینه‌های قالب‌بندی از جمله درشت (bold) و کج (italic) پشتیبانی می‌کند.
.sp
بنابراین، با در نظر گرفتن اعلان قبلی و افزودن رنگ به آن:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- (set_color green) $PWD (set_color \-\-reset) \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
گزینه \(dq\-\-reset\(dq به ترمینال اعلام می‌کند که به گزینه‌های قالب‌بندی پیش‌فرض خود بازگردد.
.sp
دستور \fBset_color\fP با تولید یک توالی گریز (escape sequence) کار می‌کند؛ رشته متنی خاصی که ترمینال‌ها آن را به عنوان دستورالعمل تفسیر می‌کنند \- برای مثال، جهت تغییر رنگ. بنابراین دستور \fBset_color red\fP اثری مشابه زیر ایجاد می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo \ee\e[31m
.EE
.UNINDENT
.UNINDENT
.sp
اگرچه می‌توانید توالی‌های گریز را به صورت دستی بنویسید، اما استفاده از \fBset_color\fP بسیار آسان‌تر است.
.SH "کوتاه‌سازی دایرکتوری کاری (SHORTENING THE WORKING DIRECTORY)"
.sp
این وضعیت مناسب است، اما متغیر \fBPWD\fP ممکن است کمی طولانی شود، و معمولاً ما فقط به چند دایرکتوری آخر علاقه‌مند هستیم. می‌توانیم این مسیر را با تابع کمکی \fBprompt_pwd\fP کوتاه کنیم که دایرکتوری کاری خلاصه‌شده را به ما می‌دهد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- (set_color green) (prompt_pwd) (set_color \-\-reset) \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
تابع \fBprompt_pwd\fP گزینه‌هایی برای کنترل میزان کوتاه‌سازی دریافت می‌کند. برای نمونه، اگر بخواهیم دو دایرکتوری آخر نمایش داده شوند، از \fBprompt_pwd \-\-full\-length\-dirs 2\fP استفاده می‌کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- (set_color green) (prompt_pwd \-\-full\-length\-dirs 2) (set_color \-\-reset) \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
با دایرکتوری جاری \(dq/home/tutorial/Music/Lena Raine/Oneknowing\(dq، این دستور عبارت زیر را چاپ می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
~/M/Lena Raine/Oneknowing>_
.EE
.UNINDENT
.UNINDENT
.SH "وضعیت خروج (STATUS)"
.sp
یکی از اطلاعات مهمی که هر دستور بازمی‌گرداند، وضعیت خروج (\fBstatus\fP) است. این مقدار یک عدد صحیح از 0 تا 255 است و معمولاً به عنوان کد خطا استفاده می‌شود \- مقدار 0 در صورتی که دستور با موفقیت به پایان رسیده باشد، یا عددی از 1 تا 255 در صورت بروز خطا.
.sp
نمایش این مقدار در اعلان مفید است، اما نشان دادن آن هنگامی که 0 است بیهوده و اضافه به نظر می‌رسد.
.sp
پیش از هر چیز، از آنجا که هر دستور (به جز \fBset\fP) وضعیت را تغییر می‌دهد، لازم است آن را به عنوان نخستین کار در اعلان برای استفاده‌های بعدی ذخیره کنید. از یک متغیر محلی (local) استفاده کنید تا به تابع اعلان شما محدود بماند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
set \-l last_status $status
.EE
.UNINDENT
.UNINDENT
.sp
سپس می‌توانید در صورت غیرصفر بودن، یک رشته متنی را مقداردهی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# تنها در صورتی که وضعیت صفر نباشد نمایش داده شود
set \-l stat
if test $last_status \-ne 0
    set stat (set_color red)\(dq[$last_status]\(dq(set_color \-\-reset)
end
.EE
.UNINDENT
.UNINDENT
.sp
و برای چاپ آن، آن را به \fBstring join\fP اضافه می‌کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
string join \(aq\(aq \-\- (set_color green) (prompt_pwd) (set_color \-\-reset) $stat \(aq>\(aq
.EE
.UNINDENT
.UNINDENT
.sp
اگر مقدار \fB$last_status\fP برابر 0 باشد، متغیر \fB$stat\fP خالی خواهد بود و در نتیجه اصلاً نمایش داده نخواهد شد.
.sp
بنابراین تمام اعلان ما اکنون به این شکل درمی‌آید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    set \-l last_status $status
    # تنها در صورتی که وضعیت صفر نباشد نمایش داده شود
    set \-l stat
    if test $last_status \-ne 0
        set stat (set_color red)\(dq[$last_status]\(dq(set_color \-\-reset)
    end

    string join \(aq\(aq \-\- (set_color green) (prompt_pwd) (set_color \-\-reset) $stat \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
و پس از اجرای دستور \fBfalse\fP (که مقدار 1 را برمی‌گرداند)، ظاهر آن به شکل زیر خواهد بود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
~/M/L/Oneknowing>false
~/M/L/Oneknowing[1]>_
.EE
.UNINDENT
.UNINDENT
.SH "اعلان گذرا (TRANSIENT PROMPT)"
.sp
برای فعال‌سازی قابلیت اعلان گذرا (transient prompt)، متغیر \fBfish_transient_prompt\fP را روی 1 تنظیم کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
set \-g fish_transient_prompt 1
.EE
.UNINDENT
.UNINDENT
.sp
با این تنظیم، fish پیش از اجرای هر خط فرمان، توابع اعلان را با آرگومان \fB\-\-final\-rendering\fP دوباره اجرا می‌کند.
بنابراین می‌توانید از آن برای خلوت کردن و مرتب‌سازی اعلان‌های قبلی خود استفاده کنید. برای مثال، اگر بخواهید هنگام پیمایش به بالا فقط نام دایرکتوری جاری دیده شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    set \-l last_status $status
    set \-l stat
    set \-l pwd
    # بررسی اینکه آیا اعلان گذرا یا نهایی است
    if contains \-\- \-\-final\-rendering $argv
        set pwd (path basename $PWD)
    else
        set pwd (prompt_pwd)
        # تنها در صورتی که وضعیت صفر نباشد نمایش داده شود
        if test $last_status \-ne 0
            set stat (set_color red)\(dq[$last_status]\(dq(set_color \-\-reset)
        end
    end

    string join \(aq\(aq \-\- (set_color green) $pwd (set_color \-\-reset) $stat \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
اکنون اجرای دو دستور در یک دایرکتوری می‌تواند به چنین صفحه‌ای منجر شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Oneknowing>false
~/M/L/Oneknowing[1]>_
.EE
.UNINDENT
.UNINDENT
.SH "ذخیره اعلان (SAVE THE PROMPT)"
.sp
هنگامی که از اعلان خود رضایت داشتید، می‌توانید آن را با دستور \fBfuncsave fish_prompt\fP ذخیره کنید (رجوع کنید به \fBfuncsave\fP \- ذخیره تعریف یک تابع در دایرکتوری بارگذاری خودکار کاربر) یا خودتان آن را در مسیر ~/.config/fish/functions/fish_prompt.fish بنویسید.
.sp
اگر می‌خواهید دوباره آن را ویرایش کنید، آن فایل را باز کرده یا از دستور \fBfunced fish_prompt\fP استفاده کنید (رجوع کنید به \fBfunced\fP \- ویرایش تعاملی یک تابع).
.SH "گام‌های بعدی (?WHERE TO GO FROM HERE)"
.sp
ما اکنون یک اعلان ساده اما کاربردی و کارآمد ساخته‌ایم، اما بی‌تردید کارهای بیشتری می‌توان انجام داد.
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B پوسته fish توابع کمکی بیشتری ارائه می‌دهد:
.INDENT 7.0
.IP \(bu 2
\fBprompt_login\fP برای شرح کاربر/نام میزبان/کانتینر یا \fBprompt_hostname\fP برای شرح صرفاً نام میزبان
.IP \(bu 2
\fBfish_is_root_user\fP برای کمک به تغییر نماد مربوط به کاربر ریشه (root).
.IP \(bu 2
\fBfish_vcs_prompt\fP برای نمایش اطلاعات سیستم کنترل نسخه (یا \fBfish_git_prompt\fP / \fBfish_hg_prompt\fP / \fBfish_svn_prompt\fP برای محدود کردن به سیستم‌های خاص)
.UNINDENT
.UNINDENT
.IP \(bu 2
می‌توانید با تغییر \fBfish_right_prompt\fP یک اعلان سمت راست، یا با تغییر \fBfish_mode_prompt\fP اعلان حالت vi اضافه کنید.
.IP \(bu 2
.INDENT 2.0
.TP
.B برخی اعلان‌ها دارای ویژگی‌های جالب یا پیشرفته‌ای هستند:
.INDENT 7.0
.IP \(bu 2
افزودن زمان چاپ شدن اعلان
.IP \(bu 2
نمایش یکپارچه‌سازی‌های گوناگون مانند محیط مجازی پایتون (venv)
.IP \(bu 2
رنگ‌آمیزی متفاوت بخش‌های مختلف.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
می‌توانید برای ایده گرفتن، به اعلان‌های نمونه fish نگاهی بیندازید. دستور \fBfish_config\fP را اجرا کنید، اعلان دلخواه خود را بیابید و آن را برگزینید. برای مثال:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
fish_config prompt show # <\- تمام اعلان‌های نمونه را نشان می‌دهد
fish_config prompt choose disco # <\- اعلان disco را برای این نشست برمی‌گزیند
funced fish_prompt # <\- اعلان fish_prompt را در ویرایشگر شما باز می‌کند و پس از خروج آن را مجدداً بارگذاری می‌نماید
.EE
.UNINDENT
.UNINDENT
.SH "نویسنده (AUTHOR)"
توسعه‌دهندگان fish-shell
.SH "حق نشر (COPYRIGHT)"
توسعه‌دهندگان fish-shell
.\" End of generated man page.