Worktree

Trong ứng dụng ChatGPT dành cho máy tính, 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 gây ảnh hưởng lẫn nhau. Đối với Git repository, tác vụ theo lịch có thể chạy trên các worktree nền chuyên dụng để không xung đột với công việc đang thực hiện. Trong dự án không dùng hệ thống quản lý phiên bản, tác vụ theo 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 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 Git repository 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 repository. Mỗi worktree có bản sao riêng của mọi tệp trong repo, nhưng tất cả đều dùng chung metadata (thư mục .git) về commit, nhánh và các thông tin khác. 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ộ: Repository 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: Luồng di 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 chúng một cách an toàn.

Tại sao nên dùng worktree

1. 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.
2. Xếp hàng công việc chạy nền trong khi bạn tiếp tục tập trung vào công việc ở tiền cảnh.
3. Sau đó di chuyển cuộc trò chuyện vào Local khi bạn sẵn sàng kiểm tra, kiểm thử hoặc cộng tác trực tiếp hơn.

Bắt đầu

Worktree yêu cầu Git repository. Hãy đảm bảo dự án bạn chọn nằm trong một Git repository.

1. Chọn "Worktree"

   Trong chế độ xem cuộc trò chuyện mới, chọn Worktree bên dưới ô soạn thảo. Bạn cũng có thể chọn một môi trường cục bộ để chạy tập lệnh thiết lập cho worktree.

2. Chọn nhánh khởi đầu

   Bên dưới ô soạn thảo, chọn nhánh Git 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.

3. Gửi prompt

   Gửi prompt 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".

4. 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 và 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 luồng làm việc. Bạn có thể xem Local là tiền cảnh và Worktree là nền. Handoff cho phép bạn di chuyển cuộc trò chuyện giữa hai nơi.

Ở 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 bạn checkout một nhánh trên 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 hướng phổ biến:

1. Chỉ làm việc trên worktree. Hướng 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 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ộ.
2. Bàn giao cuộc trò chuyện cho Local. Dùng hướng 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 phần đầu cuộc trò chuyện.

Từ đây, bạn có thể commit các thay đổi, push nhánh lên repository từ xa và mở pull request trên GitHub.

Bạn có thể mở IDE tại worktree bằng nút "Mở" trong phần đầu, sử dụng terminal tích hợp hoặc bất kỳ công cụ nào khác cần dùng từ thư mục worktree.

Hãy nhớ rằng nếu tạo một nhánh trên worktree, bạn không thể checkout nhánh đó trong bất kỳ worktree nào khác, kể cả checkout cục bộ.

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 phần đầu cuộc trò chuyện và di chuyển cuộc trò chuyện sang Local.

Hướng 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 duy trì liên kết với cùng một worktree theo thời gian. Nếu sau đó bạn bàn giao cuộc trò chuyện trở lại worktree, Codex sẽ đưa cuộc trò chuyện về đúng môi trường nền đó để bạn tiếp tục từ nơi đã dừng.

Bạn cũng có thể thực hiện theo hướng ngược lại. Nếu đang làm việc trong Local và muốn giải phóng tiền cảnh, hãy dùng Bàn giao để di chuyển cuộc trò chuyện sang worktree. Điều này hữu ích khi bạn muốn Codex tiếp tục làm việc trong nền trong lúc chuyển sự chú ý trở lại một công việc cục bộ khác.

Vì Handoff sử dụng các thao tác Git, mọi tệp thuộc tệp .gitignore sẽ không 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 vĩnh viễn

Theo mặc định, các cuộc trò chuyện sử dụng worktree do Codex quản lý. Chúng được thiết kế để gọn nhẹ và có thể loại bỏ. Mỗi 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 đó bạn bàn giao cuộc trò chuyện về đó.

Nếu muốn một môi trường tồn tại lâu dài, hãy tạo worktree vĩnh viễn từ menu dấu ba chấm của một dự án trong thanh bên. Thao tác này tạo một worktree vĩnh viễn mới dưới dạng một dự án riêng. Worktree vĩnh viễn 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 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 tác vụ. Nếu bạn 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. Nó ở trạng thái detached HEAD. Nhờ đó, Codex có thể 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 repository bỏ qua các 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 repository 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ý.

Hãy dùng tính năng này cho những 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 những 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 tệp 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.json

Codex bỏ qua symlink nguồn và không ghi đè các tệp đã tồn tại trong checkout mới. Hành vi này áp dụng cho worktree cục bộ do ứ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 từ dòng lệnh.

Giới hạn về nhánh

Giả sử Codex hoàn tất một số công việc trên worktree và bạn chọn tạo 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 này trên checkout cục bộ. Nếu cố checkout nhánh, bạn sẽ nhận được lỗi sau:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

Để giải quyết, bạn cần checkout một nhánh khác thay cho feature/a trên worktree.

Nếu dự định checkout nhánh cục bộ, hãy dùng Handoff để di chuyển cuộc trò chuyện vào Local thay vì cố duy trì cùng một nhánh được checkout ở cả hai nơi cùng lúc.

Dọn dẹp worktree

Worktree có thể chiếm nhiều dung lượng ổ đĩa. Mỗi worktree có tập hợp tệp repository, phần phụ thuộc, bộ nhớ đệm build và các thành phần khác riêng. 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 những 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à worktree vĩnh viễn

Worktree do Codex quản lý tự động bị xóa khi:

• Bạn lưu trữ cuộc trò chuyện liên kết
• Codex cần xóa các worktree cũ hơn để duy trì trong giới hạn đã cấu hình

Trước khi xóa một worktree do Codex quản lý, Codex lưu snapshot của công việc trên đó. Nếu mở một cuộc trò chuyện sau khi worktree của cuộc trò chuyện đó đã bị xóa, bạn sẽ thấy tùy chọn khôi phục worktree.

Câu hỏi thường gặp