Repo

Repo介绍

要处理 Android 代码，需要同时使用Git和Repo。

Repo是以Git为基础构建的代码库管理工具。Repo可以在必要时整合多个Git代码库，将相关内容上传到版本控制系统，并自动执行Android开发工作流程的部分环节。

Repo命令是一段可执行的Python脚本，是对Git命令的封装，可以使用Repo执行跨网络操作。

基本工作流程

与代码库进行交互的基本模式如下：

使用 repo start 新建一个主题分支。
修改文件。
使用 git add 暂存更改。
使用 git commit 提交更改。
使用 repo upload 将更改上传到审核服务器。

任务参考

以下任务列表简要总结了如何执行常见的 Repo 和 Git 任务。要了解如何使用 Repo 下载源代码，请参阅下载源代码和使用 Repo。

同步客户端

要同步所有可用项目的文件，请运行以下命令：

repo sync

要同步所选项目的文件，请运行以下命令：

repo sync PROJECT0 PROJECT1 ... PROJECTN

创建主题分支

当您开始进行更改（例如当您开始处理错误或使用新功能）时，请在本地工作环境中新建一个主题分支。主题分支不是原始文件的副本；它代表着特定提交。这样一来，您可以轻松创建本地分支并在这些分支之间切换。通过使用分支，您可以将工作的某个方面与其他方面分隔开来。请参阅分隔主题分支（一篇有关使用主题分支的趣味文章）。

要使用 Repo 新建一个主题分支，请转到要修改的项目并运行以下命令：

repo start BRANCH_NAME .

请注意，句点代表当前工作目录中的项目。要验证您的新分支是否已创建，请运行以下命令：

repo status .

使用主题分支

要将分支分配给特定项目，请运行以下命令：

repo start BRANCH_NAME PROJECT_NAME

要查看所有项目的列表，请访问 android.googlesource.com。再次提醒，如果您已转到特定的项目目录，可以简单地使用一个句点来表示当前项目。

要切换到您已在本地工作环境中创建的另一个分支，请运行以下命令：

git checkout BRANCH_NAME

要查看现有分支的列表，请运行以下命令：

git branch

或

repo branches

当前分支的名称前面将标注星号。

注意：如果存在错误，可能会导致 repo sync 重置本地主题分支。如果在您运行 repo sync 之后，git branch 显示 *（无分支），请再次运行 git checkout。

暂存文件

默认情况下，Git 会检测到您在项目中所做的更改，但不会跟踪这些更改。要让 Git 保存您的更改，您必须将更改标记为包含在提交中。这也称为“暂存”。

您可以通过运行以下命令来暂存更改：

git add

对于此命令，项目目录中的任何文件或目录都可作为参数。git add 并不像其名称表示的这样只是简单地将文件添加到 Git 代码库，它还可以用于暂存文件的修改和删除的内容。

查看客户端状态

要列出文件的状态，请运行以下命令：

repo status

要查看未提交的修改，请运行以下命令：

repo diff

如果您准备立即提交，运行 repo diff 命令可让系统显示您所做的不会被提交的每一项本地修改。如果您准备立即提交，要查看将被提交的每一项修改，则需要运行 Git 命令 git diff。在运行该命令之前，请确保您已转到项目目录下：

cd ~/WORKING_DIRECTORY/PROJECT
git diff --cached

提交更改

在 Git 中，提交是修订版本控制的基本单位，包含目录结构的快照以及整个项目的文件内容。在 Git 中创建提交很简单，只需输入以下命令即可：

git commit

系统会提示您使用惯用的编辑器提供一条提交消息；请为您提交到 AOSP 的所有更改都提供一条会有帮助作用的消息。如果您没有添加日志消息，提交将会终止。

将更改上传到 Gerrit

上传之前，请先更新为最新修订版本：

repo sync

然后运行以下命令：

repo upload

运行此命令后，系统会随即列出您已提交的更改，并提示您选择要上传到审核服务器的分支。如果只有一个分支，您会看到一个简单的 y/n 提示符。

