# تكامل التحكم بالإصدارات (/ar/docs/verdent-for-vscode/common-workflows/version-control)

> العمل مع Git وأنظمة التحكم بالإصدارات الأخرى



يتكامل Verdent for VS Code بسلاسة مع Git وأنظمة التحكم بالإصدارات الأخرى، ما يتيح عمليات التحكم بالإصدارات باللغة الطبيعية، وتوليد رسائل الالتزام (commit) تلقائيًا، وإدارة الفروع بذكاء. يوضح هذا الدليل كيفية الاستفادة من تكامل Git في Verdent لتحقيق سير عمل فعّال في التحكم بالإصدارات.

***

## إنشاء رسائل التزام (commit) ذات معنى [#إنشاء-رسائل-التزام-commit-ذات-معنى]

لنفترض أنك أجريت تغييرات وتريد من Verdent توليد رسالة التزام وصفية.

<Steps>
  <Step title="طلب الالتزام مع توليد الرسالة">
    ```
    Stage all changes and create a commit with an appropriate message
    ```

    يحلل Verdent تغييراتك باستخدام git diff.
  </Step>

  <Step title="يحلل Verdent التغييرات">
    يفحص Verdent:

    * الملفات المعدَّلة والغرض منها
    * طبيعة التغييرات (ميزة جديدة، إصلاح خلل، إعادة هيكلة)
    * نطاق التأثير
    * الوظائف ذات الصلة
  </Step>

  <Step title="توليد رسالة التزام وصفية">
    ```bash
    git commit -m "feat: add user profile image upload with S3 integration

    - Add file upload endpoint to user API
    - Integrate AWS S3 for image storage
    - Update user model with profileImage field
    - Add frontend image upload component with preview"
    ```

    تتبع الرسالة تنسيق الالتزام التقليدي (conventional commit) وتصف ما تغيّر.
  </Step>

  <Step title="يتم إنشاء الالتزام">
    يتم الالتزام بالتغييرات باستخدام الرسالة المولَّدة. يمكنك مراجعة الالتزام:

    ```bash
    git log -1
    ```
  </Step>
</Steps>

<Tip>
  **نصائح:**

  * يتّبع Verdent تنسيقات الالتزام التقليدية (feat وfix وrefactor وdocs وغيرها)
  * تركّز رسائل الالتزام على "ماذا" و"لماذا"، وليس "كيف"
  * يمكنك تخصيص تنسيق رسالة الالتزام في القواعد الخاصة بالمستخدم أو قواعد المشروع
  * اطلب أنماطًا محددة لرسالة الالتزام: "أنشئ التزامًا برسالة مفصّلة متعددة الأسطر"
</Tip>

***

## تخصيص تنسيقات رسائل الالتزام [#تخصيص-تنسيقات-رسائل-الالتزام]

لنفترض أنك تريد من Verdent اتّباع اصطلاحات رسائل الالتزام الخاصة بفريقك.

<Tabs>
  <Tab title="قواعد المستخدم (عامة)">
    حدِّد تفضيلات رسالة الالتزام في `VERDENT.md` لجميع المشاريع:

    ```markdown
    # VERDENT.md

    ## Git Commit Messages

    When generating commit messages:
    - Always include ticket number in format: [PROJ-123]
    - Use present tense verbs
    - Maximum 50 characters for first line
    - Include detailed explanation in body
    - Add "Co-authored-by" for pair programming sessions

    Example format:
    [PROJ-123] Add user authentication feature

    Detailed explanation of changes...

    Co-authored-by: Team Member <email@example.com>
    ```

    يتّبع Verdent هذه القواعد عالميًا.
  </Tab>

  <Tab title="قواعد المشروع">
    حدِّد اصطلاحات الالتزام الخاصة بالمشروع في `AGENTS.md`:

    ```markdown
    # AGENTS.md

    ## Git Commit Conventions

    For this project, use conventional commits with these scopes:
    - feat(api): API changes
    - feat(ui): Frontend changes
    - fix(auth): Authentication fixes
    - docs(readme): Documentation updates

    Always reference GitHub issue: "Fixes #123" or "Relates to #456"
    ```

    تنطبق القواعد على هذا المشروع فقط.
  </Tab>

  <Tab title="التعليمات المضمَّنة">
    قدِّم تعليمات لمرة واحدة مباشرةً:

    ```
    Create a commit with message format: "[TICKET-NUMBER] description" including reference to issue #42
    ```

    يولّد Verdent:

    ```bash
    git commit -m "[PROJ-42] Add search functionality

    Relates to #42"
    ```
  </Tab>
</Tabs>

<Tip>
  **نصائح:**

  * تنطبق قواعد المستخدم عالميًا على جميع المشاريع
  * تتجاوز قواعد المشروع (AGENTS.md) قواعد المستخدم في مشاريع محددة
  * تتجاوز التعليمات المضمَّنة كلتيهما لتلبية الاحتياجات لمرة واحدة
  * يُوصى باستخدام تنسيق Conventional Commits للحفاظ على الاتساق
