Repo工作原理和使用介紹

Posted on 2021-12-15 by WalkonNet

1. 概要

repo是Android為瞭方便管理多個git庫而開發的Python腳本。repo的出現，並非為瞭取代git，而是為瞭讓Android開發者更為有效的利用git。

Android源碼包含數百個git庫，僅僅是下載這麼多git庫就是一項繁重的任務，所以在下載源碼時，Android就引入瞭repo。 Android官方推薦下載repo的方法是通過Linux curl命令，下載完後，為repo腳本添加可執行權限：

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

由於國內Google訪問受限，所以上述命令不一定能下載成功。其實，我們現在可以從很多第三方渠道找到repo腳本，隻需要取下來，確保repo可以正確執行即可。

2. 工作原理

repo需要關註當前git庫的數量、名稱、路徑等，有瞭這些基本信息，才能對這些git庫進行操作。通過集中維護所有git庫的清單，repo可以方便的從清單中獲取git庫的信息。這份清單會隨著版本演進升級而產生變化，同時也有一些本地的修改定制需求，所以，repo是通過一個git庫來管理項目的清單文件的，這個git庫名字叫manifests。

當打開repo這個可執行的python腳本後，發現代碼量並不大(不超過1000行)，難道僅這一個腳本就完成瞭AOSP數百個git庫的管理嗎？並非如此。 repo是一系列腳本的集合，這些腳本也是通過git庫來維護的，這個git庫名字叫repo。

在客戶端使用repo初始化一個項目時，就會從遠程把manifests和repo這兩個git庫拷貝到本地，但這對於Android開發人員來說，又是近乎無形的(一般通過文件管理器，是無法看到這兩個git庫的)。 repo將自動化的管理信息都隱藏根目錄的.repo子目錄中。

2.1 項目清單庫(.repo/manifests)

AOSP項目清單git庫下，隻有一個文件default.xml，是一個標準的XML，描述瞭當前repo管理的所有信息。

AOSP的default.xml的文件內容如下：

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <remote  name="aosp"
             fetch=".."
             review="https://android-review.googlesource.com/" />
    <default revision="master"
             remote="aosp"
             sync-j="4" />
    <project path="build" name="platform/build" groups="pdk,tradefed" >
        <copyfile src="core/root.mk" dest="Makefile" />
    </project>
    <project path="abi/cpp" name="platform/abi/cpp" groups="pdk" />
    <project path="art" name="platform/art" groups="pdk" />
    ...
    <project path="tools/studio/translation" name="platform/tools/studio/translation" groups="notdefault,tools" />
    <project path="tools/swt" name="platform/tools/swt" groups="notdefault,tools" />
</manifest>

<remote>：描述瞭遠程倉庫的基本信息。name描述的是一個遠程倉庫的名稱，通常我們看到的命名是origin;fetch用作項目名稱的前緣，在構造項目倉庫遠程地址時使用到;review描述的是用作code review的server地址
<default>：default標簽的定義的屬性，將作為<project>標簽的默認屬性，在<project>標簽中，也可以重寫這些屬性。屬性revision表示當前的版本，也就是我們俗稱的分支;屬性remote描述的是默認使用的遠程倉庫名稱，即<remote>標簽中name的屬性值;屬性sync-j表示在同步遠程代碼時，並發的任務數量，配置高的機器可以將這個值調大
<project>：每一個repo管理的git庫，就是對應到一個<project>標簽，path描述的是項目相對於遠程倉庫URL的路徑，同時將作為對應的git庫在本地代碼的路徑; name用於定義項目名稱，命名方式采用的是整個項目URL的相對地址。譬如，AOSP項目的URL為https://android.googlesource.com/，命名為platform/build的git庫，訪問的URL就是https://android.googlesource.com/platform/build

如果需要新增或替換一些git庫，可以通過修改default.xml來實現，repo會根據配置信息，自動化管理。但直接對default.xml的定制，可能會導致下一次更新項目清單時，與遠程default.xml發生沖突。因此，repo提供瞭一個種更為靈活的定制方式local_manifests:所有的定制是遵循default.xml規范的，文件名可以自定義，譬如local_manifest.xml, another_local_manifest.xml等，將定制的XML放在新建的.repo/local_manifests子目錄即可。repo會遍歷.repo/local_manifests目錄下的所有*.xml文件，最終與default.xml合並成一個總的項目清單文件manifest.xml。

