Git Commit Message: Quy tắc, Ví dụ và Quy ước

Vì sao Git Commit Message quan trọng

Commit message giải thích các thay đổi của bạn cho bất kỳ ai đọc code sau này, bao gồm cả chính bạn trong tương lai.

Ba tháng nữa, bạn sẽ không nhớ tại sao mình refactor pipeline dữ liệu đó hay vì sao bạn chuyển từ pandas sang polars cho một thao tác cụ thể. Commit message là bản ghi duy nhất về lập luận của bạn. Không có nó, bạn sẽ phải đoán hoặc đào bới trong các luồng Slack và ticket JIRA.

Dưới đây là vài lý do cụ thể hơn vì sao git commit message quan trọng.

Code review diễn ra nhanh hơn với commit message rõ ràng. Người review có thể lướt qua thông điệp, hiểu mục đích và tập trung xem triển khai có khớp không. Thông điệp mơ hồ buộc reviewer phải đảo ngược tư duy của bạn chỉ từ diff mà thôi.

Gỡ lỗi cũng dễ hơn. Khi một lỗi xuất hiện, bạn sẽ dùng git log hoặc git blame để truy vết thời điểm đoạn code có vấn đề được đưa vào. Một thông điệp như "fix authentication bug" chẳng nói lên điều gì. Một thông điệp như "fix token expiration check in auth middleware" chỉ thẳng tới vấn đề.

Hợp tác nhóm phụ thuộc vào lịch sử dễ đọc. Khi ai đó tham gia dự án của bạn hoặc tiếp quản phần bạn để lại, họ sẽ đọc qua các commit để hiểu codebase đã tiến hóa thế nào. Thông điệp rõ ràng biến lịch sử Git của bạn thành tài liệu thực sự hữu ích.

Tóm lại, một commit message mô tả rõ ràng chỉ mất 15–30 giây để viết, nhưng tiết kiệm hàng giờ bối rối về sau.

Nguyên tắc cốt lõi của một Git Commit Message tốt

Commit message tốt tuân theo vài nguyên tắc đơn giản — chỉ vậy thôi.

Viết cho người đọc trong tương lai

Commit message không phải viết cho bạn ở thời điểm hiện tại — mà cho bất kỳ ai sẽ đọc nó sau sáu tháng nữa.

Người đó có thể là thành viên mới đang cố hiểu vì sao codebase vận hành theo một cách nào đó. Cũng có thể là chính bạn, đang cố nhớ vì sao đã đưa ra quyết định cụ thể. Dù là ai, họ sẽ không có ngữ cảnh như bạn hôm nay.

Tập trung vào mục đích và lý do, không chỉ là thay đổi gì. Diff cho thấy đã thay đổi gì. Thông điệp của bạn nên giải thích vì sao thay đổi và giải quyết vấn đề nào.

Rõ ràng và súc tích

Thông điệp ngắn gọn, mô tả giúp dễ lướt khi bạn đang xem hàng chục commit.

Một thông điệp như "add caching" là mơ hồ. Còn "add Redis caching for API responses" nói chính xác chuyện gì đã xảy ra. Bạn có thể đọc nó trong git log --oneline và biết ngay commit làm gì.

Dòng tiêu đề nên trả lời: commit này làm gì? Nếu cần hơn 50–60 ký tự để trả lời, có lẽ bạn đang commit quá nhiều thay đổi cùng lúc.

Nhất quán

Tính nhất quán trong repo khiến lịch sử có thể dự đoán và dễ phân tích hơn.

Khi mọi commit theo cùng một định dạng, bạn có thể nhanh chóng lướt qua lịch sử. Bạn biết nhìn ở đâu để thấy loại thay đổi, phạm vi và mô tả. Nhóm áp dụng định dạng nhất quán cũng có thể tự động hóa các tác vụ như tạo changelog hoặc lọc commit theo loại.

Chọn một phong cách và bám theo. Nếu nhóm dùng mệnh lệnh hiện tại, đừng thỉnh thoảng chuyển sang thì quá khứ.

Giải thích cái gì và vì sao (không phải như thế nào)