</Tip>

***

## إنشاء طلبات السحب (Pull Requests) [#إنشاء-طلبات-السحب-pull-requests]

لنفترض أنك تريد من Verdent إنشاء طلب سحب شامل.

<Steps>
  <Step title="تأكد من الالتزام بالتغييرات">
    ```
    Make sure all my changes are committed
    ```

    يتحقق Verdent من حالة git ويلتزم بأي تغييرات غير ملتزَم بها.
  </Step>

  <Step title="ادفع الفرع إلى المستودع البعيد">
    ```
    Push this branch to origin
    ```

    يدفع Verdent:

    ```bash
    git push origin feature/user-notifications
    ```
  </Step>

  <Step title="طلب إنشاء طلب السحب">
    ```
    Create a pull request for this feature
    ```

    يستخدم Verdent واجهة سطر الأوامر `gh` لإنشاء طلب السحب.
  </Step>

  <Step title="يولّد Verdent وصف طلب السحب">
    يحلل Verdent الالتزامات والتغييرات لتوليد ما يلي:

    **العنوان:** Add user notification system

    **النص:**

    ```markdown
    ## Summary
    - Implements real-time user notifications
    - Adds WebSocket support for instant delivery
    - Includes email fallback for offline users
    - Comprehensive test coverage

    ## Test Plan
    - [ ] Test real-time notifications in browser
    - [ ] Verify email fallback for offline users
    - [ ] Check notification persistence across sessions
    - [ ] Test with multiple concurrent users

    ## Changes
    - Added NotificationService with WebSocket integration
    - Created notification UI components
    - Integrated SendGrid for email notifications
    - Added notification preferences to user settings
    ```

    يتم إنشاء طلب السحب بوصف شامل.
  </Step>
</Steps>

<Tip>
  **نصائح:**

  * يحلل Verdent جميع الالتزامات في الفرع لتوليد وصف طلب السحب
  * اطلب تنسيقات محددة لطلب السحب: "أنشئ طلب سحب مع خطة اختبار مفصّلة"
  * أضف لقطات الشاشة: "أضف لقطة الشاشة هذه إلى وصف طلب السحب"
  * يمكنك تنقيح وصف طلب السحب قبل الإنشاء: "حدِّث طلب السحب ليذكر التغيير الجذري (breaking change)"
</Tip>

***

## حل تعارضات الدمج (Merge Conflicts) [#حل-تعارضات-الدمج-merge-conflicts]

لنفترض أنك واجهت تعارضات دمج وتحتاج إلى مساعدة Verdent لحلها.

<Steps>
  <Step title="محاولة الدمج">
    ```
    Merge main into this feature branch
    ```

    يحدث تعارض دمج:

    ```bash
    Auto-merging src/auth.ts
    CONFLICT (content): Merge conflict in src/auth.ts
    ```
  </Step>

  <Step title="طلب حل التعارض">
    ```
    Help me resolve the merge conflict in src/auth.ts
    ```

    يقرأ Verdent علامات التعارض.
  </Step>

  <Step title="يحلل Verdent كلا الإصدارين">
    يفحص Verdent:

    * تغييرات الفرع الحالي (HEAD)
    * التغييرات الواردة (الفرع الرئيسي)
    * السياق المحيط بالتعارضات
    * غرض كلا التغييرين
  </Step>

  <Step title="يقترح Verdent حلًا">
    ```
    The conflict is between your JWT implementation and the main branch's session-based auth. I'll merge both approaches to support both authentication methods.
    ```

    يحل Verdent التعارض عبر دمج التغييرين بذكاء.
  </Step>

  <Step title="تحديد التعارض كمحلول">
    ```bash
    git add src/auth.ts
    git commit -m "Merge main into feature/jwt-auth, resolved conflicts"
    ```

    يتم حل التعارض واكتمال الدمج.
  </Step>
</Steps>

<Tip>
  **نصائح:**

  * يفهم Verdent سياق الكود لحل التعارضات بذكاء
  * راجع دائمًا حلول التعارضات قبل الالتزام
  * بالنسبة للتعارضات المعقدة، اطلب من Verdent شرح كلا الإصدارين أولًا
  * اختبر بدقة بعد حل التعارضات
</Tip>

<Tip>
  يحلل Verdent تعارضات الدمج عبر فهم غرض كلا الفرعين، ويقترح حلولًا تحافظ على وظائف الطرفين.
</Tip>

***

## إدارة الفروع والوسوم (Tags) [#إدارة-الفروع-والوسوم-tags]

لنفترض أنك بحاجة إلى إدارة الفروع وإنشاء وسوم الإصدارات.

