فایل gitignore چیست؟ جلوگیری از فایل‌های اضافی و رمزها در گیت

فایل gitignore فهرستی از الگوهاست که به گیت می‌گوید کدام فایل‌ها و پوشه‌ها را نادیده بگیرد تا خروجی‌های موقت، پوشه‌های build و رمزها وارد مخزن نشوند. کافی است در ریشه پروژه یک فایل .gitignore بسازید، الگوهای مدنظر را بنویسید و آن را commit کنید؛ از آن پس، فایل‌های مطابق با این الگوها به وضعیت staged اضافه نمی‌شوند.

فایل gitignore چیست و چطور کار می‌کند؟

.gitignore یک فایل متنی ساده است که هر خط آن یک الگو (pattern) تعریف می‌کند. این الگوها می‌توانند با wildcard ها نوشته شوند:

• * هر رشته‌ای از کاراکترها را می‌گیرد (مثلا *.log)
• ? یک کاراکتر واحد (مثلا file?.txt)
• ** تطابق بازگشتی در چند سطح پوشه (مثلا cache/**)
• / ابتدای رشته را به ریشه مخزن لنگر می‌کند (مثلا /dist فقط dist ریشه را می‌گیرد)
• علامت ! یک الگوی قبلی را مستثنی می‌کند (re-include)

خطوطی که با # شروع می‌شوند، توضیح هستند. ترتیب مهم است: اگر چند الگو با یک مسیر تطابق داشته باشند، قاعده‌ای که «دیرتر» اعمال می‌شود (و نزدیک‌تر به مسیر/فایل است) غالب خواهد بود. فایل‌های از پیش versioned توسط گیت حتی اگر با .gitignore تطابق داشته باشند، همچنان ردیابی می‌شوند تا زمانی که آن‌ها را از شاخص خارج کنید.

چه فایل‌هایی را باید نادیده بگیریم؟

• خروجی‌های build و بسته‌بندی: dist/, build/, out/, .next/
• پوشه‌های وابستگی‌ها: node_modules/, vendor/
• رمزها و پیکربندی‌های محلی: .env، *.env، *.pem، *.key، config/*.local.*
• فایل‌های لاگ و گزارش: *.log، logs/
• کش‌ها و فایل‌های موقتی زبان/ابزار: __pycache__/, .pytest_cache/, .mypy_cache/, coverage/
• فایل‌های سیستم عامل و IDE: .DS_Store، Thumbs.db، .idea/، .vscode/ (مگر تنظیمات workspace که واقعا باید اشتراکی باشند)

برای اشتراک ساختار متغیرهای محیطی بدون افشای رمز، یک فایل .env.example بدون مقادیر واقعی نگه دارید.

ساخت و اعمال .gitignore در یک مخزن موجود

1. در ریشه پروژه فایل را بسازید:

   touch .gitignore
   

2. الگوهای لازم را اضافه کنید، مثلا:

   # خروجی‌ها و وابستگی‌ها
   dist/
   build/
   node_modules/
   
   # رمزها و پیکربندی محلی
   .env
   .env.*
   *.pem
   *.key
   
   # لاگ‌ها و کش‌ها
   *.log
   coverage/
   

3. اگر فایل‌هایی از قبل commit شده‌اند، ابتدا آن‌ها را از شاخص خارج کنید تا .gitignore اثر کند:

   git rm --cached -r node_modules dist build .env
   git commit -m "Remove generated and secret files from index"
   

   این دستور فایل‌ها را از تاریخچه فعلی حذف نمی‌کند؛ فقط ردیابی در commit های بعدی را متوقف می‌کند.

4. اگر رمز یا کلید قبلا به مخزن و ریموت push شده است: بلافاصله آن رمز را در سرویس مربوطه rotate/غیرفعال کنید. سپس برای پاک‌سازی تاریخچه باید بازنویسی تاریخچه انجام دهید (ابزارهایی مثل git filter-repo یا BFG). این کار نیازمند درک اثراتش و احتمالا force-push است.

نمونه‌های آماده .gitignore برای فناوری‌های متداول

Node.js / React / Next.js

# وابستگی‌ها و خروجی‌ها
node_modules/
dist/
build/
.next/
coverage/

# لاگ‌ها
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# محیط و سیستم
.env
.env.*
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/

Python / Django

# بایت‌کد و کش‌ها
__pycache__/
*.py[cod]
*.pyo
.mypy_cache/
.pytest_cache/

# محیط مجازی
.venv/
venv/
env/

# پروژه
db.sqlite3
media/
staticfiles/

# محیط
.env

PHP / Laravel

/vendor/
/node_modules/
/public/storage
/storage/*.key
/.env
Homestead.yaml
Homestead.json
npm-debug.log*

الگوها: اولویت، استثناها و فایل‌های ریشه

قوانین زیر به درک بهتر رفتار الگوها کمک می‌کند:

• ترتیب مهم است؛ تطابق‌های دیرتر می‌توانند قبلی‌ها را خنثی کنند. برای استثنا از ! استفاده کنید:

  dist/
  !dist/.keep
  

  فایل dist/.keep حتی با وجود نادیده گرفتن dist/ ردیابی می‌شود.

• اسلش انتهایی نشان می‌دهد الگو برای پوشه است:

  logs/   # فقط پوشه logs
  *.log   # همه فایل‌های با پسوند log هرجا
  

• / در ابتدای الگو یعنی از ریشه مخزن:

  /dist   # فقط dist در ریشه
  dist    # هر dist در هر زیرپوشه
  

• فایل از قبل ردیابی‌شده با .gitignore ناپدید نمی‌شود. برای توقف ردیابی از git rm –cached استفاده کنید.
• می‌توانید در هر زیرپوشه هم .gitignore جداگانه بگذارید؛ قواعد نزدیک‌تر به فایل موثرترند.
• برای نادیده‌گیری‌های محلی که نباید commit شوند، از .git/info/exclude در همان مخزن استفاده کنید.

.gitignore سراسری برای همه پروژه‌ها

برای نادیده گرفتن فایل‌های سیستم عامل یا ابزارها در تمام مخازن (مثل .DS_Store یا Thumbs.db)، یک gitignore سراسری بسازید:

# ایجاد فایل ignore سراسری
touch ~/.gitignore_global

# نمونه الگوهای عمومی
printf ".DS_Store\nThumbs.db\n*.swp\n" >> ~/.gitignore_global

# معرفی به گیت
git config --global core.excludesFile ~/.gitignore_global

بررسی نتیجه و عیب یابی

• وضعیت فایل‌ها را ببینید:

  git status
  

  فایل‌هایی که در ignore هستند، به بخش Changes not staged for commit اضافه نمی‌شوند.

• دلیل نادیده گرفته شدن یک فایل را پیدا کنید:

  git check-ignore -v path/to/file
  

  این دستور فایل و شماره خط قاعده موثر را نمایش می‌دهد.

• اگر الگو بیش از حد کلی است، آن را خاص‌تر کنید. مثلا به جای *.json (که package.json را هم می‌گیرد)، فقط logs/*.json یا data/*.json را نادیده بگیرید.
• اگر پوشه‌ای را ignore کرده‌اید و می‌خواهید یک زیرمسیر خاص در آن ردیابی شود، باید مسیرهای میانی را نیز دوباره include کنید:

  data/
  !data/keep/
  !data/keep/file.txt
  

چک لیست سریع قبل از اولین commit

• وابستگی‌ها (node_modules، vendor) در .gitignore هستند.
• خروجی‌های build، پوشه‌های cache و فایل‌های log نادیده گرفته می‌شوند.
• رمزها و کلیدها (.env، *.pem، *.key) خارج از مخزن‌اند و یک .env.example دارید.
• فایل‌های سیستم عامل و IDE (.DS_Store، .idea، .vscode) نادیده گرفته شده‌اند.
• اگر فایل حساسی قبلا commit شده، آن را rotate و تاریخچه را پاکسازی کنید.

گام بعدی

اگر می‌خواهید کار با شاخه‌ها، بازنویسی تاریخچه و همکاری تیمی را اصولی یاد بگیرید، مسیر ادامه طبیعی شما یادگیری عمیق‌تر گیت است. برای شروع منسجم می‌توانید از آموزش گیت و گیت هاب بهره بگیرید.