Github 使用指南

一. 介绍

Github是一个全球最大的代码托管平台，也是一个开源软件开发社区，它为程序员、开发者和团队提供了一个基于互联网的集中式代码管理工具。它使用Git作为基础技术，并提供了一系列功能强大的协作和开发工具，例如问题跟踪、代码审核、版本控制、分支管理等等。

Github最初是由美国程序员Tom Preston-Werner和Chris Wanstrath以及P. J. Hyett在2008年4月创建的，当时它只是一个简单的Web应用程序，用于管理和分享代码。随着开源软件的普及和互联网的发展，Github迅速成为全球最受欢迎的代码托管平台之一，目前拥有超过6000万的开发者和超过1.5亿个代码仓库。

主要用途

1. 代码托管：开发者可以将代码存储在Github上，并通过Git进行版本控制和协作开发。
2. 项目管理：Github提供了强大的项目管理功能，包括任务分配、问题追踪和代码审核等。
3. 文档管理：开发者可以使用Github来存储和共享文档，如API文档、用户手册等。
4. 博客托管：开发者可以使用Github Pages来搭建静态博客，将博客页面托管在Github上。
5. 开源社区：Github是一个开源社区，开发者可以通过贡献开源项目来提升自己的技能和声誉。

优势

1. 分布式版本控制：Github使用Git进行版本控制，具有分布式版本控制的优势，可以避免单点故障和数据丢失。
2. 开放性和透明度：Github是一个开源社区，任何人都可以访问和查看公开的项目和代码，提高了透明度和开放性。
3. 协作和共享：Github提供了强大的协作和共享功能，开发者可以轻松地与团队成员、同行和其他开发者协作开发。
4. 社区和生态系统：Github是一个庞大的开源社区，包括众多开源项目和开发者，开发者可以从中受益，并提高 自己的技能和经验。
5. 强大的工具和服务：Github提供了许多强大的工具和服务，如CI/CD、自动化部署、代码审核、问题追踪和Wiki等，可以帮助开发者提高效率和质量。

Github的基本概念

仓库(repository)：指存储项目代码和文件的地方。一个仓库可以包含多个文件和文件夹，并记录项目历史和版本信息。 分支(branch)：指在仓库中创建的一个代码版本。通过创建分支，可以在不影响主干代码的情况下进行实验和修改。 提交(commit)：指将修改过的文件和文件夹保存到仓库中的操作。每个提交都会包含一条描述修改内容的信息。 合并(merge)：指将一个分支的代码合并到另一个分支或主干代码中的操作。 发布(Release)：指的是将特定版本的代码或文件打包并发布到 GitHub，这些版本可以用来对外发布项目的稳定版本、发布更新等。 发布(publish)：一般指将静态网站发布到 GitHub Pages。 拉取请求(pull request)：指在 Github 上发起的一项合并请求，通常由分支的创建者向项目的维护者发起，请求合并分支代码到主干分支。 问题(Issue)：指在 Github 上的一个问题跟踪系统，可以用于报告软件缺陷、请求新功能或讨论项目问题等。 派生(Fork)：指的是复制某个仓库到自己的 GitHub 帐号下。在自己的帐号下进行修改、提交变更等操作不会影响到原始的项目。如果希望你所做的修改能够贡献给原始项目，你可以提交 Pull Request 给原作者，让他来评审并接受你的修改。 （发布） Github Pages：是 GitHub 提供的一项免费的静态网站托管服务。

二、准备工作

1. 注册Github账号。链接
2. 安装Git客户端。链接
3. 生成SSH密钥

git 客户端配置

在命令行终端输入git --version命令，如果能够显示Git的版本号，则说明Git客户端已经成功安装。

1. 设置Git客户端的用户信息，包括用户名和电子邮件地址。

   git config --global user.name "your_name"   # nsleep
   git config --global user.email "your_email" # simoncq@163.com

