[[PageOutline]] = Tips and Tricks for using Git with WebKit = See also: * [http://gitorious.org/webkit/pages/UsingMirrorWithGitSvn How to setup an always up-to-date git-svn mirror of QtWebKit] * [wiki:"Moving to Git" Proposal for moving WebKit development to Git] == Install == You can download Git binaries directly from the [http://git-scm.com/download official site!] Or: === Mac users === * Update your Git install: http://code.google.com/p/git-osx-installer/ * Update your SVN install (for `git-svn` bindings): http://www.open.collab.net/downloads/community/ === [http://www.debian.org Debian] users === {{{ sudo apt-get install git-core }}} === Windows users === Install git for Cygwin using the Cygwin installer. Cygwin's git is functionally complete but has performance issues. For better performance, you can use [http://code.google.com/p/msysgit msysgit] (note that you still need Cygwin's git to work with some of WebKit's scripts): * [http://code.google.com/p/msysgit/downloads/list Download the latest msysgit full installer]. You want the file with the label "Full installer for official Git", like Git-N.N.N.N-*.exe, not the mysysGit-* files. * When installing msysgit, tell the installer to: * Use Git Bash only * Checkout as-is, commit as-is * Choose `Start > Programs > Git > Git Bash` * Create a file named .bashrc in your Git Bash home directory that contains the following: {{{ cd /c/cygwin/home/ export HOME=$(pwd) }}} * Relaunch Git Bash. The shell should be using your Cygwin home directory as its home directory. Whenever you want to run a git command manually, use Git Bash. You can also run `prepare-ChangeLog` from Git Bash. == Checkout == To checkout WebKit using git: {{{ git clone git://git.webkit.org/WebKit.git WebKit }}} If you want to be able to commit changes to the Subversion repository, or just want to check out branches that aren't contained in WebKit.git, you will need track the Subversion repository. To do that, inform `git-svn` of the location of the WebKit SVN repository, and update the branch that `git-svn` uses to track the Subversion repository so that it will re-use the history that we've already cloned from `git.webkit.org` rather than trying to fetch it all from Subversion: {{{ cd WebKit git svn init -T trunk http://svn.webkit.org/repository/webkit git update-ref refs/remotes/trunk origin/master }}} This will add the following section to your `.git/config`: {{{ [svn-remote "svn"] url = http://svn.webkit.org/repository/webkit fetch = trunk:refs/remotes/trunk }}} You can then run the following command to have `git-svn` rebuild its metadata from your local repository, and to pull any recent commits from the WebKit SVN repository. {{{ git svn fetch }}} == Updating == If you're not tracking the Subversion repository the following command will fetch new commits from `git.webkit.org`: {{{ git fetch }}} You can then merge or rebase your local branches with `origin/master` to pick up the new commits. If you are tracking the Subversion repository, this command will fetch information about new commits from Subversion, reset your local branch to match Subversion exactly, and then apply your local commits on top: {{{ git svn rebase }}} If you'd like to fetch new commits from the Subversion repository without moving your local branch, you can use the following command: {{{ git svn fetch }}} If you don't fetch new revisions from Subversion very often and find fetching them one by one too slow, you can modify the svn section in your .git/config file to point directly to the '''refs/remotes/origin/master''' rather then '''refs/remotes/trunk''' which is how it is set up by default. In this case 'git svn fetch' will be way faster if done after "git fetch" or "git pull", since it'll realize it already has all the revisions locally. Edit your svn entry to look like this: {{{ [svn-remote "svn"] url = http://svn.webkit.org/repository/webkit fetch = trunk:refs/remotes/origin/master }}} and then re-build the svn index by doing 'git svn fetch' once. == Commit manually through git-svn directly == If you have been granted commit access to WebKit's SVN repository it is possible to work entirely with git and to commit through `git-svn`, however using webkit-patch land (see next section) is encouraged since it deals with changelogs, commit logs and bugzilla for you. After you have configured your working copy to track the Subversion repository you can: 1. Create a `tot_staging` branch or whatever name you choose 2. Apply a patch, cherry-pick a commit, or even merge a branch if it has been reviewed 3. Run `git svn rebase` and fix any ChangeLog conflicts that might result 4. Ensure the git log entry for your local commit contains an accurate copy of all the Changelog entries for your commit. 5. And then when everything is ready-- {{{ git svn dcommit }}} Since "git svn dcommit" creates a revision in the subversion repository for each local commit, you may need to squash (i.e. combine) commits to ensure that your commit to the WebKit repository will create just one revision. You can do this, for example, by using-- {{{ git rebase -i HEAD~n }}} where n is the number of commits you want to see in the interactive editor. You can use `git commit -a --amend` for example to amend an existing local commit and avoid creating additional commits that you may need to squash later on. As you may have guessed from step 4 above, "git svn dcommit" does not use the "commit-log-editor" setting to create a commit message to store in the remote Subversion repository. Instead it simply uses the commit message already associated to the local commit, so you need to ensure that it is an accurate copy of all your commit's Changelog entries. This is somewhat different from committing with Subversion, where "svn commit" does intervene with "commit-log-editor" to create a commit message for the remote repository. == WebKit Script support for Git == * Important git config settings for preparing ChangeLogs. {{{ git config --global user.name "Foo Bar" git config --global user.email "foo@webkit.org" }}} webkit-patch and check-webkit-style commands all work with git. By default all webkit-patch commands will treat all changes in your branch as a single commit (i.e. all local commits + working copy changes get uploaded/committed as a single commit). To operate on a specific commit, use --git-commit=commitish or "-g commitish". commitish can be a single commit (e.g. HEAD~1), a commit range (e.g. HEAD~3..HEAD~1, operates on HEAD~2 and HEAD~1 as a single commit) or the working copy (i.e., HEAD..). WARNING: webkit-patch land will hang the first time you call it. It's (silently) blocked on prompting for your svn credentials. You'll need to use "git svn dcommit" for your first commit. The various scripts in `WebKitTools/Scripts` have been made to work pretty well with Git. Here are some of the specific things you can do with them: * Telling Git to use '''resolve-ChangeLogs''' automatically as a merge-driver for ChangeLogs {{{ git config merge.changelog.driver "perl path/to/resolve-ChangeLogs --merge-driver %O %A %B" }}} * Telling the various scripts to '''append the git branch name to every build'''. This is especially useful so you don't clobber your previous branch's build when you switch branches {{{ git config core.webKitBranchBuild (true|false) //the default is off }}} * Overriding the core.webKitBranchBuild setting for a specific branch {{{ git config branch.$branchName.webKitBranchBuild (true|false) }}} '''The following are only needed if you don't use webkit-patch.''' * Using '''prepare-Changelog''' with git {{{ WebKitTools/Scripts/prepare-ChangeLog --git-commit=$committish --git-reviewer="Foo Reviewer" }}} * Using '''resolve-ChangeLog''' with git. Assuming you got a conflict merging a ChangeLog file, this tool will reapply the patch using {{{patch --fuzz=3}}} so that your change lands at the top of the ChangeLog file. If the patch was successfully applied, {{{git-add}}} is run on the ChangeLog file. Note that this tool does not change the date of the ChangeLog entry (unlike {{{svn-apply}}}). {{{ WebKitTools/Scripts/resolve-ChangeLogs path/to/ChangeLog [path/to/ChangeLog ...] }}} * Using '''commit-log-editor''' with git will automatically insert the ChangeLog entry as your commit message {{{ git config core.editor "perl path/to/commit-log-editor" }}} If you want to make sure log gets regenerated from ChangeLog entry each time you modify an already existing commit, use --regenerate-log: {{{ git config core.editor "perl path/to/commit-log-editor --regenerate-log" }}} * If you do not manually generate a ChangeLog entry and you have staged changes in your working tree, '''commit-log-editor''' will automatically generate a commit message in the WebKit ChangeLog entry format when you do 'git commit'. You can control this behaviour with the git configuration option '''webkitGenerateCommitMessage''' on a global or per-branch basis. {{{ git config core.webkitGenerateCommitMessage (true|false) //the default is true git config branch.$branchName.webkitGenerateCommitMessage (true|false) }}} == Misc. Tips and Tricks == * You can setup '''Git shell completion and branch name in your bash prompt.''' In your /contrib/completion directory you will find a 'git-completion.bash' file. The command "git --exec-path" may help you determine your path to git. Follow the instructions in that file to enable shell completion. Here is a nice bash prompt for instance {{{ PS1='\[\033[41;1;37m\]\u@\h:\[\033[40;1;33m\]\W$(__git_ps1 " (%s)")>\[\033[0m\] ' }}} * You can set up '''multiple working directories to work on more than one branch at a time.''' In your /path/to/git/source/contrib/workdir directory you will find a 'git-new-workdir' script that can create new working directories. The usage is {{{ ./git-new-workdir [] }}} * Colorize various git commands {{{ git config --global color.status auto git config --global color.diff auto git config --global color.branch auto }}} * If you're using `git-send-bugzilla` or `webkit-patch` you may also want git to remember your bugzilla credentials: {{{ git config --global bugzilla.username "name@example.com" git config --global bugzilla.password "yourpassword" }}} == Ignores == * You can setup your git repository to ignore the same files that are ignored in the tracked Subversion repository with: (this will take some time) {{{ git svn show-ignore >> .git/info/exclude }}} == Workflow == If you are not familiar with Git and wish to see a a sample workflow for making modifications, see [wiki:HackingWebInspector#NowDoYourHacking the web inspector tutorial]. == Maintaining Good Performance == `git-gc` can be used to make your git repository take up less space and increase git's performance. Some git commands will run a "lite" version of `git-gc` automatically, but you may want to run it manually from time to time. Running it is as simple as: {{{ git gc }}} It is a good idea to do an "aggressive" gc occasionally, like so (be warned that this can take multiple hours!): {{{ # The following git-config commands are only needed on Windows AFAIK git config pack.threads 1 git config pack.windowMemory 256m git gc --aggressive }}}