Development with Git
This page gives tips on how to contribute to the CDK development using the Git repository.
For CDK Users
How do I make a Git checkout?
$ git clone git://github.com/cdk/cdk.git
How can I update my local checkout?
If you have done the above clone, you should be able to do the following equivalent for 'svn update':
$ git pull
How do I checkout the stable CDK 1.4.x branch?
Using the "cdk-1.4.x" branch name, we can get a copy of the source code for release 1.2.1 with:
$ git checkout cdk-1.4.x
How do I checkout CDK 1.4.2?
Using the "cdk-1.4.2" tag, we can get a copy of the source code for release 1.4.2 with:
$ git checkout -b cdk-1.4.2-copy cdk-1.4.2
For CDK Developers
What should I do first before making commits?
Before you commit any change to a local branch, you should set your name and email address. Because commits are no longer linked to a SourceForge account, this is critical, and I'll reject all commits without proper name and email address.
$ git config --global user.name "mad scientist" $ git config --global user.email email@example.com
How do I make a private branch for my own development?
Assumes you already have a local clone up the Git repository on SourceForge.
$ git checkout -b myLocalBranchForMyOwnNewFeature cdk-1.2.x
It is highly recommended to put every independent new feature in a separate branch. This will result in small patches that are easier to review and therefore more easily incorporated in the main development branch.
How do I keep my development branch synchronized with upstream?
If you are developing a patch for cdk-1.2.x, then it wise the make it a patch against the latest version. I will not go into details here, but google for details on 'git rebase' to get some background info. In general, assuming you have a local development branch which was branched from the main cdk-1.2.x branch, you do:
$ git checkout myLocalBranchForMyOwnNewFeature $ git rebase cdk-1.2.x
Can I email my patches?
Yes. You can make patches with the command:
$ git format-patch 843b6c2f5fb4178c627e8a8db57421bce4b43efc
This command will make patches for every commit *after* identified by the 40-char code (as given by git log).
You can email the resulting .patch files to cdkpatches _at_ gmail _dot_ com.
How do I apply patches created with format-patch?
You can apply such patches with:
$ git am 0001-Clean-up-of-PathTools-and-added-test-method-annotati.patch
Can I test patches by others that have not been included in the SourceForge repository?
Yes. Git is a distributed system, and any repository is equal. The SourceForge one just happens to be the main repository from which we make releases. It is advisable to make a branch before applying third party patches, as branches are easier to delete if you do not like them. You have ensure that you branch from the right commit, to ensure your local branch and branch you pull have a common history. The below example pulls a patch from a remove branch (myCoolPatch) made from master:
$ git checkout -b testPatchByDeveloperX master $ git pull git://www.example.com/cdk myCoolPatch
You can then inspect the patch in detail with:
$ git log
But there may be better ways to do this, for example, for when you do not know from which branch a patch was made? To be continued...
How do I indicate that the commit I have reviewed is OK?
If you are happy with a patch, you can 'approve' it by doing a 'sign-off', which works on a commit-by-commit basis:
$ git commit --amend --signoff
If the patch contains many commit, you can sign them one-by-one by using 'git rebase -i HEAD~10' where you can replace the 10 by any number depending on how many patches you need to go back to sign all commits. Read the 'git rebase -i' documentation on how to make the rebase allow you to edit patch by patch, where the edit is merely the signoff given above.
Alternatively, you can pass a particular commit hash with the '-c' option. For example:
$ git commit --amend --signoff -c 8ed3ffdd1f623fbac13c1af545811a6bf1cf7a65
How can I publish a branch on my web server?
Publishing your own branch on a public Git repository is fairly easy. First you need to set up a Git repository on your server:
$ ssh my.server.example.com $ cd /var/www/path/to/webserver/folders $ mkdir cdk.git $ cd cdk.git $ git --bare init $ exit
After which you can copy your branch to that location from your local machine with:
$ git checkout yourBranch $ git push ssh://my.server.example.com/var/www/path/to/webserver/folders/cdk.git yourBranch
It is important to note that the while people will be able to clone or pull using the http:// protocol, the push requires SSH access to your server and therefore uses the ssh:// protocol in the push. This has consequences for the path you give in the URL in the git push command: it needs to be a physical path, for example, /home/user/public_html/ or /var/www/, and not a the path you would find in the http:// URL version. This is particularly important in the /home/user/public_html/ situation, which is often translated to http://www.example.com/~user/ when accessing it via the web server.
To make the branch visible for cloning with with the http protocol, you need to log in once more and update some server info:
$ ssh my.server.example.com $ cd /var/www/path/to/webserver/folders/cdk.git $ git-update-server-info
How do I update my published branch?
If you want to tune your branch, for example, to reply to reviewer comments, and you do this by making additional commits, you can upload them in the same way, but you will also still need to update the server info.
$ git checkout yourBranch $ nano FOO $ git commit -m "Applied reviewer comment: Use IAtom instead of Atom" FOO $ git push ssh://my.server.example.com/var/www/path/to/webserver/folders/cdk.git yourBranch $ ssh my.server.example.com $ cd /var/www/path/to/webserver/folders/cdk.git $ git-update-server-info
For Branch Managers
How do I go about applying or pulling a patch?
Patches can either come via an email attachment (generated using git format-patch) or by pulling from a developers remote repository. First consider the case of an email patch, that say is made against cdk-1.2.x.
$ git checkout cdk-1.2.x $ git pull # to be in sync with cdk-1.2.x on SourceForge $ git checkout -b patchBranch $ git am -s PATCH_FILE
At this point, you should look at the changes, make sure it compiles and all the usual stuff of code review. Next
$ git checkout cdk-1.2.x $ git rebase patchBranch
At this point, if you view the git log, you will see that the patch from patchBranch is now included in the history of cdk-1.2.x, in a linear fashion. That is, no pesky merge messages in the commit log.
An alternative approach is to pull directly from a contributors repository. The sequence is as follows:
$ git checkout cdk-1.2.x $ git pull # to be in sync with cdk-1.2.x on SourceForge $ git checkout -b patchBranch $ git pull git://remote.re.po branchName
Doing a git log will show that the patch is commited to patchBranch but will also include a merge commit at the top of the log. One useful technique that helps to show what the merge brought in, is to do
$ git log HEAD~1..HEAD
This is useful since the result of the pull is to show the merge commit message at the top of the log, whereas the actual code changes might be at an earlier date and hence lower down in the log. The above command shows explicitly what was in the merge.
One possibility, rather than a plain pull, is to use the --rebase argument. However if there is a change in the local that is not in the remote branch or vice versa, a merge will take place
How do I get a writable checkout?
SVN had a read-only and a rewrite repository. So does Git, and you'll need the ssh:// format to be able to push changes. However, in practice one the branch managers will have write access and pull from your branch instead.
$ git clone ssh://$YOURSFACCOUNT@cdk.git.sourceforge.net/gitroot/cdk
However, when doing a push you might face the error below:
$ git push origin ... error: unable to create temporary sha1 filename ./objects/f4: File exists ... fatal: failed to write object error: unpack failed: unpacker exited with error code To ssh://firstname.lastname@example.org/gitroot/cdk ! [remote rejected] cdk-1.2.x -> cdk-1.2.x (n/a (unpacker error)) error: failed to push some refs to 'ssh://email@example.com/gitroot/cdk'
In case you see something like this, you should ask to have Git access set via the Admin settings.
How come I can not push my changes to the repository on SourceForge? I could with the SVN repository?
Only branch managers can do this. If you have written a patch, this patch will need to be reviewed by peers first. When the branch manager decides that the patch is in good shape, he will pull from your repository, or apply your patch otherwise. Before, with SVN, many CDK developers had write access.
How do I apply bug fixes in the cdk-1.2.x branch to master?
Merging and rebasing is not working, so you are stuck with pulling the changes with:
$ git checkout master $ git pull . cdk-1.2.x
How to make a tag?
SVN had a tags/ folder where we could keep released versions. How does Git do tags?
$ git tag cdk-1.2.0 $ git push --tags
How do I publish and remove a branch on SourceForge?
SVN had a branches/ folder where we could publish branches publically. Git is a distributed system, and can have branches anywhere. However, for the CDK development we will have branches from which releases are made. Branches on SourceForge will *not* be used for development; distributed branches outside SourceForge will be used for this instead.
To publish a new local branch on SourceForge:
$ git checkout -b cdk-2.0.x master $ git push origin cdk-2.0.x
To remove a branch from SourceForge you can use the ':' operator:
$ git push origin :cdk-2.0.x