File riêng của project

Một project không chỉ có website: mã nguồn app React trong app/, một script deploy, ghi chú trong docs/, dữ liệu test trong backend/fixtures/, một README. Mọi file không thuộc phần nào của website là file của project (project file). Nền tảng lưu chúng cho nhóm của bạn, nên người tiếp theo chạy webmati clone cũng có chúng.

• Chúng không bao giờ được phục vụ ra ngoài: không khách truy cập, trang hay workflow nào đọc chúng, nên push một file như vậy không đổi gì trên website đang chạy. webmati push thường là gửi chúng — không cần --live, không có gì để xuất bản.
• Chúng đồng bộ y như mọi thứ khác: cùng các chữ cái trong webmati status, pull mang thay đổi của đồng nghiệp về, push không ghi đè file bạn chưa pull, resolve giải quyết xung đột.

webmati status                       # A  app/src/App.tsx — added
webmati push -m "form đăng nhập"     # file của project đi cùng lần push
webmati history                      # mỗi lần push một snapshot: ai, khi nào, ghi chú

Bạn không cần git cho việc nào trong số này: vài thứ một nhóm hay mở git để làm đều là lệnh ở đây (xem Lịch sử không cần git).

Cái gì là file của project, cái gì không

Mọi thứ trong thư mục project trừ:

• các phần của website: theme/, backend/workflows/, backend/tables/, backend/routes.json, variables.json, secrets.json, workers.json, pages/, content/, redirects.json, translations/, wellknown/;
• file của chính CLI: webmati.toml, .webmati/, các file AGENTS.md và CLAUDE.md mà clone tạo, và .git/;
• những gì .webmatiignore hoặc bất kỳ .gitignore nào loại ra.

.webmatiignore nằm ở gốc project và dùng cú pháp gitignore. clone tạo sẵn bản mặc định này (project chưa có file này cũng dùng đúng các luật đó):

node_modules/
dist/
build/
.next/
.vite/
coverage/
*.log
.DS_Store
.env*
!.env.example
*.pem
*.key
id_rsa*
.webmati/

Vì vậy dist/ và node_modules/ của app không bao giờ được gửi: khách truy cập chỉ nhận bản build qua webmati app deploy. Mọi .gitignore trong project cũng được tôn trọng, kể cả các file lồng bên trong (cả file trong app/). Sửa .webmatiignore để loại thêm; bản thân nó cũng là file của project, nên cả nhóm dùng chung luật.

Luật ignore không bao giờ xoá file

File đã được đồng bộ vẫn tiếp tục đồng bộ khi một luật bắt đầu khớp nó — giống git. Muốn ngừng đồng bộ, hãy xoá file rồi push. Còn file trên server mà luật của bạn loại ra thì không bị tải về cũng không bị xoá: status và pull cho biết có bao nhiêu file như vậy.

Thông tin đăng nhập không bao giờ rời máy bạn

Trước khi tải lên bất cứ gì, push đọc mọi file văn bản để tìm giá trị trông như thông tin đăng nhập — private key, key của nền tảng, Stripe, GitHub, AWS hay npm, mật khẩu trong URL — và từ chối lần push, chỉ rõ file và dòng:

Push refused by the offline checks (the server would refuse these too):
  app/src/pay.ts:2: error secret: this line holds what looks like a Stripe secret key — it would leave this machine
      fix: read it from an environment variable (or a backend secret: `webmati tool call set_backend_secret`), then push again

--no-validate không bỏ qua bước này, và server kiểm tra lại lần nữa. File có tên như file chứa thông tin đăng nhập bị từ chối bất kể nội dung: .env (nhưng không phải .env.example), *.pem, *.key, id_rsa*, .netrc, credentials.json, state của Terraform. webmati validate cho thấy đúng các lỗi đó trước khi bạn push.

Pull, xung đột và gộp

pull tải file mới và file đã đổi, xoá file đồng nghiệp đã xoá, và giữ quyền thực thi của script (chmod +x cũng là một thay đổi). Khi một file đổi ở cả hai phía, nó gộp:

• văn bản theo dòng, như git — chỗ hai bên cùng sửa có dấu <<<<<<<;
• .json theo từng khoá (một tsconfig.json có comment thì gộp theo dòng);
• file nhị phân (ảnh, font) không gộp được: đó là xung đột, bản của server nằm ở .webmati/conflicts/<path>.remote.

Khi push của bạn bị từ chối vì đồng nghiệp đã push trước, chỉ cần webmati pull: nó gộp thay đổi của họ vào của bạn, rồi push lại. Pull cho biết thay đổi nó đã lấy, đã gộp hay đang xung đột là của ai, trong snapshot nào:

  S  docs/setup.md  — changed on the server by lan@shop.vn · webmati-cli@lan-mac in #14

Xem Xung đột.

Lịch sử không cần git

Mỗi lần push có thay đổi file của project đều ghi một snapshot của toàn bộ tập file: số thứ tự, ai (tài khoản của người đó, và máy mà key nằm trên), khi nào, ghi chú -m của bạn và những gì đã đổi. Giữ 50 bản mới nhất, không bản nào cũ hơn 90 ngày trừ bản mới nhất.

webmati history                                # mọi snapshot, mới nhất trước
webmati history docs/setup.md                  # chỉ những bản đã đổi file này (hoặc một thư mục)
webmati diff docs/setup.md --at 12             # những gì đã đổi kể từ snapshot 12 (--since 12 cũng vậy)
webmati restore docs/setup.md --at 12          # đưa file đó về máy đúng như #12 — rồi push
webmati files restore 12                       # đưa MỌI file trên server về đúng như #12 (hỏi trước)
webmati files ls app/src                       # các file server đang giữ trong app/src

  #14  2026-10-11 10:02Z  lan@shop.vn · webmati-cli@lan-mac  "step two"
        modified docs/setup.md

restore --at chỉ ghi bản trên máy bạn: status báo file đã sửa và lần push sau gửi nó, như mọi thay đổi khác. files restore đổi server cho cả nhóm (webmati pull mang về máy); bản thân nó cũng được ghi thành snapshot nên hoàn tác được theo cùng cách, và nếu có ai push xen giữa lúc xem kế hoạch và lúc khôi phục thì lệnh bị từ chối, không có gì thay đổi.

history backend/workflows/<code> liệt kê các phiên bản workflow đã được xuất bản (webmati tool call revert_backend_workflow đưa một bản trở lại chạy thật). File theme giữ lịch sử dưới dạng phiên bản theme trong trang quản trị (bản sao cả theme); history dành cho file riêng của project và workflow.

Giới hạn

File lớn hơn được status báo và không bao giờ được gửi: loại nó ra bằng .webmatiignore (kết quả build và thư viện phụ thuộc không bao giờ cần đồng bộ).

Tiếp theo

Vòng làm việc hằng ngày