My favorites | Sign in
Logo
Project Home
  
Downloads
  
Wiki
  
Issues
    
Search
for
Updated Nov 03 (5 days ago) by evan@chromium.org
Labels: git
UsingGit  
Using Git to work on Chromium

Some people working on Chromium prefer to use the Git version control system. This document explains how we have best found to use Git.

NOTE: If you just git clone the Chromium repo, your checkout will not work.

Getting the code

First checkout

  1. Make a new directory for working with Chromium and cd into it.
  2. Download the depot tools, which are used to fetch external dependencies of the code base.

    Here are Linux instructions; see the install info for other platforms. 

    svn co http://src.chromium.org/svn/trunk/tools/depot_tools

  3. Grab the main tree with Git: 

    git clone git://git.chromium.org/chromium.git src
    • NOTE: using this exact name of the output directory (src) is important!
    • NOTE: this is a very large download, more than 650mb. You might get a smaller download via the --depth argument to git clone.
    • NOTE: if you are within the Google corporate network, see the internal ChromeGit wiki page for some extra notes.

  4. Create a .gclient file by running gclient: 

    ./depot_tools/gclient config http://src.chromium.org/svn/trunk/src

    (If you are a committer, see below for a slight tweak on this.)

  5. Optional. Edit your .gclient file to avoid checking out the enormous set of WebKit layout tests. Find the line that has an example of excluding a component, and add beneath it: 

    "src/third_party/WebKit/LayoutTests": None,

  6. Have gclient pull Chromium's dependencies as normal svn checkouts: 

    ./depot_tools/gclient sync

    If all went well, gclient will recognize you're managing your src directory yourself, and print the following at the very beginning. 

          ________ found .git directory; skipping src

    Note that it will not skip entire src. It will still check out other files such as tools and third party files.

Advanced Tricks

  • WebKit and git. See UsingWebKitGit and http://trac.webkit.org/wiki/UsingGitWithWebKit.

  • gcl compatibility. If you plan to commit changes to trunk/deps and want to use gcl for that, you should configure .gclient with url: svn://src.chromium.org/chrome/trunk/src instead of the http url. This will make sure that the relevant chromium dependencies will be checked out in a gcl compatible way. However, you must have committer access to src.chromium.org.

Staying up to date

  1. Run git pull or whichever command is appropriate to update your checkout. The Git community book is a good resource to learn git from.
  2. Run /path/to/gclient sync if any of the DEPS files change to update dependent subdirectories.

Contributing

Configure your checkout

Since contributing code using git requires git-cl, read git-cl's README and README.codereview to learn how to use it. Since you already have depot_tools in your PATH, git-cl will "just work." Configure it with: 

git cl config http://src.chromium.org/svn/

You must add the junk to your ~/.subversion/config that's specified on http://dev.chromium.org/developers/coding-style under "Subversion properties". Else git won't set svn properties correctly and people might yell at you.

Making local changes

The first step to contributing a patch is to write it. Create a branch and make your changes: 

git checkout -q -b mywork origin
vi ...
git commit -a -v

Presubmit tests

After committing your changes locally, use git-cl to run all of the presubmit tests associated with your change. 

git cl presubmit

This runs both upload and dcommit presubmit tests. They will alert you to any problems with your change that you should address before completing or dcommitting your patch.

Code Reviews

All code changes are reviewed using http://codereview.chromium.org. Use git-cl to easily upload a branch as a proposed change.

You can associate each git branch you work on with a code review by running the following: 

git checkout mywork
git cl upload

Uploading your change will also run the upload presubmit tests on your change. To skip the presubmit tests, use the flag --bypass-hooks.

Subsequent invocations of 'upload' on the same branch will add updates to the same code review. See git cl help for more.

Trybots

git-try, part of depot_tools, will run git branches through the try bots.

If your patch depends on specific branches in Chromium and WebKit, you can run git-try with: 

git try -b BOT --webkit WEBKIT_BRANCH [CHROMIUM_BRANCH]

where WEBKIT_BRANCH and CHROMIUM_BRANCH are branches to compare with. In most cases, they will be master and trunk, respectively.

If you are running the patch on try bots, use BOT as layout_win,layout_mac,layout_linux.

Renames and Copies

Git has a strange notion of how copies and renames work; see the Git FAQ about it. If git diff -M -C shows that git knows a file was renamed, then git cl upload and git cl dcommit will include the proper metadata for reviewing and committing the rename. If not, ask evan@chromium.org about it -- this code isn't tested well so there are surely bugs.

Committing

To commit from your checkout, you must (obviously) first have commit access.

Initial Setup

Make sure you are in src/ folder when you run this command: 

git svn init --prefix=origin/ -T trunk/src svn://svn.chromium.org/chrome

(If you're a git ninja, you might notice that this sets up refs/remotes/origin to naturally point at the git server, with the twist that git-svn also uses refs/remotes/origin/trunk.)

Run git svn fetch once just to let it rebuild its revision database.

Really Committing

Should Just Work. Always use git cl dcommit. It runs git svn dcommit for you along with running the very important presubmit tests. To bypass the presubmit tests (eg. to committ on a closed tree), use the flag --bypass-hooks.

Windows

If you are using msysgit, you are asking for trouble. Using both msysgit (including TortoiseGit) and cygwin's version of git is a path to lead to repository corruption so it's safer to stick with the cygwin's version. So if you still have msysgit in your PATH, you are on your own.

Sane people will install the following cygwin packages:

  • curl (for git-cl-patch)
  • git
  • gitk (optional)
  • subversion-perl
  • python

After installation, sanity check your git-svn binaries by running "git svn info". If you see an error message like , you'll need to remap your binaries.

Be sure to turn off git's crlf munging: 

git config --global core.autocrlf false

Binaries may not work out of the box:

cygwin 1.7 (and also 1.5 on Windows 7) may throw error message like 

$ git svn info
6 [main] perl 4760 C:\cygwin\bin\perl.exe: *** fatal error 
- unable to remap <library> to same address as parent

while using git. You'll need to rebase your dlls with ash.exe and 'rebaseall'.

Troubleshooting

Sometimes (it seems to happen on Windows, but not other platforms?) git-svn will get confused about things. Symptoms include it trying to refetch commits you've already fetched, or printing "transaction out of date" errors on unrelated files.

Try this recipe: 

rm -rf .git/svn   # clobber git-svn metadata
git svn find-rev r1   # run a no-op command to rebuild metadata

Tips & Tricks

Finding Files Fast

Use git-gs located in src/depot_tools to search the source tree.

Since git keeps an index of all files it knows about, it can filter the master list of files by file extension and only grep through those files. It doesn't have to crawl your tree (and all those layout test results) to grep over source code. Performing a git gs [searchterm] from /src/ gets results in a couple seconds with a cold disk. It's often instant with a warm disk.

Note this won't search dependencies pulled by gclient.