Một dự án Android hiếm khi hỏng vì thiếu tính năng. Nó hỏng vì ai đó commit nhầm local.properties, đẩy cả thư mục build/ lên repo, hoặc force-push lên main và xoá mất công của cả tuần.
Bài này là phần Git thực dụng cho dự án Android 2026: repo đầu tiên, .gitignore, chiến lược nhánh, rebase, conflict trong Gradle, tag và versionCode, secret, Git LFS.
Mục lục
Cập nhật 2026: Git cho Android đã ổn định
- Git không đổi lớn.
git switchvàgit restoređã thaygit checkouttừ Git 2.23; dùng cái mới vì nó tách rõ “đổi nhánh” và “bỏ thay đổi”. - GitHub, GitLab hay Bitbucket đều host tốt. Khác biệt thật nằm ở CI, quyền riêng tư và chi phí, không ở Git.
- Android Studio vẫn là client chính: stage theo file hoặc hunk, rebase, conflict resolver ba khung. CLI vẫn cần cho CI.
- Toolchain 2026 (AGP 9.5, Gradle 9.9, Kotlin 2.4.21): commit
gradle/wrapper/,libs.versions.tomlvà lockfile; tuyệt đối không commitbuild/và.gradle/. - SVN không còn lý do tồn tại trong dự án Android mới: không có nhánh rẻ, không có review gắn với PR, và mọi tool Android đều giả định Git.
Repo đầu tiên: init, clone và .gitignore
git init tạo thư mục .git — toàn bộ lịch sử nằm ở đó, không phải trên mây. git clone kéo cả lịch sử từ server về.
git config --global init.defaultBranch main
cd MyApp
git init
git clone git@github.com:evotek/my-app.git
cd my-app
Việc quan trọng hơn cả là .gitignore. Android Studio sinh sẵn file khá tốt, nhưng vẫn phải đọc từng dòng: hai lỗi hay gặp nhất — commit local.properties và commit keystore — đều do tin vào file mặc định.
# File: .gitignore
*.iml
.gradle/
build/
local.properties
.idea/*
captures/
.externalNativeBuild/
.cxx/
*.apk
*.aab
*.jks
*.keystore
build/ khớp mọi thư mục tên build ở bất kỳ cấp nào, gồm output module và file KSP sinh ra. .gradle/ là cache tái tạo được. local.properties chứa đường dẫn SDK trên máy bạn và thường cả mật khẩu keystore. *.jks là khoá ký; commit nó nghĩa là trao quyền phát hành app cho bất kỳ ai đọc được repo.
Ngoại lệ cho .idea/. Nếu team dùng chung code style, ignore kiểu .idea/* rồi mở lại !.idea/codeStyles/. Ignore cả thư mục rồi thêm dấu ! không có tác dụng: Git không re-include file khi thư mục cha đã bị loại trừ.
Vòng lặp hằng ngày: add, commit, pull, push
Ba vùng: working directory (file bạn sửa), staging area (sẽ vào commit) và repository (lịch sử đã chốt).
git status
git diff
git add app/src/main/java/.../CheckoutScreen.kt
git add -p # stage từng hunk
git commit -m "feat(checkout): add payment method selector"
git log --oneline --graph --decorate -12
git pull --rebase origin main
git push origin HEAD
Đừng dùng git add . như phản xạ: nó stage cả file rác chưa kịp nhìn — trong dự án Android thường là output build. git add -p chậm hơn ba giây nhưng tạo commit đúng chủ đề.
Thông điệp commit theo Conventional Commits, có scope: feat(checkout): ..., fix(login): ..., chore(deps): bump Gradle to 9.9.0. Dòng đầu dưới 72 ký tự, thì hiện tại hoặc mệnh lệnh — vì git log --oneline là công cụ điều tra khi production có sự cố.
git stash dành cho lúc đang sửa dở và phải đổi nhánh gấp, ví dụ hotfix trên nhánh release:
git stash push -m "wip: checkout validation"
git switch release/1.4
# sửa hotfix, commit, push
git switch feature/checkout-v2
git stash pop
Stash là giải pháp tạm: nó không được backup ở đâu. Thay đổi đáng giữ hơn một ngày thì commit lên nhánh nháp và push.
Chiến lược nhánh: trunk-based hay GitFlow
| Mô hình | Phù hợp khi | Nhánh điển hình |
|---|---|---|
| Trunk-based | Team nhỏ, CI mạnh, tính năng sau feature flag | main + nhánh sống 1–3 ngày |
| GitFlow | Phát hành theo quý, cần đóng băng bản release, nhiều bên QA | main, develop, release/* |
| Trunk + release branch | App mobile: trunk nhanh, bản đã lên Play vẫn cần vá | main, release/1.4, feature/* |
Với Android, tôi nghiêng về mô hình thứ ba. Bạn không “phát hành lại” được bản đã lên Play: người dùng đã cài, review đã duyệt, versionCode đã tăng. Nhánh release giữ bản đang chờ duyệt ổn định, trong khi main nhận tính năng. GitFlow đầy đủ thường thừa với team dưới mười người; trunk-based thuần thiếu chỗ cho bản vá khẩn cấp nếu không có feature flag.
git switch main
git pull --rebase
git switch -c feature/checkout-v2
git branch -a
git branch -d feature/checkout-v2
git push origin --delete feature/checkout-v2
Đặt tên nhánh theo việc, không theo người: feature/checkout-v2, fix/crash-on-empty-cart, release/1.4. Nhánh linh-dev sẽ sống mãi vì không ai dám xoá.
Rebase hay merge
Quy tắc ngắn: rebase để làm sạch lịch sử nhánh chưa ai dùng chung, merge để ghi nhận hợp nhất trên nhánh đã chia sẻ.
- Rebase feature lên
maintrước khi mở PR: commit thành một đường thẳng, review từng commit dễ hơn, không có “Merge main into feature” rác. - Merge khi vào
mainqua PR: merge commit đánh dấu thời điểm tính năng hoàn thành mà không viết lại lịch sử nhánh chung. - Không rebase nhánh người khác đang dùng. Rebase tạo commit mới với hash mới; người kia pull sẽ thấy lịch sử khác và sinh conflict không đáng có.
git switch feature/checkout-v2
git fetch origin
git rebase origin/main
# xử lý conflict, rồi:
git add app/src/main/java/.../CartRepository.kt
git rebase --continue
git push --force-with-lease origin feature/checkout-v2
--force-with-lease từ chối push nếu remote có commit mới hơn lần fetch cuối của bạn — nó chặn việc ghi đè commit đồng nghiệp vừa push. Trên main và release/* thì đừng force-push kể cả với lease: bật protected branch để server từ chối thay bạn.
Xử lý conflict trong file Gradle
Conflict xảy ra khi hai nhánh sửa cùng vùng của một file. Trong dự án Android, 90% conflict tập trung ở libs.versions.toml, build.gradle.kts và lockfile — khó hơn conflict Kotlin vì cả hai bên đều đúng về cú pháp.
Ví dụ conflict trong version catalog sau khi hai người cùng bump Kotlin:
[versions]
<<<<<<< HEAD
kotlin = "2.4.21"
=======
kotlin = "2.4.20"
>>>>>>> feature/checkout-v2
Cách xử lý có kỷ luật: chọn một phiên bản (thường bản mới hơn, nhưng phải kiểm tra AGP 9.5 và Compose compiler có hỗ trợ), xoá toàn bộ marker, chạy ./gradlew :app:assembleDebug để chắc dependency resolve, rồi git add và git commit hoặc git rebase --continue. Marker còn sót khiến Gradle báo “Unexpected tokens”.
git status # file nào "both modified"
git diff --check # phát hiện marker còn sót
git checkout --theirs gradle/libs.versions.toml # bản của commit đang rebase
git checkout --ours gradle/libs.versions.toml # bản của nhánh đích
Cẩn thận với --ours/--theirs khi rebase. Lúc rebase, “ours” là nhánh bạn rebase lên, “theirs” là commit của bạn — ngược với trực giác và ngược với lúc merge. Không chắc thì đọc mô tả trong git status.
Lockfile thì đừng sửa tay. gradle.lockfile là kết quả sinh ra, không phải nguồn. Khi conflict, chọn một bên bất kỳ rồi để Gradle tính lại bằng ./gradlew dependencies --write-locks.
Với build.gradle.kts, conflict thường ở block dependencies hoặc plugins. Đọc cả hai bên rồi hợp nhất theo ý định: một bên thêm plugin, bên kia đổi version thì kết quả đúng là plugin mới với version mới — điều Git không tự quyết.
Tag, release và semantic versioning
Tag annotated lưu người tạo, ngày và message:
git tag -a v1.4.2 -m "Release 1.4.2: checkout v2, fix empty cart crash"
git push origin v1.4.2 # push đúng tag, đừng dùng --tags mù quáng
git tag -l
git show v1.4.2
git describe --tags # dùng trong CI
Semantic versioning: MAJOR khi phá vỡ tương thích dữ liệu hoặc API công khai, MINOR khi thêm tính năng tương thích ngược, PATCH khi sửa lỗi. Với app Android, versionName là chuỗi người dùng thấy, versionCode là số nguyên Play dùng để so sánh — Play chỉ nhận bản có versionCode lớn hơn, và giá trị này không bao giờ được tái sử dụng.
// File: app/build.gradle.kts
val major = 1
val minor = 4
val patch = 2
android {
compileSdk = 36
defaultConfig {
// 1.4.2 -> 10402; giới hạn versionCode của Google Play là 2,100,000,000
versionCode = major * 10000 + minor * 100 + patch
versionName = "$major.$minor.$patch"
minSdk = 24
targetSdk = 36
}
}
Cách đánh số này giới hạn patch và minor ở 99 — đủ cho hầu hết app. Điều bắt buộc chỉ là tính đơn điệu tăng; một versionCode dùng lại sẽ khiến bản cập nhật không bao giờ đến được người dùng.
Tag là đầu vào của CI: pipeline nghe v*, đọc git describe --tags, build AAB, ký và upload.
Secret: local.properties, keystore, google-services.json
| File | Chứa gì | Cách xử lý |
|---|---|---|
local.properties |
Đường dẫn SDK, đôi khi mật khẩu keystore | Ignore; CI sinh từ biến môi trường |
*.jks, *.keystore |
Khoá ký release, có thể phát hành app thay bạn | Không bao giờ commit; CI giải mã từ secret |
google-services.json |
Cấu hình Firebase: project id, API key phía client | Không phải secret server, nhưng tránh repo public |
google-services.json không nguy hiểm như keystore: API key nằm sẵn trong APK. Nhưng nó chứa cấu hình môi trường, dễ build nhầm project Firebase và không nên nằm trong repo public; để CI ghi file từ secret.
# CI runner (Linux)
printf 'sdk.dir=%s\n' "$ANDROID_SDK_ROOT" > local.properties
echo "$KEYSTORE_BASE64" | base64 -d > "$RUNNER_TEMP/release.jks"
./gradlew :app:bundleRelease -Pandroid.injected.signing.store.file="$RUNNER_TEMP/release.jks"
Trong build.gradle.kts, đọc signing config từ biến môi trường (KEYSTORE_PATH, KEYSTORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD) thay vì hard-code, và chỉ áp dụng cho build release.
Nếu keystore đã vào lịch sử Git, đổi mật khẩu chưa đủ — file vẫn nằm trong commit cũ. Gỡ bằng git filter-repo (đừng dùng filter-branch), tạo upload key mới và xin Google reset. Play App Signing giữ app signing key, nên bạn không mất khả năng cập nhật app.
Git LFS cho asset lớn
Git lưu mọi phiên bản của mọi file trong lịch sử. Một video 80 MB đổi ba lần là 240 MB trong repo, và mỗi lần clone đều phải kéo về. Ảnh UI vài chục KB thì không sao; PSD, video onboarding, model ML, bộ font thì nên dùng Git LFS.
git lfs install
git lfs track "*.psd" "*.mp4" "app/src/main/assets/models/*.tflite"
git add .gitattributes
git add app/src/main/assets/models
git commit -m "chore(assets): move onboarding video to LFS"
LFS thay file lớn bằng pointer nhỏ trong Git, nội dung thật nằm ở storage của GitHub/GitLab. Hai điều cần biết: CI phải có LFS, nếu không checkout chỉ lấy pointer và build lỗi khó hiểu; và mỗi nền tảng có quota dung lượng/bandwidth, kiểm tra plan trước khi đẩy vài GB.
Vệ sinh code review cho dự án Android
Review là nơi Git trả công cho bạn. Ba thói quen giữ PR đọc được:
- PR nhỏ. Mục tiêu dưới 300 dòng thay đổi thật, không tính file sinh ra và lockfile. PR 1.200 dòng sẽ được approve cho xong, không phải vì đúng.
- Không commit file sinh ra.
BuildConfig, output KSP,build/,.gradle/,*.imlđều tái tạo được, chỉ làm diff nhiễu và xung đột vô nghĩa. - Không reformat cả file. PR đổi 400 dòng chỉ vì thụt lề sẽ che mất thay đổi thật. Chạy
ktlintFormattrên đúng file bạn sửa, hoặc tách PR format riêng.
Bump dependency để PR riêng; thay đổi UI thì đính screenshot; chạy ./gradlew lint testDebugUnitTest và để CI xanh trước khi request review.
Lỗi thường gặp và cách sửa
- Commit keystore. Hậu quả nặng nhất. Gỡ khỏi lịch sử bằng
git filter-repo, tạo upload key mới, xin reset trên Play Console. - Commit
build/từ lần đầu. Repo phình, diff rác mãi. Sửa: thêm vào.gitignore,git rm -r --cached build .gradle, commit việc gỡ theo dõi. - Force-push lên nhánh chung. Chỉ dùng
--force-with-leasetrên nhánh của bạn; bật protected branch chomain. - CRLF. Windows commit
gradlewvới CRLF làm CI Linux chết ở/usr/bin/env: 'sh\r'. Thêm.gitattributesvới* text=auto eol=lf,gradlew text eol=lf, rồigit add --renormalize .. Giữ quyền thực thi bằnggit update-index --chmod=+x gradlew. - Sửa tay lockfile. Conflict
gradle.lockfilephải để./gradlew dependencies --write-lockssinh lại. - Asset nhị phân lớn. Dùng LFS hoặc Play Asset Delivery; xoá file ở commit mới không xoá nó khỏi lịch sử.
Nhìn về 2027 và checklist
Git sẽ không đổi nhiều trong 2027; thứ đổi là quy trình quanh nó. Trunk-based với nhánh sống ngắn tiếp tục thắng vì CI nhanh hơn và feature flag phổ biến hơn. Secret scanning bật mặc định ở nhiều plan nên commit nhầm khoá sẽ bị cảnh báo sớm — nhưng đừng dựa vào nó.
.gitignorechặnbuild/,.gradle/,local.properties,*.iml,*.jksngay từ commit đầu..gitattributeschuẩn hoá LF, giữgradlewchạy được trên CI Linux.- Nhánh feature sống dưới ba ngày; rebase lên
maintrước khi mở PR. - Keystore và mật khẩu chỉ nằm trong secret của CI.
versionCodetăng đơn điệu, tag annotated mỗi bản release, versionName theo semver.- PR nhỏ, không file sinh ra, không reformat cả file, CI xanh trước khi review.
Đọc tiếp: GitHub, GitLab hay Bitbucket để chọn nơi lưu repo và CI, Gradle là gì để hiểu vì sao wrapper và version catalog phải commit, ký ứng dụng APK/AAB để nối Git với pipeline release, và lộ trình Android để đặt Git vào đúng chặng.



