git add

اللقطات الأساسية

إضافة محتوى الملفات إلى الفهرس (منطقة التجهيز)

يحدّث الأمر 'git add' الفهرس بالمحتوى الحالي لشجرة العمل، لتحضير محتوى الـ commit التالي. الفهرس، ويُسمّى أيضًا منطقة التجهيز، هو ما تستخدمه لتحضير محتوى الـ commit التالي. عندما تشغّل 'git commit' دون وسائط أخرى، لا يدخل إلا ما جُهّز. يمكن تشغيل هذا الأمر عدة مرات قبل الـ commit لإضافة التغييرات تدريجيًا.

الصيغة

git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--all | -A] [--update | -u] [--] [<pathspec>...]
[ ] اختياري| أو<arg> قيمة تُستبدل... قابل للتكرار--flag خيار

الخيارات

انقر على أي خيار لتوسيعه

مبتدئ (4)

جهّز كل شيء دفعة واحدة - كل الملفات الجديدة والتعديلات والحذف في مشروعك كله.

عند الحاجةيجهّز كل شيء، بما فيه الحذف — تحقّق من git status أولًا حتى لا يتسلل شيء غير مرغوب

مثال

git add -A

جهّز فقط تغييرات الملفات التي يعرفها Git أصلًا. تُتجاهل الملفات الجديدة غير المتتبَّعة.

عند الحاجةيجهّز تغييرات الملفات المتتبَّعة فقط — مفيد عندما لا تكون الملفات الجديدة جاهزة بعد

مثال

git add -u

اعرف بالضبط أي الملفات تُجهَّز أثناء تشغيل الأمر. يطبع اسم كل ملف لحظة إضافته.

عند الحاجةيعرض كل ملف أثناء تجهيزه؛ مفيد في عمليات add الكبيرة

مثال

git add -v .

عاين ما سيُجهَّز دون تجهيز أي شيء. ممتاز للتحقق قبل الـ commit.

موصى بهمعاينة غير ضارة لما سيجهّزه add واسع

مثال

git add -n .

متوسط (5)

اختر تفاعليًا أجزاء الملف التي تجهّزها. مثالي لتقسيم التغييرات الكبيرة إلى commits مركّزة.

موصى بهراجع وجهّز بالضبط الأجزاء التي تنتمي إلى هذا الـ commit

مثال

git add -p

افتح واجهة كاملة بقوائم لإدارة التجهيز. تتيح التجهيز وإلغاءه ومراجعة التغييرات تفاعليًا.

عند الحاجةتجهيز عبر قائمة؛ يغطي -p معظم الحاجات بشكل أكثر مباشرة

مثال

git add -i

جهّز ملفًا يتجاهله .gitignore عادةً. استخدمه عندما تحتاج إلى تجاوز قواعد التجاهل.

عند الحاجةيجهّز ملفات متجاهَلة — تأكّد أن الملف ينتمي فعلًا إلى المستودع

مثال

git add -f dist/bundle.js

سجّل أن ملفًا سيُضاف لاحقًا، دون تجهيز محتواه. مفيد لإظهار الملفات الجديدة في 'git diff'.

عند الحاجةيجعل الملفات الجديدة مرئية لـ git diff وadd -p قبل تجهيزها

مثال

git add -N newfile.js

أسكت التحذير عند إضافة مستودع مضمَّن (مجلد له .git خاص به) إلى الفهرس. استخدمه عندما تريد فعلًا إضافة مستودع git متداخل.

غير موصى بهفي العادة تريد git submodule add بدل مستودع مضمَّن مجرد

مثال

git add --no-warn-embedded-repo vendor/library

متقدم (6)

افتح الـ diff في محررك قبل التجهيز. يمكنك اختيار التغييرات التي تدخل يدويًا.

عند الحاجةتعديل الـ diff يدويًا قبل التجهيز؛ من السهل إنتاج patch لا يمكن تطبيقه