2. 设置默认文本编辑器 如果没有设置默认的文本编辑器，Git 会使用系统默认的文本编辑器，例如 Vim。

   git config --global core.editor "vim"

3. 设置默认分支 将默认分支设置为其他分支，例如 main 分支。

   git config --global init.defaultBranch main

4. 其他配置 还有一些其他的 Git 配置可以进行，例如设置颜色输出、配置 Git 对换行符的处理等等。 可以使用以下命令来查看当前的 Git 配置

   git config --list

在安装Git客户端后，可以选择性的安装一个可视化图形软件辅助git使用，例如： 1. Sourcetree 2. GitKraken 3. GitHub Desktop 4. Tower

生成SSH密钥

为了方便本地访问Github，创建ssh密钥，并将公钥[%USERPROFILE%/.ssh/id_rsa.pub]上传Github ssh keys

ssh-keygen -t rsa -b 4096 -C "your_email" 	# 创建密钥对
ssh -T git@github.com # 测试添加ssh是否成功  -v 显示详细信息	

• 更多参见Github Docs

三、Github 基本操作

创建仓库(repository)

git init

克隆(clone)仓库到本地

git clone https://github.com/<YourName>/YourRepoName.git

在本地进行修改和提交

# 暂存
git add README.md
git add .
# 提交本地仓库
git commit -m "Update Messages"

将本地提交推送(push)到Github

# 添加远程版本库
git remote add origin https://github.com/<YourName>/YourRepoName.git
# 推送
git push -u origin main

查看提交历史

查看当前分支的提交历史

git log

查看某个特定分支的提交历史

git log <branch-name>

其中 <branch-name> 是要查看的分支的名称。

git log 命令支持许多选项和参数，例如使用 --author 选项按作者筛选提交记录，使用 --since 和 --until 选项按时间段筛选提交记录等等。可以通过运行 git log --help 命令来查看所有选项和参数的帮助信息。

撤销提交

撤销提交有两种情况：一种是撤销本地未推送到远程仓库的提交，另一种是撤销已经推送到远程仓库的提交。

撤销本地未推送到远程仓库的提交

如果你在本地提交了代码，但是还没有推送到远程仓库，可以使用以下两种方法撤销提交：

1. 使用 git reset 命令。该命令会将当前分支指向指定的提交，并且将代码库重置为该提交的状态。如果不带参数，则默认将当前分支指向上一次提交。

   git reset HEAD~1   # 撤销上一次提交

2. 使用 git revert 命令。该命令会创建一个新的提交来撤销指定的提交。这种方法不会删除任何历史记录。

   git revert HEAD   # 撤销上一次提交

撤销已经推送到远程仓库的提交

如果你已经将代码推送到远程仓库，并且其他人已经对该提交进行了修改，那么就需要使用 git revert 命令来创建一个新的提交来撤销之前的提交。

1. 首先使用 git log 命令查看要撤销的提交的哈希值。
2. 然后使用 git revert <commit-hash> 命令创建一个新的提交。
3. 最后使用 git push 命令将新的提交推送到远程仓库。

分支管理

常用的分支管理命令包括：

• git branch：列出所有分支，以及当前所在的分支。
• git branch [branch name]：新建一个分支。
• git checkout [branch name]：切换到指定分支。
• git checkout -b [branch name]：新建一个分支，并切换到该分支。
• git merge [branch name]：将指定分支合并到当前分支。
• git branch -d [branch name]：删除指定分支。
• git branch -D [branch name]：强制删除指定分支。

Github的相关工具和服务

Github Desktop Travis CI Codecov Coveralls

常见问题解答

如何解决冲突(conflict)

在 Git 中，冲突通常发生在两个分支上进行了相同文件的更改，并且尝试将这两个分支合并（merge）时发生。为了解决冲突，可以按照以下步骤进行：

