4.6.1. 关于repo¶

Repo是Google开发的用于管理Android版本库的一个工具。Repo并不是用于取代Git，是用Python对Git进行了一定的封装，简化了对多个Git版本库的管理。对于repo管理的任何一个版本库，都还是需要使用Git命令进行操作。

repo的使用过程大致如下：

• 运行repo init命令，克隆Android的一个清单库。这个清单库和前面假设的“子模组”方式工作的索引库不同，是通过XML技术建立的版本库清单。
• 清单库中的manifest.xml文件，列出了160多个版本库的克隆方式。包括版本库的地址和工作区地址的对应关系，以及分支的对应关系。
• 运行repo sync命令，开始同步，即分别克隆这160多个版本库到本地的工作区中。
• 同时对160多个版本库执行切换分支操作，切换到某个分支。

4.6.2. 安装repo¶

首先下载repo的引导脚本，可以使用wget、curl甚至浏览器从地址http://android.git.kernel.org/repo下载。把repo脚本设置为可执行，并复制到可执行的路径中。在Linux上可以用下面的指令将repo下载并复制到用户主目录的bin目录下。

$ curl http://android.git.kernel.org/repo > ~/bin/repo
$ chmod a+x ~/bin/repo

为什么说下载的repo只是一个引导脚本（bootstrap）而不是直接称为repo呢？因为repo的大部分功能代码不在其中，下载的只是一个帮助完成整个repo程序的继续下载和加载工具。如果您是一个程序员，对repo的执行比较好奇，可以一起分析一下repo引导脚本。否则可以跳到下一节。

看看repo引导脚本的前几行（为方便描述，把注释和版权信息过滤掉了），会发现一个神奇的魔法：

1   #!/bin/sh
2
3   REPO_URL='git://android.git.kernel.org/tools/repo.git'
4   REPO_REV='stable'
5
6   magic='--calling-python-from-/bin/sh--'
7   """exec" python -E "$0" "$@" """#$magic"
8   if __name__ == '__main__':
9     import sys
10    if sys.argv[-1] == '#%s' % magic:
11      del sys.argv[-1]
12  del magic

Repo引导脚本是用什么语言开发的？这是一个问题。

• 第1行，有经验的Linux开发者会知道此脚本是用Shell脚本语言开发的。
• 第7行，是这个魔法的最神奇之处。既是一条合法的shell语句，又是一条合法的python语句。
• 第7行作为shell语句，执行exec，用python调用本脚本，并替换本进程。三引号在这里相当于一个空字串和一个单独的引号。
• 第7行作为python语句，三引号定义的是一个字符串，字符串后面是一个注释。
• 实际上第1行到第7行，即是合法的shell语句又是合法的python语句。从第8行开始后面都是python脚本了。
• Repo引导脚本无论是使用shell执行，或是用python执行，效果都相当于使用python执行此脚本。

Repo真正的位置在哪里？

在引导脚本repo的main函数，首先调用`` _FindRepo``函数，从当前目录开始依次向上递归查找.repo/repo/main.py文件。

def main(orig_args):
  main, dir = _FindRepo()

函数_FindRepo返回找到的.repo/repo/main.py脚本文件，以及包含repo/main.py的.repo目录。如果找到.repo/repo/main.py脚本，则把程序的控制权交给.repo/repo/main.py脚本。（省略了在repo开发库中执行情况的判断）

在下载repo引导脚本后，没有初始化之前，当然不会存在.repo/repo/main.py脚本，这时必须进行初始化操作。

4.6.3. repo和清单库的初始化¶

下载并保存repo引导脚本后，建立一个工作目录，这个工作目录将作为Android的工作区目录。在工作目录中执行repo init -u <url>完成repo完整的下载以及项目清单版本库（manifest.git）的下载。

$ mkdir working-directory-name
$ cd working-directory-name
$ repo init -u git://android.git.kernel.org/platform/manifest.git

命令repo init要完成如下操作：

• 完成repo这一工具的完整下载，因为现在有的不过是repo的引导程序。

  初始化操作会从Android的代码中克隆repo.git库，到当前目录下的.repo/repo目录下。在完成repo.git克隆之后，repo init命令会将控制权交给工作区的.repo/repo/main.py这个刚刚从repo.git库克隆来的脚本文件，继续进行初始化。

