إذا فشل أمر git pull بينما يبدو مشروعك على Mac نظيفاً، فحدد أولاً الخطأ بدقة: قد يكون Git بصدد حماية ملفات محلية أو متجاهلة، أو إخفاء تغييرات الوحدات الفرعية (submodules)، أو رفض دمج تواريخ الفروع المتباعدة. في Terminal، تحقق من الحالة الكاملة للمستودع وتتبع الفروع قبل تعديل الملفات أو اختيار سلوك الدمج (merge) أو إعادة التأسيس (rebase).

ابدأ من داخل المستودع والتقط الخطأ الفعلي

افتح تطبيق Terminal، وانتقل إلى مجلد المشروع، وأعد تشغيل أمر السحب فقط إذا كنت بحاجة إلى إعادة إظهار الرسالة. يستخدم Terminal صدفة zsh افتراضياً في إصدارات macOS الحالية، وتعمل الأوامر المذكورة بين علامات اقتباس أدناه في zsh وbash. دليل Apple لـ Terminal

cd "/path/to/your/project"
git status --short --branch
git pull

استبدل المسار الموضوع بين علامتي اقتباس بمجلد مشروعك الفعلي. اقرأ رسالة خطأ السحب كاملة. تشير عبارة "Your local changes … would be overwritten" إلى وجود عائق على مستوى الملفات. بينما تعني عبارة "Divergent branches" أو "Not possible to fast-forward" أن تواريخ الإيداعات (commits) المحلية والبعيدة (upstream) بحاجة إلى اختيار طريقة للتوفيق بينهما. قد تبدو هذه المشكلات متشابهة في واجهات المستخدم الرسومية، لكنها تتطلب خطوات مختلفة للحل.

ابحث عن الملفات المخفية في عرض الحالة الموجز

يمكن أن يتجاهل العرض القصير للحالة تفاصيل مهمة. نفذ فحصاً أوفى للقراءة فقط:

git status --untracked-files=all --ignored=matching --ignore-submodules=none
git diff --
git diff --cached --

يقوم أمر git status عادةً بالإبلاغ عن الملفات غير المتتبعة، ولكن قد يخفيها إعداد محلي؛ يعرض الخيار --untracked-files=all الملفات الفردية داخل المجلدات غير المتتبعة. كما تُستبعد الملفات المتجاهلة ما لم يُطلب عرضها، لذا فإن الخيار --ignored=matching يكشف عن المسارات المتجاهلة التي تطابق قواعد التجاهل. ويطلب الخيار --ignore-submodules=none من أمر الحالة الإبلاغ عن تغييرات الوحدات الفرعية حتى لو كان التكوين يخفيها بخلاف ذلك. يوثق Git أوضاع الحالة هذه ويشير إلى أن المسارات المتجاهلة تتلقى علامة حالة مميزة. توثيق Git status

يعرض أمرا git diff تعديلات شجرة العمل المتتبعة والتغييرات المجهزة (staged)، على التوالي. ولا يعرضان محتويات الملفات المتجاهلة أو غير المتتبعة. وبالتالي، فإن النتيجة "النظيفة" من واجهة مستخدم رسومية، أو مجلد آخر، أو عرض حالة مصفى لا تثبت أن كل عائق ظاهر؛ استخدم Terminal في نفس المستودع وافحص المسار المحدد الذي ذكره Git بدقة. تستبعد قواعد التجاهل عمداً الملفات غير المتتبعة المطابقة من مخرجات الحالة العادية. توثيق Git ignore

إذا كان المسار المذكور متجاهلاً أو غير متتبع، فافحصه قبل نقله أو حذفه. لا تقم بتشغيل git clean، أو git reset --hard، أو الكتابة فوق المسار كحل تشخيصي مختصر: يمكن أن تؤدي هذه الأوامر إلى إزالة العمل أو الملفات المحلية. وإذا كان يحتوي على شيء تحتاجه، فاصنع نسخة منفصلة أو احتفظ به بطريقة أخرى قبل حل التعارض.

تحقق من الوحدات الفرعية (submodules) وعلامات الفهرس (index flags)