恢复同步冲突

如果 repo sync 显示同步冲突，请执行以下操作：

查看未合并的文件（状态代码 = U）。
根据需要修改存在冲突的地方。
在相关项目目录中进行更改，为相关文件运行 git add 和 git commit，然后对这些更改执行“衍合”(rebase) 命令。例如：
```
git add .
git commit
git rebase --continue
```
当衍合完成后，再一次开始整个同步过程：
```
repo sync PROJECT0 PROJECT1 ... PROJECTN
```

清理您的客户端文件

要在更改合并到 Gerrit 中后更新您的本地工作目录，请运行以下命令：

repo sync

要安全移除已过时的主题分支，请运行以下命令：

repo prune

删除客户端

由于所有状态信息都会存储在客户端中，您只需从文件系统中删除相应目录即可：

rm -rf WORKING_DIRECTORY

删除客户端将永久删除您尚未上传以供审核的任何更改。

Git 和 Repo 快速参考表

Repo 命令参考资料

使用 Repo 需遵循的格式如下：

repo <COMMAND> <OPTIONS>

可选元素显示在方括号 [ ] 中。例如，许多命令会将项目列表用作参数。您可以为项目指定项目列表，作为名称列表或本地源代码目录的路径列表：

repo sync [<PROJECT0> <PROJECT1> <PROJECTN>]
repo sync [</PATH/TO/PROJECT0> ... </PATH/TO/PROJECTN>]

help

安装 Repo 后，您可以通过运行以下命令找到最新文档（开头是包含所有命令的摘要）：

repo help

您可以通过在 Repo 树中运行以下命令来获取有关某个命令的信息：

repo help <COMMAND>

例如，以下命令会生成 Repo init 参数的说明和选项列表，该参数会在当前目录中初始化 Repo。（要了解详情，请参阅 init。）

repo help init

init

$ repo init -u <URL> [<OPTIONS>]

在当前目录中安装 Repo。这会创建一个 .repo/ 目录，其中包含用于 Repo 源代码和标准 Android 清单文件的 Git 代码库。该 .repo/ 目录中还包含 manifest.xml，这是一个指向 .repo/manifests/ 目录中所选清单的符号链接。

选项：

-u：指定要从中检索清单代码库的网址。您可以在 https://android.googlesource.com/platform/manifest中找到常见清单
-m：在代码库中选择清单文件。如果未选择任何清单名称，则会默认选择 default.xml。
-b：指定修订版本，即特定的清单分支。

注意：对于其余的所有 Repo 命令，当前工作目录必须是 .repo/ 的父目录或相应父目录的子目录。

sync

repo sync [<PROJECT_LIST>]

下载新的更改并更新本地环境中的工作文件。如果您在未使用任何参数的情况下运行 repo sync，则该操作会同步所有项目的文件。

运行 repo sync 后，将出现以下情况：

如果目标项目从未同步过，则 repo sync 相当于 git clone。远程代码库中的所有分支都会复制到本地项目目录中。
如果目标项目已同步过，则 repo sync 相当于以下命令：
```
git remote update
git rebase origin/<BRANCH>
```
其中 <BRANCH> 是本地项目目录中当前已检出的分支。如果本地分支没有在跟踪远程代码库中的分支，则相应项目不会发生任何同步。
如果 git rebase 操作导致合并冲突，那么您需要使用普通 Git 命令（例如 git rebase --continue）来解决冲突。

repo sync 运行成功后，指定项目中的代码会与远程代码库中的代码保持同步。

选项：

-d：将指定项目切换回清单修订版本。如果项目当前属于某个主题分支，但只是临时需要清单修订版本，则此选项会有所帮助。
-s：同步到当前清单中清单服务器元素指定的一个已知的良好版本。
-f：即使某个项目同步失败，系统也会继续同步其他项目。

upload

repo upload [<PROJECT_LIST>]

