GIT-GREP(1)                       Git Manual                       GIT-GREP(1)

نام (NAME)
       git-grep - چاپ خطوط منطبق با یک الگو

خلاصه دستور (SYNOPSIS)
       git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
                  [-v | --invert-match] [-h|-H] [--full-name]
                  [-E | --extended-regexp] [-G | --basic-regexp]
                  [-P | --perl-regexp]
                  [-F | --fixed-strings] [-n | --line-number] [--column]
                  [-l | --files-with-matches] [-L | --files-without-match]
                  [(-O | --open-files-in-pager) [<pager>]]
                  [-z | --null]
                  [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet]
                  [--max-depth <depth>] [--[no-]recursive]
                  [--color[=<when>] | --no-color]
                  [--break] [--heading] [-p | --show-function]
                  [-A <post-context>] [-B <pre-context>] [-C <context>]
                  [-W | --function-context]
                  [(-m | --max-count) <num>]
                  [--threads <num>]
                  [-f <file>] [-e] <pattern>
                  [--and|--or|--not|(|)|-e <pattern>...]
                  [--recurse-submodules] [--parent-basename <basename>]
                  [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>...]
                  [--] [<pathspec>...]


توضیحات (DESCRIPTION)
       جستجو برای الگوهای مشخص‌شده در فایل‌های ردیابی‌شده در درخت کاری، blobهای
       ثبت‌شده در فایل نمایه، یا blobها در اشیاء درخت (tree) داده‌شده. الگوها
       فهرست‌هایی از یک یا چند عبارت جستجو هستند که با نویسه خط جدید از هم جدا
       شده‌اند. یک رشته خالی به عنوان عبارت جستجو با تمام خطوط مطابقت دارد.

