نام (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)