git checkout

الفروع والدمج

تبديل الفروع أو استعادة ملفات شجرة العمل

git checkout أمر متعدد الاستخدامات: يبدّل الفروع، وينشئ فروعًا جديدة، ويستعيد ملفات من commits محددة، ويمكنه وضع مستودعك في حالة «HEAD منفصل». ومع أن إصدارات Git الأحدث وزّعت بعض وظائفه على «git switch» و«git restore»، ما زال checkout شائع الاستخدام ومفهومًا على نطاق واسع.

الصيغة

git checkout <branch>
git checkout -b <new-branch> [<start-point>]
git checkout -B <branch> [<start-point>]
git checkout --detach [<branch>]
git checkout [--] <pathspec>...
git checkout <commit> -- <pathspec>...
[ ] اختياري| أو<arg> قيمة تُستبدل... قابل للتكرار--flag خيار

الخيارات

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

مبتدئ (3)

أنشئ فرعًا جديدًا وانتقل إليه فورًا. يعادل تشغيل git branch <name> ثم git checkout <name>.

موصى بهينشئ وينتقل في خطوة واحدة (الصيغة الحديثة: git switch -c)

مثال

git checkout -b feature-login

تخلّص من التغييرات غير المجهّزة في الملفات المحددة باستعادتها من منطقة التجهيز (الفهرس)، لا من HEAD. تبقى التغييرات المجهّزة. ويفصل -- مسارات الملفات عن أسماء الفروع.

عند الحاجةيتخلّص من التعديلات غير المجهّزة نهائيًا — وgit restore <file> هي الصيغة الحديثة

مثال

git checkout -- src/app.js

أخفِ رسائل الإفادة. مفيد في السكربتات التي لا تحتاج فيها إلى تأكيدات «Switched to branch».

عند الحاجةيخفي الرسائل؛ للسكربتات أساسًا

مثال

git checkout -q main

متوسط (8)

أنشئ فرعًا جديدًا أو أعد ضبطه إن كان موجودًا، ثم انتقل إليه. مفيد لإعادة ضبط فرع على الـ commit الحالي.

غير موصى بهيعيد ضبط فرع موجود بصمت وقد يترك commits يتيمة

مثال

git checkout -B feature-login

عند إنشاء فرع جديد، اضبط إعداد التتبّع لفرع الـ upstream. يتيح git pull/push دون تحديد المستودع البعيد.

موصى بهينشئ فرعًا محليًا مرتبطًا بفرع بعيد

مثال

git checkout --track origin/feature

عند إنشاء فرع جديد من فرع تتبّع بعيد، لا تضبط التتبّع. سيكون الفرع مستقلًا.

عند الحاجةينشئ فرعًا من فرع بعيد دون ربطه كـ upstream

مثال

git checkout --no-track -b feature origin/main

افصل HEAD عند الـ commit المحدد. يمكنك فحص شيفرة قديمة أو التجربة دون التأثير في أي فرع.

عند الحاجةفحص commit قديم؛ أنشئ فرعًا قبل التسجيل عليه

مثال

git checkout --detach v1.0.0

أعد ملفًا إلى حالته في commit محدد. يوضع الملف في مجلد عملك ومنطقة التجهيز معًا.

عند الحاجةيعيد النسخة القديمة من ملف، مجهّزة، دون تبديل الفرع

مثال

git checkout a1b2c3d -- src/app.js

أجبر الـ checkout حتى مع تغييرات غير محفوظة. يرمي كل التعديلات المحلية على الملفات المتتبَّعة (لا المتعارضة فقط) وأي ملفات غير متتبَّعة تعترض الطريق.

غير موصى بهيتخلّص من كل التغييرات غير المسجّلة في الملفات المتتبَّعة — استخدم stash بدلًا منه

مثال

git checkout -f main

أثناء تعارضات الدمج، اسحب نسختنا (الفرع الذي كنت عليه) من الملف المتعارض. مفيد لحل التعارض باختيار طرف. ملاحظة: أثناء rebase ينعكس ours/theirs.

عند الحاجةيحل ملفًا متعارضًا بالإبقاء على نسختك (ينعكس الطرفان أثناء rebase)

مثال

git checkout --ours config.js

أثناء تعارضات الدمج، اسحب نسختهم (الفرع الجاري دمجه) من الملف المتعارض. يقبل التغييرات الواردة. ملاحظة: أثناء rebase ينعكس ours/theirs.

عند الحاجةيحل ملفًا متعارضًا بأخذ الطرف القادم

مثال

git checkout --theirs config.js

متقدم (3)

