Git & GitHub cho Business Analyst viết SRS

Tóm tắt

Tài liệu này giải thích Git/GitHub cho Business Analyst không chuyên kỹ thuật, đặc biệt là BA đang làm việc với BA-kit để viết SRS theo module trong dự án nhiều BA.

3 điều BA cần nhớ nhất:

1. Git giống như Google Docs có lịch sử phiên bản — mỗi lần "save" (commit) là một bản chụp; mỗi BA làm trên "bản sao" (branch) riêng
2. Luôn tạo branch riêng cho module của mình — không bao giờ sửa trực tiếp main
3. Pull Request = gửi bài cho Lead BA duyệt — trước khi nhập vào bản chính

Git là gì? Tại sao BA cần biết?

Hình dung kiến trúc Git + GitHub:

Mỗi BA clone repo về máy → tạo branch riêng → viết → push lên GitHub → tạo PR → Lead BA review → merge vào main.

Git là công cụ theo dõi thay đổi của file văn bản (như .md). Nó ghi lại ai sửa cái gì, khi nào, và cho phép quay lại phiên bản cũ.

GitHub là nơi lưu trữ các "kho chứa" Git trên mạng, để nhiều BA cùng làm việc.

So sánh với đời thường

Cài đặt GitHub CLI (gh) — là có tất cả

Chỉ cần cài gh (GitHub CLI) là đủ. gh là công cụ dòng lệnh chính thức từ GitHub. Khi cài gh, lệnh git cũng sẽ có sẵn (hoặc được cài kèm tự động trên macOS/Linux). Không cần cài riêng git-scm.com.

Sau khi cài xong, bạn có thể dùng cả 2:

• git clone, git pull, git commit, git push... — thao tác với repository
• gh pr create, gh auth login... — thao tác với GitHub (PR, issue, review)

Kiểm tra đã cài chưa?

Mở Terminal (macOS/Linux) hoặc Command Prompt / PowerShell (Windows), gõ:

git --version        # Nếu ra kết quả như "git version 2.47.0" → đã có
gh --version         # Nếu ra kết quả như "gh version 2.60.0" → đã có

Nếu báo command not found (macOS/Linux) hoặc 'gh' is not recognized... (Windows) → chưa cài, làm theo hướng dẫn bên dưới.

Cài gh

macOS

brew install gh

brew install gh sẽ tự động cài kèm git nếu máy chưa có. Một lệnh, đủ cả 2.

Linux (Ubuntu/Debian)

(type -p wget >/dev/null || sudo apt install wget -y) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

apt install gh sẽ tự động cài kèm git nếu máy chưa có.

Linux (Fedora/RHEL)

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh

Windows

# Trong PowerShell (chạy với quyền Admin) — cài cả gh và git:
winget install --id GitHub.cli
winget install --id Git.Git

Trên Windows, gh và git là 2 gói riêng, cần cài cả 2. Sau khi cài Git.Git, mở Git Bash (được cài kèm) thay vì Command Prompt để dùng — Git Bash đã được cấu hình sẵn PATH.

Chú ý khi cài Git.Git trên Windows: Tại bước "Adjusting your PATH environment", chọn "Git from the command line and also from 3rd-party software" để có thể gọi git từ Command Prompt và PowerShell nếu cần.

Đăng nhập GitHub CLI

Sau khi cài gh, đăng nhập 1 lần:

gh auth login

Chọn:

1. GitHub.com (không phải GitHub Enterprise)
2. HTTPS (khuyên dùng cho BA)
3. Login with a web browser → mở trình duyệt → nhập mã hiển thị trên terminal

Sau khi đăng nhập, kiểm tra:

gh auth status
# Kết quả: ✓ Logged in to github.com as <tên-tài-khoản>

PATH — Đảm bảo gọi được git và gh từ mọi nơi

PATH là danh sách thư mục mà hệ điều hành tìm khi bạn gõ lệnh trong terminal. Nếu git hoặc gh không nằm trong PATH, terminal sẽ báo command not found.

macOS & Linux

Git và gh thường tự động thêm vào PATH khi cài qua Homebrew hoặc apt/dnf. Kiểm tra:

