Android Git Workflow

This is overview of the standard workflow we suggest for working on a project using repo. It is designed as a simple outline reference, with links to more details on each step. Your first time through you should read through the details as you follow the steps. For more information about repo, see Using Repo and Git.

Setup repo: repo init
See this page for detailed instructions on setting up repo.


repo init -u ssh://android-git.corp.google.com:29418/platform/manifest.git -b master
Retrieve current source: repo sync
This may fail if you have outstanding changes that need to be merged, with a message about being "n commits behind." If so, this can usually be fixed with:

cd path/to/projectgit rebase goog/master <branchname>    # or goog/donutrepo sync                              # to continue and finish the sync
Select work project: cd project/path
Remember that repo is just an aggregator of multiple git projects. By moving your working directory into a particular project, git will now operate in the context of that project.


Create a work branch: repo start branchname .
The . argument to repo specifies which project to start the branch on. Since you have already moved into the project you want to work on, just specifying the current directory will suffice

Remember branch names: git branch
In case you forget the branches you've created, use git branch. This lists all of your branch names. An asterisk appears beside the one that will be affected by your git and repo commands.


Modify your files
You don't need to tell git to checkout a file before you start changing it; git will determine which files have been modified when you are ready to commit them.


Add files if needed: git add path/to/file
git add is not strictly for adding newly-created files. What it does is move contents of your working tree (the files you edit on disk) to the staging area (where you batch up new files and changes to existing files before committing). Running git add on a modified file will stage the changes in that file such that they will be part of the next git commit you do. git add . will add all new files and any modified files at or below the current directory to the staging area.

For more complicated manipulation of the staging area, git add -i provides an interactive tool for updating, adding, and reverting files. Use git help add for documentation on using the interactive tool.

For more information about the relationship between your working tree and the staging area, see The Git Index from the Git Book or The Staging Area at gitready.com.


Commit files to branch: git commit -a
The commit command transfers your staging area into the current branch. The -a option tells it to automatically stage any modified or deleted files (but not newly added files), and commit those.

This is generally the easiest way to commit your changes, if you know you just want to commit all of your current work. For more complicated situations, you can use the git add command as described above, or git commit --interactive to invoke the same interactive editor as available in git add. An option for those that are command line impaired is git gui.




If you forgot to start your branch, you can do repo start branchname . here before committing your files, or see here if you forgot to run 'repo start' and already ran commit.





TODO: describe how to recover if files are committed to the wrong branch.


Commit message
Be sure to create a descriptive commit message for every change. A commit message starts with a single subject line of not more than 60 characters separated from the rest of the commit message by a blank line. The subject line can also contain "DO NOT MERGE" typically at the beginning of the subject line. Following the subject line should be a more detailed set of sentences/paragraphs which describes the change more completely.

The last paragraph of a commit message may optionally contain a series of lines that maybe used by automated tools such as Gerrit. Currently this inclues:


Bug: <a-bug-identifier>Reviewed-by: <name>@<domamin>CC: <name>@<domain>Signed-off-by: <name>@<domain>Please remember that anything you put in a commit message is made public. Don't use this feature to disclose an internal only mailing list (like the vending machine team), or to disclose an email address of a coworker. Please only reference people by the address they prefer to be public, e.g. their @android.com address.



Making additional changes if needed
To continue making changes to a commit, you simply follow the same process of modifying the files and committing them.


Modify your files

Add more files if needed: git add path/to/file
You only need to do this for files that are new since the last commit. See above for the same details on adding files.


Verify the current branch: git show
This is a good habit to get in, since it allows you to verify that you will be committing files to the topic branch you think you are working on.


Update branch: git commit -a --amend
The --amend options will add these changes to your current work in the branch. The git show command we did above was to verify that we will be amending to the actual branch where our existing work is.

TODO: describe how to recover if --amend is forgotten. (Create a new branch and use git merge --squash to merge the series of commits into it?)


Check status: repo status .
This command will show you any files that have been added or modified that are not committed. You should always run this to make sure you have not forgotten anything in your upload. If things are good, it will show nothing.


Send out review: repo upload --re=[e-mail] .
Sending a review involves uploading a complete copy of your commit to Gerrit. At this point you could completely remove that change from your machine and still be able to submit it through Gerrit, however it should be kept for now to deal with further changes from code reviews or resolving with other peoples' changes.


Finding an approver
Some projects in the source tree have a restricted list of people who can approve a change. You can tell if you have self-approval power by clicking on "Publish Comments" button for your patch and checking if there are "+2" radio buttons. If there are, then you have self-approval power. If not, you do not, and you need to have someone with approval power review and approve your change. 


Work on another task while waiting for review
Since we are all juggling multiple tasks, you will probably want to work on your next feature or bug while you are waiting for a review. There are three ways to do this, with slightly different workflows.


Working in a different package
This is the simplest case, as there is no conflict between your old work and your new work. You simply move to the new package, start a new branch, and get to work:


$ cd path/to/2nd/package$ repo start new-branch .To switch back and forth between the two projects (e.g. to make additional changes to the uploaded branch) you don't really need to do anything. Both old-branch and new-branch are active and can be worked on.


Working in the same package: Independent changes
If you have further work to do in the same package, but your changes are unrelated, it may be simplest to simply start a new branch. Because your changes are independent, you won't have to worry about reconciling them between branches, and your work in the new branch will not get mixed in with the change you have out for review.. You can flip back-and-forth at any time to work on either branch.