أنشئ فرعًا جديدًا لم يولد بعد بلا تاريخ commits. تبقى الملفات الحالية في شجرة العمل ومنطقة التجهيز؛ وأول commit على هذا الفرع لن يكون له أب، فينشأ تاريخ مستقل.

عند الحاجةيبدأ تاريخًا مستقلًا (gh-pages، التوثيق)؛ نادرًا ما تحتاجه

مثال

git checkout --orphan gh-pages

عند تبديل الفرع مع تغييرات محلية تمس ملفات تختلف بين الفرعين، انقلها بدمج ثلاثي بدل الرفض؛ وتبقى التعارضات في شجرة العمل لتحلّها. منذ Git 2.55 تُحفظ التغييرات المحلية أولًا كمدخل stash، فلم يعد التبديل المتعارض قادرًا على إضاعتها.

عند الحاجةينقل التعديلات المحلية إلى فرع آخر؛ وقد يترك تعارضات

مثال

git checkout -m feature

اختر تفاعليًا الأجزاء التي تتخلّص منها من مجلد العمل. يتيح لك إبقاء بعض التغييرات والتراجع عن غيرها في الملف نفسه.

عند الحاجةيتخلّص من الأجزاء المختارة فقط — راجع كل سؤال بعناية

مثال

git checkout -p -- app.js

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

إنشاء الفروع

طرق مختلفة لإنشاء فرع جديد والانتقال إليه

الأمرإن كان الفرع موجودًاالتاريخالأنسب لـ
-b <name>يفشل بخطأعادي (موصول)العمل المعتاد على ميزة جديدة
-B <name>يُعاد ضبطه على الـ commit الحاليعادي (موصول)إعادة بدء فرع من الصفر
--orphan <name>يفشل بخطألا شيء (مفصول)gh-pages، التوثيق، صفحة بيضاء

التبديل مع تغييرات غير محفوظة

ما يحدث لتعديلاتك المحلية عند تبديل الفروع

الأمرتغييرات غير محفوظةمستوى الخطرمتى تستخدمه
git checkout <branch>ممنوع عند التعارضآمنالسلوك الافتراضي - يمنع الحوادث
git checkout -f <branch>تُحذف نهائيًاخطيرالتخلّي عمدًا عن كل التغييرات المحلية
git checkout -m <branch>تُدمج بدمج ثلاثيمتوسطنقل التغييرات إلى فرع آخر
git stash + checkoutمحفوظة لوقت لاحقآمنتبديل سياق مؤقت

استعادة الملفات

التخلّص من محتوى الملفات أو استعادته من مصادر مختلفة

الأمرالمصدريؤثر في التجهيزقابل للاستعادة
-- <file>الفهرس (النسخة المجهّزة)Noلا - التغييرات تضيع إلى الأبد
<commit> -- <file>commit محددنعم (مجهَّز)لا - لكنه مجهَّز للمراجعة
-p -- <file>الفهرس (تفاعلي)Noجزئي - اختر الأجزاء

تتبّع الفروع البعيدة

التحكم في العلاقة بين الفروع المحلية والبعيدة

الأمرينشئ تتبّعًاحالة الاستخدامgit push/pull
--track origin/featنعم (تلقائيًا)العمل على فرع زميليعمل دون وسائط
--no-track -b exp origin/mainلا (مستقل)التجربة بأمانيتطلب تحديد المستودع البعيد
<remote-branch>نعم (إن لم يكن هناك لبس)سحب سريع لفرع بعيديعمل دون وسائط

حل تعارضات الدمج

اختيار طرف أثناء تعارضات الدمج

الأمريُبقييتخلّصمتى تستخدمه
--ours <file>نسخة فرعكالتغييرات الواردةتغييراتك هي الصحيحة
--theirs <file>النسخة الواردةتغييراتكقبول تنفيذهم
(manual edit)نتيجة مدمجةلا شيءتحتاج أجزاء من الطرفين

checkout مقابل الأوامر الحديثة

قسّم Git 2.23+ الأمر checkout إلى أوامر مركّزة

الأمريبدّل الفروعيستعيد الملفاتيُنصح به لـ
git checkoutنعمنعمالاعتياد، إصدارات Git القديمة
git switchنعمNoنية واضحة: عمليات الفروع فقط
git restoreNoنعمنية واضحة: عمليات الملفات فقط

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

1
git stash

احفظ العمل الحالي غير المحفوظ

2
git checkout other-branch

انتقل إلى الفرع الآخر

3
(review or make quick fix)

أنجز العمل المطلوب على هذا الفرع

4
git checkout -

عُد إلى الفرع السابق (اختصار)

5
git stash pop

