| <html devsite><head> |
| <title>概览</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> |
| 要使用 Android 代码，您需要使用 <strong>Git</strong>（一种开源版本控制系统）和 <strong>Repo</strong>（一种对 Git 构成补充的 Google 代码库管理工具）。 |
| </p> |
| |
| <h2 id="git">Git</h2> |
| |
| <p> |
| Git 旨在处理分布在多个代码库上的大型项目。Android 使用 Git 执行本地操作，例如建立本地分支、提交、对比差异、修改。打造 Android 项目所面临的挑战之一就是确定如何最好地支持外部社区 - 从业余爱好者社区到生产大众消费类设备的大型 OEM。我们希望组件可以替换，并希望有趣的组件能够在 Android 之外自行发展。我们最初决定使用一种分布式修订版本控制系统，经过筛选，最后选中了 Git。 |
| </p> |
| |
| <p> |
| 要详细了解 Git，请参阅 <a href="https://git-scm.com/documentation" class="external">Git 文档</a>。 |
| </p> |
| |
| <h2 id="repo">Repo</h2> |
| <p> |
| Repo 可以在必要时整合 Git 代码库，将相关内容上传到我们的 <a href="https://android-review.googlesource.com/">Gerrit 修订版本控制系统</a>，并自动执行 Android 开发工作流程的部分环节。Repo 并非用来取代 Git，只是为了让您在 Android 环境中更轻松地使用 Git。Repo 命令是一段可执行的 Python 脚本，您可以将其放在路径中的任何位置。使用 Android 源代码文件时，您可以使用 Repo 执行跨网络操作。例如，您可以用一个 Repo 命令，将文件从多个代码库下载到本地工作目录。 |
| </p> |
| |
| <p> |
| 在大多数情况下，您可以仅使用 Git（不必使用 Repo），或结合使用 Repo 和 Git 命令以组成复杂的命令。不过，使用 Repo 执行基本的跨网络操作可大大简化您的工作。要详细了解 Repo，请参阅 <a href="/setup/develop/repo">Repo 命令参考资料</a>。 |
| </p> |
| |
| <h2 id="other-tools">其他工具</h2> |
| |
| <p> |
| 其他工具包括 <a href="https://gerrit-review.googlesource.com/Documentation/" class="external">Gerrit</a>，这是一个基于网页的代码审核系统，适用于使用 Git 的项目。Gerrit 允许所有授权用户提交更改（如果通过代码审核，这些更改会自动纳入项目中），以此鼓励他们更集中地使用 Git。此外，Gerrit 可以在浏览器中并排显示更改，并支持代码内注释，使得审核工作变得更轻松。 |
| </p> |
| |
| <p> |
| 最后，<a href="http://developer.android.com/tools/studio/index.html" class="external">Android Studio</a> 是用于开发 Android 应用的官方集成开发环境 (IDE)。 |
| </p> |
| |
| <h2 id="workflow">工作流程</h2> |
| |
| <p> |
| Android 开发涉及以下基本工作流程： |
| </p> |
| |
| <ol> |
| <li>使用 <code>repo start</code> 新建一个主题分支。 |
| </li> |
| <li>修改文件。 |
| </li> |
| <li>使用 <code>git add</code> 暂存更改。 |
| </li> |
| <li>使用 <code>git commit</code> 提交更改。 |
| </li> |
| <li>使用 <code>repo upload</code> 将更改上传到审核服务器。 |
| </li> |
| </ol> |
| |
| <h2 id="common-tasks">常见任务</h2> |
| |
| <p> |
| 在 Android 代码库中使用 Git 和 Repo 会涉及到执行以下常见任务： |
| </p> |
| |
| <table> |
| <tbody><tr> |
| <th>命令</th> |
| <th>说明</th> |
| </tr> |
| <tr> |
| <td><code>repo init</code></td> |
| <td>初始化一个新客户端。</td> |
| </tr> |
| <tr> |
| <td><code>repo sync</code></td> |
| <td>将客户端同步到代码库。</td> |
| </tr> |
| <tr> |
| <td><code>repo start</code></td> |
| <td>新建一个分支。</td> |
| </tr> |
| <tr> |
| <td><code>repo status</code></td> |
| <td>显示当前分支的状态。</td> |
| </tr> |
| <tr> |
| <td><code>repo upload</code></td> |
| <td>将更改上传到审核服务器。</td> |
| </tr> |
| <tr> |
| <td><code>git add</code></td> |
| <td>暂存文件。</td> |
| </tr> |
| <tr> |
| <td><code>git commit</code></td> |
| <td>提交已暂存文件。</td> |
| </tr> |
| <tr> |
| <td><code>git branch</code></td> |
| <td>显示当前分支。</td> |
| </tr> |
| <tr> |
| <td><code>git branch [branch]</code></td> |
| <td>创建新的主题分支。</td> |
| </tr> |
| <tr> |
| <td><code>git checkout [branch]</code></td> |
| <td>将 HEAD 切换到指定分支。</td> |
| </tr> |
| <tr> |
| <td><code>git merge [branch]</code></td> |
| <td>将 [branch] 合并到现有分支。</td> |
| </tr> |
| <tr> |
| <td><code>git diff</code></td> |
| <td>显示未暂存更改的 diff 结果。</td> |
| </tr> |
| <tr> |
| <td><code>git diff --cached</code></td> |
| <td>显示已暂存更改的 diff 结果。</td> |
| </tr> |
| <tr> |
| <td><code>git log</code></td> |
| <td>显示现有分支的历史记录。</td> |
| </tr> |
| <tr> |
| <td><code>git log m/[codeline]..</code></td> |
| <td>显示未推送的提交。</td> |
| </tr> |
| </tbody></table> |
| |
| <p> |
| 要了解如何使用 Repo 下载源代码，请参阅<a href="/setup/build/downloading">下载源代码</a>和 <a href="/setup/develop/repo">Repo 命令参考资料</a>。 |
| </p> |
| |
| <h3 id="synchronizing-clients">同步客户端</h3> |
| |
| <p> |
| 要同步所有可用项目的文件，请运行以下命令：</p> |
| <pre class="devsite-terminal devsite-click-to-copy">repo sync</pre> |
| |
| <p> |
| 要同步所选项目的文件，请运行以下命令：</p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo sync <var>PROJECT0 PROJECT1 ... PROJECTN</var> |
| </pre> |
| |
| <h3 id="creating-topic-branches">创建主题分支</h3> |
| |
| <p> |
| 当您开始进行更改（例如当您开始修复错误或实现新功能）时，请在本地工作环境中新建一个主题分支。主题分支<strong>不</strong>是原始文件的副本；它指向某一项提交记录，可以简化创建本地分支以及在本地分支之间进行切换的操作。通过使用分支，您可以将工作的某个方面与其他方面分隔开来。请参阅<a href="http://www.kernel.org/pub/software/scm/git/docs/howto/separating-topic-branches.txt" class="external">分隔主题分支</a>（一篇有关使用主题分支的有趣文章）。 |
| </p> |
| |
| <p> |
| 要使用 Repo 新建一个主题分支，请转到相应项目并运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo start <var>BRANCH_NAME</var> . |
| </pre> |
| |
| <p> |
| 尾随句点 (.) 代表当前工作目录中的项目。 |
| </p> |
| |
| <p> |
| 要验证新分支是否已创建，请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo status . |
| </pre> |
| |
| <h3 id="using-topic-branches">使用主题分支</h3> |
| |
| <p>要将分支分配给特定项目，请运行以下命令：</p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo start <var>BRANCH_NAME PROJECT_NAME</var> |
| </pre> |
| |
| <p>要查看所有项目的列表，请参阅 <a href="https://android.googlesource.com/" class="external">android.googlesource.com</a>。如果您已转到相应的项目目录，则只需使用一个句点来表示当前项目即可。 |
| </p> |
| |
| <p> |
| 要切换到本地工作环境中的另一个分支，请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| git checkout <var>BRANCH_NAME</var> |
| </pre> |
| |
| <p> |
| 要查看现有分支的列表，请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| git branch |
| </pre> |
| |
| <p>或</p> |
| |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo branches |
| </pre> |
| |
| <p> |
| 这两个命令均可返回现有分支的列表，并会在当前分支的名称前面标注星号 (*)。 |
| </p> |
| |
| <aside class="note"><strong>注意</strong>：如果存在错误，可能会导致 <code>repo |
| sync</code> 重置本地主题分支。如果在您运行 <code>repo sync</code> 之后，<code>git branch</code> 显示 *（无分支），请再次运行 <code>git checkout</code>。</aside> |
| |
| <h3 id="staging-files">暂存文件</h3> |
| |
| <p> |
| 默认情况下，Git 会检测到您在项目中所做的更改，但不会跟踪这些更改。要让 Git 保存您的更改，您必须标记或暂存这些更改，以将其纳入到提交中。<em></em> |
| </p> |
| |
| <p> |
| 要暂存更改，请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| git add |
| </pre> |
| |
| <p> |
| 该命令接受将项目目录中的文件或目录作为参数。<code>git add</code> 并不像其名称表示的这样只是简单地将文件添加到 Git 代码库，它还可以用于暂存文件的修改和删除的内容。 |
| </p> |
| |
| <h3 id="viewing-client-status">查看客户端状态</h3> |
| |
| <p> |
| 要列出文件状态，请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo status |
| </pre> |
| |
| <p> |
| 要查看未提交的修改（<strong>未</strong>标记为需要提交的本地修改），请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| repo diff |
| </pre> |
| |
| <p> |
| 要查看已提交的修改（<strong>已标记为</strong>需要提交的本地修改），请确保您已转到相应的项目目录，然后运行包含 <code>cached</code> 参数的 <code>git |
| diff</code>： |
| </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">提交更改</h3> |
| |
| <p> |
| 在 Git 中，提交是修订版本控制的基本单位，包含目录结构的快照以及整个项目的文件内容。<em></em>要在 Git 中创建提交，请运行以下命令： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| git commit |
| </pre> |
| |
| <p> |
| 当系统提示您输入提交消息时，请针对要提交至 AOSP 的更改提供一条简短（但有用）的消息。如果您不添加提交消息，提交将会中止。 |
| </p> |
| |
| <h3 id="uploading-changes-to-gerrit">将更改上传到 Gerrit</h3> |
| |
| <p> |
| 请更新至最新版本，然后上传相应更改： |
| </p> |
| <pre class="devsite-click-to-copy"> |
| <code class="devsite-terminal">repo sync</code> |
| <code class="devsite-terminal">repo upload</code> |
| </pre> |
| |
| <p> |
| 运行此命令后，系统会随即列出您已提交的更改，并提示您选择要上传到审核服务器的哪个分支。如果只有一个分支，则您会看到一个简单的 <code>y/n</code> 提示符。 |
| </p> |
| |
| <h3 id="resolving-sync-conflicts">解决同步冲突</h3> |
| |
| <p> |
| 如果 <code>repo sync</code> 命令提示同步冲突，请执行以下操作： |
| </p> |
| |
| <ol> |
| <li>查看未合并的文件（状态代码 = U）。</li> |
| <li>根据需要修改存在冲突的地方。</li> |
| <li>对相关项目目录进行更改。添加并提交受影响的文件，然后对这些更改执行“衍合”(rebase) 命令：<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>当衍合完成后，再一次开始整个同步过程：<pre class="devsite-terminal devsite-click-to-copy"> |
| repo sync <var>PROJECT0 PROJECT1 ... PROJECTN</var> |
| </pre> |
| </li> |
| </ol> |
| |
| <h3 id="cleaning-up-client-files">清理客户端</h3> |
| <p> |
| 将更改合并到 Gerrit 之后，请更新您的本地工作目录，然后使用 <code>repo prune</code> 安全地移除已过时的主题分支： |
| </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">删除客户端</h3> |
| <p> |
| 由于所有状态信息都会存储在客户端中，您只需从文件系统中删除相应目录即可： |
| </p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| rm -rf <var>WORKING_DIRECTORY</var> |
| </pre> |
| |
| <p> |
| 删除客户端将永久删除您尚未上传以供审核的所有更改。<em></em> |
| </p> |
| |
| </body></html> |
