垦荒学园
  • 中文

      • Git GitHub操作

      GitHub 是世界上最大的代码托管平台，本章将详细介绍如何使用 Git 与 GitHub 进行交互，包括仓库管理、协作开发、Pull Request 等操作。

      GitHub 基础概念

      什么是 GitHub？

      GitHub 是基于 Git 的代码托管平台，提供了：

      • 🏠 代码托管：远程仓库存储
      • 👥 协作开发：团队协作工具
      • 🔍 代码审查：Pull Request 机制
      • 🚀 CI/CD：GitHub Actions 自动化
      • 📊 项目管理：Issues、Projects、Wiki

      GitHub vs Git

      Git（本地）          GitHub（远程）
├── 版本控制         ├── 代码托管
├── 分支管理         ├── 协作平台
├── 提交历史         ├── 社交功能
└── 本地操作         └── 云端服务

      创建和配置 GitHub 仓库

      在 GitHub 上创建仓库

      1. 登录 GitHub
      2. 点击右上角的 "+" 按钮
      3. 选择 "New repository"
      4. 填写仓库信息：
        • Repository name（仓库名）
        • Description（描述）
        • Public/Private（公开/私有）
        • Initialize with README
        • Add .gitignore
        • Choose a license

      连接本地仓库到 GitHub

      方法一：克隆现有仓库

      # 克隆 GitHub 仓库到本地
git clone https://github.com/username/repository.git

# 或使用 SSH（推荐）
git clone git@github.com:username/repository.git

# 进入仓库目录
cd repository

# 查看远程仓库信息
git remote -v

      方法二：推送现有本地仓库

      # 在本地创建仓库
mkdir my-project
cd my-project
git init

# 添加远程仓库
git remote add origin https://github.com/username/my-project.git

# 或使用 SSH
git remote add origin git@github.com:username/my-project.git

# 创建初始提交
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"

# 推送到 GitHub
git push -u origin main

      SSH 密钥配置

      生成 SSH 密钥

      # 生成新的 SSH 密钥
ssh-keygen -t ed25519 -C "your.email@example.com"

# 如果系统不支持 ed25519
ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

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

# 添加密钥到 SSH 代理
ssh-add ~/.ssh/id_ed25519

      添加 SSH 密钥到 GitHub

      # 复制公钥到剪贴板
# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux
xclip -sel clip < ~/.ssh/id_ed25519.pub

# Windows (Git Bash)
clip < ~/.ssh/id_ed25519.pub

# 手动查看并复制
cat ~/.ssh/id_ed25519.pub

      然后在 GitHub 上：

      1. 进入 Settings → SSH and GPG keys
      2. 点击 "New SSH key"
      3. 粘贴公钥内容
      4. 添加描述性标题
      5. 点击 "Add SSH key"

      测试 SSH 连接

      # 测试 SSH 连接
ssh -T git@github.com

# 成功的输出示例：
# Hi username! You've successfully authenticated, but GitHub does not provide shell access.

      基本 GitHub 操作

      推送代码到 GitHub

      # 推送当前分支到远程
git push origin main

# 推送并设置上游分支
git push -u origin feature-branch

# 推送所有分支
git push --all origin

# 推送标签
git push origin v1.0.0
git push --tags origin

      从 GitHub 拉取更新

      # 拉取并合并远程更改
git pull origin main

# 等同于
git fetch origin
git merge origin/main

# 使用 rebase 拉取
git pull --rebase origin main

# 拉取所有远程分支
git fetch --all

      查看远程仓库信息

      # 查看远程仓库
git remote -v

# 查看远程分支
git branch -r

# 查看所有分支（本地和远程）
git branch -a

# 查看远程仓库详细信息
git remote show origin

      Fork 和 Pull Request 工作流

      Fork 仓库

      1. 在 GitHub 上找到要贡献的项目
      2. 点击右上角的 "Fork" 按钮
      3. 选择 Fork 到你的账户

      克隆 Fork 的仓库

      # 克隆你 Fork 的仓库
git clone git@github.com:yourusername/original-project.git
cd original-project

# 添加原始仓库为上游远程
git remote add upstream git@github.com:originalowner/original-project.git

# 验证远程仓库
git remote -v
# origin    git@github.com:yourusername/original-project.git (fetch)
# origin    git@github.com:yourusername/original-project.git (push)
# upstream  git@github.com:originalowner/original-project.git (fetch)
# upstream  git@github.com:originalowner/original-project.git (push)

      保持 Fork 同步

      # 获取上游仓库的更新
git fetch upstream

# 切换到主分支
git checkout main

# 合并上游的更改
git merge upstream/main

