1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
|
<html devsite>
<head>
<title>Overview</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
Working with Android code requires using <strong>Git</strong> (an open-source
version control system) and <strong>Repo</strong> (a Google-built repository
management tool that runs on top of Git).
</p>
<h2 id="git">Git</h2>
<p>
Git is designed to handle large projects that are distributed over multiple
repositories. Android uses 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 hobbyist community to large OEMs building mass-market consumer devices. We
wanted components to be replaceable, and we wanted interesting components to
have a life of their own outside of Android. We first chose a distributed
revision control system, then narrowed it down to Git.
</p>
<p>
For more details on Git, refer to
<a href="https://git-scm.com/documentation" class="external">Git
Documentation</a>.
</p>
<h2 id="repo">Repo</h2>
<p>
Repo unifies Git repositories when necessary, performs uploads to the
<a href="https://android-review.googlesource.com/">Gerrit revision control
system</a>, 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
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.
</p>
<p>
In most situations, you can use Git instead of Repo, or mix Repo and Git
commands to form complex commands. However, using Repo for basic
across-network operations will make your work much simpler. For more details
on Repo, see the <a href="repo.html">Repo Command Reference</a>.
</p>
<h2 id="other-tools">Other tools</h2>
<p>
Other tools include
<a href="https://gerrit-review.googlesource.com/Documentation/" class="external">Gerrit</a>,
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 the
browser and enabling inline comments.
</p>
<p>
Finally,
<a href="http://developer.android.com/tools/studio/index.html" class="external">Android
Studio</a> is the official integrated development environment (IDE) for
Android application development.
</p>
<h2 id="workflow">Workflow</h2>
<p>
Android development involves the following basic workflow:
</p>
<ol>
<li>Start a new topic branch using <code>repo start</code>.
</li>
<li>Edit the files.
</li>
<li>Stage changes using <code>git add</code>.
</li>
<li>Commit changes using <code>git commit</code>.
</li>
<li>Upload changes to the review server using <code>repo upload</code>.
</li>
</ol>
<h2 id="common-tasks">Common tasks</h2>
<p>
Working with Git and Repo in the Android code repositories involves
performing the following common tasks:
</p>
<table>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
<tr>
<td><code>repo init</code></td>
<td>Initializes a new client.</td>
</tr>
<tr>
<td><code>repo sync</code></td>
<td>Syncs client to repositories.</td>
</tr>
<tr>
<td><code>repo start</code></td>
<td>Starts a new branch.</td>
</tr>
<tr>
<td><code>repo status</code></td>
<td>Shows status of current branch.</td>
</tr>
<tr>
<td><code>repo upload</code></td>
<td>Uploads changes to the review server.</td>
</tr>
<tr>
<td><code>git add</code></td>
<td>Stages files.</td>
</tr>
<tr>
<td><code>git commit</code></td>
<td>Commits staged files.</td>
</tr>
<tr>
<td><code>git branch</code></td>
<td>Shows current branches.</td>
</tr>
<tr>
<td><code>git branch [branch]</code></td>
<td>Creates new topic branch.</td>
</tr>
<tr>
<td><code>git checkout [branch]</code></td>
<td>Switches HEAD to specified branch.</td>
</tr>
<tr>
<td><code>git merge [branch]</code></td>
<td>Merges [branch] into current branch.</td>
</tr>
<tr>
<td><code>git diff</code></td>
<td>Shows diff of unstaged changes.</td>
</tr>
<tr>
<td><code>git diff --cached</code></td>
<td>Shows diff of staged changes.</td>
</tr>
<tr>
<td><code>git log</code></td>
<td>Shows history of current branch.</td>
</tr>
<tr>
<td><code>git log m/[codeline]..</code></td>
<td>Shows commits that are not pushed.</td>
</tr>
</table>
<p>
For information about using Repo to download source, see
<a href="../build/downloading.html">Downloading the Source</a> and the
<a href="repo.html">Repo Command Reference</a>.
</p>
<h3 id="synchronizing-clients">Synchronizing clients</h3>
<p>
To synchronize the files for all available projects:
</p>
<pre class="devsite-terminal devsite-click-to-copy">repo sync</pre>
<p>
To synchronize the files for selected projects:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo sync <var>PROJECT0 PROJECT1 ... PROJECTN</var>
</pre>
<h3 id="creating-topic-branches">Creating topic branches</h3>
<p>
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 is
<strong>not</strong> a copy of the original files; it is 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
<a href="http://www.kernel.org/pub/software/scm/git/docs/howto/separating-topic-branches.txt" class="external">Separating
topic branches</a>.
</p>
<p>
To start a topic branch using Repo, navigate to the project and run:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo start <var>BRANCH_NAME</var> .
</pre>
<p>
The trailing period (.) represents the project in the current working
directory.
</p>
<p>
To verify the new branch was created:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo status .
</pre>
<h3 id="using-topic-branches">Using topic branches</h3>
<p>To assign the branch to a specific project:</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo start <var>BRANCH_NAME PROJECT_NAME</var>
</pre>
<p>For a list of all projects, refer to
<a href="https://android.googlesource.com/" class="external">android.googlesource.com</a>.
If you've already navigated to the project directory, just use a period to
represent the current project.
</p>
<p>
To switch to another branch in your local work environment:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
git checkout <var>BRANCH_NAME</var>
</pre>
<p>
To view a list of existing branches:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
git branch
</pre>
<p>or</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo branches
</pre>
<p>
Both commands return the list of existing branches with the name of the
current branch preceded by an asterisk (*).
</p>
<aside class="note"><strong>Note:</strong> A bug might cause <code>repo
sync</code> to reset the local topic branch. If <code>git branch</code> shows *
(no branch) after you run <code>repo sync</code>, run <code>git checkout</code>
again.</aside>
<h3 id="staging-files">Staging files</h3>
<p>
By default, Git notices but does not track the changes you make in a project.
To tell Git to preserve your changes, you must mark or <em>stage</em> those
changes for inclusion in a commit.
</p>
<p>
To stage changes:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
git add
</pre>
<p>
This command accepts arguments for files or directories within the project
directory. Despite the name, <code>git add</code> does not simply add files to
the git repository; it can also be used to stage file modifications and
deletions.
</p>
<h3 id="viewing-client-status">Viewing client status</h3>
<p>
To list the state of files:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo status
</pre>
<p>
To view uncommitted edits (local edits that are <strong>not</strong> marked for commit):
</p>
<pre class="devsite-terminal devsite-click-to-copy">
repo diff
</pre>
<p>
To view committed edits (located edits that <strong>are marked</strong> for
commit), ensure you are in the project directory then run <code>git
diff</code> with the <code>cached</code> argument:
</p>
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">cd <var>~/WORKING_DIRECTORY/PROJECT</var></code>
<code class="devsite-terminal">git diff --cached</code>
</pre>
<h3 id="committing-changes">Committing changes</h3>
<p>
A <em>commit</em> is the basic unit of revision control in Git and consists of
a snapshot of directory structure and file contents for the entire project. To
create a commit in Git:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
git commit
</pre>
<p>
When prompted for a commit message, provide a short (but helpful) message for
changes submitted to AOSP. If you do not add a commit message, the commit is
aborted.
</p>
<h3 id="uploading-changes-to-gerrit">Uploading changes to Gerrit</h3>
<p>
Update to the latest revision, then upload the change:
</p>
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">repo sync</code>
<code class="devsite-terminal">repo upload</code>
</pre>
<p>
This command returns a list of changes you have committed and prompts you to
select the branches to upload to the review server. If there is only one
branch, you will see a simple <code>y/n</code> prompt.
</p>
<h3 id="resolving-sync-conflicts">Resolving sync conflicts</h3>
<p>
If the <code>repo sync</code> command returns sync conflicts:
</p>
<ol>
<li>View the files that are unmerged (status code = U).</li>
<li>Edit the conflict regions as necessary.</li>
<li>Change to the relevant project directory. Add and commit the affected
files, then rebase the changes:
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">git add .</code>
<code class="devsite-terminal">git commit</code>
<code class="devsite-terminal">git rebase --continue</code>
</pre>
</li>
<li>After the rebase completes, start the entire sync again:
<pre class="devsite-terminal devsite-click-to-copy">
repo sync <var>PROJECT0 PROJECT1 ... PROJECTN</var>
</pre>
</li>
</ol>
<h3 id="cleaning-up-client-files">Cleaning up clients</h3>
<p>
After merging changes to Gerrit, update your local working directory then use
<code>repo prune</code> to safely remove stale topic branches:
</p>
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">repo sync</code>
<code class="devsite-terminal">repo prune</code>
</pre>
<h3 id="deleting-clients">Deleting clients</h3>
<p>
Because all state information is stored in your client, you only need to
delete the directory from your filesystem:
</p>
<pre class="devsite-terminal devsite-click-to-copy">
rm -rf <var>WORKING_DIRECTORY</var>
</pre>
<p>
Deleting a client <em>permanently deletes</em> any changes you have not yet
uploaded for review.
</p>
</body>
</html>
|
