AG(1)                                                                    AG(1)

نام (NAME)
       ag - جستجوگر متنی سریع شبیه به grep (The Silver Searcher)

خلاصه دستور (SYNOPSIS)
       ag [گزینه‌ها] الگو [مسیر ...]

توضیحات (DESCRIPTION)
       جستجوی بازگشتی برای الگو در مسیر. شبیه به grep یا ack، اما بسیار
       سریع‌تر.

گزینه‌ها (OPTIONS)
       --ackmate
              نمایش نتایج در قالبی قابل تجزیه توسط ابزار AckMate
              https://github.com/protocool/AckMate.

       --[no]affinity
              تنظیم وابستگی پردازنده ریسه‌ها (affinity) در صورت پشتیبانی
              سیستم‌عامل. مقدار پیش‌فرض true است.

       --agrc=پرونده
              استفاده از پرونده به جای متغیر $AGRC یا $HOME/.agrc برای
              گزینه‌های پیش‌فرض. برای غیرفعال کردن خواندن از فایل agrc از
              --no-agrc استفاده کنید. برای جزئیات بیشتر بخش AGRC را ببینید.

       -a --all-types
              جستجو در تمامی فایل‌ها. این گزینه شامل فایل‌های پنهان نمی‌شود و هیچ
              فایل نادیده‌گیری (ignore) را در نظر نمی‌گیرد.

       -A --after[=خطوط]
              چاپ خطوط پس از تطابق. در صورت مشخص نشدن، مقدار پیش‌فرض خطوط برابر
              با ۲ است.

       -B --before[=خطوط]
              چاپ خطوط پیش از تطابق. در صورت مشخص نشدن، مقدار پیش‌فرض خطوط
              برابر با ۲ است.

       --[no]break
              چاپ یک خط خالی جدید بین نتایج مطابقت در فایل‌های مختلف. این گزینه
              به صورت پیش‌فرض فعال است.

       -c --count
              فقط تعداد موارد منطبق را در هر فایل چاپ می‌کند. توجه: این مقدار
              تعداد کل تطابق‌ها است، نه تعداد خطوط منطبق. اگر تعداد خطوط را
              می‌خواهید، خروجی را با لوله به wc -l بفرستید.

       --[no]color
              نمایش کدهای رنگی در نتایج خروجی. به صورت پیش‌فرض فعال است.

       --color-line-number
              کدهای رنگی برای شماره خطوط. مقدار پیش‌فرض 1;33 است.

       --color-match
              کدهای رنگی برای اعداد و موارد منطبق در نتایج. مقدار پیش‌فرض 30;43
              است.

       --color-path
              کدهای رنگی برای نام مسیرها. مقدار پیش‌فرض 1;32 است.

       --column
              نمایش شماره ستون در نتایج خروجی.

       -C --context[=خطوط]
              چاپ خطوط قبل و بعد از موارد منطبق. در صورت مشخص نشدن، مقدار
              پیش‌فرض خطوط برابر با ۲ است.

       -D --debug
              نمایش مقادیر بسیار زیادی از اطلاعات اشکال‌زدایی (دیباگ). کاربردی
              ندارد مگر آن‌که واقعاً در حال خطایابی باشید.

       --depth=تعداد
              جستجو تا عمق تعداد دایرکتوری، مقدار -1 برای حالت نامحدود است.
              مقدار پیش‌فرض ۲۵ است.

       -E --extension=پسوند
              جستجو در فایل‌های دارای این پسوند. معادل با -j -G ´\.EXT$´ (مقدار
              پسوند می‌تواند یک قطعه عبارت باقاعده باشد).

       --[no]filename
              چاپ نام فایل‌ها. به صورت پیش‌فرض فعال است، مگر هنگام جستجو در یک
              تک‌فایل.

       -f --[no]follow
              دنبال کردن پیوندهای نمادین (symlinks). مقدار پیش‌فرض false است.

       -F --fixed-strings
              نام مستعار برای --literal به منظور سازگاری با دستور grep.

       --[no]group
              حالت پیش‌فرض، --group، موارد منطبق چندگانه در یک فایل را با
              یکدیگر گروه‌بندی کرده و همه را زیر یک‌بار ذکر نام فایل نمایش
              می‌دهد. گزینه --nogroup از این کار صرف‌نظر کرده و در عوض نام فایل
              را در ابتدای هر خط منطبق قرار می‌دهد.

       -g --filename-pattern=الگو
              چاپ نام فایل‌های منطبق با الگو.

       -G --file-search-regex=الگو
              فقط جستجو در فایل‌هایی که نام آن‌ها با عبارت باقاعده الگو همخوانی
              دارد.

       -H --[no]heading
              چاپ نام فایل‌ها در بالای محتوای منطبق.

       --help-types
              نام مستعار برای --list-file-types به منظور سازگاری با دستور ack.

       --hidden
              جستجو در فایل‌های پنهان. این گزینه همچنان از قوانین فایل‌های
              نادیده‌گیری (ignore) پیروی می‌کند.

       -I --ignore=الگو
              نادیده گرفتن فایل‌ها و دایرکتوری‌هایی که نام آن‌ها با الگو همخوانی
              دارد. استفاده از نام‌های دقیق و تحت‌اللفظی فایل‌ها و پوشه‌ها نیز
              مجاز است.

       --ignore-dir=الگو
              نام مستعار برای --ignore به منظور سازگاری با دستور ack.

       -i --ignore-case
              تطابق بدون در نظر گرفتن بزرگی و کوچکی حروف (حساس نبودن به حروف
              بزرگ و کوچک).

       -j --just-filename
              هنگام استفاده از عبارت باقاعده جستجوی فایل (مانند -g یا -G)، فقط
              نام فایل را جستجو کن و کل مسیر را در نظر نگیر.

       -l --files-with-matches
              فقط چاپ نام فایل‌های حاوی موارد منطبق، نه خود خطوط منطبق. یک
              پرس‌وجوی خالی تمام فایل‌هایی را که جستجو می‌شوند چاپ می‌کند.

       -L --files-without-matches
              فقط چاپ نام فایل‌هایی که هیچ موردی از تطابق را شامل نمی‌شوند.

       --list-file-types
              بخش انواع فایل (FILE TYPES) در ادامه را ببینید.

       -m --max-count=تعداد
              پرش از ادامه فایل پس از پیدا کردن تعداد تطابق. مقدار پیش‌فرض 0
              است که هرگز متوقف نمی‌شود.

       --[no]mmap
              تغییر وضعیت استفاده از ورودی/خروجی مبتنی بر نگاشت حافظه (mmap).
              در پلتفرم‌هایی که mmap() سریع‌تر از read() است، پیش‌فرض true است
              (تمام سیستم‌ها به جز macOS).

       --[no]multiline
              تطابق عبارات باقاعده در چندین خط (عبور از خطوط جدید). به صورت
              پیش‌فرض فعال است.

       -n --norecurse
              عدم پیمایش بازگشتی در دایرکتوری‌ها.

       --[no]numbers
              نمایش شماره خطوط. به صورت پیش‌فرض هنگام جستجو در جریان‌های ورودی
              (streams) یا تک‌فایل، شماره خطوط نمایش داده نمی‌شود.

       -o --only-matching
              فقط چاپ بخش منطبق خطوط.

       --one-device
              هنگام پیمایش بازگشتی دایرکتوری‌ها، پوشه‌هایی را که روی سایر
              دستگاه‌های ذخیره‌سازی قرار دارند اسکن نکن. این ویژگی به شما اجازه
              می‌دهد از اسکن دستگاه‌های کند متصل به شبکه اجتناب کنید. این قابلیت
              در همه پلتفرم‌ها پشتیبانی نمی‌شود.

       -p --path-to-ignore=مسیر
              مشخص کردن مسیر به یک فایل ignore. خاص.

       -P --pager=دستور
              استفاده از یک صفحه‌بندی‌کننده (pager) مانند less. برای غیرفعال
              کردن از --nopager استفاده کنید. در صورت هدایت خروجی با لوله
              (pipe) به برنامه‌ای دیگر، این گزینه نادیده گرفته می‌شود.
              صفحه‌بندی‌کننده به ترتیب اولویت از موارد زیر انتخاب می‌شود: آرگومان
              خط فرمان، متغیر محیطی PAGER، و دستور "less".

       --parallel
              تجزیه جریان ورودی به عنوان عبارت جستجو، نه داده‌ای که باید جستجو
              شود. این گزینه برای استفاده با ابزارهایی مانند GNU parallel
              طراحی شده است. به عنوان مثال: echo "foo\nbar\nbaz" | parallel
              "ag {} ." سه نمونه از ag را اجرا کرده و دایرکتوری جاری را برای
              "foo"، "bar" و "baz" جستجو می‌کند.

       --print-long-lines
              چاپ موارد منطبق در خطوط بسیار طولانی (به صورت پیش‌فرض بیش از 2k
              کاراکتر).

       --passthrough --passthru
              هنگام جستجو در جریان ورودی، تمام خطوط را حتی در صورت عدم تطابق
              چاپ کن.

       -Q --literal
              عدم تجزیه الگو به عنوان عبارت باقاعده (regex). تطابق مستقیم و
              تحت‌اللفظی متن.

       -q --silent
              نادیده گرفتن تمام پیام‌های گزارش، از جمله خطاها.

       -r --recurse
              پیمایش بازگشتی در دایرکتوری‌ها هنگام جستجو. مقدار پیش‌فرض true
              است.

       -s --case-sensitive
              تطابق حساس به بزرگی و کوچکی حروف.

       -S --smart-case
              تطابق حساس به بزرگی و کوچکی حروف در صورت وجود حروف بزرگ در الگو،
              و تطابق غیرحساس در غیر این صورت. به صورت پیش‌فرض فعال است.

       --search-binary
              جستجو در فایل‌های باینری برای یافتن موارد منطبق.

       --stats
              نمایش آمار جستجو (تعداد فایل‌های اسکن‌شده، زمان سپری‌شده و غیره).

       --stats-only
              فقط نمایش آمار جستجو (فایل‌های اسکن‌شده، زمان و غیره) و عدم نمایش
              هیچ خروجی دیگری.

       -t --all-text
              جستجو در تمام فایل‌های متنی. این گزینه شامل فایل‌های پنهان نمی‌شود.

       -u --unrestricted
              جستجو در تمامی فایل‌ها. این گزینه فایل‌های ignore. و gitignore. و
              غیره را نادیده می‌گیرد و فایل‌های باینری و پنهان را نیز جستجو
              می‌کند.

       -U --skip-vcs-ignores
              نادیده گرفتن فایل‌های ignore سیستم‌های کنترل نسخه (مانند
              gitignore. و hgignore.)، اما همچنان در نظر گرفتن فایل ignore..

       -v --invert-match
              تطابق تمام خطوطی که الگوی مشخص‌شده را شامل نمی‌شوند.

       -V --version
              نمایش اطلاعات نسخه ابزار.

       --vimgrep
              نمایش خروجی در قالبی مشابه دستور :vimgrep /pattern/g در ویرایشگر
              Vim.

              نمونه‌ای از پیکربندی در فایل vimrc./~:

              set grepprg=ag\ --vimgrep\ $* set grepformat=%f:%l:%c:%m

              سپس از :grep برای جستجوی عبارت استفاده کنید و با دستوراتی نظیر
              :copen، :cn، :cp و غیره بین نتایج جابه‌جا شوید.

       -w --word-regexp
              تطابق فقط برای کلمات کامل.

       --workers=تعداد
              استفاده از تعداد ریسه (ترد) پردازشی کارگر. مقدار پیش‌فرض تعداد
              هسته‌های پردازنده (CPU) با حداکثر سقف ۸ است.

       -W --width=تعداد
              برش دادن خطوط منطبق پس از تعداد کاراکتر مشخص‌شده.

       -X --invert-file-search-regex=الگو
              شبیه به -G، اما فقط در فایل‌هایی جستجو می‌کند که نام آن‌ها با عبارت
              باقاعده الگو همخوانی ندارد. جستجوهای مبتنی بر نوع فایل همچنان
              اعمال شده و معکوس نمی‌شوند.

       -z --search-zip
              جستجو در محتوای فایل‌های فشرده‌شده. در حال حاضر از قالب‌های gz و xz
              پشتیبانی می‌شود. این گزینه نیازمند کامپایل شدن ag به همراه
              کتابخانه‌های lzma و zlib است.

       -Z --null-lines
              استفاده از نویسه NULL (\0) به عنوان جداکننده خطوط به جای \n. این
              گزینه اساساً برای جستجو در فایل‌های خاص مانند /proc/pid/environ
              کاربرد دارد. این تنظیم به صورت سراسری برای تمامی فایل‌های
              جستجوشده اعمال می‌شود و \n به عنوان خط جدید در نظر گرفته نمی‌شود.
              این بدان معناست که اگر یک فایل متنی معمولی (بدون بایت تهی) حاوی
              تطابق باشد، کل فایل به گونه‌ای چاپ می‌شود که گویی یک خط واحد است.
              این تنظیم نحوه پردازش خطوط جدید در الگوهای regex را تغییر نمی‌دهد
              (یعنی تطابق PCRE دست‌نخورده می‌ماند).

       -0 --null --print0
              جداسازی نام فایل‌ها با \0 به جای \n: این گزینه به xargs -0
              <command> اجازه می‌دهد تا نام فایل‌های حاوی فاصله یا خطوط جدید را
              به درستی پردازش کند.

