GitHub

介绍

  • 全球最大的代码托管平台，也是一个社区

  • 也可以托管 Gist 代码片段

  • 团队协作开发平台：有完善的协作功能 (Fork, Issue, Pull Request) 等功能

  • 提供免费的静态网站托管服务 GitHub Pages

  • GitHub 每个仓库的总体积限制是 1GB（Gitee 是 500MB），每个仓库中每个 release 的最大文件体积限制是 2GB（Gitee 是 1GB）；release 数量没有明确的限制；对于普通用户，仓库（仓库代码 + release 文件）的总体积限制为 100 GB

参考资料

使用

工具

GitHub Markdown

1
2
3
4
5
> [!NOTE]
> [!TIP]
> [!IMPORTANT]
> [!WARNING]
> [!CAUTION]

image.png

GitHub 基本使用

  • Repo 页面

image.png

  • Issues 页面

Untitled

  • Pull requests 页面（简称 PR）

Untitled

image.png

  • Pull Requests 流程:

    • Fork（复刻） 该 Repo；
    • git clone fork 的 Repo 到本地，进行代码修改并提交，会出现提交的 commit 相对原 Repo 的前后关系；
    • 点击 “Contribute”，提一个 Pull Request 给原来的 Repo；
    • 点击 “Sync fork”，同步原 Repo 最新代码。
  • 改变 Repo 的 public private 状态：该 Repo 的 Settings - Danger Zone

image.png

  • 设置自己的 activity 为 private：Settings - Public profile - Contributions & activity

Untitled

image.png

GitHub Pages

GitHub Pages 介绍

  • GitHub 提供的免费静态网页托管服务，类似的还有 Gitee Pages 和 GitLab Pages；商用：Vercel、Netlify、Cloudflare Pages 等
  • GitHub 会为每个用户/组织分配一个二级域名 username.github.io
  • 创建一个名为 username.github.io 的 repo，会作为主页，通过 username.github.io 即可访问 repo 内存放的静态网页
  • 对于其他 repo（可无限创建），也可以开启 Pages 功能，通过 username.github.io/repo-name 访问，静态页面来源也需要指定
  • 部署时自动创建 gh-pages 分支：GitHub - peaceiris/actions-gh-pages

image.png

GitHub 个人首页

参考：美化 GitHub profile 教程：GitHub - rzashakeri/beautify-github-profile

创建名为 username 的 repo，在 README.md 文档中添加内容即可生成个人首页（profile），可以添加 GitHub 统计信息以丰富并自定义 profile。

可获取动态生成的 GitHub 统计信息的 repo：

使用 github-readme-stats repo 部署的 vercel app API 会有次数限制，且只能访问公开 repo 的相关数据，导致统计信息不全。因此更建议 fork 该 repo，部署自己的 vercel app API（可以访问私有 repo 数据，参见 deploy-on-your-own；添加 PAT_1 环境变量时，注意需点击 Save 保存）

github-stats repo：使用 Github Acitons 生成 GitHub 统计信息卡片（生成速度较慢）；克隆该 repo，删除 .git，创建自己的 repo（非 fork），根据需要添加 EXCLUDED、EXCLUDED_LANGS 和 EXCLUDE_FORKED_REPOS secrets（创建这些 secrets 的方法：进入该 repo 的设置页面中的 “Secrets” 部分，创建新 secret）

profile 实例参考：

标准 README.md 文件写法：GitHub - RichardLitt/standard-readme: A standard style for README files

优秀 README.md 文件：GitHub - matiassingers/awesome-readme: A curated list of awesome READMEs

GitHub Star history：GitHub Star History

1
< img alt="Star History" loading="lazy" src="https://api.star-history.com/svg?repos=SamirPaulb/DSAlgo&type=Date">

GitHub contribution 可视化：

徽章

通常在 GitHub 的 README 文件或其他在线文档中显示以展示各种信息，如构建状态、测试覆盖率、包版本、许可证信息等。

徽章/ icon 相关 repo：

Python 相关（使用 pypi）

