je-editor 0.0.222__py3-none-any.whl → 0.0.224__py3-none-any.whl

je_editor/pyside_ui/git_ui/git_client/commit_table.py

@@ -3,25 +3,63 @@ from PySide6.QtWidgets import QTableView
 
 
 class CommitTable(QTableView):
+    """
+    CommitTable 類別：用來顯示 Git Commit 紀錄的表格
+    CommitTable class: A table view to display Git commit history
+    """
+
     def __init__(self, parent=None):
         super().__init__(parent)
-        self.model_data = QStandardItemModel(0, 5, self)  # 多一欄
+
+        # 建立一個 QStandardItemModel，初始為 0 行 5 欄
+        # Create a QStandardItemModel with 0 rows and 5 columns
+        self.model_data = QStandardItemModel(0, 5, self)  # 多一欄 / 5 columns
+
+        # 設定表頭標籤
+        # Set horizontal header labels
         self.model_data.setHorizontalHeaderLabels(["#", "SHA", "Message", "Author", "Date"])
+
+        # 將模型綁定到 QTableView
+        # Set the model for QTableView
         self.setModel(self.model_data)
+
+        # 設定選擇行為為整列選取
+        # Set selection behavior to select entire rows
         self.setSelectionBehavior(QTableView.SelectionBehavior.SelectRows)
+
+        # 禁止編輯表格內容
+        # Disable editing of table cells
         self.setEditTriggers(QTableView.EditTrigger.NoEditTriggers)
+
+        # 讓最後一欄自動延展填滿
+        # Stretch the last column to fill available space
         self.horizontalHeader().setStretchLastSection(True)
 
     def set_commits(self, commits):
+        """
+        將 commit 資料填入表格
+        Populate the table with commit data
+        :param commits: commit 資料清單 (list of dicts with sha, message, author, date)
+        """
+        # 清空現有資料
+        # Clear existing rows
         self.model_data.setRowCount(0)
-        for idx, c in enumerate(commits, start=1):
+
+        # 遍歷 commit 清單，逐行加入表格
+        # Iterate over commits and append rows
+        for index, commit in enumerate(commits, start=1):
             row = [
-                QStandardItem(str(idx)),  # 行號
-                QStandardItem(c["sha"][:7]),
-                QStandardItem(c["message"]),
-                QStandardItem(c["author"]),
-                QStandardItem(c["date"]),
+                QStandardItem(str(index)),          # 行號 / row number
+                QStandardItem(commit["sha"][:7]),      # SHA 短碼 / short SHA
+                QStandardItem(commit["message"]),      # 提交訊息 / commit message
+                QStandardItem(commit["author"]),       # 作者 / author
+                QStandardItem(commit["date"]),         # 日期 / date
             ]
+            # 設定每個欄位不可編輯
+            # Make each item non-editable
             for item in row:
                 item.setEditable(False)
-            self.model_data.appendRow(row)
+
+            # 將這一列加入模型
+            # Append row to the model
+            self.model_data.appendRow(row)

je_editor/pyside_ui/git_ui/git_client/git_branch_tree_widget.py

@@ -19,64 +19,89 @@ log = logging.getLogger(__name__)
 
 
 class GitTreeViewGUI(QWidget):
+    """
+    GitTreeViewGUI: Git 提交歷史圖形化檢視器
+    GitTreeViewGUI: A graphical viewer for Git commit history
+    """
+
     def __init__(self):
         super().__init__()
         self.language_wrapper_get = language_wrapper.language_word_dict.get
         self.setWindowTitle(self.language_wrapper_get("git_graph_title"))
 
+        # === 主版面配置 / Main layout ===
         git_treeview_main_layout = QVBoxLayout(self)
         git_treeview_main_layout.setContentsMargins(0, 0, 0, 0)
         git_treeview_main_layout.setSpacing(0)
 
+        # === 工具列 / Toolbar ===
         git_treeview_toolbar = QToolBar()
