# GitHub 项目上传完整指南

> 从零开始，将本地项目推送到 GitHub 远程仓库的完整流程。
> 以 AI-Wellfound 项目为例，所有命令均适用。

---

## 目录

1. [前置准备：Git 安装与配置](#1-前置准备git-安装与配置)
2. [.gitignore 文件配置](#2-gitignore-文件配置)
3. [初始化本地仓库与首次提交](#3-初始化本地仓库与首次提交)
4. [关联远程仓库](#4-关联远程仓库)
5. [推送到 GitHub](#5-推送到-github)
6. [后续更新与同步](#6-后续更新与同步)
7. [常见问题处理](#7-常见问题处理)
8. [SSH Key 免密推送配置](#8-ssh-key-免密推送配置)
9. [验证上传结果](#9-验证上传结果)

---

## 1. 前置准备：Git 安装与配置

### 1.1 安装 Git

- **Windows**: 下载 [git-scm.com](https://git-scm.com/download/win)，安装时勾选 "Git Bash Here"
- **macOS**: `brew install git` 或安装 Xcode Command Line Tools
- **Linux**: `sudo apt install git` (Ubuntu/Debian)

验证安装：

```bash
git --version
# 输出示例: git version 2.45.0
```

### 1.2 配置用户名和邮箱

```bash
# 全局配置（所有仓库生效）
git config --global user.name "your_username"
git config --global user.email "your_email@example.com"

# 仅对当前仓库配置（在项目目录下执行）
git config user.name "your_username"
git config user.email "your_email@example.com"
```

> **说明**: `user.name` 填你的 GitHub 用户名或真实姓名均可；`user.email` 必须填写你 GitHub 账号绑定的邮箱，否则 commit 记录不会关联到你的账号。

查看当前配置：

```bash
git config --global --list
```

### 1.3 （可选）保存 GitHub 凭据

避免每次 push 都输入密码。二选一：

**方式 A： credential manager（Windows 推荐）**
```bash
# Windows Git 自带，无需额外配置
git config --global credential.helper manager
```

**方式 B：个人访问令牌（PAT）**
1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token，勾选 `repo` 权限
3. Push 时密码栏粘贴 token

---

## 2. .gitignore 文件配置

`.gitignore` 告诉 Git 哪些文件/目录不要追踪和上传。在项目**根目录**创建此文件。

### 2.1 通用模板

```gitignore
# ─── Python ───
__pycache__/
*.pyc
*.pyo
*.egg-info/
dist/
build/
venv/
.venv/

# ─── Node.js ───
node_modules/
.next/
.nuxt/

# ─── 环境变量（重要：绝不上传！）───
.env
.env.local
.env.production

# ─── IDE ───
.idea/
.vscode/
*.swp
*.swo

# ─── 系统文件 ───
.DS_Store
Thumbs.db
desktop.ini

# ─── 日志 ───
*.log

# ─── 运行时生成的数据 ───
data/uploads/*
data/results/*
data/checkpoints/*
!data/uploads/.gitkeep    # 保留空目录结构
!data/results/.gitkeep
!data/checkpoints/.gitkeep

# ─── 工具私有目录 ───
.workbuddy/
```

### 2.2 语法速查

| 语法 | 含义 | 示例 |
|------|------|------|
| `file.txt` | 忽略所有叫这个名字的文件 | `README.bak` |
| `*.log` | 忽略所有 .log 后缀文件 | `*.pyc` |
| `dir/` | 忽略整个目录 | `node_modules/` |
| `!file` | 取消忽略（例外） | `!.gitkeep` |
| `#` | 注释 | `# 这是注释` |
| `**/cache` | 任意层级下的 cache 目录 | `**/temp` |

### 2.3 如果已经不小心提交了不该提交的文件

```bash
# 从 Git 追踪中移除（但保留本地文件）
git rm -r --cached node_modules/
git rm --cached .env

# 然后提交
git commit -m "chore: remove tracked files that should be ignored"
```

---

## 3. 初始化本地仓库与首次提交

### 3.1 完整流程

```bash
# 进入项目目录
cd D:/Coding/Workbuddy/AI-Wellfound

# 第一步：初始化 Git 仓库（生成 .git 目录）
git init

# 第二步：添加所有文件到暂存区
git add .

# 第三步：查看暂存状态（确认要提交的文件）
git status

# 第四步：提交
git commit -m "feat: initial commit - AI Excel data completion tool"
```

### 3.2 分步 add（推荐大项目使用）

```bash
# 添加核心代码
git add app.py core/ templates/ static/

# 添加配置文件
git add requirements.txt Dockerfile .gitignore

# 添加文档
git add README.md start.bat start.sh

# 查看将要提交的内容
git status

# 提交
git commit -m "feat: initial commit - AI Excel data completion tool"
```

### 3.3 提交信息规范

采用 **Conventional Commits** 格式：

```
<type>(<scope>): <description>

# type 类型：
feat:     新功能
fix:      修复 bug
docs:     文档更新
style:    代码格式（不影响功能）
refactor: 重构（既非新功能也非修 bug）
chore:    构建过程或辅助工具变动
test:     测试相关
```

示例：
```bash
git commit -m "feat: add OpenAI API integration for web scraping"
git commit -m "fix: handle playwright timeout on slow websites"
git commit -m "docs: update README with deployment instructions"
git commit -m "chore: optimize Dockerfile build layers"
```

---

## 4. 关联远程仓库

### 情况 A：在 GitHub 上创建全新的空仓库

1. 打开 [github.com/new](https://github.com/new)
2. 填写仓库信息：
   - **Repository name**: `AI-Wellfound`
   - **Description**: `AI-powered Excel data completion tool for Wellfound`
   - **可见性**: Public（公开）或 Private（私有）
   - **不要勾选** "Add a README file"、"Add .gitignore"、"Choose a license"（本地已有则不勾选，否则会导致冲突）
3. 点击 "Create repository"
4. 创建后，GitHub 会显示仓库地址：

```bash
# 关联远程仓库（二选一）
# HTTPS 方式
git remote add origin https://github.com/your_username/AI-Wellfound.git

# SSH 方式（需先配置 SSH Key，见第 8 节）
git remote add origin git@github.com:your_username/AI-Wellfound.git

# 验证关联
git remote -v
```

### 情况 B：关联已有的远程仓库

如果远程仓库已有内容（如 GitHub 自动生成的 README/LICENSE）：

```bash
# 关联
git remote add origin https://github.com/your_username/AI-Wellfound.git

# 拉取远程内容并合并
git pull origin main --allow-unrelated-histories

# 或如果确定本地内容是最新，强制推送（见第 7 节警告）
```

### 情况 C：Fork 后关联上游

```bash
# 添加上游仓库
git remote add upstream https://github.com/original_owner/repo.git

# 查看所有远程
git remote -v
# origin    https://github.com/your_username/repo.git (fetch)
# origin    https://github.com/your_username/repo.git (push)
# upstream  https://github.com/original_owner/repo.git (fetch)
# upstream  https://github.com/original_owner/repo.git (push)
```

---

## 5. 推送到 GitHub

### 5.1 首次推送

```bash
# 推送到 main 分支并设置上游跟踪
git push -u origin main
```

> `-u` 参数设置上游跟踪，之后直接 `git push` 即可。

### 5.2 后续推送

```bash
# 方式 1：标准推送（已设置 -u 后）
git push

# 方式 2：指定分支
git push origin main

# 方式 3：推送所有本地分支
git push --all
```

### 5.3 处理分支名问题

GitHub 新仓库默认分支可能是 `main` 或 `master`。如果推送时提示分支名不匹配：

```bash
# 查看当前分支
git branch

# 重命名本地分支（如果需要）
git branch -M main

# 然后推送
git push -u origin main
```

---

## 6. 后续更新与同步

### 6.1 日常工作流

```bash
# 1. 修改文件后查看变化
git status
git diff                    # 查看具体改动

# 2. 添加到暂存区
git add .                   # 添加所有改动
git add app.py              # 只添加指定文件

# 3. 提交
git commit -m "feat: add retry logic for API calls"

# 4. 推送
git push
```

### 6.2 拉取远程更新

```bash
# 获取远程变化（不合并）
git fetch origin

# 拉取并合并
git pull origin main

# 拉取时出现冲突 → 手动解决 →
git add .
git commit -m "fix: resolve merge conflict"
git push
```

---

## 7. 常见问题处理

### 7.1 推送被拒绝（远程有本地没有的提交）

```
error: failed to push some refs to 'github.com:...'
hint: Updates were rejected because the remote contains work
```

**方案 A：拉取合并后再推送（推荐）**
```bash
git pull origin main --rebase
# 如有冲突，解决后
git add .
git rebase --continue
git push
```

**方案 B：强制推送（覆盖远程，慎用！）**
```bash
# 仅在确认远程内容可以被覆盖时使用
git push origin main --force
# 或更安全的 force-with-lease（只在没有新远程提交时才强制）
git push origin main --force-with-lease
```

> **警告**: `--force` 会永久删除远程仓库中你本地没有的提交。在团队协作中**绝对不要**使用。个人项目覆盖自己的仓库可以使用 `--force-with-lease`。

### 7.2 远程仓库已有 README 但本地没有

```bash
# 允许合并不相关的历史
git pull origin main --allow-unrelated-histories
# 可能需要处理冲突（编辑冲突文件，解决后）
git add .
git commit -m "merge: merge remote README with local project"
git push
```

### 7.3 推送时要求输入用户名密码

```bash
# 方法 1：使用 HTTPS + Token
# 用户名：GitHub 用户名
# 密码：Personal Access Token（不是登录密码）

# 方法 2：切换到 SSH（推荐，见第 8 节）
git remote set-url origin git@github.com:your_username/AI-Wellfound.git
```

### 7.4 文件太大无法推送

```bash
# 错误: fatal: pack exceeds maximum allowed size

# 方法 1：Git LFS（大文件存储）
git lfs install
git lfs track "*.psd"          # 追踪大文件类型
git add .gitattributes
git add your_large_file.psd
git commit -m "add large file with LFS"
git push

# 方法 2：从历史中彻底删除大文件（bfg 或 git-filter-branch）
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch big_file.dat' \
  --prune-empty --tag-name-filter cat -- --all
```

### 7.5 撤销错误的 commit

```bash
# 撤销最近一次 commit，保留改动在工作区
git reset --soft HEAD~1

# 撤销最近一次 commit，丢弃改动
git reset --hard HEAD~1

# 撤销已 push 的 commit（创建一个新的反向 commit）
git revert <commit-hash>
git push
```

### 7.6 修改最后一次 commit 信息

```bash
# 修改 commit message
git commit --amend -m "new message"

# 追加遗漏的文件到最后一次 commit
git add forgotten_file.py
git commit --amend --no-edit

# 如果已经 push 过了，需要强制推送
git push --force-with-lease
```

---

## 8. SSH Key 免密推送配置

配置 SSH 后，push/pull 时无需输入密码，更安全更方便。

### 8.1 检查是否已有 SSH Key

```bash
ls ~/.ssh/
# 如果看到 id_rsa 和 id_rsa.pub 或 id_ed25519 和 id_ed25519.pub
# 说明已有，跳到 8.4 步
```

### 8.2 生成新的 SSH Key

```bash
# 推荐 Ed25519（更安全、更短）
ssh-keygen -t ed25519 -C "your_email@example.com"

# 如果系统不支持 Ed25519，用 RSA
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```

交互提示：
```
Enter file in which to save the key:    # 回车（使用默认路径）
Enter passphrase:                      # 可回车跳过，也可设置密码
Enter same passphrase again:           # 再次确认
```

### 8.3 启动 ssh-agent 并添加密钥

```bash
# 启动 ssh-agent
eval "$(ssh-agent -s)"

# 添加私钥
ssh-add ~/.ssh/id_ed25519
# 或 RSA
ssh-add ~/.ssh/id_rsa
```

### 8.4 将公钥添加到 GitHub

```bash
# 复制公钥内容
# Windows (Git Bash):
cat ~/.ssh/id_ed25519.pub | clip

# macOS:
cat ~/.ssh/id_ed25519.pub | pbcopy

# Linux:
cat ~/.ssh/id_ed25519.pub
# 手动复制输出的全部内容
```

然后在 GitHub 网页操作：
1. 打开 [github.com/settings/keys](https://github.com/settings/keys)
2. 点击 **"New SSH key"**
3. **Title**: 随便起个名字，如 "My-PC"
4. **Key type**: "Authentication Key"
5. **Key**: 粘贴刚才复制的公钥内容
6. 点击 **"Add SSH key"**

### 8.5 测试 SSH 连接

```bash
ssh -T git@github.com
# 首次连接会提示:
# The authenticity of host 'github.com (140.82.112.3)' can't be established.
# ED25519 key fingerprint is SHA256:xxxxx
# 输入 yes 回车

# 成功提示:
# Hi your_username! You've successfully authenticated, but GitHub does not provide shell access.
```

### 8.6 切换远程仓库为 SSH

```bash
# 将 HTTPS 地址替换为 SSH 地址
git remote set-url origin git@github.com:your_username/AI-Wellfound.git

# 验证
git remote -v
# origin  git@github.com:your_username/AI-Wellfound.git (fetch)
# origin  git@github.com:your_username/AI-Wellfound.git (push)
```

---

## 9. 验证上传结果

### 9.1 网页端验证

1. 打开 `https://github.com/your_username/AI-Wellfound`
2. 确认以下内容：

| 检查项 | 确认方式 |
|--------|---------|
| 文件是否完整 | 查看 Code 标签页，确认所有预期文件都在 |
| .gitignore 生效 | 确认 `__pycache__/`、`.env`、`data/uploads/` 等不在列表中 |
| README 正确显示 | 首页应自动渲染 README.md |
| 分支正确 | 页面左上角显示 `main` 分支 |
| 最新 commit | 右侧显示最新提交信息和时间 |

### 9.2 命令行验证

```bash
# 查看远程分支
git branch -r

# 查看提交历史
git log --oneline -5

# 确认本地与远程同步
git status
# 应显示: Your branch is up to date with 'origin/main'.
```

---

## 附录：AI-Wellfound 项目专用命令速查

以下是针对本项目从零上传到 GitHub 的**完整命令序列**，复制粘贴即可执行：

```bash
# ─── 1. 配置 Git（首次使用）───
git config --global user.name "your_username"
git config --global user.email "your_email@example.com"

# ─── 2. 进入项目目录 ───
cd D:/Coding/Workbuddy/AI-Wellfound

# ─── 3. 初始化仓库 ───
git init

# ─── 4. 验证 .gitignore ───
# （项目已有 .gitignore，无需额外创建）

# ─── 5. 添加所有文件 ───
git add .

# ─── 6. 确认暂存区 ───
git status

# ─── 7. 首次提交 ───
git commit -m "feat: initial commit - AI Excel data completion tool"

# ─── 8. 关联远程仓库（先在 GitHub 网页创建空仓库）───
git remote add origin https://github.com/your_username/AI-Wellfound.git

# ─── 9. 推送 ───
git branch -M main
git push -u origin main
```

完成！打开 `https://github.com/your_username/AI-Wellfound` 查看结果。