1
2
3
4
5
6
7
8
<!-- package 版本 -->
![PyPi](https://img.shields.io/pypi/v/spt?logo=pypi&logoColor=white&label=PyPI)
<!-- package 下载量 -->
![PyPI Downloads](https://img.shields.io/pypi/dm/spt?logo=pypi&logoColor=white&color=blue&label=PyPI%20downloads)
<!-- Python 版本 -->
![Requires Python 3.6+](https://img.shields.io/badge/Python-3.6+-blue.svg?logo=python&logoColor=white)
<!-- package wheel -->
![PyPI - Wheel](https://img.shields.io/pypi/wheel/spt)

GitHub Repo 相关（使用 github）

1
2
3
4
5
6
7
8
9
10
<!-- star 数目 -->
![GitHub Repo stars](https://img.shields.io/github/stars/Bit-Part-Young/spt)
<!-- license 证书 -->
[![GitHub](https://img.shields.io/github/license/jzhang-github/PyFunction)](https://github.com/jzhang-github/PyFunction/blob/main/LICENSE)
<!-- 点击量 -->
![Hits-of-Code](https://hitsofcode.com/github/Bit-Part-Young/spt?branch=master)
<!-- CI 状态 方式 1 -->
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Bit-Part-Young/github-stats/main.yml)
<!-- 方式 2 -->
![Generate Stats Images - passing](https://github.com/Bit-Part-Young/github-stats/actions/workflows/main.yml/badge.svg)

编程语言 logo（使用 badge）

1
2
3
4
5
6
![Python](https://img.shields.io/badge/-Python-3776ab?style=flat-square&logo=python&logoColor=fff)
![Shell](https://img.shields.io/badge/-Shell-4eaa25?style=flat-square&logo=gnu%20bash&logoColor=fff)
![C++](https://img.shields.io/badge/-C%2b%2b-00599c?style=flat-square&logo=C%2b%2b&logoColor=fff)
![Fortran](https://img.shields.io/badge/-Fortran-734f96?style=flat-square&logo=fortran&logoColor=fff)
![Julia](https://img.shields.io/badge/-Julia-9558b2?style=flat-square&logo=julia&logoColor=fff)
![LaTeX](https://img.shields.io/badge/-LaTeX-008080?style=flat-square&logo=latex&logoColor=fff)

pre-commit

Git项目管理，代码规范pre-commit使用详解 - 夏冬

pre-commit：用于管理和维护 git 钩子的框架。允许配置多种钩子，这些钩子会在代码提交到仓库之前自动运行，以检查代码风格、格式化代码、检查语法错误（可用于 Python、Markdown、Shell）等。配置文件：.pre-commit-config.yaml

1
2
3
4
5
6
7
8
9
10
11
12
# 安装
pip install -U pre-commit
# 安装钩子
pre-commit install
# 生成默认配置
pre-commit sample-config
# 手动运行钩子
pre-commit run
pre-commit run --all-files

# 删除钩子
rm .git/hooks/pre-commit

格式：

1
2
3
4
5
6
7
repos:
  - repo:  # 钩子 repo url
    rev:  # 版本
    hooks:  # 列出要使用的具体钩子
      - id:  # 钩子唯一标识
        args:  # 可选 传递给钩子的额外参数
        language_version: # 编程语言版本 如 python3.11

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
exclude: '.git|.tox'
default_stages: [commit]
fail_fast: true

repos:
  - repo: https://github.com/psf/black-pre-commit-mirror
    rev: 24.4.2
    hooks:
      - id: black  # black-jupyter
        # language_version: python3.11

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.2
    hooks:
      # Run the linter.
      - id: ruff
        args: [ --fix ]
        types_or: [ python, pyi, jupyter ]
      # Run the formatter.
      - id: ruff-format
        types_or: [ python, pyi, jupyter ]

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
    - id: isort
      name: isort (python)
      args:
      - --profile=black

GitHub Actions

  • GitHub 提供的 CI/CD 服务：CI（Continuous Integration）：持续集成；CD（Continuous Delivery）：持续交付
  • 即配置一些自动化任务，在特定事件发生时自动执行：如每次 push 后自动测试，release 时自动构建部署
  • 配置文件：.github/workflows/workflow_name.yml；可以有多个 .yml 文件

参考资料：

具体示例：

GitHub CLI

1
2
3
4
5
6
7
sudo apt install gh  # Ubuntu

sudo pacman -S github-cli  # Arch Linux

brew install gh  # Mac

conda install gh --channel conda-forge  # Conda
  • 源码编译安装
1
2
3
4
5
6
7
8
9
# 安装 golang
curl -sS https://webi.sh/golang | sh

git clone https://github.com/cli/cli.git gh-cli
cd gh-cli

make install prefix=$HOME/src/gh

ln -s ~/src/gh/bin/gh ~/bin
  • 验证登录：按照提示进行
1
gh auth login
  • 创建 release 并上传文件：file 格式可以是压缩文件，pdf，md 等，txt 不行
1
2
3
4
5
gh release create v0.0.1  # 创建 release

gh release upload v0.0.1 file  # 上传附加文件

gh release list  # 列出 releases
  • 创建 issue
1
gh issue create --title "gh issue test" --body "create an issue by gh"
  • GitHub Copilot CLI 使用（效果一般）
1
2
3
4
5
6
7
8
# 安装
gh extension install github/gh-copilot

gh copilot explain  # 解释
gh copilot suggest  # 建议

# 设置别名 ghcs 和 ghce
echo 'eval "$(gh copilot alias -- zsh)"' >> ~/.zshrc

相关问题

  • GitHub feed 最新消息时间与电脑时间差 12 小时（移动端、网页均是次情况）

  • GitHub 桌面端不好用；移动端有探索功能

  • 之前留言过的 GitHub issue，仍会收到后续通知， 如何关闭（在 GitHub 个人主页的 Notifications 处关闭）

  • GitHub Organization 删除后，90 天内该名字无法被使用

  • GitHub 添加 organization 成员（弄成课题组）