While the Repo tool orchestrates the download of the entire AOSP tree, the actual source code management at the individual project level is handled entirely by Git. Because AOSP is developed by thousands of engineers across multiple companies, the Git workflows are highly structured.
Git Objects in AOSP
At its core, Git is a simple key-value data store. Understanding how it stores data is crucial for debugging corrupted AOSP checkouts.
- Blobs: These store the actual file data (the source code text).
- Trees: These represent directories, mapping filenames to specific blob objects.
- Commits: A commit object points to a specific tree object, along with metadata like the author, timestamp, and the ID of the parent commit.
- Tags: Tags are essentially named pointers to specific commits. In AOSP, tags like
android-14.0.0_r12are used to mark exact release points for security updates.
You can inspect the raw objects inside an AOSP git repository:
# Inside an AOSP project (e.g., frameworks/base)
# Look at the raw content of the latest commit object
git cat-file -p HEAD
Branches and HEAD in Context
When you run repo sync, Repo checks out a specific commit for every repository based on the manifest file. Because the exact commit is specified, you are usually placed in a "detached HEAD" state.
Before you make any changes to a repository, you must explicitly create a branch using the Repo tool. Do not use git branch directly, as Repo needs to track the branch linkage.
# Create a branch named "my-feature" in ALL repositories
repo start my-feature --all
# Create a branch only in the current directory's repository
repo start my-feature .
Cherry-Pick and Rebase Workflows
AOSP development relies heavily on linearly rewriting history. Merge commits are generally discouraged in favor of rebasing.
- Rebase: If you are working on a feature and Google releases a new AOSP security patch, you will
git rebaseyour local commits on top of the new upstream commits to keep a clean, linear history. - Cherry-Pick: Often, device manufacturers need to backport a specific security fix from Android 14 down to Android 12. They use
git cherry-pick <commit-hash>to extract that specific patch and apply it to the older branch without merging the entire modern codebase.
Gerrit Code Review Integration
You do not push code directly to AOSP using standard git push. Instead, AOSP uses a web-based code review system called Gerrit.
When you are ready to submit code, you use the repo upload command. This command packages your local Git commits and uploads them to the Gerrit server as a "Change".
# Upload your current branch to Gerrit for review
repo upload .
Other engineers will review your Change on the Gerrit web interface. If they request modifications, you do not create a new commit. Instead, you amend your original commit locally and run repo upload again. Gerrit uses a hidden "Change-Id" inserted into your commit message to link the amended commit to the existing code review.
# Fixing code based on Gerrit feedback
git add modified_file.cpp
git commit --amend
repo upload .