گزینه‌ها (OPTIONS)
       --cached
           به جای جستجو در فایل‌های ردیابی‌شده در درخت کاری، در blobهای ثبت‌شده
           در فایل نمایه جستجو می‌کند.

       --untracked
           علاوه بر جستجو در فایل‌های ردیابی‌شده در درخت کاری، در فایل‌های
           ردیابی‌نشده نیز جستجو می‌کند.

       --no-index
           جستجوی فایل‌ها در دایرکتوری جاری که توسط گیت مدیریت نمی‌شود، یا با
           نادیده گرفتن اینکه دایرکتوری جاری توسط گیت مدیریت می‌شود. این کار تا
           حدودی شبیه به اجرای ابزار معمولی grep(1) همراه با گزینه -r آن است،
           اما با مزایای اضافی، مانند استفاده از الگوهای pathspec برای محدود
           کردن مسیرها؛ برای اطلاعات بیشتر مدخل pathspec در gitglossary(7) را
           ببینید.

           این گزینه نمی‌تواند همراه با --cached یا --untracked استفاده شود.
           همچنین به grep.fallbackToNoIndex در بخش CONFIGURATION در زیر مراجعه
           کنید.

       --no-exclude-standard
           همچنین در فایل‌های نادیده‌گرفته‌شده با نادیده گرفتن سازوکار .gitignore
           جستجو می‌کند. تنها با گزینه --untracked مفید است.

       --exclude-standard
           به فایل‌های نادیده‌گرفته‌شده مشخص‌شده از طریق سازوکار .gitignore توجه
           نمی‌کند. تنها هنگام جستجوی فایل‌ها در دایرکتوری جاری با --no-index
           مفید است.

       --recurse-submodules
           جستجوی بازگشتی در هر زیرماژول که در مخزن فعال و دریافت (checked
           out) شده است. هنگامی که در ترکیب با گزینه <tree> استفاده شود،
           پیشوند تمام خروجی‌های زیرماژول، نام شیء <tree> پروژه والد خواهد بود.
           این گزینه نمی‌تواند همراه با --untracked استفاده شود، و اگر
           --no-index مشخص شده باشد هیچ تأثیری ندارد.

       -a, --text
           پردازش فایل‌های باینری به گونه‌ای که گویی متنی هستند.

       --textconv
           رعایت تنظیمات فیلتر textconv.

       --no-textconv
           رعایت نکردن تنظیمات فیلتر textconv. این حالت پیش‌فرض است.

       -i, --ignore-case
           نادیده گرفتن تفاوت حروف کوچک و بزرگ بین الگوها و فایل‌ها.

       -I
           عدم تطبیق الگو در فایل‌های باینری.

       --max-depth <depth>
           به ازای هر <pathspec> داده‌شده در خط فرمان، حداکثر تا <depth> سطح از
           دایرکتوری‌ها به پایین می‌رود. مقدار 1- به معنی عدم محدودیت است. این
           گزینه در صورتی که <pathspec> حاوی نویسه‌های عام (wildcard) فعال باشد
           نادیده گرفته می‌شود. به عبارت دیگر اگر "a*" با دایرکتوری به نام "a*"
           مطابقت داشته باشد، "*" به صورت تحت‌اللفظی تطبیق داده می‌شود، بنابراین
           --max-depth همچنان مؤثر است.

       -r, --recursive
           مشابه --max-depth=-1؛ این حالت پیش‌فرض است.

       --no-recursive
           مشابه --max-depth=0.

       -w, --word-regexp
           تطبیق الگو تنها در مرز کلمه (یا در ابتدای خط شروع شود یا قبل از آن
           یک نویسه غیرکلمه‌ای باشد؛ یا در انتهای خط پایان یابد یا بعد از آن یک
           نویسه غیرکلمه‌ای باشد).

       -v, --invert-match
           انتخاب خطوط غیرمنطبق.

       -h, -H
           به‌طور پیش‌فرض، دستور نام فایل را برای هر تطابق نشان می‌دهد. گزینه -h
           برای سرکوب این خروجی استفاده می‌شود. گزینه -H برای کامل بودن وجود
           دارد و کاری انجام نمی‌دهد جز اینکه گزینه -h را که پیش‌تر در خط فرمان
           داده شده لغو می‌کند.

       --full-name
           هنگامی که از یک زیردایرکتوری اجرا می‌شود، دستور معمولاً مسیرها را
           نسبت به دایرکتوری جاری خروجی می‌دهد. این گزینه خروجی مسیرها را نسبت
           به دایرکتوری اصلی پروژه اجباری می‌کند.

       -E, --extended-regexp, -G, --basic-regexp
           استفاده از عبارات منظم گسترده/پایه POSIX برای الگوها. پیش‌فرض
           استفاده از عبارات منظم پایه است.

       -P, --perl-regexp
           استفاده از عبارات منظم سازگار با پرل (Perl) برای الگوها.

           پشتیبانی از این نوع عبارات منظم یک وابستگی اختیاری زمان کامپایل
           است. اگر گیت با پشتیبانی از آن‌ها کامپایل نشده باشد، ارائه این گزینه
           باعث خاتمه با خطا خواهد شد.

       -F, --fixed-strings
           استفاده از رشته‌های ثابت برای الگوها (الگو به عنوان عبارت منظم تفسیر
           نمی‌شود).

       -n, --line-number
           افزودن شماره خط به ابتدای خطوط منطبق.

       --column
           افزودن آفست بایتی (شروع از ۱) اولین تطابق از ابتدای خط منطبق، به
           عنوان پیشوند.

       -l, --files-with-matches, --name-only, -L, --files-without-match
           به جای نمایش هر خط منطبق، تنها نام فایل‌هایی را نشان می‌دهد که حاوی
           تطابق هستند (یا نیستند). برای سازگاری بهتر با git diff، گزینه
           --name-only مترادفی برای --files-with-matches است.

       -O[<pager>], --open-files-in-pager[=<pager>]
           باز کردن فایل‌های منطبق در صفحه‌بند (نه خروجی grep).  اگر صفحه‌بند
           "less" یا "vi" باشد و کاربر تنها یک الگو مشخص کرده باشد، اولین فایل
           به‌طور خودکار در اولین تطابق قرار می‌گیرد. آرگومان pager اختیاری است؛
           در صورت مشخص شدن، باید بدون فاصله به گزینه متصل باشد. اگر pager
           مشخص نشود، از صفحه‌بند پیش‌فرض استفاده خواهد شد (ببینید: core.pager
           در git-config(1)).

       -z, --null
           استفاده از \0 به عنوان جداکننده نام مسیرها در خروجی، و چاپ آن‌ها
           به‌صورت دست‌نخورده. بدون این گزینه، نام مسیرهای دارای نویسه‌های
           «غیرمعمول» طبق توضیحات متغیر پیکربندی core.quotePath نقل‌قول می‌شوند
           (ببینید: git-config(1)).

       -o, --only-matching
           تنها بخش‌های منطبق (غیرخالی) از یک خط منطبق را چاپ می‌کند، به‌طوری که
           هر بخش در یک خط خروجی جداگانه باشد.

       -c, --count
           به جای نمایش هر خط منطبق، تعداد خطوطی را که مطابقت دارند نشان
           می‌دهد.

       --color[=<when>]
           نمایش تطابق‌های رنگی. مقدار باید یکی از موارد always (پیش‌فرض)، never
           یا auto باشد.

       --no-color
           خاموش کردن برجسته‌سازی تطابق‌ها، حتی زمانی که فایل پیکربندی پیش‌فرض را
           خروجی رنگی قرار داده باشد. مشابه --color=never.

       --break
           چاپ یک خط خالی میان تطابق‌های فایل‌های مختلف.

       --heading
           نمایش نام فایل در بالای تطابق‌های آن فایل به جای ابتدای هر خط
           نمایش‌داده‌شده.

       -p, --show-function
           نمایش خط قبلی حاوی نام تابع مربوط به تطابق، مگر اینکه خود خط منطبق
           نام تابع باشد. نام تابع به همان روشی تعیین می‌شود که git diff هدرهای
           قطعه پچ را مشخص می‌کند (ببینید: Defining a custom hunk-header در
           gitattributes(5)).

       -<num>, -C <num>, --context <num>
           نمایش <num> خط قبل و بعد، و قرار دادن خطی شامل -- میان گروه‌های
           پیوسته تطابق‌ها.

       -A <num>, --after-context <num>
           نمایش <num> خط بعد، و قرار دادن خطی شامل -- میان گروه‌های پیوسته
           تطابق‌ها.

       -B <num>, --before-context <num>
           نمایش <num> خط قبل، و قرار دادن خطی شامل -- میان گروه‌های پیوسته
           تطابق‌ها.

       -W, --function-context
           نمایش متن پیرامونی از خط قبلی حاوی نام تابع تا خط پیش از نام تابع
           بعدی، که عملاً کل تابعی را که تطابق در آن یافت شده است نشان می‌دهد.
           نام تابع به همان روشی تعیین می‌شود که git diff هدرهای قطعه پچ را
           مشخص می‌کند (ببینید: Defining a custom hunk-header در
           gitattributes(5)).

       -m <num>, --max-count <num>
           محدود کردن تعداد تطابق‌ها در هر فایل. هنگام استفاده از گزینه -v یا
           --invert-match، جستجو پس از تعداد مشخص‌شده از موارد عدم تطابق متوقف
           می‌شود. مقدار 1- نتایج نامحدود را برمی‌گرداند (پیش‌فرض). مقدار 0
           بلافاصله با وضعیت غیرصفر خارج می‌شود.

       --threads <num>
           تعداد ریسه‌های کاری grep برای استفاده. برای اطلاعات بیشتر NOTES ON
           THREADS و grep.threads در CONFIGURATION را ببینید.

       -f <file>
           خواندن الگوها از <file>، هر الگو در یک خط.

           ارسال الگو از طریق <file> امکان ارائه الگوی جستجوی حاوی \0 را فراهم
           می‌کند.

           همه انواع الگو از الگوهای حاوی \0 پشتیبانی نمی‌کنند. اگر نوع الگوی
           داده‌شده نتواند از چنین الگویی پشتیبانی کند، گیت با خطا خارج می‌شود.
           نوع الگوی --perl-regexp هنگامی که با بک‌اند PCRE v2 کامپایل شده باشد
           بیشترین پشتیبانی را برای این نوع الگوها دارد.

           در نسخه‌های گیت قبل از 2.23.0 الگوهای حاوی \0 بدون اطلاع به عنوان
           رشته ثابت در نظر گرفته می‌شدند. این موضوع هرگز مستند نشده بود،
           همچنین رفتارهای عجیب و مستندنشده‌ای میان مثلاً الگوهای غیر ASCII حاوی
           \0 و --ignore-case وجود داشت.

           در نسخه‌های آینده ممکن است پشتیبانی از الگوهای حاوی \0 برای بک‌اندهای
           جستجوی بیشتری اضافه شود؛ تا آن زمان، هنگامی که نوع الگوی مورد نظر
           از آن‌ها پشتیبانی نکند برنامه با خطا پایان می‌یابد.

       -e
           پارامتر بعدی الگو است. این گزینه باید برای الگوهایی که با - شروع
           می‌شوند استفاده شود و باید در اسکریپت‌هایی که ورودی کاربر را به grep
           ارسال می‌کنند به کار رود. الگوهای متعدد با or ترکیب می‌شوند.

       --and, --or, --not, ( ... )
           مشخص کردن نحوه ترکیب الگوهای متعدد با استفاده از عبارات بولی.  --or
           عملگر پیش‌فرض است.  --and اولویت بالاتری نسبت به --or دارد.  -e باید
           برای تمام الگوها استفاده شود.

       --all-match
           هنگام ارائه چندین عبارت الگو که با --or ترکیب شده‌اند، این فلگ برای
           محدود کردن تطابق به فایل‌هایی که خطوطی منطبق با همه آن‌ها دارند مشخص
           می‌شود.

       -q, --quiet
           خطوط منطبق را در خروجی چاپ نمی‌کند؛ در عوض، در صورت وجود تطابق با
           وضعیت 0 و در صورت عدم تطابق با وضعیت غیرصفر خارج می‌شود.

       <tree>...
           به جای جستجو در فایل‌های ردیابی‌شده در درخت کاری، در blobهای موجود در
           درخت‌های داده‌شده جستجو می‌کند.

       --
           پایان گزینه‌ها را اعلام می‌کند؛ بقیه پارامترها محدودکننده‌های
           <pathspec> هستند.

       <pathspec>...
           در صورت ارائه، جستجو را به مسیرهایی که حداقل با یک الگو مطابقت
           دارند محدود می‌کند. هم تطابق مسیرهای ابتدایی و هم الگوهای glob(7)
           پشتیبانی می‌شوند.

           برای جزئیات بیشتر درباره نحو <pathspec>، مدخل pathspec در
           gitglossary(7) را ببینید.