• 克隆 android 的清单库 manifest.git（地址来自于 -u 参数）。

  克隆的清单库位于.repo/manifests.git中，并本地克隆到.repo/manifests。清单文件.repo/manifest.xml是符号链接指向.repo/manifests/default.xml。

• 提问用户的姓名和邮件地址，如果和Git缺省的用户名、邮件地址不同，则记录在.repo/manifests.git库的 config 文件中。

• 命令repo init还可以附带--mirror参数，以建立和上游Android的版本库一模一样的镜像。会在后面的章节介绍。

从哪里下载repo.git？

在repo引导脚本的前几行，定义了缺省的repo.git的版本库位置以及要检出的缺省分支。

REPO_URL='git://android.git.kernel.org/tools/repo.git'
REPO_REV='stable'

如果不想从缺省任务获取repo，或者不想获取稳定版（stable分支）的repo，可以在repo init命令中通过下面的参数覆盖缺省的设置，从指定的源地址克隆repo代码库。

• 参数--repo-url，用于设定repo的版本库地址。
• 参数--repo-branch，用于设定要检出的分支。
• 参数--no-repo-verify，设定不要对repo的里程碑签名进行严格的验证。

实际上，完成repo.git版本库的克隆，这个repo引导脚本就江郎才尽了，init命令的后续处理（以及其他命令）都交给刚刚克隆出来的.repo/repo/main.py来继续执行。

清单库是什么？从哪里下载？

清单库实际上只包含一个default.xml文件。这个XML文件定义了多个版本库和本地地址的映射关系，是repo工作的指引文件。所以在使用repo引导脚本进行初始化的时候，必须通过-u参数指定清单库的源地址。

清单库的下载，是通过repo init命令初始化时，用-u参数指定清单库的位置。例如repo针对Android代码库进行初始化时执行的命令：

$ repo init -u git://android.git.kernel.org/platform/manifest.git

Repo引导脚本的`` init``命令可以使用下列和清单库相关的参数：

• 参数-u（--manifest-url）：设定清单库的Git服务器地址。
• 参数-b（--manifest-branch）：检出清单库特定分支。
• 参数--mirror：只在repo第一次初始化的时候使用，以和Android服务器同样的结构在本地建立镜像。
• 参数-m（--manifest-name）：当有多个清单文件，可以指定清单库的某个清单文件为有效的清单文件。缺省为default.xml。

Repo初始化命令（repo init）可以执行多次：

• 不带参数的执行repo init，从上游的清单库获取新的清单文件default.xml。
• 使用参数-u（--manifest-url）执行repo init，会重新设定上游的清单库地址，并重新同步。
• 使用参数-b（--manifest-branch）执行repo init，会使用清单库的不同分支，以便在使用repo sync时将项目同步到不同的里程碑。
• 但是不能使用--mirror命令，该命名只能在第一次初始化时执行。那么如何将已经按照工作区模式同步的版本库转换为镜像模式呢？会在后面看到一个解决方案。

4.6.4. 清单库和清单文件¶

当执行完毕repo init之后，工作目录内空空如也。实际上有一个.repo目录。在该目录下除了一个包含repo的实现的repo库克隆外，就是manifest库的克隆，以及一个符号链接链接到清单库中的default.xml文件。

$ ls -lF .repo/
drwxr-xr-x 3 jiangxin jiangxin 4096 2010-10-11 18:57 manifests/
drwxr-xr-x 8 jiangxin jiangxin 4096 2010-10-11 10:08 manifests.git/
lrwxrwxrwx 1 jiangxin jiangxin   21 2010-10-11 10:07 manifest.xml -> manifests/default.xml
drwxr-xr-x 7 jiangxin jiangxin 4096 2010-10-11 10:07 repo/

在工作目录下的.repo/manifest.xml文件就是Android项目的众多版本库的清单文件。Repo命令的操作，都要参考这个清单文件。

打开清单文件，会看到如下内容：

  1  <?xml version="1.0" encoding="UTF-8"?>
  2  <manifest>
  3    <remote  name="korg"
  4             fetch="git://android.git.kernel.org/"
  5             review="review.source.android.com" />
  6    <default revision="master"
  7             remote="korg" />
  8
  9    <project path="build" name="platform/build">
 10      <copyfile src="core/root.mk" dest="Makefile" />
 11    </project>
 12
 13    <project path="bionic" name="platform/bionic" />

       ...