+
+        # 開啟 Git 專案動作 / Action to open Git repo
         open_repo_action = QAction(self.language_wrapper_get("git_graph_toolbar_open"), self)
         open_repo_action.triggered.connect(self.open_repo)
         git_treeview_toolbar.addAction(open_repo_action)
 
+        # 刷新圖表動作 / Action to refresh graph
         act_refresh = QAction(self.language_wrapper_get("git_graph_toolbar_refresh"), self)
         act_refresh.triggered.connect(self.refresh_graph)
         git_treeview_toolbar.addAction(act_refresh)
 
         git_treeview_main_layout.addWidget(git_treeview_toolbar)
 
+        # === 分割器 (左：圖形檢視 / 右：提交表格) ===
         splitter = QSplitter(Qt.Orientation.Horizontal)
-        self.graph_view = CommitGraphView()
-        self.commit_table = CommitTable()
+        self.graph_view = CommitGraphView()   # 提交圖形檢視器 / commit graph view
+        self.commit_table = CommitTable()     # 提交表格 / commit table
         splitter.addWidget(self.graph_view)
         splitter.addWidget(self.commit_table)
-        splitter.setSizes([600, 400])
-        git_treeview_main_layout.addWidget(splitter, 1)  # 1 表示可伸縮
+        splitter.setSizes([600, 400])  # 左右比例 / left-right ratio
+        git_treeview_main_layout.addWidget(splitter, 1)  # stretch=1 表示可伸縮
 
+        # === 狀態列 / Status bar ===
         self.status = QStatusBar()
         git_treeview_main_layout.addWidget(self.status)
 
+        # === Git 相關屬性 ===
         self.repo_path = None
         self.git = None
 
+        # === 檔案監控器 / File system watcher ===
         self.watcher = QFileSystemWatcher()
         self.watcher.directoryChanged.connect(self._on_git_changed)
         self.watcher.fileChanged.connect(self._on_git_changed)
 
+        # === 定時器 (延遲刷新) / Timer for delayed refresh ===
         self.refresh_timer = QTimer()
         self.refresh_timer.setSingleShot(True)
         self.refresh_timer.timeout.connect(self.refresh_graph)
 
+        # === 表格選擇事件 / Table selection event ===
         self.commit_table.selectionModel().selectionChanged.connect(self._on_table_selection)
 
     def _on_table_selection(self, selected, _):
+        """
+        當使用者在提交表格中選擇某一列時，讓圖形檢視器聚焦到該行
+        When user selects a row in commit table, focus graph view on that row
+        """
         if not selected.indexes():
             return
         row = selected.indexes()[0].row()
         self.graph_view.focus_row(row)
 
     def open_repo(self):
-        # Open repo and set up the graph.
+        """
+        開啟 Git 專案並初始化圖形檢視
+        Open a Git repository and set up the graph view
+        """
         path = QFileDialog.getExistingDirectory(self, self.language_wrapper_get("git_graph_menu_open_repo"))
         if not path:
             return
         repo_path = Path(path)
         git = GitCLI(repo_path)
         if not git.is_git_repo():
+            # 若不是 Git 專案，顯示警告
+            # Show warning if not a Git repo
             QMessageBox.warning(self, self.language_wrapper_get("git_graph_title"),
                                 self.language_wrapper_get("git_graph_error_not_git"))
             return
@@ -86,11 +111,15 @@ class GitTreeViewGUI(QWidget):
         self.refresh_graph()
 
     def _setup_watcher(self):
+        """
+        設定檔案監控，監控 .git 目錄與相關檔案
+        Setup file watcher to monitor .git directory and related files
+        """
         self.watcher.removePaths(self.watcher.files())
         self.watcher.removePaths(self.watcher.directories())
         if not self.repo_path:
             return
-        git_dir = self.repo_path / ".git_client"
+        git_dir = self.repo_path / ".git_client"  # ⚠️ 這裡應該是 ".git"，可能是自訂路徑
         if git_dir.exists():
             self.watcher.addPath(str(git_dir))
             for f in ["HEAD", "packed-refs"]:
@@ -102,21 +131,26 @@ class GitTreeViewGUI(QWidget):
                 self.watcher.addPath(str(refs_dir))
 
     def _on_git_changed(self):
