Spaces:

Zoey7Web
/

Wellfound

Runtime error

App Files Files Community

Wellfound / GITHUB_UPLOAD_GUIDE.md

Zoey7Web

Upload 21 files

28291d7 verified about 1 month ago

preview code

Raw

History Blame Contribute Delete

14.5 kB

GitHub 项目上传完整指南

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

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

1.1 安装 Git

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

验证安装：

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

1.2 配置用户名和邮箱

# 全局配置（所有仓库生效）
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 记录不会关联到你的账号。

查看当前配置：

git config --global --list

1.3 （可选）保存 GitHub 凭据

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

方式 A： credential manager（Windows 推荐）

# Windows Git 自带，无需额外配置
git config --global credential.helper manager

方式 B：个人访问令牌（PAT）

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate new token，勾选 repo 权限
Push 时密码栏粘贴 token

2. .gitignore 文件配置

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

2.1 通用模板

# ─── 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 如果已经不小心提交了不该提交的文件

# 从 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 完整流程

# 进入项目目录
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（推荐大项目使用）

# 添加核心代码
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:     测试相关

示例：

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 上创建全新的空仓库

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

# 关联远程仓库（二选一）
# 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）：

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

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

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

情况 C：Fork 后关联上游

# 添加上游仓库
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 首次推送

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

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

5.2 后续推送

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

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

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

5.3 处理分支名问题

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

# 查看当前分支
git branch

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

# 然后推送
git push -u origin main

6. 后续更新与同步

6.1 日常工作流

# 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 拉取远程更新

# 获取远程变化（不合并）
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：拉取合并后再推送（推荐）

git pull origin main --rebase
# 如有冲突，解决后
git add .
git rebase --continue
git push

方案 B：强制推送（覆盖远程，慎用！）

# 仅在确认远程内容可以被覆盖时使用
git push origin main --force
# 或更安全的 force-with-lease（只在没有新远程提交时才强制）
git push origin main --force-with-lease

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

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

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

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

# 方法 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 文件太大无法推送

# 错误: 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

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

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

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

7.6 修改最后一次 commit 信息

# 修改 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

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

8.2 生成新的 SSH Key

# 推荐 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 并添加密钥

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

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

8.4 将公钥添加到 GitHub

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

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

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

然后在 GitHub 网页操作：

打开 github.com/settings/keys
点击 "New SSH key"
Title: 随便起个名字，如 "My-PC"
Key type: "Authentication Key"
Key: 粘贴刚才复制的公钥内容
点击 "Add SSH key"

8.5 测试 SSH 连接

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

# 将 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 网页端验证

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

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

9.2 命令行验证

# 查看远程分支
git branch -r

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

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

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

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

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