# 推送更新到你的 Fork
git push origin main

      创建功能分支

      # 确保在最新的主分支上
git checkout main
git pull upstream main

# 创建新的功能分支
git checkout -b feature/add-user-authentication

# 进行开发工作
echo "新功能代码" > new_feature.py
git add new_feature.py
git commit -m "feat: 添加用户认证功能"

# 推送功能分支到你的 Fork
git push -u origin feature/add-user-authentication

      创建 Pull Request

      1. 在 GitHub 上访问你的 Fork
      2. 点击 "Compare & pull request" 按钮
      3. 填写 PR 信息：
        • 标题：简洁描述更改
        • 描述：详细说明更改内容
        • 选择正确的基础分支和比较分支
      4. 点击 "Create pull request"

      Pull Request 模板

      ## 更改描述
简要描述这个 PR 的目的和内容

## 更改类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 重构
- [ ] 性能优化
- [ ] 其他

## 测试
- [ ] 添加了新的测试
- [ ] 所有现有测试通过
- [ ] 手动测试完成

## 截图（如果适用）
添加截图来展示 UI 更改

## 相关 Issue
Closes #123
Related to #456

## 检查清单
- [ ] 代码遵循项目的编码规范
- [ ] 自我审查了代码更改
- [ ] 添加了必要的注释
- [ ] 更新了相关文档
- [ ] 我的更改不会产生新的警告
- [ ] 添加了测试来证明修复有效或功能正常工作

      GitHub Issues 管理

      创建 Issue

      # 通过 GitHub CLI 创建 Issue
gh issue create --title "修复登录页面样式问题" --body "登录页面在移动设备上显示异常"

# 添加标签和指派
gh issue create --title "添加用户认证" --label "enhancement,priority:high" --assignee username

      Issue 模板

      <!-- .github/ISSUE_TEMPLATE/bug_report.md -->
---
name: Bug 报告
about: 创建一个报告来帮助我们改进
title: '[BUG] '
labels: bug
assignees: ''
---

**描述 Bug**
清晰简洁地描述这个 bug 是什么。

**重现步骤**
重现行为的步骤：
1. 进入 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误

**期望行为**
清晰简洁地描述你期望发生什么。

**截图**
如果适用，添加截图来帮助解释你的问题。

**环境信息：**
 - 操作系统: [例如 iOS]
 - 浏览器 [例如 chrome, safari]
 - 版本 [例如 22]

**附加信息**
在这里添加关于问题的任何其他信息。

      在提交中关联 Issue

      # 在提交信息中引用 Issue
git commit -m "fix: 修复登录页面样式问题

修复了移动设备上登录表单显示异常的问题。

Fixes #123"

# 其他关键词
# Closes #123    - 关闭 Issue
# Fixes #123     - 修复 Issue  
# Resolves #123  - 解决 Issue
# Related to #123 - 相关 Issue

      GitHub Actions 基础

      创建简单的 CI 工作流

      # .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    
    - name: Setup Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run linter
      run: npm run lint
    
    - name: Run tests
      run: npm test
    
    - name: Build project
      run: npm run build

      自动部署工作流

      # .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Build
      run: npm run build
    
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

      GitHub 高级功能

      GitHub Pages

      # 启用 GitHub Pages
# 1. 进入仓库 Settings
# 2. 滚动到 Pages 部分
# 3. 选择源分支（通常是 main 或 gh-pages）
# 4. 选择文件夹（/ 或 /docs）

# 创建 GitHub Pages 分支
git checkout --orphan gh-pages
git rm -rf .
echo "<h1>Hello GitHub Pages</h1>" > index.html
git add index.html
git commit -m "Initial GitHub Pages commit"
git push -u origin gh-pages

      GitHub Releases

      # 创建标签
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# 使用 GitHub CLI 创建 Release
gh release create v1.0.0 --title "Version 1.0.0" --notes "
## 新功能
- 添加用户认证
- 实现数据导出

## Bug 修复
- 修复登录问题
- 解决性能问题
"

# 上传文件到 Release
gh release upload v1.0.0 dist/app.zip

      GitHub Discussions

      # 启用 Discussions
# 1. 进入仓库 Settings
# 2. 滚动到 Features 部分
# 3. 勾选 Discussions

# 使用 GitHub CLI 创建讨论
gh api repos/:owner/:repo/discussions \
  --method POST \
  --field title="项目路线图讨论" \
  --field body="让我们讨论项目的未来发展方向" \
  --field category_id="DIC_kwDOExample"

      团队协作最佳实践

      分支保护规则

      在 GitHub 仓库设置中配置分支保护：

      # 保护规则建议：
