| # 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` 查看结果。 |
|
|