مثال

git add -e app.js

لا تُضف ملفات، حدّث فقط معلومات stat() الخاصة بها في الفهرس. يحتاج إلى pathspec. مفيد بعد تغييرات في أختام الوقت فقط.

عند الحاجةيحدّث فقط معلومات الملفات في الفهرس؛ وgit status يفعل ذلك بالفعل

مثال

git add --refresh .

تابع إضافة الملفات حتى لو فشل بعضها بسبب أخطاء. ينتهي الأمر مع ذلك برمز خروج غير صفري.

عند الحاجةيتخطّى الملفات التي لا يمكن إضافتها؛ وينتهي الأمر مع ذلك برمز غير صفري

مثال

git add --ignore-errors .

تحقّق إن كانت الملفات ستُتجاهل، حتى لو لم تكن موجودة بعد. يعمل مع ‎--dry-run فقط.

عند الحاجةمع ‎--dry-run فقط: يفحص قواعد التجاهل حتى للمسارات غير الموجودة

مثال

git add -n --ignore-missing *.tmp

جهّز الملفات الجديدة والمعدّلة، لكن تجاهل الملفات المحذوفة من شجرة العمل. اسم بديل: ‎--ignore-removal. لا أثر له إلا مع pathspec (مثل git add --no-all .).

غير موصى بهسلوك قديم من قبل 2.0 يترك الحذف دون تجهيز بصمت

مثال

git add --no-all .

ولّد الأجزاء التي يعرضها -p/-i بـ <n> أسطر سياق بدل 3 الافتراضية (أو diff.context). يتطلب Git 2.51 أو أحدث — الإصدارات الأقدم ترفضه بـ "unknown switch `U'".

عند الحاجةأسطر سياق أكثر في أجزاء add -p — يحتاج Git 2.51 أو أحدث

مثال

git add -p -U5 app.js

خبير (6)

تجاوز بت التنفيذ للملفات المضافة. استخدم +x لجعلها قابلة للتنفيذ و-x لإزالته.

عند الحاجةيضبط بت التنفيذ في الفهرس — مفيد على Windows

مثال

git add --chmod=+x script.sh

أعد تطبيق مرشح 'clean' على كل الملفات المتتبَّعة. مفيد بعد تغيير إعدادات نهايات الأسطر.

عند الحاجةشغّله مرة واحدة بعد تغيير قواعد نهايات الأسطر في .gitattributes

مثال

git add --renormalize .

اسمح بتحديث مدخلات الفهرس خارج مخروط الـ sparse checkout. للـ sparse checkouts المتقدمة فقط.

عند الحاجةفقط لمستودعات sparse checkout التي تعدّل مسارات خارج المخروط

مثال

git add --sparse path/outside/cone

اقرأ مسارات الملفات من ملف بدل سطر الأوامر. استخدم '-' للقراءة من stdin.

عند الحاجةللسكربتات ذات المسارات الكثيرة؛ يتجنّب حدود طول سطر الأوامر

مثال

git add --pathspec-from-file=files.txt

في -p/-i، اعرض السياق بين الأجزاء حتى عدد الأسطر المحدد، مع دمج الأجزاء المتقاربة في جزء واحد (0 افتراضيًا، أو diff.interHunkContext). يتطلب Git 2.51 أو أحدث.

عند الحاجةيدمج الأجزاء المتقاربة في add -p — يحتاج Git 2.51 أو أحدث

مثال

git add -p --inter-hunk-context=5

يُستخدم مع ‎--pathspec-from-file. تُفصل عناصر الـ pathspec بمحرف NUL بدل الأسطر الجديدة. يتعامل مع أسماء الملفات ذات المحارف الخاصة.

عند الحاجةمكمّل لـ ‎--pathspec-from-file للأسماء التي فيها أسطر جديدة أو محارف غريبة

مثال

git add --pathspec-from-file=files.txt --pathspec-file-nul