local_manifests的修改示例如下：

$ ls .repo/local_manifests
local_manifest.xml
another_local_manifest.xml

$ cat .repo/local_manifests/local_manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <project path="manifest" name="tools/manifest" />
    <project path="platform-manifest" name="platform/manifest" />
</manifest>

2.2 repo腳本庫(.repo/repo)

repo對git命令進行瞭封裝，提供瞭一套repo的命令集(包括init, sync等)，所有repo管理的自動化實現也都包含在這個git庫中。在第一次初始化的時候，repo會從遠程把這個git庫下載到本地。

倉庫目錄保存的是歷史信息和修改記錄，工作目錄保存的是當前版本的信息。一般來說，一個項目的Git倉庫目錄（默認為.git目錄）是位於工作目錄下面的，但是Git支持將一個項目的Git倉庫目錄和工作目錄分開來存放。對於repo管理而言，既有分開存放，也有位於工作目錄存放的:

manifests：倉庫目錄有兩份拷貝，一份位於工作目錄(.repo/manifests)的.git目錄下，另一份獨立存放於.repo/manifests.git
repo：倉庫目錄位於工作目錄(.repo/repo)的.git目錄下
project：所有被管理git庫的倉庫目錄都是分開存放的，位於.repo/projects目錄下。同時，也會保留工作目錄的.git，但裡面所有的文件都是到.repo的鏈接。這樣，即做到瞭分開存放，也兼容瞭在工作目錄下的所有git命令。

既然.repo目錄下保存瞭項目的所有信息，所有要拷貝一個項目時，隻是需要拷貝這個目錄就可以瞭。repo支持從本地已有的.repo中恢復原有的項目。

3. 使用介紹

repo命令的使用格式如下所示：

$ repo <COMMAND> <OPTIONS>

可選的的有：help、init、sync、upload、diff、download、forall、prune、start、status，每一個命令都有實際的使用場景，下面我們先對這些命令做一個簡要的介紹：

3.1 init

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

-u：指定manifests這個遠程git庫的URL，manifests庫是整個項目的清單。默認情況，這個git庫隻包含瞭default.xml一個文件，其內容可以參見Android的樣本
-m， –manifest-name：指定所需要的manifests庫中的清單文件。默認情況下，會使用maniftests/default.xml
-b， –manifest-branch：指定manifest.xml文件中的一個版本，，也就是俗稱的“分支”

運行該命令後，會在當前目錄下新建一個.repo子目錄：

.repo

├── manifests # 一個git庫，包含default.xml文件，用於描述repo所管理的git庫的信息

├── manifests.git # manifest這個git庫的實體，manifest/.git目錄下的所有文件都會鏈接到該目錄

├── manifest.xml # manifests/default.xml的一個軟鏈接

└── repo # 一個git庫，包含repo運行的所有腳本

這些本地的目錄是如何生成的呢？執行repo命令時，可以通過–trace參數，來看實際發生瞭什麼。

