对Github中Apollo项目进行版本控制的方法_apollo github

本文介绍对Github中Apollo项目进行版本控制涉及到的各方面内容。本文使用的操作系统为Ubuntu 16.04。

一、在Github注册一个账号

打开Chrome或其他浏览器，进入Github主页，选择“Sign Up”，填写相关信息，具体操作就不用介绍了吧。我在Github的账号为：davidhopper2003。

二、安装Git

按快捷键“Ctrl+Alt+T”打开命令行终端，输入如下shell命令：

sudo apt-get install git
git config --global user.name "Your Name"
git config --global user.email "email@example.com"
1
2
3

注意，这里的Email最好与Github中注册账号的Email地址一致，否则无法与你的Github账号对应起来。

三、设置Git代理

说明：如果没有VPN，可直接忽略本节内容。

在天朝由于墙的原因，访问github网站速度很慢，可能会影响到正常工作，建议花点找小钱买个代理账号（关于Ubuntu 16.04系统中代理设置的方法，可参见我撰写的文章：Ubuntu 16.04系统中代理工具shadowsocks-qt5的使用方法。
如果操作系统进行了代理设置，则git使用代理的方法如下：
Git允许使用三种协议来连接远程仓库：ssh、http/https、git。因此要让git使用代理，首先必须明确本地git使用何种协议连接远程仓库，然后根据不同协议设置代理（Github一般使用http/https和ssh两种协议）。

3.1 设置SSH协议的代理

如果远程仓库拥有如下格式：

git@github.com:archerie/learngit.git
ssh://git@github.com:archerie/learngit.git
1
2

那么使用的就是SSH协议连接的远程仓库。使用vi或其他文本编辑器修改如下配置文件：~/.ssh/config（没有则新建），内容如下：

#Linux
Host github.com
  User git
  Port 22
  Hostname github.com
  ProxyCommand nc -x 127.0.0.1:1080 %h %p
1
2
3
4
5
6

3.2 设置http/https协议代理

如果远程仓库链接拥有如下格式：

http://github.com/archerie/learngit.git
https://github.com/archerie/learngit.git
1
2

说明使用的是http/https协议，可在命令行终端中输入如下命令配置：

# 全局设置
git config --global http.proxy socks5://localhost:1080
# 单次设置
git clone https://github.com/example/example.git --config "http.proxy=socks5://localhost:1080"
1
2
3
4

3.3 设置Git协议的代理

Git协议是Git提供的一个守护进程，它监听专门的端口（9418），然后提供类似于ssh协议的服务，只是它不需要验证。如果远程仓库链接是如下形式：

git://github.com/archerie/learngit.git
1

说明使用的git协议连接，可在命令行终端中输入如下命令配置：

git config --global core.gitproxy "git-proxy"
git config --global socks.proxy "localhost:1080"
1
2

配置完毕后，可以使用如下命令查看是否设置成功：

git config --list
1

上述命令在我机器上执行的结果如下：

http.proxy=socks5://localhost:1080
user.email=davidhopper2003@hotmail.com
user.name=David Hopper
core.gitproxy=git-proxy
socks.proxy=localhost:1080
1
2
3
4
5

四、生成并配置Github所需的SSH key

4.1 生成SSH key

按快捷键“Ctrl+Alt+T”打开命令行终端，输入如下shell命令，注意将"your_email@example.com"替换为你在Github中的Emai地址，这个地址一定不能填错，否则无法登录Github：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
1

该命令会在本机生成一个新的SSH key，它使用你提供的Email地址作为标签。接下来会出现如下提示，按回车键即可：

Generating public/private rsa key pair.
Enter a file in which to save the key (/home/davidhopper/.ssh/id_rsa): [Press enter]
1
2

之后会出现如下提示，让你输入密码，请输入你的密码并牢记之：

Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]
1
2

如果一切顺利，应当会在~/.ssh目录生成多个key文件，可使用如下命令检查：

ls -al ~/.ssh
1

如果出现如下所示的类似信息，表示操作成功：

总用量 24
drwx------  2 david david 4096 2月  26 11:38 .
drwxr-xr-x 37 david david 4096 2月  26 11:21 ..
-rw-rw-r--  1 david david  108 2月  26 08:55 config
-rw-------  1 david david 1766 2月  26 09:14 id_rsa
-rw-r--r--  1 david david  400 2月  26 09:14 id_rsa.pub
-rw-r--r--  1 david david  884 12月 23 13:56 known_hosts
1
2
3
4
5
6
7