يمكن أن يبدو المستودع الذي يحتوي على وحدات فرعية نظيفاً في مستواه الأعلى بينما تحتوي إحدى الوحدات الفرعية على تعديلات محلية، أو ملفات غير متتبعة، أو إيداع مختلف تم سحبه. يطلب أمر الحالة الموسع أعلاه من Git عدم تجاهل حالة الوحدات الفرعية. يمكنك أيضاً الدخول إلى دليل الوحدة الفرعية المذكور وتشغيل git status --untracked-files=all هناك؛ حيث تمتلك كل وحدة فرعية شجرة عمل وحالة خاصة بها.

في حالات أقل شيوعاً، يمكن أن يحمل فهرس Git علامات تؤثر على كيفية تعامله مع المسارات. يُعلم خيار assume-unchanged نظام Git بافتراض أن الملف يطابق الفهرس، بينما يمكن لخيار skip-worktree تجنب تحديث مسار ما أثناء عمليات مثل السحب. افحص الإدخالات غير المعتادة باستخدام:

git ls-files -v

يسرد هذا الأمر المسارات المتتبعة مع علامات الفهرس؛ قد تشير العلامات ذات الأحرف الصغيرة إلى إدخالات assume-unchanged، بينما يشير الحرف S إلى skip-worktree. تعامل مع هذا كدليل فحص، وليس كأمر تنظيف. لا تقم بإزالة العلامات بشكل عشوائي عبر المستودع بأكمله؛ إذا تم ذكر مسار متأثر، فتحقق من محتوياته وإعدادات التجهيز الجزئي (sparse-checkout) للمشروع قبل تغيير حالة الفهرس الخاصة به. توثيق Git update-index

إذا كانت الرسالة تتعلق بفروع متباعدة

لا تعني شجرة العمل النظيفة أن فرعك المحلي والفرع البعيد (upstream) لهما نفس التاريخ. تحقق من الفرع الحالي وما يتتبعه:

git branch --show-current
git branch -vv
git status --short --branch

يمكن لمخرجات الحالة والفروع إظهار ما إذا كان الفرع المحلي متقدماً أو متأخراً أو متباعداً عن فرعه البعيد. يقوم أمر git pull أولاً بجلب التغييرات البعيدة ثم دمج الفرع البعيد المكوّن. يتوقف سلوكه الافتراضي المقتصر على التقديم السريع (fast-forward-only) عندما يتباعد الفرعان المحلي والبعيد؛ هذه سياسة تتعلق بتاريخ الإيداعات، وليست دليلاً على وجود تغييرات غير مدمجة في الملفات. توثيق Git pull

إذا كانت هناك إيداعات محلية، فاختر طريقة تناسب قواعد التعاون في المشروع: تعيد عملية rebase تطبيق الإيداعات المحلية فوق الفرع البعيد، بينما تجمع عملية merge بين التاريخين وقد تُنشئ إيداع دمج (merge commit). راجع مشرفي المستودع أو القواعد المتبعة في الفريق إذا لم تكن متأكداً. تجنب تعيين تفضيل سحب عام أو فرض إعادة تعيين الفرع قسراً فقط لكتم رسالة الخطأ؛ فكلاهما لا يوضح ما يجب أن يحدث لتلك الإيداعات.

استخدم الخطأ لتحديد الفحص التالي

يتطلب تعارض الملفات فحص المسار المذكور، بما في ذلك الملفات المتجاهلة والوحدات الفرعية. وتتطلب رسالة التباعد فحص تاريخ الفرع وتحديد كيفية دمج الإيداعات. إذا بقيت الحالة نظيفة ولكن الخطأ ذكر مساراً محدداً، فتأكد من أن Terminal يعمل في فرع العمل المتوقع، وافحص ذلك المسار مباشرة، وتحقق من علامات الفهرس ذات الصلة. الرسالة الدقيقة هي الأداة التشخيصية الأكثر فائدة: احتفظ بالملفات والإيداعات المحلية حتى تفهم نوع الرفض الذي يبلغ عنه Git.

المصادر