Git و GitHub

العمل مع الوسوم

13 دقيقة الدرس 16 من 35

العمل مع الوسوم

الوسوم في Git هي مراجع تشير إلى نقاط محددة من الالتزامات في تاريخ المستودع الخاص بك. تُستخدم عادة لتحديد نقاط الإصدار (v1.0، v2.0، إلخ) ولالتقاط المعالم المهمة في مشروعك. على عكس الفروع، لا تتغير الوسوم - فهي تحدد نقطة معينة في الزمن بشكل دائم.

فهم الوسوم

يدعم Git نوعين من الوسوم:

الوسوم الخفيفة (Lightweight Tags):
- مؤشر بسيط إلى التزام
- مجرد اسم لتجزئة الالتزام
- لا يتم تخزين معلومات إضافية
- مثل إشارة مرجعية

الوسوم المشروحة (Annotated Tags):
- كائنات كاملة في قاعدة بيانات Git
- تحتوي على اسم المُوسِم والبريد الإلكتروني والتاريخ
- يمكن أن تتضمن رسالة
- يمكن التوقيع عليها والتحقق منها باستخدام GPG
- موصى بها للإصدارات

أفضل ممارسة: استخدم دائماً الوسوم المشروحة للإصدارات وعلامات الإصدار العامة. استخدم الوسوم الخفيفة للعلامات المؤقتة أو الاستخدام الشخصي فقط.

إنشاء وسوم خفيفة

إنشاء وسم خفيف بسيط - فقط قدم اسم الوسم:

# إنشاء وسم خفيف عند الالتزام الحالي
git tag v1.0.0

# إنشاء وسم خفيف عند التزام محدد
git tag v0.9.0 abc1234

# عرض الوسم
git show v1.0.0

الوسوم الخفيفة هي مجرد مؤشرات - لا يتم تخزين بيانات إضافية.

إنشاء وسوم مشروحة

الوسوم المشروحة أكثر شمولاً وموصى بها للإصدارات:

# إنشاء وسم مشروح مع رسالة
git tag -a v1.0.0 -m "Release version 1.0.0"

# إنشاء وسم مشروح مع محرر لرسالة أطول
git tag -a v1.0.0

# وسم التزام محدد
git tag -a v0.9.0 abc1234 -m "Beta release"

# عرض معلومات الوسم التفصيلية
git show v1.0.0

عندما تعرض وسماً مشروحاً باستخدام git show، سترى معلومات المُوسِم والتاريخ والرسالة وتفاصيل الالتزام.

ملاحظة: تتضمن الوسوم المشروحة اسم المُوسِم والبريد الإلكتروني والطابع الزمني ورسالة الوسم. هذا يجعلها مثالية لتحديد الإصدارات الرسمية.

الإصدار الدلالي (Semantic Versioning)

الاتفاقية الأكثر شيوعاً لوسوم الإصدار هي الإصدار الدلالي (SemVer):

التنسيق: MAJOR.MINOR.PATCH

v1.0.0 - الإصدار المستقر الأولي
v1.0.1 - التصحيح: إصلاحات الأخطاء (متوافق مع الإصدارات السابقة)
v1.1.0 - الثانوي: ميزات جديدة (متوافق مع الإصدارات السابقة)
v2.0.0 - الرئيسي: تغييرات كبيرة (غير متوافق مع الإصدارات السابقة)

أمثلة:
git tag -a v1.0.0 -m "First stable release"
git tag -a v1.0.1 -m "Fix critical security bug"
git tag -a v1.1.0 -m "Add user authentication feature"
git tag -a v2.0.0 -m "Complete API redesign"

نصيحة: استخدم البادئة "v" للوسوم (v1.0.0) بدلاً من الأرقام فقط (1.0.0). هذا هو المعيار الصناعي ويساعد في التمييز بين وسوم الإصدار والمعرفات الرقمية الأخرى.

سرد الوسوم

يوفر Git عدة طرق لعرض الوسوم الخاصة بك:

# سرد جميع الوسوم
git tag

# سرد الوسوم المطابقة لنمط
git tag -l "v1.*"
git tag -l "v2.0.*"

# عرض تفاصيل الوسوم (الوسوم المشروحة فقط)
git tag -n
git tag -n5  # عرض أول 5 أسطر من الرسالة

# عرض معلومات تفصيلية عن وسم محدد
git show v1.0.0

دفع الوسوم إلى المستودع البعيد

بشكل افتراضي، git push لا يدفع الوسوم إلى المستودعات البعيدة. يجب دفعها صراحة:

# دفع وسم واحد
git push origin v1.0.0

# دفع جميع الوسوم دفعة واحدة
git push origin --tags

# دفع جميع الوسوم (بما في ذلك الخفيفة)
git push origin --tags

# دفع الوسوم المشروحة فقط
git push origin --follow-tags

تحذير: git push --tags يدفع جميع الوسوم (الخفيفة والمشروحة). استخدم --follow-tags لدفع الوسوم المشروحة فقط تلقائياً مع الالتزامات.

فحص الوسوم

يمكنك عرض الكود الخاص بك عند وسم محدد، لكن هذا يضعك في حالة "HEAD منفصل":

# فحص وسم (حالة HEAD منفصل)
git checkout v1.0.0

# إنشاء فرع جديد من وسم
git checkout -b hotfix-branch v1.0.0

# عرض الملفات عند وسم محدد دون الفحص
git show v1.0.0:path/to/file.txt

