# gclient

gclient is a tool for managing a modular checkout of source code from multiple
source code repositories. It wraps underlying source code management commands
to provide support for distributing tree updates, status commands, and diffs
across multiple checked-out working directories.

The gclient script is controlled by a `.gclient` file at the top of a directory
tree which will contain source code from multiple locations. A `.gclient` file
is a Python script that defines a list of `solutions` with the following format:

    solutions = [
      { "name"        : "src",
        "url"         : "https://chromium.googlesource.com/chromium/src.git",
        "custom_deps" : {
          # To use the trunk of a component instead of what's in DEPS:
          #"component": "https://github.com/luci/luci-go",
          # To exclude a component from your working copy:
          #"data/really_large_component": None,
        }
      },
    ]

A `solution` is a collection of component pieces of software that will be
checked out in a specific directory layout for building together.

Each entry in the `solutions` list is defined by a Python dictionary that
contains the following items:

- `name`: The name of the directory in which the solution will be checked out.
- `url`: The URL from which this solution will be checked out. gclient expects
  that the checked-out solution will contain a file named `DEPS` that in turn
  defines the specific pieces that must be checked out to create the working
  directory layout for building and developing the solution's software.
- `deps_file`: A string containing just the filename (not a path) of the file in
  the solution dir to use as the list of dependencies. This tag is optional, and
  defaults to `DEPS`.
- `custom_deps`: A dictionary containing optional custom overrides for entries
  in the solution's `DEPS` file.  This can be used to have the local working
  directory *not* check out and update specific components, or to sync the local
  working-directory copy of a given component to a different specific revision,
  or a branch, or the head of a tree. It can also be used to append new entries
  that do not exist in the `DEPS` file.

