---
title: 版本控制整合
description: 與 Git 及其他版本控制系統協作
---

Verdent for VS Code 能與 Git 及其他版本控制系統無縫整合，讓你以自然語言進行版本控制操作、自動產生提交訊息，以及智慧的分支管理。本指南將說明如何運用 Verdent 的 Git 整合，建立高效的版本控制工作流程。

---

## 建立有意義的提交訊息

假設你已做出變更，並希望 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 遵循 conventional commit 格式（feat、fix、refactor、docs 等）
  - 提交訊息聚焦於「做了什麼」和「為什麼」，而非「如何做」
  - 你可以在 User Rules 或 Project Rules 中自訂提交訊息格式
  - 要求特定的提交訊息風格：「建立一個包含詳細多行訊息的提交」
</Tip>

***

## 自訂提交訊息格式

假設你希望 Verdent 遵循你團隊特定的提交訊息慣例。

<Tabs>
  <Tab title="User Rules（全域）">
    在 `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="Project Rules">
    在 `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>
  **提示：**
  - User Rules 全域套用於所有專案
  - Project Rules（AGENTS.md）會覆寫特定專案的 User Rules
  - 行內指示會覆寫上述兩者，適用於一次性需求
  - 建議使用 Conventional Commits 格式以維持一致性
</Tip>

***

## 建立 Pull Request

假設你希望 Verdent 建立一個完整的 pull request。

<Steps>
  <Step title="確認變更已提交">
    ```
    Make sure all my changes are committed
    ```

    Verdent 會檢查 git status 並提交任何未提交的變更。
  </Step>

  <Step title="將分支推送到遠端">
    ```
    Push this branch to origin
    ```

    Verdent 會推送：
    ```bash
    git push origin feature/user-notifications
    ```
  </Step>

  <Step title="要求建立 PR">
    ```
    Create a pull request for this feature
    ```

    Verdent 會使用 `gh` CLI 建立 PR。
  </Step>

  <Step title="Verdent 產生 PR 描述">
    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
    ```

    該 PR 會以完整的描述建立。
  </Step>
</Steps>

<Tip>
  **提示：**
  - Verdent 會分析分支中所有提交來產生 PR 描述
  - 要求特定的 PR 格式：「建立一個包含詳細測試計畫的 PR」
  - 加入截圖：「將這張截圖加入 PR 描述」
  - 你可以在建立前優化 PR 描述：「更新 PR 以提及破壞性變更」
</Tip>

***

## 解決合併衝突

假設你遇到合併衝突，需要 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）
    - 進入的變更（main 分支）
    - 衝突周圍的上下文
    - 兩項變更的意圖
  </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>

***

## 管理分支與標籤

假設你需要管理分支並建立發行標籤。

<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 會在合併前確保 main 為最新狀態。
  </Tab>

  <Tab title="標記發行版本">
    **建立帶註解的標籤：**

    ```
    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`
  - 合併前務必拉取最新變更
  - 為發行版本使用帶註解的標籤（包含中繼資料）
  - 遵循語意化版本：v1.2.3（major.minor.patch）
</Tip>

<Tip>
一致的分支命名慣例有助於 Verdent 理解你的工作流程。可在 AGENTS.md 中定義模式以自動遵循。
</Tip>

***

## 常見問題

<Accordion title="Verdent 會自動提交我的變更嗎？">
不會。Verdent 只在你明確要求時才會建立提交。你對於變更何時提交保有完全控制。當你準備好時，只要說「暫存所有變更並建立提交」即可。
</Accordion>

<Accordion title="我可以在提交前編輯提交訊息嗎？">
可以。你可以請 Verdent 在建立提交前修改提交訊息。可說「更新提交訊息以提及破壞性變更」或「讓提交訊息更簡潔」。Verdent 會根據你的回饋重新產生訊息。
</Accordion>

<Accordion title="Verdent 能與 GitHub、GitLab、Bitbucket 及其他 Git 平台搭配使用嗎？">
可以。Verdent 使用標準 Git 指令，因此無論託管平台為何皆可搭配任何 Git 儲存庫使用。在建立 pull request 方面，Verdent 使用需要 GitHub 的 `gh` CLI，但所有其他 Git 操作皆可通用。
</Accordion>

<Accordion title="Verdent 會未經詢問就推送到遠端儲存庫嗎？">
不會。Verdent 只在你明確要求時才會推送到遠端儲存庫。所有 Git 操作（commit、push、merge、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>