'\" t
.\"     Title: rgr
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-09-02
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: Persian
.\"
.TH "RGR" "1" "2026-09-02" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
rgr \- ابزاری تعاملی برای جایگزینی در ripgrep جهت یافتن و جایگزین کردن آسان متن میان فایل‌ها در خط فرمان.
.SH "توضیحات (DESCRIPTION)"
.sp
برای استفاده از این ابزار، ابتدا باید \fBrg\fP (معروف به \fBripgrep\fP) را نصب کرده باشید.
ببینید: \c
.URL "https://github.com/BurntSushi/ripgrep#installation" "" "."
.SH "نحوه استفاده (USAGE)"
.sp
\fBاستفاده معمول\fP
.sp
هنگام شروع، تمام آرگومان‌های خط فرمان به \fBrg\fP منتقل می‌شوند (با افزودن \fB\-\-json\fP و \fB\-\-no\-config\fP).
سپس خروجی JSON تجزیه شده و یک رابط خط فرمانی (که در ادامه توضیح داده شده) در اختیارتان قرار می‌گیرد.
.sp
توجه داشته باشید از آنجا که از گزینهٔ \fB\-\-json\fP استفاده می‌شود، تعدادی از گزینه‌های \fBrg\fP در دسترس نخواهند بود.
برای مشاهده فهرستی از گزینه‌های پشتیبانی‌شده که به \fBripgrep\fP ارسال خواهند شد، \fBrgr \-\-help\fP را ببینید.
.sp
\fBگروه‌های تطبیق (Capturing Groups)\fP
.sp
می‌توانید هنگام استفاده از \fBrgr\fP از گروه‌های تطبیق استفاده کنید، به عنوان مثال \fBrgr "foo (\(rsw+)"\fP.
در صورت استفاده از آن‌ها، می‌توان با ارجاع به نامشان به صورت \fB$name\fP یا اندیس آنها به صورت \fB$1\fP از موارد مطابقت‌یافته در جایگزینی استفاده کرد.
این نحو از کریت regex به ارث رسیده است، ببینید: \c
.URL "https://docs.rs/regex/1.8.4/regex/struct.Captures.html#method.expand" "" ""
.sp
هنگام استفاده از گروه‌های تطبیق تنها یک الگو می‌تواند به صورت هم‌زمان ارسال شود (یعنی استفاده از چند گزینهٔ \fB\-e <pat>\fP مجاز نیست).
.sp
\fBجایگزینی خودکار\fP
.sp
برای جایگزین کردن هر مورد مطابقت‌یافته بدون باز کردن رابط تعاملی، \fB\-y\fP یا \fB\-\-autoreplace\fP را به همراه \fB\-r\fP یا \fB\-\-replace\fP ارسال کنید. برای مثال، \fBrgr \-y "old_name" \-r "new_name"\fP.
.sp
عبارت جایگزین باید به‌طور صریح مشخص شود. در صورت عدم وجود \fB\-r\fP یا \fB\-\-replace\fP، جایگزینی خودکار پیش از جستجو با خطا متوقف می‌شود.
.sp
\fBخواندن نتایج از یک فایل\fP
.sp
این ابزار همچنین از خواندن نتایج از یک فایل JSON با در نظر گرفتن سناریوی کاربردی زیر پشتیبانی می‌کند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
کاربر دستور "rg \-\-json <args> > rg\-results.json" را اجرا می‌کند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اکنون این ابزار می‌تواند با استفاده از آن نتایج از طریق "RGR_JSON_FILE=./rg\-results.json rgr" اجرا شود
.RE.SH "رابط کاربری (INTERFACE)"
.sp
برای مشاهدهٔ فهرست کلیدهای میانبر، هنگامی که در حالت \fBSELECT\fP هستید، کلید \fB?\fP را فشار دهید.
چند حالت مختلف وجود دارد:
.sp
\fBSELECT\fP
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
این حالت نخستین حالتی است که پس از اجرای \fBrgr\fP نمایش داده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
در این حالت فهرستی از تطابق‌ها نمایش داده می‌شود و می‌توان وضعیت آن‌ها را فعال یا غیرفعال کرد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
غیرفعال کردن یک تطابق بدین معناست که خود آن مورد \fIجایگزین نخواهد شد\fP.
.RE
.sp
\fBREPLACE\fP
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
در این حالت کاربر متن جایگزین مورد نظر را تایپ می‌کند و تطابق‌ها به‌صورت بی‌درنگ به‌روزرسانی می‌شوند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
توجه داشته باشید که این حالت صرفاً یک پیش‌نمایش است و هیچ تغییری روی دیسک نوشته نمی‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
در این حالت بایت‌های غیر UTF\-8 موجود در تطابق‌ها با نویسهٔ جایگزینِ UTF\-8 نشان داده می‌شوند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
فشردن control+s باعث می‌شود تمام تطابق‌های انتخاب‌شده با متن واردشده جایگزین شوند.
.RE
.sp
\fBCONFIRM\fP
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
پیش از نوشتن جایگزینی‌ها روی دیسک، تأیید کاربر درخواست می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
جایگزینی‌ها روی دیسک نوشته می‌شوند و تمام تلاش‌ها برای استفاده از کدگذاری صحیح فایل انجام می‌پذیرد (بخش FILE ENCODING را ببینید).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
توجه داشته باشید که \fBrgr\fP برشی از بایت‌ها به جز آنچه \fBrg\fP در خروجی خود گزارش کرده است را \fIجایگزین نخواهد کرد\fP (بخش FILE ENCODING را ببینید).
.RE
.sp
\fBHELP\fP
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
این حالت اطلاعاتی دربارهٔ \fBrgr\fP و کلیدهای میانبر آن ارائه می‌دهد.
.RE.SH "نویسه‌های کنترلی (CONTROL CHARACTERS)"
.sp
کاربر می‌تواند نحوهٔ نمایش نویسه‌های کنترلی در رابط کاربری را با فشردن control+v تغییر دهد.
حالت‌های مختلف عبارتند از:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
C: نمایش نویسه‌های کنترلی رایج
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
c: نمایش نویسه‌های کنترلی رایج (یک خطی)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
A: نمایش تمام نویسه‌های کنترلی
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
a: نمایش تمام نویسه‌های کنترلی (یک خطی)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
H: نمایش نویسه‌های کنترلی رایج به عنوان فاصله و حذف سایر موارد (مخفی)
.RE
.SH "کدگذاری فایل (FILE ENCODING)"
.sp
مدیریت کدگذاری فایل در دو مرحله رخ می‌دهد: در حالت \fBSELECT\fP و هنگام نوشتن جایگزینی‌ها روی دیسک.
.sp
\fIدر حالت \fBSELECT\fP\fP، بایت‌های غیر UTF\-8 با نویسهٔ جایگزین UTF\-8 نشان داده می‌شوند.
این اتفاق به این دلیل رخ می‌دهد که خود فایل‌ها هنوز خوانده نشده‌اند (اطلاعات مستقیماً از ripgrep می‌آید) و بنابراین کدگذاری فایل نامشخص است.
.sp
\fIدر حین جایگزینی\fP کدگذاری به شیوهٔ زیر مدیریت می‌شود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر یک نشانگر ترتیب بایت (BOM) پیدا شود، از آن کدگذاری استفاده می‌شود؛ در غیر این صورت
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر یک کدگذاری به ripgrep ارسال شده باشد، از آن کدگذاری استفاده می‌شود؛ در غیر این صورت
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
از کتابخانهٔ \fBchardet\fP (\c
.URL "https://github.com/thuleqaid/rust\-chardet" "" ")"
برای تشخیص کدگذاری استفاده می‌شود
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر آن هم ناموفق باشد، کدگذاری UTF8 فرض می‌شود
.RE
.sp
توجه داشته باشید که \fBrgr\fP \fIهرگز تطابقی را که انتظار ندارد، جایگزین نخواهد کرد\fP.
اگر در حین جایگزینی یک تطابق، بایت‌های جایگزین‌شونده با موارد تطبیق‌یافته توسط ripgrep یکسان نباشند، ابزار عملیات را لغو کرده و فایل روی دیسک نوشته نخواهد شد. (خطاها به STDERR گزارش می‌شوند.).SH "صفحه خانگی (HOMEPAGE)"
.sp
.URL "https://github.com/acheronfail/repgrep" "" ""
.SH "باگ‌ها و قابلیت‌ها (BUGS AND FEATURES)"
.sp
لطفاً باگ‌ها و درخواست‌های قابلیت‌ها را در سامانهٔ پیگیری مشکلات گزارش دهید.
تمام تلاش خود را به کار گیرید تا یک نمونه آزمایشی قابل بازتولید برای باگ‌ها فراهم کنید.
همچنین لطفاً نسخهٔ \fBrgr\fP و \fBrg\fP را نیز درج نمایید.