1 <!-- 2 Copyright 2010 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 --> 16 17 # Version Control with Repo and Git # 18 19 To work with the Android code, you will need to use both Git and Repo. In most situations, you can use Git instead of Repo, or mix Repo and Git commands to form complex commands. Using Repo for basic across-network operations will make your work much simpler, however. 20 21 **Git** is an open-source version-control system designed to handle very large projects that are distributed over multiple repositories. In the context of Android, we use 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 hobbiest community to large OEMs building mass-market consumer devices. We wanted components to be replaceable, and we wanted interesting components to be able to grow a life of their own outside of Android. We first chose a distributed revision control system, then further narrowed it down to Git. 22 23 **Repo** is a repository management tool that we built on top of Git. Repo unifies the many Git repositories when necessary, does the uploads to our [revision control system](http://review.source.android.com/), 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 will 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. 24 25 **Gerrit** is 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-browser and enabling inline comments. 26 27 ## Basic Workflow ## 28 29 <div style="float:right"> 30 <img src="/images/submit-patches-0.png"> 31 </div> 32 33 The basic pattern of interacting with the repositories is as follows: 34 35 1. Use `repo start` to start a new topic branch. 36 37 1. Edit the files. 38 39 1. Use `git add` to stage changes. 40 41 1. Use `git commit` to commit changes. 42 43 1. Use `repo upload` to upload changes to the review server. 44 45 # Task reference # 46 47 The task list below shows a summary of how to do common Repo and Git tasks. 48 For complete quick-start information and examples, see [Getting started](downloading.html). 49 50 ## Synchronizing your client ## 51 52 To synchronize the files for all available projects: 53 54 $ repo sync 55 56 To synchronize the files for selected projects: 57 58 $ repo sync PROJECT0 PROJECT1 PROJECT2 ... 59 60 ## Creating topic branches ## 61 62 Start a topic branch in your local work environment whenever you begin a change, for example 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. This makes creating local branches and switching among them a light-weight operation. By using branches, you can isolate one aspect of your work from the others. For an interesting article about using topic branches, see [Separating topic branches](http://www.kernel.org/pub/software/scm/git/docs/howto/separating-topic-branches.txt). 63 <img src="/images/external-link.png"> 64 65 To start a topic branch using Repo: 66 67 $ repo start BRANCH_NAME 68 69 To verify that your new branch was created: 70 71 $ repo status 72 73 ## Using topic branches ## 74 75 To assign the branch to a particular project: 76 77 $ repo start BRANCH_NAME PROJECT 78 79 To switch to another branch that you have created in your local work environment: 80 81 $ git checkout BRANCH_NAME 82 83 To see a list of existing branches: 84 85 $ git branch 86 87 or 88 89 $ repo branches 90 91 The name of the current branch will be preceded by an asterisk. 92 93 *Note: A bug might be causing `repo sync` to reset the local topic branch. If `git branch` shows \* (no branch) after you run `repo sync`, then run `git checkout` again.* 94 95 ## Staging files ## 96 97 By default, Git notices but does not track the changes you make in a project. In order to tell git to preserve your changes, you must mark them for inclusion in a commit. This is also called "staging". 98 99 You can stage your changes by running 100 101 git add 102 103 which accepts as arguments any 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. 104 105 ## Viewing client status ## 106 107 To list the state of your files: 108 109 $ repo status 110 111 To see uncommitted edits: 112 113 $ repo diff 114 115 The `repo diff` command shows every local edit that you have made that would *not* go into the commit, if you were to commit right now. To see every edit that would go into the commit if you were to commit right now, you need a Git command, `git diff`. Before running it, be sure you are in the project directory: 116 117 $ cd ~/WORKING_DIRECTORY/PROJECT 118 $ git diff --cached 119 120 ## Committing changes ## 121 122 A commit is the basic unit of revision control in git, consisting of a snapshot of directory structure and file contents for the entire project. Creating a commit in git is as simple as typing 123 124 git commit 125 126 You will be prompted for a commit message in your favorite editor; please provide a helpful message for any changes you submit to the AOSP. If you do not add a log message, the commit will be aborted. 127 128 ## Uploading changes to Gerrit ## 129 130 Before uploading, update to the latest revisions: 131 132 repo sync 133 134 Next run 135 136 repo upload 137 138 This will list the changes you have committed and prompt you to select which branches to upload to the review server. If there is only one branch, you will see a simple `y/n` prompt. 139 140 ## Recovering sync conflicts ## 141 142 If a `repo sync` shows sync conflicts: 143 144 - View the files that are unmerged (status code = U). 145 - Edit the conflict regions as necessary. 146 - Change into the relevant project directory, run `git add` and `git commit` for the files in question, and then "rebase" the changes. For example: 147 148 $ git add . 149 $ git commit 150 $ git rebase --continue 151 152 - When the rebase is complete start the entire sync again: 153 154 $ repo sync PROJECT0 PROJECT1 ... PROJECTN 155 156 ## Cleaning up your client files ## 157 158 To update your local working directory after changes are merged in Gerrit: 159 160 $ repo sync 161 162 To safely remove stale topic branches: 163 164 $ repo prune 165 166 ## Deleting a client ## 167 168 Because all state information is stored in your client, you only need to delete the directory from your filesystem: 169 170 $ rm -rf WORKING_DIRECTORY 171 172 Deleting a client will *permanently delete* any changes you have not yet uploaded for review. 173 174 # Git and Repo cheatsheet # 175 176 <img src="/images/git-repo-1.png"> 177 178 179
