Repo command reference

Repo complements Git by simplifying work across multiple repositories. See Source Control
Tools (/docs/setup/develop) for an explanation of the relationship between Repo and Git. For
more details on Repo, see the Repo README
 (https://gerrit.googlesource.com/git-repo/+/HEAD/README.md).

Repo use takes the following form:

$ repo command options edit

Optional elements are shown in brackets [ ]. For example, many commands take project-list
as an argument. You can specify project-list as a list of names or a list of paths to local
source directories for the projects:

$ repo sync [project0 project1 ... projectn edit]

$ repo sync [/path/to/project0 ... /path/to/projectn edit]

help
This page merely highlights key options. See the command line help for full details. When
Repo is installed, you can find the latest documentation starting with a summary of all
commands by running:

$ repo help

You can see detailed information about any command by running this within a Repo tree:

$ repo help command edit

For example, the following command yields a description and list of options for the init
argument of Repo, which initializes Repo in the current directory. (See init (#init) for details.)

$ repo help init

Or to see only the list of available options, run:

$ repo command edit --help

For example:

$ repo init --help

init

$ repo init -u url edit [options edit]

Installs Repo in the current directory. This creates a .repo/ directory with Git repositories
for the Repo source code and the standard Android manifest files.

Options:

-u : Specify a URL from which to retrieve a manifest repository. The common manifest
is found at https://android.googlesource.com/platform/manifest .

-m : Select a manifest file within the repository. If no manifest name is selected, the
default is default.xml .

-b : Specify a revision, that is, a particular manifest-branch.

Note: For all remaining Repo commands, the current working directory must either be the parent
directory of .repo/ or a subdirectory of the parent directory.

sync

$ repo sync [project-list edit]

Downloads new changes and updates the working files in your local environment,
essentially accomplishing git fetch across all Git repositories. If you run repo sync
without arguments, it synchronizes the files for all projects.

When you run repo sync , this is what happens:

If the project has never been synchronized, then repo sync is equivalent to git
clone . All branches in the remote repository are copied to the local project directory.

If the project has been synchronized before, then repo sync is equivalent to:

git remote update

git rebase origin/branch

where branch is the currently checked-out branch in the local project directory. If the
local branch isn't tracking a branch in the remote repository, then no synchronization
occurs for the project.

If the Git rebase operation results in merge conflicts, use the normal Git commands
(for example, git rebase --continue ) to resolve the conflicts.

After a successful run of repo sync , the code in specified projects is up to date and
synced with the code in the remote repository.

Here are key options. See repo help sync for more:

-c : Fetch only the current manifest branch from the server.

 -d : Switch specified projects back to the manifest revision. This is helpful if the
project is currently on a topic branch, but the manifest revision is temporarily needed.

-f : Proceed with syncing other projects even if a project fails to sync.

-jthreadcount : Split the sync across threads for faster completion. Ensure you don't
overwhelm your machine - leave some CPU reserved for other tasks. To see the
number of available CPUs, first run: nproc --all

-q : Run quietly by suppressing status messages.

-s : Sync to a known good build as specified by the manifest-server element in the

current manifest.

upload

$ repo upload [project-list edit]

For the specified projects, Repo compares the local branches to the remote branches
updated during the last Repo sync. Repo prompts you to select one or more of the branches
that haven't been uploaded for review.

All commits on the selected branches are then transmitted to Gerrit over an HTTPS
connection. You need to configure an HTTPS password to enable upload authorization.
Visit the Password Generator  (https://android-review.googlesource.com/new-password) to
generate a new username/password pair to use over HTTPS.

When Gerrit receives the object data over its server, it turns each commit into a change so
that reviewers can comment on a specific commit. To combine several checkpoint commits
into a single commit, use git rebase -i before you run the upload.

If you run repo upload without arguments, it searches all of the projects for changes to
upload.

To edit changes after they've been uploaded, use a tool like git rebase -i or git commit
--amend to update your local commits. After your edits are complete:

Verify that the updated branch is the currently checked out branch.

Use repo upload --replace PROJECT to open the change matching editor.
 For each commit in the series, enter the Gerrit change ID inside the brackets:

# Replacing from branch foo

[ 3021 ] 35f2596c Refactor part of GetUploadableBranches to lookup one sp
[ 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.

After the upload is complete, the changes have an additional patch set.

If you want to upload only the currently checked out Git branch, use the flag --current-
branch (or --cbr for short).

diff

$ repo diff [project-list edit]

Shows outstanding changes between the commit and the working tree using git diff .

download

$ repo download target change edit

Downloads the specified change from the review system and makes it available in your
project's local working directory.

For example, to download change 23823  (https://android-review.googlesource.com/23823) into

your platform/build directory:
$ repo download platform/build 23823

Running repo sync removes any commits retrieved with repo download . Or you can
check out the remote branch using git checkout m/main .

Note: There are replication delays to all servers worldwide, so there's a slight mirroring lag between when
a change is visible on the web in Gerrit (https://android-review.googlesource.com/) and when repo
download can find the change for all users.

forall

$ repo forall [project-list edit] -c command edit

Executes the given shell command in each project. The following additional environment
variables are made available by repo forall :

REPO_PROJECT is set to the unique name of the project.

REPO_PATH is the path relative to the root of the client.

REPO_REMOTE is the name of the remote system from the manifest.

REPO_LREV is the name of the revision from the manifest, translated to a local
tracking branch. Use this if you need to pass the manifest revision to a locally
executed Git command.

REPO_RREV is the name of the revision from the manifest, exactly as written in the
manifest.

Options:

-c : Command and arguments to execute. The command is evaluated through

/bin/sh and any arguments after it are passed through as shell positional
parameters.
 -p : Show project headers before output of the specified command. This is achieved
by binding pipes to the command's stdin, stdout, and sterr streams, and piping all
output into a continuous stream that is displayed in a single pager session.

-v : Show messages the command writes to stderr.

prune

$ repo prune [project-list edit]

Prunes (deletes) topics that are already merged.

start

$ repo start
branch-name edit [project-list edit]

Begins a new branch for development, starting from the revision specified in the manifest.

TheBRANCH_NAME argument provides a short description of the change you're trying to

make to the projects. If you don't know, consider using the name default .

The project-list argument specifies which projects participate in this topic branch.

Note: A period ( . ) is shorthand for the project in the current working directory.

status
$ repo status [project-list edit]

Compares the working tree to the staging area (index) and the most recent commit on this
branch (HEAD) in each project specified. Displays a summary line for each file where there
is a difference between these three states.

To see the status of just the current branch, run repo status . . The status information is
listed by project. For each file in the project, a two-letter code is used.

In the first column, an uppercase letter indicates how the staging area differs from the last
committed state.

Letter Meaning Description

- No change Same in HEAD and index

A Added Not in HEAD, in index

M Modified In HEAD, modified in index

D Deleted In HEAD, not in index

R Renamed Not in HEAD, path changed in index

C Copied Not in HEAD, copied from another in index

T Mode changed Same content in HEAD and index, mode changed

U Unmerged Conflict between HEAD and index; resolution required

In the second column, a lowercase letter indicates how the working directory differs from
the index.
Letter Meaning Description

- New/unknown Not in index, in work tree

m Modified In index, in work tree, modified

d Deleted In index, not in work tree

Handling repo errors

$ git commit -a # Commit local changes first so they aren't lost.

repo start branch-name edit # Start the branch
git reset --hard HEAD@{1} # And reset the branch so that it matches the commi
repo upload .

repo: error: no branches ready for upload appears when the command
The error
repo start wasn't run at the start of the session. To recover, you can check the commit id,
start a new branch and then merge it.

Content and code samples on this page are subject to the licenses described in the Content License (/license).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Last updated 2023-07-25 UTC.