انواع فایل (FILE TYPES)
       امکان محدود کردن انواع فایل‌های مورد جستجو وجود دارد. به عنوان مثال، پاس
       دادن --html فقط فایل‌های با پسوندهای htm، html، shtml یا xhtml را جستجو
       می‌کند. برای مشاهده لیست انواع پشتیبانی‌شده، دستور ag --list-file-types
       را اجرا کنید.

نادیده گرفتن فایل‌ها (IGNORING FILES)
       به صورت پیش‌فرض، ابزار ag فایل‌هایی را که نامشان با الگوهای موجود در
       gitignore.، hgignore. یا ignore. مطابقت داشته باشد نادیده می‌گیرد. این
       فایل‌ها می‌توانند در هر کجای دایرکتوری‌های در حال جستجو قرار داشته باشند.
       فایل‌های باینری نیز به صورت پیش‌فرض نادیده گرفته می‌شوند. در نهایت، ag به
       دنبال الگوهای نادیده‌گیری در مسیر $HOME/.agignore می‌گردد.

       اگر می‌خواهید فیلترهای gitignore. و hgignore. را نادیده بگیرید اما
       همچنان ignore. را لحاظ کنید، از گزینه -U استفاده نمایید.

       از گزینه -t برای جستجو در تمامی فایل‌های متنی، از -a برای جستجو در تمام
       فایل‌ها، و از -u برای جستجو در همه موارد از جمله فایل‌های پنهان استفاده
       کنید.