-        # Refresh git tree timer
+        """
+        當 Git 目錄變更時，啟動延遲刷新
+        When Git directory changes, start delayed refresh
+        """
         self.refresh_timer.start(500)
 
     def refresh_graph(self):
-        # Refresh git tree
+        """
+        刷新 Git 提交圖與提交表格
+        Refresh Git commit graph and commit table
+        """
         if not self.git:
             return
         try:
-            refs = self.git.get_all_refs()
-            commits = self.git.get_commits(max_count=500)
+            refs = self.git.get_all_refs()                  # 取得所有 refs
+            commits = self.git.get_commits(max_count=500)   # 取得最近 500 筆提交
             graph = CommitGraph()
-            graph.build(commits, refs)
-            self.graph_view.set_graph(graph)
-            self.commit_table.set_commits(commits)
+            graph.build(commits, refs)                      # 建立提交圖
+            self.graph_view.set_graph(graph)                # 更新圖形檢視
+            self.commit_table.set_commits(commits)          # 更新提交表格
         except Exception as e:
             QMessageBox.critical(self, self.language_wrapper_get("git_graph_title"),
-                                 f"{self.language_wrapper_get('git_graph_error_exec_failed')}\n{e}")
-
+                                 f"{self.language_wrapper_get('git_graph_error_exec_failed')}\n{e}")