اختيار الخيار المناسب

أوامر التجهيز

أي الملفات تُجهَّز بكل أمر

الأمرملفات جديدةملفات معدّلةملفات محذوفةالنطاق
git add <file>✓✓✓الملف المحدد فقط
git add .✓✓✓المجلد الحالي وما تحته
git add -A✓✓✓المستودع كله
git add -u✗✓✓الملفات المتتبَّعة فقط
git add --no-all✓✓✗يتجاهل الحذف

خيارات تفاعلية

خيارات للتحكم الدقيق فيما يُجهَّز

الأمرالوضعالدقةحالة الاستخدام
git add -pPatchجزءًا جزءًاتجهيز تغييرات محددة داخل ملف
git add -eالمحررسطرًا سطرًاتعديل الـ diff يدويًا قبل التجهيز
git add -iقائمةملفًا ملفًاقائمة تجهيز تفاعلية كاملة

خيارات المعاينة والمخرجات

خيارات تعرض معلومات دون تعديل منطقة التجهيز

الأمرالإجراءيعدّل الفهرسالغرض
git add -nDry-run✗معاينة ما سيُجهَّز
git add -vتفصيلي✓عرض الملفات أثناء تجهيزها
git add --refreshالتحديث✗تحديث معلومات stat فقط

ملفات خاصة

خيارات للملفات التي تحتاج معاملة خاصة

الأمريعالجالسلوكالاستخدام المعتاد
git add -fملفات متجاهَلةتجاوز .gitignoreإضافة ملف يُتجاهل عادةً
git add -Nملفات جديدةنية الإضافة (فارغ)تتبّع ملف لـ git diff دون تجهيزه
git add --chmod=+xالملفات التنفيذيةضبط وضع الملفجعل السكربتات قابلة للتنفيذ
git add --sparseملفات sparseخارج المخروطتجهيز ملفات خارج الـ sparse checkout

خيارات متقدمة

خيارات للخبراء في حالات محددة

الأمرالغرضمتى تستخدمه
git add --renormalizeإعادة تطبيق مرشحات cleanبعد تغيير نهايات الأسطر في .gitattributes
git add --pathspec-from-fileقراءة المسارات من ملفتجهيز ملفات كثيرة من قائمة
git add --ignore-errorsالمتابعة رغم الأخطاءجهّز ما يمكن وتخطَّ الإخفاقات
git add --no-warn-embedded-repoإسكات تحذير الوحدة الفرعيةإضافة مستودعات متداخلة عن قصد

أمثلة على سير العمل

1
git status

راجع كل التغييرات أولًا

2
git add -A

جهّز كل الملفات الجديدة والمعدّلة والمحذوفة

3
git commit -m "Your message"

نفّذ commit لكل التغييرات المجهّزة

1
git add -p

اختر تفاعليًا تغييرات الإصلاح فقط (اضغط 'y' لأجزاء الإصلاح و'n' لأجزاء الميزة)

2
git commit -m "Fix login validation bug"

نفّذ commit للإصلاح فقط

3
git add -A

الآن جهّز تغييرات الميزة المتبقية

4
git commit -m "Add dark mode toggle"

نفّذ commit للميزة منفصلة

1
git status

اعرف ما المعدّل وما غير المتتبَّع

2
git add -u

جهّز تعديلات الملفات المتتبَّعة فقط

3
git status

تحقّق أن الملفات الجديدة ما زالت غير متتبَّعة

4
git commit -m "Update existing files"

نفّذ commit دون الملفات الجديدة

1
git add -n .

يعرض dry-run ما سيُضاف

2
git diff

راجع التغييرات الفعلية بالتفصيل

3
git add .

إن كان كل شيء جيدًا، جهّز فعلًا

1
git add dist/bundle.js

هذا يفشل - الملف متجاهَل

2
git add -f dist/bundle.js

الإضافة بالإجبار تتجاوز .gitignore

