Thứ làm hỏng build không phải là một dòng code sai, mà là một commit chứa obj/. Máy bạn build được, máy đồng nghiệp báo lỗi project.assets.json trỏ tới đường dẫn không tồn tại, còn CI thì restore lại từ đầu và ra kết quả khác. Quản lý mã nguồn với Git cho dự án .NET không khó ở các lệnh cơ bản — khó ở những quy ước nhỏ quyết định repo có sạch hay không.
Bài này giả định bạn đã biết clone, add, commit, push. Phần dưới là những gì một team .NET cần thống nhất để lịch sử commit còn đọc được sau sáu tháng, và để việc chuyển nhánh không kéo theo artifact cũ.
Mục lục
Cập nhật 2026
dotnet new gitignoresinh mẫu.gitignoređúng cho SDK hiện tại, thay vì copy một file từ blog cũ rồi thiếu mục. Dùng nó làm điểm bắt đầu, không phải bản cuối cùng.- Central Package Management (
Directory.Packages.props) là cách chuẩn để ghim version trong repo nhiều project; nó biến phần lớn xung đột.csprojthành xung đột một file. - Secret scanning đã thành mặc định trên GitHub (push protection) và có trong GitLab; quét trước khi push rẻ hơn nhiều so với xoay credential sau khi lộ.
- Các lệnh cũ trong bài gốc (
git checkout -- file,git checkout -b) vẫn chạy nhưng đã có dạng rõ nghĩa hơn:git restore,git switch(Git 2.23+).
Mô hình: commit là snapshot, branch là con trỏ
Git lưu mỗi commit như một ảnh chụp toàn bộ cây làm việc, không phải một danh sách diff. Diff chỉ được tính khi bạn xem. Hiểu điều này giải thích ba hành vi hay gây bối rối:
- Chuyển nhánh là đổi con trỏ và ghi lại file — nhanh, nhưng file bị bỏ qua bởi
.gitignorethì không được Git bảo vệ.bin/vàobj/cũ từ nhánh trước vẫn nằm trên đĩa. rebasetạo commit mới với hash mới. Đó là lý do không rebase nhánh đã được người khác pull.- Merge giữ nguyên hash cũ và thêm một merge commit. Lịch sử có nhánh, nhưng không mất gì.
Merge hay rebase, chọn theo câu hỏi “ai đã thấy commit này?”
Quy tắc thực dụng: nhánh riêng, chưa ai dùng → rebase để lịch sử tuyến tính. Nhánh đã push và có người dựa vào → merge. Trên nhánh dài ngày, rebase định kỳ lên main giúp xung đột xuất hiện sớm và nhỏ, thay vì dồn vào ngày merge.
git config pull.rebase true # pull = fetch + rebase, mặc định cho repo này
git config merge.conflictStyle zdiff3 # hiện cả base, giúp hiểu xung đột thật
git fetch origin
git rebase origin/main
# Khi rebase một nhánh nhiều commit lộn xộn
git rebase -i origin/main # squash, reword, drop
git pull mặc định merge tạo ra những merge commit “Merge branch ‘main’ of …” không ai đọc. Đặt pull.rebase=true một lần cho cả team là cách rẻ nhất để dọn lịch sử.
Git cho dự án .NET: chọn workflow nào?
Hai mô hình còn phổ biến, và chúng không phải lựa chọn tôn giáo. Trung bình một team ASP.NET Core deploy hàng tuần nên nghiêng trunk-based; team làm sản phẩm đóng gói theo phiên bản (desktop, on-premise) thường cần release branch.
| Tiêu chí | Trunk-based | Git Flow |
|---|---|---|
| Nhánh sống bao lâu | Vài giờ đến 2 ngày | Vài tuần |
| Ai deploy | Mỗi merge vào main |
Theo release branch |
| Xung đột | Nhỏ, xuất hiện sớm | Lớn, dồn cuối chu kỳ |
| Phù hợp khi | Web/API, CI/CD, feature flag | Nhiều phiên bản song song |
| Cần gì | Test tự động đủ nhanh, feature flag | Quy trình cherry-pick kỷ luật |
Điều cốt lõi không phải tên mô hình mà là tuổi thọ nhánh. Nhánh sống càng lâu, chi phí merge càng lớn theo cấp số nhân vì số file chạm nhau tăng. Nếu một feature không xong trong hai ngày, tách nó thành nhiều PR nhỏ hoặc giấu sau feature flag thay vì giữ một nhánh mở.
Đặt tên nhánh theo việc, không theo người: feat/order-export, fix/checkout-401, chore/bump-efcore. Tên nhánh không cần số ticket nếu tracker của bạn đã liên kết tự động, nhưng phải đủ để đọc log.
.gitignore: thứ đầu tiên phải đúng
Với .NET, danh sách bắt buộc gần như cố định. Bắt đầu bằng template của SDK rồi thêm phần của team:
dotnet new gitignore
# Build output
[Bb]in/
[Oo]bj/
artifacts/
# IDE và cấu hình cá nhân
.vs/
.idea/
*.user
*.suo
*.userosscache
# Test và coverage
TestResults/
*.trx
coverage*.json
coverage*.xml
# Secret cục bộ
secrets.json
*.pfx
appsettings.*.local.json
Điểm dễ bỏ sót: *.user chứa đường dẫn máy cá nhân và cấu hình IIS Express; .vs/ chứa cache của Roslyn; secrets.json là file mà dotnet user-secrets ghi ra ngoài thư mục project (nhưng nhiều team vẫn copy vào repo).
Vì sao commit obj/ lại có hại
Nhiều người nghĩ obj/ chỉ là file tạm, commit cũng “không sao”. Sai ở ba điểm cụ thể:
obj/project.assets.jsonvàobj/*.csproj.nuget.g.propschứa đường dẫn tuyệt đối tới NuGet cache trên máy build. Máy khác đọc file này sẽ restore sai hoặc bỏ qua package mới.obj/Debug/net10.0/*.AssemblyInfo.csđược sinh lại mỗi build từ thuộc tính trong.csproj. Commit nó nghĩa là mỗi lần đổi version hayInternalsVisibleTo, bạn có thêm một file nhiễu trong diff.- Artifact cũ còn trên đĩa sau khi chuyển nhánh làm MSBuild tưởng project đã build xong, dẫn tới lỗi “đã build mà vẫn thiếu type” — kiểu lỗi chỉ tái hiện trên máy người khác.
Nếu đã commit rồi, đừng chỉ thêm vào .gitignore: file vẫn nằm trong lịch sử và vẫn được checkout. Cần git rm -r --cached obj bin rồi commit, và với repo lớn, dọn lịch sử bằng git filter-repo.
Xung đột .csproj và packages.lock.json
.csproj là XML do con người viết, nên xung đột thường chỉ là hai người thêm hai PackageReference khác nhau. Cách xử lý:
- Chấp nhận cả hai dòng, sau đó chạy
dotnet restorevà build lại. Đừng “chọn bên thắng” theo bản năng. - Bật Central Package Management để version nằm một chỗ. Xung đột version trở thành xung đột trong
Directory.Packages.props, dễ thấy hơn nhiều. - Dùng lock file cho ứng dụng deploy:
RestorePackagesWithLockFiletrongDirectory.Build.props, và CI chạydotnet restore --locked-modeđể build thất bại khi lock lệch.
<!-- Directory.Packages.props -->
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="10.0.14" />
<PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.3" />
</ItemGroup>
packages.lock.json được sinh tự động và nên commit, nhưng không nên sửa tay. Khi xung đột, bỏ bản của bạn, chạy dotnet restore để sinh lại, rồi kiểm tra diff — mọi thay đổi phải đến từ thay đổi package có chủ ý.
Cẩn thận với git checkout --ours / --theirs trong lúc rebase: ý nghĩa bị đảo so với merge. Trong rebase, ours là nhánh đích (upstream), theirs là commit của bạn. Đây là lỗi làm mất code phổ biến nhất khi rebase.
Commit message và review
Conventional Commits không phải thủ tục hành chính: nó cho phép sinh changelog và quyết định version tự động. Tối thiểu:
feat(orders): thêm xuất Excel theo bộ lọc
fix(auth): trả 401 thay vì 302 khi token hết hạn
perf(products): bỏ N+1 khi tải ảnh thumbnail
refactor!: đổi tên ITenantContext thành ITenantAccessor
BREAKING CHANGE: DI registration cho ITenantContext đã đổi.
Dòng đầu dưới 72 ký tự, thì hiện tại, không thì quá khứ cũng được miễn là nhất quán trong repo. Phần thân giải thích vì sao, không lặp lại cái gì — diff đã nói cái gì.
Với PR .NET, checklist review hiệu quả nhất là thứ máy không bắt được: migration có tương thích ngược không, async có bị .Result ở đâu không, DI lifetime có bị captive dependency không, và endpoint mới có cần authorization policy riêng không. Giữ PR dưới khoảng 400 dòng thay đổi; trên mức đó, review chất lượng tụt rõ rệt.
Công cụ Git nên dùng hằng ngày
git worktree: hai nhánh, hai thư mục
Khi đang giữa feature mà cần hotfix trên main, git stash là cách tệ: build state, IDE index và terminal đều bị đổi. Worktree cho bạn thư mục thứ hai trỏ vào cùng repo:
git worktree add ../shop-hotfix origin/main
cd ../shop-hotfix
# sửa, test, commit, push như bình thường
git worktree remove ../shop-hotfix
Mỗi worktree có working directory riêng nhưng dùng chung object database, nên không clone lại và không tốn dung lượng gấp đôi. Đây cũng là cách chạy build cho hai nhánh song song mà không đánh nhau qua obj/.
git bisect: tìm commit gây lỗi bằng test
git bisect start
git bisect bad HEAD
git bisect good v1.4.0
git bisect run dotnet test tests/Shop.Tests/Shop.Tests.csproj --filter "FullyQualifiedName~OrderExport"
git bisect reset
Với khoảng 100 commit, bisect cần khoảng 7 lần build. Điều kiện là test phải ổn định — test flaky sẽ chỉ bạn tới sai commit. Nếu bước nào không build được, trả mã 125 để bisect bỏ qua commit đó thay vì dừng.
git rerere và bảo trì repo
git config rerere.enabled true
git maintenance start
rerere ghi lại cách bạn giải xung đột và tự áp dụng khi gặp lại cùng xung đột — hữu ích khi rebase nhánh dài ngày nhiều lần. git maintenance start đặt lịch gc, commit-graph và prefetch, giúp git log và status vẫn nhanh trên repo vài nghìn commit.
Secret trong repo: chặn trước, dọn sau
Connection string, API key, chứng chỉ .pfx là những thứ xuất hiện trong repo .NET thường xuyên nhất. Nguyên tắc: dev dùng dotnet user-secrets, CI dùng biến môi trường hoặc OIDC, production dùng Key Vault/secret manager của hạ tầng.
dotnet user-secrets init --project src/Shop.Api
dotnet user-secrets set "ConnectionStrings:Shop" "Server=.;Database=Shop;..." --project src/Shop.Api
Chặn ở máy dev và ở CI bằng scanner, đừng dựa vào việc review bằng mắt:
gitleaks detect --source . --redact
gitleaks protect --staged # pre-commit hook
trufflehog git file://. --only-verified
Nếu secret đã vào lịch sử, thứ tự đúng là: xoay credential trước, rồi mới dọn lịch sử bằng git filter-repo --path secrets.json --invert-paths, sau đó force-push và thông báo cho team. Dọn lịch sử mà không xoay key chỉ là che dấu vết — key vẫn nằm trong fork, trong cache của CI, trong bản clone của ai đó.
Bật push protection của host nếu có. GitHub và GitLab đều quét được mẫu credential phổ biến; Azure DevOps cần extension hoặc pipeline task riêng, nên đừng giả định nó có sẵn.
Host: GitHub, GitLab hay Azure DevOps?
Cả ba đều là Git thật, khác biệt nằm ở phần quanh Git: quyền, review, pipeline, tích hợp identity.
| Nhu cầu | Lựa chọn hợp lý |
|---|---|
| Repo mở, cộng đồng, Actions có sẵn | GitHub |
| Self-host, CI mạnh, quy trình merge request chặt | GitLab |
| Team đã dùng Microsoft Entra ID, board, pipeline .NET | Azure DevOps |
Bất kể host nào, bốn thiết lập nên bật ngay từ đầu: bảo vệ nhánh chính (không push trực tiếp), bắt buộc PR review tối thiểu một người, bắt buộc CI xanh trước khi merge, và tắt force-push trên nhánh chính. Với .NET, thêm một required check chạy dotnet test và một check chạy dotnet format --verify-no-changes để giữ format ổn định.
Sai lầm thường gặp
- Commit
bin/để “deploy nhanh”. Binary trong Git không diff được, phình repo vĩnh viễn, và lần sau không ai biết binary đó build từ commit nào. - Force-push lên nhánh chung. Người khác đã pull sẽ có lịch sử không khớp; họ phải reset và có thể mất commit. Chỉ force-push nhánh cá nhân, và dùng
--force-with-lease. - Merge
mainvào feature mỗi ngày. Tạo merge commit nhiễu; rebase lênmaingiữ lịch sử phẳng và xung đột vẫn được xử lý từng bước. - Store credential dạng plaintext. Dùng credential helper của OS hoặc SSH key;
git config credential.helper storeghi token ra file không mã hóa. - Để nhánh feature sống quá lâu. Không có gì trong Git cứu được một nhánh 3 tuần; feature flag và PR nhỏ là giải pháp ở tầng quy trình.
Checklist cho repo .NET mới
dotnet new gitignore, thêm.vs/,*.user,secrets.json; commit ngay trong commit đầu tiên.- Thêm
global.jsonghim SDK10.0.100vớirollForward: latestFeature. - Bật
Directory.Packages.propsvàRestorePackagesWithLockFilenếu có deploy production. - Đặt
pull.rebase=true,merge.conflictStyle=zdiff3,rerere.enabled=true— một lần cho mỗi máy. - Bật branch protection + required CI check trên
main. - Cài gitleaks ở pre-commit và trong pipeline.
Bước tiếp theo trong lộ trình là đưa repo đó vào CI thật: xem GitHub Actions cho ASP.NET Core. Nếu bạn còn đang chuẩn hóa lệnh chạy local, bài Làm chủ .NET CLI đi trước bài này. Và nếu bạn cần nhìn lại toàn bộ thứ tự các chặng, ASP.NET Core Roadmap là điểm xuất phát.