$ repo start new-branch .$ repo sync .To switch back and forth between the two branches (e.g. to make additional changes to the uploaded branch) you can use git checkout. You must be sure to stage and commit your work in progress, before you do this.


$ git add .$ git commit --amend         # caution: don't use --amend the first time you commit in a branch$ git checkout old-branch    # or new-branch to flip the other wayEach time you do this, your local sources will "flip". You will need to rebuild, refresh your IDE, etc. Your old and new changes are not intermixed.

When you finally submit one or the other branch (via gerrit), you will need to reconcile the changes before you upload the other change. You will find that repo sync complains that your branch is now "n commits behind." There are various ways to resolve this, but the simplest way is to treat it like any other change to the package, and rebase it:


$ repo sync -n .                         # download new changes$ git rebase korg/master new-branch      # or e.g. korg/donut if you're working there
Working in the same package: Dependent changes in the same package
If you have further work to do in the same package, and your new changes depend on (or build upon) your old work, you need to create a dependent branch.


$ repo start new-branch .$ git reset --hard old-branchTo switch back and forth between the two branches (e.g. to make additional changes to the uploaded branch) you can use git checkout. You must be sure to stage and commit your work in progress.


$ git add .$ git commit --amend         # caution: don't use --amend the first time you commit in a branch$ git checkout old-branchRemember, each time you do this, your local sources will "flip". However, when you flip from old-branch to new-branch, you will probably want the changes from old-branch to propagate into new-branch - here's how:


$ git add .$ git commit --amend         # caution: don't use --amend the first time you commit in a branch$ repo upload --replace .    # optional - assumes you are ready to upload old-branch for further review$ git checkout new-branch$ git rebase --onto old-branch HEAD^When you are ready to upload and submit, things are slightly more complicated. Here are the three basic steps you may be taking (though not necessarily in this order).


Upload old-branch or new-branch for review
You should be able to do this at any time. Be sure to carefully un-comment the desired change when you type repo upload --replace.


Submit old-branch after reviews & approvals
You should be able to do this at any time (if you have the necessary approvals). After this is done, you can quickly update your working tree:


$ git checkout new-branch$ repo sync .$ repo pruneAfter which "new-branch" should be properly rebased on the submitted old-branch, and thus no longer have outstanding dependencies.

TBD: Are these steps sufficient? What might go wrong or might require extra steps?


Submit new-branch after reviews & approvals
Because new-branch builds on old-branch, this would only happen after old-branch has been submitted (see above).

TBD: Because time may have elapsed since old-branch was submitted, and cleanup steps may or may not have been done, it would be nice if we could show here how to "check" and confirm that new-branch has been properly rebased and is independent of the no-longer-pending old-branch.


Update change from review comments if needed
You may need to make modifications to your commit due to reviewer feedback.


Switch to branch: repo checkout branchname .
This is only needed if you have switched to working on another branch while waiting for the review.


Modify files
Use the same steps as before in adding changes to the current work branch (edit then git add).


Modify your original change: git commit --amend
The --amend option will combine the original change, plus your new changes, and create a new change (sha1).


Upload the new patchset: repo upload --replace .
The --replace option has Gerrit replace your previous commit with the new one (with your most recent changes). If you forget to use --replace you will be creating a new change in Gerrit. To recover, simply abandon (in the Gerrit UI) either the old or new change, and proceed as appropriate from there.


Submit change in gerrit
Use the Gerrit web UI to finally submit your change, after it has been verified and approved. (Note that if you're not on the Android team, you need someone to do this for you. You'll have a button that says "Abandon Change" instead of "Submit Change".)


If gerrit reports a path conflict
Gerrit may fail at this point if other changes have happened in the tree since you started your own that potentially conflict with it. To recover, you will need to rebase (and possibly resolve) your change and then re-upload it to Gerrit.


Retrieve current source: repo sync
This will pull you up to the head of the source tree for rebasing.


Rebase branch to head: git rebase goog/tree
This will modify your current topic branch so that it is based off of the new tree head. The tree portion should be the tree you are working on: for example, "donut" or "master".

At this point there may be merge conflicts that you need to resolve. If this is the case, modify the indicated files by appropriately editing the conflict markers/text in the files, and then using git commit -a --amend as you normally would to merge them into your topic branch. Once done, use git rebase --continue to complete the merge.

TODO: how to recover if the wrong tree is used.


Update review: repo upload --replace .
Send the updated change to Gerrit to be submitted.


Cherry pick changes from other repo
A developer coordinating changes between two different repos will frequently need to bring changes from one repo into another. To do this, you have to manually cherry pick the changes. Make sure that your workspace is clean and then follow the steps below:

$ git fetch <the change url listed in git pull from the other repo>  # fetch the changes$ git cherry-pick FETCH_HEAD                                       # cherry-pick the fetched changeNote that the symref, FETCH_HEAD, points to the latest change that git fetches. One can list all the commits fetched previously using the command below:
$ git log FETCH_HEAD                                               # list fetched commits
Finish branch(es) if desired: repo prune
At this point you are done. At some point later, after you have synced to the current source, you will want to use repo prune to have repo remove any of your branches that are now merged into the tree. In some cases this may not work (such as if you for some reason rebased a branch after uploading it to gerrit), in which case you can use "repo abandon branchname ." to forcibly remove a local branch.

You may also choose to continue with related work in the branch. In that case be sure that you do not use --amend on your first commit to it!. Also be sure this is only done after you have actually successfully merged the current branch contents in to gerrit.