对于指定的项目，Repo 会将本地分支与最后一次 repo sync 时更新的远程分支进行比较。Repo 会提示您选择一个或多个尚未上传以供审核的分支。

您选择一个或多个分支后，所选分支上的所有提交都会通过 HTTPS 连接传输到 Gerrit。您需要配置一个 HTTPS 密码以启用上传授权。要生成新的用户名/密码对以用于 HTTPS 传输，请访问密码生成器。

当 Gerrit 通过其服务器接收对象数据时，它会将每项提交转变成一项更改，以便审核者可以单独针对每项提交给出意见。要将几项“检查点”提交合并为一项提交，请使用 git rebase -i，然后再运行 repo upload。

如果您在未使用任何参数的情况下运行 repo upload，则该操作会搜索所有项目中的更改以进行上传。

要在更改上传之后对其进行修改，您应该使用 git rebase -i 或 git commit --amend 等工具更新您的本地提交。修改完成之后，请执行以下操作：

进行核对以确保更新后的分支是当前已检出的分支。

对于相应系列中的每项提交，请在方括号内输入 Gerrit 更改 ID：

# Replacing from branch foo
[ 3021 ] 35f2596c Refactor part of GetUploadableBranches to lookup one specific...
[ 2829 ] ec18b4ba Update proto client to support patch set replacments
# Insert change numbers in the brackets to add a new patch set.
# To create a new change record, leave the brackets empty.

上传完成后，这些更改将拥有一个额外的补丁程序集。

diff

repo diff [<PROJECT_LIST>]

使用 git diff 显示提交与工作树之间的明显更改。

download

repo download <TARGET> <CHANGE>

从审核系统中下载指定更改，并放在您项目的本地工作目录中供使用。

例如，要将更改 23823 下载到您的平台/编译目录，请运行以下命令：

$ repo download platform/build 23823

repo sync 应该可以有效移除通过 repo download 检索到的任何提交。或者，您可以将远程分支检出，例如 git checkout m/master。

注意：由于全球的所有服务器均存在复制延迟，因此某项更改（位于 Gerrit 中）出现在网络上的时间与所有用户可通过 repo download 找到此项更改的时间之间存在些许的镜像延迟。

forall

repo forall [<PROJECT_LIST>] -c <COMMAND>

在每个项目中运行指定的 shell 命令。通过 repo forall 可使用下列额外的环境变量：

REPO_PROJECT 可设为项目的具有唯一性的名称。
REPO_PATH 是客户端根目录的相对路径。
REPO_REMOTE 是清单中远程系统的名称。
REPO_LREV 是清单中修订版本的名称，已转换为本地跟踪分支。如果您需要将清单修订版本传递到某个本地运行的 Git 命令，则可使用此变量。
REPO_RREV 是清单中修订版本的名称，与清单中显示的名称完全一致。

选项：

-c：要运行的命令和参数。此命令会通过 /bin/sh 进行求值，它之后的任何参数都将作为 shell 位置参数传递。
-p：在指定命令输出结果之前显示项目标头。这通过以下方式实现：将管道绑定到命令的 stdin、stdout 和 sterr 流，然后通过管道将所有输出结果传输到一个页面调度会话中显示的连续流中。
-v：显示该命令向 stderr 写入的消息。

prune

repo prune [<PROJECT_LIST>]

删减（删除）已合并的主题。

start

repo start <BRANCH_NAME> [<PROJECT_LIST>]

从清单中指定的修订版本开始，创建一个新的分支进行开发。

*<BRANCH_NAME>* 参数应简要说明您尝试对项目进行的更改。如果您不知道，则不妨考虑使用默认名称。

*<PROJECT_LIST>* 指定了将参与此主题分支的项目。

注意：“.”是一个非常实用的简写形式，用来代表当前工作目录中的项目。

status

repo status [<PROJECT_LIST>]

对于每个指定的项目，将工作树与临时区域（索引）以及此分支 (HEAD) 上的最近一次提交进行比较。在这三种状态存在差异之处显示每个文件的摘要行。