• 运行 git status 命令，查看冲突的文件。
• 打开冲突的文件，查看冲突的位置。Git 会在冲突的地方插入一些标记，标识出两个不同的更改。
• 修改文件，解决冲突。根据实际情况选择保留、删除或修改其中一个或两个更改。
• 保存文件。
• 运行 git add 命令，将冲突文件标记为已解决。
• 运行 git commit 命令，提交合并后的更改。
• 如果需要，推送(push)到远程仓库。

如何回退(commit revert)

在 Git 中，要回退（revert）一个提交（commit），可以使用 git revert 命令。该命令并不会删除之前的提交。因此，在回退一个提交之后，如果需要彻底删除这个提交，可以使用 git reset 命令或者 git rebase 命令。但是，这样做会导致历史提交记录被修改，不建议在公共仓库中执行这样的操作。

• 使用 git log 命令查看最近的提交历史，找到需要回退的提交的 SHA-1 标识符。
• 然后，可以使用 git revert 命令指定需要回退的提交的 SHA-1 标识符。

如何合并(merge)和推送(push)分支

步骤如下： 1. 首先，切换到目标分支，例如主分支 main：

git checkout master

2. 将要合并的分支 feature 合并到当前分支 main 上：

git merge feature

如果出现冲突，需要解决冲突后再执行合并操作。 3. 将合并后的更改推送到远程仓库：

git push origin master

如果第一次推送，需要使用 -u 参数设置上游分支：

git push -u origin master

如果推送过程中提示需要拉取最新代码，请先拉取最新代码：

git pull origin master
 git push origin master

如何通过Pull Request进行协作和代码审核

一般步骤： 1. Fork源代码仓库到自己的账户下，然后将代码仓库clone到本地。 2. 创建一个新分支，基于最新的远程代码。

git checkout -b new-branch origin/master

3. 在新分支上进行修改和提交。

git add .
git commit -m "commit message"

4. 将新分支推送到自己的远程仓库中。

git push origin new-branch

5. 在Github上创建一个Pull Request，选择要合并到的目标分支，写明详细的修改内容和描述，向目标分支的仓库管理员请求代码审核。代码审核人员检查代码，提出修改意见，或者在PR页面中进行评论讨论。如果代码审核通过，管理员就可以将该PR合并到目标分支。 6. 删除本地分支。

git branch -d new-branch

7. 更新自己的仓库到最新版本，以便下次开发。

git fetch upstream
git merge upstream/master
git push origin master

其中 upstream 指的是一个远程仓库的地址

CRLF 报错问题

首先问题出在不同操作系统所使用的换行符是不一样的，下面罗列一下三大主流操作系统的换行符： Uinx/Linux采用换行符 LF 表示下一行（LF：LineFeed，换行）； Dos和Windows采用回车+换行CRLF表示下一行（CRLF: CarriageReturn LineFeed，中文意思是回车换行）； Mac OS采用回车CR表示下一行（CR：CarriageReturn，回车）。

当错误出现的时候，可以执行下面命令：

git config --global core.autocrlf false

core.autocrlf 有三个值: 为 true 时，Git 会将你 add 的所有文件视为文本文件，将结尾的 CRLF 转换为LF，而 checkout 时会再将文件的LF格式转为 CRLF 格式。 为 false 时，line endings 不做任何改变，文本文件保持其原来的样子。 为 input 时，add 时 Git 会把 CRLF 转换为 LF，而 check 时仍旧为 LF，所以 Windows 操作系统不建议设置此值。

SSL 证书错误

当错误出现的时候，可以执行下面命令：

git config --global http.sslVerify false
git config --global https.sslVerify false

如何手动验证证书并将其添加到 Git 的信任列表中？

• 在浏览器中打开网站，并单击地址栏中的锁形图标。
• 选择“证书”或“证书信息”选项。
• 在“证书”窗口中选择“详细信息”选项卡。
• 在“详细信息”选项卡中，选择“证书颁发机构”/“证书层次结构”字段下的网址，点击“导出”，保存类型为“证书链”(.pem,.crt)。
• 输入命令
  

  git config --global http.sslCAInfo /path/to/github.crt