4.2 将SSH key加入ssh-agent

输入如下命令将SSH key加入ssh-agent：

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
1
2

4.3 将SSH key加入Github账户

使用vi或其他文件编辑器打开公钥文件：~/.ssh/id_rsa.pub，使用“Ctrl+C”快捷键复制该文件中的全部内容。
打开Chrome或其他浏览器，登录你的Github账户，按下图操作：

五、建立、复制和同步Apollo项目分支

5.1 在Github网站建立Apollo项目分支

打开Chrome或其他浏览器，登录你的Github账户，进入Apollo项目主页：https://github.com/ApolloAuto/apollo， 点击其中的“Fork”按钮（如下图所示），在你的Github账户建立Apollo项目分支：

5.2 将项目分支复制到本地

在本机合适的位置建立Apollo项目分支的存储目录（我的目录为：/home/david/code/davidhopper）
。按快捷键“Ctrl+Alt+T”打开命令行终端，执行如下命令，将项目分支复制到本地（注意：如果不使用代理，复制速度会很慢，估计要花费大半天，期间还不能出现网络问题，否则前功尽弃；若使用代理，最多几分钟就可完成）：

cd /home/david/code/davidhopper
git clone https://github.com/davidhopper2003/apollo
1
2

如果要使用SSH协议传输，则使用如下命令：

git clone git@github.com:davidhopper2003/apollo.git
1

说明：如何获取一个项目的SSH协议地址？在浏览器中打开该项目主页，按照下图操作即可：

5.3 将项目分支与Apollo项目主分支同步

因为Apollo项目主分支每天都会更新，因此我们应当随时保持与主分支的同步状态。具体操作方法如下：
a) 将Apollo项目主分支设置为当前项目分支的上游仓库
按快捷键“Ctrl+Alt+T”打开命令行终端，进入本地项目目录（我的目录为：/home/david/code/davidhopper/apollo），执行如下命令：

cd /home/david/code/davidhopper/apollo
git remote add upstream https://github.com/ApolloAuto/apollo
1
2

如果要使用SSH协议传输，则使用如下命令：

git remote add upstream git@github.com:ApolloAuto/apollo.git
1

操作完成后，可使用下述命令查看项目分支及上游仓库的信息：

git remote -v
1

上述命令在我的电脑上显示信息为（我使用SSH协议传输）：

origin	git@github.com:davidhopper2003/apollo.git (fetch)
origin	git@github.com:davidhopper2003/apollo.git (push)
upstream	git@github.com:ApolloAuto/apollo.git (fetch)
upstream	git@github.com:ApolloAuto/apollo.git (push)
1
2
3
4

b) 将项目分支与Apollo项目主分支同步（本节操作较繁琐，大家可直接跳过看第七节内容）
继续在上述令行终端输入如下命令，将其与Apollo项目主分支同步：

# Fetch the branches and their respective commits from the upstream repository. 
git fetch upstream

# Check out your fork's local master branch.
git checkout master

# Merge the changes from upstream/master into your local master branch. This brings 
# your fork's master branch into sync with the upstream repository, without losing 
# your local changes.
git merge upstream/master
1
2
3
4
5
6
7
8
9
10

六、向Apollo项目主分支提交本地修改（本节操作较繁琐，大家可直接跳过看第七节内容）

我们在本地Apollo项目分支修改代码后，可能会有一些不错的代码需向Apollo项目主分支提交。显然，直接向其推送（push）是不可能接受的（因为我们没有修改Apollo项目主分支的权限。假设可以这样操作，Apollo项目主分支将变得千疮百孔，无法维护，因此这种情况必然不可能发生），我们只能在本地提交（commit），再推送（push）到自己的项目分支（我的项目分支为：git@github.com:davidhopper2003/apollo.git（SSH协议），https://github.com/davidhopper2003/apollo（ HTTPS协议）），最后向Apollo项目主分支发起一个拉取请求（pull request）

6.1 从Apollo项目主分支拉取（pull）最新内容至本地项目

先将项目主分支（我的项目主分支为：git@github.com:davidhopper2003/apollo.git， https://github.com/davidhopper2003/apollo）的最新内容拉取到本地master分支：

# 进入Apollo项目目录
cd /home/david/code/davidhopper/apollo
# 拉取最新修改
git pull
1
2
3
4

6.2 创建本地项目的local_dev分支

直接在本地的master分支上进行修改，可能会让master分支产生超前Apollo项目master分支的问题。为此，我们首先创建本地master分支的local_dev分支，然后切换到local_dev分支：