要仅查看当前分支的状态，请运行 repo status。系统会按项目列出状态信息。对于项目中的每个文件，系统使用两个字母的代码来表示：

在第一列中，大写字母表示临时区域与上次提交状态之间的不同之处。

字母	含义	说明
-	无更改	HEAD 与索引中相同
A	已添加	不存在于 HEAD 中，但存在于索引中
M	已修改	存在于 HEAD 中，但索引中的文件已修改
D	已删除	存在于 HEAD 中，但不存在于索引中
R	已重命名	不存在于 HEAD 中，但索引中的文件的路径已更改
C	已复制	不存在于 HEAD 中，已从索引中的另一个文件复制
T	模式已更改	HEAD 与索引中的内容相同，但模式已更改
U	未合并	HEAD 与索引之间存在冲突；需要解决方案

在第二列中，小写字母表示工作目录与索引之间的不同之处。

字母	含义	说明
-	新/未知	不存在于索引中，但存在于工作树中
m	已修改	存在于索引中，也存在于工作树中（但已修改）
d	已删除	存在于索引中，不存在于工作树中

下载源代码

Android 源代码树位于由 Google 托管的 Git 代码库中。Git 代码库中包含 Android 源代码的元数据，其中包括与对源代码进行的更改以及更改日期相关的元数据。本文档介绍了如何下载特定 Android 代码流水线的源代码树。

要从特定设备的出厂映像开始，请参阅选择设备版本。

安装 Repo

Repo 是一款工具，可让您在 Android 环境中更轻松地使用 Git。要详细了解 Repo，请参阅开发部分。

要安装 Repo，请执行以下操作：

确保主目录下有一个 bin/ 目录，并且该目录包含在路径中：
```
mkdir ~/bin
PATH=~/bin:$PATH
```

下载 Repo 工具，并确保它可执行：

curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

对于 1.21 版，Repo 的 SHA-1 校验和为 b8bd1804f432ecf1bab730949c82b93b0fc5fede

对于 1.22 版，Repo 的 SHA-1 校验和为 da0514e484f74648a890c0467d61ca415379f791

对于 1.23 版，Repo 的 SHA-256 校验和为 e147f0392686c40cfd7d5e6f332c6ee74c4eab4d24e2694b3b0a0c037bf51dc5

初始化 Repo 客户端

安装 Repo 后，设置您的客户端以访问 Android 源代码代码库：

创建一个空目录来存放您的工作文件。如果您使用的是 MacOS，必须在区分大小写的文件系统中创建该目录。为其指定一个您喜欢的任意名称：
```
mkdir WORKING_DIRECTORY
cd WORKING_DIRECTORY
```
使用您的真实姓名和电子邮件地址配置 Git。要使用 Gerrit 代码审核工具，您需要一个与已注册的 Google 帐号关联的电子邮件地址。确保这是您可以接收邮件的有效地址。您在此处提供的姓名将显示在您提交的代码的提供方信息中。
```
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```
运行 repo init 以获取最新版本的 Repo 及其最近的所有错误更正内容。您必须为清单指定一个网址，该网址用于指定 Android 源代码中包含的各个代码库将位于工作目录中的什么位置。
```
repo init -u https://android.googlesource.com/platform/manifest
```
要对“master”以外的分支进行校验，请使用 -b 来指定相应分支。要查看分支列表，请参阅源代码标记和版本。
```
repo init -u https://android.googlesource.com/platform/manifest -b android-4.0.1_r1
```

初始化成功后，系统将显示一条消息，告诉您 Repo 已在工作目录中完成初始化。客户端目录中现在应包含一个 .repo 目录，清单等文件将保存在该目录下。

下载 Android 源代码树

要将 Android 源代码树从默认清单中指定的代码库下载到工作目录，请运行以下命令：

repo sync

Android 源代码文件将位于工作目录中对应的项目名称下。初始同步操作将需要 1 个小时或更长时间才能完成。要详细了解 repo sync 和其他 Repo 命令，请参阅开发部分。

