ما الذي يُتجاهل وما الذي يُودع في commit

يُقاس ملف .gitignore الجيد بمعاييره لا بطوله. والمعيار واحد: هل يستطيع من يستنسخ المستودع من الصفر إعادة إنتاج النتيجة نفسها بالشيفرة والإعدادات وحدها؟ ما يمكن إعادة إنتاجه يُتجاهل، وما لا يمكن، أو ما يثبّت النتيجة، يُودع.

ما يُتجاهل

النوع	أمثلة	السبب
مخرجات البناء	`dist/`، `build/`، `target/`، `.o`، `.class`	يُعاد إنتاجها من الشيفرة
الاعتماديات المثبتة	`node_modules/`، `vendor/` (PHP)، `.venv/`	يُعاد تثبيتها من ملف البيان وملف القفل
الذاكرات المؤقتة والسجلات	`.cache/`، `.pytest_cache/`، `*.log`، `coverage/`	تتغير مع كل تشغيل
البيئة المحلية والأسرار	`.env`، `.pem`، `local.properties`، `.tfstate`	تختلف بحسب الشخص/البيئة أو يجب ألا تتسرب
حالة الأدوات الشخصية	`.DS_Store`، `*.swp`، `.idea/workspace.xml`	لا علاقة لها بالمشروع (يُنصح بملف gitignore العام)

ما يُودع

ملفات القفل: package-lock.json، yarn.lock، pnpm-lock.yaml، Cargo.lock، poetry.lock، uv.lock، Gemfile.lock، composer.lock، go.sum، .terraform.lock.hcl. تضمن أن يثبّت الجميع الإصدارات نفسها. بعض القوالب، مثل قالب Angular، تتجاهل ملفات القفل، فراجع النتيجة.
أمثلة الإعداد: .env.example، config.example.yml. توضح القيم المطلوبة من دون أن تحتوي أسرارًا حقيقية.
مغلّفات أدوات البناء: gradlew وgradle/wrapper/، mvnw. تأكد من أن jar المغلّف لم يُتجاهل بسبب *.jar في قالب Java.
إعدادات المحرر التي اتفق عليها الفريق: .editorconfig، .vscode/settings.json، .vscode/extensions.json، .idea/codeStyles/. مشاركة إعدادات التنسيق والتدقيق تسهّل المراجعة.

ملفات .gitignore في المجلدات الفرعية

لا يقتصر .gitignore على الجذر. فملف .gitignore في مجلد فرعي يعمل على أساس ذلك المجلد وله الأولوية على الملفات الأعلى. وفي monorepo تحتاج فيه كل حزمة إلى قواعد مختلفة، يكون وضع ملف مستقل في كل مجلد حزمة أسهل قراءة.

repo/
├── .gitignore          # common: .DS_Store, .env, coverage/
├── apps/web/.gitignore # .next/, out/
└── services/api/.gitignore # target/

الإبقاء على المجلدات الفارغة

يتتبع git الملفات فقط ولا يحفظ المجلدات الفارغة. لكي يبقى المجلد موجودًا مع تجاهل محتواه، كمجلد السجلات، ضع فيه ملفًّا علامة ثم أعد تضمينه بالنفي.

/log/*
!/log/.keep

الأسماء مثل .keep أو .gitkeep ليست ميزة رسمية في git بل مجرد عرف، وأي اسم يعمل. وطريقة أخرى هي وضع ملف .gitignore في ذلك المجلد بالمحتوى التالي، فيتجاهل كل شيء عدا نفسه.

*
!.gitignore

عند دمج القوالب

المزيج الشائع هو لغة/إطار عمل أو اثنان + نظام التشغيل + المحرر. وإن كانت قواعد النظام والمحرر في الملف العام فيمكن حذفها.
تحقّق من الترتيب. القوالب التي تحتوي قواعد نفي (Gradle، VisualStudioCode) تأتي بعد القوالب ذات القواعد الواسعة (Java، Kotlin).
احذف التكرار مع الحفاظ على المعنى. تكرار القاعدة لا يغير السلوك لكنه يصعّب القراءة. ولا يحذف مولّد هذا الموقع التكرار إلا إذا لم توجد قاعدة نفي بينهما.
أبقِ تعليقات الأقسام. بعد أشهر ستحتاج إلى معرفة مصدر كل قاعدة لتتمكن من حذفها بأمان.
اختبر. أدخل المسارات الحقيقية المأخوذة من git ls-files في اختبار الأنماط للتأكد من عدم تجاهل ملفات عن غير قصد (مثل شيفرة الواجهة الأمامية التي تقع تحت lib/ في قالب Python).

قواعد قصيرة ومحددة

القواعد الواسعة جدًّا مثل *.json تبتلع ملفات الإعداد أيضًا. ضيّق المسار قدر الإمكان (/dist/)، وأنهِ المجلدات بشرطة مائلة لتمييزها عن الملفات التي تحمل الاسم نفسه. وتعليق من سطر واحد فوق القاعدة يشرح سببها يساعد الشخص التالي على تقرير ما إذا كان يمكن حذفها.