---
# System prepended metadata

title: GitHub 建立 Repo ＆ VS Code 提交/推送（Commit / Push）教學

---

# GitHub 建立 Repo ＆ VS Code 提交/推送（Commit / Push）教學

> 目標：你會完成一個完整流程：**GitHub 建 repo → 本機用 VS Code 初始化/連結 → Commit → Push → 後續更新**  
> 適用：Windows / macOS / Linux（介面文字可能略不同，但流程一致）

---

## 0. 事前準備（必做一次）
### A. 安裝 Git
- Windows：建議安裝 Git for Windows（安裝完會附 Git Bash）
- macOS：可用 Homebrew 安裝或使用 Xcode Command Line Tools
- Linux：用套件管理器安裝

安裝完確認：
```bash
git --version
```

### B. 設定 Git 使用者資訊
```bash=
git config --global user.name "你的名字"
git config --global user.email "你的信箱"
```

### C. 登入 GitHub

- VS Code 右下角或 Command Palette（Ctrl+Shift+P / Cmd+Shift+P）
- 搜尋：GitHub: Sign in
- 依提示用瀏覽器登入

> 如果你用 HTTPS 推送，後續會走瀏覽器授權/Token；用 SSH 則要設定 SSH key（進階章節有）。
---

## 1. 在 GitHub 建立 Repo（網頁操作）

1. 打開 GitHub → 左上角 + → New

![image](https://hackmd.io/_uploads/Hy8TtcoI-g.png)

2. 填寫：
    - Repository name：例如 my-project
    - Public / Private：選你要的
3. 初始化選項（建議）：
    - Add a README file（新手建議勾）
    - Add .gitignore（可選，例如 Node / Python）
    - Choose a license（可選）

4. 按 Create repository

![image](https://hackmd.io/_uploads/rkDZ99oL-l.png)


建立完成後，記下 repo URL（通常長這樣）：
- HTTPS：https://github.com/<user>/<repo>.git
- SSH：git@github.com:<user>/<repo>.git
    
![image](https://hackmd.io/_uploads/ByhQ95jI-e.png)

---

## 2. 方式一：你本機已經有專案 → 推到 GitHub
### A. 用 VS Code 打開你的專案資料夾

VS Code → File → Open Folder... → 選專案資料夾

### B. 初始化 Git（如果你還沒 git init）

VS Code 左側 Source Control（版本控制）

若看到「Initialize Repository」→ 按下去

或用終端機：
```bash
git init
```

### C. 加入檔案到暫存區（Stage）

VS Code → Source Control：

在 Changes 區塊按 +（Stage All Changes 或單檔 Stage）

或終端機：
```bash
git add .
```

### D. 建立第一次提交（Commit）

VS Code → Source Control 上方輸入訊息，例如：

init: first commit
然後按 Commit（勾勾圖示）

或終端機：

```bash
git commit -m "init: first commit"
```

### E. 加入遠端 repo（Remote: origin）

回到 GitHub repo 頁面，複製 HTTPS/SSH URL。

終端機（建議最直覺）：

```bash
git remote add origin https://github.com/<user>/<repo>.git
```

確認 remote 有沒有成功：
    
```bash
git remote -v
```

### F. 推送到 GitHub（Push）

第一次推送通常要設定 upstream（主分支可能是 main）：

```bash
git branch -M main
git push -u origin main
```

> -u 會把本機 main 跟遠端 main 綁定，之後只要 git push 就好。

---

## 3. 方式二：GitHub 已有 Repo → 你要下載到本機（Clone）(我常用的方法)

### A. 在 GitHub Repo 頁面按 Code → 複製 URL
    
![image](https://hackmd.io/_uploads/rygv35oLWl.png)
![image](https://hackmd.io/_uploads/BJHp3coIbx.png)

### B. 用 VS Code Clone

1. VS Code → Ctrl+Shift+P / Cmd+Shift+P
2. 輸入：Git: Clone
3. 貼上 URL
![image](https://hackmd.io/_uploads/BysMa5s8-x.png)

4. 選本機資料夾 → 開啟專案

或終端機：
    
```bash
git clone https://github.com/<user>/<repo>.git
cd <repo>
code .
```

---

## 4. 日常開發流程（最常用）

每次改完程式，基本流程就是：

1. 檔案變更

2. Stage（選要提交的檔）

3. Commit

4. Push

VS Code 版：

- Source Control
![image](https://hackmd.io/_uploads/HkBbRcj8We.png)


    - $+$ Stage
    ![image](https://hackmd.io/_uploads/SknXR9iU-l.png)

    - 輸入訊息
    ![image](https://hackmd.io/_uploads/BJ34RqoI-l.png)

    - Commit（勾勾）
    - Push（上方同步/推送按鈕）
    ![image](https://hackmd.io/_uploads/B1a8A5iLbl.png)


終端機版：
```bash
git add .
git commit -m "feat: update something"
git push
```
---
## 5. 常見狀況與排除
### A. 我不知道現在狀態？
```bash=
git status
```

### B. 看提交紀錄
```bash
git log --oneline --decorate --graph
```

### C. Push 被拒絕：遠端有更新（non-fast-forward）

先把遠端拉下來再推：

```bash
git pull --rebase
git push
```

> --rebase 通常比 merge 更乾淨（提交線比較直）。

### D. 我不小心把不該提交的檔加進來（例如 .env）

先把它加入 .gitignore

如果已經被 Git 追蹤過，需要取消追蹤：

```bash
git rm --cached .env
git commit -m "chore: ignore env"
git push
```

---

## 6. 分支（Branch）基本用法（建議至少會）
### A. 建新分支
    
```bash
git checkout -b feature/login
```

### B. 推送分支到 GitHub
```bash
git push -u origin feature/login
```

### C. 切回主分支
```bash
git checkout main
```

---

##7.（進階）HTTPS vs SSH 怎麼選？
HTTPS（windows常用）

- 優點：不太需要額外設定

- 缺點：有時要重新授權（看環境）

SSH（mac/linux常用） - 但如果不是自己電腦建議不要走這個

- 優點：穩定、免反覆輸入密碼/授權

- 缺點：第一次要設 SSH Key

SSH 快速流程（概念版）：

1. 產生 key：
```bash
ssh-keygen
```
 
2. 把 ~/.ssh/id_ed25519.pub 內容貼到 GitHub → SSH keys

3. remote 用 git@github.com:... 形式

---

## 8. Commit 訊息建議格式（好維護）

常用慣例（類似 Conventional Commits）：

- feat: 新功能

- fix: 修 bug

- chore: 雜項（依賴、設定）

- docs: 文件

- refactor: 重構（不改功能）

- test: 測試

例：

- feat: add login page

- fix: handle null token

- docs: update README

---

## 9. 你應該記住的最小指令集

```bash
git status
git add .
git commit -m "message"
git pull --rebase
git push
```

---

## 10. 快速檢查清單

- [ ] GitHub 建 repo

- [ ] 本機專案 git init（或 clone）

- [ ] git add .

- [ ] git commit -m "..."

- [ ] git remote add origin <url>（若 clone 可略）

- [ ] git push -u origin main

- [ ] 後續：改完 → add → commit → push