استعد عملك المحفوظ

1
git checkout main

انتقل إلى الفرع main

2
git pull origin main

احصل على أحدث التغييرات من المستودع البعيد

3
git checkout -b feature-name

أنشئ فرع الميزة الجديد وانتقل إليه

4
(make changes and commits)

اعمل على الميزة

5
git push -u origin feature-name

ادفع الفرع واضبط التتبّع

1
git status

اعرف الملفات التي عُدّلت

2
git diff file.js

راجع التغييرات التي ستتخلّص منها

3
git checkout -- file.js

تخلّص من تغييرات ملف محدد

4
git checkout -- .

أو تخلّص من كل التغييرات غير المجهّزة في الملفات المتتبَّعة

1
git log --oneline

اعثر على hash الـ commit الذي تحتاجه

2
git checkout <commit-hash>

اسحب ذلك الـ commit المحدد (HEAD منفصل)

3
(inspect, test, or debug)

افحص الشيفرة القديمة

4
git checkout main

عُد إلى الفرع main عند الانتهاء

1
git log --oneline -- file.js

اعثر على الـ commits التي غيّرت هذا الملف

2
git show <commit>:file.js

عاين النسخة القديمة

3
git checkout <commit> -- file.js

استعد الملف من ذلك الـ commit (يصبح مجهَّزًا)

4
git commit -m 'Restore file.js'

احفظ النسخة المستعادة في commit

1
git fetch origin

احصل على أحدث معلومات الفروع البعيدة

2
git branch -r

اعرض الفروع البعيدة المتاحة

3
git checkout --track origin/feature

أنشئ فرعًا محليًا يتتبّع البعيد

4
git pull

الآن يعمل pull دون تحديد المستودع البعيد

حل المشكلات

error: Your local changes to the following files would be overwritten by checkout

السبب: لديك تغييرات غير محفوظة تتعارض مع الفرع الهدف

احفظ تغييراتك في commit، أو خبّئها بـ stash، أو استخدم -f للإجبار (يتخلّص من التغييرات)

git stash && git checkout branch && git stash pop

error: pathspec 'branch-name' did not match any file(s) known to git

السبب: الفرع غير موجود، أو ربما أخطأت في كتابة الاسم

اعرض الفروع المتاحة بـ git branch -a، أو أنشئ الفرع بـ -b

git branch -a | grep branch-name

You are in 'detached HEAD' state

السبب: سحبت hash لـ commit أو وسمًا بدل اسم فرع

إن أردت مواصلة العمل فأنشئ فرعًا. وإلا فاسحب فرعًا موجودًا

git checkout -b new-branch-name

ضياع الـ commits المنفَّذة في حالة HEAD منفصل

السبب: نفّذت commits في حالة HEAD منفصل ثم انتقلت إلى فرع آخر

اعثر على الـ commits عبر الـ reflog وأنشئ فرعًا لحفظها

git reflog && git branch recovered-work <commit-hash>

تعذّر الـ checkout: سيُكتب فوق ملف غير متتبَّع

السبب: لديك ملفات غير متتبَّعة موجودة في الفرع الهدف

احذف الملفات غير المتتبَّعة أو انقلها أو خبّئها أولًا

git stash --include-untracked && git checkout branch

تخلّصت من تغييرات بالخطأ بـ checkout --

السبب: يحذف git checkout -- <file> التغييرات غير المحفوظة نهائيًا

للأسف، لا يستطيع Git استعادتها. راجع السجل المحلي في محررك

(check IDE local history if available)

fatal: 'name' could be both a local file and a tracking branch

السبب: ملف أو مجلد يحمل اسم الفرع البعيد نفسه الذي تريد سحبه

أضف -- في النهاية لتخبر Git أن الاسم فرع، أو استخدم git switch

git checkout branch-name --

الفرع لا يتحدّث بعد الـ checkout

السبب: ربما سحبت فرع تتبّع بعيد مباشرة

أنشئ فرع تتبّع محليًا بدل سحب origin/branch مباشرة

