.TH RG 1 2026-07-15 "15.2.0" "User Commands" . . .SH "نام (NAME)" rg \- جستجوی بازگشتی در دایرکتوری جاری برای خطوط منطبق با یک الگو . . .SH "خلاصه دستور (SYNOPSIS)" .\" I considered using GNU troff's .SY and .YS "synopsis" macros here, but it .\" looks like they aren't portable. Specifically, they don't appear to be in .\" BSD's mdoc used on macOS. .sp \fBrg\fP [\fIOPTIONS\fP] \fIPATTERN\fP [\fIPATH\fP...] .sp \fBrg\fP [\fIOPTIONS\fP] \fB\-e\fP \fIPATTERN\fP... [\fIPATH\fP...] .sp \fBrg\fP [\fIOPTIONS\fP] \fB\-f\fP \fIPATTERNFILE\fP... [\fIPATH\fP...] .sp \fBrg\fP [\fIOPTIONS\fP] \fB\-\-files\fP [\fIPATH\fP...] .sp \fBrg\fP [\fIOPTIONS\fP] \fB\-\-type\-list\fP .sp \fIcommand\fP | \fBrg\fP [\fIOPTIONS\fP] \fIPATTERN\fP .sp \fBrg\fP [\fIOPTIONS\fP] \fB\-\-help\fP .sp \fBrg\fP [\fIOPTIONS\fP] \fB\-\-version\fP . . .SH "توضیحات (DESCRIPTION)" ابزار ripgrep (rg) دایرکتوری جاری را به صورت بازگشتی برای یافتن یک الگوی عبارت باقاعده (regex) جستجو می‌کند. به طور پیش‌فرض، ripgrep به \fB.gitignore\fP شما احترام می‌گذارد و فایل‌ها و دایرکتوری‌های پنهان و همچنین فایل‌های دودویی (binary) را به طور خودکار نادیده می‌گیرد. .sp موتور عبارت باقاعده پیش‌فرض ripgrep از خودکاره متناهی (finite automata) استفاده می‌کند و زمان جستجوی خطی را تضمین می‌نماید. به همین دلیل، ویژگی‌هایی مانند ارجاع به عقب (backreferences) و بررسی پیرامونی دلخواه (look-around) پشتیبانی نمی‌شوند. با این حال، اگر ripgrep به همراه PCRE2 ساخته شده باشد، پرچم \fB\-P/\-\-pcre2\fP می‌تواند برای فعال‌سازی ارجاع به عقب و بررسی پیرامونی استفاده شود. .sp ابزار ripgrep از فایل‌های پیکربندی پشتیبانی می‌کند. متغیر محیطی \fBRIPGREP_CONFIG_PATH\fP را روی مسیر یک فایل پیکربندی تنظیم کنید. این فایل می‌تواند در هر خط یک آرگومان شل را مشخص کند. خطوطی که با \fB#\fP شروع می‌شوند نادیده گرفته خواهند شد. برای جزئیات بیشتر، بخش \fBCONFIGURATION FILES\fP را در ادامه ببینید. .sp ابزار ripgrep به طور خودکار قابل خواندن بودن stdin را تشخیص داده و stdin را برای یافتن الگوی regex جستجو می‌کند؛ مانند \fBls | rg foo\fP. در برخی محیط‌ها، ممکن است stdin وجود داشته باشد در حالی که نباید باشد. برای خاموش کردن تشخیص خودکار stdin، می‌توان دایرکتوری مورد نظر برای جستجو را صراحتاً مشخص کرد؛ مانند \fBrg foo ./\fP. .sp همانند ابزارهای دیگری نظیر \fBls\fP، ابزار ripgrep نیز خروجی خود را بر اساس اینکه آیا stdout به یک tty متصل است یا خیر تغییر می‌دهد. به طور پیش‌فرض، هنگام چاپ روی یک tty، ابزار ripgrep رنگ‌ها، شماره خطوط و قالب سربرگی را فعال می‌کند که مسیر هر فایل منطبق را تنها یک‌بار فهرست می‌کند، نه یک‌بار به ازای هر خط منطبق. .sp نکته: برای غیرفعال کردن تمام فیلترهای هوشمند و شبیه‌تر کردن رفتار ripgrep به grep سنتی، از \fBrg -uuu\fP استفاده کنید. . . .SH "نحو عبارت باقاعده (REGEX SYNTAX)" ابزار ripgrep به طور پیش‌فرض از موتور عبارت باقاعده زبان Rust استفاده می‌کند که نحو آن در اینجا مستند شده است: \fIhttps://docs.rs/regex/1.*/regex/#syntax\fP .sp ابزار ripgrep از عبارات باقاعده بایت‌محور استفاده می‌کند که دارای مستندات تکمیلی است: \fIhttps://docs.rs/regex/1.*/regex/bytes/index.html#syntax\fP .sp به عنوان یک تقریب کلی، ripgrep از عبارات باقاعده شبیه به Perl بدون بررسی پیرامونی (look-around) یا ارجاع به عقب (backreferences) استفاده می‌کند. این امر آن‌ها را بسیار شبیه به عبارات باقاعده گسترش‌یافته (ERE) پشتیبانی‌شده توسط *egrep* می‌کند، اما با چند ویژگی اضافی مانند رده‌های نویسه‌ای یونیکد. .sp اگر از ripgrep به همراه پرچم \fB\-P/\-\-pcre2\fP استفاده می‌کنید، لطفاً برای مستندات مربوط به نحو پشتیبانی‌شده به \fIhttps://www.pcre.org\fP یا صفحات راهنمای (man) بسته PCRE2 مراجعه کنید. . . .SH "آرگومان‌های موضعی (POSITIONAL ARGUMENTS)" .TP 12 \fIPATTERN\fP یک عبارت باقاعده که برای جستجو استفاده می‌شود. برای تطبیق با الگویی که با خط تیره شروع می‌شود، از گزینه \fB\-e/\-\-regexp\fP استفاده کنید. .TP 12 \fIPATH\fP یک فایل یا دایرکتوری برای جستجو. دایرکتوری‌ها به صورت بازگشتی جستجو می‌شوند. مسیرهای فایلی که صراحتاً در خط فرمان مشخص شده‌اند، بر قواعد تطبیق الگو (glob) و نادیده‌گیری (ignore) اولویت دارند. . . .SH "گزینه‌ها (OPTIONS)" این بخش تمامی پرچم‌هایی را که ripgrep می‌پذیرد مستند می‌کند. پرچم‌ها بر اساس عملکردشان در دسته‌بندی‌های زیر گروه‌بندی شده‌اند. .sp توجه داشته باشید که بسیاری از گزینه‌ها می‌توانند فعال یا غیرفعال شوند. در برخی موارد، آن پرچم‌ها صراحتاً در ادامه فهرست نشده‌اند. برای مثال، پرچم \fB\-\-column\fP (فهرست‌شده در زیر) شماره ستون‌ها را در خروجی ripgrep فعال می‌کند، اما پرچم \fB\-\-no\-column\fP (که در زیر نیامده است) آن‌ها را غیرفعال می‌سازد. حالت معکوس نیز وجود دارد. به عنوان مثال، پرچم \fB\-\-no\-ignore\fP (فهرست‌شده در زیر) منطق \fBgitignore\fP در ripgrep را غیرفعال می‌کند، اما پرچم \fB\-\-ignore\fP (که در زیر نیامده است) آن را فعال می‌سازد. این پرچم‌ها برای لغو تنظیمات یک فایل پیکربندی ripgrep (یا نام مستعار) در خط فرمان مفید هستند. مستندات هر پرچم مشخص می‌کند که آیا یک پرچم معکوس وجود دارد یا خیر. در همه موارد، آخرین پرچم مشخص‌شده اولویت خواهد داشت. . .SS "گزینه‌های ورودی (INPUT OPTIONS)" \fB\-e\fP \fIPATTERN\fP, \fB\-\-regexp\fP=\fIPATTERN\fP .RS 4 الگویی برای جستجو. این گزینه می‌تواند چندین بار مشخص شود، که در این صورت تمامی الگوهای داده شده، علاوه بر هر الگویی که از طریق \fB\-f/\-\-file\fP ارائه شده باشد، جستجو می‌شوند. خطوطی که حداقل با یکی از الگوهای ارائه‌شده مطابقت داشته باشند چاپ می‌شوند. این پرچم همچنین می‌تواند هنگام جستجوی الگوهایی که با خط تیره شروع می‌شوند استفاده شود. .sp برای مثال، جهت جستجوی عبارت متنی مستقیم \fB\-foo\fP: .sp .EX rg \-e \-foo .EE .sp همچنین می‌توانید از جداکننده ویژه \fB\-\-\fP استفاده کنید تا نشان دهید پرچم دیگری ارائه نخواهد شد. به طور مشخص، دستور زیر معادل دستور بالا است: .sp .EX rg \-\- \-foo .EE .sp هنگامی که \fB\-f/\-\-file\fP یا \fB\-e/\-\-regexp\fP استفاده شود، ripgrep تمامی آرگومان‌های موضعی را به عنوان فایل‌ها یا دایرکتوری‌هایی برای جستجو در نظر می‌گیرد. .RE .sp \fB\-f\fP \fIPATTERNFILE\fP, \fB\-\-file\fP=\fIPATTERNFILE\fP .RS 4 جستجوی الگوها از فایل داده‌شده، با یک الگو در هر خط. هنگامی که از این پرچم چندین بار یا در ترکیب با پرچم \fB\-e/\-\-regexp\fP استفاده شود، تمامی الگوهای ارائه‌شده جستجو می‌شوند. خطوط الگوی خالی با تمام خطوط ورودی مطابقت خواهند داشت، و نویسه خط جدید (newline) جزئی از الگو محسوب نمی‌شود. .sp یک خط تنها در صورتی چاپ می‌شود که حداقل با یکی از الگوها تطبیق یابد. .sp هنگامی که \fIPATTERNFILE\fP برابر با \fB-\fP باشد، الگوها از \fBstdin\fP خوانده خواهند شد. .sp هنگامی که \fB\-f/\-\-file\fP یا \fB\-e/\-\-regexp\fP استفاده شود، ripgrep تمامی آرگومان‌های موضعی را به عنوان فایل‌ها یا دایرکتوری‌هایی برای جستجو در نظر می‌گیرد. .RE .sp \fB\-\-pre\fP=\fICOMMAND\fP .RS 4 به ازای هر \fIPATH\fP ورودی، این پرچم موجب می‌شود ripgrep به جای محتوای \fIPATH\fP، خروجی استاندارد \fICOMMAND\fP \fIPATH\fP را جستجو کند. این گزینه انتظار دارد برنامه \fICOMMAND\fP یا یک مسیر کامل باشد یا در متغیر محیطی \fBPATH\fP شما در دسترس باشد. ارسال یک رشته خالی برای \fICOMMAND\fP یا استفاده از پرچم \fB\-\-no\-pre\fP این رفتار را غیرفعال می‌کند. .sp .TP 12 \fBهشدار (WARNING)\fP هنگامی که این پرچم تنظیم شود، ripgrep بدون قید و شرط برای هر فایلی که جستجو می‌شود یک فرآیند (process) ایجاد می‌کند. بنابراین اگر به انعطاف‌پذیری ارائه‌شده توسط این پرچم نیازی نداشته باشید، این امر می‌تواند افت کارایی بسیار زیادی را تحمیل کند. یک راهکار ممکن برای کاهش این مشکل، استفاده از پرچم \fB\-\-pre\-glob\fP برای محدود کردن فایل‌هایی است که پیش‌پردازنده روی آن‌ها اجرا می‌شود. .PP هنگامی که ripgrep در حال جستجوی stdin است، پیش‌پردازنده اجرا نمی‌شود. .sp هنگام جستجو در میان مجموعه‌ای از فایل‌ها که ممکن است به یکی از چندین پیش‌پردازنده نیاز داشته باشند، \fICOMMAND\fP باید یک برنامه پوششی (wrapper) باشد که ابتدا \fIPATH\fP را بر اساس شماره‌های جادویی (magic numbers)/محتوا یا بر اساس نام \fIPATH\fP دسته‌بندی کرده و سپس آن را به پیش‌پردازنده مناسب ارسال کند. همچنین ورودی استاندارد هر \fICOMMAND\fP برای سهولت به \fIPATH\fP متصل است. .sp برای مثال، یک اسکریپت شل برای \fICOMMAND\fP ممکن است به این شکل باشد: .sp .EX case "$1" in *.pdf) exec pdftotext "$1" - ;; *) case $(file "$1") in *Zstandard*) exec pzstd -cdq ;; *) exec cat ;; esac ;; esac .EE .sp اسکریپت بالا از \fBpdftotext\fP برای تبدیل یک فایل PDF به متن ساده استفاده می‌کند. برای سایر فایل‌ها، اسکریپت از ابزار \fBfile\fP برای تشخیص نوع فایل بر اساس محتوای آن بهره می‌برد. اگر فایلی فشرده‌شده در قالب Zstandard باشد، آنگاه از \fBpzstd\fP برای خارج کردن محتوا از حالت فشرده به سمت stdout استفاده می‌شود. .sp این گزینه بر پرچم \fB\-z/\-\-search\-zip\fP اولویت دارد. .RE .sp \fB\-\-pre\-glob\fP=\fIGLOB\fP .RS 4 این پرچم در ارتباط با پرچم \fB\-\-pre\fP کار می‌کند. به طور مشخص، هنگامی که یک یا چند پرچم \fB\-\-pre\-glob\fP مشخص شوند، تنها فایل‌هایی که با مجموعه الگوهای تطبیق (globs) داده‌شده مطابقت داشته باشند به دستوری که توسط پرچم \fB\-\-pre\fP تعیین شده سپرده می‌شوند. هر فایلی که مطابقت نداشته باشد بدون استفاده از دستور پیش‌پردازنده جستجو خواهد شد. .sp این پرچم هنگام جستجوی فایل‌های متعدد به همراه پرچم \fB\-\-pre\fP مفید است؛ بدین صورت که امکان جلوگیری از ایجاد سربار فرآیند را برای فایل‌هایی که نیازی به پیش‌پردازش ندارند فراهم می‌سازد. برای مثال، با در نظر گرفتن اسکریپت شل زیر با نام \fIpre-pdftotext\fP: .sp .EX #!/bin/sh pdftotext "$1" - .EE .sp می‌توان از \fB\-\-pre\fP \fIpre-pdftotext\fP \fB\-\-pre\-glob\fP '\fI*.pdf\fP' استفاده کرد تا ripgrep دستور \fIpre-pdftotext\fP را فقط روی فایل‌های دارای پسوند \fI.pdf\fP اجرا کند. .sp می‌توان از چندین پرچم \fB\-\-pre\-glob\fP استفاده کرد. قوانین تطبیق الگو (globbing) با الگوهای \fBgitignore\fP یکسان است. برای مستثنی کردن یک الگو، یک نویسه \fB!\fP قبل از آن قرار دهید. .sp اگر از پرچم \fB\-\-pre\fP استفاده نشود، این پرچم هیچ اثری نخواهد داشت. .RE .sp \fB\-z\fP, \fB\-\-search\-zip\fP .RS 4 این پرچم به ripgrep دستور می‌دهد که در فایل‌های فشرده جستجو کند. در حال حاضر فایل‌های gzip، bzip2، xz، LZ4، LZMA، Brotli و Zstd پشتیبانی می‌شوند. این گزینه انتظار دارد باینری‌های استخراج از حالت فشرده (مانند \fBgzip\fP) در متغیر محیطی \fBPATH\fP شما در دسترس باشند. اگر باینری‌های لازم یافت نشوند، ripgrep به طور پیش‌فرض پیام خطایی صادر نمی‌کند. برای مشاهده اطلاعات بیشتر از پرچم \fB\-\-debug\fP استفاده کنید. .sp توجه داشته باشید که این پرچم باعث نمی‌شود ripgrep قالب‌های آرشیو را مانند ساختار درختی دایرکتوری‌ها جستجو کند. این پرچم تنها سبب می‌شود ripgrep فایل‌های فشرده را تشخیص داده و قبل از جستجوی محتوای آن‌ها همانند هر فایل دیگری، آن‌ها را از حالت فشرده خارج سازد. .sp این گزینه بر پرچم \fB\-\-pre\fP اولویت دارد. .sp این پرچم را می‌توان با \fB\-\-no-search-zip\fP غیرفعال کرد. .RE ..SS "گزینه‌های جستجو (SEARCH OPTIONS)" \fB\-s\fP, \fB\-\-case\-sensitive\fP .RS 4 جستجو را حساس به حروف کوچک و بزرگ انجام می‌دهد. این حالت پیش‌فرض است. .sp این یک گزینه سراسری است که برای تمام الگوهای داده‌شده به ripgrep اعمال می‌شود. الگوهای منفرد همچنان می‌توانند با استفاده از نشانگرهای درون‌خطی regex، به صورت غیرحساس به حروف مطابقت داده شوند. برای مثال، \fB(?i)abc\fP حتی در صورت استفاده از این پرچم، با \fBabc\fP به صورت غیرحساس به حروف مطابقت خواهد داشت. .sp این پرچم، پرچم‌های \fB\-i/\-\-ignore\-case\fP و \fB\-S/\-\-smart\-case\fP را لغو می‌کند. .RE .sp \fB\-\-crlf\fP .RS 4 هنگامی که فعال باشد، ripgrep به‌جای تنها \fB\\n\fP، با CRLF (\fB\\r\\n\fP) به عنوان پایان‌دهنده خط رفتار می‌کند. .sp در اصل، این به لنگرهای خط \fB^\fP و \fB$\fP در الگوهای regex اجازه می‌دهد تا CRLF،‏ CR یا LF را به‌جای صرفاً LF به عنوان پایان‌دهنده خط در نظر بگیرند. توجه داشته باشید که آن‌ها هرگز بین یک CR و یک LF تطبیق داده نمی‌شوند. با CRLF به عنوان یک پایان‌دهنده خط واحد رفتار می‌شود. .sp هنگام استفاده از موتور regex پیش‌فرض، پشتیبانی از CRLF را می‌توان در داخل الگو با پرچم \fBR\fP نیز فعال کرد. برای مثال، \fB(?R:$)\fP دقیقاً پیش از CR یا LF تطبیق می‌یابد، اما هرگز بین CR و LF قرار نمی‌گیرد. .sp این پرچم، \fB\-\-null\-data\fP را لغو می‌کند. .sp این پرچم را می‌توان با \fB\-\-no-crlf\fP غیرفعال کرد. .RE .sp \fB\-\-dfa\-size\-limit\fP=\fINUM+SUFFIX?\fP .RS 4 حد بالای اندازه DFA در موتور regex. حد پیش‌فرض مقداری سخاوتمندانه برای هر الگوی منفرد یا برای الگوهای متعدد و نسبتاً کوچک است. این مقدار تنها باید برای ورودی‌های بسیار بزرگ regex تغییر کند، جایی که در صورت رسیدن به این حد، ممکن است در غیر این صورت از موتور پشتیبان regex (که کندتر است) استفاده شود. .sp قالب ورودی پسوندهای \fBK\fP،‏ \fBM\fP یا \fBG\fP را می‌پذیرد که به ترتیب نشان‌دهنده کیلوبایت، مگابایت و گیگابایت هستند. اگر پسوندی ارائه نشود، ورودی به عنوان بایت در نظر گرفته می‌شود. .RE .sp \fB\-E\fP \fIENCODING\fP, \fB\-\-encoding\fP=\fIENCODING\fP .RS 4 کدگذاری متنی (encoding) را که ripgrep در تمام فایل‌های جستجوشده استفاده خواهد کرد مشخص می‌کند. مقدار پیش‌فرض \fBauto\fP است که باعث می‌شود ripgrep بیشترین تلاش خود را برای تشخیص خودکار کدگذاری بر مبنای هر فایل انجام دهد. تشخیص خودکار در این حالت تنها برای فایل‌هایی اعمال می‌شود که با نشانگر ترتیب بایت (BOM) مربوط به UTF-8 یا UTF-16 آغاز می‌شوند. هیچ تشخیص خودکار دیگری انجام نمی‌شود. همچنین می‌توان \fBnone\fP را تعیین کرد که شناسایی خودکار BOM را کاملاً غیرفعال کرده و همیشه منجر به جستجوی بایت‌های خام می‌شود، از جمله خود BOM در صورت وجود، بدون توجه به کدگذاری آن. .sp سایر مقادیر پشتیبانی‌شده را می‌توان در فهرست برچسب‌ها در اینجا یافت: \fIhttps://encoding.spec.whatwg.org/#concept-encoding-get\fP. .sp برای جزئیات بیشتر درباره کدگذاری و نحوه برخورد ripgrep با آن، \fBGUIDE.md\fP را ببینید. .sp تشخیص کدگذاری که ripgrep استفاده می‌کند را می‌توان با پرچم \fB\-\-no-encoding\fP به حالت خودکار آن بازگرداند. .RE .sp \fB\-\-engine\fP=\fIENGINE\fP .RS 4 مشخص می‌کند که از کدام موتور عبارت باقاعده (regex) استفاده شود. هنگامی که یک موتور regex را انتخاب می‌کنید، این انتخاب برای تمام عبارت‌های باقاعده ارائه‌شده به ripgrep اعمال می‌شود (برای مثال، از طریق چند پرچم \fB\-e/\-\-regexp\fP یا \fB\-f/\-\-file\fP). .sp مقادیر پذیرفته‌شده عبارتند از \fBdefault\fP،‏ \fBpcre2\fP، یا \fBauto\fP. .sp مقدار پیش‌فرض \fBdefault\fP است که معمولاً سریع‌ترین گزینه است و باید برای بیشتر موارد استفاده مناسب باشد. موتور \fBpcre2\fP عموماً زمانی مفید است که بخواهید از قابلیت‌هایی مانند look-around یا پس‌ارجاع‌ها (backreferences) استفاده کنید. مقدار \fBauto\fP بسته به ویژگی‌های استفاده‌شده در الگو، با نهایت تلاش به صورت پویا میان موتورهای regex پشتیبانی‌شده انتخاب می‌کند. .sp توجه داشته باشید که موتور \fBpcre2\fP یک قابلیت اختیاری در ripgrep است. اگر PCRE2 در ساخت ripgrep شما گنجانده نشده باشد، استفاده از این پرچم منجر به چاپ پیام خطا توسط ripgrep و خروج از برنامه می‌شود. .sp این پرچم کاربردهای قبلی پرچم‌های \fB\-P/\-\-pcre2\fP و \fB\-\-auto\-hybrid\-regex\fP را لغو می‌کند. .RE .sp \fB\-F\fP, \fB\-\-fixed\-strings\fP .RS 4 با تمام الگوها به عنوان رشته‌های متنی صریح (لفظی) به‌جای عبارات باقاعده رفتار می‌کند. هنگامی که از این پرچم استفاده می‌شود، نیازی به گریز دادن فرانوسه‌های ویژه عبارت باقاعده مانند \fB.(){}*+\fP نخواهد بود. .sp این پرچم را می‌توان با \fB\-\-no-fixed-strings\fP غیرفعال کرد. .RE .sp \fB\-i\fP, \fB\-\-ignore\-case\fP .RS 4 هنگامی که این پرچم داده شود، تمام الگوها بدون حساسیت به حروف کوچک و بزرگ جستجو خواهند شد. قوانین عدم حساسیت به حروف در موتور regex پیش‌فرض ripgrep با قوانین ساده تبدیل وضعیت حروف («simple» case folding) در یونیکد مطابقت دارد. .sp این یک گزینه سراسری است که برای تمامی الگوهای داده‌شده به ripgrep اعمال می‌شود. الگوهای منفرد همچنان می‌توانند با استفاده از پرچم‌های درون‌خطی regex به صورت حساس به حروف تطبیق داده شوند. برای مثال، \fB(?\-i)abc\fP حتی در صورت استفاده از این پرچم، با \fBabc\fP به صورت حساس به حروف تطبیق می‌یابد. .sp این پرچم، \fB\-s/\-\-case\-sensitive\fP و \fB\-S/\-\-smart\-case\fP را لغو می‌کند. .RE .sp \fB\-v\fP, \fB\-\-invert\-match\fP .RS 4 این پرچم تطبیق را معکوس می‌کند؛ به این معنی که ripgrep به‌جای چاپ خطوط منطبق، خطوطی را که تطابق ندارند چاپ می‌کند. .sp توجه داشته باشید که این گزینه تنها تطبیق خط‌به‌خط را معکوس می‌کند. برای مثال، ترکیب این پرچم با \fB\-l/\-\-files\-with\-matches\fP فایل‌هایی را نشان می‌دهد که دارای هر خطی باشند که با الگوهای ارائه‌شده مطابقت ندارد. این با گزینه‌ای مانند \fB\-\-files\-without\-match\fP یکسان نیست، که فایل‌هایی را خروجی می‌دهد که هیچ خط منطبقی در آن‌ها وجود ندارد. .sp این پرچم را می‌توان با \fB\-\-no-invert-match\fP غیرفعال کرد. .RE .sp \fB\-x\fP, \fB\-\-line\-regexp\fP .RS 4 هنگامی که فعال باشد، ripgrep تنها تطابق‌هایی را نشان می‌دهد که با مرزهای خط احاطه شده باشند. این معادل قرار دادن هر الگو بین \fB^\fP و \fB$\fP است. به عبارت دیگر، این گزینه تنها خطوطی را چاپ می‌کند که در آن کل خط در تطابق شرکت داشته باشد. .sp این پرچم، پرچم \fB\-w/\-\-word\-regexp\fP را لغو می‌کند. .RE .sp \fB\-m\fP \fINUM\fP, \fB\-\-max\-count\fP=\fINUM\fP .RS 4 تعداد خطوط منطبق در هر فایل جستجوشده را به \fINUM\fP محدود می‌کند. .sp هنگامی که از \fB\-U/\-\-multiline\fP استفاده می‌شود، یک تطابق واحد که چندین خط را در بر می‌گیرد، برای این محدودیت تنها یک بار شمرده می‌شود. تطابق‌های متعدد در یک خط منفرد تنها یک بار شمرده می‌شوند، درست همان‌طور که در حالت غیرچندخطی رفتار می‌شود. .sp در صورت ترکیب با \fB\-A/\-\-after\-context\fP یا \fB\-C/\-\-context\fP، اگر خطوط زمینه (context) دارای تطابق باشند، ممکن است تطابق‌های بیشتری نسبت به حد حداکثر چاپ شوند. .sp توجه داشته باشید که \fB0\fP یک مقدار مجاز است اما بعید است مفید باشد. در صورت استفاده از آن، ripgrep هیچ چیزی را جستجو نخواهد کرد. .RE .sp \fB\-\-mmap\fP .RS 4 هنگامی که فعال باشد، ripgrep در صورت امکان با استفاده از نگاشت حافظه (memory maps) جستجو خواهد کرد. این ویژگی به طور پیش‌فرض زمانی که ripgrep تشخیص دهد سریع‌تر خواهد بود، فعال است. .sp جستجوی نگاشت حافظه در تمامی شرایط قابل استفاده نیست. برای مثال، هنگام جستجوی فایل‌های مجازی یا جریان‌هایی مانند \fBstdin\fP. در چنین مواردی، حتی در صورت فعال بودن این پرچم، از نگاشت حافظه استفاده نخواهد شد. .sp توجه داشته باشید که در صورت استفاده از نگاشت حافظه، اگر ripgrep فایلی را جستجو کند که هم‌زمان کوتاه (truncate) می‌شود، ممکن است به طور غیرمنتظره متوقف شود. کاربران می‌توانند با غیرفعال کردن نگاشت حافظه، از وقوع این احتمال جلوگیری کنند. .sp این پرچم را می‌توان با \fB\-\-no-mmap\fP غیرفعال کرد. .RE .sp \fB\-U\fP, \fB\-\-multiline\fP .RS 4 این پرچم جستجو در چندین خط را فعال می‌کند. .sp هنگامی که حالت چندخطی فعال است، ripgrep این محدودیت را که تطابق نمی‌تواند شامل نویسه پایان‌دهنده خط باشد، برمی‌دارد. برای مثال، وقتی حالت چندخطی فعال نیست (پیش‌فرض)، عبارت باقاعده \fB\\p{any}\fP با هر نقطه کد (codepoint) یونیکد به جز \fB\\n\fP تطبیق می‌یابد. به طور مشابه، استفاده از عبارت باقاعده \fB\\n\fP صریحاً ممنوع است و اگر سعی کنید از آن استفاده کنید، ripgrep خطایی برمی‌گرداند. با این حال، وقتی حالت چندخطی فعال باشد، \fB\\p{any}\fP با هر نقطه کد یونیکد، از جمله \fB\\n\fP تطبیق پیدا می‌کند و عبارات باقاعده‌ای مانند \fB\\n\fP مجاز هستند. .sp یک نکته مهم این است که حالت چندخطی معناشناسی تطابق \fB.\fP را تغییر نمی‌دهد؛ به این معنی که در اکثر موتورهای تطبیق regex، یک \fB.\fP به طور پیش‌فرض با هر نویسه‌ای غیر از \fB\\n\fP مطابقت دارد و این موضوع در ripgrep نیز صادق است. برای اینکه \fB.\fP با \fB\\n\fP تطبیق داده شود، باید پرچم «dot all» را در داخل عبارت باقاعده فعال کنید. برای مثال، هر دو عبارت \fB(?s).\fP و \fB(?s:.)\fP معناشناسی یکسانی دارند که در آن \fB.\fP با هر نویسه‌ای از جمله \fB\\n\fP مطابقت می‌یابد. در غیر این صورت، پرچم \fB\-\-multiline\-dotall\fP می‌تواند برای تبدیل رفتار «dot all» به پیش‌فرض ارسال شود. این پرچم تنها زمانی اعمال می‌شود که جستجوی چندخطی فعال باشد. .sp هیچ محدودیتی در تعداد خطوطی که یک تطابق منفرد می‌تواند در بر گیرد وجود ندارد. .sp \fBهشدار\fP: به دلیل نحوه عملکرد موتور regex زیرین، جستجوهای چندخطی ممکن است کندتر از جستجوهای عادی خط‌محور باشند و همچنین ممکن است حافظه بیشتری مصرف کنند. به‌ویژه، هنگامی که حالت چندخطی فعال است، ripgrep نیاز دارد که هر فایلی که جستجو می‌کند به طور پیوسته در حافظه قرار گیرد (خواه با خواندن آن روی heap یا با نگاشت حافظه آن). مواردی که نمی‌توان آن‌ها را نگاشت حافظه کرد (مانند \fBstdin\fP) پیش از شروع جستجو تا رسیدن به EOF به طور کامل خوانده خواهند شد. به طور کلی، ripgrep این اقدامات را تنها در صورت لزوم انجام می‌دهد. به طور مشخص، اگر پرچم \fB\-U/\-\-multiline\fP داده شود اما regex شامل الگوهایی نباشد که با نویسه‌های \fB\\n\fP تطبیق یابند، ripgrep به طور خودکار از خواندن کل فایل در حافظه قبل از جستجو در آن خودداری می‌کند. با این وجود، اگر فقط به تطابق‌هایی اهمیت می‌دهید که حداکثر یک خط را در بر می‌گیرند، همیشه بهتر است حالت چندخطی را غیرفعال کنید. .sp این پرچم، پرچم \fB\-\-stop\-on\-nonmatch\fP را لغو می‌کند. .sp این پرچم را می‌توان با \fB\-\-no-multiline\fP غیرفعال کرد. .RE .sp \fB\-\-multiline\-dotall\fP .RS 4 این پرچم حالت «dot all» را در تمام الگوهای regex فعال می‌کند. این امر باعث می‌شود که \fB.\fP هنگام فعال بودن جستجوی چندخطی، با نویسه‌های پایان‌دهنده خط تطبیق یابد. این پرچم در صورتی که جستجوی چندخطی با پرچم \fB\-U/\-\-multiline\fP فعال نشده باشد، هیچ اثری ندارد. .sp به طور معمول، \fB.\fP با هر نویسه‌ای به جز پایان‌دهنده‌های خط مطابقت پیدا می‌کند. در حالی که این رفتار معمولاً برای تطبیق خط‌محور مرتبط نیست (زیرا تطابق‌ها حداکثر می‌توانند یک خط را در بر گیرند)، هنگام جستجو با پرچم \fB\-U/\-\-multiline\fP می‌تواند مفید باشد. به طور پیش‌فرض، حالت چندخطی بدون فعال بودن حالت «dot all» اجرا می‌شود. .sp این پرچم به طور کلی برای استفاده در یک نام مستعار (alias) یا فایل پیکربندی ripgrep شما در نظر گرفته شده است اگر معناشناسی «dot all» را به طور پیش‌فرض ترجیح می‌دهید. توجه داشته باشید که صرف‌نظر از استفاده شدن یا نشدن این پرچم، معناشناسی «dot all» همچنان از طریق پرچم‌های درون‌خطی در خود الگوی regex قابل کنترل است، برای مثال \fB(?s:.)\fP همیشه «dot all» را فعال می‌کند، در حالی که \fB(?-s:.)\fP همیشه «dot all» را غیرفعال می‌سازد. علاوه بر این، می‌توانید از رده‌های نویسه مانند \fB\\p{any}\fP برای تطبیق با هر نقطه کد یونیکد بدون توجه به فعال بودن یا نبودن حالت «dot all» استفاده کنید. .sp این پرچم را می‌توان با \fB\-\-no-multiline-dotall\fP غیرفعال کرد. .RE .sp \fB\-\-no\-unicode\fP .RS 4 این پرچم حالت یونیکد را برای تمام الگوهای داده‌شده به ripgrep غیرفعال می‌کند. .sp به طور پیش‌فرض، ripgrep «حالت یونیکد» را در تمام عبارات باقاعده خود فعال می‌کند. این امر پیامدهای متعددی دارد: .sp.IP \(bu 3n نویسه \fB.\fP تنها با مقادیر اسکالر معتبر یونیکد کدگذاری‌شده با UTF-8 مطابقت پیدا می‌کند. .sp .IP \(bu 3n کلاس‌هایی مانند \fB\\w\fP، \fB\\s\fP و \fB\\d\fP همگی سازگار با یونیکد هستند و دامنه بسیار گسترده‌تری نسبت به نسخه‌های صرفاً ASCII خود دارند. .sp .IP \(bu 3n تطبیق غیرحساس به حروف کوچک و بزرگ از فولدینگ حروف یونیکد (Unicode case folding) استفاده خواهد کرد. .sp .IP \(bu 3n طیف گسترده‌ای از کلاس‌ها مانند \fB\\p{Emoji}\fP در دسترس هستند. (اگرچه مجموعه کلاس‌های در دسترس بسته به موتور regex متغیر است. به‌طور کلی، موتور regex پیش‌فرض کلاس‌های بیشتری را پشتیبانی می‌کند.) .sp .IP \(bu 3n مرزهای کلمه (\fB\\b\fP و \fB\\B\fP) از تعریف یونیکد برای نویسه‌های کلمه استفاده می‌کنند. .PP در برخی موارد ممکن است غیرفعال کردن این ویژگی‌ها مطلوب باشد. این پرچم دقیقاً همین کار را انجام می‌دهد. برای مثال، حالت یونیکد گاهی می‌تواند تأثیر منفی بر کارایی داشته باشد، به‌ویژه هنگامی که مواردی مانند \fB\\w\fP مکرراً استفاده می‌شوند (از جمله با تکرارهای مقید مانند \fB\\w{100}\fP) در حالی که تنها تفسیر ASCII آن‌ها مورد نیاز است. .sp این پرچم را می‌توان با \fB\-\-unicode\fP غیرفعال کرد. .RE .sp \fB\-\-null\-data\fP .RS 4 فعال‌سازی این پرچم باعث می‌شود که ripgrep به جای مقدار پیش‌فرض \fP\\n\fP، از بایت \fBNUL\fP به عنوان پایان‌دهندهٔ خط استفاده کند. .sp این قابلیت هنگام جستجو در فایل‌های باینری بزرگ مفید است؛ فایل‌هایی که اگر از \fB\\n\fP به عنوان پایان‌دهندهٔ خط در آن‌ها استفاده می‌شد، خطوط بسیار طویلی می‌داشتند. به‌ویژه اینکه ripgrep نیاز دارد هر خط دست‌کم در حافظه جا شود. استفاده از \fBNUL\fP می‌تواند یک راهکار موقتِ سودمند برای پایین نگه داشتن حافظه مورد نیاز و جلوگیری از شرایط OOM (کمبود حافظه / out of memory) باشد. .sp این گزینه همچنین برای پردازش داده‌های جداشده با NUL، مانند خروجی تولیدشده هنگام استفاده از پرچم \fB\-0/\-\-null\fP در ripgrep یا پرچم \fB\-\-print0\fP در \fBfind\fP، مفید است. .sp استفاده از این پرچم به معنای اعمال خودکار \fB\-a/\-\-text\fP است. این پرچم همچنین اولویت بالاتری نسبت به \fB\-\-crlf\fP دارد و آن را نادیده می‌گیرد. .RE .sp \fB\-P\fP, \fB\-\-pcre2\fP .RS 4 هنگامی که این پرچم مشخص شود، ripgrep به جای موتور regex پیش‌فرض خود از موتور regex پ‌سی‌آر‌ای۲ (PCRE2) استفاده خواهد کرد. .sp این گزینه به‌طور کلی زمانی سودمند است که می‌خواهید از امکاناتی مانند look-around یا ارجاع به گذشته (backreferences) استفاده کنید. .sp استفاده از این پرچم معادل ارسال \fB\-\-engine=pcre2\fP است. کاربران می‌توانند به جای آن از \fB\-\-engine=auto\fP استفاده کنند تا ripgrep به‌طور خودکار موتور regex مناسب را بر اساس الگوهای داده‌شده انتخاب کند. این پرچم و پرچم \fB\-\-engine\fP یکدیگر را لغو می‌کنند. .sp توجه داشته باشید که PCRE2 یک قابلیت اختیاری در ripgrep است. اگر PCRE2 در بیلد ripgrep شما گنجانده نشده باشد، استفاده از این پرچم باعث چاپ یک پیام خطا توسط ripgrep و خروج از برنامه خواهد شد. همچنین PCRE2 در برخی موارد ممکن است تجربه کاربری ضعیف‌تری ارائه دهد، زیرا APIهای درون‌نگری (introspection APIs) کمتری نسبت به موتور regex پیش‌فرض ripgrep دارد. به عنوان مثال، اگر از یک \fB\\n\fP در regex مربوط به PCRE2 بدون پرچم \fB\-U/\-\-multiline\fP استفاده کنید، ripgrep بدون اعلام خطا هیچ تطابقی پیدا نخواهد کرد (silently fail)، در حالی که در موتور regex پیش‌فرض بلافاصله خطایی گزارش می‌شود. .sp این پرچم را می‌توان با \fB\-\-no-pcre2\fP غیرفعال کرد. .RE .sp \fB\-\-regex\-size\-limit\fP=\fINUM+SUFFIX?\fP .RS 4 حد مجاز اندازه regex کامپایل‌شده؛ جایی که regex کامپایل‌شده عموماً متناظر با یک شیء منفرد در حافظه است که می‌تواند با تمام الگوهای ارائه‌شده به ripgrep تطابق یابد. حد پیش‌فرض به اندازه کافی سخاوتمندانه در نظر گرفته شده است تا اکثر الگوهای معقول (یا حتی تعداد کمی از آن‌ها) در آن جای گیرند. .sp تغییر این مقدار زمانی مفید است که صراحتاً بخواهید به ripgrep اجازه دهید تا در صورت نیاز زمان و/یا حافظه بسیار بیشتری را برای ساخت تطبیق‌دهندهٔ regex صرف کند. .sp قالب ورودی پسوندهای \fBK\fP، \fBM\fP یا \fBG\fP را می‌پذیرد که به ترتیب متناظر با کیلوبایت، مگابایت و گیگابایت هستند. اگر پسوندی ارائه نشود، ورودی به عنوان بایت در نظر گرفته می‌شود. .RE .sp \fB\-S\fP, \fB\-\-smart\-case\fP .RS 4 این پرچم به ripgrep دستور می‌دهد در صورتی که الگو تماماً از حروف کوچک تشکیل شده باشد، جستجو را بدون حساسیت به حروف کوچک و بزرگ انجام دهد. در غیر این صورت، جستجو با حساسیت به بزرگی و کوچکی حروف انجام خواهد شد. .sp یک الگو در صورتی تماماً با حروف کوچک در نظر گرفته می‌شود که هر دو شرط زیر برقرار باشند: .sp .IP \(bu 3n نخست، الگو شامل حداقل یک نویسه عینی (literal) باشد. برای مثال، \fBa\\w\fP حاوی یک نویسه عینی (\fBa\fP) است، اما \fB\\w\fP به‌تنهایی چنین نیست. .sp .IP \(bu 3n دوم، از میان نویسه‌های عینی موجود در الگو، هیچ‌کدام طبق یونیکد حرف بزرگ به شمار نیایند. برای مثال، \fBfoo\\pL\fP هیچ نویسه بزرگی ندارد اما \fBFoo\\pL\fP دارای نویسه بزرگ است. .PP این گزینه بر پرچم‌های \fB\-s/\-\-case\-sensitive\fP و \fB\-i/\-\-ignore\-case\fP اولویت دارد و آن‌ها را لغو می‌کند. .RE .sp \fB\-\-stop\-on\-nonmatch\fP .RS 4 فعال کردن این گزینه باعث می‌شود ripgrep به محض برخورد با خطی که مطابقت ندارد—پس از آنکه قبلاً خطی منطبق را پیدا کرده باشد—خواندن فایل را متوقف کند. این قابلیت زمانی مفید است که انتظار می‌رود تمام تطابق‌ها در یک فایل در خطوط متوالی قرار داشته باشند، برای مثال به دلیل مرتب بودن (sort بودن) خطوط. .sp این گزینه پرچم \fB\-U/\-\-multiline\fP را نادیده می‌گیرد و بر آن اولویت دارد. .RE .sp \fB\-a\fP, \fB\-\-text\fP .RS 4 این پرچم به ripgrep دستور می‌دهد تا فایل‌های باینری را طوری جستجو کند که گویی فایل متنی هستند. هنگامی که این پرچم فعال باشد، تشخیص فایل باینری در ripgrep غیرفعال می‌شود. این بدان معناست که در صورت وجود تطابق حین جستجوی یک فایل باینری، محتویات آن ممکن است در خروجی چاپ شود. این امر ممکن است باعث چاپ کدهای گریز (escape codes) شده و رفتار ترمینال شما را دگرگون کند. .sp تشخیص فایل باینری، در زمان فعال بودن نیز عملکردی کاملاً بی‌نقص ندارد. به‌طور کلی، این سازوکار از یک روش مکاشفه‌ای (heuristic) ساده استفاده می‌کند. اگر در حین جستجو یک بایت \fBNUL\fP دیده شود، فایل باینری در نظر گرفته شده و جستجو متوقف می‌شود (مگر اینکه این پرچم داده شده باشد). در مقابل، اگر از پرچم \fB\-\-binary\fP استفاده شود، ripgrep تنها زمانی متوقف می‌شود که پس از یافتن یک تطابق، بایت \fBNUL\fP را مشاهده کند (یا تمام فایل را جستجو نماید). .sp این پرچم اولویت بالاتری نسبت به \fB\-\-binary\fP دارد و آن را لغو می‌کند. .sp این پرچم را می‌توان با \fB\-\-no-text\fP غیرفعال کرد. .RE .sp \fB\-j\fP \fINUM\fP, \fB\-\-threads\fP=\fINUM\fP .RS 4 این پرچم تعداد تقریبی رشته‌ها (threads) را برای اجرا تنظیم می‌کند. مقدار \fB0\fP (که پیش‌فرض است) باعث می‌شود ripgrep تعداد رشته‌ها را با استفاده از روش‌های مکاشفه‌ای تعیین کند. .RE .sp \fB\-w\fP, \fB\-\-word\-regexp\fP .RS 4 در صورت فعال بودن، ripgrep تنها تطابق‌هایی را نمایش می‌دهد که در مرزهای کلمه (word boundaries) محصور شده باشند. این کار معادل احاطه کردن هر الگو با \fB\\b{start-half}\fP و \fB\\b{end-half}\fP است. این نگارش سفارشی از موتور regex پیش‌فرض ripgrep، بر خلاف \fB\\b\fP، نیازی به تطبیق نویسهٔ کلمه‌ای در یک طرف ندارد؛ بدین معنا که \fB\\b{start-half}\fP متناظر با تطبیق \fB\\W|\\A\fP در سمت چپ و \fB\\b{end-half}\fP متناظر با تطبیق \fB\\W|\\z\fP در سمت راست است. .sp این گزینه پرچم \fB\-x/\-\-line\-regexp\fP را نادیده می‌گیرد. .RE .sp \fB\-\-auto\-hybrid\-regex\fP .RS 4 منسوخ شده است (DEPRECATED). به جای آن از \fB\-\-engine\fP استفاده کنید. .sp هنگام استفاده از این پرچم، ripgrep بسته به قابلیت‌های استفاده‌شده در الگو، به‌طور پویا میان موتورهای regex پشتیبانی‌شده یکی را انتخاب می‌کند. هنگامی که ripgrep موتور regex را انتخاب کرد، این انتخاب را برای تمام عبارات باقاعده ارائه‌شده به ripgrep (مثلاً از طریق چندین پرچم \fB\-e/\-\-regexp\fP یا \fB\-f/\-\-file\fP) اعمال می‌کند. .sp به عنوان نمونه‌ای از رفتار این پرچم، ripgrep هر زمان که الگو بتواند با موفقیت توسط موتور regex پیش‌فرض مبتنی بر اتوماتای متناهی کامپایل شود، تلاش می‌کند از آن استفاده کند. اگر PCRE2 فعال باشد و الگوی داده‌شده نتواند با موتور regex پیش‌فرض کامپایل شود، PCRE2 به‌طور خودکار برای جستجو به کار گرفته خواهد شد. اگر PCRE2 در دسترس نباشد، این پرچم اثری ندارد زیرا تنها یک موتور regex برای انتخاب وجود خواهد داشت. .sp در آینده ممکن است ripgrep قواعد مکاشفه‌ای خود را برای نحوه تصمیم‌گیری درباره موتور regex مورد استفاده تغییر دهد. به‌طور کلی، این مکاشفه‌ها محدود به تحلیل ایستای الگوها خواهند بود و نه رفتارهای مشخص زمان اجرا حین جستجوی فایل‌ها. .sp نقطه ضعف اصلی استفاده از این پرچم این است که ممکن است همیشه مشخص نباشد ripgrep از کدام موتور regex استفاده می‌کند، و بنابراین ممکن است معناشناسی تطابق یا مشخصات کارایی ripgrep به‌طور نامحسوس و غیرمنتظره‌ای دستخوش تغییر شود. با این حال، در بسیاری از موارد همه موتورهای regex درباره نتیجه تطابق توافق دارند و پشتیبانی شفاف از ویژگی‌های پیشرفته‌تر regex مانند look-around و مراجع بازگشتی بدون نیاز صریح به فعال کردن آن‌ها می‌تواند مناسب باشد. .sp این پرچم را می‌توان با \fB\-\-no-auto-hybrid-regex\fP غیرفعال کرد. .RE .sp \fB\-\-no\-pcre2\-unicode\fP .RS 4 منسوخ شده است (DEPRECATED). به جای آن از \fB\-\-no\-unicode\fP استفاده کنید. .sp توجه داشته باشید که حالت یونیکد به‌طور پیش‌فرض فعال است. .sp این پرچم را می‌توان با \fB\-\-pcre2-unicode\fP غیرفعال کرد. .RE ..SS "گزینه‌های پالایش (FILTER OPTIONS)" \fB\-\-binary\fP .RS 4 فعال‌سازی این پرچم موجب می‌شود ripgrep در فایل‌های دودویی (binary) نیز جستجو کند. به‌طور پیش‌فرض، ripgrep به‌منظور بهبود ارتباط نتایج و افزایش سرعت جستجو، به‌طور خودکار از فایل‌های دودویی صرف‌نظر می‌کند. .sp فایل‌های دودویی بر اساس وجود یا عدم وجود بایت \fBNUL\fP به‌صورت اکتشافی شناسایی می‌شوند. به‌طور پیش‌فرض (بدون تنظیم این پرچم)، به محض مشاهده یک بایت \fBNUL\fP، جستجوی فایل توسط ripgrep متوقف می‌شود. معمولاً بایت‌های \fBNUL\fP در ابتدای بیشتر فایل‌های دودویی قرار دارند. اگر بایت \fBNUL\fP پس از یک تطابق رخ دهد، ripgrep آن تطابق را چاپ نخواهد کرد، جستجوی آن فایل را متوقف می‌کند و هشداری مبنی بر نادیده گرفته شدن برخی از تطابق‌ها صادر می‌نماید. .sp در مقابل، هنگام استفاده از این پرچم، ripgrep حتی در صورت یافتن بایت \fBNUL\fP به جستجوی فایل ادامه خواهد داد. به‌ویژه، در صورت مشاهده بایت \fBNUL\fP، جستجو تا زمان یافتن یک تطابق یا رسیدن به انتهای فایل (هرکدام زودتر رخ دهد) ادامه می‌یابد. اگر تطابقی یافت شود، ripgrep متوقف شده و هشداری مبنی بر توقف زودهنگام جستجو چاپ می‌کند. .sp اگر می‌خواهید ripgrep فایلی را بدون هیچ‌گونه رسیدگی ویژه به بایت‌های \fBNUL\fP جستجو کند (و احتمالاً داده‌های دودویی را در خروجی استاندارد stdout چاپ نماید)، باید از پرچم \fB\-a/\-\-text\fP استفاده کنید. .sp پرچم \fB\-\-binary\fP پرچمی برای کنترل سازوکار پالایش خودکار ripgrep است. از این رو، هنگام جستجوی صریح یک فایل مشخص یا هنگام جستجو در ورودی استاندارد stdin نیازی به استفاده از آن نیست؛ یعنی تنها هنگام جستجوی بازگشتی در یک دایرکتوری کاربرد دارد. .sp هنگامی که پرچم \fB\-u/\-\-unrestricted\fP سه بار تکرار شود، این پرچم به‌طور خودکار فعال می‌گردد. .sp این پرچم بر پرچم \fB\-a/\-\-text\fP اولویت دارد. .sp این پرچم را می‌توان با \fB\-\-no-binary\fP غیرفعال کرد. .RE .sp \fB\-L\fP, \fB\-\-follow\fP .RS 4 این پرچم به ripgrep دستور می‌دهد هنگام پیمایش دایرکتوری‌ها، پیوندهای نمادین (symbolic links) را دنبال کند. این رفتار به‌طور پیش‌فرض غیرفعال است. توجه داشته باشید که ripgrep حلقه‌های پیوند نمادین را بررسی کرده و در صورت یافتن آن‌ها خطا گزارش می‌دهد. ripgrep همچنین برای پیوندهای شکسته نیز خطا گزارش می‌کند. برای جلوگیری از نمایش پیام‌های خطا، از پرچم \fB\-\-no\-messages\fP استفاده کنید. .sp این پرچم را می‌توان با \fB\-\-no-follow\fP غیرفعال کرد. .RE .sp \fB\-g\fP \fIGLOB\fP, \fB\-\-glob\fP=\fIGLOB\fP .RS 4 شامل کردن یا مستثنی کردن فایل‌ها و دایرکتوری‌های مطابق با الگوی glob ارائه‌شده برای جستجو. این گزینه همواره بر هر منطق چشم‌پوشی دیگری اولویت دارد. می‌توان از چندین پرچم glob استفاده کرد. قواعد الگوها با الگوهای \fB.gitignore\fP مطابقت دارند. با افزودن یک \fB!\fP در ابتدای الگو آن را مستثنی کنید. اگر چندین الگو با یک فایل یا دایرکتوری مطابقت داشته باشند، الگویی که دیرتر در خط فرمان آمده باشد تقدم دارد. .sp به‌عنوان یک قابلیت الحاقی، الگوهای glob از تعیین گزینه‌های جانشین پشتیبانی می‌کنند: .BI "\-g '" ab{c,d}* ' معادل است با .BI "\-g " "abc " "\-g " abd. گزینه‌های جانشین خالی مانند .BI "\-g '" ab{,c} ' در حال حاضر پشتیبانی نمی‌شوند. توجه داشته باشید که این افزونهٔ نحوی در حال حاضر در فایل‌های \fBgitignore\fP نیز فعال است، حتی با وجود اینکه این نحو توسط خود git پشتیبانی نمی‌شود. ممکن است ripgrep این افزونهٔ نحوی را در فایل‌های gitignore غیرفعال کند، اما همواره از طریق پرچم \fB\-g/\-\-glob\fP در دسترس خواهد بود. .sp هنگامی که این پرچم تنظیم شود، هر فایل و دایرکتوری برای بررسی تطابق با آن ارزیابی می‌شود. برای نمونه، اگر تنها می‌خواهید در یک دایرکتوری خاص با نام \fIfoo\fP جستجو کنید، استفاده از .BI "\-g " foo نادرست است زیرا \fIfoo/bar\fP با الگوی \fIfoo\fP مطابقت ندارد. در عوض، باید از .BI "\-g '" foo/** '. استفاده کنید. .RE .sp \fB\-\-glob\-case\-insensitive\fP .RS 4 پردازش تمامی الگوهای glob مشخص‌شده با پرچم \fB\-g/\-\-glob\fP بدون حساسیت به حروف بزرگ و کوچک. این کار در عمل موجب می‌شود با \fB\-g/\-\-glob\fP همانند \fB\-\-iglob\fP برخورد شود. .sp این پرچم را می‌توان با \fB\-\-no-glob-case-insensitive\fP غیرفعال کرد. .RE .sp \fB\-.\fP, \fB\-\-hidden\fP .RS 4 جستجوی فایل‌ها و دایرکتوری‌های مخفی. به‌طور پیش‌فرض، فایل‌ها و دایرکتوری‌های مخفی نادیده گرفته می‌شوند. توجه داشته باشید که اگر یک فایل یا دایرکتوری مخفی در یک فایل چشم‌پوشی در فهرست مجاز (whitelist) قرار گرفته باشد، حتی بدون ارائه این پرچم نیز جستجو خواهد شد؛ همچنین در صورتی که یک فایل یا دایرکتوری مخفی به‌طور صریح به‌عنوان آرگومان به ripgrep داده شود. .sp یک فایل یا دایرکتوری در صورتی مخفی در نظر گرفته می‌شود که نام پایهٔ آن با یک نویسه نقطه (\fB.\fP) شروع شود. در سیستم‌عامل‌هایی که از صفت فایل «مخفی» پشتیبانی می‌کنند، مانند Windows، فایل‌های دارای این صفت نیز مخفی تلقی می‌شوند. .sp توجه داشته باشید که \fB\-./\-\-hidden\fP فایل‌ها و پوشه‌هایی مانند \fB.git\fP را صرف‌نظر از پرچم \fB\-\-no\-ignore\-vcs\fP شامل خواهد کرد. برای مستثنی کردن چنین مسیرهایی هنگام استفاده از \fB\-./\-\-hidden\fP، باید صریحاً آن‌ها را با استفاده از پرچمی دیگر یا یک فایل چشم‌پوشی نادیده بگیرید. .sp این پرچم را می‌توان با \fB\-\-no-hidden\fP غیرفعال کرد. .RE .sp \fB\-\-iglob\fP=\fIGLOB\fP .RS 4 شامل کردن یا مستثنی کردن فایل‌ها و دایرکتوری‌های مطابق با الگوی glob ارائه‌شده برای جستجو. این گزینه همواره بر هر منطق چشم‌پوشی دیگری اولویت دارد. می‌توان از چندین پرچم glob استفاده کرد. قواعد الگوها با الگوهای \fB.gitignore\fP مطابقت دارند. با افزودن یک \fB!\fP به ابتدای الگو آن را مستثنی کنید. اگر چندین الگو با یک فایل یا دایرکتوری مطابقت داشته باشند، الگویی که دیرتر در خط فرمان آمده باشد تقدم دارد. الگوهای استفاده‌شده از طریق این پرچم بدون حساسیت به حروف بزرگ و کوچک تطبیق داده می‌شوند. .RE .sp \fB\-\-ignore\-file\fP=\fIPATH\fP .RS 4 مسیری به یک یا چند فایل قواعد با قالب \fBgitignore\fP را تعیین می‌کند. این الگوها پس از الگوهای موجود در فایل‌های \fB.gitignore\fP، \fB.rgignore\fP و \fB.ignore\fP اعمال شده و نسبت به دایرکتوری کاری جاری مطابقت داده می‌شوند. یعنی فایل‌های مشخص‌شده از طریق این پرچم نسبت به فایل‌هایی که به‌طور خودکار در درخت دایرکتوری یافته می‌شوند، اولویت کمتری دارند. با استفاده مکرر از این پرچم می‌توان فایل‌های چشم‌پوشی بیشتری را تعیین کرد. هنگام تعیین چندین فایل چشم‌پوشی، فایل‌های پیشین اولویت کمتری نسبت به فایل‌های بعدی دارند. .sp اگر به دنبال روشی برای گنجاندن یا استثنا کردن مستقیم فایل‌ها و دایرکتوری‌ها در خط فرمان هستید، در عوض از \fB\-g/\-\-glob\fP استفاده کنید. .RE .sp \fB\-\-ignore\-file\-case\-insensitive\fP .RS 4 پردازش فایل‌های چشم‌پوشی (\fB.gitignore\fP، \fB.ignore\fP و غیره) بدون حساسیت به حروف بزرگ و کوچک. توجه داشته باشید که این کار با افت کارایی همراه است و بیشترین کاربرد را در سیستم‌های فایل فاقد حساسیت به حروف کوچک و بزرگ (مانند Windows) دارد. .sp این پرچم را می‌توان با \fB\-\-no-ignore-file-case-insensitive\fP غیرفعال کرد. .RE .sp \fB\-d\fP \fINUM\fP, \fB\-\-max\-depth\fP=\fINUM\fP .RS 4 این پرچم عمق پیمایش دایرکتوری را به میزان \fINUM\fP سطح فراتر از مسیرهای ارائه‌شده محدود می‌کند. مقدار \fB0\fP تنها خود مسیرهای مشخص‌شده به صراحت را جستجو می‌کند. .sp برای نمونه، \fBrg --max-depth 0 \fP\fIdir/\fP هیچ اثری ندارد زیرا به داخل \fIdir/\fP ورود نمی‌کند. دستور \fBrg --max-depth 1 \fP\fIdir/\fP تنها فرزندان مستقیم \fIdir\fP را جستجو می‌کند. .sp نگارش جایگزین برای این پرچم \fB\-\-maxdepth\fP است. .RE .sp \fB\-\-max\-filesize\fP=\fINUM+SUFFIX?\fP .RS 4 نادیده گرفتن فایل‌هایی با اندازهٔ بزرگ‌تر از \fINUM\fP. این گزینه در مورد دایرکتوری‌ها صدق نمی‌کند. .sp قالب ورودی پسوندهای \fBK\fP، \fBM\fP یا \fBG\fP را می‌پذیرد که به‌ترتیب متناظر با کیلوبایت، مگابایت و گیگابایت هستند. در صورت عدم درج پسوند، مقدار بر حسب بایت در نظر گرفته می‌شود. .sp مثال‌ها: \fB\-\-max-filesize 50K\fP یا \fB\-\-max\-filesize 80M\fP. .RE .sp \fB\-\-no\-ignore\fP .RS 4 هنگام تنظیم، فایل‌های چشم‌پوشی مانند \fB.gitignore\fP، \fB.ignore\fP و \fB.rgignore\fP نادیده گرفته می‌شوند. این گزینه شامل \fB\-\-no\-ignore\-dot\fP، \fB\-\-no\-ignore\-exclude\fP، \fB\-\-no\-ignore\-global\fP، \fB\-\-no\-ignore\-parent\fP و \fB\-\-no\-ignore\-vcs\fP نیز می‌شود. .sp این گزینه شامل \fB\-\-no\-ignore\-files\fP نمی‌شود، چرا که \fB\-\-ignore\-file\fP صریحاً به‌عنوان یک آرگومان خط فرمان تعیین می‌گردد. .sp هنگامی که پرچم \fB\-u/\-\-unrestricted\fP تنها یک بار داده شود، رفتاری کاملاً مشابه با این پرچم خواهد داشت و می‌توان آن را یک نام مستعار در نظر گرفت. با این حال، تکرار بیشتر پرچم \fB\-u/\-\-unrestricted\fP تأثیرات مضاعفی به دنبال دارد. .sp این پرچم را می‌توان با \fB\-\-ignore\fP غیرفعال کرد. .RE .sp \fB\-\-no\-ignore\-dot\fP .RS 4 عدم رعایت قواعد پالایش موجود در فایل‌های \fB.ignore\fP یا \fB.rgignore\fP. .sp این گزینه تأثیری بر نادیده گرفتن فایل‌ها و دایرکتوری‌هایی که نامشان با نقطه آغاز می‌شود توسط ripgrep ندارد. برای آن منظور، پرچم \fB\-./\-\-hidden\fP را ببینید. این پرچم همچنین تأثیری بر رعایت قواعد پالایش در فایل‌های \fB.gitignore\fP ندارد. .sp این پرچم را می‌توان با \fB\-\-ignore-dot\fP غیرفعال کرد. .RE .sp \fB\-\-no\-ignore\-exclude\fP .RS 4 عدم رعایت قواعد پالایش فایل‌هایی که به‌صورت دستی برای مخزن پیکربندی شده‌اند. برای مثال، این شامل فایل \fB.git/info/exclude\fP در \fBgit\fP است. .sp این پرچم را می‌توان با \fB\-\-ignore-exclude\fP غیرفعال کرد. .RE .sp \fB\-\-no\-ignore\-files\fP .RS 4 در صورت فعال بودن، هر پرچم \fB\-\-ignore\-file\fP، حتی مواردی که پس از این پرچم در دستور بیایند، نادیده گرفته می‌شوند. .sp این پرچم را می‌توان با \fB\-\-ignore-files\fP غیرفعال کرد. .RE .sp \fB\-\-no\-ignore\-global\fP .RS 4 عدم رعایت قواعد پالایش فایل‌های چشم‌پوشی حاصل از منابع «سراسری» (global) مانند گزینهٔ پیکربندی \fBcore.excludesFile\fP در \fBgit\fP (که مقدار پیش‌فرض آن \fB$HOME/.config/git/ignore\fP است). .sp این پرچم را می‌توان با \fB\-\-ignore-global\fP غیرفعال کرد. .RE .sp \fB\-\-no\-ignore\-parent\fP .RS 4 هنگام تنظیم این پرچم، قواعد پالایش فایل‌های چشم‌پوشی موجود در دایرکتوری‌های والد نادیده گرفته می‌شوند. به‌طور پیش‌فرض، ripgrep دایرکتوری‌های والدِ دایرکتوری کاری جاری را به سمت بالا پیمایش می‌کند تا فایل‌های چشم‌پوشی مرتبطی را که باید اعمال شوند بیابد. در برخی شرایط ممکن است این رفتار مطلوبی نباشد. .sp این پرچم را می‌توان با \fB\-\-ignore-parent\fP غیرفعال کرد. .RE .sp \fB\-\-no\-ignore\-vcs\fP .RS 4 در صورت تعیین، قواعد پالایش فایل‌های چشم‌پوشی سامانه کنترل نسخه (مانند \fB.gitignore\fP) نادیده گرفته می‌شوند. به‌طور پیش‌فرض، ripgrep برای پالایش خودکار از قواعد چشم‌پوشی \fBgit\fP پیروی می‌کند. در برخی موارد، ممکن است پیروی از قواعد کنترل نسخه مطلوب نبوده و در عوض تمایل به پیروی اختصاصی از قواعد \fB.ignore\fP یا \fB.rgignore\fP وجود داشته باشد. .sp توجه داشته باشید که این پرچم مستقیماً بر پالایش فایل‌ها یا پوشه‌های کنترل نسخه‌ای که با نقطه (\fB.\fP) آغاز می‌شوند (مانند \fB.git\fP) اثر نمی‌گذارد. این موارد در عوض تحت تأثیر \fB\-./\-\-hidden\fP و پرچم‌های مربوط به آن هستند. .sp این پرچم برای فایل‌های چشم‌پوشی سامانه کنترل نسخه به منزلهٔ اعمال \fB\-\-no\-ignore\-parent\fP نیز هست. .sp این پرچم را می‌توان با \fB\-\-ignore-vcs\fP غیرفعال کرد. .RE .sp \fB\-\-no\-require\-git\fP .RS 4 با ارائه این پرچم، فایل‌های چشم‌پوشی سامانه کنترل نسخه مانند \fB.gitignore\fP حتی در صورتی که هیچ مخزن \fBgit\fPای موجود نباشد نیز رعایت می‌شوند. .sp به‌طور پیش‌فرض، ripgrep تنها زمانی قواعد پالایش فایل‌های چشم‌پوشی سامانه کنترل نسخه را رعایت می‌کند که تشخیص دهد جستجو در داخل یک مخزن کنترل نسخه در حال اجراست؛ برای نمونه، هنگامی که یک دایرکتوری \fB.git\fP مشاهده شود. .sp این پرچم محدودیت پیش‌فرض فوق را برمی‌دارد. برای مثال، این پرچم زمانی می‌تواند سودمند باشد که محتویات یک مخزن \fBgit\fP در محلی ذخیره یا کپی شده باشد، اما وضعیت اصلی مخزن وجود نداشته باشد. .sp این پرچم را می‌توان با \fB\-\-require-git\fP غیرفعال کرد. .RE .sp \fB\-\-one\-file\-system\fP .RS 4 هنگام فعال بودن، ripgrep از مرزهای سیستم فایلی که جستجو از آن آغاز شده است عبور نخواهد کرد. .sp توجه داشته باشید که این حالت به ازای هر آرگومان مسیر داده‌شده به ripgrep اعمال می‌شود. برای نمونه، در دستور .sp .EX rg \-\-one\-file\-system /foo/bar /quux/baz .EE .sp ابزار ripgrep هر دو مسیر \fI/foo/bar\fP و \fI/quux/baz\fP را حتی در صورت قرار داشتن روی سیستم‌های فایل متفاوت جستجو می‌کند، اما هنگام پیمایش درخت دایرکتوریِ هر مسیر، از مرز سیستم فایل مربوط به آن عبور نخواهد کرد. .sp این رفتار مشابه پرچم \fB\-xdev\fP یا \fB\-mount\fP در دستور \fBfind\fP است. .sp این پرچم را می‌توان با \fB\-\-no-one-file-system\fP غیرفعال کرد. .RE .sp \fB\-t\fP \fITYPE\fP, \fB\-\-type\fP=\fITYPE\fP .RS 4 این پرچم جستجوی ripgrep را به فایل‌های مطابق با \fITYPE\fP محدود می‌کند. می‌توان چندین پرچم \fB\-t/\-\-type\fP ارائه داد. .sp این پرچم از مقدار ویژهٔ \fBall\fP پشتیبانی می‌کند؛ در این حالت دستور به‌گونه‌ای عمل خواهد کرد که گویی \fB\-t/\-\-type\fP برای تک‌تک انواع فایل‌های پشتیبانی‌شده توسط ripgrep (از جمله انواع فایل‌های سفارشی) داده شده است. نتیجه این است که \fB\-\-type=all\fP موجب می‌شود ripgrep در حالت «فهرست سفید» جستجو کند، به این معنا که تنها فایل‌هایی را جستجو می‌کند که از طریق تعاریف نوع خود می‌شناسد. .sp توجه داشته باشید که اولویت این پرچم نسبت به پرچم \fB\-g/\-\-glob\fP و هرگونه قواعد موجود در فایل‌های چشم‌پوشی کمتر است. .sp برای مشاهدهٔ فهرست انواع فایل‌های موجود، از پرچم \fB\-\-type\-list\fP استفاده کنید. .RE .sp \fB\-T\fP \fITYPE\fP, \fB\-\-type\-not\fP=\fITYPE\fP .RS 4 فایل‌های مطابق با \fITYPE\fP را جستجو نمی‌کند. می‌توان چندین پرچم \fB\-T/\-\-type\-not\fP تعیین کرد. برای مشاهده تمامی انواع موجود، پرچم \fB\-\-type\-list\fP را به کار ببرید. .sp این پرچم از مقدار ویژهٔ \fBall\fP پشتیبانی می‌کند؛ در این صورت عملکرد آن همانند ارائه‌شدن \fB\-T/\-\-type\-not\fP برای تمام انواع فایل‌های پشتیبانی‌شده توسط ripgrep (شامل انواع فایل‌های سفارشی) خواهد بود. نتیجه آن است که \fB\-\-type\-not=all\fP موجب کارکرد ripgrep در حالت «فهرست سیاه» می‌شود؛ یعنی فقط فایل‌هایی که توسط تعاریف نوع آن ناشناخته هستند جستجو خواهند شد. .sp جهت مشاهده فهرست انواع فایل‌های دردسترس، از پرچم \fB\-\-type\-list\fP استفاده کنید. .RE .sp \fB\-\-type\-add\fP=\fITYPESPEC\fP .RS 4 این پرچم یک الگوی glob جدید برای یک نوع فایل مشخص اضافه می‌کند. در هر بار تنها یک الگو می‌تواند افزوده شود. می‌توان چندین پرچم \fB\-\-type\-add\fP را مشخص کرد. الگوها به الگوهای موجود از پیش تعریف‌شده درون ripgrep اضافه می‌شوند، مگر اینکه از \fB\-\-type\-clear\fP استفاده شود. .sp توجه داشته باشید که این پرچم باید در هر بار اجرای ripgrep به آن منتقل شود؛ زیرا تنظیمات نوع پایدار نمی‌مانند. برای یک راه‌حل دائمی، بخش \fBCONFIGURATION FILES\fP را بررسی کنید. .sp مثال: .sp .EX rg \-\-type\-add 'foo:*.foo' -tfoo \fIPATTERN\fP .EE .sp همچنین می‌توان از این پرچم برای وارد کردن قواعد از انواع دیگر با استفاده از دستور ویژه include بهره گرفت. این دستور ویژه اجازه می‌دهد یک یا چند نام نوع دیگر (جداشده با ویرگول) که تعریف شده‌اند تعیین گردند و قواعد آن‌ها به‌طور خودکار به نوع مشخص‌شده وارد شوند. برای نمونه، به‌منظور ایجاد یک نوع به نام src که با فایل‌های C++، Python و Markdown مطابقت داشته باشد، می‌توان دستور زیر را به کار برد: .sp .EX \-\-type\-add 'src:include:cpp,py,md' .EE .sp با تکرار استفاده از این پرچم، همچنان می‌توان قواعد glob بیشتری را به نوع src اضافه نمود: .sp .EX \-\-type\-add 'src:include:cpp,py,md' \-\-type\-add 'src:*.foo' .EE .sp توجه داشته باشید که نام انواع فایل فقط باید شامل حروف یا ارقام یونیکد باشد. استفاده از نویسه‌های نشانه‌گذاری مجاز نیست. .RE .sp \fB\-\-type\-clear\fP=\fITYPE\fP .RS 4 پاک کردن الگوهای نوع فایلی که پیش‌تر برای \fITYPE\fP تعریف شده‌اند. این پرچم تمامی الگوهای قبلاً تعریف‌شده برای \fITYPE\fP را پاک می‌کند، ولی می‌توان بعد از این پرچم الگوهای جدیدی اضافه کرد. .sp توجه داشته باشید که این گزینه باید در هر بار فراخوانی ripgrep داده شود؛ تنظیمات نوع فایل ماندگار نیستند. برای یک راه‌حل پایدار، بخش \fBCONFIGURATION FILES\fP را ببینید. .RE .sp \fB\-u\fP, \fB\-\-unrestricted\fP .RS 4 این پرچم سطح پالایش «هوشمند» را کاهش می‌دهد. استفادهٔ چندباره (تا ۳ بار) پالایش را از این هم کمتر می‌کند. در صورت تکرار به تعداد سه بار، ripgrep تک‌تک فایل‌های موجود در ساختار درختی دایرکتوری را جستجو خواهد کرد. .sp یک بار استفاده از پرچم \fB\-u/\-\-unrestricted\fP معادل \fB\-\-no\-ignore\fP است. دو بار استفاده از \fB\-u/\-\-unrestricted\fP معادل \fB\-\-no\-ignore\fP \fB\-./\-\-hidden\fP خواهد بود. سه بار استفاده از آن معادل \fB\-\-no\-ignore\fP \fB\-./\-\-hidden\fP \fB\-\-binary\fP است. .sp تنها پالایشی که ripgrep حتی در هنگام استفاده از \fB-uuu\fP همچنان انجام می‌دهد، نادیده گرفتن پیوندهای نمادین و جلوگیری از چاپ تطابق‌های مربوط به فایل‌های دودویی است. پیوندهای نمادین را می‌توان با پرچم \fB\-L/\-\-follow\fP دنبال کرد و با فایل‌های دودویی نیز می‌توان از طریق پرچم \fB\-a/\-\-text\fP مانند فایل‌های متنی رفتار نمود. .RE.SS "گزینه‌های خروجی (OUTPUT OPTIONS)" \fB\-A\fP \fINUM\fP, \fB\-\-after\-context\fP=\fINUM\fP .RS 4 نمایش \fINUM\fP خط پس از هر تطابق. .sp این گزینه پرچم \fB\-\-passthru\fP را لغو کرده و بخشی از پرچم \fB\-C/\-\-context\fP را نادیده می‌گیرد. .RE .sp \fB\-B\fP \fINUM\fP, \fB\-\-before\-context\fP=\fINUM\fP .RS 4 نمایش \fINUM\fP خط پیش از هر تطابق. .sp این گزینه پرچم \fB\-\-passthru\fP را لغو کرده و بخشی از پرچم \fB\-C/\-\-context\fP را نادیده می‌گیرد. .RE .sp \fB\-\-block\-buffered\fP .RS 4 در صورت فعال بودن، ripgrep از بافرینگ بلوکی استفاده خواهد کرد؛ بدین معنی که به محض یافتن یک خط منطبق، آن را در یک بافر در حافظه می‌نویسد و تا زمانی که بافر به اندازه مشخصی نرسد، آن را در stdout نخواهد نوشت. هنگامی که خروجی استاندارد ripgrep به یک لوله یا یک فایل هدایت شود، این حالت پیش‌فرض است. زمانی که stdout به یک tty متصل باشد، بافرینگ خطی به صورت پیش‌فرض استفاده می‌شود. اجبار بافرینگ بلوکی می‌تواند هنگام ارسال حجم بالایی از محتوا به یک tty مفید باشد. .sp این گزینه پرچم \fB\-\-line\-buffered\fP را لغو می‌کند. .sp این پرچم را می‌توان با \fB\-\-no-block-buffered\fP غیرفعال کرد. .RE .sp \fB\-b\fP, \fB\-\-byte\-offset\fP .RS 4 چاپ آفست بایتی (مبتنی بر صفر) در فایل ورودی پیش از هر خط خروجی. اگر \fB\-o/\-\-only\-matching\fP مشخص شده باشد، آفستِ خود متن منطبق‌شده چاپ می‌شود. .sp اگر ripgrep تبدیل کدبندی (transcoding) انجام دهد، آفست بایتی بر اساس نتیجه تبدیل کدبندی محاسبه می‌شود و نه داده‌های اصلی. این موضوع به همین شکل برای سایر دگرگونی‌های اعمال‌شده روی داده‌ها، مانند فشرده‌زدایی یا فیلتر \fB\-\-pre\fP نیز صدق می‌کند. .sp این پرچم را می‌توان با \fB\-\-no-byte-offset\fP غیرفعال کرد. .RE .sp \fB\-\-color\fP=\fIWHEN\fP .RS 4 این پرچم زمان استفاده از رنگ‌ها را کنترل می‌کند. مقدار پیش‌فرض \fBauto\fP است، بدین معنی که ripgrep تلاش می‌کند زمان استفاده از رنگ را تشخیص دهد. برای مثال، اگر ripgrep در یک tty خروجی دهد، از رنگ‌ها استفاده می‌کند، اما اگر خروجی به یک فایل یا لوله هدایت شود، خروجی رنگی غیرفعال خواهد شد. .sp همچنین ripgrep در برخی شرایط دیگر نیز به‌طور پیش‌فرض خروجی رنگی را غیرفعال می‌کند؛ از جمله موارد زیر، ولی نه محدود به آن‌ها: .sp .IP \(bu 3n زمانی که متغیر محیطی \fBTERM\fP تنظیم نشده باشد یا برابر با \fBdumb\fP باشد. .sp .IP \(bu 3n زمانی که متغیر محیطی \fBNO_COLOR\fP تنظیم شده باشد (صرف‌نظر از مقدار آن). .sp .IP \(bu 3n زمانی که پرچم‌هایی داده شوند که حاکی از عدم استفاده از رنگ هستند؛ به عنوان مثال \fB\-\-vimgrep\fP و \fB\-\-json\fP. . .PP مقادیر ممکن برای این پرچم عبارتند از: .sp .IP \fBnever\fP 10n رنگ‌ها هرگز استفاده نخواهند شد. .sp .IP \fBauto\fP 10n حالت پیش‌فرض. ripgrep تلاش می‌کند هوشمندانه عمل کند. .sp .IP \fBalways\fP 10n رنگ‌ها همیشه استفاده خواهند شد، صرف‌نظر از این‌که خروجی به کجا ارسال می‌شود. .sp .IP \fBansi\fP 10n مشابه 'always'، اما کدهای گریز ANSI را تولید می‌کند (حتی در کنسول ویندوز). . .PP این پرچم همچنین تولید ابرپیوندها (hyperlinks) را کنترل می‌کند. به عنوان مثال، اگر یک قالب ابرپیوند مشخص شده باشد، در صورت غیرفعال بودن رنگ، ابرپیوندها استفاده نخواهند شد. اگر می‌خواهید ابرپیوندها تولید شوند اما رنگی نباشند، باید از پرچم \fB\-\-colors\fP برای تنظیم دستی تمام سبک‌های رنگ روی \fBnone\fP استفاده کنید: .sp .EX \-\-colors 'path:none' \\ \-\-colors 'line:none' \\ \-\-colors 'column:none' \\ \-\-colors 'match:none' \\ \-\-colors 'highlight:none' .EE .sp .RE .sp \fB\-\-colors\fP=\fICOLOR_SPEC\fP .RS 4 این پرچم تنظیمات رنگ را برای استفاده در خروجی مشخص می‌کند. این پرچم می‌تواند چندین بار داده شود. تنظیمات به صورت تکرارشونده اعمال می‌شوند. برچسب‌های رنگی از پیش موجود به یکی از هشت گزینه محدود هستند: \fBred\fP، \fBblue\fP، \fBgreen\fP، \fBcyan\fP، \fBmagenta\fP، \fByellow\fP، \fBwhite\fP و \fBblack\fP. سبک‌ها محدود به \fBnobold\fP، \fBbold\fP، \fBnointense\fP، \fBintense\fP، \fBnounderline\fP، \fBunderline\fP، \fBnoitalic\fP یا \fBitalic\fP هستند. .sp قالب این پرچم به صورت \fB{\fP\fItype\fP\fB}:{\fP\fIattribute\fP\fB}:{\fP\fIvalue\fP\fB}\fP است. مقدار \fItype\fP باید یکی از \fBpath\fP، \fBline\fP، \fBcolumn\fP، \fBhighlight\fP یا \fBmatch\fP باشد. مقدار \fIattribute\fP می‌تواند \fBfg\fP، \fBbg\fP یا \fBstyle\fP باشد. مقدار \fIvalue\fP یا یک رنگ (برای \fBfg\fP و \fBbg\fP) یا یک سبک متن است. قالب ویژه \fB{\fP\fItype\fP\fB}:none\fP تمام تنظیمات رنگی مربوط به \fItype\fP را پاک می‌کند. .sp به عنوان مثال، دستور زیر رنگ تطابق را به سرخابی و رنگ پس‌زمینه شماره خطوط را به زرد تغییر می‌دهد: .sp .EX rg \-\-colors 'match:fg:magenta' \-\-colors 'line:bg:yellow' .EE .sp مثالی دیگر، دستور زیر متن غیرمنطبق در خطوط منطبق را «برجسته» (highlight) می‌کند: .sp .EX rg \-\-colors 'highlight:bg:yellow' \-\-colors 'highlight:fg:black' .EE .sp نوع رنگی "highlight" به‌ویژه برای ایجاد تمایز بین خطوط منطبق و سیاق پیرامونی چاپ‌شده توسط پرچم‌های \fB\-B/\-\-before\-context\fP، \fB\-A/\-\-after\-context\fP، \fB\-C/\-\-context\fP یا \fB\-\-passthru\fP مفید است. .sp هنگامی که tty از توالی‌های رنگی ANSI پشتیبانی کند، می‌توان از رنگ‌های گسترش‌یافته برای \fIvalue\fP استفاده کرد. این مقادیر یا به صورت \fIx\fP (256 رنگ) یا .IB x , x , x (رنگ حقیقی ۲۴ بیتی / truecolor) مشخص می‌شوند که در آن \fIx\fP عددی بین \fB0\fP تا \fB255\fP (شامل هر دو) است. \fIx\fP می‌تواند به عنوان یک عدد ده‌دهی عادی یا یک عدد هگزادسیمال با پیشوند \fB0x\fP مشخص شود. .sp به عنوان مثال، دستور زیر رنگ پس‌زمینه تطابق را به مقدار rgb یعنی (0,128,255) تغییر می‌دهد: .sp .EX rg \-\-colors 'match:bg:0,128,255' .EE .sp یا به‌طور معادل: .sp .EX rg \-\-colors 'match:bg:0x0,0x80,0xFF' .EE .sp توجه داشته باشید که سبک‌های \fBintense\fP و \fBnointense\fP هنگام استفاده در کنار این کدهای رنگی گسترش‌یافته هیچ اثری نخواهند داشت. .RE .sp \fB\-\-column\fP .RS 4 نمایش شماره ستون‌ها (مبتنی بر ۱). این گزینه تنها شماره ستون را برای نخستین تطابق در هر خط نمایش می‌دهد. این پرچم کاراکترهای یونیکد را در نظر نمی‌گیرد؛ یک بایت معادل با یک ستون است. این گزینه مستلزم \fB\-n/\-\-line\-number\fP است. .sp هنگامی که \fB\-o/\-\-only\-matching\fP استفاده شود، شماره ستون‌های درج‌شده منطبق بر شروع هر تطابق خواهند بود. .sp این پرچم را می‌توان با \fB\-\-no-column\fP غیرفعال کرد. .RE .sp \fB\-C\fP \fINUM\fP, \fB\-\-context\fP=\fINUM\fP .RS 4 نمایش \fINUM\fP خط پیش و پس از هر تطابق. این معادل با ارائه هم‌زمان هر دو پرچم \fB\-B/\-\-before\-context\fP و \fB\-A/\-\-after\-context\fP با مقداری یکسان است. .sp این گزینه پرچم \fB\-\-passthru\fP را لغو می‌کند. هر دو پرچم \fB\-A/\-\-after\-context\fP و \fB\-B/\-\-before\-context\fP، صرف‌نظر از ترتیب، بخشی از این پرچم را لغو می‌کنند. برای مثال، \fB\-A2 \-C1\fP معادل با \fB\-A2 \-B1\fP است. .RE .sp \fB\-\-context\-separator\fP=\fISEPARATOR\fP .RS 4 رشته مورد استفاده برای جداسازی خطوط سیاق غیرپیوسته در خروجی. این فقط زمانی استفاده می‌شود که یکی از پرچم‌های سیاق استفاده شده باشد (یعنی \fB\-A/\-\-after\-context\fP، \fB\-B/\-\-before\-context\fP یا \fB\-C/\-\-context\fP). توالی‌های گریز مانند \fB\\x7F\fP یا \fB\\t\fP قابل استفاده هستند. مقدار پیش‌فرض \fB\-\-\fP است. .sp زمانی که جداکننده سیاق روی یک رشته خالی تنظیم شود، همچنان یک خط جدید درج می‌شود. برای غیرفعال کردن کامل جداکننده‌های سیاق، از پرچم \fB\-\-no-context-separator\fP استفاده کنید. .RE .sp \fB\-\-field\-context\-separator\fP=\fISEPARATOR\fP .RS 4 تنظیم جداکننده فیلدهای سیاق. این جداکننده فقط هنگام چاپ خطوط سیاق استفاده می‌شود. از آن برای تفکیک مسیر فایل‌ها، شماره خطوط، ستون‌ها و خود خط سیاق استفاده می‌شود. جداکننده می‌تواند شامل هر تعداد بایت، از جمله صفر باشد. توالی‌های گریز مانند \fB\\x7F\fP یا \fB\\t\fP قابل استفاده هستند. .sp نویسه \fB-\fP مقدار پیش‌فرض است. .RE .sp \fB\-\-field\-match\-separator\fP=\fISEPARATOR\fP .RS 4 تنظیم جداکننده فیلدهای تطابق. این جداکننده فقط هنگام چاپ خطوط منطبق استفاده می‌شود. از آن برای تفکیک مسیر فایل‌ها، شماره خطوط، ستون‌ها و خود خط منطبق استفاده می‌شود. جداکننده می‌تواند شامل هر تعداد بایت، از جمله صفر باشد. توالی‌های گریز مانند \fB\\x7F\fP یا \fB\\t\fP قابل استفاده هستند. .sp نویسه \fB:\fP مقدار پیش‌فرض است. .RE .sp \fB\-\-heading\fP .RS 4 این پرچم به جای چاپ مسیر فایل به عنوان پیشوند برای هر خط منطبق، مسیر فایل را بالای دسته‌های تطابق هر فایل چاپ می‌کند. .sp این حالت، حالت پیش‌فرض هنگام چاپ روی یک tty است. .sp هنگامی که \fBstdout\fP یک tty نباشد، ripgrep به‌طور پیش‌فرض به قالب استاندارد شبه-grep بازمی‌گردد. در محیط‌های شبه‌یونیکس می‌توان با ارسال خروجی ripgrep از طریق لوله به \fBcat\fP این قالب را اجبار کرد. برای مثال، \fBrg\fP \fIfoo\fP \fB| cat\fP. .sp این پرچم را می‌توان با \fB\-\-no-heading\fP غیرفعال کرد. .RE .sp \fB\-h\fP, \fB\-\-help\fP .RS 4 این پرچم خروجی راهنما را برای ripgrep چاپ می‌کند. .sp برخلاف اغلب پرچم‌های دیگر، رفتار پرچم کوتاه، \fB\-h\fP، و پرچم بلند، \fB\-\-help\fP، متفاوت است. پرچم کوتاه خروجی راهنمای فشرده و خلاصه‌ای را نشان می‌دهد، در حالی که پرچم بلند خروجی راهنمای جامع و کامل را نمایش خواهد داد. خروجی راهنمای جامع شامل مستندات کامل است، در حالی که خروجی راهنمای فشرده برای هر پرچم تنها یک خط نمایش می‌دهد. .RE .sp \fB\-\-hostname\-bin\fP=\fICOMMAND\fP .RS 4 این پرچم نحوه تعیین نام میزبان این سیستم توسط ripgrep را کنترل می‌کند. مقدار پرچم باید مربوط به یک فایل اجرایی باشد (خواه یک مسیر کامل یا دستوری که از طریق متغیر محیطی \fBPATH\fP سیستم قابل یافتن باشد). هنگام تنظیم، ripgrep این فایل اجرایی را بدون هیچ آرگومانی اجرا کرده و خروجی آن را (پس از حذف فاصله‌های خالی ابتدا و انتها) به عنوان نام میزبان سیستم شما در نظر می‌گیرد. .sp در صورت عدم تنظیم (حالت پیش‌فرض، یا یک رشته خالی)، ripgrep تلاش می‌کند تا نام میزبان سیستم را به‌طور خودکار تشخیص دهد. در یونیکس، این معادل فراخوانی \fBgethostname\fP است. در ویندوز، این معادل فراخوانی \fBGetComputerNameExW\fP برای دریافت "physical DNS hostname" سیستم است. .sp ابزار ripgrep از نام میزبان سیستم برای تولید ابرپیوندها استفاده می‌کند. .RE .sp \fB\-\-hyperlink\-format\fP=\fIFORMAT\fP .RS 4 تنظیم قالب ابرپیوندهای مورد استفاده هنگام چاپ نتایج. ابرپیوندها عناصر خاصی از خروجی ripgrep، مانند مسیر فایل‌ها را قابل کلیک می‌کنند. این قابلیت عموماً تنها در شبیه‌سازهای ترمینالی که از ابرپیوندهای OSC-8 پشتیبانی می‌کنند کار می‌کند. برای مثال، قالب \fBfile://{host}{path}\fP یک ابرپیوند منطبق بر RFC 8089 تولید می‌کند. برای دیدن قالبی که ripgrep استفاده می‌کند، پرچم \fB\-\-debug\fP را بدهید. .sp همچنین، یک رشته قالب می‌تواند متناظر با یکی از نام‌های مستعار زیر باشد: \fBdefault\fP، \fBnone\fP، \fBcursor\fP، \fBfile\fP، \fBgrep+\fP، \fBkitty\fP، \fBmacvim\fP، \fBtextmate\fP، \fBvscode\fP، \fBvscode-insiders\fP، \fBvscodium\fP. این نام مستعار با رشته قالبی جایگزین خواهد شد که برای کار با برنامه مربوطه در نظر گرفته شده است. .sp متغیرهای زیر در رشته قالب در دسترس هستند: .sp.TP 12 \fB{path}\fP اجباری. با مسیر پروندهٔ منطبق جایگزین می‌شود. تضمین می‌شود که مسیر مطلق و کُدگذاری‌شده به‌صورت درصدی (percent encoded) باشد، به‌گونه‌ای که برای قرار گرفتن در یک URI معتبر باشد. توجه داشته باشید که تضمین می‌شود مسیر با یک / آغاز شود. .TP 12 \fB{host}\fP اختیاری. با نام میزبان (hostname) سامانهٔ شما جایگزین می‌شود. در Unix، این با فراخوانی \fBgethostname\fP مطابقت دارد. در Windows، این متناظر با فراخوانی \fBGetComputerNameExW\fP برای واکشی «نام میزبان فیزیکی DNS» سامانه است. همچنین اگر \fB\-\-hostname\-bin\fP ارائه شده باشد، نام میزبان بازگردانده‌شده از خروجی آن برنامه استفاده خواهد شد. اگر هیچ نام میزبانی یافت نشود، این متغیر با یک رشتهٔ خالی جایگزین می‌شود. .TP 12 \fB{line}\fP اختیاری. در صورت تناسب، با شماره خط تطابق جایگزین می‌شود. اگر هیچ شماره خطی در دسترس نباشد (برای نمونه، اگر \fB\-\-no\-line\-number\fP داده شده باشد)، به‌طور خودکار با مقدار 1 جایگزین می‌شود. .TP 12 \fB{column}\fP اختیاری، اما نیازمند حضور \fB{line}\fP است. در صورت تناسب، با شماره ستون تطابق جایگزین می‌شود. اگر هیچ شماره ستونی در دسترس نباشد (برای نمونه، اگر \fB\-\-no\-column\fP داده شده باشد)، به‌طور خودکار با مقدار 1 جایگزین می‌شود. .TP 12 \fB{wslprefix}\fP اختیاری. این یک مقدار ویژه است که بر روی \fBwsl$/\fP\fIWSL_DISTRO_NAME\fP تنظیم می‌شود، جایی که \fIWSL_DISTRO_NAME\fP با مقدار متغیر محیطی معادل مطابقت دارد. اگر سامانه Unix نباشد یا متغیر محیطی \fIWSL_DISTRO_NAME\fP تنظیم نشده باشد، این متغیر با یک رشتهٔ خالی جایگزین می‌شود. .PP رشته قالب (format string) می‌تواند خالی باشد. یک رشته قالب خالی معادل نام مستعار \fBnone\fP است. در این حالت، پیوندها (hyperlinks) غیرفعال خواهند شد. .sp در حال حاضر، ripgrep به‌طور پیش‌فرض پیوندها را فعال نمی‌کند. کاربران باید خودشان آن‌ها را فعال کنند. اگر مطمئن نیستید از چه قالبی استفاده کنید، \fBdefault\fP را امتحان کنید. .sp همانند رنگ‌ها، هنگامی که ripgrep تشخیص دهد خروجی استاندارد (stdout) به یک tty متصل نیست، پیوندها بدون توجه به مقدار این پرچم به‌طور خودکار غیرفعال می‌شوند. کاربران می‌توانند \fB\-\-color=always\fP را ارسال کنند تا درج پیوندها اجباری شود. .sp توجه داشته باشید که پیوندها تنها زمانی نوشته می‌شوند که یک مسیر نیز در خروجی وجود داشته باشد و رنگ‌ها فعال باشند. برای نوشتن پیوندها بدون رنگ، باید ripgrep را طوری پیکربندی کنید که هیچ‌چیز را رنگ‌آمیزی نکند بدون اینکه تمام کدهای گریز ANSI را کلاً غیرفعال کند: .sp .EX \-\-colors 'path:none' \\ \-\-colors 'line:none' \\ \-\-colors 'column:none' \\ \-\-colors 'match:none' .EE .sp دلیل این سازوکار ripgrep این است که پرچم \fB\-\-color\fP را به‌عنوان معیاری برای مجاز بودن یا نبودن استفاده از کدهای گریز ANSI در نظر می‌گیرد. این بدان معناست که متغیرهای محیطی مانند \fBNO_COLOR=1\fP و \fBTERM=dumb\fP نه‌تنها رنگ‌ها، بلکه پیوندها را نیز غیرفعال می‌کنند. به‌طور مشابه، زمانی که ripgrep در یک tty نمی‌نویسد، رنگ‌ها و پیوندها غیرفعال می‌شوند (مگر اینکه با تنظیم \fB\-\-color=always\fP این رفتار اجباری شود). .sp اگر مستقیماً در یک پرونده جستجو می‌کنید، برای نمونه: .sp .EX rg foo path/to/file .EE .sp در این صورت پیوندها درج نخواهند شد، زیرا مسیر داده‌شده در خروجی ظاهر نمی‌شود. برای نمایان شدن مسیر و در نتیجه پیوند، از پرچم \fB\-H/\-\-with\-filename\fP استفاده کنید. .sp برای اطلاعات بیشتر در مورد پیوندها در شبیه‌سازهای پایانه، ببینید: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda .RE .sp \fB\-\-include\-zero\fP .RS 4 هنگامی که همراه با \fB\-c/\-\-count\fP یا \fB\-\-count\-matches\fP استفاده شود، باعث می‌شود ripgrep تعداد تطابق‌ها را برای هر پرونده چاپ کند، حتی اگر هیچ تطابقی (صفر مورد) وجود نداشته باشد. این گزینه به‌طور پیش‌فرض غیرفعال است اما می‌تواند فعال شود تا رفتار ripgrep بیشتر شبیه به grep شود. .sp این پرچم را می‌توان با \fB\-\-no-include-zero\fP غیرفعال کرد. .RE .sp \fB\-\-line\-buffered\fP .RS 4 هنگام فعال بودن، ripgrep همواره از میان‌گیر خطی (line buffering) استفاده خواهد کرد؛ بدین معنی که هر زمان خط منطبقی یافت شود، بلافاصله به stdout ارسال (flush) می‌شود. این حالت پیش‌فرضِ ripgrep هنگام اتصال stdout به tty است، اما در غیر این صورت، ripgrep از میان‌گیر بلوکی (block buffering) استفاده می‌کند که معمولاً سریع‌تر است. این پرچم ripgrep را مجبور به استفاده از میان‌گیر خطی می‌کند حتی در شرایطی که در حالت عادی از میان‌گیر بلوکی استفاده می‌کرد. این گزینه معمولاً در خط‌لوله‌های (pipelines) پوسته مفید است، برای نمونه: .sp .EX tail -f something.log | rg foo --line-buffered | rg bar .EE .sp این گزینه بر پرچم \fB\-\-block\-buffered\fP ارجحیت دارد. .sp این پرچم را می‌توان با \fB\-\-no-line-buffered\fP غیرفعال کرد. .RE .sp \fB\-n\fP, \fB\-\-line\-number\fP .RS 4 نمایش شمارهٔ خطوط (بر پایهٔ ۱). .sp این گزینه هنگامی که stdout به یک tty متصل باشد به‌طور پیش‌فرض فعال است. .sp این پرچم را می‌توان با \fB\-N/\-\-no\-line\-number\fP غیرفعال کرد. .RE .sp \fB\-N\fP, \fB\-\-no\-line\-number\fP .RS 4 عدم نمایش شمارهٔ خطوط. .sp هنگامی که stdout به tty متصل نباشد، شمارهٔ خطوط به‌طور پیش‌فرض خاموش هستند. .sp شمارهٔ خطوط را می‌توان با \fB\-n/\-\-line\-number\fP به‌طور اجباری فعال کرد. .RE .sp \fB\-M\fP \fINUM\fP, \fB\-\-max\-columns\fP=\fINUM\fP .RS 4 در صورت تعیین، ripgrep خطوط طولانی‌تر از این حد (برحسب بایت) را نادیده می‌گیرد. به جای چاپ خطوط طولانی، تنها تعداد تطابق‌های موجود در آن خط چاپ می‌شود. .sp هنگامی که این پرچم تعیین نشود یا روی \fB0\fP تنظیم شود، هیچ اثری نخواهد داشت. .RE .sp \fB\-\-max\-columns\-preview\fP .RS 4 پیش‌نمایشی از خطوطی که از حد مجاز ستون‌ها فراتر می‌روند چاپ می‌کند. .sp هنگام استفاده از پرچم \fB\-M/\-\-max\-columns\fP، ripgrep به‌طور پیش‌فرض هر خط بیش از حد طولانی را کاملاً با پیامی مبنی بر حذف یک خط منطبق جایگزین می‌کند. هنگامی که این پرچم با \fB\-M/\-\-max\-columns\fP ترکیب شود، به جای آن پیش‌نمایشی از خط (متناظر با اندازهٔ حد تعیین‌شده) نمایش داده می‌شود، که در آن بخش فراتر از حد مجازِ خط نشان داده نمی‌شود. .sp اگر پرچم \fB\-M/\-\-max\-columns\fP تنظیم نشده باشد، این گزینه هیچ اثری ندارد. .sp این پرچم را می‌توان با \fB\-\-no-max-columns-preview\fP غیرفعال کرد. .RE .sp \fB\-0\fP, \fB\-\-null\fP .RS 4 هر زمان که یک مسیر پرونده چاپ می‌شود، یک بایت \fBNUL\fP به دنبال آن قرار می‌گیرد. این شامل چاپ مسیر پرونده‌ها پیش از تطابق‌ها و هنگام چاپ فهرستی از پرونده‌های منطبق مانند \fB\-c/\-\-count\fP، \fB\-l/\-\-files\-with\-matches\fP و \fB\-\-files\fP می‌شود. این گزینه برای استفاده به‌همراه \fBxargs\fP بسیار کاربردی است. .RE .sp \fB\-o\fP, \fB\-\-only\-matching\fP .RS 4 تنها بخش‌های منطبق‌شده (غیرخالی) از یک خط منطبق را چاپ می‌کند، به‌طوری که هر بخش در یک خط خروجی جداگانه قرار می‌گیرد. .RE .sp \fB\-\-path\-separator\fP=\fISEPARATOR\fP .RS 4 جداکنندهٔ مسیر را برای استفاده هنگام چاپ مسیر پرونده‌ها مشخص می‌کند. مقدار پیش‌فرض آن بر اساس بستر اجرایی شما تعیین می‌شود، که در Unix برابر \fB/\fP و در Windows برابر \fB\\\fP است. این پرچم برای لغو حالت پیش‌فرض در شرایطی که محیط نیاز دارد (برای نمونه cygwin) در نظر گرفته شده است. جداکنندهٔ مسیر محدود به یک بایت منفرد است. .sp تنظیم این پرچم روی یک رشتهٔ خالی، رفتار آن را به حالت پیش‌فرض بازمی‌گرداند؛ یعنی جداکنندهٔ مسیر به‌طور خودکار بر اساس محیط انتخاب می‌شود. .RE .sp \fB\-\-passthru\fP .RS 4 هر دو نوع خطوط منطبق و غیرمنطبق را چاپ می‌کند. .sp روش دیگر برای دستیابی به اثری مشابه، تغییر الگوی جستجو برای تطابق با رشتهٔ خالی است. برای نمونه، اگر با \fBrg\fP \fIfoo\fP جستجو می‌کنید، استفاده از \fBrg\fP \fB'^|\fP\fIfoo\fP\fB'\fP به جای آن باعث چاپ تمام خطوط در تمامی پرونده‌های مورد جستجو می‌شود، اما فقط نمونه‌های \fIfoo\fP برجسته خواهند شد. این پرچم بدون نیاز به تغییر الگو، همین رفتار را فراهم می‌کند. .sp نگارش دیگر این پرچم \fB\-\-passthrough\fP است. .sp این گزینه بر پرچم‌های \fB\-C/\-\-context\fP، \fB\-A/\-\-after\-context\fP و \fB\-B/\-\-before\-context\fP ارجحیت دارد. .RE .sp \fB\-p\fP, \fB\-\-pretty\fP .RS 4 این یک نام مستعار برای دسترسی راحت‌تر به \fB\-\-color=always \-\-heading \-\-line\-number\fP است. این پرچم زمانی مفید است که حتی در صورت هدایت خروجی ripgrep به برنامه‌ای دیگر یا یک پرونده، خروجی آراسته و خوانا می‌خواهید. برای نمونه: \fBrg -p \fP\fIfoo\fP \fB| less -R\fP. .RE .sp \fB\-q\fP, \fB\-\-quiet\fP .RS 4 هیچ چیزی در stdout چاپ نمی‌کند. اگر تطابقی در یک پرونده پیدا شود، ripgrep جستجو را متوقف می‌کند. این پرچم زمانی کاربرد دارد که ripgrep تنها به خاطر کد خروجش استفاده می‌شود (که در صورت عدم یافتن تطابق، یک کد خطا خواهد بود). .sp هنگام استفاده از \fB\-\-files\fP، پس از یافتن نخستین پرونده‌ای که با هیچ قاعدهٔ نادیده‌گیری (ignore rules) مطابقت ندارد، ripgrep جستجوی پرونده‌ها را متوقف می‌کند. .RE .sp \fB\-r\fP \fIREPLACEMENT\fP, \fB\-\-replace\fP=\fIREPLACEMENT\fP .RS 4 هنگام چاپ نتایج، هر تطابق را با متن ارائه‌شده جایگزین می‌کند. نه این پرچم و نه هیچ پرچم دیگری در ripgrep پرونده‌های شما را تغییر نخواهند داد. .sp اندیس‌های گروه‌های گیرش (برای نمونه \fB$\fP\fI5\fP) و نام‌ها (برای نمونه \fB$\fP\fIfoo\fP) در رشتهٔ جایگزینی پشتیبانی می‌شوند. شماره‌گذاری اندیس‌های گروه‌های گیرش بر پایهٔ موقعیت پرانتز بازکنندهٔ گروه انجام می‌شود، به این صورت که چپ‌ترین گروه \fB$\fP\fI1\fP است. گروه ویژهٔ \fB$\fP\fI0\fP با کل تطابق متناظر است. .sp نام یک گروه از طولانی‌ترین رشته‌ای از حروف، ارقام و زیرخط‌ها (یعنی \fB[_0-9A-Za-z]\fP) پس از \fB$\fP تشکیل می‌شود. برای نمونه، \fB$\fP\fI1a\fP با گروهی به نام \fI1a\fP جایگزین خواهد شد، نه با گروه دارای اندیس \fI1\fP. اگر نام گروه شامل نویسه‌هایی غیر از حروف، اعداد یا زیرخط باشد، یا بخواهید بلافاصله پس از گروه یک رشتهٔ دیگر قرار دهید، باید نام داخل آکولاد قرار گیرد. برای نمونه، \fB${\fP\fI1\fP\fB}\fP\fIa\fP محتوای گروه در اندیس \fI1\fP را گرفته و \fIa\fP را به انتهای آن اضافه می‌کند. .sp اگر یک اندیس یا نام به یک گروه گیرش معتبر اشاره نکند، با یک رشتهٔ خالی جایگزین می‌شود. .sp در پوسته‌هایی مانند Bash و zsh، باید الگو را به جای نقل‌قول دوتایی (double quotes) درون نقل‌قول تکی (single quotes) قرار دهید. در غیر این صورت، اندیس‌های گروه‌های گیرش با متغیرهای گسترش‌یافتهٔ پوسته که احتمالاً خالی هستند جایگزین خواهند شد. .sp برای نوشتن نویسهٔ واقعی \fB$\fP، از \fB$$\fP استفاده کنید. .sp توجه داشته باشید که جایگزینی به‌طور پیش‌فرض هر تطابق را جایگزین می‌کند، نه کل خط را. برای جایگزینی کل خط، باید کل خط را تطبیق دهید. .sp این پرچم می‌تواند همراه با پرچم \fB\-o/\-\-only\-matching\fP استفاده شود. .RE .sp \fB\-\-sort\fP=\fISORTBY\fP .RS 4 این پرچم مرتب‌سازی صعودی نتایج را فعال می‌کند. مقادیر ممکن برای این پرچم عبارت‌اند از: .sp.TP 12 \fBnone\fP (پیش‌فرض) نتایج را مرتب نمی‌کند. سریع‌ترین حالت است و می‌تواند به‌صورت چندنخی اجرا شود. .TP 12 \fBpath\fP بر اساس مسیر فایل مرتب می‌کند. همیشه تک‌نخی است. ترتیب با مرتب‌سازی فایل‌ها در هر مدخل دایرکتوری در هنگام پیمایش تعیین می‌شود. این بدان معناست که در صورت وجود فایل‌های \fBa/b\fP و \fBa+\fP، دومی پس از اولی مرتب خواهد شد، حتی اگر معمولاً \fB+\fP پیش از \fB/\fP مرتب شود. .TP 12 \fBmodified\fP بر اساس آخرین زمان تغییر فایل مرتب می‌کند. همیشه تک‌نخی است. .TP 12 \fBaccessed\fP بر اساس آخرین زمان دسترسی به فایل مرتب می‌کند. همیشه تک‌نخی است. .TP 12 \fBcreated\fP بر اساس زمان ایجاد فایل مرتب می‌کند. همیشه تک‌نخی است. .PP اگر معیار مرتب‌سازی انتخاب‌شده (به‌صورت دستی یا پیش‌فرض) در سیستم شما در دسترس نباشد (برای مثال، زمان ایجاد در سیستم‌های فایل ext4 در دسترس نیست)، آنگاه ripgrep تلاش می‌کند تا این موضوع را تشخیص دهد، خطایی چاپ کند و بدون جستجو خارج شود. .sp برای مرتب‌سازی معکوس یا نزولی نتایج، از پرچم \fB\-\-sortr\fP استفاده کنید. همچنین این پرچم \fB\-\-sortr\fP را لغو می‌کند. .sp توجه داشته باشید که مرتب‌سازی نتایج در حال حاضر همواره ripgrep را مجبور می‌کند پردازش موازی را کنار بگذارد و در قالب یک تک‌نخ اجرا شود. .RE .sp \fB\-\-sortr\fP=\fISORTBY\fP .RS 4 این پرچم مرتب‌سازی نتایج را به ترتیب نزولی فعال می‌کند. مقادیر ممکن برای این پرچم عبارتند از: .sp .TP 12 \fBnone\fP (پیش‌فرض) نتایج را مرتب نمی‌کند. سریع‌ترین حالت است و می‌تواند به‌صورت چندنخی اجرا شود. .TP 12 \fBpath\fP بر اساس مسیر فایل مرتب می‌کند. همیشه تک‌نخی است. ترتیب با مرتب‌سازی فایل‌ها در هر مدخل دایرکتوری در هنگام پیمایش تعیین می‌شود. این بدان معناست که در صورت وجود فایل‌های \fBa/b\fP و \fBa+\fP، دومی پیش از اولی مرتب خواهد شد، حتی اگر معمولاً در هنگام مرتب‌سازی لغت‌نگاشتی معکوس، \fB+\fP پس از \fB/\fP قرار گیرد. .TP 12 \fBmodified\fP بر اساس آخرین زمان تغییر فایل مرتب می‌کند. همیشه تک‌نخی است. .TP 12 \fBaccessed\fP بر اساس آخرین زمان دسترسی به فایل مرتب می‌کند. همیشه تک‌نخی است. .TP 12 \fBcreated\fP بر اساس زمان ایجاد فایل مرتب می‌کند. همیشه تک‌نخی است. .PP اگر معیار مرتب‌سازی انتخاب‌شده (به‌صورت دستی یا پیش‌فرض) در سیستم شما در دسترس نباشد (برای مثال، زمان ایجاد در سیستم‌های فایل ext4 در دسترس نیست)، آنگاه ripgrep تلاش می‌کند تا این موضوع را تشخیص دهد، خطایی چاپ کند و بدون جستجو خارج شود. .sp برای مرتب‌سازی نتایج به ترتیب صعودی، از پرچم \fB\-\-sort\fP استفاده کنید. همچنین این پرچم \fB\-\-sort\fP را لغو می‌کند. .sp توجه داشته باشید که مرتب‌سازی نتایج در حال حاضر همواره ripgrep را مجبور می‌کند پردازش موازی را کنار بگذارد و در قالب یک تک‌نخ اجرا شود. .RE .sp \fB\-\-trim\fP .RS 4 در صورت فعال بودن، تمام فاصله‌های خالی (whitespace) اسکی (ASCII) در ابتدای هر خط چاپ‌شده حذف خواهند شد. .sp این پرچم را می‌توان با \fB\-\-no-trim\fP غیرفعال کرد. .RE .sp \fB\-\-vimgrep\fP .RS 4 این پرچم به ripgrep دستور می‌دهد نتایج را به گونه‌ای چاپ کند که هر تطابق در خط اختصاصی خود به همراه شماره خط و شماره ستون قرار گیرد. .sp با این گزینه، خطی که بیش از یک تطابق داشته باشد به طور کامل بیش از یک بار چاپ خواهد شد. به همین دلیل، حجم کل خروجی حاصل از این پرچم می‌تواند نسبت به اندازه ورودی به صورت درجه دو (quadratic) باشد. برای مثال، اگر الگو با تک‌تک بایت‌های یک فایل ورودی تطابق داشته باشد، آنگاه هر خط به ازای هر بایت منطبق تکرار خواهد شد. از این رو، کاربران تنها زمانی باید از این پرچم استفاده کنند که چاره دیگری وجود نداشته باشد. ادغام‌های ویرایشگر باید روش‌های دیگری را برای خواندن نتایج از ripgrep ترجیح دهند، مانند استفاده از پرچم \fB\-\-json\fP. یک راهکار جایگزین برای جلوگیری از مصرف بیش از حد حافظه این است که ripgrep را با پرچم \fB\-j/\-\-threads\fP مجبور به کار در حالت تک‌نخی کنید. البته توجه داشته باشید که این کار بر حجم کل خروجی تأثیری ندارد و فقط بر حافظه هیپ (heap memory) مورد استفاده ripgrep اثر می‌گذارد. .RE .sp \fB\-H\fP, \fB\-\-with\-filename\fP .RS 4 این پرچم به ripgrep دستور می‌دهد مسیر فایل را برای هر خط منطبق چاپ کند. این حالت زمانی که بیش از یک فایل جستجو شود، رفتار پیش‌فرض است. اگر \fB\-\-heading\fP فعال باشد (پیش‌فرض هنگام چاپ در یک tty)، مسیر فایل بالای دسته‌های تطابق مربوط به هر فایل نشان داده می‌شود؛ در غیر این صورت، نام فایل به عنوان پیشوند برای هر خط منطبق نمایش داده خواهد شد. .sp این پرچم \fB\-I/\-\-no\-filename\fP را لغو می‌کند. .RE .sp \fB\-I\fP, \fB\-\-no\-filename\fP .RS 4 این پرچم به ripgrep دستور می‌دهد هرگز مسیر فایل را همراه با خط منطبق چاپ نکند. این حالت زمانی که صراحتاً به ripgrep دستور جستجوی یک فایل یا stdin داده شود، رفتار پیش‌فرض است. .sp این پرچم \fB\-H/\-\-with\-filename\fP را لغو می‌کند. .RE .sp \fB\-\-sort\-files\fP .RS 4 منسوخ شده است (DEPRECATED). به جای آن از \fB\-\-sort=path\fP استفاده کنید. .sp این پرچم به ripgrep دستور می‌دهد نتایج جستجو را بر اساس مسیر فایل به صورت لغت‌نگاشتی و با ترتیب صعودی مرتب کند. توجه داشته باشید که این کار در حال حاضر تمام پردازش موازی را غیرفعال کرده و جستجو را در یک نخ اجرا می‌کند. .sp این پرچم \fB\-\-sort\fP و \fB\-\-sortr\fP را لغو می‌کند. .sp این پرچم را می‌توان با \fB\-\-no-sort-files\fP غیرفعال کرد. .RE ..SS "حالت‌های خروجی (OUTPUT MODES)" \fB\-c\fP, \fB\-\-count\fP .RS 4 این پرچم خروجی عادی را غیرفعال کرده و تعداد خطوطی را که با الگوهای داده‌شده برای هر فایل جست‌وجوشده تطابق دارند نشان می‌دهد. برای هر فایل دارای تطابق، مسیر آن و تعداد در یک خط چاپ می‌شود. توجه داشته باشید مگر در حالتی که \fB\-U/\-\-multiline\fP فعال باشد و الگوی/الگوهای داده‌شده بتوانند روی چندین خط تطابق یابند، این گزینه تعداد خطوط منطبق را گزارش می‌کند و نه تعداد کل تطابق‌ها را. هنگامی که حالت چندخطی فعال باشد و الگوی/الگوهای داده‌شده بتوانند در چندین خط مطابقت یابند، \fB\-c/\-\-count\fP معادل \fB\-\-count\-matches\fP خواهد بود. .sp اگر تنها یک فایل به ripgrep داده شود، در صورت وجود تطابق تنها تعداد چاپ می‌شود. در این حالت می‌توان از پرچم \fB\-H/\-\-with\-filename\fP برای اجبار به چاپ مسیر فایل استفاده کرد. اگر نیاز دارید که صرف‌نظر از وجود یا عدم وجود تطابق تعداد چاپ شود، از \fB\-\-include\-zero\fP استفاده کنید. .sp توجه داشته باشید که ممکن است نتایج این پرچم با خروجی \fB\-l/\-\-files\-with\-matches\fP ناسازگار باشد. به‌ویژه اینکه به‌طور پیش‌فرض، ripgrep تلاش می‌کند از جست‌وجوی فایل‌های حاوی داده‌های باینری خودداری کند. با این پرچم، ripgrep نیاز دارد تا تمام محتوای فایل‌ها را جست‌وجو کند که ممکن است شامل داده‌های باینری باشد. اما با \fB\-l/\-\-files\-with\-matches\fP، ripgrep می‌تواند به‌محض مشاهده یک تطابق، که ممکن است بسیار پیش از هرگونه دادهٔ باینری باشد، متوقف شود. برای جلوگیری از این ناسازگاری بدون غیرفعال کردن تشخیص داده‌های باینری، از پرچم \fB\-\-binary\fP استفاده کنید. .sp این گزینه بر پرچم \fB\-\-count\-matches\fP تقدم دارد. توجه داشته باشید زمانی که \fB\-c/\-\-count\fP با \fB\-o/\-\-only\-matching\fP ترکیب شود، ripgrep طوری عمل می‌کند که گویی \fB\-\-count\-matches\fP داده شده است. .RE .sp \fB\-\-count\-matches\fP .RS 4 این پرچم خروجی عادی را غیرفعال کرده و تعداد تطابق‌های مجزای الگوهای داده‌شده را برای هر فایل جست‌وجوشده نمایش می‌دهد. برای هر فایل حاوی تطابق، مسیر آن و تعداد تطابق‌ها در یک خط چاپ می‌شود. توجه داشته باشید که این گزینه تعداد کل تطابق‌های مجزا را گزارش می‌کند و نه تعداد خطوط منطبق را. .sp اگر تنها یک فایل به ripgrep داده شود، در صورت وجود تطابق تنها تعداد چاپ می‌شود. در این حالت می‌توان از پرچم \fB\-H/\-\-with\-filename\fP برای اجبار به چاپ مسیر فایل استفاده کرد. .sp این گزینه بر پرچم \fB\-c/\-\-count\fP تقدم دارد. توجه داشته باشید زمانی که \fB\-c/\-\-count\fP با \fB\-o/\-\-only\-matching\fP ترکیب شود، ripgrep به‌گونه‌ای عمل می‌کند که گویی \fB\-\-count\-matches\fP داده شده است. .RE .sp \fB\-l\fP, \fB\-\-files\-with\-matches\fP .RS 4 تنها مسیرهایی را که دست‌کم یک تطابق دارند چاپ کرده و از چاپ محتوای تطابق‌ها خودداری می‌کند. .sp توجه داشته باشید که ممکن است نتایج این پرچم با خروجی \fB\-c/\-\-count\fP ناسازگار باشد. به‌ویژه اینکه ripgrep به‌طور پیش‌فرض تلاش می‌کند از جست‌وجوی فایل‌های حاوی داده‌های باینری خودداری کند. با این پرچم، ممکن است ripgrep پیش از مشاهده داده‌های باینری جست‌وجو را متوقف کند. اما با \fB\-c/\-\-count\fP، ripgrep باید کل محتوا را برای تعیین تعداد تطابق‌ها جست‌وجو کند؛ بدین معنا که ممکن است داده‌های باینری را مشاهده کرده و در نتیجه از جست‌وجوی آن فایل صرف‌نظر کند. برای جلوگیری از این ناسازگاری بدون غیرفعال کردن تشخیص داده‌های باینری، از پرچم \fB\-\-binary\fP استفاده کنید. .sp این گزینه بر \fB\-\-files\-without\-match\fP تقدم دارد. .RE .sp \fB\-\-files\-without\-match\fP .RS 4 مسیرهایی را که فاقد هرگونه تطابق هستند چاپ کرده و از چاپ محتوای تطابق‌ها خودداری می‌کند. .sp این گزینه بر \fB\-l/\-\-files\-with\-matches\fP تقدم دارد. .RE .sp \fB\-\-json\fP .RS 4 چاپ نتایج را در قالب JSON Lines فعال می‌کند. .sp هنگامی که این پرچم داده شود، ripgrep توالی‌ای از پیام‌ها را صادر می‌کند که هر یک به‌صورت یک شیء JSON کدگذاری شده‌اند، و شامل پنج نوع پیام مختلف است: .sp .TP 12 \fBbegin\fP پیامی که نشان می‌دهد یک فایل در حال جست‌وجو است و دست‌کم شامل یک تطابق است. .TP 12 \fBend\fP پیامی که نشان می‌دهد جست‌وجوی یک فایل به پایان رسیده است. این پیام همچنین شامل آمار خلاصه‌ای دربارهٔ جست‌وجوی آن فایل خاص است. .TP 12 \fBmatch\fP پیامی که نشان می‌دهد یک تطابق پیدا شده است. این پیام شامل متن و آفست‌های تطابق است. .TP 12 \fBcontext\fP پیامی که نشان می‌دهد یک خط زمینه (context) یافت شده است. این پیام شامل متن خط و اطلاعات تطابق (در صورت معکوس بودن جست‌وجو) است. .TP 12 \fBsummary\fP پیام نهایی صادرشده توسط ripgrep که شامل آمار خلاصهٔ جست‌وجو در تمام فایل‌ها است. .PP از آنجا که معتبر بودن مسیر فایل‌ها یا محتوای آن‌ها بر اساس استاندارد UTF-8 تضمین نمی‌شود و خود JSON نیز باید با کدگذاری یونیکد قابل‌نمایش باشد، ripgrep تمام عناصر داده را به‌صورت شیءهایی با یکی از دو کلید \fBtext\fP یا \fBbytes\fP صادر می‌کند. کلید \fBtext\fP در صورتی که داده‌ها UTF-8 معتبر باشند یک رشتهٔ معمولی JSON است، در حالی که \fBbytes\fP محتوای کدگذاری‌شدهٔ داده‌ها در قالب base64 است. .sp قالب JSON Lines تنها برای نمایش نتایج جست‌وجو پشتیبانی می‌شود. این قالب نمی‌تواند همراه با سایر پرچم‌هایی که انواع دیگری از خروجی را تولید می‌کنند، مانند \fB\-\-files\fP، \fB\-l/\-\-files\-with\-matches\fP، \fB\-\-files\-without\-match\fP، \fB\-c/\-\-count\fP یا \fB\-\-count\-matches\fP استفاده شود. در صورت استفادهٔ هم‌زمان از هر یک از پرچم‌های یادشده با \fB\-\-json\fP، ابزار ripgrep خطا گزارش خواهد داد. .sp سایر پرچم‌هایی که جنبه‌هایی از خروجی استاندارد را کنترل می‌کنند مانند \fB\-o/\-\-only\-matching\fP، \fB\-\-heading\fP، \fB\-r/\-\-replace\fP، \fB\-M/\-\-max\-columns\fP و غیره، در صورت تنظیم بودن \fB\-\-json\fP هیچ تأثیری ندارند. با این حال، فعال‌سازی خروجی JSON همواره به‌صورت ضمنی و بدون قید و شرط \fB\-\-stats\fP را فعال می‌کند. .sp توضیحات کامل‌تر دربارهٔ قالب JSON استفاده‌شده را می‌توانید در اینجا بیابید: \fIhttps://docs.rs/grep-printer/*/grep_printer/struct.JSON.html\fP. .sp این پرچم را می‌توان با \fB\-\-no-json\fP غیرفعال کرد. .RE . .SS "گزینه‌های گزارش‌گیری (LOGGING OPTIONS)" \fB\-\-debug\fP .RS 4 نمایش پیام‌های اشکال‌زدایی. لطفاً هنگام ثبت گزارش باگ از این گزینه استفاده کنید. .sp پرچم \fB\-\-debug\fP عموماً برای یافتن دلیل نادیده گرفتن یک فایل خاص توسط ripgrep مفید است. پیام‌های اشکال‌زدایی باید تمام فایل‌های نادیده‌گرفته‌شده و دلیل آن را ذکر کنند. .sp برای دریافت خروجی اشکال‌زدایی با جزئیات بیشتر، از پرچم \fB\-\-trace\fP استفاده کنید که شامل \fB\-\-debug\fP به همراه داده‌های ردگیری تکمیلی است. .RE .sp \fB\-\-no\-ignore\-messages\fP .RS 4 هنگامی که این پرچم فعال باشد، تمام پیام‌های خطای مربوط به تجزیهٔ فایل‌های ignore سرکوب می‌شوند. به‌طور پیش‌فرض، پیام‌های خطا در خروجی خطای استاندارد (stderr) چاپ می‌شوند. در مواردی که این خطاها مورد انتظار هستند، می‌توان از این پرچم برای جلوگیری از نویز ناشی از پیام‌ها استفاده کرد. .sp این پرچم را می‌توان با \fB\-\-ignore-messages\fP غیرفعال کرد. .RE .sp \fB\-\-no\-messages\fP .RS 4 این پرچم برخی از پیام‌های خطا را سرکوب می‌کند؛ به‌ویژه پیام‌های مربوط به عدم موفقیت در باز کردن و خواندن فایل‌ها. پیام‌های خطای مربوط به نحو (syntax) الگو همچنان نمایش داده می‌شوند. .sp این پرچم را می‌توان با \fB\-\-messages\fP غیرفعال کرد. .RE .sp \fB\-\-stats\fP .RS 4 در صورت فعال بودن، ripgrep آمار تجمیعی دربارهٔ جست‌وجو را چاپ می‌کند. هنگامی که این پرچم مشخص شود، ripgrep در پایان جست‌وجو دست‌کم آمارهای زیر را در خروجی استاندارد (stdout) چاپ خواهد کرد: تعداد خطوط منطبق، تعداد فایل‌های دارای تطابق، تعداد فایل‌های جست‌وجوشده، و مدت زمان صرف‌شده برای تکمیل کل جست‌وجو. .sp این مجموعه از آمارهای تجمیعی ممکن است در طول زمان گسترش یابد. .sp این پرچم هنگام استفاده از \fB\-\-json\fP همواره به‌طور ضمنی فعال است. .sp توجه داشته باشید که این پرچم در صورت استفاده از \fB\-\-files\fP، \fB\-l/\-\-files\-with\-matches\fP یا \fB\-\-files\-without\-match\fP هیچ تأثیری ندارد. .sp این پرچم را می‌توان با \fB\-\-no-stats\fP غیرفعال کرد. .RE .sp \fB\-\-trace\fP .RS 4 نمایش پیام‌های ردگیری. این گزینه جزئیات بیشتری نسبت به پرچم \fB\-\-debug\fP ارائه می‌دهد. معمولاً تنها در صورتی باید از این پرچم استفاده کنید که \fB\-\-debug\fP اطلاعات مورد نظر شما را صادر نکند. .RE ..SS "سایر رفتارها (OTHER BEHAVIORS)" \fB\-\-files\fP .RS 4 چاپ نام هر فایلی که قرار است بدون انجام واقعی جستجو، جستجو شود. این گزینه برای تعیین اینکه آیا یک فایل خاص جستجو می‌شود یا خیر مفید است. .sp این گزینه \fB\-\-type\-list\fP را لغو می‌کند. .RE .sp \fB\-\-generate\fP=\fIKIND\fP .RS 4 این پرچم به ripgrep دستور می‌دهد نوع خاصی از خروجی را که با \fIKIND\fP مشخص می‌شود تولید کرده و سپس بدون جستجو خارج شود. \fIKIND\fP می‌تواند یکی از مقادیر زیر باشد: .sp .TP 15 \fBman\fP یک صفحهٔ راهنما (man page) را برای ripgrep در قالب \fBroff\fP تولید می‌کند. .TP 15 \fBcomplete\-bash\fP یک اسکریپت تکمیل خودکار برای پوستهٔ \fBbash\fP تولید می‌کند. .TP 15 \fBcomplete\-zsh\fP یک اسکریپت تکمیل خودکار برای پوستهٔ \fBzsh\fP تولید می‌کند. .TP 15 \fBcomplete\-fish\fP یک اسکریپت تکمیل خودکار برای پوستهٔ \fBfish\fP تولید می‌کند. .TP 15 \fBcomplete\-powershell\fP یک اسکریپت تکمیل خودکار برای PowerShell تولید می‌کند. .PP خروجی در \fBstdout\fP نوشته می‌شود. فهرست بالا ممکن است در طول زمان گسترش یابد. .RE .sp \fB\-\-no\-config\fP .RS 4 هنگام تنظیم، ripgrep هرگز فایل‌های پیکربندی را نخواهد خواند. هنگام حضور این پرچم، ripgrep متغیر محیطی \fBRIPGREP_CONFIG_PATH\fP را در نظر نخواهد گرفت. .sp اگر زمانی قابلیتی به ripgrep افزوده شود که فایل‌های پیکربندی را به‌طور خودکار در مکان‌های از پیش تعریف‌شده بخواند، این پرچم آن رفتار را نیز غیرفعال خواهد کرد. .RE .sp \fB\-\-pcre2\-version\fP .RS 4 هنگامی که این پرچم وجود دارد، ripgrep نسخهٔ PCRE2 مورد استفاده را همراه با دیگر اطلاعات چاپ کرده و سپس خارج می‌شود. اگر PCRE2 در دسترس نباشد، ripgrep یک پیام خطا چاپ کرده و با یک کد خطا خارج می‌شود. .RE .sp \fB\-\-type\-list\fP .RS 4 نمایش تمام انواع فایل‌های پشتیبانی‌شده و الگوهای تطبیق (glob) متناظر با آن‌ها. این گزینه هرگونه پرچم‌های \fB\-\-type\-add\fP و \fB\-\-type\-clear\fP داده‌شده را در نظر می‌گیرد. هر نوع در یک خط جداگانه چاپ می‌شود که به دنبال آن یک \fB:\fP و سپس در همان خط، فهرستی از الگوهای تطبیق آن نوع که با کاما از هم جدا شده‌اند قرار می‌گیرد. .RE .sp \fB\-V\fP, \fB\-\-version\fP .RS 4 این پرچم نسخهٔ ripgrep را چاپ می‌کند. همچنین ممکن است اطلاعات مرتبط دیگری، مانند وجود بهینه‌سازی‌های خاص معماری هدف و بازنگری (revision) \fBgit\fP که این ساختِ ripgrep از روی آن کامپایل شده است را چاپ کند. .RE . . .SH "وضعیت خروج (EXIT STATUS)" اگر ripgrep تطابقی پیدا کند، وضعیت خروج برنامه \fB0\fP است. اگر هیچ تطابقی یافت نشود، وضعیت خروج \fB1\fP خواهد بود. اگر خطایی رخ دهد، وضعیت خروج همیشه \fB2\fP است مگر اینکه ripgrep با پرچم \fB\-q/\-\-quiet\fP اجرا شده باشد و تطابقی پیدا شده باشد. به‌طور خلاصه: .sp .IP \(bu 3n وضعیت خروج \fB0\fP تنها زمانی رخ می‌دهد که حداقل یک تطابق پیدا شده باشد و هیچ خطایی رخ نداده باشد، مگر اینکه \fB\-q/\-\-quiet\fP داده شده باشد. . .IP \(bu 3n وضعیت خروج \fB1\fP تنها زمانی رخ می‌دهد که هیچ تطابقی پیدا نشده و هیچ خطایی رخ نداده باشد. . .IP \(bu 3n وضعیت خروج \fB2\fP زمانی رخ می‌دهد که خطایی رخ داده باشد. این امر هم برای خطاهای فاجعه‌بار (مانند خطای نحو در عبارت باقاعده) و هم برای خطاهای جزئی (مانند ناتوانی در خواندن یک فایل) صدق می‌کند. . . .SH "فیلتر خودکار (AUTOMATIC FILTERING)" ابزار ripgrep به‌طور پیش‌فرض مقدار قابل‌توجهی فیلترسازی خودکار انجام می‌دهد. این بخش آن فیلترها و نحوهٔ کنترل آن‌ها را شرح می‌دهد. .sp \fBنکته\fP: برای غیرفعال کردن فیلترسازی خودکار، از \fBrg -uuu\fP استفاده کنید. .sp فیلترسازی خودکار و «هوشمند» ripgrep یکی از بارزترین ویژگی‌های متمایزکنندهٔ ripgrep از دیگر ابزارها مانند \fBgrep\fP است. به این ترتیب، رفتار آن ممکن است برای کاربرانی که انتظارش را ندارند غافلگیرکننده باشد. .sp ابزار ripgrep چهار نوع فیلترسازی را به‌طور خودکار انجام می‌دهد: .sp . .IP 1. 3n فایل‌ها و دایرکتوری‌هایی که با قوانین نادیده‌گیری (ignore) مطابقت دارند جستجو نمی‌شوند. .IP 2. 3n فایل‌ها و دایرکتوری‌های پنهان جستجو نمی‌شوند. .IP 3. 3n فایل‌های دودویی (فایل‌های با بایت \fBNUL\fP) جستجو نمی‌شوند. .IP 4. 3n پیوندهای نمادین دنبال نمی‌شوند. .PP نوع اول فیلترسازی پیچیده‌ترین آن‌هاست. ابزار ripgrep تلاش خواهد کرد تا جای ممکن با دقت به قوانین \fBgitignore\fP شما پایبند باشد. به‌طور خاص، این شامل موارد زیر است: . .IP \(bu 3n هرگونه قانون سراسری، برای مثال در \fB$HOME/.config/git/ignore\fP. . .IP \(bu 3n هرگونه قانون در فایل‌های مرتبط \fB.gitignore\fP. این شامل فایل‌های \fB.gitignore\fP در دایرکتوری‌های والد که بخشی از همان مخزن \fBgit\fP هستند نیز می‌شود. (مگر اینکه \fB\-\-no\-require\-git\fP داده شده باشد.) . .IP \(bu 3n هرگونه قانون محلی، برای مثال در \fB.git/info/exclude\fP. .PP در برخی موارد، ripgrep و \fBgit\fP از لحاظ فایل‌های نادیده‌گرفته‌شده همیشه هماهنگ نخواهند بود. برای مثال، فایلی که از طریق \fB.gitignore\fP نادیده گرفته شده اما توسط \fBgit\fP ردگیری می‌شود، توسط ripgrep جستجو نخواهد شد، با وجود اینکه \fBgit\fP آن را ردگیری می‌کند. بعید است که این مورد هرگز رفع شود. در عوض، باید یا مطمئن شوید که قوانین مستثنی‌سازی شما دقیقاً با فایل‌هایی که ردگیری می‌کنید مطابقت دارد، یا اینکه برای جستجو از \fBgit grep\fP استفاده کنید. .sp قوانین نادیده‌گیری اضافی را می‌توان در خارج از زمینهٔ \fBgit\fP نیز ارائه داد: . .IP \(bu 3n هرگونه قانون در \fB.ignore\fP. ابزار ripgrep همچنین فایل‌های \fB.ignore\fP در دایرکتوری‌های والد را رعایت می‌کند. . .IP \(bu 3n هرگونه قانون در \fB.rgignore\fP. ابزار ripgrep همچنین فایل‌های \fB.rgignore\fP در دایرکتوری‌های والد را رعایت می‌کند. . .IP \(bu 3n هرگونه قانون در فایل‌های مشخص‌شده با پرچم \fB\-\-ignore\-file\fP. .PP اولویت قوانین نادیده‌گیری به شرح زیر است، به‌طوری که موارد بعدی بر موارد قبلی اولویت دارند: . .IP \(bu 3n فایل‌های ارائه‌شده توسط \fB\-\-ignore\-file\fP. . .IP \(bu 3n قوانین سراسری gitignore، برای مثال از \fB$HOME/.config/git/ignore\fP. . .IP \(bu 3n قوانین محلی از \fB.git/info/exclude\fP. . .IP \(bu 3n قوانین موجود در \fB.gitignore\fP. . .IP \(bu 3n قوانین موجود در \fB.ignore\fP. . .IP \(bu 3n قوانین موجود در \fB.rgignore\fP. .PP بنابراین به عنوان مثال، اگر \fIfoo\fP در یک \fB.gitignore\fP و \fB!\fP\fIfoo\fP در یک \fB.rgignore\fP باشد، آنگاه \fIfoo\fP نادیده گرفته نخواهد شد زیرا \fB.rgignore\fP بر \fB.gitignore\fP اولویت دارد. .sp هر یک از انواع فیلترسازی را می‌توان از طریق پرچم‌های خط فرمان پیکربندی کرد: . .IP \(bu 3n چندین پرچم که با \fB\-\-no\-ignore\fP شروع می‌شوند وجود دارند که تعیین می‌کنند کدام‌یک از قوانین نادیده‌گیری رعایت شوند. پرچم \fB\-\-no\-ignore\fP به تنهایی همهٔ آن‌ها را غیرفعال می‌کند. . .IP \(bu 3n پرچم \fB\-./\-\-hidden\fP ابزار ripgrep را وادار به جستجوی فایل‌ها و دایرکتوری‌های پنهان می‌کند. . .IP \(bu 3n پرچم \fB\-\-binary\fP ابزار ripgrep را وادار به جستجوی فایل‌های باینری می‌کند. . .IP \(bu 3n پرچم \fB\-L/\-\-follow\fP ابزار ripgrep را وادار به دنبال کردن پیوندهای نمادین می‌کند. .PP به‌عنوان یک میانبر ویژه، پرچم \fB\-u\fP می‌تواند تا سه بار مشخص شود. هر بار تکرار بیشتر، فیلترسازی را به‌صورت تدریجی کاهش می‌دهد: . .IP \(bu 3n گزینهٔ \fB\-u\fP معادل \fB\-\-no\-ignore\fP است. . .IP \(bu 3n گزینهٔ \fB\-uu\fP معادل \fB\-\-no\-ignore \-\-hidden\fP است. . .IP \(bu 3n گزینهٔ \fB\-uuu\fP معادل \fB\-\-no\-ignore \-\-hidden \-\-binary\fP است. .PP به‌ویژه، \fBrg -uuu\fP باید دقیقاً همان محتوایی را جستجو کند که \fBgrep -r\fP جستجو می‌کند. . ..SH "فایل‌های پیکربندی (CONFIGURATION FILES)" ابزار ripgrep از خواندن فایل‌های پیکربندی که رفتار پیش‌فرض ripgrep را تغییر می‌دهند پشتیبانی می‌کند. قالب فایل پیکربندی به سبک \(lqrc\(rq بوده و بسیار ساده است. این قالب بر اساس دو قانون تعریف می‌شود: . .IP 1. 3n هر خط، پس از حذف فاصله‌های خالی (whitespace)، یک آرگومان پوسته است. . .IP 2. 3n خطوطی که با \fB#\fP آغاز می‌شوند (که می‌تواند اختیاری با هر مقداری از فاصله‌های خالی پیش از آن همراه باشد) نادیده گرفته می‌شوند. .PP ابزار ripgrep فقط و فقط در صورتی به دنبال یک فایل پیکربندی واحد می‌گردد که متغیر محیطی \fBRIPGREP_CONFIG_PATH\fP مقداردهی شده و غیرخالی باشد. ripgrep در هنگام راه‌اندازی، آرگومان‌ها را از این فایل تجزیه کرده و به‌گونه‌ای رفتار می‌کند که گویی آرگومان‌های موجود در این فایل به ابتدای آرگومان‌های صریح داده‌شده به ripgrep در خط فرمان اضافه شده‌اند. با این حال توجه داشته باشید که دستور \fBrg\fP اجراشده همچنان باید معتبر باشد؛ بدین معنا که حتی اگر فایل پیکربندی از گزینهٔ \fB\-e/\-\-regexp\fP استفاده کند، دستور باید همواره حداقل حاوی یک الگو در خط فرمان باشد. .sp برای مثال، اگر فایل ripgreprc شما تنها شامل یک خط باشد: .sp .EX \-\-smart\-case .EE .sp آنگاه دستور زیر: .sp .EX RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo .EE .sp رفتاری دقیقاً یکسان با دستور زیر خواهد داشت: .sp .EX rg \-\-smart-case foo .EE .sp مثال دیگر، افزودن نوع‌ها است، به این صورت: .sp .EX \-\-type-add web:*.{html,css,js}* .EE .sp دستور بالا رفتاری همسان با دستور زیر خواهد داشت: .sp .EX rg \-\-type\-add 'web:*.{html,css,js}*' foo .EE .sp همین موضوع برای استفاده از globها نیز صدق می‌کند. این مورد: .sp .EX \-\-glob=!.git .EE .sp یا این: .sp .EX \-\-glob !.git .EE .sp رفتاری یکسان با دستور زیر خواهد داشت: .sp .EX rg \-\-glob '!.git' foo .EE .sp نکتهٔ اساسی این است که هر آرگومان پوسته باید در خط مجزای خود قرار گیرد. بنابراین برای مثال، یک فایل پیکربندی حاوی: .sp .EX \-j 4 .EE .sp احتمالاً آن‌چه را که مد نظر دارید انجام نمی‌دهد. در عوض، باید به این شکل باشد: .sp .EX \-j 4 .EE .sp یا: .sp .EX \-j4 .EE .sp ابزار ripgrep همچنین گزینهٔ \fB\-\-no\-config\fP را ارائه می‌دهد که در صورت استفاده، تمام پشتیبانی از پیکربندی را غیرفعال خواهد کرد. این شامل هرگونه پشتیبانی در آینده از بارگذاری خودکار فایل‌های پیکربندی از مسیرهای از پیش تعیین‌شده نیز می‌شود. .sp تداخل‌های میان فایل‌های پیکربندی و آرگومان‌های صریح، دقیقاً مانند تداخل‌ها در یک فراخوانی یکسان در خط فرمان مدیریت می‌شوند. به این معنا که با فرض اینکه فایل پیکربندی شما تنها شامل \fB\-\-smart\-case\fP باشد، در این صورت این دستور: .sp .EX RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo \-\-case\-sensitive .EE .sp دقیقاً معادل است با: .sp .EX rg \-\-smart\-case foo \-\-case\-sensitive .EE .sp که در این وضعیت، گزینهٔ \fB\-\-case\-sensitive\fP بر گزینهٔ \fB\-\-smart\-case\fP اولویت یافته و آن را خنثی می‌کند. . . .SH "تکمیل پوسته (SHELL COMPLETION)" فایل‌های تکمیل پوسته برای Bash، Fish، Zsh و PowerShell در فایل آرشیو انتشار (tarball) گنجانده شده‌اند. .sp برای \fBbash\fP، فایل \fBrg.bash\fP را به \fB$XDG_CONFIG_HOME/bash_completion\fP یا \fB/etc/bash_completion.d/\fP منتقل کنید. .sp برای \fBfish\fP، فایل \fBrg.fish\fP را به \fB$HOME/.config/fish/completions\fP منتقل کنید. .sp برای \fBzsh\fP، فایل \fB_rg\fP را به یکی از دایرکتوری‌های موجود در \fB$fpath\fP خود منتقل کنید. . ..SH "هشدارها (CAVEATS)" ابزار ripgrep ممکن است هنگام استفاده از تنظیمات پیش‌فرض، چنانچه فایلی را جستجو کند که به‌طور هم‌زمان کوتاه (truncated) می‌شود، به‌طور غیرمنتظره‌ای متوقف شود. با ارسال پرچم \fB\-\-no\-mmap\fP که استفاده از نگاشت‌های حافظه را در تمام موارد به‌صورت اجباری غیرفعال می‌کند، می‌توان از این رفتار جلوگیری کرد. .sp بسته به چند عامل، ripgrep ممکن است مقدار زیادی حافظه مصرف کند. نخست، اگر ripgrep از پردازش موازی برای جستجو استفاده کند (حالت پیش‌فرض)، تمام خروجی مربوط به هر فایل به‌طور جداگانه در حافظه بافر می‌شود تا از درهم‌آمیختگی نتایج منطبق در خروجی جلوگیری گردد. برای جلوگیری از این موضوع، می‌توانید با استفاده از پرچم \fB\-j1\fP پردازش موازی را غیرفعال کنید. دوم، ripgrep برای اجرای جستجو همیشه باید حداقل یک سطر کامل را در حافظه نگه دارد. از این رو، فایلی با سطرهای بسیار طولانی می‌تواند موجب مصرف زیاد حافظه توسط ripgrep شود. به‌طور کلی، این حالت تنها هنگام جستجو در داده‌های باینری همراه با پرچم فعال \fB\-a/\-\-text\fP رخ می‌دهد. (هنگامی که پرچم \fB\-a/\-\-text\fP فعال نباشد، ripgrep تمام بایت‌های NUL را با پایان‌دهنده‌های سطر جایگزین می‌کند که معمولاً مانع از مصرف بیش‌ازحد حافظه می‌شود.) سوم، هنگامی که ripgrep فایلی بزرگ را با استفاده از نگاشت حافظه جستجو می‌کند، احتمالاً میزان حافظه مقیم (resident memory) این فرایند به اندازه حجم فایل گزارش خواهد شد. با این حال، این بدان معنا نیست که ripgrep در عمل به استفاده از این مقدار حافظه heap نیاز داشته است؛ سیستم‌عامل به‌طور کلی این مورد را مدیریت خواهد کرد. . . .SH "نسخه (VERSION)" 15.2.0 . . .SH "صفحه خانگی (HOMEPAGE)" \fIhttps://github.com/BurntSushi/ripgrep\fP .sp لطفاً باگ‌ها و درخواست‌های قابلیت‌های جدید را به بخش ثبت مشکلات (issue tracker) گزارش دهید. لطفاً تمام تلاش خود را برای ارائه یک نمونه آزمایشی بازتولیدپذیر از خطا به کار گیرید. این نمونه باید شامل داده‌های مورد جستجو، دستور \fBrg\fP، خروجی واقعی و خروجی مورد انتظار باشد. لطفاً خروجی حاصل از اجرای همان دستور \fBrg\fP همراه با پرچم \fB\-\-debug\fP را نیز ضمیمه کنید. .sp اگر سوالاتی دارید که مشخصاً در دسته‌بندی «باگ» یا «درخواست قابلیت» قرار نمی‌گیرند، می‌توانید آن‌ها را در بخش گفتگوهای (Discussions) ردیاب مشکلات مطرح کنید: \fIhttps://github.com/BurntSushi/ripgrep/discussions\fP . . .SH "نویسندگان (AUTHORS)" Andrew Gallant <\fIjamslam@gmail.com\fP>