Worktree
Worktree
Sử dụng Git worktree trong Codex trên ứng dụng ChatGPT dành cho máy tính để chạy song song nhiều cuộc trò chuyện
Worktree cho phép Codex chạy nhiều cuộc trò chuyện độc lập trong cùng một dự án mà không ảnh hưởng lẫn nhau. Repository, worktree và các lệnh vẫn nằm trên máy tính hoặc môi trường phát triển từ xa chứa dự án. Bạn có thể làm việc trực tiếp trong ứng dụng ChatGPT dành cho máy tính hoặc dùng Remote trong ứng dụng ChatGPT dành cho thiết bị di động để bắt đầu, hướng dẫn, phê duyệt và xem xét các cuộc trò chuyện trong worktree trên máy tính đã kết nối.
Đối với repository Git, tác vụ đã lên lịch có thể chạy trên các worktree nền chuyên biệt để không xung đột với công việc đang thực hiện của bạn. Trong các dự án không được quản lý phiên bản, tác vụ đã lên lịch chạy trực tiếp trong thư mục dự án. Bạn cũng có thể bắt đầu cuộc trò chuyện trong một worktree theo cách thủ công và dùng Handoff để di chuyển cuộc trò chuyện giữa Local và Worktree.
Worktree là gì
Worktree chỉ hoạt động trong các dự án thuộc một kho lưu trữ Git vì bên dưới chúng sử dụng Git worktree. Worktree cho phép bạn tạo một bản sao thứ hai ("checkout") của kho lưu trữ. Mỗi worktree có bản sao riêng của mọi tệp trong kho lưu trữ, nhưng tất cả đều dùng chung siêu dữ liệu (thư mục .git) về commit, nhánh, v.v. Nhờ đó, bạn có thể checkout và làm việc song song trên nhiều nhánh.
Thuật ngữ
- Checkout cục bộ: Kho lưu trữ mà bạn đã tạo. Đôi khi chỉ được gọi là Local trong ứng dụng ChatGPT dành cho máy tính.
- Worktree: Một Git worktree được tạo từ checkout cục bộ của bạn trong ứng dụng ChatGPT dành cho máy tính.
- Handoff: Quy trình chuyển cuộc trò chuyện giữa Local và Worktree. Codex xử lý các thao tác Git cần thiết để di chuyển công việc của bạn giữa hai môi trường một cách an toàn.
Vì sao nên sử dụng worktree
- Làm việc song song với Codex mà không làm xáo trộn thiết lập Local hiện tại.
- Xếp hàng công việc chạy nền trong khi bạn vẫn tập trung vào công việc ở tiền cảnh.
- Chuyển cuộc trò chuyện sang Local sau này khi bạn sẵn sàng kiểm tra, thử nghiệm hoặc cộng tác trực tiếp hơn.
Bắt đầu
Worktree yêu cầu kho lưu trữ Git. Hãy đảm bảo dự án bạn chọn nằm trong một kho lưu trữ Git.
Chọn "Worktree"
Trong chế độ xem cuộc trò chuyện mới, chọn Worktree bên dưới trình soạn thảo. Bạn cũng có thể chọn một môi trường cục bộ để chạy các tập lệnh thiết lập cho worktree.
Chọn nhánh khởi đầu
Bên dưới trình soạn thảo, chọn nhánh Git dùng làm cơ sở cho worktree. Đó có thể là nhánh
main/master, một nhánh tính năng hoặc nhánh hiện tại có các thay đổi cục bộ chưa được stage.Gửi lời nhắc
Gửi lời nhắc và Codex sẽ tạo một Git worktree dựa trên nhánh bạn đã chọn. Theo mặc định, Codex làm việc ở trạng thái "detached HEAD".
Chọn nơi tiếp tục làm việc
Khi sẵn sàng, bạn có thể tiếp tục làm việc trực tiếp trên worktree hoặc bàn giao cuộc trò chuyện cho checkout cục bộ. Việc bàn giao đến hoặc từ Local sẽ di chuyển cả cuộc trò chuyện lẫn mã để bạn có thể tiếp tục trong checkout còn lại.
Làm việc giữa Local và Worktree
Worktree có giao diện và cách sử dụng gần giống checkout cục bộ. Điểm khác biệt là vị trí của chúng trong quy trình làm việc. Bạn có thể coi Local là tiền cảnh và Worktree là nền. Handoff cho phép bạn chuyển cuộc trò chuyện giữa hai môi trường.
Bên dưới, Handoff xử lý các thao tác Git cần thiết để di chuyển công việc an toàn giữa hai checkout. Điều này quan trọng vì Git chỉ cho phép một nhánh được checkout tại một nơi ở cùng một thời điểm. Nếu checkout một nhánh trong worktree, bạn không thể đồng thời checkout nhánh đó trong checkout cục bộ và ngược lại.
Trong thực tế, có hai quy trình phổ biến:
- Chỉ làm việc trên worktree. Quy trình này phù hợp nhất khi bạn có thể xác minh các thay đổi trực tiếp trên worktree, chẳng hạn vì đã cài đặt các phần phụ thuộc và công cụ bằng tập lệnh thiết lập môi trường cục bộ.
- Bàn giao cuộc trò chuyện cho Local. Sử dụng quy trình này khi bạn muốn đưa cuộc trò chuyện ra tiền cảnh, chẳng hạn vì muốn kiểm tra các thay đổi trong IDE quen thuộc hoặc chỉ có thể chạy một phiên bản ứng dụng.
Lựa chọn 1: Làm việc trên worktree
Nếu muốn tiếp tục chỉ làm việc trên worktree cùng các thay đổi của mình, hãy chuyển worktree thành một nhánh bằng nút Tạo nhánh tại đây trong tiêu đề cuộc trò chuyện.
Từ đây, bạn có thể commit các thay đổi, đẩy nhánh lên kho lưu trữ từ xa và mở pull request trên GitHub.
Bạn có thể mở IDE tại worktree bằng nút "Open" trong phần đầu trang, sử dụng terminal tích hợp hoặc dùng bất kỳ công cụ nào khác cần thiết từ thư mục worktree.
Lựa chọn 2: Bàn giao cuộc trò chuyện cho Local
Nếu muốn đưa cuộc trò chuyện ra tiền cảnh, hãy chọn Bàn giao trong tiêu đề cuộc trò chuyện và chuyển cuộc trò chuyện sang Local.
Quy trình này phù hợp khi bạn muốn đọc các thay đổi trong cửa sổ IDE quen thuộc, chạy máy chủ phát triển hiện có hoặc xác thực công việc trong chính môi trường bạn sử dụng hằng ngày.
Codex xử lý các bước Git cần thiết để di chuyển cuộc trò chuyện an toàn giữa worktree và checkout cục bộ.
Mỗi cuộc trò chuyện luôn liên kết với cùng một worktree theo thời gian. Nếu sau đó bạn chuyển cuộc trò chuyện trở lại một worktree, Codex sẽ đưa cuộc trò chuyện về đúng môi trường nền đó để bạn có thể tiếp tục từ chỗ đã dừng.
Vì Handoff sử dụng các thao tác Git, mọi tệp thuộc tệp .gitignore sẽ không được di chuyển cùng cuộc trò chuyện, trừ khi Codex sao chép chúng vào một worktree cục bộ được quản lý bằng .worktreeinclude.
Chi tiết nâng cao
Worktree do Codex quản lý và worktree cố định
Theo mặc định, các cuộc trò chuyện sử dụng worktree do Codex quản lý. Các worktree này được thiết kế để gọn nhẹ và có thể loại bỏ. Một worktree do Codex quản lý thường dành riêng cho một cuộc trò chuyện và Codex sẽ đưa cuộc trò chuyện đó trở lại cùng worktree nếu sau này bạn bàn giao nó về đó.
Nếu muốn có một môi trường tồn tại lâu dài, hãy tạo một worktree cố định từ menu ba chấm của một dự án trong thanh bên. Thao tác này tạo một worktree cố định mới dưới dạng một dự án riêng. Worktree cố định không tự động bị xóa và bạn có thể bắt đầu nhiều cuộc trò chuyện từ cùng một worktree.
Cách Codex quản lý worktree cho bạn
Codex tạo các worktree trong $CODEX_HOME/worktrees. Commit khởi đầu là commit HEAD của nhánh được chọn khi bạn bắt đầu cuộc trò chuyện. Nếu chọn một nhánh có thay đổi cục bộ, Codex cũng áp dụng các thay đổi chưa commit vào worktree. Worktree không được checkout dưới dạng một nhánh mà ở trạng thái detached HEAD. Điều này cho phép Codex tạo nhiều worktree mà không làm lộn xộn các nhánh của bạn.
Sao chép tệp cục bộ bị bỏ qua vào worktree được quản lý
Worktree cục bộ do Codex quản lý bắt đầu từ một Git checkout, vì vậy các tệp được theo dõi đã có sẵn. Nếu kho lưu trữ bỏ qua những tệp thiết lập cục bộ mà worktree mới cần, hãy thêm tệp .worktreeinclude vào thư mục gốc của kho lưu trữ và liệt kê các đường dẫn bị bỏ qua hoặc mẫu kiểu .gitignore cần sao chép khi Codex tạo worktree được quản lý.
Sử dụng tính năng này cho các tệp mà Git chủ ý bỏ qua, chẳng hạn như .env, .env.local hoặc config/secrets.json. Codex chỉ sao chép các tệp bị bỏ qua khớp với .worktreeinclude; Codex không sao chép các tệp cục bộ khác mà Git không theo dõi. Không liệt kê các tệp được theo dõi.
Codex tự động sao chép một AGENTS.override.md bị bỏ qua vào các worktree cục bộ được quản lý, vì vậy bạn không cần liệt kê tệp đó trong .worktreeinclude.
# .worktreeinclude
.env
.env.local
config/secrets.jsonCodex bỏ qua các liên kết tượng trưng nguồn và không ghi đè những tệp đã tồn tại trong checkout mới. Hành vi này áp dụng cho các worktree cục bộ được ứng dụng ChatGPT dành cho máy tính quản lý, không áp dụng cho worktree từ xa hoặc Git worktree do bạn tự tạo bằng dòng lệnh.
Giới hạn của nhánh
Giả sử Codex hoàn thành một số công việc trên worktree và bạn chọn tạo một nhánh feature/a trên đó bằng Tạo nhánh tại đây. Bây giờ, bạn muốn thử nhánh đó trên checkout cục bộ. Nếu cố checkout nhánh này, bạn sẽ gặp lỗi sau:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Để khắc phục, bạn cần checkout một nhánh khác thay cho feature/a trên worktree.
Nếu định checkout nhánh ở máy cục bộ, hãy sử dụng Handoff để chuyển cuộc trò chuyện sang Local thay vì cố giữ cùng một nhánh được checkout ở hai nơi cùng lúc.
Tại sao lại có giới hạn này?
Git không cho phép checkout cùng một nhánh trong nhiều worktree cùng lúc vì một nhánh đại diện cho một tham chiếu có thể thay đổi duy nhất (`refs/heads/Khi một nhánh được checkout, Git coi HEAD của nhánh đó thuộc về worktree ấy và kỳ vọng các thao tác như commit, reset, rebase và merge sẽ cập nhật tham chiếu đó theo một trình tự xác định, tuần tự. Việc cho phép nhiều worktree cùng checkout một nhánh sẽ gây ra sự mơ hồ và tình trạng tranh chấp về thao tác của worktree nào sẽ cập nhật tham chiếu nhánh, từ đó có thể dẫn đến mất commit, chỉ mục không nhất quán hoặc cách giải quyết xung đột không rõ ràng.
Bằng cách thực thi quy tắc mỗi nhánh chỉ thuộc về một worktree, Git đảm bảo mỗi nhánh có một bản sao làm việc chính thức duy nhất, đồng thời vẫn cho phép các worktree khác tham chiếu an toàn đến cùng các commit thông qua detached HEAD hoặc các nhánh riêng biệt.
Dọn dẹp worktree
Worktree có thể chiếm nhiều dung lượng đĩa. Mỗi worktree có bộ tệp kho lưu trữ, phần phụ thuộc, bộ nhớ đệm bản dựng riêng, v.v. Vì vậy, ứng dụng ChatGPT dành cho máy tính cố gắng duy trì số lượng worktree trong một giới hạn hợp lý.
Theo mặc định, Codex giữ lại 15 worktree do Codex quản lý gần đây nhất. Bạn có thể thay đổi giới hạn này hoặc tắt tính năng tự động xóa trong phần cài đặt nếu muốn tự quản lý dung lượng đĩa.
Codex cố gắng tránh xóa các worktree vẫn còn quan trọng. Worktree do Codex quản lý sẽ không tự động bị xóa nếu:
- Có một cuộc trò chuyện được ghim liên kết với worktree đó
- Cuộc trò chuyện vẫn đang diễn ra
- Worktree là một worktree cố định
Worktree do Codex quản lý sẽ tự động bị xóa khi:
- Bạn lưu trữ cuộc trò chuyện được liên kết
- Codex cần xóa các worktree cũ hơn để không vượt quá giới hạn đã cấu hình
Trước khi xóa một worktree do Codex quản lý, Codex lưu một bản chụp nhanh của công việc trên đó. Nếu mở một cuộc trò chuyện sau khi worktree của nó đã bị xóa, bạn sẽ thấy tùy chọn khôi phục worktree.