<Tabs>
  <Tab title="عمليات الفروع">
    **إنشاء الفروع والتبديل بينها:**

    ```
    Create a new branch called feature/user-notifications
    ```

    ينفّذ Verdent:

    <CodeGroup>
      ```bash "Create New Branch"
      git checkout -b feature/user-notifications
      ```

      ```bash "Switch to Existing Branch"
      git checkout main
      ```

      ```bash "Create and Push Branch"
      git checkout -b feature/payment-integration
      git push -u origin feature/payment-integration
      ```
    </CodeGroup>
  </Tab>

  <Tab title="الدمج">
    **دمج فروع الميزات:**

    ```
    Merge the feature/user-notifications branch into main
    ```

    ينفّذ Verdent سير عمل الدمج:

    ```bash
    git checkout main
    git pull origin main
    git merge feature/user-notifications
    git push origin main
    ```

    يتأكد Verdent من أن الفرع الرئيسي محدَّث قبل الدمج.
  </Tab>

  <Tab title="وسم الإصدارات">
    **إنشاء وسوم موصوفة (annotated tags):**

    ```
    Create an annotated tag for version 1.2.0 with release notes
    ```

    ينشئ Verdent وسمًا مفصّلًا:

    ```bash
    git tag -a v1.2.0 -m "Release 1.2.0

    New Features:
    - User notification system
    - Email integration
    - Real-time WebSocket support

    Bug Fixes:
    - Fixed authentication timeout issue
    - Resolved cart calculation bug"
    ```

    **دفع الوسوم:**

    ```
    Push all tags to origin
    ```

    يدفع Verdent:

    ```bash
    git push origin --tags
    ```
  </Tab>
</Tabs>

<Tip>
  **نصائح:**

  * استخدم أسماء فروع وصفية: `feature/user-auth`، `fix/cart-bug`، `refactor/api-layer`
  * اسحب دائمًا أحدث التغييرات قبل الدمج
  * استخدم الوسوم الموصوفة (annotated tags) للإصدارات (فهي تتضمن بيانات وصفية)
  * اتّبع الترقيم الدلالي (semantic versioning): v1.2.3 (رئيسي.فرعي.تصحيح)
</Tip>

<Tip>
  تساعد اصطلاحات تسمية الفروع المتسقة Verdent على فهم سير عملك. حدِّد الأنماط في AGENTS.md للامتثال التلقائي.
</Tip>

***

## الأسئلة الشائعة [#الأسئلة-الشائعة]

<Accordion title="هل يلتزم Verdent بتغييراتي تلقائيًا؟">
  لا. لا ينشئ Verdent التزامات إلا عند طلبك ذلك صراحةً. تحتفظ بالتحكم الكامل في توقيت الالتزام بالتغييرات. يكفي أن تطلب "جهّز جميع التغييرات وأنشئ التزامًا (commit)" عندما تكون جاهزًا.
</Accordion>

<Accordion title="هل يمكنني تعديل رسالة الالتزام قبل الالتزام؟">
  نعم. يمكنك أن تطلب من Verdent تنقيح رسالة الالتزام قبل إنشائها. قل "حدِّث رسالة الالتزام لذكر التغيير الجذري (breaking change)" أو "اجعل رسالة الالتزام هذه أكثر إيجازًا." سيعيد Verdent توليد الرسالة بناءً على ملاحظاتك.
</Accordion>

<Accordion title="هل يعمل Verdent مع GitHub وGitLab وBitbucket ومنصات Git الأخرى؟">
  نعم. يستخدم Verdent أوامر Git القياسية، لذا فهو يعمل مع أي مستودع Git بغض النظر عن منصة الاستضافة. لإنشاء طلبات السحب، يستخدم Verdent واجهة سطر الأوامر `gh` التي تتطلب GitHub، لكن جميع عمليات Git الأخرى تعمل بشكل عام.
</Accordion>

<Accordion title="هل يدفع Verdent إلى المستودعات البعيدة دون طلب؟">
  لا. لا يدفع Verdent إلى المستودعات البعيدة إلا عند طلبك ذلك صراحةً. تتطلب جميع عمليات Git (الالتزام، الدفع، الدمج، إعادة الأساس (rebase)) تعليمات صريحة منك لضمان السلامة.
</Accordion>

<Accordion title="هل يمكن لـ Verdent حل جميع أنواع تعارضات الدمج؟">
  يمكن لـ Verdent حل معظم تعارضات الدمج النصية عبر فهم سياق الكود وغرضه. قد تتطلب تعارضات الملفات الثنائية أو التعارضات المعقدة متعددة الأطراف تدخلًا يدويًا. راجع دائمًا حل التعارض الذي يقترحه Verdent قبل الالتزام.
</Accordion>

***

## اطّلع أيضًا على [#اطّلع-أيضًا-على]

<CardGroup cols="2">
  <Card title="أمثلة على المهام متعددة الخطوات" icon="list-check" href="/docs/verdent-for-vscode/common-workflows/multi-step-tasks">
    سير عمل معقد متعدد الخطوات وإدارة المهام
  </Card>

  <Card title="كتابة كود جديد" icon="code" href="/docs/verdent-for-vscode/task-based-guides/writing-code">
    إنشاء ميزات ومكونات جديدة باستخدام Verdent
  </Card>
</CardGroup>