3
git commit -m "Add build for deployment"

نفّذ commit للملف المتجاهَل عادةً

مفاتيح الوضع التفاعلي

اختصارات لوحة المفاتيح لأوضاع git add التفاعلية. تعمل في وضع patch ‏(-p) والوضع التفاعلي (-i).

وضع patch

-p
yجهّز هذا الجزء
nلا تجهّز هذا الجزء
qخروج؛ لا تجهّز هذا الجزء ولا ما تبقّى
aجهّز هذا الجزء وكل الأجزاء التالية في الملف
dلا تجهّز هذا الجزء ولا الأجزاء التالية في الملف
sقسّم الجزء الحالي إلى أجزاء أصغر
eعدّل الجزء الحالي يدويًا
?اعرض المساعدة

الوضع التفاعلي

-i
1 / sStatus - عرض حالة التجهيز الحالية
2 / uUpdate - اختيار الملفات لتجهيزها
3 / rRevert - إلغاء تجهيز الملفات المختارة
4 / aAdd untracked - إضافة ملفات جديدة
5 / pPatch - الدخول في وضع patch للملفات المختارة
6 / dDiff - عرض الـ diff للتغييرات المجهّزة
7 / qخروج
8 / hمساعدة

حل المشكلات

الملف لا يُضاف (متجاهَل)

السبب: الملف يطابق نمطًا في .gitignore

ابحث عن النمط المطابق في .gitignore. استخدم -f لإجبار الإضافة إن كان ذلك مقصودًا.

git add -f <file>

خطأ «Permission denied»

السبب: الملف مقفل من عملية أخرى أو ليست لديك صلاحية القراءة

أغلق التطبيقات التي تستخدم الملف، أو تحقّق من صلاحياته. استخدم ‎--ignore-errors لمتابعة الملفات الأخرى.

git add --ignore-errors .

لا يحدث شيء عند تشغيل git add

السبب: قد تكون الملفات مجهّزة أصلًا، أو لا توجد تغييرات لإضافتها

شغّل git status لرؤية الحالة الحالية. الملفات المجهّزة أصلًا لا تُضاف مرة أخرى.

git status

الملفات الجديدة لا تظهر في git diff

السبب: الملفات غير المتتبَّعة لا تظهر في git diff افتراضيًا

استخدم git add -N لتعليم نية الإضافة، فيعرض git diff المحتوى بعدها.

git add -N <file> && git diff

تحذير بشأن مستودع git مضمَّن

السبب: تضيف مجلدًا يحتوي مجلد .git خاصًا به (مستودع متداخل)

احذف مجلد .git المتداخل، أو استخدم الوحدات الفرعية في git، أو أسكت التحذير.

git add --no-warn-embedded-repo <folder>

نهايات الأسطر تظهر كتغييرات باستمرار

السبب: نهايات أسطر غير متّسقة (CRLF مقابل LF) بين نظامك والمستودع

اضبط .gitattributes بـ 'text=auto' وأعد تطبيع كل الملفات.

git add --renormalize .

سكربتات (مثل git diff-files) تُظهر الملفات معدّلة مع أن المحتوى لم يتغيّر

السبب: تغيّرت أختام الوقت للملفات، فصارت معلومات stat المخزّنة في الفهرس قديمة

حدّث الفهرس لتجديد معلومات stat دون تجهيز. (يحدّثه git status تلقائيًا.)

git add --refresh .

نصائح وأخطاء شائعة

