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 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 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 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.
Android development involves the following basic workflow:
- Start a new topic branch using
- Edit the files.
- Stage changes using
- Commit changes using
- Upload changes to the review server using
Working with Git and Repo in the Android code repositories involves performing the following common tasks:
||Initializes a new client.|
||Syncs client to repositories.|
||Starts a new branch.|
||Shows status of current branch.|
||Uploads changes to the review server.|
||Commits staged files.|
||Shows current branches.|
||Creates new topic branch.|
||Switches HEAD to specified branch.|
||Merges [branch] into current branch.|
||Shows diff of unstaged changes.|
||Shows diff of staged changes.|
||Shows history of current branch.|
||Shows commits that are not pushed.|
To synchronize the files for all available projects:
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:
Both commands return the list of existing branches with the name of the current branch preceded by an asterisk (*).
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:
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
Viewing client status
To list the state of files:
To view uncommitted edits (local edits that are not marked for commit):
To view committed edits (located edits that are marked for
commit), ensure you are in the project directory then run
diff with the
git diff --cached
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:
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:
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
Resolving sync conflicts
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 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:
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.