Code thể hiện bạn đã giải bài toán như thế nào. Commit message nên giải thích vấn đề là gì và vì sao bạn chọn giải pháp này.

Đừng viết "refactored load_data() to use list comprehension instead of for loop." Hãy viết "speed up data loading by 40% for large CSV files." Thông điệp đầu mô tả thay đổi code. Thông điệp sau giải thích tác động.

Thêm ngữ cảnh khi giúp người đọc sau này hiểu quyết định của bạn. Nếu bạn đã thử ba cách khác trước khi chốt cách này, hãy đề cập. Nếu có bug report hay quyết định thiết kế liên quan, hãy tham chiếu.

Cấu trúc của một Git Commit Message

Hầu hết Git commit message theo cấu trúc ba phần tiêu chuẩn: dòng tiêu đề, phần thân và phần chân.

Dòng tiêu đề

Dòng tiêu đề là tóm tắt một dòng xuất hiện trong git log --oneline và danh sách pull request.

Giữ dưới 50 ký tự nếu có thể, tối đa 72. Giới hạn này đảm bảo thông điệp hiển thị đúng trong terminal và UI của GitHub mà không bị cắt. Nếu bạn không thể tóm tắt trong 50 ký tự, có lẽ bạn đang cố mô tả quá nhiều thay đổi trong một commit.

Dùng lối mệnh lệnh — viết "add feature" thay vì "added feature" hay "adds feature." Hãy nghĩ như đang hoàn thành câu "Nếu được áp dụng, commit này sẽ...". Vậy "Nếu được áp dụng, commit này sẽ add Redis caching" nghe tự nhiên, còn "... will adds Redis caching" thì không.

Ví dụ:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Phần thân (khi cần)

Bỏ qua phần thân với các thay đổi đơn giản. Nếu dòng tiêu đề giải thích đầy đủ commit, vậy là xong.

Thêm phần thân khi bạn cần giải thích vì sao thay đổi hoặc cung cấp ngữ cảnh giúp người đọc sau này. Chừa một dòng trống giữa tiêu đề và thân — Git dùng nó để tách hai phần.

Phần thân nên trả lời: Giải quyết vấn đề gì? Vì sao chọn cách tiếp cận này? Có tác dụng phụ hay hạn chế nào không? Bạn đã cân nhắc giải pháp nào khác?

Ngắt dòng ở 72 ký tự để giữ văn bản dễ đọc trong terminal. Hầu hết trình soạn thảo có thể làm tự động.

Ví dụ:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.Được hỗ trợ bởi

Phần chân (tùy chọn)

Dùng phần chân để tham chiếu issue, pull request liên quan hoặc các thay đổi phá vỡ tương thích.

Nếu commit của bạn sửa một issue trên GitHub, thêm Fixes #123 hoặc Closes #456 ở phần chân. GitHub sẽ tự động đóng issue khi commit được merge. Với thay đổi phá vỡ tương thích, thêm BREAKING CHANGE: kèm mô tả điều gì bị phá vỡ và cách di trú.

Ví dụ:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789Được hỗ trợ bởi

Bạn không cần phần chân cho hầu hết commit — chỉ dùng khi liên kết tham chiếu bên ngoài hoặc đánh dấu thay đổi phá vỡ tương thích.

Các loại Git Commit Message thường gặp và khi nào dùng

Nhiều dự án dùng tiền tố loại commit để phân loại thay đổi nhanh chóng.

Bạn không cần ghi nhớ một danh sách nhãn cứng nhắc. Mục tiêu là giúp người đọc nhanh chóng nhận diện loại thay đổi mà không phải đọc toàn bộ diff.

Có bốn nhóm bạn nên biết:

• Thay đổi tính năng giới thiệu chức năng mới. Dùng tiền tố như feat: hoặc add: khi bạn xây dựng thứ gì đó mới — endpoint API mới, hàm xử lý dữ liệu hay tính năng hướng đến người dùng. Ví dụ: feat: add CSV export for analysis results.

