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). See Source Control Tools for an explanation of the relationship between Repo and Git and links to supporting documentation for each tool.
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 the client to the repositories.|
||Starts a new branch.|
||Shows the status of the current branch.|
||Uploads changes to the review server.|
||Stages the files.|
||Commits the staged files.|
||Shows the current branches.|
||Creates a new topic branch.|
||Shows diff of the unstaged changes.|
||Shows diff of the staged changes.|
||Shows the history of the current branch.|
||Shows the commits that aren't 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 isn't a copy of the original files; it's 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
To verify that 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 doesn't track the changes that 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 doesn't just 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 that you're 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 the directory structure and file contents for the entire project. Use this command 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 don't add a commit message, the commit fails.
Uploading changes to Gerrit
Update to the latest revision, then upload the change:
These commands return a list of changes you have committed and prompt you to
select the branches to upload to the review server. If there's only one
branch, you 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 file system:
rm -rf WORKING_DIRECTORY
Deleting a client permanently deletes any changes you haven't uploaded for review.