181  </manifest>

这个文件不太复杂，是么？

• 这个XML的顶级元素是manifest，见第2行和第181行。
• 第3行通过一个remote元素，定义了名为korg（kernel.org缩写）的源，其Git库的基址为git://android.git.kernel.org/，还定义了代码审核服务器的地址review.source.android.com。还可以定义更多的remote元素，这里只定义了一个。
• 第6行用于设置各个项目缺省的远程源地址（remote）为korg，缺省的分支为master。当然各个项目（project元素）可以定义自己的remote和revision覆盖该缺省配置。
• 第9行定义一个项目，该项目的远程版本库相对路径为：”platform/build”，在工作区克隆的位置为：”build”。
• 第10行，即project元素的子元素copyfile，定义了项目克隆后的一个附加动作：拷贝文件从core/root.mk至Makefile。
• 第13行后后续的100多行定义了其他160个项目，都是采用类似的project元素语法。name参数定义远程版本库的相对路径，path参数定义克隆到本地工作区的路径。
• 还可以出现manifest-server元素，其url属性定义了通过XMLRPC提供实时更新清单的服务器URL。只有当执行repo sync –smart-sync的时候，才会检查该值，并用动态获取的manifest覆盖掉缺省的清单。

4.6.5. 同步项目¶

在工作区，执行下面的命令，会参照.repo/manifest.xml清单文件，将项目所有相关的版本库全部克隆出来。不过最好请在读完本节内容之后再尝试执行这条命令。

$ repo sync

对于Android，这个操作需要通过网络传递接近2个GB的内容，如果带宽不是很高的话，可能会花掉几个小时甚至是一天的时间。

也可以仅克隆感兴趣的项目，在repo sync后面跟上项目的名称。项目的名称来自于.repo/manifest.xml这个XML文件中project元素的name属性值。例如克隆platform/build项目：

$ repo sync platform/build

Repo有一个功能可以在这里展示。就是repo支持通过本地清单，对缺省的清单文件进行补充以及覆盖。即可以在.repo目录下创建local_manifest.xml文件，其内容会和.repo/manifest.xml文件的内容进行合并。

在工作目录下运行下面的命令，可以创建一个本地清单文件。这个本地定制的清单文件来自缺省文件，但是删除了remote元素和default元素，并将所有的project元素都重命名为remove-project元素。这实际相当于对原有的清单文件“取反”。

$ sed -e '/<remote/,+4 d' -e 's/<project/<remove-project/g' \
  -e 's/project>/remove-project>/g' \
  < .repo/manifest.xml > .repo/local_manifest.xml

用下面的这条命令可以看到repo运行时实际获取到的清单。这个清单来自于.repo/manifest.xml和.repo/local_manifest.xml两个文件的汇总。

$ repo manifest -o -

当执行repo sync命令时，实际上就是依据合并后的清单文件进行同步。如果清单中的项目被自定义清单全部“取反”，执行同步就不会同步任何项目，甚至会删除已经完成同步的项目。

本地定制的清单文件local_manifest.xml支持前面介绍的清单文件的所有语法，需要注意的是：

• 不能出现重复定义的remote元素。这就是为什么上面的脚本要删除来自缺省manifest.xml的remote元素。
• 不能出现default元素，仅为全局仅能有一个。
• 不能出现重复的project定义（name属性不能相同），但是可以通过remove-project元素将缺省清单中定义的project删除再重新定义。

试着编辑.repo/local_manifest.xml，在其中再添加几个project元素，然后试着用repo sync命令进行同步。

4.6.6. 建立Android代码库本地镜像¶

Android为企业提供一个新的市场，无论大企业，小企业都是处于同一个起跑线上。研究Android尤其是Android系统核心或者是驱动的开发，首先需要做的就是本地克隆建立一套Android版本库管理机制。因为Android的代码库是那么庞杂，如果一个开发团队每个人都去执行repo init -u，再执行repo sync从Android服务器克隆版本库的话，多大的网络带宽恐怕都不够用。唯一的办法是本地建立一个Android版本库的镜像。

