Git word-diff: Review thay đổi từng từ trong tài liệu

Một đoạn README dài chỉ đổi hai từ, nhưng diff thông thường đánh dấu cả dòng bị xóa và thêm lại. Người review phải dò từng chữ để tìm thay đổi thực sự. Git word-diff cung cấp một cách nhìn bổ sung: đánh dấu phần từ ngữ được thay ngay trong dòng, phù hợp khi đọc tài liệu và thông điệp giao diện.

1. Chọn đúng phạm vi trước khi đổi cách hiển thị

Giả sử file guide.txt đã được Git theo dõi. Chạy tại gốc repository và thay đường dẫn theo dự án:

git --no-pager diff --word-diff=plain -- guide.txt

Lệnh này xem thay đổi chưa stage so với index. Nếu đã stage nội dung cần review, dùng:

git --no-pager diff --cached --word-diff=plain -- guide.txt

Đừng kết luận “không có thay đổi” chỉ vì lệnh đầu không hiện gì sau khi bạn vừa stage file. Cũng cần kiểm tra trạng thái nếu file mới chưa được theo dõi: diff thông thường không tự đưa nội dung file untracked vào kết quả.

2. Đọc ví dụ thay đổi thời gian lưu log

Trong một repository thử nghiệm, guide.txt ban đầu chứa câu Keep logs for seven days.. Sau khi đổi seven thành fourteen mà chưa stage, đầu ra word-diff có dòng:

Keep logs for [-seven-]{+fourteen+} days.

Phần trong [-...-] bị bỏ; phần trong {+...+} được thêm. Thay đổi nhỏ về chữ có thể lớn về ý nghĩa: thời gian lưu tăng gấp đôi. Reviewer vẫn cần kiểm tra cấu hình và tài liệu liên quan, thay vì duyệt chỉ vì diff trông ngắn.

Theo tài liệu Git diff, chế độ plain không escape các dấu phân cách nếu chúng đã có trong nội dung. Vì vậy, nếu file đang hướng dẫn chính cú pháp này, hãy đối chiếu diff theo dòng để tránh nhầm dấu thật với dấu hiển thị.

3. Dùng khi nào thì hữu ích?

Cách nhìn này phù hợp khi sửa câu văn dài, thông báo lỗi hoặc mô tả tham số. Trong buổi review, bạn có thể đọc đoạn văn hoàn chỉnh trước, dùng word-diff để tìm phần được sửa, rồi kiểm tra xem câu mới có còn nhất quán với hành vi ứng dụng hay không.

Mặc định Git tách từ theo khoảng trắng, trừ khi cấu hình hoặc diff driver quy định khác. Đây không phải phân tích ngôn ngữ tự nhiên: với tiếng Việt, một từ ghép có thể gồm nhiều phần cách nhau bởi khoảng trắng. Đừng kỳ vọng công cụ hiểu nghĩa hay tự phát hiện mâu thuẫn.

4. Giữ một lượt kiểm tra theo dòng

git --no-pager diff --word-diff=none -- guide.txt

Nếu đang review phần đã stage, thêm --cached như ở bước đầu. Lượt đọc này giúp thấy cấu trúc dòng và khoảng trắng mà cách trình bày theo từ có thể làm bạn ít chú ý. Với YAML, Python hoặc Markdown, định dạng cũng có thể ảnh hưởng đến ý nghĩa hoặc cách hiển thị.

Không dùng đầu ra plain làm patch để áp dụng lại thay đổi, cũng không viết script bằng cách tách chuỗi tại các dấu ngoặc trên. Đây là định dạng thuận tiện cho mắt người, không phải bằng chứng rằng một chương trình phân tích sẽ đọc nó không mơ hồ.

5. Checklist review tài liệu

• Xác nhận đang xem phần chưa stage hay đã stage.
• Đọc cả câu sau thay đổi, không chỉ từ được tô dấu.
• Kiểm tra số liệu, đơn vị và câu lệnh liên quan.
• Đối chiếu diff theo dòng và xem bản render nếu định dạng quan trọng.
• Chỉ stage hoặc commit sau khi review; các lệnh xem diff ở trên không tự làm việc đó.

Word-diff giúp tìm nhanh điểm chỉnh sửa trong văn bản. Giá trị lớn nhất đến từ việc kết hợp nó với ngữ cảnh: câu đang nói gì, thay đổi có đúng sự thật và người đọc sẽ hiểu tài liệu mới như thế nào.