je_editor/pyside_ui/git_ui/git_client/git_client_gui.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from PySide6.QtCore import Qt
+from PySide6.QtCore import Qt, QTimer
 from PySide6.QtGui import QTextOption, QTextCharFormat, QColor, QFont, QSyntaxHighlighter, QAction
 from PySide6.QtWidgets import (
     QWidget, QVBoxLayout, QHBoxLayout, QLabel,
@@ -15,9 +15,9 @@ class GitChangeItem:
     簡單的資料結構，用來存放檔案變更資訊。
     """
 
-    def __init__(self, file_path: str, change_status: str):
-        self.file_path = file_path  # repo 相對路徑 / repo-relative path
-        self.change_status = change_status  # 狀態，例如 'untracked', 'modified', 'deleted', 'renamed', 'staged'
+    def __init__(self, path: str, status: str):
+        self.path = path  # repo 相對路徑 / repo-relative path
+        self.status = status  # 狀態，例如 'untracked', 'modified', 'deleted', 'renamed', 'staged'
 
 
 class GitGui(QWidget):
@@ -36,6 +36,7 @@ class GitGui(QWidget):
         self.checkout_button = QPushButton("Checkout")
         self.clone_repo_button = QPushButton("Clone Repo")
         self.repo_status_label = QLabel("Status: -")
+        self.commit_status_label = QLabel("Unpushed commits: ...")
 
         top = QHBoxLayout()
         top.addWidget(self.repo_path_label, 1)
@@ -48,7 +49,6 @@ class GitGui(QWidget):
         # === Left: changes list / 左側：變更清單 ===
         self.changes_list_widget = QListWidget()
         self.changes_list_widget.setSelectionMode(QListWidget.SelectionMode.SingleSelection)
-        self.changes_list_widget.setMinimumWidth(420)
 
         # === Right: diff / info viewer / 右側：差異或資訊檢視器 ===
         self.diff_viewer = QPlainTextEdit()
@@ -84,6 +84,7 @@ class GitGui(QWidget):
         self.commit_button = QPushButton("Commit")
         self.unstage_all_button = QPushButton("Unstage All")
         self.track_all_untracked_button = QPushButton("Track All Untracked")
+        self.git_push_button = QPushButton("Push")
 
         bottom = QHBoxLayout()
         bottom.addWidget(QLabel("Message:"))
@@ -94,11 +95,13 @@ class GitGui(QWidget):
         bottom.addWidget(self.stage_all_button)
         bottom.addWidget(self.commit_button)
         bottom.addWidget(self.track_all_untracked_button)
+        bottom.addWidget(self.git_push_button)
 
         # === Main layout / 主版面配置 ===
         center_layout = QVBoxLayout()
         center_layout.addLayout(top)
         center_layout.addWidget(self.repo_status_label)
+        center_layout.addWidget(self.commit_status_label)
         center_layout.addWidget(splitter, 1)
         center_layout.addLayout(bottom)
         self.setLayout(center_layout)
@@ -115,6 +118,7 @@ class GitGui(QWidget):
         self.commit_button.clicked.connect(self.on_commit_staged_changes)
         self.unstage_all_button.clicked.connect(self.on_unstage_all_changes)
         self.track_all_untracked_button.clicked.connect(self.on_track_all_untracked_files)
+        self.git_push_button.clicked.connect(self.on_push_to_github)
 
         self._update_ui_controls(enabled=False)
 
@@ -133,6 +137,12 @@ class GitGui(QWidget):
 
         center_layout.setMenuBar(menubar)
 
+        # === Timer ===
+        self.update_commit_status_timer = QTimer()
+        self.update_commit_status_timer.setInterval(1000)
+        self.update_commit_status_timer.timeout.connect(self.update_commit_status)
+        self.update_commit_status_timer.start()
+
     # ---------- Repo operations ----------
     # ---------- 儲存庫操作 ----------
 
@@ -258,16 +268,16 @@ class GitGui(QWidget):
 
         # Normalize paths (for rename "a -> b" 取目的與來源)
         src, dst = None, None
-        if "->" in change.file_path and change.change_status in ("renamed", "staged"):
-            parts = [p.strip() for p in change.file_path.split("->")]
+        if "->" in change.path and change.status in ("renamed", "staged"):
+            parts = [p.strip() for p in change.path.split("->")]
             if len(parts) == 2:
                 src, dst = parts
-        rel = dst or change.file_path
+        rel = dst or change.path
         abs_path = Path(current_repo.working_tree_dir) / Path(rel)
 
         try:
             # Untracked: 顯示新增檔案的內容（模擬 unified diff）
-            if change.change_status == "untracked":
+            if change.status == "untracked":
                 if not abs_path.exists():
                     self._safe_set_diff_text(f"(untracked file missing: {rel})")
                     return
@@ -282,7 +292,7 @@ class GitGui(QWidget):
                 return
 
             # Deleted: 顯示與 HEAD/Index 的差異（若工作樹檔案不存在也能呈現）
-            if change.change_status == "deleted":
+            if change.status == "deleted":
                 # working tree vs index（未暫存刪除）
                 if rel and not current_repo.index.diff(None, paths=[rel]):
                     # 若 diff(None) 空，試試 index vs HEAD
@@ -296,7 +306,7 @@ class GitGui(QWidget):
                 return
 
             # Renamed: 顯示 rename 變更；若僅 rename 無內容改動，diff 可能為空
-            if change.change_status == "renamed":
+            if change.status == "renamed":
                 # 優先顯示 staged rename
                 diff_text = ""
                 try:
@@ -319,7 +329,7 @@ class GitGui(QWidget):
                 return
 
             # Staged vs HEAD
-            if change.change_status == "staged":
+            if change.status == "staged":
                 diff_text = current_repo.git.diff("--cached", rel)
                 if not diff_text.strip():
                     self._safe_set_diff_text("(no staged changes vs HEAD)")
@@ -328,7 +338,7 @@ class GitGui(QWidget):
                 return
 
             # Modified / general unstaged
-            if change.change_status in ("modified",):
+            if change.status in ("modified",):
                 # working tree vs index
                 diff_text = current_repo.git.diff(rel)
                 if not diff_text.strip():
@@ -344,7 +354,7 @@ class GitGui(QWidget):
                 return
 
             # Fallback
-            self._safe_set_diff_text(f"(no diff handler for status: {change.change_status})")
+            self._safe_set_diff_text(f"(no diff handler for status: {change.status})")
 
         except GitCommandError as e:
             self._safe_set_diff_text(f"Git error while generating diff:\n{e}")
@@ -433,7 +443,7 @@ class GitGui(QWidget):
         Add a file change entry to the list.
         將檔案變更項目加入清單。
         """
-        item_text = f"[{change.change_status}] {change.file_path}"
+        item_text = f"[{change.status}] {change.path}"
         list_item = QListWidgetItem(item_text)
         list_item.setData(Qt.ItemDataRole.UserRole, change)  # 存放 GitChangeItem 物件
         list_item.setCheckState(Qt.CheckState.Unchecked)  # 預設未勾選
@@ -513,6 +523,7 @@ class GitGui(QWidget):
         try:
             file_paths = []
             for change_entry in selected_changes:
+                print(change_entry.path)
                 if "->" in change_entry.path and change_entry.status in ("renamed", "staged"):
                     parts = change_entry.path.split("->")
                     source_path = parts[0].strip()
@@ -582,7 +593,7 @@ class GitGui(QWidget):
                 self.branch_selector, self.checkout_button, self.changes_list_widget,
                 self.diff_viewer, self.commit_message_input, self.stage_selected_button,
                 self.unstage_selected_button, self.stage_all_button, self.commit_button,
-                self.unstage_all_button, self.track_all_untracked_button
+                self.unstage_all_button, self.track_all_untracked_button, self.git_push_button
         ):
             widget.setEnabled(enabled)
 