• Sửa lỗi giải quyết vấn đề hiện có. Dùng fix: khi bạn chỉnh hành vi không hoạt động như dự định. Có thể là từ null pointer exception đến tính toán sai trong mô hình. Ví dụ: fix: handle missing values in preprocessing pipeline.

• Cập nhật tài liệu cải thiện chú thích code, tệp README hoặc tài liệu nội tuyến. Dùng docs: khi bạn không thay đổi cách code hoạt động, chỉ giải thích tốt hơn. Ví dụ: docs: add usage examples for data loader class.

• Refactor và bảo trì cải thiện cấu trúc code mà không đổi hành vi. Dùng refactor: khi bạn tổ chức lại code để sạch hơn, dễ bảo trì hơn. Dùng chore: cho các tác vụ thường lệ như cập nhật phụ thuộc hoặc đổi cấu hình build. Ví dụ: refactor: extract validation logic into separate module hoặc chore: update pandas to 3.0.0.

Chọn loại mô tả đúng nhất thay đổi của bạn và tiếp tục — tính nhất quán quan trọng hơn việc chọn nhãn "hoàn hảo".

Quy tắc để viết Git Commit Message tốt hơn

Dưới đây là danh sách kiểm giúp commit message của bạn hữu ích hơn.

• Giữ dòng tiêu đề dưới 50 ký tự. Điều này đảm bảo hiển thị đúng trong git log --oneline, danh sách commit trên GitHub và đầu ra terminal mà không bị cắt. Nếu không thể trong 50 ký tự, hãy hướng tới tối đa 72.

• Dùng lối mệnh lệnh. Viết "add feature" thay vì "added feature" hay "adds feature." Dòng tiêu đề nên hoàn tất câu "Nếu được áp dụng, commit này sẽ...". Ví dụ "... sẽ add caching" là đúng.

• Tách tiêu đề và thân bằng một dòng trống. Git dùng dòng trống này để phân biệt tóm tắt và giải thích chi tiết. Không có nó, các công cụ Git có thể hiển thị sai thông điệp.

• Bỏ dấu chấm ở cuối dòng tiêu đề. Bạn tiết kiệm ký tự và dòng tiêu đề vốn không phải câu hoàn chỉnh. Viết fix null pointer in loader thay vì fix null pointer in loader.

• Viết hoa chữ cái đầu của dòng tiêu đề. Viết Add caching for API calls thay vì add caching for API calls. Điều này giúp lịch sử commit trông nhất quán và chuyên nghiệp.

• Dùng phần thân để giải thích vì sao, không phải cái gì. Diff cho thấy cái gì thay đổi. Phần thân nên giải thích lý do, cách tiếp cận thay thế bạn đã cân nhắc, và các đánh đổi đã thực hiện.

• Ngắt dòng phần thân ở 72 ký tự. Điều này tránh lỗi quấn dòng trong terminal và giữ commit message dễ đọc trên các công cụ khác nhau.

• Giữ mỗi commit là nguyên tử. Mỗi commit chỉ nên chứa một thay đổi logic. Nếu bạn vừa sửa lỗi vừa refactor code, hãy tách thành hai commit với thông điệp riêng.

Ví dụ về Git Commit Message tốt

Dưới đây là các ví dụ thực tế cho thấy commit message tốt trông như thế nào trong các kịch bản khác nhau.

Một bản sửa đơn giản

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.Được hỗ trợ bởi

Ví dụ này hiệu quả vì nó xác định vấn đề (crash do NaN), giải thích nơi xảy ra (pipeline tiền xử lý, cột age) và mô tả giải pháp (điền trung vị).

Một tính năng mới

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.Được hỗ trợ bởi

Commit tính năng tốt giải thích bạn đã xây gì, vì sao hữu ích, và các chi tiết giúp người đọc hiểu phạm vi.

Một lần refactor

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.Được hỗ trợ bởi

Thông điệp refactor nên làm rõ rằng bạn không đổi chức năng, chỉ đổi cấu trúc. Câu "all tests still pass" tạo sự yên tâm cho reviewer.

Một cập nhật tài liệu

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.Được hỗ trợ bởi

Commit tài liệu nên giải thích bạn đã bổ sung gì và vì sao cần.

