.gitignore چیست و چرا مهم است؟

هر پروژه فایل‌هایی می‌سازد که نباید وارد تاریخچهٔ Git شوند: خروجی Build، وابستگی‌های دانلودشده، کش IDE، و مهم‌تر از همه فایل‌های حاوی Secret مثل .env. اگر این‌ها Commit شوند، مخزن شلوغ، کند، و گاهی خطرناک می‌شود.

.gitignore فایلی است که به Git می‌گوید کدام مسیرها را هنگام Commit نادیده بگیرد. طبق مستندات GitHub، با ساختن .gitignore در ریشهٔ مخزن مشخص می‌کنید چه فایل‌ها و پوشه‌هایی نباید Check-in شوند. برای اینکه قانون با بقیهٔ تیم به اشتراک گذاشته شود، خودِ .gitignore را Commit کنید.

این مقاله تعریف، سطوح مختلف Ignore، اشتباه Untrack، نمونه‌های رایج، و پیوند امنیتی با نشت Secret را پوشش می‌دهد.

پاسخ کوتاه

.gitignore فهرست الگوهایی است که Git از Stage و Commit کردن آن‌ها صرف‌نظر می‌کند. برای فایل‌های محلی همه‌مخزنی می‌توانید Ignore سراسری کاربر را تنظیم کنید؛ برای استثناهای شخصی بدون اشتراک با تیم از .git/info/exclude استفاده کنید. اگر فایلی قبلاً Track شده، اضافه کردن نامش به gitignore کافی نیست — باید با git rm --cached از ایندکس خارج شود.

اهمیت امنیتی: بسیاری از نشت‌های API Key با نبودن .env در gitignore شروع می‌شوند. GitHub در راهنمای حذف دادهٔ حساس صریحاً می‌گوید فایل‌هایی که نباید Track شوند را به .gitignore اضافه و آن تغییر را Push کنید تا دیگران هم محافظت شوند.

gitignore جلوی ساخته شدن فایل حساس را نمی‌گیرد؛ جلوی وارد شدن ندانستهٔ آن به تاریخچهٔ مشترک را می‌گیرد.

سه لایهٔ Ignore

طبق Docs: برای فایل‌های موقت ادیتور که فقط روی ماشین شما ساخته می‌شوند، لایهٔ سراسری یا exclude مناسب است. برای .env و خروجی Build که همه تولید می‌کنند، .gitignore مخزن درست است.

الگوها به زبان ساده

• نام فایل دقیق: .env
• پسوند: *.log یا *.pem
• پوشه: node_modules/ یا dist/
• استثنا با ! : مثلاً نادیده گرفتن .env.* ولی نگه داشتن .env.example

gitignore

# نمونهٔ آموزشی — پروژه را با قالب رسمی زبان خودتان کامل کنید .env .env.* !.env.example node_modules/ dist/ build/ *.log .DS_Store *.pem

GitHub مجموعهٔ قالب‌های توصیه‌شده را در مخزن عمومی github/gitignore نگه می‌دارد؛ همچنین می‌توان از ژنراتورهایی مثل gitignore.io برای ترکیب OS و زبان و IDE استفاده کرد. قالب نقطهٔ شروع است، نه جایگزینی فکر کردن دربارهٔ Secretهای خاص پروژه.

فایل از قبل Track شده چه می‌شود؟

این پرتکرارترین اشتباه است: .env را به gitignore اضافه می‌کنید ولی Git همچنان تغییراتش را نشان می‌دهد، چون قبلاً Track شده است. مستند رسمی می‌گوید باید ابتدا Untrack کنید:

bash

git rm --cached path/to/file

این دستور فایل را از دیسک محلی پاک نمی‌کند؛ فقط از ایندکس Git برمی‌دارد تا از این به بعد Ignore شود. سپس Commitی بسازید که حذف از مخزن را ثبت کند. اگر Secret داخل تاریخچه بوده، Untrack نوک شاخه کافی نیست — به Runbook مقالهٔ ۰۸۲ بروید.

چرا برای کیفیت و امنیت مهم است؟

• جلوگیری از Commit تصادفی Secret و کلید.
• کوچک ماندن Clone و سریع‌تر شدن CI.
• کم شدن Conflict روی فایل‌های تولیدشدهٔ محلی.
• تمیز ماندن Review: Reviewر کد را می‌بیند نه پوشهٔ وابستگی.
• یکسان شدن تجربهٔ onboarding وقتی .env.example کنار gitignore باشد.

gitignore جایگزین Secret scanning نیست. کسی می‌تواند عمداً Force-add کند یا فایل را با نام دیگر Commit کند. لایه‌ها مکمل‌اند.

چک‌لیست برای مخزن جدید

1. قالب زبان/فریمورک را از github/gitignore بردارید.
2. .env و مشتقات را اضافه کنید؛ .env.example را استثنا کنید.
3. خروجی Build، پوشش تست، و کش IDE را پوشش دهید.
4. یک بار git status را با فایل‌های واقعی محلی آزمایش کنید.
5. در README یک خط بنویسید: فایل‌های محلی لازم کدام‌اند و چگونه ساخته می‌شوند.
6. اگر فایل حساسی قبلاً Commit شده، Untrack به علاوهٔ Rotate طبق ۰۸۲.

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

