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.

For more details on Git, refer to Git Documentation.

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:

  1. Start a new topic branch using repo start.
  2. Edit the files.
  3. Stage changes using git add.
  4. Commit changes using git commit.
  5. 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:

Command Description
repo init Initializes a new client.
repo sync Syncs client to repositories.
repo start Starts a new branch.
repo status Shows status of current branch.
repo upload Uploads changes to the review server.
git add Stages files.
git commit Commits staged files.
git branch Shows current branches.
git branch [branch] Creates new topic branch.
git checkout [branch] Switches HEAD to specified branch.
git merge [branch] Merges [branch] into current branch.
git diff Shows diff of unstaged changes.
git diff --cached Shows diff of staged changes.
git log Shows history of current branch.
git log m/[codeline].. Shows commits that are not pushed.

For information about using Repo to download source, see Downloading the Source and the Repo Command Reference.

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 (*).

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/PROJECT
git diff --cached

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 sync
repo 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:

  1. View the files that are unmerged (status code = U).
  2. Edit the conflict regions as necessary.
  3. Change to the relevant project directory. Add and commit the affected files, then rebase the changes: 
    git add .
git commit
git rebase --continue
  4. 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 sync
repo 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.