which git       # Kết quả ví dụ: /opt/homebrew/bin/git  hoặc  /usr/bin/git
which gh        # Kết quả ví dụ: /opt/homebrew/bin/gh   hoặc  /usr/bin/gh

Nếu which trả về đường dẫn → đã trong PATH, không cần làm gì thêm.

Nếu which báo not found nhưng bạn đã cài rồi → cần thêm vào PATH thủ công. Thêm dòng sau vào cuối file ~/.zshrc (macOS mặc định) hoặc ~/.bashrc (Linux):

# Nếu cài qua Homebrew (macOS Apple Silicon):
export PATH="/opt/homebrew/bin:$PATH"

# Nếu cài qua Homebrew (macOS Intel):
export PATH="/usr/local/bin:$PATH"

Sau đó chạy source ~/.zshrc (hoặc source ~/.bashrc) để áp dụng, hoặc đóng mở lại terminal.

Windows

Khi cài Git bằng installer, chọn "Git from the command line and also from 3rd-party software" — Git sẽ tự thêm vào PATH.

Nếu vẫn không gọi được, kiểm tra và thêm thủ công:

1. Mở Start → gõ "Edit environment variables" → Enter
2. Trong cửa sổ System Properties → nhấn Environment Variables...
3. Mục System variables → chọn Path → Edit
4. Kiểm tra đã có các dòng này chưa:
   • C:\Program Files\Git\cmd (Git)
   • C:\Program Files\Git\bin (Git Bash)
   • %USERPROFILE%\AppData\Local\Programs\GitHub CLI\ (gh — nếu cài qua winget)
5. Nếu thiếu → nhấn New → thêm đường dẫn tương ứng → OK
6. Đóng mở lại Command Prompt/PowerShell để áp dụng

Lưu ý cho người dùng Windows: Nếu cài Git mà vẫn gặp lỗi 'git' is not recognized, thử mở Git Bash (được cài kèm với Git) thay vì Command Prompt — Git Bash đã được cấu hình sẵn PATH.

Các lệnh Git cơ bản — giải thích bằng ví dụ đời thường

0. git branch / git status — "Tôi đang đứng ở đâu? Tạo branch mới thế nào?"

git branch               # Liệt kê tất cả branch, đánh dấu * branch hiện tại
git branch <tên-branch>  # Tạo branch mới (nhưng chưa chuyển sang)
git status               # Xem branch hiện tại + file đã sửa

Ví dụ: Bạn bước vào văn phòng, nhìn quanh xem mình đang đứng ở bàn nào (branch nào), trên bàn có những tờ giấy gì đang dang dở (file đã sửa).

Kết quả git branch:                    Kết quả git status:

* 03_modules/thanh-toan              Đang ở branch: 03_modules/thanh-toan
  main                               Đã sửa:
  03_modules/xac-thuc                  srs.md (chưa commit)
                                       screens/SCR-10.md (chưa commit)
  * = branch hiện tại                 File mới:
                                       screens/SCR-11.md (chưa track)

So sánh:

Tạo branch + chuyển sang ngay (cách BA hay dùng nhất):

Có 2 cách cùng kết quả:

# Cách truyền thống (dùng đã lâu, vẫn phổ biến):
git checkout -b 03_modules/payment

# Cách hiện đại (Git 2.23+, trực quan hơn):
git switch -c 03_modules/payment

Mẹo: Nếu Git của bạn đời mới (từ 2019 trở đi), dùng git switch -c cho dễ nhớ: switch = chuyển, -c = create. Còn không thì git checkout -b vẫn OK — cả 2 đều ra cùng kết quả.

Ví dụ tạo branch mới:

# Bước 1: Đảm bảo đang ở main và có code mới nhất
git checkout main
git pull origin main

# Bước 2: Tạo branch mới cho module của bạn
git switch -c 03_modules/payment

# Bước 3: Kiểm tra đã đứng đúng branch chưa
git branch
# Kết quả:
#   main
# * 03_modules/payment    ← dấu * xác nhận bạn đang ở branch mới

Khi dùng: LIÊN TỤC. Trước mỗi lần commit, trước khi push, trước khi chuyển branch. Đây là lệnh an toàn nhất — nó không thay đổi gì, chỉ hiển thị thông tin.

