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 # Repo command reference # 18 19 Repo usage takes the following form: 20 21 repo COMMAND OPTIONS 22 23 Optional elements are shown in brackets [ ]. Once Repo is installed, you can get information about any command by running 24 25 repo help COMMAND 26 27 Many commands take a project list as an argument. You can specify project-list as a list of names or a list of paths to local source directories for the projects: 28 29 repo sync [PROJECT0 PROJECT1 ... PROJECTN] 30 repo sync [/PATH/TO/PROJECT0 ... /PATH/TO/PROJECTN] 31 32 [TOC] 33 34 ## init ## 35 36 $ repo init -u URL [OPTIONS] 37 38 Installs Repo in the current directory. This creates a `.repo/` directory that contains Git repositories for the Repo source code and the standard Android manifest files. The `.repo/` directory also contains `manifest.xml`, which is a symlink to the selected manifest in the `.repo/manifests/` directory. 39 40 Options: 41 42 * `-u`: specify a URL from which to retrieve a manifest repository. The common manifest can be found at `git://android.git.kernel.org/platform/manifest.git` 43 44 * `-m`: select a manifest file within the repository. If no manifest name is selected, the default is default.xml. 45 46 * `-b`: specify a revision, i.e., a particular manifest-branch. 47 48 *Note: For all remaining Repo commands, the current working directory must either be the parent directory of `.repo/` or a subdirectory of the parent directory.* 49 50 51 ## sync ## 52 53 repo sync [PROJECT_LIST] 54 55 Downloads new changes and updates the working files in your local environment. If you run `repo sync` without any arguments, it will synchronize the files for all the projects. 56 57 When you run `repo sync`, this is what happens: 58 59 - If the project has never been synchronized, then `repo sync` is equivalent to `git clone`. All branches in the remote repository are copied to the local project directory. 60 61 - If the project has already been synchronized once, then `repo sync` is equivalent to: 62 63 git remote update 64 git rebase origin/BRANCH 65 66 where `BRANCH` is the currently checked-out branch in the local project directory. If the local branch is not tracking a branch in the remote repository, then no synchronization will occur for the project. 67 68 - If the git rebase operation results in merge conflicts, you will need to use the normal Git commands (for example, `git rebase --continue`) to resolve the conflicts. 69 70 After a successful `repo sync`, the code in specified projects will be up to date with the code in the remote repository. 71 72 Options: 73 74 * `-d`: switch specified projects back to the manifest revision. Helpful if the project is currently on a topic branch, but the manifest revision is temporarily needed. 75 76 * `-s`: sync to a known good build as specified by the manifest-server element in the current manifest. 77 78 * `-f`: proceed with syncing other projects even if a project fails to sync. 79 80 81 ## upload ## 82 83 repo upload [PROJECT_LIST] 84 85 For the specified projects, Repo compares the local branches to the remote branches updated during the last repo sync. Repo will prompt you to select one or more of the branches that have not yet been uploaded for review. 86 87 After you select one or more branches, all commits on the selected branches are transmitted to Gerrit over an SSH connection.You will need to configure an SSH key to enable upload authorization. Visit [SSH Keys](http://review.source.android.com/Gerrit#settings,ssh-keys) within the user settings panel to register your public keys with Gerrit. To enable password-less uploads, consider using ssh-agent on your client system. 88 89 When Gerrit receives the object data over its SSH server, it will turn each commit into a change so that reviewers can comment on each commit individually. To combine several "checkpoint" commits together into a single commit, use git rebase -i before you run repo upload. 90 91 If you run repo upload without any arguments, it will search all the projects for changes to upload. 92 93 To make edits to changes after they have been uploaded, you should use a tool like `git rebase -i` or `git commit --amend` to update your local commits. After your edits are complete: 94 95 - Make sure the updated branch is the currently checked out branch. 96 97 - Use `repo upload --replace PROJECT` to open the change matching editor. 98 99 - For each commit in the series, enter the Gerrit change ID inside the brackets: 100 101 # Replacing from branch foo 102 [ 3021 ] 35f2596c Refactor part of GetUploadableBranches to lookup one specific... 103 [ 2829 ] ec18b4ba Update proto client to support patch set replacments 104 [ 3022 ] c99883fe Teach 'repo upload --replace' how to add replacement patch se... 105 # Insert change numbers in the brackets to add a new patch set. 106 # To create a new change record, leave the brackets empty. 107 108 After the upload is complete the changes will have an additional Patch Set. 109 110 111 ## diff ## 112 113 repo diff [PROJECT_LIST] 114 115 Shows outstanding changes between commit and working tree using `git diff`. 116 117 118 ## download ## 119 120 repo download TARGET CHANGE 121 122 Downloads the specified change from the review system and makes it available in your project's local working directory. 123 124 For example, to download [change 1241](http://review.source.android.com/1241) into your platform/frameworks/base directory: 125 126 $ repo download platform/frameworks/base 1241 127 128 A `repo sync` should effectively remove any commits retrieved via `repo download`. Or, you can check out the remote branch; e.g., `git checkout m/master`. 129 130 *Note: There is a slight mirroring lag between when a change is visible on the web in [Gerrit](http://review.source.android.com) and when `repo download` will be able to find it, because changes are actually downloaded off the git://android.git.kernel.org/ mirror farm. Hence there will always be a lag of approximately 5 minutes before Gerrit pushes newly uploaded changes out to the mirror farm.* 131 132 133 ## forall ## 134 135 repo forall [PROJECT_LIST] -c COMMAND 136 137 Executes the given shell command in each project. The following additional environment variables are made available by `repo forall`: 138 139 * `REPO_PROJECT` is set to the unique name of the project. 140 141 * `REPO_PATH` is the path relative to the root of the client. 142 143 * `REPO_REMOTE` is the name of the remote sstem from the manifest. 144 145 * `REPO_LREV` is the name of the revision from the manifest, translated to a local tracking branch. Used if you need to pass the manifest revision to a locally executed git command. 146 147 * `REPO_RREV` is the name of the revision from the manifest, exactly as written in the manifest. 148 149 Options: 150 151 * `-c`: command and arguments to execute. The command is evaluated through `/bin/sh` and any arguments after it are passed through as shell positional parameters. 152 153 * `-p`: show project headers before output of the specified command. This is achieved by binding pipes to the command's stdin, stdout, and sterr streams, and piping all output into a continuous stream that is displayed in a single pager session. 154 155 * `-v`: show messages the command writes to stderr. 156 157 158 ## prune ## 159 160 repo prune [PROJECT_LIST] 161 162 Prunes (deletes) topics that are already merged. 163 164 165 ## start ## 166 167 repo start BRANCH_NAME [PROJECT_LIST] 168 169 Begins a new branch for development, starting from the revision specified in the manifest. 170 171 The `BRANCH_NAME` argument should provide a short description of the change you are trying to make to the projects.If you don't know, consider using the name default. 172 173 The `PROJECT_LIST` specifies which projects will participate in this topic branch. 174 175 *Note: "." is a useful shorthand for the project in the current working directory.* 176 177 178 ## status ## 179 180 repo status [PROJECT_LIST] 181 182 Compares the working tree to the staging area (index) and the most recent commit on this branch (HEAD) in each project specified. Displays a summary line for each file where there is a difference between these three states. 183 184 To see the status for only the current branch, run `repo status`. The status information will be listed by project. For each file in the project, a two-letter code is used: 185 186 In the first column, an uppercase letter indicates how the staging area differs from the last committed state. 187 188 letter | meaning | description 189 -------|----------------|------------------------- 190 - | no change | same in HEAD and index 191 A | added | not in HEAD, in index 192 M | modified | in HEAD, modified in index 193 D | deleted | in HEAD, not in index 194 R | renamed | not in HEAD, path changed in index 195 C | copied | not in HEAD, copied from another in index 196 T | mode changed | same content in HEAD and index, mode changed 197 U | unmerged | conflict between HEAD and index; resolution required 198 199 In the second column, a lowercase letter indicates how the working directory differs from the index. 200 201 letter | meaning | description 202 -------|----------------|---------------------------- 203 - | new/unknown | not in index, in work tree 204 m | modified | in index, in work tree, modified 205 d | deleted | in index, not in work tree 206 207 208
