配置 Git 倉庫

依項目類型以合適配置設 Git 倉庫。

適用時機

• 新項目之版本控制之始
• 為特定語言/框架加 .gitignore
• 設分支保護與慣例
• 配提交鉤子

輸入

• 必要：項目目錄
• 必要：項目類型（R 包、Node.js、Python、通用）
• 選擇性：遠端倉庫 URL
• 選擇性：分支策（基於主幹、Git Flow）
• 選擇性：提交訊息慣例

步驟

步驟一：初始化倉庫

cd /path/to/project
git init
git branch -M main

預期： .git/ 目錄已建。預設分支名為 main。

失敗時： 若 git init 敗，確 Git 已裝（git --version）。若目錄已有 .git/，倉庫已初始化——略此步。

步驟二：建 .gitignore

R 包：

# R artifacts
.Rhistory
.RData
.Rproj.user/
*.Rproj

# Environment (sensitive)
.Renviron

# renv library (machine-specific)
renv/library/
renv/staging/
renv/cache/

# Build artifacts
*.tar.gz
src/*.o
src/*.so
src/*.dll

# Documentation build
docs/
inst/doc/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

Node.js/TypeScript：

node_modules/
dist/
build/
.next/
.env
.env.local
.env.*.local
*.log
npm-debug.log*
.DS_Store
Thumbs.db
.vscode/
.idea/
coverage/

Python：

__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
.eggs/
.venv/
venv/
.env
*.log
.mypy_cache/
.pytest_cache/
htmlcov/
.coverage
.DS_Store
.idea/
.vscode/

預期： .gitignore 已建，含項目類型合適之條目。敏感檔（.Renviron、.env）與生成產物已排除。

失敗時： 若不確該含何條目，用 gitignore.io 或 GitHub 之 .gitignore 模板為起點並依項目調。

步驟三：建首次提交

git add .gitignore
git add .  # Review what's being added first with git status
git commit -m "Initial project setup"

預期： 首次提交已建，含 .gitignore 與初始項目檔。git log 顯一提交。

失敗時： 若 git commit 敗報「nothing to commit」，確檔已以 git add 暫存。若敗報作者身分錯，設 git config user.name 與 git config user.email。

步驟四：連遠端

# Add remote
git remote add origin [email protected]:username/repo.git

# Push
git push -u origin main

預期： 遠端 origin 已配。git remote -v 顯 fetch 與 push URL。首提交已推至遠端。

失敗時： 若推敗報「Permission denied (publickey)」，配 SSH 金鑰（見 setup-wsl-dev-environment）。若遠端已存，以 git remote set-url origin <url> 更。

步驟五：設分支慣例

基於主幹（小團隊推薦）：

• main：生產可用代碼
• 功能分支：feature/description
• 錯誤修復：fix/description

# Create feature branch
git checkout -b feature/add-authentication

# After work is done, merge or create PR
git checkout main
git merge feature/add-authentication

預期： 分支命名慣例已立且已記。團隊成員知每類工作之前綴。

失敗時： 若分支已以不一致之名，以 git branch -m old-name new-name 重命並更任何未結之 PR。

步驟六：配提交慣例

Conventional Commits 格式：

type(scope): description

feat: add user authentication
fix: correct calculation in weighted_mean
docs: update README installation section
test: add edge case tests for parser
refactor: extract helper function
chore: update dependencies

預期： 提交訊息慣例已記且團隊已同意。未來提交循 type: description 格式。

失敗時： 若團隊成員未循慣例，以驗格式之 commit-msg 鉤子強行（見步驟七）。

步驟七：設預提交鉤子（選擇性）

建 .githooks/pre-commit：

#!/bin/bash
# Run linter before commit

# For R packages
if [ -f "DESCRIPTION" ]; then
  Rscript -e "lintr::lint_package()" || exit 1
fi

# For Node.js
if [ -f "package.json" ]; then
  npm run lint || exit 1
fi

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

預期： 預提交鉤子於每 git commit 自動行。Lint 錯阻提交直至修。

失敗時： 若鉤子不行，驗 core.hooksPath 已設（git config core.hooksPath）且鉤子檔可執行（chmod +x）。

步驟八：建 README

# Minimal README
echo "# Project Name" > README.md
echo "" >> README.md
echo "Brief description of the project." >> README.md
git add README.md
git commit -m "Add README"

預期： README.md 已提至倉庫。項目於 GitHub 上有簡約而有資之落地頁。

失敗時： 若 README.md 已存，更之勿覆。R 項目用 usethis::use_readme_md() 取含徽章之模板。

驗證

• .gitignore 排敏感與生成檔
• 追蹤檔中無敏感數據（令牌、密碼）
• 遠端倉庫已連且可達
• 分支命名慣例已記
• 首次提交已淨建

常見陷阱

• 先提交後 .gitignore：先加 .gitignore。已追之檔不受後加條目影響
• 史中之敏感數據：若密碼已提，刪後仍於史。以 git filter-repo 或 BFG 清
• 大二進制檔：勿提大二進制。>1MB 之檔用 Git LFS
• 行尾：Windows/WSL 設 core.autocrlf=input 以防 CRLF/LF 問題

相關技能

• commit-changes - 暫存與提交之工作流
• manage-git-branches - 分支建與慣例
• create-r-package - R 包建時之 Git 設
• setup-wsl-dev-environment - Git 裝與 SSH 金鑰
• create-github-release - 自倉庫建發行版
• security-audit-codebase - 查已提之秘密