.TH UGREP-INDEXER "1" "August 05, 2026" "ugrep-indexer 7.8.4" "User Commands"
.SH "نام (NAME)"
\fBugrep-indexer\fR \- نمایه‌ساز فایل برای شتاب‌بخشی به جستجوی بازگشتی
.SH "خلاصه دستور (SYNOPSIS)"
.B ugrep-indexer [\fB-0\fR...\fB9\fR] [\fB-c\fR|\fB-d\fR|\fB-f\fR] [\fB-I\fR] [\fB-q\fR] [\fB-S\fR] [\fB-s\fR] [\fB-X\fR] [\fB-z\fR] [\fIPATH\fR]
.SH "توضیحات (DESCRIPTION)"
ابزار \fBugrep-indexer\fR فایل‌ها را به‌صورت بازگشتی نمایه‌سازی می‌کند تا جستجوی بازگشتی را با دستورهای \fBug --index\fR \fIPATTERN\fR سرعت بخشد:
.IP
$ \fBugrep-indexer\fR [\fB-I\fR] [\fB-z\fR]
.IP
  ...
.IP
$ \fBug\fR \fB--index\fR [\fB-I\fR] [\fB-z\fR] [\fB-r\fR|\fB-R\fR] \fIOPTIONS\fR \fIPATTERN\fR
.IP
$ \fBugrep\fR \fB--index\fR [\fB-I\fR] [\fB-z\fR] [\fB-r\fR|\fB-R\fR] \fIOPTIONS\fR \fIPATTERN\fR
.PP
که در آن گزینهٔ \fB-I\fR یا \fB--ignore-binary\fR از فایل‌های باینری چشم‌پوشی می‌کند، که برای محدود کردن سربار فضای ذخیره‌سازی نمایه و کاهش زمان جستجو توصیه می‌شود. گزینهٔ \fB-z\fR یا \fB--decompress\fR بایگانی‌ها و فایل‌های فشرده را نمایه‌سازی و جستجو می‌کند.
.PP
نمایه‌سازی، جستجو در سیستم‌های فایلی بزرگ و سرد (فایل‌هایی که اخیراً در حافظهٔ RAM ذخیره نشده‌اند) و سیستم‌های فایلی که عموماً در جستجو کند هستند را سریع‌تر می‌کند. توجه داشته باشید که نمایه‌سازی ممکن است سرعت جستجوی تعداد کمی فایل یا جستجوی بازگشتی در سیستم‌های فایلی سریع را افزایش ندهد.
.PP
جستجو با \fBug --index\fR ایمن است و هرگز از فایل‌های تغییریافته‌ای که ممکن است پس از نمایه‌سازی با الگو مطابقت داشته باشند گذر نمی‌کند؛ دستور \fBug --index\fR \fIPATTERN\fR همواره فایل‌ها و دایرکتوری‌هایی را که پس از نمایه‌سازی اضافه یا تغییر یافته‌اند، جستجو می‌کند. هنگامی که گزینهٔ \fB--stats\fR همراه با \fBug --index\fR استفاده می‌شود، گزارشی از جستجو تولید می‌گردد که تعداد فایل‌های رد شده‌ای که با هیچ نمایه‌ای مطابقت نداشتند و تعداد فایل‌ها و دایرکتوری‌هایی که پس از نمایه‌سازی اضافه یا اصلاح شده‌اند را نشان می‌دهد. توجه داشته باشید که جستجو با \fBug --index\fR در صورتی که الگوهای regex پیچیده‌ای حاوی رده‌های کاراکتری بزرگ یونیکد ترکیب‌شده با تکرارهای `*' یا `+' تعیین شوند، ممکن است زمان راه‌اندازی را به‌طور چشمگیری افزایش دهد؛ از انجام این کار باید خودداری کرد.
.PP
ابزار \fBugrep-indexer\fR یک فایل نمایهٔ پنهان را در هر دایرکتوری نمایه‌شده ذخیره می‌کند. اندازهٔ فایل نمایه به تعداد فایل‌های نمایه‌شده و دقت نمایه‌سازی تعیین‌شده بستگی دارد. دقت بالاتر فایل‌های نمایهٔ بزرگ‌تری تولید می‌کند تا با کاهش مثبت‌های کاذب (false positives)، کارایی جستجو را بهبود بخشد (مثبت کاذب پیش‌بینی تطابق برای فایلی است که در واقع با الگوی regex تطابق ندارد).
.PP
ابزار \fBugrep-indexer\fR یک مسیر اختیاری \fIPATH\fR به ریشهٔ درخت دایرکتوری برای نمایه‌سازی را می‌پذیرد. پیش‌فرض، نمایه‌سازی درخت دایرکتوری کاری فعلی است.
.PP
ابزار \fBugrep-indexer\fR نمایه‌ها را به‌صورت افزایشی به‌روزرسانی می‌کند. برای اجبار به نمایه‌سازی مجدد، گزینهٔ \fB-f\fR یا \fB--force\fR را مشخص کنید. نمایه‌ها با گزینهٔ \fB-d\fR یا \fB--delete\fR حذف می‌شوند.
.PP
اجرای \fBugrep-indexer\fR را می‌توان در هر زمان متوقف کرد و برای ادامهٔ نمایه‌سازی مجدداً آغاز نمود. فایل‌های نمایهٔ ناکامل باعث بروز خطا نمی‌شوند.
.PP
فایل‌های ASCII، UTF-8، UTF-16 و UTF-32 به عنوان فایل‌های متنی نمایه‌سازی و جستجو می‌شوند، مگر اینکه کدگذاری UTF آن‌ها نامعتبر باشد. فایل‌های با سایر کدگذاری‌ها به عنوان فایل‌های باینری نمایه‌سازی شده و با استفاده از \fBug --index \fB-U\fR با الگوهای regex غیر یونیکدی قابل جستجو هستند.
.PP
هنگامی که گزینهٔ \fB-I\fR یا \fB--ignore-binary\fR برای \fBugrep-indexer\fR مشخص شود، از فایل‌های باینری صرف‌نظر شده و نمایه نمی‌شوند. با استفاده از گزینهٔ \fB-I\fR در دستور \fBug --index -I\fR، از جستجو در این فایل‌های باینری نمایه‌نشده خودداری کنید.
.PP
گزینهٔ \fB-X\fR یا \fB--ignore-files\fR در \fBugrep-indexer\fR از قواعد gitignore پیروی می‌کند. به‌همین‌ترتیب، با استفاده از گزینهٔ \fB--ignore-files\fR در دستور \fBug --index --ignore-files\fR، از جستجو در فایل‌های نادیده‌گرفته‌شده و نمایه‌نشده خودداری نمایید.
.PP
بایگانی‌ها و فایل‌های فشرده با گزینهٔ \fB-z\fR یا \fB--decompress\fR در \fBugrep-indexer\fR نمایه‌سازی می‌شوند. در غیر این صورت، بایگانی‌ها و فایل‌های فشرده به عنوان فایل باینری نمایه‌سازی شده یا با گزینهٔ \fB-I\fR یا \fB--ignore-binary\fR نادیده گرفته می‌شوند. توجه داشته باشید که اگر یک بایگانی یا فایل فشرده به عنوان فایل باینری نمایه‌سازی شود، برای نمایه‌سازی محتوای درون آن مجدداً با گزینهٔ \fB-z\fR نمایه نخواهد شد. تنها فایل‌هایی که پس از نمایه‌سازی تغییر کرده باشند مجدداً نمایه می‌شوند که این امر از طریق مقایسهٔ برچسب‌های زمانی تعیین می‌گردد.
.PP
فایل‌های دارای پیوند نمادین با گزینهٔ \fB-S\fR یا \fB--dereference-files\fR در \fBugrep-indexer\fR نمایه‌سازی می‌شوند. پیوندهای نمادین به دایرکتوری‌ها هرگز دنبال نمی‌شوند.
.PP
برای ذخیره کردن یک فایل گزارش از فرآیند نمایه‌سازی، گزینهٔ \fB-v\fR یا \fB--verbose\fR را مشخص کرده و خروجی استاندارد را به یک فایل لاگ هدایت کنید. تمام پیام‌ها و هشدارها به خروجی استاندارد ارسال شده و در فایل لاگ ثبت می‌شوند.
.PP
فایل پیکربندی .ugrep-indexer حاوی گزینه‌های پیکربندی، در صورت وجود در دایرکتوری کاری یا در دایرکتوری خانگی بارگذاری می‌شود. یک گزینهٔ پیکربندی شامل نام یک گزینهٔ بلند و در صورت وجود، آرگومان آن است.
.PP
گزینه‌های زیر در دسترس هستند:
.TP
\fB\-0\fR, \fB\-1\fR, \fB\-2\fR, \fB\-3\fR, ..., \fB\-9\fR, \fB\-\-accuracy\fR=\fIDIGIT\fR
دقت نمایه‌سازی را تعیین می‌کند. دقت کم، سربار فضای ذخیره‌سازی نمایه را به قیمت نرخ بالاتری از تطابق‌های مثبت کاذب الگو (نویز بیشتر) کاهش می‌دهد. دقت بالا، نرخ تطابق‌های مثبت کاذب الگوی regex را (نویز کمتر) به قیمت افزایش سربار فضای ذخیره‌سازی نمایه کاهش می‌دهد. دقتی بین 2 تا 7 توصیه می‌شود. دقت پیش‌فرض 4 است.
.TP
\fB\-.\fR, \fB\-\-hidden\fR
نمایه‌سازی فایل‌ها و دایرکتوری‌های پنهان.
.TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام راهنما و خروج.
.TP
\fB\-c\fR, \fB\-\-check\fR
بررسی و گزارش بازگشتی نمایه‌ها بدون نمایه‌سازی دوبارهٔ فایل‌ها.
.TP
\fB\-d\fR, \fB\-\-delete\fR
حذف بازگشتی فایل‌های نمایه.
.TP
\fB\-f\fR, \fB\-\-force\fR
اجبار به نمایه‌سازی مجدد فایل‌ها، حتی فایل‌هایی که قبلاً نمایه شده‌اند.
.TP
\fB\-I\fR, \fB\-\-ignore\-binary\fR
فایل‌های باینری نمایه‌سازی نشوند.
.TP
\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
حالت بی‌صدا: آمار نمایه‌سازی نمایش داده نشود.
.TP
\fB\-S\fR, \fB\-\-dereference\-files\fR
دنبال کردن پیوندهای نمادین به فایل‌ها. پیوندهای نمادین به دایرکتوری‌ها هرگز دنبال نمی‌شوند.
.TP
\fB\-s\fR, \fB\-\-no\-messages\fR
حالت خاموش: فایل‌های ناموجود و غیرقابل خواندن نادیده گرفته می‌شوند، یعنی پیام‌های خطا و هشدارهای آن‌ها سرکوب می‌گردد.
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش نسخه و خروج.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
تولید خروجی با جزئیات. فایل‌ها با A برای بایگانی (archive)، با C برای فشرده (compressed)، و B برای باینری (binary) یا I برای باینری نادیده‌گرفته‌شده علامت‌گذاری می‌شوند. حذف‌ها با D علامت می‌خورند.
.TP
\fB\-X\fR, \fB\-\-ignore\-files\fR, \fB\-\-ignore\-files\fR=\fIFILE\fR
عدم نمایه‌سازی فایل‌ها و دایرکتوری‌های منطبق بر الگوهای عمومی (globs) در FILE که در طول نمایه‌سازی با آن‌ها مواجه می‌شود. مقدار پیش‌فرض FILE برابر با `.gitignore' است. این گزینه می‌تواند برای تعیین فایل‌های بیشتر تکرار شود.
.TP
\fB\-z\fR, \fB\-\-decompress\fR
نمایه‌سازی محتوای فایل‌های فشرده و بایگانی‌ها. فایل‌های پنهان درون بایگانی‌ها نادیده گرفته می‌شوند مگر اینکه گزینهٔ \fB\-.\fR یا \fB\-\-hidden\fR مشخص شده باشد. گزینهٔ \fB\-I\fR یا \fB\-\-ignore\-binary\fR فایل‌های باینری فشرده را نادیده می‌گیرد. هنگامی که همراه با گزینهٔ \fB\-\-zmax\fR=\fINUM\fR استفاده شود، محتوای فایل‌های فشرده و بایگانی‌های درون بایگانی‌ها را تا عمق NUM لایه نمایه‌سازی می‌کند. قالب‌های فشرده‌سازی پشتیبانی‌شده: gzip (.gz)، compress (.Z)، zip، 7z، bzip2 (نیاز به پسوند .bz، .bz2، .bzip2، .tbz، .tbz2، .tb2، .tz2 دارد)، lzma و xz (نیاز به پسوند .lzma، .tlz، .xz، .txz دارد)، lz4 (نیاز به پسوند .lz4 دارد)، zstd (نیاز به پسوند .zst، .zstd، .tzst دارد)، brotli (نیاز به پسوند .br دارد)، bzip3 (نیاز به پسوند .bz3 دارد).
.TP
\fB\-\-zmax\fR=\fINUM\fR
هنگامی که همراه با گزینهٔ \fB\-z\fR (\fB\-\-decompress\fR) استفاده شود، محتوای فایل‌های فشرده و بایگانی‌های ذخیره‌شده درون بایگانی‌ها را تا حداکثر NUM لایهٔ بازگشایی در عمق، نمایه‌سازی می‌کند. مقدار پیش‌فرض \fB\-\-zmax\fR=1 فقط امکان نمایه‌سازی فایل‌های فشرده‌نشدهٔ ذخیره‌شده در بایگانی‌های cpio، pax، tar، zip و 7z را می‌دهد؛ فایل‌ها و بایگانی‌های فشرده به عنوان فایل‌های باینری شناسایی شده و عملاً نادیده گرفته می‌شوند. مقدار \fB\-\-zmax\fR=2 را برای نمایه‌سازی فایل‌ها و بایگانی‌های فشردهٔ قرارگرفته در بایگانی‌های cpio، pax، tar، zip و 7z تعیین کنید. مقدار NUM برای حداکثر ۹۹ مرحلهٔ فشرده‌گشایی و استخراج از بایگانی، می‌تواند در بازهٔ ۱ تا ۹۹ باشد. افزایش مقدار NUM به‌تدریج کارایی را کاهش می‌دهد.
.SH "وضعیت خروج (EXIT STATUS)"
ابزار \fBugrep-indexer\fR با یکی از مقادیر زیر خارج می‌شود:
.IP 0
نمایه‌ها به‌روز هستند.
.IP 1
بررسی نمایه‌سازی \fB-c\fR فایل‌های نمایهٔ مفقود یا تاریخ‌گذشته را شناسایی کرد.
.SH "مثال‌ها (EXAMPLES)"
نمایه‌سازی بازگشتی و افزایشی تمام فایل‌های غیرباینری به همراه نمایش پیشرفت:
.IP
$ ugrep-indexer -I -v
.PP
نمایه‌سازی بازگشتی و افزایشی تمام فایل‌های غیرباینری، از جمله فایل‌های غیرباینری ذخیره‌شده در بایگانی‌ها و فایل‌های فشرده، به همراه نمایش پیشرفت:
.IP
$ ugrep-indexer -z -I -v
.PP
نمایه‌سازی افزایشی تمام فایل‌های غیرباینری شامل بایگانی‌ها و فایل‌های فشرده، نمایش پیشرفت، دنبال کردن پیوندهای نمادین به فایل‌ها (و نه دایرکتوری‌ها)، اما بدون نمایه‌سازی فایل‌ها و دایرکتوری‌های منطبق بر الگوهای .gitignore:
.IP
$ ugrep-indexer -z -I -v -S -X
.PP
اجبار به بازنمایه‌سازی تمام فایل‌های غیرباینری شامل بایگانی‌ها و فایل‌های فشرده، دنبال کردن پیوندهای نمادین به فایل‌ها (و نه دایرکتوری‌ها)، اما بدون نمایه‌سازی فایل‌ها و دایرکتوری‌های منطبق بر الگوهای .gitignore:
.IP
$ ugrep-indexer -f -z -I -v -S -X
.PP
همانند مورد قبل، اما با کاهش فضای ذخیره‌سازی فایل نمایه به حداقل از طریق کاهش دقت نمایه‌سازی از 4 (پیش‌فرض) به 0:
.IP
$ ugrep-indexer -f -0 -z -I -v -S -X
.PP
افزایش کارایی جستجو با بالا بردن دقت نمایه‌سازی از 4 (پیش‌فرض) به 7 به قیمت ایجاد فایل‌های نمایهٔ بزرگ‌تر:
.IP
$ ugrep-indexer -f7zIvSX
.PP
حذف بازگشتی تمام فایل‌های نمایهٔ پنهان ._UG#_Store برای بازگرداندن درخت دایرکتوری به حالت نمایه‌نشده:
.IP
$ ugrep-indexer -d
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
حق نشر (c) 2021-2025 Robert A. van Engelen <engelen@acm.org>
.PP
ابزار \fBugrep-indexer\fR تحت مجوز BSD\-3 منتشر شده است. تمام بخش‌های نرم‌افزار شرایط حق نشر معقولی دارند که بازتوزیع آزاد را مجاز می‌داند. این مورد شامل امکان استفادهٔ مجدد از تمام یا بخش‌هایی از درخت سورس‌کد ugrep است.
.SH "همچنین ببینید (SEE ALSO)"
ug(1), ugrep(1).
.SH "گزارش باگ‌ها (BUGS)"
گزارش اشکالات در:
.IP
https://github.com/Genivia/ugrep-indexer/issues