$ repo --trace init -u $URL -b $BRANCH -m $MANIFEST
  --------------------
  mkdir .repo; cd .repo
  git clone --bare $URL manifests.git
  git clone https://android.googlesource.com/tools/repo
  mkdir -p manifests/.git; cd manifests/.git
  for i in ../../manifests.git/*; do ln -s $ı .; done
  cd ..
  git checkout $BRANCH -- .
  cd ..
  ln -s manifests/$MANIFEST manifest.xml

首先，在當前目錄下創建.repo子目錄，後續所有的操作都在.repo子目錄下完成;

然後，clone瞭兩個git庫，其中一個是-u參數指定的manifests，本地git庫的名稱是manifest.git;另一個是默認的repo，後面我們會看到這個URL也可以通過參數來指定;

接著，創建瞭manifest/.git目錄，裡面的所有文件都是到manifests.git這個目錄的鏈接，這個是為瞭方便對manifests目錄執行git命令，緊接著，就會將manifest切換到-b參數指定的分支;

最後，在.repo目錄下，創建瞭一個軟鏈接，鏈接到-m參數制定的清單文件，默認情況是manifests/default.xml。

這樣，就完成瞭一個多git庫的初始化，之後，就可以執行其他的repo命令瞭。

我們還介紹幾個不常用的參數，在國內下載Android源碼時，會用到：

–repo-url：指定遠程repo庫的URL，默認情況是https://android.googlesource.com/tools/repo，但國內訪問Google受限，會導致這個庫無法下載，從而導致repo init失敗，所以可以通過該參數指定一個訪問不受限的repo地址
–repo-branch：同manifest這個git庫一樣，repo這個git庫也是有版本差異的，可以通過該參數來指定下載repo這個遠程git庫的特定分支
–no-repo-verify：在下載repo庫時，會對repo的源碼進行檢查。通過–repo-url指定第三方repo庫時，可能會導致檢查不通過，所以可以配套使用該參數，強制不進行檢查

3.2 sync

$ repo sync [PROJECT_LIST]

下載遠程代碼，並將本地代碼更新到最新，這個過程稱為“同步”。如果不使用任何參數，那麼會對所有repo管理的進行同步操作;也可以PROJECT_LIST參數，指定若幹要同步的PROJECT。根據本地git庫代碼不同，同步操作會有不同的行為：

當本地的git庫是第一次觸發同步操作時，那麼，該命令等價於git clone，會將遠程git庫直接拷貝到本地
當本地已經觸發過同步操作時，那麼，該命令等價於git remote update && git rebase origin/<BRANCH>，<BRANCH>就是當前與本地分支所關聯的遠程分支代碼合並可能會產生沖突，當沖突出現時，隻需要解決完沖突，然後執行git rebase --continue即可。

當sync命令正確執行完畢後，本地代碼就同遠程代碼保持一致瞭。在一些場景下，我們會用到sync命令的一些參數：

-j：開啟多線程同步操作，這會加快sync命令的執行速度。默認情況下，使用4個線程並發進行sync
-c, –current-branch：隻同步指定的遠程分支。默認情況下，sync會同步所有的遠程分支，當遠程分支比較多的時候，下載的代碼量就大。使用該參數，可以縮減下載時間，節省本地磁盤空間
-d, –detach：脫離當前的本地分支，切換到manifest.xml中設定的分支。在實際操作中，這個參數很有用，當我們第一次sync完代碼後，往往會切換到dev分支進行開發。如果不帶該參數使用sync，則會觸發本地的dev分支與manifest設定的遠程分支進行合並，這會很可能會導致sync失敗
-f, –force-broken：當有git庫sync失敗瞭，不中斷整個同步操作，繼續同步其他的git庫
–no-clone-bundle：在向服務器發起請求時，為瞭做到盡快的響應速度，會用到內容分發網絡(CDN, Content Delivery Network)。同步操作也會通過CDN與就近的服務器建立連接，使用HTTP/HTTPS的$URL/clone.bundle來初始化本地的git庫，clone.bundle實際上是遠程git庫的鏡像，通過HTTP直接下載，這會更好的利用網絡帶寬，加快下載速度。當服務器不能正常響應下載$URL/clone.bundle，但git又能正常工作時，可以通過該參數，配置不下載$URL/clone.bundle，而是直接通過git下載遠程git庫

3.3 upload

$ repo upload [PROJECT_LIST]

從字面意思理解，upload就是要上傳，將本地的代碼上傳到遠程服務器。upload命令首先會找出本地分支從上一次同步操作以來發生的改動，然後會將這些改動生成Patch文件，上傳至Gerrit服務器。如果沒有指定PROJECT_LIST，那麼upload會找出所有git庫的改動;如果某個git庫有多個分支，upload會提供一個交互界面，提示選擇其中若幹個分支進行上傳操作。

upload並不會直接將改動合並後遠程的git庫，而是需要先得到Reviewer批準。Reviewer查看改動內容、決定是否批準合入代碼的操作，都是通過Gerrit完成。 Gerrit服務器的地址是在manifests中指定的：打開.repo/manifest.xml，<remote>這個XML TAG中的review屬性值就是Review服務器的URL:

<remote name="aosp"
        fetch=".."
        review="https://android-review.googlesource.com/" />

Gerrit的實現機制不是本文討論的內容，但有幾個與Gerrit相關的概念，是需要代碼提交人員瞭解的：

Reviewer：代碼審閱人員可以是多個，是需要人為指定的。Gerrit提供網頁的操作，可以填選Reviewer。當有多個git庫的改動提交時，為瞭避免在網頁上頻繁的填選Reviewer這種重復勞動， upload提供瞭–re, –reviewer參數，在命令行一次性指定Reviewer
Commit-ID：git為瞭標識每個提交，引入瞭Commit-ID，是一個SHA-1值，針對當次提交內容的一個Checksum，可以用於驗證提交內容的完整性
Change-ID：Gerrit針對每一個Review任務，引入瞭一個Change-ID，每一個提交上傳到Gerrit，都會對應到一個Change-ID，為瞭區分於Commit-ID，Gerrit設定Change-ID都是以大寫字母 “I” 打頭的。 Change-ID與Commit-ID並非一一對應的，每一個Commit-ID都會關聯到一個Change-ID，但Change-ID可以關聯到多個Commit-ID
Patch-Set：當前需要Review的改動內容。一個Change-ID關聯多個Commit-ID，就是通過Patch-Set來表現的，當通過git commit –amend命令修正上一次的提交並上傳時， Commit-ID已經發生瞭變化，但仍可以保持Change-ID不變，這樣,在Gerrit原來的Review任務下，就會出現新的Patch-Set。修正多少次，就會出現多少個Patch-Set，可以理解，隻有最後一次修正才是我們想要的結果，所以，在所有的Patch-Set中，隻有最新的一個是真正有用的，能夠合並的。

3.4 download

$ repo download <TARGET> <CHANGE>

upload是把改動內容提交到Gerrit，download是從Gerrit下載改動。與upload一樣，download命令也是配合Gerrit使用的。

<TARGET>：指定要下載的PROJECT，譬如platform/frameworks/base, platform/packages/apps/Mms
<CHANGE>：指定要下載的改動內容。這個值不是Commit-ID，也不是Change-ID，而是一個Review任務URL的最後幾位數字。譬如，AOSP的一個Review任務https://android-review.googlesource.com/#/c/23823/，其中23823就是<CHANGE>。

3.5 forall

$ repo forall [PROJECT_LIST] -c <COMMAND>

對指定的git庫執行-c參數制定的命令序列。在管理多個git庫時，這是一條非常實用的命令。PROJECT_LIST是以空格區分的，譬如：

$ repo forall frameworks/base packages/apps/Mms -c "git status"

表示對platform/frameworks/base和platform/packages/apps/Mms同時執行git status命令。如果沒有指定PROJECT_LIST，那麼，會對repo管理的所有git庫都同時執行命令。

該命令的還有一些其他參數：

-r, –regex：通過指定一個正則表達式，隻有匹配的PROJECT，才會執行指定的命令
-p：輸出結果中，打印PROJECT的名稱

3.6 prune

$ repo prune [<PROJECT_LIST>]

刪除指定PROJECT中，已經合並的分支。當在開發分支上代碼已經合並到主幹分支後，使用該命令就可以刪除這個開發分支。

隨著時間的演進，開發分支會越來越多，在多人開發同一個git庫，多開發分支的情況會愈發明顯，假設當前git庫有如下分支：

* master
  dev_feature1_201501   # 已經合並到master
  dev_feature2_201502   # 已經合並到master
  dev_feature3_201503   # 正在開發中，還有改動記錄沒有合並到master

那麼，針對該git庫使用prune命令，會刪除dev_feature1_201501和dev_feature2_201502。

定義刪除無用的分支，能夠提交團隊的開發和管理效率。prune就是刪除無用分支的”殺手鐧“。

3.7 start

$ repo start <BRANCH_NAME> [<PROJECT_LIST>]

在指定的PROJECT的上，切換到<BRANCH_NAME>指定的分支。可以使用–all參數對所有的PROJECT都執行分支切換操作。該命令實際上是對git checkout命令的封裝，<BRANCH_NAME>是自定義的，它將追蹤manifest中指定的分支名。

當第一次sync完代碼後，可以通過start命令將git庫切換到開發分支，避免在匿名分支上工作導致丟失改動內容的情況。

3.8 status

$ repo status [<PROJECT_LIST>]

status用於查看多個git庫的狀態。實際上，是對git status命令的封裝。

4. 使用實踐

Android推薦的開發流程是：

repo init初始化工程，指定待下載的分支
repo sync下載代碼
repo start將本地git庫切換到開發分支(TOPIC BRANCH)
在本地進行修改，驗證後，提交到本地
repo upload上傳到服務器，等待review

在實際使用過程中，我們會用到repo的一些什麼子命令和參數呢？哪些參數有助於提高開發效率呢？下面我們以一些實際場景為例展開說明。

4.1 對項目清單文件進行定制

通過local_manifest機制，能夠避免瞭直接修改default.xml，不會造成下次同步遠程清單文件的沖突。

CyanogenMod(CM)適配瞭上百款機型，不同機型所涉及到的git庫很可能是有差異的。以CM對清單文件的定制為例，通過新增local_manifest.xml，內容如下：

<manifest>
    <!-- add github as a remote source -->
    <remote name="github" fetch="git://github.com" />

    <!-- remove aosp standard projects and replace with cyanogenmod versions -->
    <remove-project name="platform/bootable/recovery" />
    <remove-project name="platform/external/yaffs2" />
    <remove-project name="platform/external/zlib" />
    <project path="bootable/recovery" name="CyanogenMod/android_bootable_recovery" remote="github" revision="cm-10.1" />
    <project path="external/yaffs2" name="CyanogenMod/android_external_yaffs2" remote="github" revision="cm-10.1" />
    <project path="external/zlib" name="CyanogenMod/android_external_zlib" remote="github" revision="cm-10.1" />

    <!-- add busybox from the cyanogenmod repository -->
    <project path="external/busybox" name="CyanogenMod/android_external_busybox" remote="github" revision="cm-10.1" />

</manifest>

local_manifest.xml會與已有的default.xml融合成一個項目清單文件manifest.xml，實現瞭對一些git庫的替換和新增。可以通過以下命令導出當前的清單文件，最終snapshot.xml就是融合後的版本：

$ repo manifest -o snapshot.xml -r

在編譯之前，保存整個項目的清單，有助於問題的回溯。當項目的git庫發生變更，需要回退到上一個版本進行驗證的時候，隻需要重新基於snapshot.xml初始化上一個版本即可：

$ cp snapshot.xml .repo/manifests/
$ repo init -m snapshot.xml           # -m 參數表示自定義manifest
$ repo sync -d                        # -d 參數表示從當前分支脫離，切換到manifest中定義的分支

4.2 解決無法下載Android源碼

在repo init的時候，會從遠程下載manifests和repo這兩個git庫，默認情況下，這兩個git庫的地址都是寫死在repo這個python腳本裡面的。對於AOSP而言，這兩個git庫的地址顯然是google提供的。但由於google訪問受限的緣故，會導致init時，無法下載manifests和repo。這時候，可以使用init的-u和–repo-url參數，自定義這兩個庫的地址，輔以–no-repo-verify來繞過代碼檢查。

$ repo init --repo-url [PATH/TO/REPO] -u [PATH/TO/MANIFEST] -b [BRANCH] --no-repo-verify
$ repo sync

4.3 更快更省的下載遠程代碼

repo默認會同步git庫的所有遠程分支的代碼，但實際開發過程中，用到的分支是有限的。使用sync的-c參數，可以隻下載manifest中設定的分支，這會節省代碼下載時間以及本地的磁盤空間：

$ repo sync -c

如果實際開發過程中，需要用到另外一個分支，而又不想被其他分支幹擾，可以在已有的工程根目錄下，使用如下命令：

$ repo manifest -o snapshot.xml -r
$ repo init -u [PATH/TO/MANIFEST] -b [ANOTHER_BRANCH]
$ repo sync -c -d

以上命令序列，相當更新瞭manifest，而且僅僅隻下載ANOTHER_BRANCH的代碼，這樣本地隻保存瞭兩個分支的代碼。利用保存的snapshot.xml，還能將所有git庫方便的切換回原來的分支。

如果本地已經有一份Android源碼，假設路徑為~/android-exsit，想要下載另一份新的Android源碼，通過–reference參數，在數分鐘以內，就能將代碼下載完畢：

$ mkdir ~/android-new && cd ~/android-new
$ repo init --reference=~/android-exsit -u [PATH/TO/MANIFEST] -b [BRANCH]
$ repo sync -c

4.4 避免在匿名分支上工作

在sync完代碼後，所有git庫默認都是在一個匿名分支上(no branch)，很容易會由於誤操作導致丟失代碼修改。可以使用如下命令將所有的git庫切換到開發分支：

$ repo start BRANCH --all

4.5 使用upload提交代碼

開發人員可能同時在多個git庫，甚至多個分支上，同時進行修改，針對每個git庫單獨提交代碼是繁瑣的。可以使用如下命令，一並提交所有的修改：

$ repo upload

不用擔心會漏提交或者誤提交，upload會提供一個交互界面，開發人員選擇需要提交的git庫和分支即可。

如果需要省去Gerrit上填寫reviewer的操作，可以使用–reviewer參數指定Reviewer的郵箱地址：

$ repo upload --reviewer="[email protected]"

4.6 定期刪除已經合並的開發分支

Git鼓勵在修復Bug或者開發新的Feature時，都創建一個新的分支。創建Git分支的代價是很小的，而且速度很快，因此，不用擔心創建Git分支的成本，而是盡可能多地使用分支。

隨著時間的演進，開發分支會越來越多，而一些已經合並到主幹的開發分支是沒有存在價值的，可以通過prune命令定期刪除無用的開發分支：

$ repo prune [PROJECT_LIST]

4.7 同時操作多個git庫

對於部分開發人員而言，同時操作多個git庫是常態，如果針對每個git庫的操作命令都是相同的，那麼可以使用如下命令一次性完成所有操作:

$ repo forall -c "git branch | grep tmp | xargs git branch -D; git branch"

參數-c指定的命令序列可以很復雜，多條命令隻需要用“;”間隔。

Repo工作原理和使用介紹

目錄

1. 概要

2. 工作原理

2.1 項目清單庫(.repo/manifests)

2.2 repo腳本庫(.repo/repo)

2.3 倉庫目錄和工作目錄

3. 使用介紹

3.1 init

3.2 sync

3.3 upload

3.4 download

3.5 forall

3.6 prune

3.7 start

3.8 status

4. 使用實踐

4.1 對項目清單文件進行定制

4.2 解決無法下載Android源碼

4.3 更快更省的下載遠程代碼

4.4 避免在匿名分支上工作

4.5 使用upload提交代碼

4.6 定期刪除已經合並的開發分支

4.7 同時操作多個git庫

推薦閱讀：

發佈留言取消回覆

近期文章

目錄

1. 概要

2. 工作原理

2.1 項目清單庫(.repo/manifests)

2.2 repo腳本庫(.repo/repo)

2.3 倉庫目錄和工作目錄

3. 使用介紹

3.1 init

3.2 sync

3.3 upload

3.4 download

3.5 forall

3.6 prune

3.7 start

3.8 status

4. 使用實踐

4.1 對項目清單文件進行定制

4.2 解決無法下載Android源碼

4.3 更快更省的下載遠程代碼

4.4 避免在匿名分支上工作

4.5 使用upload提交代碼

4.6 定期刪除已經合並的開發分支

4.7 同時操作多個git庫

推薦閱讀：

發佈留言 取消回覆

近期文章

標籤

發佈留言取消回覆