| OLD | NEW |
|---|
| (Empty) |
| 1 depot_tools_tutorial(7) | |
| 2 ======================= | |
| 3 | |
| 4 NAME | |
| 5 ---- | |
| 6 depot_tools_tutorial - A tutorial introduction to the Chromium depot_tools git | |
| 7 extensions. | |
| 8 | |
| 9 DESCRIPTION | |
| 10 ----------- | |
| 11 | |
| 12 The Chromium linkgit:depot_tools[7] suite contains many git workflow-enhancing | |
| 13 tools which are designed to work together to enable anyone to wrangle the | |
| 14 Chromium codebase expertly. This tutorial explains how to do development on | |
| 15 Chromium using these tools. This will cover: | |
| 16 | |
| 17 * <<_setting_up,Setting up>> | |
| 18 * <<_getting_the_code,Getting the code>> | |
| 19 * <<_tl_dr,TL;DR>> | |
| 20 * <<_creating_uploading_a_cl,Creating / Uploading a CL>> | |
| 21 * <<_updating_the_code,Updating the code>> | |
| 22 * <<_managing_multiple_cls,Managing multiple CLs>> | |
| 23 * <<_managing_dependent_cls,Managing dependent CLs>> | |
| 24 * <<_example_walkthrough,Example Walkthrough>> | |
| 25 | |
| 26 Please refer to the manpages (or `--help` output) for details about any of the | |
| 27 commands mentioned in this tutorial. | |
| 28 | |
| 29 [NOTE] | |
| 30 If your platform does not support manpages (or you prefer something a bit more | |
| 31 expressive than plain text) you can find all documentation in 'html' form in the | |
| 32 `[DEPOT_TOOLS]/docs/html` folder. | |
| 33 | |
| 34 PREREQUISITES | |
| 35 ~~~~~~~~~~~~~ | |
| 36 This tutorial assumes basic familiarity with git terminology and concepts. If yo
u | |
| 37 need to brush up on these, the following are very good resources: | |
| 38 | |
| 39 * link:http://think-like-a-git.net/[Think like (a) Git] - A lighthearted | |
| 40 overview of git. If you're sorta-familiar with git, but not 'comfortable' with | |
| 41 it, then give this a look. | |
| 42 * link:http://gitimmersion.com/[Git Immersion Tutorial] - An in-depth git | |
| 43 tutorial. | |
| 44 * link:http://pcottle.github.io/learnGitBranching[pcottle's Visual Git | |
| 45 Branching] - An excellent interactive/graphical demo on how git handles | |
| 46 commits, branches, and shows the operations git performs on them. | |
| 47 * link:http://git-scm.com/book[Pro Git book] - ``The'' book for learning git | |
| 48 from basics to advanced concepts. A bit dry, but very through. | |
| 49 | |
| 50 If you've tried these out and are still having some trouble getting started, | |
| 51 there are 'many' other resources online which should help. If you're 'really' | |
| 52 **'really'** stuck, then chat up one of the Chromium infrastructure team | |
| 53 members for some pointers. | |
| 54 | |
| 55 Litmus Test:: | |
| 56 If you know what `git add`, `git status`, `git commit` do and you know | |
| 57 'essentially' what `git rebase` does, then you should know enough to follow | |
| 58 along. | |
| 59 | |
| 60 SETTING UP | |
| 61 ---------- | |
| 62 | |
| 63 GET DEPOT TOOLS | |
| 64 ~~~~~~~~~~~~~~~ | |
| 65 | |
| 66 ifdef::backend-xhtml11[] | |
| 67 LINUX / MAC | |
| 68 ^^^^^^^^^^^ | |
| 69 endif::backend-xhtml11[] | |
| 70 Clone the 'depot_tools' repository: | |
| 71 | |
| 72 [subs="quotes"] | |
| 73 ---- | |
| 74 [white]**$ git clone https://chromium.googlesource.com/chromium/tools/depot_tool
s** | |
| 75 ---- | |
| 76 | |
| 77 Add 'depot_tools' to the 'end' of your PATH and MANPATH (you will probably want | |
| 78 to put this in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned | |
| 79 'depot_tools' to `/path/to/depot_tools`: | |
| 80 | |
| 81 [postsubs="quotes"] | |
| 82 ---- | |
| 83 [white]**$ export PATH=$PATH:/path/to/depot_tools** | |
| 84 [white]**$ export MANPATH=$MANPATH:/path/to/depot_tools/docs** <1> | |
| 85 ---- | |
| 86 <1> Observe that this path is +depot_tools/+**+docs+**. | |
| 87 | |
| 88 // No need to show the Windows stuff on the manpage output. | |
| 89 ifdef::backend-xhtml11[] | |
| 90 WINDOWS | |
| 91 ^^^^^^^ | |
| 92 Download the 'depot_tools' | |
| 93 link:https://src.chromium.org/svn/trunk/tools/depot_tools.zip[bundle] and | |
| 94 extract it somewhere. | |
| 95 | |
| 96 [WARNING] | |
| 97 *DO NOT* use drag-n-drop or copy-n-paste extract from Explorer, this will not | |
| 98 extract the hidden ``.git'' folder which is necessary for 'depot_tools' to | |
| 99 autoupdate itself. You can use ``Extract all...'' from the context menu though. | |
| 100 | |
| 101 Add 'depot_tools' to the 'end' of your PATH. Assuming you unzipped the | |
| 102 bundle to `C:\workspace\depot_tools`: | |
| 103 | |
| 104 With Administrator access: :: | |
| 105 *Control Panel -> System and Security -> System -> Advanced system settings* | |
| 106 + | |
| 107 Modify the PATH system variable to include `C:\workspace\depot_tools`. | |
| 108 | |
| 109 Without Administrator access: :: | |
| 110 *Control Panel -> User Accounts -> User Accounts -> Change my environment vari
ables* | |
| 111 + | |
| 112 Add a PATH user variable: `%PATH%;C:\workspace\depot_tools`. | |
| 113 | |
| 114 From a `cmd.exe` shell, run the command `gclient` (without arguments). On first | |
| 115 run, gclient will install all the Windows-specific bits needed to work with the | |
| 116 code, including msysgit and python. | |
| 117 | |
| 118 [NOTE] | |
| 119 ===== | |
| 120 * If you run gclient from a non-cmd shell (e.g., cygwin, PowerShell), it | |
| 121 may appear to run properly, but msysgit, python, and other tools may not get | |
| 122 installed correctly. | |
| 123 * If you see strange errors with the file system on the first run of gclient, | |
| 124 you may want to link:http://tortoisesvn.tigris.org/faq.html#cantmove2[disable | |
| 125 Windows Indexing]. | |
| 126 * If you are running Windows XP and see errors like ``The system cannot execute | |
| 127 the specified program'', try installing the | |
| 128 link:http://code.google.com/p/chromium/issues/detail?id=75886[``Microsoft | |
| 129 Visual C++ 2008 Redistributable Package'']. | |
| 130 ===== | |
| 131 endif::backend-xhtml11[] | |
| 132 | |
| 133 BOOTSTRAPPING CONFIGURATION | |
| 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 135 If you have never used git before, you’ll need to set some global git | |
| 136 configurations; substitute your name and email address in the following | |
| 137 commands: | |
| 138 | |
| 139 [subs="quotes,attributes"] | |
| 140 ---- | |
| 141 [white]**$ git config --global user.name ``John Doe''** | |
| 142 [white]**$ git config --global user.email ``jdoe@email.com''** | |
| 143 [white]**$ git config --global core.autocrlf false** | |
| 144 [white]**$ git config --global core.filemode false** | |
| 145 [white]**$** # and for fun! | |
| 146 [white]**$ git config --global color.ui true** | |
| 147 ---- | |
| 148 | |
| 149 TL;DR | |
| 150 ----- | |
| 151 [postsubs="quotes"] | |
| 152 ---- | |
| 153 [white]**$** # get the code | |
| 154 [white]**$** # In an empty directory: | |
| 155 [white]**$ fetch {chromium,blink,...}** | |
| 156 | |
| 157 [white]**$** # Update third_party repos and run pre-compile hooks | |
| 158 [white]**$ gclient sync** | |
| 159 | |
| 160 [white]**$** # Make a new change and upload it for review | |
| 161 [white]**$ git new-branch branchname** | |
| 162 [white]**$** # repeat: [edit, git add, git commit] | |
| 163 [white]**$ git cl upload** | |
| 164 | |
| 165 [white]**$** # After change is reviewed, commit with the CQ | |
| 166 [white]**$ git cl set_commit** | |
| 167 [white]**$** # Note that the committed hash which lands will /not/ match the | |
| 168 [white]**$** # commit hashes of your local branch. | |
| 169 ---- | |
| 170 | |
| 171 | |
| 172 GETTING THE CODE | |
| 173 ---------------- | |
| 174 Pick an empty directory and run one of the following: | |
| 175 | |
| 176 [subs="quotes"] | |
| 177 ---- | |
| 178 [white]**$ fetch chromium** # Basic checkout for desktop Chromium | |
| 179 [white]**$ fetch blink** # Chromium code with Blink checked out to tip-of-tr
ee | |
| 180 [white]**$ fetch android** # Chromium checkout for Android platform | |
| 181 [white]**$ fetch ios** # Chromium checkout for iOS platform | |
| 182 ---- | |
| 183 | |
| 184 When the `fetch` tool completes you should have the following in your working | |
| 185 directory: | |
| 186 | |
| 187 [subs="quotes"] | |
| 188 ---- | |
| 189 [white]**.gclient** # A configuration file for you source checkout | |
| 190 [white]**src/** # Top-level Chromium source checkout. | |
| 191 ---- | |
| 192 | |
| 193 If you are on linux, then you'll need to run: | |
| 194 | |
| 195 [subs="specialcharacters,quotes"] | |
| 196 ---- | |
| 197 [white]**$ cd src && ./build/install-build-deps.sh** | |
| 198 ---- | |
| 199 | |
| 200 And finally: | |
| 201 | |
| 202 [postsubs="quotes"] | |
| 203 ---- | |
| 204 [white]**$ gclient sync** | |
| 205 ---- | |
| 206 | |
| 207 This will pull all dependencies of the Chromium src checkout. You will need | |
| 208 to run this any time you update the main src checkout. | |
| 209 | |
| 210 | |
| 211 CREATING / UPLOADING A CL | |
| 212 ------------------------- | |
| 213 NOTE: The remainder of the tutorial assumes that your current working directory | |
| 214 is the `src/` folder mentioned in <<_getting_the_code,Getting the code>>. | |
| 215 | |
| 216 Each CL corresponds exactly with a single branch in git. Any time you want to | |
| 217 begin a new CL, just: | |
| 218 | |
| 219 [subs="specialcharacters,quotes"] | |
| 220 ---- | |
| 221 [white]**$ git new-branch <branch_name>** | |
| 222 ---- | |
| 223 | |
| 224 This will create and checkout a new branch named `branch_name` which will track | |
| 225 the default upstream (which is `origin/master`). See linkgit:git-new-branch[1] | |
| 226 for more features, such as the ability to track 'LKGR'. | |
| 227 | |
| 228 Commit as many changes as you like to this branch. When you want to upload it | |
| 229 for review, run: | |
| 230 | |
| 231 [subs="quotes"] | |
| 232 ---- | |
| 233 [white]**$ git cl upload** | |
| 234 ---- | |
| 235 | |
| 236 This will take the diff of your branch against its upstream (`origin/master`), | |
| 237 and will post it to the link:https://codereview.chromium.org[Chromium code | |
| 238 review site]. | |
| 239 | |
| 240 | |
| 241 UPDATING THE CODE | |
| 242 ----------------- | |
| 243 Inevitably, you'll want to pull in changes from the main Chromium repo. This is | |
| 244 pretty easy with 'depot_tools': | |
| 245 | |
| 246 [subs="quotes"] | |
| 247 ---- | |
| 248 [white]**$ git rebase-update** | |
| 249 ---- | |
| 250 | |
| 251 This command will update all of your CLs to contain the latest code from their | |
| 252 upstreams. It will also automatically clean up CLs which have been committed and | |
| 253 a couple other nice things. See linkgit:git-rebase-update[1] for the full | |
| 254 scoop. | |
| 255 | |
| 256 One thing to look out for are 'merge conflicts'. These happen for exactly the | |
| 257 same as they do with SVN, but the experience is a little more controllable with | |
| 258 git. `git rebase-update` will try to rebase all your branches for you, but if it | |
| 259 encounters a merge conflict in one, it will halt and leave you in a rebase | |
| 260 conflict state (see linkgit:git-rebase[1]). Resolving `git rebase` merge | |
| 261 conflicts is beyond the scope of this tutorial, but there are many good sources | |
| 262 online (see the <<_prerequisites,Prerequisites>> for some). | |
| 263 | |
| 264 Sometimes you're pretty certain that you've committed a certain branch, but `git | |
| 265 rebase-update` isn't able to tell that for sure. This is usually because your | |
| 266 branch doesn't rebase cleanly. You could just delete the branch with `git branch | |
| 267 -D <branch>`, but you'd like to double check the diff of your branch against its | |
| 268 upstream before deleting it. If this is the case you can abort the rebase | |
| 269 started by `git rebase-update`, and then run linkgit:git-squash-branch[1] to | |
| 270 flatten your branch into a single commit. When you run `git rebase-update` | |
| 271 again, you'll get a (hopefully) much smaller / saner diff. If it turns out you | |
| 272 were wrong about your branch being fully committed, you can use | |
| 273 linkgit:git-reflog[1] to reset your branch back to where it was before. If the | |
| 274 diff looks inconsequential, you can use `git rebase --skip` to ignore it, and | |
| 275 then `git rebase-update` will clean it up for you. | |
| 276 | |
| 277 Once you're done resolving all of the merge conflict, just run `git | |
| 278 rebase-update`, and it will pick up where it left off. Once the command has | |
| 279 finished updating all of your branches, it will return you back to the branch | |
| 280 you started on. | |
| 281 | |
| 282 [NOTE] | |
| 283 Running `git rebase-update` will update all your branches, but it will not | |
| 284 automatically run `gclient sync` to update your dependencies. | |
| 285 | |
| 286 | |
| 287 MANAGING MULTIPLE CLS | |
| 288 --------------------- | |
| 289 Sometimes you want to work on more than one CL at once (say, you have a CL | |
| 290 posted for review and want to work on something else). For each CL that you | |
| 291 want to work on, just use `git new-branch <branchname>`. | |
| 292 | |
| 293 Once you start to have more than one CL at a time, it can be easy to lose your | |
| 294 bearings. Fortunately, 'depot_tools' has two tools to help you out: | |
| 295 | |
| 296 [subs="specialcharacters,quotes,attributes"] | |
| 297 ---- | |
| 298 [white]**$ git map** | |
| 299 [white blue-background]##*##{zwsp}[blue-background red]** 7dcfe47 ** [gree
n]##(##{zwsp}[aqua]**frozen_changes**{zwsp}[green]##)## [yellow]##2014-03-12## \
~ FREEZE.unindexed | |
| 300 * [red]**4b0c180** [yellow]##2014-03-12## \~ modfile | |
| 301 * [red]**59a7cca** [yellow]##2014-03-12## \~ a deleted file | |
| 302 * [red]**6bec695** [green]##(##{zwsp}[red]##origin/master##{zwsp}[green]#
#)## [yellow]##2014-03-11## \~ Add neat feature [white]**<(frozen_changes)** | |
| 303 * [red]**d15a38a** [yellow]##2014-03-11## \~ Epic README update | |
| 304 * [red]**d559894** [green]##(##{zwsp}[lime]**master**{zwsp}[green]##)## [
yellow]##2014-03-11## \~ Important upstream change | |
| 305 [red]##|## * [red]**9c311fd** [green]##(##{zwsp}[lime]**cool_feature**{zwsp
}[green]##)## [yellow]##2014-03-11## \~ Respond to CL comments | |
| 306 [red]##|## [green]##|## * [red]**2a1eeb2** [green]##(##{zwsp}[lime]**subfeatu
re**{zwsp}[green]##)## [yellow]##2014-03-11## \~ integrate with CoolService | |
| 307 [red]##|## [green]##|## * [red]**d777af6** [yellow]##2014-03-11## \~ slick co
mmenting action | |
| 308 [red]##|## [green]##|/## | |
| 309 [red]##|## * [red]**265803a** [yellow]##2014-03-11## \~ another improvement
[white]**<(subfeature)** | |
| 310 [red]##|## * [red]**6d831ac** [green]##(##{zwsp}[fuchsia]**spleen_tag**{zws
p}[green]##)## [yellow]##2014-03-11## \~ Refactor spleen | |
| 311 [red]##|## * [red]**82e74ab** [yellow]##2014-03-11## \~ Add widget | |
| 312 [red]##|/## | |
| 313 * [red]**d08c5b3** [green]##(##{zwsp}[lime]**bogus_noparent**{zwsp}[green
]##)## [yellow]##2014-03-11## ~ Wonderful beginnings [white]**<(cool_feature)
** | |
| 314 ---- | |
| 315 Note that this example repo is in dire need of a linkgit:git-rebase-update[1]! | |
| 316 | |
| 317 [subs="quotes"] | |
| 318 ---- | |
| 319 [white]**$ git map-branches** | |
| 320 [red]#origin/master# | |
| 321 [green]#cool_feature# | |
| 322 [green]#subfeature# | |
| 323 [aqua]#frozen_changes *# | |
| 324 [green]#master# | |
| 325 ---- | |
| 326 | |
| 327 linkgit:git-map[1]:: | |
| 328 This tool shows you the history of all of your branches in a pseudo-graphical | |
| 329 format. In particular, it will show you which commits all of your branches | |
| 330 are on, which commit you currently have checked out, and more. Check out the | |
| 331 doc for the full details. | |
| 332 | |
| 333 linkgit:git-map-branches[1]:: | |
| 334 This tool just shows you which branches you have in your repo, and thier | |
| 335 upstream relationship to each other (as well as which branch you have checked | |
| 336 out at the moment). | |
| 337 | |
| 338 Additionally, sometimes you need to switch between branches, but you've got work | |
| 339 in progress. You could use linkgit:git-stash[1], but that can be tricky to | |
| 340 manage because you need to remember which branches you stashed what changes on. | |
| 341 Helpfully 'depot_tools' includes two tools which can greatly assist in case: | |
| 342 | |
| 343 linkgit:git-freeze[1] allows you to put the current branch in \'suspended | |
| 344 animation' by committing your changes to a specially-named commit on the top of | |
| 345 your current branch. When you come back to your branch later, you can just run | |
| 346 linkgit:git-thaw[1] to get your work-in-progress changes back to what they were. | |
| 347 | |
| 348 Another useful tool is linkgit:git-rename-branch[1]. Unlike `git branch -m <old> | |
| 349 <new>`, this tool will correctly preserve the upstream relationships of your | |
| 350 branch compared to its downstreams. | |
| 351 | |
| 352 Finally, take a look at linkgit:git-upstream-diff[1]. This will show you the | |
| 353 combined diff for all the commits on your branch against the upstream tracking | |
| 354 branch. This is 'exactly' what `git cl upload` will push up to code review. | |
| 355 Additionally, consider trying the `--wordwise` argument to get a colorized | |
| 356 per-word diff (instead of a per-line diff). | |
| 357 | |
| 358 MANAGING DEPENDENT CLS | |
| 359 ---------------------- | |
| 360 Now that you know how to manage 'independent' CLs, we'll see how to manage | |
| 361 'dependent' CLs. Dependent CLs are useful when your second (or third or fourth | |
| 362 or ...) CL depends on the changes in one of your other CLs (such as: CL 2 won't | |
| 363 compile without CL 1, but you want to submit them as two separate reviews). | |
| 364 | |
| 365 Like all of the other CLs we've created, we use linkgit:git-new-branch[1], but | |
| 366 this time with an extra argument. First, `git checkout` the branch | |
| 367 you want to base the new one on (i.e. CL 1), and then run: | |
| 368 | |
| 369 [subs="specialcharacters,quotes"] | |
| 370 ---- | |
| 371 [white]**$ git new-branch --upstream_current <branch_name>** | |
| 372 ---- | |
| 373 | |
| 374 This will make a new branch which tracks the 'current' branch as its upstream | |
| 375 (as opposed to 'origin/master'). All changes you commit to this branch will be | |
| 376 in addition to the previous branch, but when you `git cl upload`, you will only | |
| 377 upload the diff for the dependent (child) branch. You may have as many branches | |
| 378 nested in this fashion as you like. | |
| 379 | |
| 380 linkgit:git-map[1] and linkgit:git-map-branches[1] are particularly helpful when | |
| 381 you have dependent branches. In addition, there are two helper commands which | |
| 382 let you traverse your working copy up and down this tree of branches: | |
| 383 linkgit:git-nav-upstream[1] and linkgit:git-nav-downstream[1]. | |
| 384 | |
| 385 Sometimes when dealing with dependent CLs, it turns out that you accidentally | |
| 386 based a branch on the wrong upstream, but since then you've committed changes to | |
| 387 it, or even based 'another' branch off of that one. Or you discover that you | |
| 388 have two independent CLs that would actually be much better off as dependent | |
| 389 CLs. In instances like these, you can check out the offending branch and use | |
| 390 linkgit:git-reparent-branch[1] to move it to track a different parent. Note that | |
| 391 this can also be used to move a branch from tracking `origin/master` to `lkgr` | |
| 392 or vice versa. | |
| 393 | |
| 394 | |
| 395 EXAMPLE WALKTHROUGH | |
| 396 ------------------- | |
| 397 This section will demo what a typical workflow looks like when writing, | |
| 398 updating, and committing multiple CLs. | |
| 399 | |
| 400 demo:walkthrough[] | |
| 401 | |
| 402 So there you have the basic flow. Note that you don't 'have' to do chromium | |
| 403 development using these tools. Any git workflow is compatible, as long as | |
| 404 `git cl upload` is able to upload good patches. | |
| 405 | |
| 406 | |
| 407 CONCLUSION | |
| 408 ---------- | |
| 409 Hopefully that gives you a good starting overview on Chromium development using | |
| 410 'depot_tools'. If you have questions which weren't answered by this tutorial or | |
| 411 the man pages for the tools (see the index of all tools here: | |
| 412 linkgit:depot_tools[7]), please feel free to ask. | |
| 413 | |
| 414 | |
| 415 GLOSSARY | |
| 416 -------- | |
| 417 | |
| 418 CL:: | |
| 419 A 'change-list'. This is a diff which you would like to commit to the | |
| 420 codebase. | |
| 421 | |
| 422 DEPS:: | |
| 423 A file in the chromium checkout which `gclient sync` uses to determine what | |
| 424 dependencies to pull in. This file also contains 'hooks'. | |
| 425 | |
| 426 LKGR:: | |
| 427 Last Known Good Revision. This is a linkgit:git-tag[1] which tracks the last | |
| 428 version of `origin/master` which has passed the full set of testing on the | |
| 429 link:http://build.chromium.org[main Chromium waterfall]. | |
| 430 | |
| 431 include::_footer.txt[] | |
| 432 | |
| 433 // vim: ft=asciidoc: | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 259863004:
Move docs folder to man. (Closed)
Base URL: https://chromium.googlesource.com/chromium/tools/depot_tools.git@master