使用身份验证

默认情况下，访问 Android 源代码均为匿名操作。为了防止服务器被过度使用，每个 IP 地址都有一个相关联的配额。

当与其他用户共用一个 IP 地址时（例如，在越过 NAT 防火墙访问源代码代码库时），系统甚至会针对常规使用模式（例如，许多用户在短时间内从同一个 IP 地址同步新客户端）触发配额。

在这种情况下，可以使用进行身份验证的访问方式，此类访问方式会对每位用户使用单独的配额，而不考虑 IP 地址。

第一步是使用密码生成器生成密码，然后按照密码生成器页面中的说明进行操作。

第二步是通过使用以下清单 URI，强制使用进行身份验证的访问方式：https://android.googlesource.com/a/platform/manifest。请注意 /a/ 目录前缀如何触发强制性身份验证。您可以通过以下命令将现有客户端转换为使用强制性身份验证：

repo init -u https://android.googlesource.com/a/platform/manifest

排查网络问题

在使用代理的情况下下载内容（在一些企业环境中很常见）时，您可能需要明确指定 Repo 随后使用的代理：

export HTTP_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
export HTTPS_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>

一种比较少见的情况是，Linux 客户端遇到连接问题，在下载期间（通常是在“正在接收对象”期间）被卡住。有人曾报告称，调整 TCP/IP 堆栈的设置并使用非并行命令可以改善这种情况。您需要拥有 root 权限才能修改 TCP 设置：

sudo sysctl -w net.ipv4.tcp_window_scaling=0
repo sync -j1

使用本地镜像

当您使用多个客户端时（尤其是在带宽不足的情况下），最好为所有服务器内容创建一个本地镜像，并从该镜像同步客户端（不需要访问网络）。一个完整镜像的下载文件比两个客户端的下载文件要小一些，而且包含更多信息。

以下说明假定在 /usr/local/aosp/mirror 中创建镜像。第一步是创建并同步镜像本身。请注意 --mirror 标志，该标志只能在创建新客户端时指定：

mkdir -p /usr/local/aosp/mirror
cd /usr/local/aosp/mirror
repo init -u https://android.googlesource.com/mirror/manifest --mirror
repo sync

同步镜像后，您就可以从镜像创建新客户端了。请注意，务必要指定一个绝对路径：

mkdir -p /usr/local/aosp/master
cd /usr/local/aosp/master
repo init -u /usr/local/aosp/mirror/platform/manifest.git
repo sync

最后，要将客户端与服务器同步，您需要将镜像与服务器同步，然后再将客户端与镜像同步：

cd /usr/local/aosp/mirror
repo sync
cd /usr/local/aosp/master
repo sync

您可以将镜像存储在 LAN 服务器上，然后通过 NFS、SSH 或 Git 访问它。您还可以将其存储在移动存储盘上，并在用户之间或计算机之间传用该存储盘。

验证 Git 标记

将以下公钥加载到您的 GnuPG 密钥数据库中。该密钥用于签署代表各版本的带注释标记。

gpg --import

复制并粘贴以下密钥，然后输入 EOF (Ctrl-D) 以结束输入并处理密钥。

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