• Commit نکردن خودِ .gitignore — هر نفر Ignore محلی متفاوت می‌سازد.
• نادیده گرفتن کل پوشهٔ config در حالی که فایل‌های غیرحساس باید در Git باشند.
• اعتماد به Ignore بعد از Track شدن بدون rm --cached.
• گذاشتن Secret در فایلی با نام عجیب که در الگو نیست.
• Ignore کردن قفل وابستگی بدون تصمیم تیمی — reproducability را می‌زند.

تفاوت با Branch و Permission

گاهی تیم به‌جای gitignore سعی می‌کند با Private کردن مخزن یا محدود کردن Push مشکل فایل‌های زائد را حل کند. آن‌ها مسئلهٔ دسترسی‌اند نه مسئلهٔ انتخاب فایل. gitignore تصمیم می‌گیرد چه چیزی اساساً بخشی از تاریخچهٔ منبع باشد. هر سه لایه‌اند: دیدپذیری مخزن، مجوز افراد، و Ignore فایل.

جمع‌بندی برای تصمیم

.gitignore قرارداد تیمی برای نگه‌داشتن زباله و Secret بیرون از Git است. لایهٔ مخزن را Commit کنید، فایل‌های از پیش Trackشده را Untrack کنید، و برای Secret به scanning و Rotate هم تکیه کنید. قالب‌های رسمی GitHub شروع خوب‌اند؛ فهرست Secretهای اختصاصی پروژه را خودتان کامل کنید.

اگر امروز یک کار می‌کنید: وضعیت .env را در git status و تاریخچه بررسی کنید.

الگوهای پیشرفته‌تر که ارزش دارند

نادیده گرفتن پوشه با اسلش پایانی معمولاً فقط دایرکتوری را هدف می‌گیرد. الگوهای Recursion و استثنا با علامت تعجب وقتی مفیدند که بخواهید یک فایل نمونه را نگه دارید و بقیه را حذف کنید. اگر الگو پیچیده شد، در کامنت بالای همان بخش gitignore یک خط توضیح چرایی بنویسید — خودِ فایل هم خوانده می‌شود.

gitignore در زیرپوشه‌ها می‌تواند قوانین محلی اضافه کند، ولی برای تیم کوچک معمولاً یک فایل ریشه کافی و قابل‌فهم‌تر است. پراکندگی قانون‌ها onboarding را سخت می‌کند.

وابستگی‌ها و خروجی Build

پوشه‌هایی مثل node_modules یا vendor را معمولاً Ignore می‌کنند و به قفل وابستگی و نصب در CI تکیه می‌کنند. خروجی Build مثل dist را هم مگر وقتی سیاست انتشار Artifact از Git باشد Ignore کنید. اشتباه رایج: Commit کردن باینری بزرگ که Clone را سنگین و Review را غیرممکن می‌کند.

فایل‌های سیستم‌عامل مثل DS_Store و کش IDE را یا در gitignore مخزن بگذارید یا در Ignore سراسری کاربر. اگر فقط روی ماشین شما ظاهر می‌شوند، سراسری تمیزتر است؛ اگر همه درگیرند، مخزن.

امنیت فراتر از env

• کلیدهای SSH و فایل‌های pem و p12.
• JSON حساب سرویس ابری.
• داپ دیتابیس با دادهٔ واقعی.
• خروجی ابزارهای تشخیص که ممکن است Secret را در متن گزارش بیاورند.

هر پروژه یک فهرست اختصاصی دارد. همان فهرست را در onboarding بخوانید.

gitignore و CI

CI باید همان قوانین را ببیند چون از مخزن می‌خواند. اگر چیزی لازم است در CI ساخته شود، در Workflow بسازید نه اینکه از لپ‌تاپ Commit شود. برای اطمینان، Pipeline را طوری بنویسید که بدون فایل‌های محلی Ignoreشده هم سبز شود.

چک بعد از Clone

همکار جدید بعد از Clone باید بتواند با README و env.example بالا بیاید بدون نیاز به کپی فایل‌های Ignoreشده از چت. اگر نمی‌تواند، یا مستند ناقص است یا شما به فایل‌های محلی مخفی وابسته شده‌اید — هر دو بوی بد طراحی می‌دهند.

جمع‌بندی عملی

gitignore را روز اول مخزن بسازید، قالب زبان را پایه بگیرید، Secretها را صریح اضافه کنید، فایل‌های Trackشده را Untrack کنید، و اسکن را فراموش نکنید. این کار کسل‌کننده است و دقیقاً به همین دلیل جلوِ حوادث کسل‌کنندهٔ نیمه‌شب را می‌گیرد.

منابع و مراجع

• GitHub Docs — Ignoring files — https://docs.github.com/en/get-started/git-basics/ignoring-files
• GitHub — github/gitignore templates — https://github.com/github/gitignore
• GitHub Docs — Removing sensitive data from a repository — https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository

پس از بستن gitignore، نوشتن README واضح onboarding را کامل می‌کند.