مثال‌ها (EXAMPLES)
       git grep 'time_t' -- '*.[ch]'
           جستجو برای time_t در تمام فایل‌های ردیابی‌شده c. و h. در دایرکتوری
           کاری و زیردایرکتوری‌های آن.

       git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)
           جستجو برای خطی که دارای #define و یکی از MAX_PATH یا PATH_MAX باشد.

       git grep --all-match -e NODE -e Unexpected
           جستجو برای خطی که دارای NODE یا Unexpected باشد در فایل‌هایی که
           خطوطی منطبق با هر دو دارند.

       git grep solution -- :^Documentation
           جستجو برای solution، با استثنا کردن فایل‌های موجود در Documentation.

نکاتی درباره ریسه‌ها (NOTES ON THREADS)
       هنگامی که از گزینه --open-files-in-pager استفاده شود، گزینه --threads
       (و پیکربندی grep.threads) نادیده گرفته خواهد شد و اجرای تک‌ریسه‌ای اجباری
       می‌شود.

       هنگام جستجو در مخزن اشیاء (با --cached یا با دادن اشیاء درخت)، در صورتی
       که --textconv داده شده باشد و تبدیلات متنی بسیار زیادی وجود داشته باشد،
       اجرا با چندین ریسه ممکن است کندتر از اجرای تک‌ریسه‌ای عمل کند. بنابراین،
       اگر در این حالت کارایی پایینی مشاهده شد، ممکن است استفاده از
       --threads=1 مطلوب باشد.

