gitignore - مشخص
کردن
فایل‌های
ردیابی‌نشده
برای
نادیده
گرفتن توسط
گیت
$XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude,
.gitignore
یک فایل gitignore
فایل‌های
عامدانه
ردیابی‌نشده‌ای
را مشخص
می‌کند که
گیت باید
آن‌ها را
نادیده
بگیرد.
فایل‌هایی
که از قبل
توسط گیت
ردیابی
می‌شوند
تحت تاثیر
قرار
نمی‌گیرند؛
برای
جزئیات به
بخش نکات (NOTES)
در ادامه
مراجعه
کنید.
هر سطر در
یک فایل gitignore
یک الگو را
مشخص
می‌کند.
هنگام
تصمیم‌گیری
درباره
نادیده
گرفتن یک
مسیر، گیت
معمولاً
الگوهای gitignore
را از چندین
منبع بررسی
می‌کند که
ترتیب
اولویت
آن‌ها از
بالاترین
به
پایین‌ترین
به شرح زیر
است (در یک
سطح اولویت
یکسان،
آخرین
الگوی
منطبق
نتیجه را
تعیین
می‌کند):
•الگوهای
خوانده‌شده
از خط فرمان
برای
دستوراتی
که از آن‌ها
پشتیبانی
می‌کنند.
•الگوهای
خوانده‌شده
از یک فایل
.gitignore در همان
دایرکتوری
مسیر، یا در
هر
دایرکتوری
والد (تا
بالاترین
سطح درخت
کاری)، به
طوری که
الگوهای
موجود در
فایل‌های
سطوح
بالاتر
توسط
الگوهای
موجود در
فایل‌های
سطوح
پایین‌تر
تا
دایرکتوری
حاوی فایل
بازنویسی
می‌شوند.
این الگوها
نسبت به
مکان فایل
.gitignore مطابقت
داده
می‌شوند. یک
پروژه
معمولاً
چنین
فایل‌های
.gitignore را در
مخزن خود
قرار
می‌دهد که
حاوی
الگوهایی
برای
فایل‌های
تولیدشده
به عنوان
بخشی از
ساخت پروژه
است.
•الگوهای
خوانده‌شده
از $GIT_COMMON_DIR/info/exclude.
•الگوهای
خوانده‌شده
از فایل
مشخص‌شده
توسط متغیر
پیکربندی
core.excludesFile.
اینکه یک
الگو در
کدام فایل
قرار گیرد
بستگی به
نحوه
استفاده از
آن الگو
دارد.
•الگوهایی
که باید
نسخه‌بندی
شوند و از
طریق کلون
به سایر
مخازن
توزیع
گردند (یعنی
فایل‌هایی
که همه
توسعه‌دهندگان
می‌خواهند
نادیده
گرفته شوند)
باید در یک
فایل .gitignore
قرار
گیرند.
•الگوهایی
که مختص یک
مخزن خاص
هستند اما
نیازی به
اشتراک‌گذاری
با سایر
مخازن
مرتبط
ندارند
(مانند
فایل‌های
کمکی که در
داخل مخزن
قرار دارند
اما مختص
گردش کار یک
کاربر خاص
هستند) باید
در فایل
$GIT_COMMON_DIR/info/exclude قرار
گیرند.
•الگوهایی
که کاربر
می‌خواهد
گیت در همه
شرایط
آن‌ها را
نادیده
بگیرد
(مانند
فایل‌های
پشتیبان یا
موقتی
تولیدشده
توسط
ویرایشگر
متن منتخب
کاربر)
عموماً در
فایلی قرار
می‌گیرند
که توسط core.excludesFile
در فایل ~/.gitconfig
کاربر مشخص
شده است.
مقدار
پیش‌فرض آن
$XDG_CONFIG_HOME/git/ignore است. اگر
$XDG_CONFIG_HOME تنظیم
نشده یا
خالی باشد،
به جای آن از
$HOME/.config/git/ignore
استفاده
می‌شود.
ابزارهای
سطح پایین
گیت، مانند
git ls-files و git read-tree،
الگوهای gitignore
مشخص‌شده
توسط
گزینه‌های
خط فرمان یا
از
فایل‌های
مشخص‌شده
با
گزینه‌های
خط فرمان را
می‌خوانند.
ابزارهای
سطح بالاتر
گیت، مانند
git status و git add، از
الگوهای
منابع
مشخص‌شده
در بالا
استفاده
می‌کنند.
•یک سطر
خالی با هیچ
فایلی
مطابقت
ندارد،
بنابراین
می‌تواند
به عنوان
جداکننده
برای
خوانایی
بهتر عمل
کند.
•سطری که
با # آغاز
می‌شود به
عنوان
توضیح در
نظر گرفته
می‌شود.
برای
الگوهایی
که با علامت
هش آغاز
می‌شوند،
یک بک‌اسلش
("\") در
ابتدای آن
قرار دهید.
•فاصله‌های
انتهایی
نادیده
گرفته
می‌شوند
مگر اینکه
با بک‌اسلش
("\")
نقل‌قول
شده باشند.
•پیشوند
اختیاری "!"
که الگو را
نقیض (منفی)
می‌کند؛ هر
فایل
منطبقی که
توسط یک
الگوی قبلی
مستثنی شده
بود،
مجدداً
شامل خواهد
شد. اگر یک
دایرکتوری
والد آن
فایل
مستثنی شده
باشد، شامل
کردن مجدد
یک فایل
امکان‌پذیر
نیست. گیت به
دلایل
عملکردی
دایرکتوری‌های
مستثنی‌شده
را فهرست
نمی‌کند،
بنابراین
هرگونه
الگو روی
فایل‌های
درون آن‌ها
تاثیری
نخواهد
داشت،
صرف‌نظر از
اینکه در
کجا تعریف
شده باشند.
برای
الگوهایی
که با یک "!"
واقعی آغاز
می‌شوند،
یک بک‌اسلش
("\") در
ابتدای آن
قرار دهید،
به عنوان
مثال: "\!important!.txt".
•اسلش
"/" به عنوان
جداکننده
دایرکتوری
استفاده
می‌شود.
جداکننده‌ها
ممکن است در
ابتدا، وسط
یا انتهای
الگوی
جستجوی .gitignore
وجود داشته
باشند.
•اگر یک
جداکننده
در ابتدا یا
وسط (یا هر دو)
الگو وجود
داشته
باشد،
آنگاه الگو
نسبت به سطح
دایرکتوری
همان فایل
.gitignore خاص
سنجیده
می‌شود. در
غیر این
صورت الگو
ممکن است در
هر سطحی زیر
سطح فایل .gitignore
نیز مطابقت
یابد.
•الگوهای
خوانده‌شده
از منابع
استثنا که
خارج از
درخت کاری
هستند،
مانند $GIT_COMMON_DIR/info/exclude و
core.excludesFile، به
گونه‌ای
بررسی
می‌شوند که
گویی در
ریشه درخت
کاری مشخص
شده‌اند؛
یعنی یک "/"
آغازین در
چنین
الگوهایی،
تطبیق را در
ریشه مخزن
تثبیت
می‌کند.
•اگر یک
جداکننده
در انتهای
الگو وجود
داشته
باشد،
آنگاه الگو
فقط با
دایرکتوری‌ها
مطابقت
خواهد
داشت؛ در
غیر این
صورت الگو
می‌تواند
با هر دو
مورد
فایل‌ها و
دایرکتوری‌ها
مطابقت
داشته
باشد.
•برای
مثال،
الگوی doc/frotz/ با
دایرکتوری
doc/frotz مطابقت
دارد، اما
با
دایرکتوری
a/doc/frotz مطابقت
ندارد؛ با
این حال frotz/
با frotz و a/frotz که
یک
دایرکتوری
باشند
مطابقت
دارد (تمام
مسیرها
نسبت به
فایل .gitignore
سنجیده
می‌شوند).
•یک
ستاره "*" با
هر چیزی به
جز اسلش
مطابقت
دارد. نویسه
"?" با هر
نویسه‌ای
به جز "/"
مطابقت
دارد. نماد
بازه،
مانند [a-zA-Z]،
می‌تواند
برای تطبیق
با یکی از
نویسه‌های
موجود در یک
بازه
استفاده
شود. برای
توضیحات
کامل‌تر به
fnmatch(3) و پرچم FNM_PATHNAME
مراجعه
کنید.
•یک
بک‌اسلش
("\")
می‌تواند
برای اسکیپ
کردن هر
نویسه‌ای
استفاده
شود؛ برای
نمونه، "\*"
با یک ستاره
واقعی
مطابقت
دارد (و "\a"
با "a"
مطابقت
می‌کند،
اگرچه
نیازی به
اسکیپ کردن
در آنجا
نیست).
همانند fnmatch(3)،
بک‌اسلش در
انتهای
الگو یک
الگوی
نامعتبر
محسوب
می‌شود که
هرگز با
چیزی
مطابقت
نمی‌یابد.
دو ستاره
متوالی ("**")
در
الگوهایی
که با مسیر
کامل نام
فایل
سنجیده
می‌شوند
ممکن است
معنای
ویژه‌ای
داشته
باشند:
•یک "**"
آغازین که
پس از آن یک
اسلش قرار
دارد، به
معنای
مطابقت در
تمام
دایرکتوری‌ها
است. برای
نمونه، "**/foo"
با فایل یا
دایرکتوری
"foo" در هر
مکانی
مطابقت
دارد، درست
مانند
الگوی "foo".
الگوی "**/foo/bar"
با فایل یا
دایرکتوری
"bar" در هر
کجایی که
مستقیماً
زیر
دایرکتوری
"foo" باشد
مطابقت
می‌کند.
•یک "/**"
انتهایی با
همه
محتویات
درون آن
مطابقت
دارد. برای
نمونه، "abc/**"
با تمام
فایل‌های
داخل
دایرکتوری
"abc"، نسبت
به مکان
فایل .gitignore، با
عمق
نامحدود
مطابقت
دارد.
•یک اسلش
و به دنبال
آن دو ستاره
متوالی و
سپس یک
اسلش، با
صفر یا چند
دایرکتوری
مطابقت
دارد. برای
نمونه، "a/**/b"
با "a/b"،
"a/x/b"، "a/x/y/b" و
غیره
مطابقت
می‌کند.
•سایر
ستاره‌های
متوالی به
عنوان
ستاره‌های
معمولی در
نظر گرفته
می‌شوند و
طبق قواعد
قبلی تطبیق
داده
خواهند شد.
متغیر
پیکربندی
اختیاری
core.excludesFile
نشان‌دهنده
مسیری به
فایلی حاوی
الگوهای
نام
فایل‌ها
برای
مستثنی
کردن است،
مشابه با
$GIT_COMMON_DIR/info/exclude.
الگوهای
موجود در
فایل exclude
علاوه بر
الگوهای
موجود در
$GIT_COMMON_DIR/info/exclude
استفاده
می‌شوند.
هدف از
فایل‌های gitignore
این است که
اطمینان
حاصل شود
فایل‌های
خاصی که
توسط گیت
ردیابی
نمی‌شوند،
همچنان
ردیابی‌نشده
باقی
می‌مانند.
برای
متوقف کردن
ردیابی
فایلی که در
حال حاضر
ردیابی
می‌شود، از
git rm --cached برای
حذف فایل از
ایندکس
استفاده
کنید. سپس
می‌توان
نام فایل را
به فایل .gitignore
اضافه کرد
تا از ثبت
مجدد فایل
در
کامیت‌های
بعدی
جلوگیری
شود.
گیت هنگام
دسترسی به
فایل .gitignore در
درخت کاری،
پیوندهای
نمادین را
دنبال
نمی‌کند.
این امر
رفتار
سیستم را
هنگام
دسترسی به
فایل از
ایندکس یا
درخت در
مقایسه با
فایل‌سیستم
یکدست نگه
می‌دارد.
•الگوی
hello.* با هر
فایل یا
دایرکتوری
که نام آن با
hello. آغاز شود
مطابقت
دارد. اگر
کسی بخواهد
این تطبیق
را فقط به
همان
دایرکتوری
محدود کرده
و
زیردایرکتوری‌های
آن را شامل
نشود،
می‌تواند
یک اسلش به
ابتدای
الگو اضافه
کند؛ یعنی
/hello.*؛ اکنون
الگو با hello.txt و
hello.c مطابقت
دارد اما با
a/hello.java مطابقت
نمی‌کند.
•الگوی
foo/ با
دایرکتوری
foo و مسیرهای
زیر آن
مطابقت
خواهد
داشت، اما
با یک فایل
معمولی یا
یک پیوند
نمادین foo
مطابقت
نخواهد کرد
(این امر با
نحوه
عملکرد کلی
pathspec در گیت
سازگار
است)
•الگوی
doc/frotz و /doc/frotz در هر
فایل .gitignore اثر
یکسانی
دارند. به
عبارت
دیگر، اگر
از قبل یک
اسلش میانی
در الگو
وجود داشته
باشد، اسلش
ابتدایی
تاثیری در
تمایز
نخواهد
داشت.
•الگوی
foo/*، با foo/test.json (یک
فایل
معمولی) و foo/bar
(یک
دایرکتوری)
مطابقت
دارد، اما
با foo/bar/hello.c (یک
فایل
معمولی)
مطابقت
ندارد،
زیرا ستاره
در الگو با
bar/hello.c که حاوی
اسلش است
مطابقت
نمی‌کند.
$ git status
[...]
# Untracked files:
[...]
# Documentation/foo.html
# Documentation/gitignore.html
# file.o
# lib.a
# src/internal.o
[...]
$ cat .git/info/exclude
# ignore objects and archives, anywhere in the tree.
*.[oa]
$ cat Documentation/.gitignore
# ignore generated html files,
*.html
# except foo.html which is maintained by hand
!foo.html
$ git status
[...]
# Untracked files:
[...]
# Documentation/foo.html
[...]
مثالی
دیگر:
$ cat .gitignore
vmlinux*
$ ls arch/foo/kernel/vm*
arch/foo/kernel/vmlinux.lds.S
$ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
فایل .gitignore
دوم مانع از
نادیده
گرفته شدن
arch/foo/kernel/vmlinux.lds.S توسط
گیت
می‌شود.
مثالی
برای
مستثنی
کردن
همه‌چیز به
جز یک
دایرکتوری
خاص foo/bar (به /*
توجه کنید -
بدون اسلش،
نویسه
عمومی
همه‌چیز
درون foo/bar را
نیز مستثنی
می‌کرد):
$ cat .gitignore
# exclude everything except directory foo/bar
/*
!/foo
/foo/*
!/foo/bar