Within each checked-out solution, gclient expects to find a file typically named
`DEPS` (it actually uses the value of the `deps_file` key above) which defines
the different component pieces of software that must be checked out for the
solution. The `DEPS` file is a Python script that defines a dictionary named
`deps`:

    deps = {
      "src/outside": "https://outside-server/one/repo.git@12345677890123456778901234567789012345677890",
      "src/component": "https://dont-use-github.com/its/unreliable.git@0000000000000000000000000000000000000000",
      "src/relative": "/another/repo.git@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    }

Each item in the `deps` dictionary consists of a key-value pair. The key is the
directory into which the component will be checked out, relative to the
directory containing the `.gclient` file. The value is the URL from which that
directory will be checked out. If there is no address scheme (that is, no
`http:` prefix), then the value must begin with a slash and is treated
relative to the root of the solution's repository.

The URL typically contains a specific revision or change number (as appropriate
for the underlying SCM system) to `freeze` the external software at a specific,
known state. Alternatively, if there is no revision or change number, the URL
will track the latest changes on the specific trunk or branch.

# git-cl

The git-cl README describes the git-cl command set. This document describes how
code review and git work together in general, intended for people familiar with
git but unfamiliar with the code review process supported by Rietveld and
Gerrit.


## Basic interaction with git

The fundamental problem you encounter when you try to mix git and code review is
that with git it's nice to commit code locally, while during a code review
you're often requested to change something about your code. There are a few
different ways you can handle this workflow with git:

1. Rewriting a single commit. Say the origin commit is O, and you commit your
   initial work in a commit A, making your history like O--A. After review
   comments, you `git commit --amend`, effectively erasing A and making a new
   commit A', so history is now O--A'. (Equivalently, you can use
   `git reset --soft` or `git rebase -i`.)
2. Writing follow-up commits. Initial work is again in A, and after review
   comments, you write a new commit B so your history looks like O--A--B. When
   you upload the revised patch, you upload the diff of O..B, not A..B; you
   always upload the full diff of what you're proposing to change.

The Rietveld patch uploader just takes arguments to `git diff`, so either of the
above workflows work fine.  If all you want to do is upload a patch, you can use
the upload.py provided by Rietveld with arguments like this:

    upload.py --server server.com <args to "git diff">

The first time you upload, it creates a new issue; for follow-ups on the same
issue, you need to provide the issue number:

    upload.py --server server.com --issue 1234 <args to "git diff">


## git-cl to the rescue

git-cl simplifies the above in the following ways:

1. `git cl config` puts a persistent --server setting in your .git/config.
2. The first time you upload an issue, the issue number is associated with the
   current *branch*.  If you upload again, it will upload on the same issue.
   (Note that this association is tied to a branch, not a commit, which means
   you need a separate branch per review.)
3. If your branch is _tracking_ (in the `git checkout --track` sense) another
   one (like origin/master), calls to `git cl upload` will diff against that
   branch by default.  (You can still pass arguments to `git diff` on the
   command line, if necessary.)

In the common case, this means that calling simply `git cl upload` will always
upload the correct diff to the correct place.


## Patch series

The above is all you need to know for working on a single patch.

Things get much more complicated when you have a series of commits that you want
to get reviewed. Say your history looks like O--A--B--C. If you want to upload
that as a single review, everything works just as above.

But what if you upload each of A, B, and C as separate reviews? What if you
then need to change A?

1. One option is rewriting history: write a new commit A', then use
   `git rebase -i` to insert that diff in as O--A--A'--B--C as well as squash
   it. This is sometimes not possible if B and C have touched some lines
   affected by A'.
2. Another option, and the one espoused by software like topgit, is for you to
   have separate branches for A, B, and C, and after writing A' you merge it
   into each of those branches. (topgit automates this merging process.)  This
   is also what is recommended by git-cl, which likes having different branch
   identifiers to hang the issue number off of.  Your history ends up looking
   like:

       O---A---B---C
            \   \   \
             A'--B'--C'

   Which is ugly, but it accurately tracks the real history of your work, can be
   thrown away at the end by committing A+A' as a single `squash` commit.

In practice, this comes up pretty rarely. Suggestions for better workflows are
welcome.

## Bash auto completion

1. Ensure that your base git commands are autocompleted
[doc](https://git-scm.com/book/en/v1/Git-Basics-Tips-and-Tricks).
2. Add this to your .bashrc:

        # The next line enables bash completion for git cl.
        if [ -f "$HOME/bin/depot_tools/git_cl_completion.sh" ]; then
          . "$HOME/bin/depot_tools/git_cl_completion.sh"
        fi

3. Profit.

# depot_tools

Tools for working with Chromium development. It requires python 2.7 or 3.8 for python 3 support.


## Tools

The most important tools are:

- `fetch`: A `gclient` wrapper to checkout a project. Use `fetch --help` for
  more details.
- `gclient`: A meta-checkout tool. Think
  [repo](https://source.android.com/source/using-repo.html) or [git
  submodules](https://git-scm.com/docs/git-submodule), except that it support
  OS-specific rules, e.g. do not checkout Windows only dependencies when
  checking out for Android. Use `gclient help` for more details and
  [README.gclient.md](README.gclient.md).
- `git cl`: A code review tool to interact with Rietveld or Gerrit. Use `git cl
  help` for more details and [README.git-cl.md](README.git-cl.md).
- `roll-dep`: A gclient dependency management tool to submit a _dep roll_,
  updating a dependency to a newer revision.

There are a lot of git utilities included.


## Updating

`depot_tools` updates itself automatically when running `gclient` tool. To
disable auto update, set the environment variable `DEPOT_TOOLS_UPDATE=0`.

To update package manually, run `update_depot_tools.bat` on Windows,
or `./update_depot_tools` on Linux or Mac.

On Windows only, running `gclient` will install `git` and `python`.


## Contributing

To contribute change for review:

    git new-branch <somename>
    # Hack
    git add .
    git commit -a -m "Fixes goat teleporting"
    # find reviewers
    git cl owners
    git log -- <yourfiles>

    # Request a review.
    git cl upload -r reviewer1@chromium.org,reviewer2@chromium.org --send-mail

    # Edit change description if needed.
    git cl desc

    # If change is approved, flag it to be committed.
    git cl set-commit

    # If change needs more work.
    git rebase-update
    ...
    git cl upload -t "Fixes goat teleporter destination to be Australia"

See also [open bugs](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component%3AInfra%3ESDK),
[open reviews](https://chromium-review.googlesource.com/q/status:open+project:chromium%252Ftools%252Fdepot_tools),
[forum](https://groups.google.com/a/chromium.org/forum/#!forum/infra-dev) or
[report problems](https://bugs.chromium.org/p/chromium/issues/entry?components=Infra%3ESDK).

### cpplint.py

Until 2018, our `cpplint.py` was a copy of the upstream version at
https://github.com/google/styleguide/tree/gh-pages/cpplint. Unfortunately, that
repository is not maintained any more.
If you want to update `cpplint.py` in `depot_tools`, just upload a patch to do
so. We will figure out a long-term strategy via issue https://crbug.com/916550.

Note that the `cpplint.py` here is also used by the [Tricium
analyzer](https://chromium.googlesource.com/infra/infra/+/HEAD/go/src/infra/tricium/functions/cpplint),
so if the cpplint.py here changes, we should also update the copy used there.