Ví dụ tai nạn vì không kiểm tra branch:

Bạn tưởng mình đang ở branch 03_modules/thanh-toan
Nhưng thực ra đang ở main
→ Viết cả buổi sáng, commit vào main
→ Lead BA: "Sao em commit thẳng vào main?!"
→ Mất thời gian gỡ rối

Cách phòng tránh: Luôn gõ git branch hoặc git status trước khi bắt đầu viết.

1. git clone — "Cho tôi mượn 1 bản photo toàn bộ tủ hồ sơ"

git clone https://github.com/company/srs-project.git

Ví dụ: Bạn mới vào dự án. Bạn cần toàn bộ hồ sơ SRS về máy mình để làm việc. clone = photo toàn bộ tủ hồ sơ về bàn làm việc của bạn.

Khi dùng: Lần đầu tiên tham gia dự án.

2. git pull — "Có gì mới trong tủ không? Tôi lấy về"

git pull origin main

Ví dụ: Sáng thứ Hai, bạn mở tủ hồ sơ ra xem có ai thêm gì mới không. pull = lấy tất cả bản cập nhật mới nhất từ tủ chung về bàn mình.

Khi dùng: Mỗi sáng trước khi bắt đầu làm việc. Trước khi tạo branch mới. Trước khi push.

3. git checkout -b — "Tôi mượn 1 bản photo phần payment để ghi chú riêng"

git checkout -b 03_modules/payment

Ví dụ: Bạn được giao viết SRS cho module Payment. Bạn photo riêng phần đó ra, ghi chú lung tung cũng không ảnh hưởng bản gốc trong tủ.

Khi dùng: Mỗi khi bắt đầu viết 1 module SRS mới.

main ---*---*---*---*---*---*---*--->
         \
03_modules/payment --- commit1 --- commit2 --- ...

4. git add + git commit — "Tôi ghi chép xong trang này, ký tên vào"

git add 03_modules/payment/srs.md
git commit -m "docs(payment): thêm màn hình thanh toán"

Ví dụ: Bạn viết xong phần "Màn hình thanh toán" trong SRS. Bạn đánh dấu trang đó, ghi ngày tháng + nội dung đã làm, ký tên. commit = bản ghi có chữ ký của bạn.

Cấu trúc commit message cho BA:

docs(<module>): <mô tả ngắn gọn>

- Thêm màn hình SCR-05
- Sửa Rule Code CR-VAL-03

Khi dùng: Sau mỗi lần hoàn thành 1 phần logic (1 màn hình, 1 use case, 1 nhóm rule). KHÔNG đợi viết xong cả module mới commit.

5. git push — "Tôi gửi bản ghi chú lên tủ chung"

git push origin 03_modules/payment

Ví dụ: Bạn đã ghi chép xong, giờ gửi bản photo đã ghi chú lên tủ chung để Lead BA xem.

Khi dùng: Cuối ngày làm việc, hoặc khi hoàn thành 1 phần quan trọng cần Lead BA review gấp.

6. Pull Request (PR) — giao diện GitHub

Đây không phải lệnh Git, mà là thao tác trên giao diện GitHub. Sau khi push, bạn lên GitHub tạo PR.

Ví dụ một Pull Request trên GitHub:

Cách 2: Dùng gh CLI (tạo PR ngay từ terminal, không cần mở trình duyệt)

# Cài gh CLI 1 lần (nếu chưa có):
# macOS: brew install gh
# Sau đó đăng nhập: gh auth login

# Tạo PR từ terminal:
gh pr create \
  --title "docs(payment): hoàn thiện SRS module thanh toán" \
  --body "$(cat <<'EOF'
## Mô tả
- Thêm 6 màn hình (SCR-10 đến SCR-15)
- Thêm 3 use case (UC-checkout, UC-refund, UC-receipt)
- CR-VAL-04: quy tắc validate số thẻ

## Checklist
- [x] Đã rebase lên main mới nhất
- [x] Rule Code không trùng module khác
- [ ] Chờ Lead BA review
EOF
)"