فایل پیکربندی (AGRC)
       برای تغییر گزینه‌های "پیش‌فرض"، ag می‌تواند لیستی از آرگومان‌های خط فرمان
       را از یک فایل "agrc" بخواند. یک فایل "agrc" به ترتیب اولویت از میان این
       موارد انتخاب می‌شود: ۱) مقدار مسیر در --agrc=مسیر، ۲) متغیر محیطی AGRC،
       یا ۳) فایل پیش‌فرض $HOME/.agrc.

       در صورت تعیین گزینه --noagrc، فایل "agrc" مورد استفاده قرار نخواهد
       گرفت.

       فایل "agrc" باید حاوی لیستی از آرگومان‌های خط فرمان باشد، در هر خط یک
       آرگومان. نیازی به نقل‌قول کردن آرگومان‌ها همانند شل نیست، زیرا کل خط به
       عنوان یک آرگومان واحد در نظر گرفته می‌شود. برای گزینه‌های طولانی که یک
       مقدار می‌پذیرند، از ساختار --option=value به جای --option value استفاده
       کنید.

مثال‌ها (EXAMPLES)
       ag printf: یافتن موارد منطبق برای "printf" در دایرکتوری جاری.

       ag foo /bar/: یافتن موارد منطبق برای "foo" در مسیر /bar/.

       ag -- --foo: یافتن موارد منطبق برای "--foo" در دایرکتوری جاری. (همانند
       اکثر ابزارهای خط فرمان یونیکس، "--" برای نشان دادن این است که
       آرگومان‌های بعدی نباید به عنوان گزینه در نظر گرفته شوند.)

درباره (ABOUT)
       ابزار ag در اصل توسط Geoff Greer ایجاد شده است. اطلاعات بیشتر (و آخرین
       نسخه منتشرشده) در نشانی http://geoff.greer.fm/ag در دسترس است.

       این صفحه راهنما بخشی از فورک Allen Wild برای ag است که از نسخه ۲
       کتابخانه PCRE و سایر ویژگی‌های اضافی استفاده می‌کند:
       https://github.com/aswild/the_silver_searcher

همچنین ببینید (SEE ALSO)
       grep(1)

                                   May 2020                              AG(1)