@@ -655,6 +666,60 @@ class GitGui(QWidget):
         except GitCommandError as e:
             QMessageBox.critical(self, "Clone Error", str(e))
 
+    # ===== GitHub =====
+
+    def on_push_to_github(self):
+        if not self.current_repo:
+            QMessageBox.warning(self, "Warning", "No repository opened.")
+            return
+        try:
+            origin = self.current_repo.remote(name="origin")
+            result = origin.push()
+            msg = "\n".join(str(r) for r in result)
+            QMessageBox.information(self, "Push Result", f"Pushed to origin:\n{msg}")
+        except Exception as e:
+            QMessageBox.critical(self, "Track Untracked Error", str(e))
+
+    def get_unpushed_commit_count(self, remote_name: str = "origin") -> dict:
+        try:
+            repo = self.current_repo
+            if repo is None:
+                return {"ahead": 0, "behind": 0, "error": "No repo loaded"}
+            if repo.bare:
+                return {"ahead": 0, "behind": 0, "error": "Repository is bare"}
+            if repo.head.is_detached:
+                return {"ahead": 0, "behind": 0, "error": "HEAD is detached"}
+
+            branch = repo.active_branch
+            remote = repo.remote(remote_name)
+            remote.fetch()
+
+            upstream_ref = f"{remote_name}/{branch.name}"
+            if upstream_ref not in repo.refs:
+                return {"ahead": 0, "behind": 0, "error": f"No upstream branch for {branch.name}"}
+
+            ahead_commits = list(repo.iter_commits(f"{upstream_ref}..{branch.name}"))
+            behind_commits = list(repo.iter_commits(f"{branch.name}..{upstream_ref}"))
+
+            return {"ahead": len(ahead_commits), "behind": len(behind_commits), "error": None}
+
+        except GitCommandError as e:
+            return {"ahead": 0, "behind": 0, "error": f"Git error: {e}"}
+        except Exception as e:
+            return {"ahead": 0, "behind": 0, "error": str(e)}
+
+    def update_commit_status(self):
+        result = self.get_unpushed_commit_count()
+        if result["error"]:
+            self.commit_status_label.setText(f"Error: {result['error']}")
+        else:
+            self.commit_status_label.setText(
+                f"Ahead (push): {result['ahead']} | Behind (pull): {result['behind']}"
+            )
+
+
+    # ===== Theme =====
+
     def apply_light_theme(self):
         """
         Switch to light theme highlighting.

je_editor/pyside_ui/git_ui/git_client/graph_view.py

@@ -14,18 +14,18 @@ from PySide6.QtWidgets import (
 from je_editor.git_client.commit_graph import CommitGraph
 from je_editor.utils.multi_language.multi_language_wrapper import language_wrapper
 
-# Layout constants
-NODE_RADIUS = 6
-ROW_HEIGHT = 28
-LANE_WIDTH = 22
-LEFT_MARGIN = 220  # space for SHA/message text area on the left
-
-# Colors
-EDGE_COLOR = QColor("#888")
-TEXT_COLOR = QColor("#222")
-BG_COLOR = QColor("#ffffff")
-
-# A small, repeatable lane palette
+# === 版面配置常數 / Layout constants ===
+NODE_RADIUS = 6       # 節點半徑 / node radius
+ROW_HEIGHT = 28       # 每一列高度 / row height
+LANE_WIDTH = 22       # 每一條 lane 的寬度 / lane width
+LEFT_MARGIN = 220     # 左側 SHA/訊息文字區域保留空間 / left margin for SHA/message text
+
+# === 顏色設定 / Colors ===
+EDGE_COLOR = QColor("#888")     # 邊線顏色 / edge color
+TEXT_COLOR = QColor("#222")     # 文字顏色 / text color
+BG_COLOR = QColor("#ffffff")    # 背景顏色 / background color
+
+# Lane 顏色調色盤 / Lane color palette
 LANE_COLORS = [
     QColor("#4C78A8"),
     QColor("#F58518"),
@@ -41,24 +41,38 @@ LANE_COLORS = [
 
 
 def lane_color(lane: int) -> QColor:
+    """
+    根據 lane index 回傳顏色
+    Return color based on lane index
+    """
     if lane < 0:
         return QColor("#999")
     return LANE_COLORS[lane % len(LANE_COLORS)]
 
 
 class CommitGraphView(QGraphicsView):
+    """
+    Git Commit Graph 視覺化檢視器
+    Git commit graph visualization view
+    """
+
     def __init__(self, parent=None):
         super().__init__(parent)
         self.language_wrapper_get = language_wrapper.language_word_dict.get
+
+        # 設定背景與抗鋸齒 / set background and antialiasing
         self.setBackgroundBrush(QBrush(BG_COLOR))
         self.setRenderHints(
             self.renderHints()
             | QPainter.RenderHint.Antialiasing
             | QPainter.RenderHint.TextAntialiasing
         )
+
+        # 啟用拖曳與縮放模式 / enable drag and zoom mode
         self.setDragMode(QGraphicsView.DragMode.ScrollHandDrag)
         self.setTransformationAnchor(QGraphicsView.ViewportAnchor.AnchorUnderMouse)
 
+        # 建立場景 / create scene
         self._scene = QGraphicsScene(self)
         self.setScene(self._scene)
 
@@ -67,21 +81,32 @@ class CommitGraphView(QGraphicsView):
         self._zoom = 1.0
 
     def set_graph(self, graph: CommitGraph):
+        """
+        設定 commit graph 並重新繪製
+        Set commit graph and redraw
+        """
         self.graph = graph
         self._redraw()
 
     def _lane_x(self, lane: int) -> float:
+        # 計算 lane 的 X 座標 / calculate X position for lane
         return lane * LANE_WIDTH + NODE_RADIUS * 2
 
     def _row_y(self, row: int) -> float:
+        # 計算 row 的 Y 座標 / calculate Y position for row
         return row * ROW_HEIGHT + NODE_RADIUS * 2
 
     def _redraw(self):
+        """
+        重新繪製整個 commit graph
+        Redraw the entire commit graph
+        """
         self._scene.clear()
         if not self.graph or not self.graph.nodes:
             self._scene.setSceneRect(QRectF(0, 0, 800, 400))
             return
 
+        # === 繪製邊線 (父子關係) / Draw edges (parent-child relationships) ===
         edge_pen = QPen(EDGE_COLOR, 2)
         for row, node in enumerate(self.graph.nodes):
             if not node.parent_shas:
@@ -95,6 +120,8 @@ class CommitGraphView(QGraphicsView):
                 parent_node = self.graph.nodes[prow]
                 x1 = self._lane_x(parent_node.lane_index)
                 y1 = self._row_y(prow)
+
+                # 使用三次貝茲曲線繪製邊線 / cubic Bezier curve for edge
                 path = QPainterPath(QPointF(x0, y0))
                 ctrl_y = (y0 + y1) / 2.0
                 path.cubicTo(QPointF(x0, ctrl_y), QPointF(x1, ctrl_y), QPointF(x1, y1))
@@ -102,6 +129,7 @@ class CommitGraphView(QGraphicsView):
                 edge_item.setPen(edge_pen)
                 self._scene.addItem(edge_item)
 
+        # === 繪製節點 (commit 圓點) / Draw nodes (commit circles) ===
         for row, node in enumerate(self.graph.nodes):
             cx = self._lane_x(node.lane_index)
             cy = self._row_y(row)
@@ -111,6 +139,7 @@ class CommitGraphView(QGraphicsView):
             )
             circle.setBrush(QBrush(lane_color(node.lane_index)))
             circle.setPen(QPen(Qt.PenStyle.NoPen))
+            # 設定 tooltip 顯示 commit 資訊 / tooltip with commit info
             circle.setToolTip(self.language_wrapper_get(
                 "git_graph_tooltip_commit"
             ).format(short=node.commit_sha[:7],
@@ -119,11 +148,13 @@ class CommitGraphView(QGraphicsView):
                      msg=node.commit_message))
             self._scene.addItem(circle)
 
+            # 在左側顯示行號 / show row number on the left
             label_item = QGraphicsSimpleTextItem(str(row + 1))
             label_item.setBrush(QBrush(TEXT_COLOR))
             label_item.setPos(-30, cy - NODE_RADIUS * 2)
             self._scene.addItem(label_item)
 
+        # 設定場景大小 / set scene rect
         self._scene.setSceneRect(
             QRectF(-40, 0,
                    self._lane_x(max(n.lane_index for n in self.graph.nodes) + 1) + self._padding,
@@ -131,15 +162,19 @@ class CommitGraphView(QGraphicsView):
         )
 
     def _apply_initial_view(self):
-        # Start with a mild zoom to fit rows comfortably
+        """
+        初始縮放設定
+        Apply initial zoom setting
+        """
         self._zoom = 0.9
         self._apply_zoom_transform()
 
-    # Zoom and interaction
+    # === 滑鼠滾輪縮放 / Mouse wheel zoom ===
     def wheelEvent(self, event):
         if not self._scene.items():
             return
 
+        # Ctrl+滾輪縮放，否則正常滾動
         # Ctrl+Wheel to zoom, else scroll normally
         if event.modifiers() & Qt.KeyboardModifier.ControlModifier:
             angle = event.angleDelta().y()
@@ -151,24 +186,33 @@ class CommitGraphView(QGraphicsView):
             super().wheelEvent(event)
 
     def _apply_zoom_transform(self):
+        """
+        套用縮放轉換
+        Apply zoom transform
+        """
         t = QTransform()
         t.scale(self._zoom, self._zoom)
         self.setTransform(t)
 
     def resizeEvent(self, event):
+        """
+        視窗大小改變時的事件
+        Handle resize event (keep scene rect, no auto-fit)
+        """
         super().resizeEvent(event)
-        # Keep scene rect; do not auto-fit. Users control zoom.
-        # Nothing else needed here.
+        # 保持場景大小，不自動縮放
+        # Keep scene rect; do not auto-fit
 
-    # Optional helpers for external controllers
+    # === 外部控制輔助方法 / Helper for external controllers ===
     def focus_row(self, row: int):
         """
-        Center the view around a specific row.
+        將檢視器聚焦到指定的 row
+        Center the view around a specific row
         """
         if not self.graph or row < 0 or row >= len(self.graph.nodes):
             return
         y = self._row_y(row)
         rect = QRectF(0, y - ROW_HEIGHT * 2, self._scene.width(), ROW_HEIGHT * 4)
         self.fitInView(rect, Qt.AspectRatioMode.KeepAspectRatio)
-        # Restore user zoom preference after focusing
-        self._apply_zoom_transform()
+        # 聚焦後恢復使用者縮放比例 / restore user zoom after focusing
+        self._apply_zoom_transform()