mQGiBEnnWD4RBACt9/h4v9xnnGDou13y3dvOx6/t43LPPIxeJ8eX9WB+8LLuROSV
lFhpHawsVAcFlmi7f7jdSRF+OvtZL9ShPKdLfwBJMNkU66/TZmPewS4m782ndtw7
8tR1cXb197Ob8kOfQB3A9yk2XZ4ei4ZC3i6wVdqHLRxABdncwu5hOF9KXwCgkxMD
u4PVgChaAJzTYJ1EG+UYBIUEAJmfearb0qRAN7dEoff0FeXsEaUA6U90sEoVks0Z
wNj96SA8BL+a1OoEUUfpMhiHyLuQSftxisJxTh+2QclzDviDyaTrkANjdYY7p2cq
/HMdOY7LJlHaqtXmZxXjjtw5Uc2QG8UY8aziU3IE9nTjSwCXeJnuyvoizl9/I1S5
jU5SA/9WwIps4SC84ielIXiGWEqq6i6/sk4I9q1YemZF2XVVKnmI1F4iCMtNKsR4
MGSa1gA8s4iQbsKNWPgp7M3a51JCVCu6l/8zTpA+uUGapw4tWCp4o0dpIvDPBEa9
b/aF/ygcR8mh5hgUfpF9IpXdknOsbKCvM9lSSfRciETykZc4wrRCVGhlIEFuZHJv
aWQgT3BlbiBTb3VyY2UgUHJvamVjdCA8aW5pdGlhbC1jb250cmlidXRpb25AYW5k
cm9pZC5jb20+iGAEExECACAFAknnWD4CGwMGCwkIBwMCBBUCCAMEFgIDAQIeAQIX
gAAKCRDorT+BmrEOeNr+AJ42Xy6tEW7r3KzrJxnRX8mij9z8tgCdFfQYiHpYngkI
2t09Ed+9Bm4gmEO5Ag0ESedYRBAIAKVW1JcMBWvV/0Bo9WiByJ9WJ5swMN36/vAl
QN4mWRhfzDOk/Rosdb0csAO/l8Kz0gKQPOfObtyYjvI8JMC3rmi+LIvSUT9806Up
hisyEmmHv6U8gUb/xHLIanXGxwhYzjgeuAXVCsv+EvoPIHbY4L/KvP5x+oCJIDbk
C2b1TvVk9PryzmE4BPIQL/NtgR1oLWm/uWR9zRUFtBnE411aMAN3qnAHBBMZzKMX
LWBGWE0znfRrnczI5p49i2YZJAjyX1P2WzmScK49CV82dzLo71MnrF6fj+Udtb5+
OgTg7Cow+8PRaTkJEW5Y2JIZpnRUq0CYxAmHYX79EMKHDSThf/8AAwUIAJPWsB/M
pK+KMs/s3r6nJrnYLTfdZhtmQXimpoDMJg1zxmL8UfNUKiQZ6esoAWtDgpqt7Y7s
KZ8laHRARonte394hidZzM5nb6hQvpPjt2OlPRsyqVxw4c/KsjADtAuKW9/d8phb
N8bTyOJo856qg4oOEzKG9eeF7oaZTYBy33BTL0408sEBxiMior6b8LrZrAhkqDjA
vUXRwm/fFKgpsOysxC6xi553CxBUCH2omNV6Ka1LNMwzSp9ILz8jEGqmUtkBszwo
G1S8fXgE0Lq3cdDM/GJ4QXP/p6LiwNF99faDMTV3+2SAOGvytOX6KjKVzKOSsfJQ
hN0DlsIw8hqJc0WISQQYEQIACQUCSedYRAIbDAAKCRDorT+BmrEOeCUOAJ9qmR0l
EXzeoxcdoafxqf6gZlJZlACgkWF7wi2YLW3Oa+jv2QSTlrx4KLM=
=Wi5D
-----END PGP PUBLIC KEY BLOCK-----

导入密钥后，您可以通过以下命令验证任何标记：

git tag -v TAG_NAME

如果您尚未设置 ccache，现在是设置它的一个好时机。

配置清单

Android源代码

https://android.googlesource.com/platform/manifest

分支内容

配置清单

配置清单包含的内容：

remote：远程代码配置
- name：远程仓库名
- fetch：远程仓库地址
- review：
default：默认配置
- remote：默认的远程仓库
- revision：默认使用的分支
- sync-j：同步代码时的并发数
project：当个代码库配置
- name：项目地址，和指定的remote节点中的fetch一起组成仓库地址
- path：项目拉取到本地所在的目录
- groups：项目所属分组
- remote：指定的远程仓库
- revision：指定代码分支
project的子节点：
- copyfile：执行拷贝操作
- linkfile：建立软连接