.gitignore: چه چیزی نباید وارد مخزن شود

مخزن Git باید منبع حقیقتِ کد و پیکربندی قابل‌اشتراک باشد، نه انبار node_modules، خروجی build، فایل‌های IDE شخصی، و .env پر از رمز. وقتی این‌ها وارد تاریخچه می‌شوند، کلون کند می‌شود، تعارض بی‌معنا زیاد می‌شود، و گاهی secret هم لو می‌رود. فایل .gitignore قرارداد تیم برای «این‌ها را اصلاً نامزد commit نکن» است.

gitignore جادوی امنیتی کامل نیست: فقط جلوی untracked شدن را می‌گیرد. فایلی که قبلاً track شده همچنان می‌ماند تا صریحاً از index خارج شود.

پاسخ کوتاه

در ریشهٔ مخزن `.gitignore` بسازید و الگوهای dependency، artifact، لاگ، و فایل محیطی را اضافه کنید. برای فایلِ از‌قبل‌track‌شده: الگو را بنویسید، سپس `git rm -r --cached <path>` و commit. برای تنظیمات فقط‌روی‌ماشین‌خودتان از exclude محلی یا global gitignore استفاده کنید، نه برای قواعد تیم.

gitignore پیشگیری است؛ برای فایل trackشده باید untrack هم بکنید.

چه چیزهایی معمولاً ignore می‌شوند

• وابستگی‌ها: node_modules/, vendor/, .venv/
• خروجی build: dist/, build/, target/, *.o
• محیط و secret: .env, .env.local, *.pem (با آگاهی)
• لاگ و کش: *.log, .cache/, coverage/
• سیستم‌عامل و IDE: .DS_Store, Thumbs.db, .idea/, *.swp

لیست دقیق به اکوسیستم بستگی دارد. قالب‌های رسمی جامعه در مخزن github/gitignore نقطهٔ شروع خوب‌اند، ولی باید برای مونوریپو و ابزار سفارشی تیم تنظیم شوند.

نحوهٔ کار الگوها

gitignore

# توضیح با # *.log /build/ **/.DS_Store .env* !.env.example docs/**/*.pdf

• فاقد اسلش: در هر پوشه‌ای همخوانی می‌کند (بسته به قواعد).
• با اسلش ابتدایی: نسبت به محل فایل gitignore.
• ** برای سطوح تو در تو.
• ! برای استثنا؛ ترتیب مهم است.
• فاصله و کاراکتر خاص را با دقت escape کنید.

مستندات gitignore جزئیات تقدم را توضیح می‌دهد: الگویی در فایل پایین‌تر یا نزدیک‌تر می‌تواند رفتار را تغییر دهد. برای شک، `git check-ignore -v path` بزنید.

bash

git check-ignore -v .env git check-ignore -v app/.env.local

چند لایه: محلی، مخزن، جهانی

bash

git config --global core.excludesFile ~/.config/git/ignore echo '.DS_Store' >> ~/.config/git/ignore

مثال پایه برای پروژهٔ وب رایج

gitignore

node_modules/ dist/ build/ .coverage/ *.log .env .env.* !.env.example .DS_Store .idea/ .vscode/*.log

.env.example را با مقدار جعلی نگه دارید تا هم‌تیمی‌ها کلیدهای لازم را ببینند بدون اینکه secret واقعی commit شود.

فایل قبلاً commit شده؛ حالا چه؟

bash

echo '.env' >> .gitignore git rm --cached .env git commit -m "chore: stop tracking .env" git push

--cached از index برمی‌دارد ولی فایل روی دیسک می‌ماند. اگر secret داخل تاریخچه است، فقط untrack کافی نیست؛ باید credential را بچرخانید و دربارهٔ پاک‌سازی تاریخچه تصمیم بگیرید.

الگوی مونوریپو و چندزبانه‌ها

در مونوریپو می‌توانید .gitignore ریشه + فایل در زیرپروژه‌ها داشته باشید. بهتر است قواعد مشترک را در ریشه متمرکز کنید تا تکرار متناقض کم شود. برای تولیدات هر پکیج مسیر مشخص بنویسید نه فقط `*.js` که ممکن است سورس را هم بگیرد.

اشتباه‌های رایج

• اضافه کردن node_modules بعد از commit اول و فراموش untrack.
• ignore کردن کل `.vscode/` در حالی که تیم launch.json مشترک می‌خواهد — استثناهای دقیق بگذارید.
• الگوی گشاد مثل `*` یا ignore کردن `*.json` و از دست رفتن package.json.
• اتکا به gitignore برای مخفی کردن secret در PR عمومی.
• commit کردن خودِ .gitignore با قواعد متناقض بدون review.

چک‌لیست PR اول پروژه

1. قالب زبان/فریم‌ورک را پایه بگیرید.
2. .env و کلیدها را ignore کنید؛ example بگذارید.
3. خروجی CI محلی و پوشهٔ پوشش تست را اضافه کنید.
4. با `git status` روی کلون تمیز بعد از install تأیید کنید زباله دیده نمی‌شود.
5. فایل‌های حساس از‌قبل‌track‌شده را پاک‌سازی کنید.

gitignore و GitHub

وقتی مخزن روی GitHub می‌سازید، می‌توانید قالب gitignore انتخاب کنید. این فقط نقطهٔ شروع است. همچنین UI گیت‌هاب فایل‌های ignoreشده را برای commit پیشنهاد نمی‌کند، ولی آپلود دستی یا تغییر نام می‌تواند اشتباه را دور بزند — انضباط محلی مهم است.

خلاصه

.gitignore قرارداد تمیزی مخزن است: وابستگی، build، محیط، و زبالهٔ سیستم را بیرون نگه می‌دارد. الگو را درست بنویسید، با check-ignore دیباگ کنید، فایل‌های trackشده را جدا untrack کنید، و برای secret به چرخش کلید و آموزش تیم هم فکر کنید.

سوالات متداول

چرا هنوز فایل ignoreشده را در status می‌بینم؟

احتمالاً قبلاً track شده. `git ls-files | rg pattern` و سپس rm --cached.

آیا می‌توان فقط برای خودم ignore کنم؟

بله؛ .git/info/exclude یا excludesFile سراسری. قواعد تیم را آنجا نگذارید.

ترتیب ! مهم است؟

بله؛ استثنا باید بعد از الگوی کلی بیاید تا اثر کند.

منابع و مراجع

• Git — gitignore: https://git-scm.com/docs/gitignore
• GitHub — gitignore templates repository: https://github.com/github/gitignore
• Git — git-rm: https://git-scm.com/docs/git-rm
• Git — git-check-ignore: https://git-scm.com/docs/git-check-ignore