aiden
/
depot_tools
mirror of https://chromium.googlesource.com/chromium/tools/depot_tools
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Overhaul the README files a bit.

Browse Source 
I didn't change the content much but deleted some obviously wrong stuff. Renamed
the files to .md so they will be processed by gitiles.

This change is in no way "sufficient" but that's a start.

R=tandrii@chromium.org

Review-Url: https://codereview.chromium.org/2232303002
changes/00/373500/1
maruel 9 years ago committed by Commit bot
parent dafd4f0c9a
commit 9e198a84a9
6 changed files with 216 additions and 269 deletions
Show Stats Download Patch File Download Diff File

99
README.codereview
Unescape Escape View File

@ -1,99 +0,0 @@
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.
== Concepts and terms
A Rietveld review is for discussion of a single change or patch. You
upload a proposed change, the reviewer comments on your change, and
then you can upload a revised version of your change. Rietveld stores
the history of uploaded patches as well as the comments, and can
compute diffs in between these patches. The history of a patch is
very much like a small branch in git, but since Rietveld is
VCS-agnostic the concepts don't map perfectly. The identifier for a
single review+patches+comments in Rietveld is called an "issue".
Rietveld provides a basic uploader that understands git. This program
is used by git-cl, and is included in the git-cl repo as upload.py.
== 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 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.

82
README.gclient
Unescape Escape View File

@ -1,82 +0,0 @@
# Copyright 2008-2009, Google Inc.
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" : "svn://svnserver/component/trunk/src",
"custom_deps" : {
# To use the trunk of a component instead of what's in DEPS:
#"component": "https://svnserver/component/trunk/",
# 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" : "http://outside-server/trunk@1234",
"src/component" : "svn://svnserver/component/trunk/src@77829",
"src/relative" : "/trunk/src@77829",
}
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:" or "svn:" 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.

67
README.gclient.md
Unescape Escape View File

@ -0,0 +1,67 @@
# 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" : "svn://svnserver/component/trunk/src",
"custom_deps" : {
# To use the trunk of a component instead of what's in DEPS:
#"component": "https://svnserver/component/trunk/",
# 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:` or `svn:` 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.

52
README.git-cl
Unescape Escape View File

@ -1,52 +0,0 @@
# git-cl -- a git-command for integrating reviews on Rietveld
# Copyright (C) 2008 Evan Martin <martine@danga.com>
== Background
Rietveld, also known as http://codereview.appspot.com, is a nice tool
for code reviews. You upload a patch (and some other data) and it lets
others comment on your patch.
For more on how this all works conceptually, please see README.codereview.
The remainder of this document is the nuts and bolts of using git-cl.
== Install
Copy (symlink) it into your path somewhere, along with Rietveld
upload.py.
== Setup
Run this from your git checkout and answer some questions:
$ git cl config
== How to use it
Make a new branch. Write some code. Commit it locally. Send it for
review:
$ git cl upload
By default, it diffs against whatever branch the current branch is
tracking (see "git checkout --track"). An optional last argument is
passed to "git diff", allowing reviews against other heads.
You'll be asked some questions, and the review issue number will be
associated with your current git branch, so subsequent calls to upload
will update that review rather than making a new one.
== git-svn integration
Review looks good? Commit the code:
$ git cl dcommit
This does a git-svn dcommit, with a twist: all changes in the diff
will be squashed into a single commit, and the description of the commit
is taken directly from the Rietveld description. This command also accepts
arguments to "git diff", much like upload.
Try "git cl dcommit --help" for more options.
== Extra commands
Print some status info:
$ git cl status
Edit the issue association on the current branch:
$ git cl issue 1234
Patch in a review:
$ git cl patch <url to full patch>
Try "git cl patch --help" for more options.
vim: tw=72 :

99
README.git-cl.md
Unescape Escape View File

@ -0,0 +1,99 @@
# 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.
## Reitveld concepts and terms
A Rietveld review is for discussion of a single change or patch. You upload a
proposed change, the reviewer comments on your change, and then you can upload a
revised version of your change. Rietveld stores the history of uploaded patches
as well as the comments, and can compute diffs in between these patches. The
history of a patch is very much like a small branch in git, but since Rietveld
is VCS-agnostic the concepts don't map perfectly. The identifier for a single
review+patches+comments in Rietveld is called an `issue`.
Rietveld provides a basic uploader that understands git. This program is used by
git-cl, and is included in the git-cl repo as upload.py.
## 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 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.

86
README.md
Unescape Escape View File

@ -1,55 +1,69 @@
This package contains tools for working with Chromium development:
# depot_tools
chrome-update-create-task.bat
Creates a scheduled task to do an automatic local chromium build every day.
This package contains tools for working with Chromium development. It requires
python 2.7.
cpplint.py
A copy of our linting tool which enforces Google style. Fetched from
http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py
gcl
A tool for uploading and managing code reviews on the Chromium
project, using the Rietveld code review tool. More info at:
http://code.google.com/p/rietveld/
## Tools
gclient
A script for managing a workspace with modular dependencies that
are each checked out independently from different repositories.
More info at:
http://code.google.com/p/gclient/
The most important tools are:
It updates itself automatically when running `gclient` tool. To disable
auto update, set the environment variable DEPOT_TOOLS_UPDATE=0
- `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.
To update package manually, run .\update_depot_tools.bat on Windows,
or ./update_depot_tools on Linux or Mac.
There are a lot of git utilities included.
Note: on Windows if svn, git and python are not accessible, they will be
downloaded too.
## Updating
## Contributing
`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 `svn` (not for long), `git`,
`python`.
The "gclient" wrapper knows how to keep this repository updated to
the latest versions of these tools as found at:
https://chromium.googlesource.com/chromium/tools/depot_tools.git
## Contributing
To contribute change for review:
git new-branch <somename>
git add <yourchanges>
git commit
# Hack
git add .
git commit -a -m "Fixes goat teleporting"
# find reviewers
git cl owners
git log <yourfiles>
# upload
git cl upload -r reviewer1@chromium.org,reviewer2 --send-mail
# open https://codereview.chromium.org/ and send mail
# if change is approved, flag it to be commited
git cl set_commit
# if change needs more work
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 commited.
git cl set-commit
# If change needs more work.
git rebase-update
...
git cl upload
git cl upload -t "Fixes goat teleporter destination to be Australia"
### cpplint.py
To update cpplint.py, please submit the change upstream first at
https://github.com/google/styleguide/tree/gh-pages/cpplint then copy it down.

Write Preview
Loading…
Cancel
Save