建立本地镜像非常简单，就是在执行repo init -u初始化的时候，附带上--mirror参数。

$ mkdir android-mirror-dir
$ cd android-mirror-dir
$ repo init --mirror -u git://android.git.kernel.org/platform/manifest.git

之后执行repo sync就可以安装Android的Git服务器方式来组织版本库，创建一个Android版本库镜像。

实际上附带了--mirror参数执行repo init -u命令，会在克隆的.repo/manifests.git下的config中记录配置信息：

[repo]
    mirror = true

从Android的工作区到代码库镜像

在初始化repo工作区时，如果使用不带--mirror参数的repo init -u，并完成代码同步后，如果再次执行repo init并附带了--mirror参数，repo 会报错退出：“fatal: –mirror not supported on existing client”。实际上--mirror参数只能对尚未初始化的repo工作区执行。

那么如果之前没有用镜像的方法同步Android版本库，难道要为创建代码库镜像再重新执行一次repo同步么？要知道重新同步一份Android版本库是非常慢的。我就遇到了这个问题。

不过既然有manifest.xml`文件，完全可以对工作区进行反向操作，将工作区转换为镜像服务器的结构。下面就是一个示例脚本，这个脚本利用了已有的repo代码进行实现，所以看着很简洁。8-)

脚本work2mirror.py如下：

#!/usr/bin/python
# -*- coding: utf-8 -*-

import os, sys, shutil

cwd = os.path.abspath( os.path.dirname( __file__ ) )
repodir = os.path.join( cwd, '.repo' )
S_repo = 'repo'
TRASHDIR = 'old_work_tree'

if not os.path.exists( os.path.join(repodir, S_repo) ):
    print >> sys.stderr, "Must run under repo work_dir root."
    sys.exit(1)

sys.path.insert( 0, os.path.join(repodir, S_repo) )
from manifest_xml import XmlManifest

manifest = XmlManifest( repodir )

if manifest.IsMirror:
    print >> sys.stderr, "Already mirror, exit."
    sys.exit(1)

trash = os.path.join( cwd, TRASHDIR )

for project in manifest.projects.itervalues():
    # 移动旧的版本库路径到镜像模式下新的版本库路径
    newgitdir = os.path.join( cwd, '%s.git' % project.name )
    if os.path.exists( project.gitdir ) and project.gitdir != newgitdir:
        if not os.path.exists( os.path.dirname(newgitdir) ):
            os.makedirs( os.path.dirname(newgitdir) )
        print "Rename %s to %s." % (project.gitdir, newgitdir)
        os.rename( project.gitdir, newgitdir )

    # 移动工作区到待删除目录
    if project.worktree and os.path.exists( project.worktree ):
        newworktree = os.path.join( trash, project.relpath )
        if not os.path.exists( os.path.dirname(newworktree) ):
            os.makedirs( os.path.dirname(newworktree) )
        print "Move old worktree %s to %s." % (project.worktree, newworktree )
        os.rename( project.worktree, newworktree )

    if os.path.exists ( os.path.join( newgitdir, 'config' ) ):
        # 修改版本库的配置
        os.chdir( newgitdir )
        os.system( "git config core.bare true" )
        os.system( "git config remote.korg.fetch '+refs/heads/*:refs/heads/*'" )

        # 删除 remotes 分支，因为作为版本库镜像不需要 remote 分支
        if os.path.exists ( os.path.join( newgitdir, 'refs', 'remotes' ):
            print "Delete " + os.path.join( newgitdir, 'refs', 'remotes' )
            shutil.rmtree( os.path.join( newgitdir, 'refs', 'remotes') )

# 设置 menifest 为镜像
mp = manifest.manifestProject
mp.config.SetString('repo.mirror', 'true')

使用方法很简单，只要将脚本放在Android工作区下，执行就可以了。执行完毕会将原有工作区的目录移动到old_work_tree子目录下，在确认原有工作区没有未提交的数据后，直接删除old_work_tree即可。

$ python work2mirror.py

创建新的清单库，或修改原有清单库

建立了Android代码库的本地镜像后，如果不对manifest清单版本库进行定制，在使用repo sync同步代码的时候，仍然使用Android官方的代码库同步代码，使得本地的镜像版本库形同虚设。解决办法是创建一个自己的manifest库，或者在原有清单库中建立一个分支加以修改。如果创建新的清单库，参考Android上游的manifest清单库进行创建。

4.6.7. Repo的命令集¶

Repo命令实际上是Git命令的简单或者复杂的封装。每一个repo命令都对应于repo源码树中subcmds目录下的一个同名的Python脚本。每一个repo命令都可以通过下面的命令获得帮助。

$ repo help <command>

通过阅读代码，可以更加深入的了解repo命令的封装。

repo start <newbranchname> [--all | <project>...]

repo status [<project>...]

project repo/                                   branch devwork
 -m     subcmds/status.py
 ...

repo checkout <branchname> [<project>...]

repo branches [<project>...]

*P nocolor                   | in repo
   repo2                     |

repo diff [<project>...]

repo stage -i [<project>...]

repo upload [--re --cc] {[<project>]... | --replace <project>}

参数：
  -h, --help            显示帮助信息。
  -t                    发送本地分支名称到 Gerrit 代码审核服务器。
  --replace             发送此分支的更新补丁集。注意使用该参数，只能指定一个项目。
  --re=REVIEWERS, --reviewers=REVIEWERS
                        要求由指定的人员进行审核。
  --cc=CC               同时发送通知到如下邮件地址。

repo upload --replace project_name

git push --receive-pack='gerrit receive-pack --reviewer charlie@example.com' \
         ssh://review.example.com:29418/project HEAD:refs/for/master

repo download {project change[/patchset]}...

命令行: repo rebase {[<project>...] | -i <project>...}

参数:
  -h, --help          显示帮助并退出
  -i, --interactive   交互式的变基（仅对一个项目时有效）
  -f, --force-rebase  向 git rebase 命令传递 --force-rebase 参数
  --no-ff             向 git rebase 命令传递 -no-ff 参数
  -q, --quiet         向 git rebase 命令传递 --quiet 参数
  --autosquash        向 git rebase 命令传递 --autosquash  参数
  --whitespace=WS     向 git rebase 命令传递 --whitespace  参数

repo prune [<project>...]

repo abandon <branchname> [<project>...]

4.6.8. Repo命令的工作流¶

图25-1是repo的工作流，每一个代码贡献都起始于repo start创建本地工作分支，最终都以repo upload命令将代码补丁发布于代码审核服务器。

图25-1：repo工作流

4.6.9. 好东西不能Android独享¶

通过前面的介绍能够体会到repo的精巧——repo巧妙的实现了多Git版本库的管理。因为repo使用了清单版本库，所以repo这一工具并没有被局限于Android项目，可以在任何项目中使用。下面就介绍三种repo的使用模式，将repo引入自己的（非Android）项目中，其中第三种repo使用模式是用作者改造后的repo实现脱离Gerrit服务器进行推送。

$ curl http://github.com/ossxp-com/repo/raw/master/repo > ~/bin/repo
$ chmod a+x ~/bin/repo

$ mkdir test
$ cd test
$ repo init -u git://github.com/ossxp-com/manifest.git
$ repo sync

$ mkdir test
$ cd test
$ repo init --repo-url=git://github.com/ossxp-com/repo.git \
  --repo-branch=master --no-repo-verify \
  -u git://github.com/ossxp-com/manifest.git
$ repo sync

$ make
Version of test1:    1:0.2-dev
Version of test2:    2:0.2
Version of manifest: current

$ repo config repo.pushurl ssh://git@github.com/ossxp-com/

$ repo config repo.pushurl
ssh://git@github.com/ossxp-com/

$ repo start jiangxin --all

$ repo branches
*  jiangxin                  | in all projects

$ cd test/test1
$ echo "1:0.2-jiangxin" > version
$ git diff
diff --git a/version b/version
index 37c65f8..a58ac04 100644
--- a/version
+++ b/version
@@ -1 +1 @@
-1:0.2-dev
+1:0.2-jiangxin
$ repo status
# on branch jiangxin
project test/test1/                             branch jiangxin
 -m     version
$ git add -u
$ git commit -m "0.2-dev -> 0.2-jiangxin"

$ make
Version of test1:    1:0.2-jiangxin
Version of test2:    2:0.2-jiangxin
Version of manifest: current

$ repo push

# Uncomment the branches to upload:
#
# project test/test1/:
#  branch jiangxin ( 1 commit, Mon Oct 25 18:04:51 2010 +0800):
#         4f941239 0.2-dev -> 0.2-jiangxin
#
# project test/test2/:
#  branch jiangxin ( 1 commit, Mon Oct 25 18:06:51 2010 +0800):
#         86683ece 0.2-dev -> 0.2-jiangxin

# Uncomment the branches to upload:


#
# project test/test1/:
branch jiangxin ( 1 commit, Mon Oct 25 18:04:51 2010 +0800):
#         4f941239 0.2-dev -> 0.2-jiangxin
#
# project test/test2/:
branch jiangxin ( 1 commit, Mon Oct 25 18:06:51 2010 +0800):
#         86683ece 0.2-dev -> 0.2-jiangxin

Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 293 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To ssh://git@github.com/ossxp-com/test1.git
   27aee23..4f94123  jiangxin -> master
Counting objects: 5, done.
Writing objects: 100% (3/3), 261 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To ssh://git@github.com/ossxp-com/test2.git
   7f0841d..86683ec  jiangxin -> master

--------------------------------------------
[OK    ] test/test1/     jiangxin
[OK    ] test/test2/     jiangxin

$ repo push
no branches ready for upload

$ repo start feature1 --all
$ repo push --new_branch

Total 0 (delta 0), reused 0 (delta 0)
To ssh://git@github.com/ossxp-com/test1.git
 * [new branch]      feature1 -> feature1
Total 0 (delta 0), reused 0 (delta 0)
To ssh://git@github.com/ossxp-com/test2.git
 * [new branch]      feature1 -> feature1

--------------------------------------------
[OK    ] test/test1/     feature1
[OK    ] test/test2/     feature1

$ git ls-remote git://github.com/ossxp-com/test1.git refs/heads/*
4f9412399bf8093e880068477203351829a6b1fb        refs/heads/feature1
4f9412399bf8093e880068477203351829a6b1fb        refs/heads/master
b2b246b99ca504f141299ecdbadb23faf6918973        refs/heads/test-0.1

$ mkdir test-0.1
$ cd test-0.1
$ repo init -u git://github.com/ossxp-com/manifest.git -b test-0.1
$ repo sync

$ make
Version of test1:    1:0.1.4
Version of test2:    2:0.1.3-dev
Version of manifest: current-2-g12f9080

$ repo manifest -o -
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <remote fetch="git://github.com/ossxp-com/" name="github"/>

  <default remote="github" revision="refs/heads/test-0.1"/>

  <project name="test1" path="test/test1">
    <copyfile dest="Makefile" src="root.mk"/>
  </project>
  <project name="test2" path="test/test2"/>
</manifest>

$ git ls-remote --tags git://github.com/ossxp-com/manifest.git
43e5783a58b46e97270785aa967f09046734c6ab        refs/tags/current
3a6a6da36840e716a14d52252e7b40e6ba6cbdea        refs/tags/current^{}
4735d32613eb50a6c3472cc8087ebf79cc46e0c0        refs/tags/v0.1
fb1a1b7302a893092ce8b356e83170eee5863f43        refs/tags/v0.1^{}
b23884d9964660c8dd34b343151aaf968a744400        refs/tags/v0.1.1
9c4c287069e29d21502472acac34f28896d7b5cc        refs/tags/v0.1.1^{}
127d9789cd4312ed279a7fa683c43eec73d2b28b        refs/tags/v0.1.2
47aaa83866f6d910a118a9a19c2ac3a2a5819b3e        refs/tags/v0.1.2^{}
af3abb7ed0a9ef7063e9d814510c527287c92ef6        refs/tags/v0.1.3
99c69bcfd7e2e7737cc62a7d95f39c6b9ffaf31a        refs/tags/v0.1.3^{}

$ mkdir v0.1.2
$ cd v0.1.2
$ repo init -u git://github.com/ossxp-com/manifest.git -b refs/tags/v0.1.2
$ repo sync

$ make
Version of test1:    1:0.1.2
Version of test2:    2:0.1.2
Version of manifest: v0.1.2