Tham chiếu một issue hoặc ticket

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247Được hỗ trợ bởi

Khi bạn tham chiếu một issue, hãy thêm đủ ngữ cảnh để người khác hiểu bản sửa mà không cần click vào ticket. Fixes #247 ở cuối báo cho GitHub tự động đóng issue khi commit này được merge.

Tất cả ví dụ theo cùng mẫu: bắt đầu với thay đổi gì, giải thích vì sao, thêm ngữ cảnh giúp người đọc sau này, và tham chiếu issue liên quan khi cần.

Conventional Commits như một tiêu chuẩn Git Commit Message

Conventional commits là định dạng phổ biến bổ sung cấu trúc cho commit message thông qua mẫu tiền tố đơn giản.

Định dạng cơ bản

Định dạng như sau: type(scope): description.

Type mô tả loại thay đổi bạn đang thực hiện — feat cho tính năng, fix cho sửa lỗi, docs cho tài liệu, refactor cho tái cấu trúc code, v.v. Scope là tùy chọn, chỉ phần codebase thay đổi — như (auth) hoặc (api). Description giải thích bạn đã làm gì.

Ví dụ:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate moduleĐược hỗ trợ bởi

Hãy nhớ đây là quy ước, không phải yêu cầu. Git không quan tâm bạn có dùng định dạng này không. Chủ yếu là quyết định của nhóm về cách cấu trúc thông điệp để đảm bảo nhất quán và hỗ trợ công cụ.

Khi nào conventional commits hữu ích

Những nhóm tự động hóa quy trình phát hành sẽ được lợi nhiều nhất từ conventional commits.

Các công cụ có thể phân tích lịch sử commit và tự động tạo changelog. Khi bạn gắn thẻ phát hành, công cụ quét các commit kể từ lần phát hành trước, nhóm theo loại (feat, fix, docs), và tạo changelog được định dạng. Điều này tiết kiệm công sức theo dõi thay đổi giữa các phiên bản.

Conventional commits cũng hỗ trợ tự động hóa semantic versioning. Nếu tất cả commit kể từ bản phát hành trước là sửa lỗi, công cụ sẽ tăng bản vá (1.2.3 → 1.2.4). Nếu bạn thêm tính năng, nó tăng bản nhỏ (1.2.3 → 1.3.0). Thay đổi phá vỡ tương thích sẽ tăng bản lớn (1.2.3 → 2.0.0).

Nhưng nếu nhóm bạn không dùng phát hành tự động hay tạo changelog, conventional commits có thể là quá mức cần thiết. Cấu trúc này hữu ích cho máy móc hơn con người, hãy ghi nhớ điều đó.

Những lỗi thường gặp với Git Commit Message cần tránh

Ngay cả lập trình viên giàu kinh nghiệm đôi khi cũng mắc lỗi khi viết commit message, nhưng thường do lười hơn là thiếu kiến thức.

Dưới đây là vài lỗi bạn nên tránh.

Thông điệp mơ hồ hoặc chung chung

Những thông điệp như "fix bug" hay "update code" không nói gì với người đọc sau này.

Khi bạn tìm một thay đổi cụ thể trong git log, bạn sẽ lướt qua hàng chục commit. Một thông điệp "fix bug" buộc bạn mở diff và đọc code để hiểu sửa cái gì. Còn "fix null pointer in data preprocessing" cho bạn biết ngay đây có phải commit bạn cần không.

Thông điệp chung chung làm lãng phí thời gian của mọi người. Nếu bạn không nhớ đủ rõ mình đã thay đổi gì để viết một thông điệp cụ thể, có lẽ bạn chưa nên commit.

Trộn các thay đổi không liên quan

Mỗi commit nên chứa một thay đổi logic.

Khi bạn sửa lỗi và refactor code không liên quan trong cùng một commit, bạn làm review khó hơn và khiến git bisect mất tác dụng. Nếu commit đó gây ra regression, ai đó sẽ phải gỡ xem phần nào gây lỗi. Nếu họ muốn revert chỉ phần sửa lỗi, họ không thể — họ sẽ revert cả phần refactor.