پیکربندی (CONFIGURATION)
       تمام موارد زیر این خط در این بخش به‌طور گزینشی از مستندات git-config(1)
       آورده شده است. محتوا همان چیزی است که در آنجا یافت می‌شود:

       grep.lineNumber
           در صورت تنظیم روی true، گزینه -n را به‌طور پیش‌فرض فعال می‌کند.

       grep.column
           در صورت تنظیم روی true، گزینه --column را به‌طور پیش‌فرض فعال می‌کند.

       grep.patternType
           تنظیم رفتار تطبیق پیش‌فرض. استفاده از مقدار basic، extended، fixed
           یا perl به ترتیب گزینه‌های --basic-regexp، --extended-regexp،
           --fixed-strings یا --perl-regexp را فعال خواهد کرد، در حالی که
           مقدار default از گزینه grep.extendedRegexp برای انتخاب بین basic و
           extended استفاده خواهد کرد.

       grep.extendedRegexp
           در صورت تنظیم روی true، گزینه --extended-regexp را به‌طور پیش‌فرض
           فعال می‌کند. این گزینه زمانی که گزینه grep.patternType روی مقداری
           غیر از default تنظیم شده باشد نادیده گرفته می‌شود.

       grep.threads
           تعداد ریسه‌های کاری grep برای استفاده. در صورت تنظیم نشدن (یا تنظیم
           روی 0)، گیت به تعداد هسته‌های منطقی در دسترس از ریسه‌ها استفاده خواهد
           کرد.

       grep.fullName
           در صورت تنظیم روی true، گزینه --full-name را به‌طور پیش‌فرض فعال
           می‌کند.

       grep.fallbackToNoIndex
           در صورت تنظیم روی true، اگر git grep خارج از یک مخزن گیت اجرا شود،
           به git grep --no-index عقب‌نشینی می‌کند. مقدار پیش‌فرض false است.

گیت (GIT)
       بخشی از مجموعه git(1)

Git 2.55.0                        2026-06-29                       GIT-GREP(1)