Overview

Working with Android code requires using Git (an open-source
version control system) and Repo (a Google-built repository
management tool that runs on top of Git).

Git

Git is designed to handle large projects that are distributed over multiple
repositories. Android uses Git for local operations such as local branching,
commits, diffs, and edits. One of the challenges in setting up the Android
project was figuring out how to best support the outside community—from
the hobbyist community to large OEMs building mass-market consumer devices. We
wanted components to be replaceable, and we wanted interesting components to
have a life of their own outside of Android. We first chose a distributed
revision control system, then narrowed it down to Git.

Repo

Repo unifies Git repositories when necessary, performs uploads to the
Gerrit revision control
system, and automates parts of the Android development workflow. Repo is
not meant to replace Git, only to make it easier to work with Git in the
context of Android. The repo command is an executable Python script that you
can put anywhere in your path. In working with the Android source files, you
use Repo for across-network operations. For example, with a single Repo
command you can download files from multiple repositories into your local
working directory.

In most situations, you can use Git instead of Repo, or mix Repo and Git
commands to form complex commands. However, using Repo for basic
across-network operations will make your work much simpler. For more details
on Repo, see the Repo Command Reference.

Other tools

Other tools include
Gerrit,
a web-based code review system for projects that use Git. Gerrit encourages
more centralized use of Git by allowing all authorized users to submit
changes, which are automatically merged if they pass code review. In addition,
Gerrit makes reviewing easier by displaying changes side-by-side in the
browser and enabling inline comments.

Finally,
Android
Studio is the official integrated development environment (IDE) for
Android application development.

Workflow

Android development involves the following basic workflow:

Figure 1. Basic Android workflow

Start a new topic branch using repo start.

Edit the files.

Stage changes using git add.

Commit changes using git commit.

Upload changes to the review server using repo upload.

Common tasks

Working with Git and Repo in the Android code repositories involves
performing the following common tasks:

Synchronizing clients

To synchronize the files for all available projects:

repo sync

To synchronize the files for selected projects:

repo sync PROJECT0 PROJECT1 ... PROJECTN

Creating topic branches

Start a topic branch in your local work environment whenever you begin a
change, such as when you begin work on a bug or new feature. A topic branch is
not a copy of the original files; it is a pointer to a
particular commit, which makes creating local branches and switching among
them a lightweight operation. By using branches, you can isolate one aspect of
your work from the others. For an interesting article about using topic
branches, refer to
Separating
topic branches.

To start a topic branch using Repo, navigate to the project and run:

repo start BRANCH_NAME .

The trailing period (.) represents the project in the current working
directory.

To verify the new branch was created:

repo status .

Using topic branches

To assign the branch to a specific project:

repo start BRANCH_NAME PROJECT_NAME

For a list of all projects, refer to
android.googlesource.com.
If you've already navigated to the project directory, just use a period to
represent the current project.

To switch to another branch in your local work environment:

git checkout BRANCH_NAME

To view a list of existing branches:

git branch

or

repo branches

Both commands return the list of existing branches with the name of the
current branch preceded by an asterisk (*).

Note: A bug might cause repo
sync to reset the local topic branch. If git branch shows *
(no branch) after you run repo sync, run git checkout
again.

Staging files

By default, Git notices but does not track the changes you make in a project.
To tell Git to preserve your changes, you must mark or stage those
changes for inclusion in a commit.

To stage changes:

git add

This command accepts arguments for files or directories within the project
directory. Despite the name, git add does not simply add files to
the git repository; it can also be used to stage file modifications and
deletions.

Viewing client status

To list the state of files:

repo status

To view uncommitted edits (local edits that are not marked for commit):

repo diff

To view committed edits (located edits that are marked for
commit), ensure you are in the project directory then run git
diff with the cached argument:

cd ~/WORKING_DIRECTORY/PROJECTgit diff --cached

Figure 2. Uncommitted vs. committed edits.

Committing changes

A commit is the basic unit of revision control in Git and consists of
a snapshot of directory structure and file contents for the entire project. To
create a commit in Git:

git commit

When prompted for a commit message, provide a short (but helpful) message for
changes submitted to AOSP. If you do not add a commit message, the commit is
aborted.

Uploading changes to Gerrit

Update to the latest revision, then upload the change:

repo syncrepo upload

This command returns a list of changes you have committed and prompts you to
select the branches to upload to the review server. If there is only one
branch, you will see a simple y/n prompt.

Resolving sync conflicts

If the repo sync command returns sync conflicts:

View the files that are unmerged (status code = U).

Edit the conflict regions as necessary.

Change to the relevant project directory. Add and commit the affected
files, then rebase the changes:

git add .git commitgit rebase --continue

After the rebase completes, start the entire sync again:

repo sync PROJECT0 PROJECT1 ... PROJECTN

Cleaning up clients

After merging changes to Gerrit, update your local working directory then use
repo prune to safely remove stale topic branches:

repo syncrepo prune

Deleting clients

Because all state information is stored in your client, you only need to
delete the directory from your filesystem:

rm -rf WORKING_DIRECTORY

Deleting a client permanently deletes any changes you have not yet
uploaded for review.