Khi dùng: Mỗi khi hoàn thành 1 module SRS, hoặc 1 nhóm màn hình đủ lớn.

7. git rebase — "Tôi cập nhật bản photo của tôi cho khớp với bản gốc mới nhất"

git checkout 03_modules/payment
git rebase main

Ví dụ: Bạn đang viết SRS payment được 3 ngày. Sáng nay Lead BA cập nhật DESIGN.md và backbone.md. Bạn muốn bản photo payment của mình "bắt kịp" những thay đổi đó, như thể bạn bắt đầu viết từ bản mới nhất.

Trước rebase:
  main:    A --- B --- C
                \
  payment:       D --- E

Sau rebase (lịch sử thẳng hàng):
  main:    A --- B --- C
                      \
  payment:             D' --- E'

So sánh merge vs rebase:

MERGE (an toàn, dễ hiểu)            REBASE (sạch sẽ, lịch sử thẳng)

A --- B --- C --- M                  A --- B --- C --- D' --- E'
      \         /                        (lịch sử thẳng 1 hàng)
       D ----- E

Có merge commit đánh dấu             Không có merge commit
Giữ nguyên lịch sử thật              Viết lại lịch sử (sạch hơn)

Ví dụ: Sáp nhập 2 tập hồ sơ         Ví dụ: Tháo ghim, chèn trang mới
vào 1, để lại dấu vết               vào đúng vị trí, như thể nó
                                     luôn ở đó từ đầu

Khi dùng rebase (cho BA):

• ✅ Branch của riêng bạn, chưa ai khác đụng vào
• ✅ Trước khi tạo PR, để lịch sử gọn gàng
• ❌ KHÔNG BAO GIỜ rebase branch main hoặc branch của BA khác

8. git push --force-with-lease — "Gửi lại bản đã sửa, nhưng kiểm tra xem có ai gửi đè không"

git push --force-with-lease origin 03_modules/payment

Ví dụ: Sau khi rebase, lịch sử branch của bạn đã thay đổi. GitHub từ chối nhận vì "lịch sử không khớp". Bạn cần gửi phiên bản mới, nhưng phải kiểm tra xem có ai đã push lên branch của bạn không.

• --force-with-lease: "Tôi sẽ đè lên bản cũ, nhưng chỉ khi không có ai khác đã gửi gì mới lên"
• --force (hoặc -f): CỰC KỲ NGUY HIỂM — "ĐÈ LÊN TẤT CẢ! Không cần kiểm tra gì hết!"

9. git status — "Tôi đã sửa những gì rồi nhỉ?"

git status

Ví dụ: Nhìn xuống bàn làm việc xem có những tờ giấy nào đã ghi chú, tờ nào chưa ký tên.

Khi dùng: Luôn luôn, trước mỗi lần commit. Giúp bạn không bỏ sót file.

10. git log --oneline — "Lịch sử tôi đã làm gì?"

git log --oneline -10

Ví dụ: Lật lại sổ nhật ký làm việc, xem 10 mục gần nhất.

11. git stash — "Tạm cất đống giấy tờ đang dở để làm việc gấp"

git stash

Ví dụ: Bạn đang viết dở màn hình SCR-12 thì Lead BA bảo sửa gấp SCR-05. Bạn "cất tạm" đống đang viết vào ngăn kéo, sửa SCR-05 xong thì lấy ra làm tiếp.

git stash               # Cất đi
# ... làm việc gấp ...
git stash pop           # Lấy ra làm tiếp

12. git diff — "Tôi đã sửa những dòng nào?"

git diff

Ví dụ: So sánh 2 bản photo — bản cũ và bản bạn vừa ghi chú — để thấy từng dòng thay đổi.

Sơ đồ luồng làm việc

Luồng làm việc hàng ngày của 1 BA

BUỔI SÁNG — lấy code mới nhất:

1. git checkout main
2. git pull origin main
3. git checkout 03_modules/payment — chuyển sang branch module của mình

TRONG NGÀY — chu kỳ "viết → lưu" (lặp lại nhiều lần):