# 1. 要求 Pull Request 审查
# 2. 要求状态检查通过
# 3. 要求分支是最新的
# 4. 限制推送权限
# 5. 要求管理员遵循规则

      代码审查流程

      # 审查者的工作流程：
# 1. 检出 PR 分支进行本地测试
gh pr checkout 123

# 2. 运行测试
npm test

# 3. 审查代码更改
gh pr diff 123

# 4. 添加审查意见
gh pr review 123 --approve
gh pr review 123 --request-changes --body "请修复安全问题"

# 5. 合并 PR（如果是维护者）
gh pr merge 123 --squash

      项目管理

      # 使用 GitHub Projects
# 1. 创建项目看板
# 2. 添加列（To Do, In Progress, Done）
# 3. 将 Issues 和 PR 添加到项目
# 4. 使用自动化规则

# 使用里程碑管理版本
# 1. 创建里程碑（如 v1.0.0）
# 2. 将相关 Issues 分配到里程碑
# 3. 跟踪进度

      GitHub CLI 使用

      安装 GitHub CLI

      # macOS
brew install gh

# Ubuntu/Debian
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Windows
winget install GitHub.cli

      常用 GitHub CLI 命令

      # 认证
gh auth login

# 仓库操作
gh repo create my-new-repo --public
gh repo clone username/repo
gh repo fork username/repo

# Issue 操作
gh issue list
gh issue create --title "Bug report" --body "Description"
gh issue close 123

# Pull Request 操作
gh pr list
gh pr create --title "New feature" --body "Description"
gh pr checkout 123
gh pr merge 123

# Release 操作
gh release list
gh release create v1.0.0 --notes "Release notes"

# 查看仓库状态
gh repo view
gh pr status
gh issue status

      故障排除

      常见 GitHub 问题

      # 问题1: 推送被拒绝
# 原因: 远程仓库有新的提交
# 解决: 先拉取再推送
git pull origin main
git push origin main

# 问题2: SSH 连接失败
# 原因: SSH 密钥配置问题
# 解决: 重新配置 SSH 密钥
ssh-keygen -t ed25519 -C "your.email@example.com"
# 然后添加到 GitHub

# 问题3: Fork 同步问题
# 原因: Fork 落后于原仓库
# 解决: 同步 Fork
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# 问题4: 大文件推送失败
# 原因: 文件超过 GitHub 限制（100MB）
# 解决: 使用 Git LFS
git lfs track "*.zip"
git add .gitattributes
git add large-file.zip
git commit -m "Add large file with LFS"

      GitHub API 限制

      # 查看 API 限制
gh api rate_limit

# 使用认证提高限制
gh auth login

# 对于大量操作，考虑使用 Personal Access Token

      安全最佳实践

      保护敏感信息

      # 使用 .gitignore 排除敏感文件
echo "*.env" >> .gitignore
echo "config/secrets.json" >> .gitignore
echo "*.key" >> .gitignore

# 使用 GitHub Secrets 存储敏感信息
# 在仓库 Settings → Secrets and variables → Actions 中添加

# 在 GitHub Actions 中使用 Secrets
env:
  API_KEY: ${{ secrets.API_KEY }}
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

      访问控制

      # 仓库访问控制：
# 1. 使用团队管理权限
# 2. 定期审查协作者
# 3. 使用分支保护规则
# 4. 启用双因素认证
# 5. 监控仓库活动

      总结

      GitHub 操作的核心要点：

      基础操作

      git clone    # 克隆仓库
git push     # 推送更改
git pull     # 拉取更新
gh pr create # 创建 PR
gh issue create # 创建 Issue

      协作流程

      • 🍴 Fork 工作流：适合开源贡献
      • 🌿 分支工作流：适合团队协作
      • 📋 Issue 跟踪：管理任务和 Bug
      • 🔍 代码审查：保证代码质量

      自动化工具

      • ⚡ GitHub Actions：CI/CD 自动化
      • 🚀 GitHub Pages：静态网站托管
      • 📦 GitHub Releases：版本发布管理
      • 💬 GitHub Discussions：社区讨论

      最佳实践

      • ✅ 配置 SSH 密钥认证
      • ✅ 使用分支保护规则
      • ✅ 编写清晰的 PR 描述
      • ✅ 及时同步 Fork
      • ✅ 保护敏感信息

      掌握 GitHub 操作后，你就能够：

      • 🤝 高效地进行团队协作
      • 🔄 参与开源项目贡献
      • 🚀 自动化开发和部署流程
      • 📊 有效管理项目进度

      在下一章中，我们将学习 Git 术语表。