Android uses repo for managing the collections of individual git repositories needed by each “tree”. See that page for more information, including install instructions. You'll need to install repo before you can work with Android repositories.
AOSP's Downloading the source explains how to initialize a new tree (similar to git clone, but for a whole repo tree). For the NDK the main difference is that you need to specify the master-ndk branch by adding -b master-ndk. See Building.md for more specific instructions.
Warning: Unlike git clone, repo init will not check out the source into a new directory. If you run repo init && repo sync in your home directory you will have a lot to clean up. If you run repo init in a tree that already has a different repo tree in it, you'll reinitialize that tree with a different branch and the next sync may delete existing projects.
repo init only prepares the tree, you'll still need to run repo sync to fetch the source.
The repo equivalent of git pull is repo sync. It's recommended that you run repo sync -c -j $THREADS. -c ensures that only the branches that are needed are fetched to avoid consuming too much disk space, and -j $THREADS allows repo to use multiple threads when updating.
repo trees place git projects in a detached HEAD state by default. To create a local branch that can be sent for review, use repo start $BRANCH_NAME .. This is similar to git checkout -b or git switch -c, but will configure the new branch so that it can be uploaded for review.
Any time you start new work, use repo start $BRANCH_NAME .. Each local branch is its own review chain, so you'll want separate branches for distinct changes.
When you're ready to upload your changes, commit them to your local branch. Gerrit will create one review per commit and will associate commits that are in the same branch together in a series. If you made many commits while working on the change, squash them (repo rebase -i --autosquash . will start an interactive rebase that you can use to re-order and combine commits) so that each commit is complete but minimal. Splitting large changes into multiple commits improves reviewability, but each commit should be able to build and pass tests on its own so it can be submitted individually.
In most cases you'll only need one commit in a branch.
To get changes reviewed, run repo upload --cbr .. This will upload the commits in the current branch and directory. To upload changes in other directories, pass those paths instead of .. Multiple paths can be given to upload multiple projects with the same command.--cbr is “current branch”. Without --cbr an interactive mode will open in your editor that you can use to upload branches other than the one that is currently checked out.
You can also add reviewers when uploading your changes with the --re=$USER1,$USER2,... argument. If your reviewers are Googlers, Gerrit can usually work out that name means name@google.com. In other cases you'll need to spell out the full email address of the reviewer.
Once the change is uploaded, you can open it in Gerrit and enable autosubmit if you want the change to be submitted once it has been reviewed and passed presubmit testing. Don't worry, if anyone has review comments those will prevent the change from being submitted before you can see them.
To minimize the amount of time you spend waiting on machines, it‘s best to vote Presubmit Ready+1 on your change when you upload it to get treehugger running ASAP. By default treehugger won’t start testing a change until it has either been +2'd or has autosubmit set.
If you have changes that span multiple git projects that need to be submitted together (are mutually dependent), give them the same topic name in Gerrit. If you used the same branch name when running repo start in each project, you can pass -t to repo upload to automatically assign the branch name as the topic name in Gerrit.
To update your commit to address review comments, make the change and amend the commit. If you have a stack of commits and need to amend something other than the top commit, you can use the --fixup argument to git commit and then rebase with --autosquash, or use the edit option on a commit after starting an interactive rebase (repo rebase -i --autosquash .).
After amending your changes, run repo upload again as you did before. This will create a new “patch set” (PS) for the existing review in Gerrit. This is a new “version” of the commit. You do not need to specify reviewers again when uploading new patch sets.
Once you have approval (Code Review +2) and either a +1 or a +2 from someone in the OWNERS file (or are in the OWNERS file yourself), all review comments have been addressed and marked as “Done”, and presubmit (AKA “treehugger”) has responded with Presubmit Verified +1, your change can be submitted. If you enabled autosubmit this will happen automatically. Otherwise use the “Submit” button in the UI.
The repo/Gerrit process has some differences compared to the GitHub Pull Request workflow. If you‘re familiar with using pull requests you should read everything above for the details, but here’s a quick cheat sheet mapping similar processes:
| GitHub | Gerrit |
|---|---|
git clone $X | mkdir $X && cd $X && repo init $X && repo sync |
git pull | repo sync |
git checkout -b/git switch -c | repo start . |
git push and other pull request steps | repo upload |