HEAD منفصل: عندما تفحص وسماً، فأنت لست على أي فرع. أي التزامات تقوم بها لن تنتمي إلى فرع ويمكن أن تُفقد. قم دائماً بإنشاء فرع جديد إذا كنت تريد إجراء تغييرات من نقطة موسومة.

حذف الوسوم

في بعض الأحيان تحتاج إلى إزالة الوسوم (أخطاء إملائية، إصدار خاطئ، إلخ):

# حذف وسم محلي
git tag -d v1.0.0

# حذف وسم بعيد (طريقتان)
git push origin --delete v1.0.0
git push origin :refs/tags/v1.0.0

# حذف وسوم متعددة
git tag -d v1.0.0 v1.0.1 v1.0.2

مهم: إذا حذفت وأعدت إنشاء وسم بنفس الاسم، فقد يسبب ذلك ارتباكاً للمطورين الآخرين. تواصل مع فريقك قبل تعديل الوسوم المنشورة.

سير عمل الإصدار العملي

إليك سير عمل نموذجي لإنشاء إصدار مع الوسوم:

# 1. تأكد من أنك على الفرع الرئيسي وأنه محدث
git checkout main
git pull origin main

# 2. تأكد من أن جميع الاختبارات تنجح والكود جاهز
# قم بتشغيل مجموعة الاختبارات الخاصة بك هنا

# 3. حدّث أرقام الإصدار في الكود الخاص بك (package.json، إلخ)
# قم بتحرير الملفات حسب الحاجة

# 4. التزم بتحديث الإصدار
git add .
git commit -m "Bump version to 1.2.0"

# 5. إنشاء وسم مشروح
git tag -a v1.2.0 -m "Release version 1.2.0

New features:
- Added user dashboard
- Improved performance
- Fixed critical bugs"

# 6. دفع الالتزامات والوسم
git push origin main
git push origin v1.2.0

# 7. إنشاء ملاحظات الإصدار على GitHub (اختياري)

عمليات الوسوم المتقدمة

بعض السيناريوهات المتقدمة التي قد تواجهها:

# وسم حالة ملف محددة (غير موصى به، لكنه ممكن)
git tag snapshot-config abc1234 path/to/config.php

# العثور على الوسم الذي يحتوي على التزام
git tag --contains abc1234

# العثور على الوسوم القابلة للوصول من التزام
git describe --tags

# سرد الوسوم مرتبة حسب الإصدار
git tag --sort=v:refname

# سرد الوسوم مرتبة حسب التاريخ
git tag --sort=-creatordate

مقارنة الوسوم

يمكنك مقارنة إصدارات مختلفة من الكود الخاص بك باستخدام الوسوم:

# إظهار الاختلافات بين وسمين
git diff v1.0.0 v1.1.0

# إظهار السجل بين وسمين
git log v1.0.0..v1.1.0

# إظهار الملفات المتغيرة بين الوسوم
git diff --name-only v1.0.0 v1.1.0

# إنشاء سجل التغييرات بين الوسوم
git log v1.0.0..v1.1.0 --oneline --no-merges

تمرين عملي:

إنشاء سير عمل للإصدار:

أنشئ مستودعاً جديداً أو استخدم مستودعاً موجوداً
قم بعمل عدة التزامات لمحاكاة التطوير
أنشئ وسماً مشروحاً v1.0.0 للإصدار الأول
قم بمزيد من الالتزامات بميزات جديدة
أنشئ وسم v1.1.0
اسرد جميع الوسوم واعرض تفاصيلها
قارن الاختلافات بين v1.0.0 و v1.1.0
تدرب على دفع الوسوم إلى مستودع بعيد

الأوامر المستخدمة:

git tag -a v1.0.0 -m "First stable release"
git tag -a v1.1.0 -m "Added new features"
git tag
git show v1.0.0
git diff v1.0.0 v1.1.0
git push origin --tags

أخطاء الوسوم الشائعة

❌ استخدام وسوم خفيفة للإصدارات
git tag v1.0.0
✓ استخدم وسوماً مشروحة بدلاً من ذلك
git tag -a v1.0.0 -m "Release 1.0.0"

❌ نسيان دفع الوسوم
git push origin main
✓ ادفع الوسوم صراحة
git push origin v1.0.0

❌ الوسم بدون اختبار
git tag -a v1.0.0 -m "Release"
✓ اختبر بشكل شامل أولاً
# قم بتشغيل الاختبارات، تحقق من أن كل شيء يعمل
git tag -a v1.0.0 -m "Release"

الملخص

في هذا الدرس، تعلمت:

تحدد الوسوم نقاطاً محددة في تاريخ Git، عادة للإصدارات
الوسوم الخفيفة هي مؤشرات بسيطة؛ الوسوم المشروحة تتضمن بيانات وصفية
استخدم الإصدار الدلالي (MAJOR.MINOR.PATCH) لأرقام الإصدار
يجب دفع الوسوم صراحة إلى المستودعات البعيدة
فحص الوسوم يضعك في حالة HEAD منفصل
يُنصح باستخدام الوسوم المشروحة لجميع الإصدارات العامة
يمكن مقارنة الوسوم لرؤية التغييرات بين الإصدارات

التالي: في الدرس التالي، سنتعلم عن تخزين التغييرات - ميزة قوية لتخزين العمل مؤقتاً دون الالتزام!