depot_tools_tutorial \- A tutorial introduction to the Chromium depot_tools git extensions\&.
.SH"DESCRIPTION"
.sp
The Chromium \fBdepot_tools\fR(7) suite contains many git workflow\-enhancing tools which are designed to work together to enable anyone to wrangle the Chromium codebase expertly\&. This tutorial explains how to do development on Chromium using these tools\&. This will cover:
If your platform does not support manpages (or you prefer something a bit more expressive than plain text) you can find all documentation in \fIhtml\fR form in the [DEPOT_TOOLS]/man/html folder\&.
\- An excellent interactive/graphical demo on how git handles commits, branches, and shows the operations git performs on them\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
\m[blue]\fBPro Git book\fR\m[]\&\s-2\u[4]\d\s+2
\-\(lqThe\(rq book for learning git from basics to advanced concepts\&. A bit dry, but very through\&.
.RE
.sp
If you\(cqve tried these out and are still having some trouble getting started, there are \fImany\fR other resources online which should help\&. If you\(cqre \fIreally\fR\fB\fIreally\fR\fR stuck, then chat up one of the Chromium infrastructure team members for some pointers\&.
.PP
Litmus Test
.RS4
If you know what
git add,
git status,
git commit
do and you know
\fIessentially\fR
what
git rebase
does, then you should know enough to follow along\&.
Add \fIdepot_tools\fR to the \fIend\fR of your PATH (you will probably want to put this in your ~/\&.bashrc or ~/\&.zshrc)\&. Assuming you cloned \fIdepot_tools\fR to /path/to/depot_tools:
If you have never used git before, you\(cqll need to set some global git configurations; substitute your name and email address in the following commands:
This will pull all dependencies of the Chromium src checkout\&. You will need to run this any time you update the main src checkout, including when you switch branches\&.
This will create and checkout a new branch named branch_name which will track the default upstream branch (origin/master)\&. See \fBgit-new-branch\fR(1) for more features\&.
This will take the diff of your branch against its upstream branch (in that case origin/master), and will post it to the \m[blue]\fBChromium code review site\fR\m[]\&\s-2\u[5]\d\s+2\&.
Inevitably, you\(cqll want to pull in changes from the main Chromium repo\&. This is pretty easy with \fIdepot_tools\fR:
.sp
.ifn\{\
.RS4
.\}
.nf
\fB$ git rebase\-update\fR
.fi
.ifn\{\
.RE
.\}
.sp
.sp
This command will update all of your CLs to contain the latest code from their upstreams\&. It will also automatically clean up CLs which have been committed and a couple other nice things\&. See \fBgit-rebase-update\fR(1) for the full scoop\&.
.sp
One thing to look out for are \fImerge conflicts\fR\&. These happen for exactly the same as they do with SVN, but the experience is a little more controllable with git\&. git rebase\-update will try to rebase all your branches for you, but if it encounters a merge conflict in one, it will halt and leave you in a rebase conflict state (see \fBgit-rebase\fR(1))\&. Resolving git rebase merge conflicts is beyond the scope of this tutorial, but there are many good sources online (see the Prerequisites for some)\&.
.sp
Sometimes you\(cqre pretty certain that you\(cqve committed a certain branch, but git rebase\-update isn\(cqt able to tell that for sure\&. This is usually because your branch doesn\(cqt rebase cleanly\&. You could just delete the branch with git branch \-D <branch>, but you\(cqd like to double check the diff of your branch against its upstream before deleting it\&. If this is the case you can abort the rebase started by git rebase\-update, and then run \fBgit-squash-branch\fR(1) to flatten your branch into a single commit\&. When you run git rebase\-update again, you\(cqll get a (hopefully) much smaller / saner diff\&. If it turns out you were wrong about your branch being fully committed, you can use \fBgit-reflog\fR(1) to reset your branch back to where it was before\&. If the diff looks inconsequential, you can use git rebase \-\-skip to ignore it, and then git rebase\-update will clean it up for you\&.
.sp
Once you\(cqre done resolving all of the merge conflict, just run git rebase\-update, and it will pick up where it left off\&. Once the command has finished updating all of your branches, it will return you back to the branch you started on\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBNote\fR
.ps-1
.br
.sp
Running git rebase\-update will update all your branches, but it will not automatically run gclient sync to update your dependencies\&.
Sometimes you want to work on more than one CL at once (say, you have a CL posted for review and want to work on something else)\&. For each CL that you want to work on, just use git new\-branch <branch_name>\&.
Once you start to have more than one CL at a time, it can be easy to lose your bearings\&. Fortunately, \fIdepot_tools\fR has two tools to help you out:
This tool shows you the history of all of your branches in a pseudo\-graphical format\&. In particular, it will show you which commits all of your branches are on, which commit you currently have checked out, and more\&. Check out the doc for the full details\&.
This tool just shows you which branches you have in your repo, and their upstream relationship to each other (as well as which branch you have checked out at the moment)\&.
Additionally, sometimes you need to switch between branches, but you\(cqve got work in progress\&. You could use \fBgit-stash\fR(1), but that can be tricky to manage because you need to remember which branches you stashed what changes on\&. Helpfully \fIdepot_tools\fR includes two tools which can greatly assist in case:
.sp
\fBgit-freeze\fR(1) allows you to put the current branch in \*(Aqsuspended animation\*(Aq by committing your changes to a specially\-named commit on the top of your current branch\&. When you come back to your branch later, you can just run \fBgit-thaw\fR(1) to get your work\-in\-progress changes back to what they were\&.
.sp
Another useful tool is \fBgit-rename-branch\fR(1)\&. Unlike git branch \-m <old> <new>, this tool will correctly preserve the upstream relationships of your branch compared to its downstreams\&.
.sp
Finally, take a look at \fBgit-upstream-diff\fR(1)\&. This will show you the combined diff for all the commits on your branch against the upstream tracking branch\&. This is \fIexactly\fR what git cl upload will push up to code review\&. Additionally, consider trying the \-\-wordwise argument to get a colorized per\-word diff (instead of a per\-line diff)\&.
.SH"MANAGING DEPENDENT CLS"
.sp
Now that you know how to manage \fIindependent\fR CLs, we\(cqll see how to manage \fIdependent\fR CLs\&. Dependent CLs are useful when your second (or third or fourth or \&...) CL depends on the changes in one of your other CLs (such as: CL 2 won\(cqt compile without CL 1, but you want to submit them as two separate reviews)\&.
.sp
Like all of the other CLs we\(cqve created, we use \fBgit-new-branch\fR(1), but this time with an extra argument\&. First, git checkout the branch you want to base the new one on (i\&.e\&. CL 1), and then run:
This will make a new branch which tracks the \fIcurrent\fR branch as its upstream (as opposed to \fIorigin/master\fR)\&. All changes you commit to this branch will be in addition to the previous branch, but when you git cl upload, you will only upload the diff for the dependent (child) branch\&. You may have as many branches nested in this fashion as you like\&.
.sp
\fBgit-map\fR(1) and \fBgit-map-branches\fR(1) are particularly helpful when you have dependent branches\&. In addition, there are two helper commands which let you traverse your working copy up and down this tree of branches: \fBgit-nav-upstream\fR(1) and \fBgit-nav-downstream\fR(1)\&.
.sp
Sometimes when dealing with dependent CLs, it turns out that you accidentally based a branch on the wrong upstream, but since then you\(cqve committed changes to it, or even based \fIanother\fR branch off of that one\&. Or you discover that you have two independent CLs that would actually be much better off as dependent CLs\&. In instances like these, you can check out the offending branch and use \fBgit-reparent-branch\fR(1) to move it to track a different parent\&. Note that this can also be used to move a branch from tracking origin/master to lkgr or vice versa\&.
no changes added to commit (use "git add" and/or "git commit \-a")
.fi
.ifn\{\
.RE
.\}
.sp
Someone on the code review pointed out that our typo\-fix has a typo :( We\*(Aqre still working on \*(Aqchap2\*(Aq but we really want to land \*(Aqfix_typo\*(Aq, so let\*(Aqs switch over and fix it\&.
.sp
.ifn\{\
.RS4
.\}
.nf
\fB$ git freeze\fR
\fB$ git checkout fix_typo\fR
Switched to branch \*(Aqfix_typo\*(Aq
Your branch is ahead of \*(Aqorigin/master\*(Aq by 1 commit\&.
(use "git push" to publish your local commits)
\fB$ echo \-e \*(Aq/Kuun\ens/Kuun/Kun\enwq\*(Aq | ed build/whitespace_file\&.txt\fR
While that runs through the CQ, let\*(Aqs get started on chapter 3\&. Since we know that chapter 3 depends on chapter 2, we\*(Aqll track the current chapter2 branch\&.
So there you have the basic flow\&. Note that you don\(cqt \fIhave\fR to do chromium development using these tools\&. Any git workflow is compatible, as long as git cl upload is able to upload good patches\&.
.SH"CONCLUSION"
.sp
Hopefully that gives you a good starting overview on Chromium development using \fIdepot_tools\fR\&. If you have questions which weren\(cqt answered by this tutorial or the man pages for the tools (see the index of all tools here: \fBdepot_tools\fR(7)), please feel free to ask\&.
.SH"GLOSSARY"
.PP
CL
.RS4
A
\fIchange\-list\fR\&. This is a diff which you would like to commit to the codebase\&.
.RE
.PP
DEPS
.RS4
A file in the chromium checkout which
gclient sync
uses to determine what dependencies to pull in\&. This file also contains
Part of the chromium \fBdepot_tools\fR(7) suite\&. These tools are meant to assist with the development of chromium and related projects\&. Download the tools from \m[blue]\fBhere\fR\m[]\&\s-2\u[7]\d\s+2\&.
