Repo complements Git by simplifying work across multiple repositories. For an explanation of the relationship between Repo and Git, see Source control tools. For more details on Repo, see the Repo README
Repo use takes the following form:
repo command options
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]
repo sync [/path/to/project0 ... /path/to/projectn]
help
repo help
Provides help on the repo
command. You can see detailed information about a
specific Repo command specifying a command as an option:
repo help command
For example, the following command yields a description and list of options
for the init
command:
repo help init
Or, to see only the list of available options for a command, run:
repo command --help
For example:
repo init --help
init
repo init -u url [options]
Installs Repo in the current directory. This command 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 athttps://android.googlesource.com/platform/manifest
.-m
: Select a manifest file within the repository. If no manifest name is selected, the default isdefault.xml
.-b
: Specify a revision, that is, a particular manifest-branch.
sync
repo sync [project-list]
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 togit 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 origen/branch
Where branch is the current 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.
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.
Key options:
-c
: Fetch only the current manifest branch from the server.-d
: Switch specified projects back to the manifest revision. This option is helpful if the project is on a topic branch, but the manifest revision is needed temporarily.-f
: Proceed with syncing other projects even if a project fails to sync.threadcount
: 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 runnproc --all
.-q
: Run quietly by suppressing status messages.-s
: Sync to a known good build as specified by themanifest-server
element in the current manifest.
For more options, run repo help sync
.
upload
repo upload [project-list]
Uploads changes to the review server. 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. To generate a new username/password pair to use over HTTPS, visit the Password generator.
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 current 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 specific... [ 2829 ] ec18b4ba Update proto client to support patch set replacements # 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).
For related changes, it is useful to keep all the CLs in the same topic. You can
add a topic name while uploading with --topic=TOPIC
. Or, just pass -t
to set
the topic name same as the local branch name.
diff
repo diff [project-list]
Shows outstanding changes between the commit and the working tree using
git diff
.
download
repo download target change
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 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
.
forall
repo forall [project-list] -c command
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 variable 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]
Prunes (deletes) topics that are already merged.
start
repo start branch-name [project-list]
Begins a new branch for development, starting from the revision specified in the manifest.
The BRANCH_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.
status
repo status [project-list]
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 the current branch only, 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 |
Handle repo errors
git commit -a # Commit local changes first so they aren't lost. repo start branch-name # Start the branch git reset --hard HEAD@{1} # And reset the branch so that it matches the commit before repo start repo upload .
The error repo: error: no branches ready for upload
appears when the command
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.