git checkout --track origin/branch-name

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

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

  • ✓استخدم 'git stash' قبل تبديل الفرع إن كان لديك عمل غير محفوظ في commit تريد إبقاءه
  • ✓فضّل 'git checkout -b' على 'git branch' + 'git checkout' منفصلين لإنشاء فرع والانتقال إليه
  • ✓استخدم '--' لفصل مسارات الملفات عن أسماء الفروع بوضوح: 'git checkout -- file.txt'
  • ✓فكّر في الأوامر الحديثة 'git switch' للفروع و'git restore' للملفات - النية أوضح
  • ✓استخدم 'git checkout -' للعودة سريعًا إلى الفرع السابق (مثل 'cd -')
  • ✓قبل استخدام '-f' لإجبار الـ checkout، تأكد أنك تريد فعلًا التخلّص من تغييراتك
  • ✓في حالة HEAD منفصل، أنشئ فرعًا فورًا إن كنت تنوي تنفيذ commits
  • ✓استخدم '--track' عند سحب الفروع البعيدة لضبط الدفع والسحب تلقائيًا
  • ✓استخدم 'git checkout <commit> -- <file>' لاستعادة ملفات محددة دون تبديل الفرع
  • ✓تجنّب سحب commits مباشرة إلا للتحقيق - استخدم أسماء الفروع للعمل المعتاد
  • ✓استخدم '-p' (وضع patch) عندما تريد التخلّص من بعض التغييرات فقط في ملف
  • ✓تحقّق دائمًا أنك على الفرع الصحيح بـ 'git branch' أو 'git status' قبل بدء العمل

أخطاء متكررة

  • ✗محاولة الـ checkout مع تغييرات غير محفوظة. يرفض Git التبديل إن كان سيكتب فوق تغييراتك - نفّذ commit أو stash، أو استخدم -f للإجبار (يتخلّص من التغييرات).
  • ✗الخلط بين checkout للفروع وcheckout للملفات. استعادة ملفات بالخطأ عند محاولة تبديل الفرع - ضع -- قبل مسارات الملفات: git checkout -- file.txt
  • ✗تنفيذ commits في حالة HEAD منفصل. تصبح هذه الـ commits يتيمة عند سحب فرع آخر - أنشئ فرعًا أولًا: git checkout -b my-branch
  • ✗استخدام -B دون فهم أنه يكتب فوق الموجود. قد يضيّع موضع الفرع الموجود - استخدم -b للفروع الجديدة، و-B فقط عند إعادة الضبط عن قصد.

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

A:

'git switch' أمر أحدث (Git 2.23+) لا يفعل إلا تبديل الفروع، مما يجعله أوضح وأكثر أمانًا. أما 'git checkout' فيبدّل الفروع ويستعيد الملفات معًا، وهذا قد يربك. استخدم 'git switch' للفروع و'git restore' للملفات إن كنت تفضّل الطريقة الحديثة.

A:

للأسف، لا يمكن ذلك بـ Git وحده - تُحذف التغييرات نهائيًا. بعض بيئات التطوير فيها سجل محلي قد يساعد. لهذا يجب الحذر مع هذا الأمر.

A:

يعني HEAD منفصل أنك سحبت commit محددًا بدل فرع. يمكنك الاستكشاف وتنفيذ commits، لكنها لن تنتمي إلى أي فرع. أنشئ فرعًا بـ 'git checkout -b name' لحفظ عملك.

A:

'-b' ينشئ فرعًا جديدًا ويفشل إن كان موجودًا أصلًا. '-B' ينشئ فرعًا جديدًا أو يعيد ضبط فرع موجود على الموضع الحالي. استخدم '-B' عندما تريد إعادة ضبط فرع عن قصد.

A:

استخدم 'git checkout other-branch -- path/to/file'. هذا ينسخ الملف من ذلك الفرع إلى مجلد عملك ومنطقة التجهيز. ثم يمكنك حفظه في commit على فرعك الحالي.

A:

يحميك Git من فقدان العمل. إن كان تبديل الفرع سيكتب فوق تغييراتك، فإنه يرفض. احفظ تغييراتك في commit، أو خبّئها بـ 'git stash'، أو استخدم 'git checkout -f' للإجبار (وهذا يتخلّص من التغييرات).

A:

ينقلك إلى الفرع الذي سحبته سابقًا، مثل 'cd -' في الـ shell. طريقة سريعة للتنقل بين فرعين تعمل عليهما.

A:

نفّذ أولًا 'git fetch origin'، ثم إما 'git checkout branch-name' (ينشئ Git فرع تتبّع تلقائيًا إن كان origin/branch-name موجودًا) أو صراحةً 'git checkout --track origin/branch-name'.

A:

نعم، استخدم 'git checkout -p <commit> -- <file>' للوضع التفاعلي، أو ببساطة 'git checkout <commit> -- <specific-files>' لاستعادة ملفات معينة فقط من ذلك الـ commit.

A:

لأنه يفعل أمرين مختلفين جدًا: تبديل الفروع واستعادة الملفات. قدّم Git 2.23 الأمرين 'git switch' و'git restore' للفصل بين المهمتين. وما زال 'git checkout' يعمل ويُستخدم على نطاق واسع.