1. Viết SRS (srs.md, screens/*.md, usecases/*.md)
2. git status — kiểm tra đã sửa những file nào
3. git add <file> — chọn file để lưu
4. git commit -m "docs(x): mô tả" — ký tên

CUỐI NGÀY — đẩy lên GitHub:

1. git pull --rebase origin main — đồng bộ với main
2. git push origin 03_modules/payment — (nếu đã rebase: thêm --force-with-lease)
3. Khi hoàn thành module: lên GitHub tạo Pull Request

Luồng phối hợp nhiều BA

Tuần 1-2: Backbone (Lead BA làm)

• Lead BA tạo: backbone.md, DESIGN.md, shared-shell-contract.md
• Merge vào main

Tuần 3-4: BA A & BA B tách branch từ main

Tuần 5: Lead BA lắp ráp

• Pull tất cả module → Compile 04_compiled/
• Tạo compiled-frd.html, compiled-srs.html
• Cross-artifact consistency check

Best Practice: Git cho BA viết SRS (theo BA-kit)

Dựa trên BA-kit Multi-BA Governance và Module Branch Rules, đây là quy tắc vàng:

Quy tắc 1: Mỗi BA = 1 branch module riêng

✅ Đúng:
   BA A → branch: 03_modules/thanh-toan
   BA B → branch: 03_modules/xac-thuc

❌ Sai:
   BA A và BA B cùng viết chung branch 03_modules/thanh-toan

Lý do: BA-kit quy định mỗi Module BA sở hữu module warm shard của riêng mình. Branch riêng = tránh conflict, rõ trách nhiệm.

Quy tắc 2: Backbone và DESIGN.md là bất khả xâm phạm

• Chỉ Lead BA sửa 02_backbone/backbone.md, shared-shell-contract.md, designs/{slug}/DESIGN.md
• BA module chỉ đọc, không sửa
• Nếu cần thay đổi Portal Matrix hay Navigation Schema → tạo PR ngược về Lead BA

BA Module thấy cần thêm Portal ID mới
  → KHÔNG tự thêm vào backbone
  → Tạo issue báo Lead BA
  → Lead BA cập nhật backbone → BA Module pull về

Quy tắc 3: Rule Code & Message Code phải unique toàn cục

✅ Đúng:
   Module payment: CR-VAL-01, CR-VAL-02, MSG-ERR-01
   Module auth:    CR-VAL-03, CR-VAL-04, MSG-ERR-02

❌ Sai:
   Module payment: CR-VAL-01
   Module auth:    CR-VAL-01  ← TRÙNG!

Cách làm: Trước khi gán code mới, kiểm tra toàn bộ repo xem code đó đã tồn tại chưa:

grep -r "CR-VAL-01" plans/

Quy tắc 4: PR nhỏ, review nhanh

Lý do: PR nhỏ → Lead BA review trong 10 phút. PR to → mất 2 tiếng, dễ bỏ sót.

Quy tắc 5: Trước khi tạo PR, luôn rebase lên main

git checkout 03_modules/thanh-toan
git pull --rebase origin main
# Giải quyết conflict nếu có
git push --force-with-lease origin 03_modules/thanh-toan

Việc này đảm bảo module của bạn tương thích với mọi thay đổi mới nhất từ Lead BA và BA khác.

Quy tắc 6: Commit message theo chuẩn

docs(payment): thêm màn hình thanh toán thẻ (SCR-10)

- SCR-10: Màn hình nhập thông tin thẻ
- UC-checkout: Use case thanh toán
- CR-VAL-04: Quy tắc validate số thẻ (16 chữ số)
- MSG-ERR-03: Thông báo lỗi thẻ không hợp lệ

Refs: backbone.md#Portal-Matrix

Quy tắc 7: Conflict giải quyết bình tĩnh

Tình huống: BA A sửa CR-VAL-03 trong payment, BA B cũng sửa CR-VAL-03 trong auth

     → Git báo CONFLICT khi merge
     → KHÔNG tự ý chọn bản nào
     → Báo Lead BA → Lead BA phân xử → 1 người đổi code

Tình huống thường gặp & cách xử lý

Tình huống 1: "Tôi quên pull sáng nay, giờ push bị từ chối"

# Git báo:
# ! [rejected]  03_modules/payment -> 03_modules/payment (non-fast-forward)

# Xử lý:
git pull --rebase origin main
# Giải quyết conflict (nếu có)
git push origin 03_modules/payment

Tình huống 2: "Tôi commit nhầm vào main!"

# Đừng hoảng sợ! Chưa push thì cứu được

# Lưu commit đang bị kẹt:
git log --oneline -1    # Ghi nhớ commit hash (vd: abc1234)

# Quay về branch của mình:
git checkout 03_modules/payment

# Mang commit theo:
git cherry-pick abc1234

# Về main xóa commit nhầm:
git checkout main
git reset --hard HEAD~1

Tình huống 3: "Tôi cần biết ai đã sửa dòng này trong SRS"

git blame plans/project-2026/03_modules/auth/srs.md

Kết quả hiển thị từng dòng + ai sửa + commit nào + ngày nào. Giống như hỏi "Ai đã viết dòng này trong hồ sơ?"

Tình huống 4: "Tôi cần quay lại phiên bản SRS tuần trước"

# Xem lịch sử:
git log --oneline 03_modules/payment/srs.md

# Xem nội dung cũ (không sửa gì):
git show <commit-hash>:03_modules/payment/srs.md

# Khôi phục file về phiên bản cũ:
git checkout <commit-hash> -- 03_modules/payment/srs.md

Bộ lệnh Git cho BA (cheat sheet)

Khởi động dự án (làm 1 lần)

git clone <url-repo>                  # Tải toàn bộ dự án về máy
cd <thư-mục-dự-án>                    # Vào thư mục dự án

Mỗi sáng trước khi làm

git branch                            # Kiểm tra đang ở branch nào (luôn làm đầu tiên!)
git checkout main                     # Về branch chính
git pull origin main                  # Lấy bản mới nhất
git checkout 03_modules/<tên-module>  # Quay lại branch module của mình
git pull --rebase origin main         # Kéo cập nhật từ main vào branch mình

Bắt đầu module mới (làm 1 lần cho mỗi module)

git checkout -b 03_modules/<tên-module>   # Tạo branch riêng

Trong ngày — chu kỳ "viết → lưu" (lặp lại nhiều lần)

# ... viết SRS ...
git branch                                    # Luôn kiểm tra: đang ở đúng branch chưa?
git status                                    # Xem đã sửa những file nào
git add <đường-dẫn-file>                      # Chọn file muốn lưu
git commit -m "docs(<module>): <mô tả>"       # Lưu + ký tên

Cuối ngày — gửi lên GitHub

git pull --rebase origin main                 # Đồng bộ với main
git push origin 03_modules/<tên-module>       # Gửi lên GitHub

Khi hoàn thành module — tạo PR

git pull --rebase origin main                 # Đồng bộ lần cuối
git push --force-with-lease origin 03_modules/<tên-module>
# Sau đó lên GitHub → New Pull Request

Cứu nguy

git branch                          # "Tôi đang ở branch nào?" (dùng đầu tiên khi hoảng loạn)
git status                          # "Tôi đã sửa gì, đang ở đâu?"
git stash                           # Cất tạm việc đang dở
git stash pop                       # Lấy việc đã cất ra làm tiếp
git log --oneline -10               # Xem 10 thay đổi gần nhất
git diff                            # Xem chi tiết từng dòng thay đổi
git checkout -- <file>              # Hủy thay đổi chưa commit
git blame <file>                    # Ai đã sửa dòng này?

Tài liệu tham khảo

• Atlassian: Merging vs. Rebasing — giải thích merge vs rebase chi tiết
• GitHub Flow — quy trình làm việc chính thức từ GitHub
• Conventional Commits — chuẩn commit message
• Dev.to: Best Workflow for Collaborating on a Shared GitHub Repository
• Scientyfic World: Version Control and Documentation Collaboration — docs-as-code workflow cho technical writer
• BA-kit rules: ba-workflow.md → Multi-BA Governance & Module Branch Rules
• BA-kit rules: ba-quality-standards.md → Cross-Module Consistency

Tiếp theo

• Làm việc nhóm với BA-kit — collaboration workflow qua BA-kit
• Xử lý thay đổi cho BA team — 5 tình huống thường gặp khi dự án đang chạy