Bạn luôn nên tách thay đổi thành các commit riêng. Sửa lỗi ở một commit, refactor ở commit khác. Mỗi commit nên là thứ có thể revert độc lập mà không làm vỡ codebase.

Nếu bạn đã trộn thay đổi trên máy, dùng git add -p để stage từng phần của file riêng rẽ và commit theo từng khối logic.

Để lại thông điệp đang làm dở (WIP)

Những commit với thông điệp như "WIP" hay "temp fix" thì ổn trên máy cục bộ nhưng không nên xuất hiện trên nhánh chính.

Trước khi merge feature branch, hãy dọn lịch sử commit. Squash các commit WIP thành những commit ý nghĩa với thông điệp chuẩn chỉnh. Viết lại "asdf" hay "trying something" thành mô tả giải thích bạn thực sự đã làm gì.

Dùng git rebase -i để gộp commit, viết lại thông điệp và sắp xếp lại thay đổi trước khi push. Nhóm của bạn nên thấy một lịch sử sạch về cái gì đã thay đổi và vì sao, chứ không phải đọc quá trình debug của bạn.

Thực hành tốt nhất cho các nhóm khi dùng Git Commit Message

Nếu nhóm của bạn muốn lịch sử Git thực sự hữu ích, bạn cần tính nhất quán. Dưới đây là một số thực hành tốt nên theo.

Thống nhất phong cách chung từ sớm. Quyết định liệu bạn sẽ dùng conventional commits, định dạng tùy chỉnh, hay chỉ một bộ quy tắc cơ bản. Chọn một cách và bám theo trên toàn nhóm. Khi nửa số commit ghi "feat: add feature" còn nửa kia ghi "Added new feature", lịch sử của bạn sẽ khó lướt và tự động hóa có thể hỏng.

Phong cách không quan trọng bằng việc mọi người đều tuân theo. Một số nhóm thích mệnh lệnh hiện tại ("add feature"), số khác dùng thì quá khứ ("added feature"). Cả hai đều ổn nếu áp dụng nhất quán.

Ghi tài liệu quy ước ở nơi dễ truy cập. Thêm tệp CONTRIBUTING.md vào repo để giải thích định dạng commit message của bạn kèm ví dụ. Bao gồm trong tài liệu onboarding cho thành viên mới. Khi ai đó hỏi "tôi nên định dạng commit này thế nào?", hãy trỏ họ đến tài liệu thay vì giải thích lại.

Tài liệu nên bao quát định dạng cơ bản bạn dùng, khi nào thêm phần thân so với chỉ tiêu đề, cách tham chiếu issue hoặc ticket, và vài ví dụ thực từ repo của bạn.

Sử dụng commit message trong code review. Commit message tốt giúp review pull request nhanh hơn và tập trung hơn. Reviewer có thể đọc commit message để hiểu tiến trình thay đổi trước khi đi vào code.

Khi review, hãy kiểm tra commit message giống như kiểm tra code. Nếu thông điệp mơ hồ hoặc gây hiểu lầm, yêu cầu viết lại trước khi merge. Một PR với commit rõ ràng sẽ dễ review, dễ revert khi cần, và dễ hiểu về sau.

Kết luận

Một commit message rõ ràng chỉ mất 30 giây để viết nhưng tiết kiệm hàng giờ bối rối về sau.

Hãy xem lịch sử commit là tài liệu sống cùng code của bạn. Khi bạn viết "fix bug" thay vì "fix null pointer in data preprocessing", bạn đang lãng phí thời gian của mọi người đọc commit đó sau này — bao gồm cả chính bạn.

Hãy đối xử với commit message như với code. Nếu bạn sẽ không push code cẩu thả, không chú thích lên production, thì cũng đừng push commit message cẩu thả. Dùng lối mệnh lệnh, giữ tiêu đề dưới 50 ký tự, giải thích lý do trong phần thân khi cần, và đảm bảo mỗi commit là nguyên tử.

Giờ bạn đã biết cách viết commit message có ý nghĩa. Để nâng cao kỹ năng, hãy đăng ký khóa học Intermediate Git của chúng tôi.