New workflow for replacing gclient with git submodules.

Introduction

gclient has its fans and detractors. Among the chief criticisms of gclient is its opaqueness; another is its tendency to modify your working copy in unexpected ways.

This flow, based on git-submodules, is offered as a simpler, more transparent, and more git-ish alternative.

If you have been using gclient, you do not need a clean checkout to start using the submodule flow. You may switch to using the submodule commands at any time. (If you are a Google employee working with Google-internal code, you will need to run a quick, one-time, reversible migration script. Check internal docs.)

Note that this does not have any effect on how you will use 'git-cl' for creating/uploading/committing CL's. That remains the same.

Minimum requirements

• git version >= 1.7.8. The Windows bootstrapping flow will ensure this requirement is met. If you're on Linux or Mac, you'll need to verify this yourself by running 'git --version'.

Getting Started

• If you haven't yet, follow the instructions for installing depot_tools.
• Double-check you have completed the important prerequisites for using Git correctly.
• Clone the top-level chromium source:

> git clone --template=$PATH_TO_YOUR_DEPOT_TOOLS/git-templates https://chromium.googlesource.com/chromium/src.git

• ... or, if you're working with an existing checkout, copy over the git template files manually:

> cp -rf $PATH_TO_YOUR_DEPOT_TOOLS/git-templates/* src/.git/

• If you are cross-compiling (e.g., for android), explicitly set the target OS. You can refer to the "deps_os" sections in the file src/DEPS to get the known target names. Be sure to do this before running 'git-crsync' for the first time.

> cd src
> git config target.os android

• At this point, you should run 'git crsync' once, as explained below, to initialize a few boilerplate git configs in your checkout. Only if you're curious, here are the details:
• When running commands like 'git status' and 'git commit -a', you typically want git to ignore the state of your submodule checkouts. That behavior is controlled by the 'submodule.<name>.ignore' git config option.
• When running any 'git diff' command, you likewise want git to ignore diffs in your submodule checkouts. This is important when running 'git cl upload', because that command runs 'git diff' to ensure that you're not uploading from a dirty tree.

• If you're a committer, and you have not already done so, follow the instructions for setting up git-svn mirroring.

Using git submodules

In most regards, your workflow will be the same as the git unmanaged flow. Here are the differences:

• You won't have a .gclient file in your working directory. If you do have one, make sure you rename or delete it.

• You are responsible for managing your top-level (src) checkout, using raw git commands like 'git fetch', 'git pull', 'git rebase', 'git checkout', etc.

• To update dependencies, instead of 'gclient sync', use the git-crsync script in depot_tools like this:

> git crsync [-j [jobs]] [--no-hooks]

• The -j argument may be used to set the degree of parallel execution in fetching submodules (default is 10).
• After updating, git-crsync will run hooks to update to the latest toolchain versions and regenerate build files (the same stuff that 'gclient runhooks' does). If you want to skip the hooks, use the --no-hooks flag.

• If you would like to run a single command to update your top-level src checkout with the latest changes from the remote server and then update submodules (roughly equivalent to what 'gclient sync' does), The command 'git crup' is shorthand for 'git pull origin && git crsync'.

git try

Using git try to submit jobs may require passing another flag. If you get errors during the patch/update step, use the '--root=src' flag:

> git try -b mac_rel,linux_rel --root=src

How do I ...

Check out a different revision of a submodule

You can control the checked out revision of a submodule, rather than pinning it to the version listed in the DEPS file:

• Disable updating of the submodule. This means that commands like 'git submodule update' and 'git crsync' will skip it.

> git config submodule.third_party/WebKit.update none

• Manually check out the revision you want. Note that if you want to always float to tip-of-tree, you will have to do this periodically; there is no "automatic" updating of a submodule to the latest revision on a branch:

> cd third_party/WebKit
> git fetch origin && git checkout origin/master

• To disable this behavior, and update the submodule checkout according to DEPS:

> git config submodule.third_party/WebKit.update checkout
> git submodule update third_party/WebKit

Do the equivalent of 'gclient runhooks'

> git runhooks

Run hooks automatically every time I switch branches

Create a post-checkout git hook:

> cat <<EOF > .git/hooks/post-checkout
#!/bin/bash

git runhooks
EOF

Sync to LKGR

There is a remote branch named lkgr that always points to the lkgr revision. To check out the lkgr branch:

> git checkout origin/lkgr

To create a working branch based on lkgr:

> git branch my_work_branch refs/remotes/origin/lkgr
> git checkout my_work_branch

Sync to an older revision

Run the following on master:

> git checkout [hash to sync to]
> git crsync

You can find the hash to sync to by using git lkgr -r [svn revision].