Sơ đồ GitGraph là một thành phần trực quan hóa chuyên biệt được các nhà phát triển, đội ngũ DevOps và người viết kỹ thuật sử dụng để truyền đạt rõ ràng các chiến lược nhánh Git, quản lý phát hành và quy trình phát triển. Được tích hợp sẵn vào Mermaid.js, gitGraphđộng cơ sử dụng mô hình thời gian tuần tự, khai báo. Điều này ánh xạ các lệnh thực tế từ terminal trực tiếp sang bản đồ thời gian trực quan chính xác mà không cần chỉnh sửa hình ảnh thủ công.
Hiểu về Ma trận Thời gian GitGraph
Khác với sơ đồ luồng hệ thống tự do, sơ đồ GitGraph tuân theo logic nghiêm ngặt, tuần tự, theo thứ tự xảy ra, mô phỏng không gian làm việc kiểm soát phiên bản thực tế:
- Tự động nhánh gốc:Mỗi không gian làm việc sơ đồ được khởi tạo sẽ tự động tạo một đường thời gian gốc chính. Mặc định, đường này được đặt tên là
main, và tất cả các hành động tiếp theo đều theo dõi theo nó trừ khi một nhánh thay thế sạch sẽ được tạo ra. - Ưu tiên thứ tự:Các thành phần được hiển thị dọc theo trục thời gian từ trái sang phải dựa trên thứ tự chèn lệnh trong tệp nguồn mã của bạn.
Cấu trúc cú pháp cơ bản
Mỗi dòng thời gian bắt đầu bằng từ viết thường chữ cái đầu tiên viết hoa gitGraphtừ khóa khai báo. Tiếp theo là một cột liệt kê tuần tự các lệnh thực thi nguyên tử như commit, checkout và merge.
gitGraph
commit
commit
branch feature-login
checkout feature-login
commit
checkout main
merge feature-login
Bản tham chiếu lệnh hành động Git đầy đủ
Động cơ bố cục hiểu các lệnh hành động cụ thể, viết thường để điều chỉnh độ dày đường, chia tách các đường hoặc kết hợp các điểm cuối lại với nhau trên bảng canvas không gian làm việc.
| Token lệnh Git | Các thay đổi đối số tham số | Hành vi kỹ thuật và bố cục |
|---|---|---|
commit |
id: "hash", type: TYPE, nhãn: "v1.0" |
Thêm một nút mốc mới trực tiếp vào đường dẫn nhánh mục tiêu đang hoạt động. |
nhánh |
tên, thứ tự: Số nguyên |
Tạo một phân nhánh đường đi mới. Bạn có thể buộc vị trí xếp chồng dọc của nó bằng cách sử dụng tùy chọn rõ ràngthứ tự giá trị. |
checkout / chuyển đổi |
tên-nhánh |
Dịch chuyển con trỏ chỉ số ghi âm đang hoạt động sang đường nhánh mục tiêu đã chỉ định. Các thao tác tiếp theo sẽ theo dõi theo đường đi này. |
hợp nhất |
tên-nhánh-mục-tiêu, id: "băm", nhãn: "v2" |
Hợp nhất đường nhánh đã chỉ định trở lại nhánh hiện tại, tạo ra một điểm giao nhau hình ảnh rõ rệt. |
cherry-pick |
id: "băm-đã-đăng-ký", cha: "băm-cha" |
Nhân bản một bản ghi cụ thể từ nhánh bên ngoài lên đường đi nhánh hiện tại mà không trộn lẫn các đường đi. |
Tính năng nâng cao: Loại bản ghi & Tùy chỉnh nhãn
Để phân biệt giữa các bản vá thông thường, hoàn nguyên hệ thống hoặc các phiên bản chính thức lớn, bạn có thể gán mộtloại và nhãn bộ sửa đổi chuỗi bên trong một khối đối số sử dụng các thuộc tính kiểu key-value như JSON.
Các loại phân loại hình dạng commit được hỗ trợ:
loại: BÌNH THƯỜNG: Cấu hình mặc định. Hiển thị như một nút hình tròn đặc đầy màu dọc theo đường thời gian.loại: NGƯỢC LẠI: Nhấn mạnh việc hoàn nguyên kiến trúc hoặc chương trình. Hiển thị như một nút hình tròn đặc bị chéo ($X$).loại: NỔI BẬT: Gợi ý sự chú ý đến những thay đổi cấu trúc quan trọng hoặc các sửa lỗi bảo mật. Hiển thị như một hộp hình chữ nhật dài, đặc đầy màu.
gitGraph
commit id: "Ban đầu"
commit loại: NỔI BẬT id: "Sửa lỗi bảo mật-1.0.1" nhãn: "v1.0.1"
commit loại: NGƯỢC LẠI id: "Hoàn nguyên-Tính năng-X"
Tính năng nâng cao: Logic chọn lựa và các ràng buộc nghiêm ngặt
Lệnh cherry-picklệnh sao chép một nút cô lập cụ thể từ một nhánh khác lên nhánh đang hoạt động của bạn. Để thực hiện cherry-pick mà không gây lỗi bố cục biên dịch, bạn phải tuân theo các yêu cầu kiểm tra không gian làm việc nghiêm ngặt sau:
- Ràng buộc loại trừ: ID commit đích mà bạn đang cherry-pick *phải không* tồn tại trước đó trên nhánh mà bạn đang theo dõi.
- Lịch sử tiền điều kiện: Đường nhánh đang hoạt động hiện tại phải chứa ít nhất một nút commit hợp lệ trước khi thực hiện hành động cherry-pick.
- Yêu cầu cha của nút hợp nhất: Nếu bạn đang cherry-pick một nút hợp nhất, bạn phải truyền rõ ràng chuỗi nhận dạng cha trực tiếp ngay phía trên bằng cách sử dụng khối sửa đổi
cha: "băm"khối sửa đổi.
gitGraph
commit id: "thiết lập"
nhánh staging
chuyển sang staging
commit id: "sửa lỗi tính năng"
chuyển sang main
commit id: "cơ sở"
cherry-pick id: "sửa lỗi tính năng"
Tính năng nâng cao: Cấu hình tham số Frontmatter
Bạn có thể điều chỉnh chính xác các hành vi trực quan toàn cục (như bật/tắt nhãn nhánh, thay đổi chỉ số hàng, hoặc chồng các dòng thời gian) bằng cách khai báo một %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% khối chỉ thị cấu hình ở đầu tuyệt đối của đoạn mã biểu đồ của bạn.
Ma trận tham số có thể cấu hình
| Chuỗi khóa cấu hình | Định nghĩa kiểu | Giá trị mặc định | Kết quả thay đổi giao diện trực quan |
|---|---|---|---|
showBranches |
Boolean | true |
Bật/tắt hiển thị nhãn theo dõi từng nhánh ở phía bên trái lưới bảng vẽ. |
showCommitLabel |
Boolean | true |
Bật/tắt việc hiển thị tiêu đề văn bản và mã ký tự chữ số trực tiếp trên các nút dòng thời gian riêng lẻ. |
mainBranchName |
Chuỗi | "main" |
Thay đổi văn bản theo dõi tên nhánh gốc mặc định (ví dụ: thay đổi thành "master" hoặc "trunk"). |
mainBranchOrder |
Số nguyên | 0 |
Thiết lập chỉ số vị trí thứ tự chồng dọc từ trên xuống dưới cho đường theo dõi dòng thời gian gốc chính. |
parallelCommits |
Boolean | sai |
Nếu được sửa đổi thành đúng, các bản ghi riêng biệt có khoảng cách bước cha giống nhau sẽ được căn chỉnh đối xứng trên cùng một mức dọc. |
Bản thiết kế thực tế: Đường ống quản lý phát hành Git-Flow doanh nghiệp
Bản thiết kế doanh nghiệp toàn diện này minh họa một đường ống phát hành sản xuất tiêu chuẩn. Nó ghi đè các tham số cấu hình để đổi tên đường dẫn gốc thành trunk, thiết lập thứ tự phân nhánh cố định, sử dụng nhiều đường nhánh (develop và feature-auth), thực hiện hợp nhất, áp dụng nhãn tùy chỉnh và triển khai các hình dạng bản ghi nổi bật ưu tiên cao.
%%{init: { 'gitGraph': { 'mainBranchName': 'trunk', 'showCommitLabel': true } } }%%
gitGraph
commit id: "Ban-dau-Core" tag: "v1.0.0"
commit id: "Thiet-lap-CI"
branch develop
checkout develop
commit id: "Sprint-1-Co-so"
branch feature-auth
checkout feature-auth
commit id: "Logich-JWT"
commit id: "Logich-MFA" type: NHOI
checkout develop
merge feature-auth id: "Hop-nhat-Auth"
commit id: "Da-bien-soan-Beta"
checkout trunk
merge develop id: "Phat-hanh-Prod" tag: "v2.0.0"
Những lỗi cú pháp phổ biến & Giới hạn hệ thống
Khi biên dịch các biểu đồ kiểm soát phiên bản chính xác, hãy lưu ý những tham số khắc phục sự cố này để tránh lỗi tính toán bố cục:
- Lỗi phân biệt chữ hoa chữ thường: Khai báo khởi tạo chính phải được viết rõ ràng bằng camelCase như
gitGraph. Viết toàn bộ bằng chữ thường nhưgitgraphsẽ gây ra lỗi sập trình biên dịch khi phân tích cú pháp. - Các định danh chữ số và chữ cái không được đặt trong dấu ngoặc kép: Khi truyền các tham số bản ghi tùy chỉnh (ví dụ,
id: core_init), các giá trị chứa dấu gạch ngang, khoảng trắng hoặc dấu chấm *phải* được đặt trong dấu ngoặc kép. Bỏ quên khối dấu ngoặc kép sẽ dẫn đến lỗi biên dịch xác thực. - Mục tiêu checkout không hợp lệ: Gọi một
checkout branch_namehành động trên một định danh chuỗi chưa được khởi tạo trước đó bằng cách sử dụngbranch branch_namelệnh sẽ ngay lập tức làm hỏng việc xây dựng đồ thị. - Xung đột thứ tự nhánh: Khi sử dụng
orderthẻ cấu hình trên các nhánh, đảm bảo rằng nhiều đường đi không được ánh xạ vào các số nguyên giống nhau trừ khi bạn muốn các vết đường đi trên bảng vẽ chồng chéo lên nhau. Giữ số đường đi của nhánh là duy nhất. - Lỗi tách biệt khoảng trắng: Đảm bảo có các khoảng trắng rõ ràng cho các đối số khi tách biệt các thuộc tính bên trong ma trận tham số trong dấu ngoặc đơn (ví dụ: dùng
id: "1", type: HIGHLIGHT). Bỏ sót dấu phẩy hoặc khoảng trắng có thể gây ra ngoại lệ phân tích cú pháp.