git checkout -b local_dev
1

git checkout命令加上-b参数表示创建并切换，相当于以下两条命令：

# 创建分支local_dev
git branch local_dev
# 切换到分支 local_dev
git checkout local_dev
1
2
3
4

可以使用git branch命令查看当前分支：

git branch
1

结果显示为：

* local_dev
  master
1
2

git branch命令会列出所有分支，当前分支前面会标记一个*号。

还可以根据远程分支创建本地分支：

# 本地分支名与远程分支名可以相同，也可以不同
git checkout -b 本地分支名 origin/远程分支名
# 例如：根据远程的"3.0_dev"分支创建本地的"dh_dev"分支
git checkout -b dh_dev origin/3.0_dev
# 查看本地分支和远程分支的跟踪关系
git branch -vv
1
2
3
4
5
6

6.3 在本地项目的local_dev分支上进行修改、提交

修改代码后，将修改内容提交（commit），最后将本地提交向Github上的项目分支推送（push），操作方法如下：

# 把工作时的所有变化提交到暂存区，包括文件内容修改(modified)以及新文件(new)，但不包括被删除的文件。
git add .

# 将example.cc文件提交到暂存区
git add example.cc

# 将所有修改的文件（不包括新文件）提交到暂存区
git add -u

# 将暂存区的修改提交到local_dev分支
git commit -m "Here is the comment. " 

# 将当前分支由local_dev切换到master
git checkout master 

# 将local_dev分支的所有更改合并到master分支
# --squash选项的含义是：只提交本地文件内容的修改，但不提交、不移动HEAD，其效果相当于将
# local_dev分支上文件的多次修改合并成一条记录放置于当前分支上，但舍弃原来的commit历史。
git merge --squash local_dev

# 需要一条额外的commit命令，将local_dev分支上的多条commit记录变为下面的唯一一次commit。
git commit -m "new commit message here"

# 合并完成后可以放心地删除本地local_dev分支（除非你确认不需再进行开发，否则就不要删除）
git branch -d local_dev

# 将本地修改提交到Github中自己的项目主分支
git push
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

6.4 向Apollo项目主分支发送拉取请求（pull request）

打开Chrome或其他浏览器，登录你的Github账户，进入你的Apollo项目分支主页（我的主页为：https://github.com/davidhopper2003/apollo）， 按下图所示向Apollo项目主分支发送拉取请求（pull request），之后等待Apollo项目代码维护人员与你联系。如果没有问题，他们就会将你的修改合并到Apollo项目主分支。



注意：第一次提交时，还需要签订一个协议，否则Apollo项目代码维护人员无法将你的pull request合并，如下图所示：

七、直接使用开发分支向Apollo项目主分支提交本地修改

第六节方法操作太繁琐，且稍有不慎就可能污染master分支，这里参照Apollo帮助文档，给出一种直接使用开发分支向Apollo项目主分支提交本地修改的便捷方法。
假定我们已完成第一节到第五节（不包括5.3.b节）的全部工作，忽略5.3.b节和第六节内容，直接按下述步骤操作：

7.1 切换至自己的开发分支

# 创建你的开发分支，例如：我就使用dh_dev（表示davidhopper_dev)，注意该步骤只需进行一次
git branch dh_dev
# 切换到分支dh_dev
git checkout dh_dev
1
2
3
4

7.2 将当前分支与Apollo项目主分支同步

git pull --rebase  upstream master
1

7.3 在本地完成代码修改并提交到本地仓库

# 把工作时的所有变化提交到暂存区，包括文件内容修改(modified)以及新文件(new)，但不包括被删除的文件。
git add .

# 将暂存区的修改提交到dev分支
git commit -m "Here is the comment. " 
1
2
3
4
5

7.4 将暂存区修改内容推送到自己的Apollo项目分叉（Fork）

git push -f -u origin dh_dev
1

7.5 向Apollo项目主分支发送拉取请求（pull request）

打开Chrome或其他浏览器，登录你的Github账户，进入你的Apollo项目分支主页（我的主页为：https://github.com/davidhopper2003/apollo）， 按下图所示向Apollo项目主分支发送拉取请求（pull request），之后等待Apollo项目代码维护人员与你联系。如果没有问题，他们就会将你的修改合并到Apollo项目主分支。




注意：第一次提交时，还需要签订一个协议，否则Apollo项目代码维护人员无法将你的pull request合并，如下图所示：