أفضل الممارسات

  • ✓راجع التغييرات قبل تجهيزها: استخدم 'git diff' لترى ما ستجهّزه، أو 'git add -p' للمراجعة التفاعلية.
  • ✓جهّز التغييرات المترابطة معًا: اجمع التغييرات المترابطة منطقيًا في commit واحد. لا تخلط إصلاح الأخطاء بالميزات الجديدة.
  • ✓استخدم 'git add -p' للتغييرات الكبيرة: عندما تُجري عدة تغييرات لا علاقة بينها في ملف، استخدم وضع patch لتجهيزها منفصلة.
  • ✓راجع git status كثيرًا: شغّل دائمًا 'git status' قبل التجهيز وبعده لتتحقق مما سيدخل الـ commit.
  • ✓احذر من 'git add .': فهو يجهّز كل شيء في المجلد الحالي. فكّر في تحديد أسماء الملفات أو استخدام 'git add -p' لتحكّم أكبر.
  • ✓اضبط .gitignore أولًا: قبل أول 'git add'، تأكد أن .gitignore يستبعد مخرجات البناء والاعتماديات والملفات الحساسة.
  • ✓استخدم dry-run للتحقق: عند الشك، يعرض 'git add -n .' ما سيُجهَّز دون تجهيز أي شيء.
  • ✓جهّز الحذف صراحةً: حذف ملف محليًا لا يجهّز الحذف. استخدم 'git add -u' أو 'git add -A' لتضمين الحذف.

أخطاء متكررة

  • ✗'git add .' مقابل 'git add -A': كلاهما يجهّز الملفات الجديدة والمعدّلة والمحذوفة، لكن '.' يغطي المجلد الحالي وما تحته فقط، بينما يغطي '-A' شجرة العمل كلها.
  • ✗نسيان أن 'git add' لا ينفّذ commit. الملفات تُجهَّز فقط وتحتاج إلى 'git commit' لتُسجَّل.
  • ✗إضافة ملفات كان يجب تجاهلها. راجع دائمًا .gitignore قبل تشغيل 'git add -A' أو 'git add .'
  • ✗عدم مراجعة التغييرات قبل تجهيزها. استخدم 'git add -p' لمراجعة ما تجهّزه بعناية أكبر.
  • ✗الخلط بين 'git add -u' و'git add -A': الخيار '-u' يجهّز تعديلات الملفات المتتبَّعة وحذفها فقط، لا الملفات الجديدة غير المتتبَّعة.

الأسئلة الشائعة

A:

منذ Git 2.0 يجهّز كلاهما الملفات الجديدة والمعدّلة والمحذوفة. الفرق في النطاق: 'git add .' يغطي المجلد الحالي ومجلداته الفرعية فقط، بينما يغطي 'git add -A' المستودع كله، أيًّا كان مجلدك الحالي.

A:

الملف على الأرجح مدرج في .gitignore. تحقّق بـ 'git check-ignore <file>'. وإن احتجت إلى إضافته رغم ذلك، فاستخدم 'git add -f <file>' للإجبار.

A:

نعم! استخدم 'git restore --staged <file>' (أو 'git reset HEAD <file>' في إصدارات Git القديمة) لإلغاء تجهيز ملف دون فقدان تغييراتك.

A:

استخدم 'git add -p <file>' للدخول في وضع patch التفاعلي. يعرض Git كل تغيير (hunk) ويتيح لك اختيار ما تجهّزه بـ y/n.

A:

يحدث هذا عادةً بسبب تغيّر نهايات الأسطر (CRLF/LF) أو صلاحيات الملفات. راجع 'git diff' لترى ما تغيّر. اضبط .gitattributes للتعامل مع نهايات الأسطر.

A:

أضف أولًا الملفات التي تريد استبعادها إلى .gitignore، ثم استخدم 'git add .'. أو أضف الملفات واحدًا واحدًا أو استخدم أنماطًا مثل 'git add *.js'.

A:

يخبر Git أنك تنوي إضافة الملف لاحقًا. يصبح الملف متتبَّعًا (يظهر في git diff) لكن محتواه لا يُجهَّز بعد. مفيد لمراجعة الملفات الجديدة قبل الـ commit.

A:

لا، يتتبّع Git الملفات فقط، لا المجلدات. الحل الشائع هو إضافة ملف .gitkeep أو .gitignore داخل المجلد الفارغ.