In Relation To

Back to home

Hibernate moves to Git + Git tips and tricks

Posted by    |      

Yyou probably don't know it yet but Hibernate Core and Hibernate Validator source code is now on Git and Hibernate Search and co will likely follow very soon. There are various reasons for the move but to summarize it, life was not bad under SVN but it's really great under Git.

Getting Hibernate sources

The public reference Git repository is hosted at GitHub. We are not married to GitHub but so far, we really like the infrastructure they offer. Kudos to them! In any case moving is one clone away. That tends to keep services like that on their toes.

Hibernate Core is here while Hibernate Validator is there.

Contributing

If you want to contribute a fix or new feature, either:

  • use the GitHub fork capability: clone, work on a branch, fork the repo on GitHub (fork button), push the work there and trigger a pull request (pull request button). Also see http://help.github.com/forking and http://help.github.com/pull-requests
  • use the pure Git approach: clone, work on a branch, push to a public fork repo hosted somewhere, trigger a pull request git pull-request
  • provide a good old patch file: clone the repo, create a patch with git format-patch or diff and attach the patch file to JIRA

Our preference is GitHub over pure Git over patches:

  • GitHub lets us comment on your changes in a fine grained way
  • Git generally leads to more small commits that are easier to follow
  • a big fat patch of 100k is always depressing and can't be updated easliy

If you still want to do it the old way a provide a patch file, that's ok too.

Various tips on Git

While in no way comprehensive, here are a collection of useful tips when using Git.

Read a book on it

The time will be worth it. I particularly enjoyed Pro Git. It's an awesome book and very practical. It has a free html and epub version (buying the tree version is recommended to repay the author).

Cloning

Prefer the git protocol when cloning over http (so say the experts). At the very least that will be much faster. cloning the repo from GitHub took me less than 3 minutes. 

#for people with read/write access
git clone git@github.com:hibernate/hibernate-core.git

#for people with read-only access
git clone git://github.com/hibernate/hibernate-core.git

This will create a remote link named origin. I usually tend to rename it to reflect what it really is. 

git remote rename origin core-on-github

Note that you can attach more than one remote repository to your local repository 

git clone git://github.com/hibernate/hibernate-core.git
git remote rename origin ref-core-github
git remote add manu-core-github git@github.com:emmanuelbernard/hibernate-core.git
git fetch manu-core-github

Pushing and pulling

To initially get a copy of a remote branch locally, do 

git checkout -b 3.6 origin/3.6

When pulling a branch, it's best to keep the same name between the origin repo and your clone. Many syntax have shortcuts in this situation (are you listening Hardy? ;) ). You can then do 

git push origin master

If you happen to have renamed the branch master to say local-master locally, do 

git push origin local-master:master

To delete a branch on a remote repository, you push an empty one 

git push origin :branch-to-remove

Branches

Always work on a topic branch and merge your work when you are done. 

git checkout master
git checkout -b HHH-XXX
#hack commit hack commit

Don't forget to pull from your master and rebase this topic branch before proposing request pull.

There are many advantages to this, one of them being that you can work on many different things in parallel and sync them with the reference master easily.

Likewise if you want to share a work with somebody from the Hibernate team, push to the public repo and define the pull request of your topic branch. Make sure your topic branch is above the most recent master.

Commits

Prefer small commits, they will be more readable and will very unlikely fail on merge.

Write good comments (one short line including the issue number at stake and a summary, followed by a blank line and a more detailed explanation if needed. 

HHH-XXX Fix NPE on persist

Fix stupid bug by Gavin that lead to a NPE when persisting objects with components

Merge or rebase

It's a debate, but here is my take on it.

  • Primitive 0: DO NOT rebase a branch that you have shared publicly (unless you know people won't use it or you wish them harm).
  • Primitive 1: Prefer rebase over merge assuming it does not break Primitive 0

This is particularly sensible when you trigger a pull request: rebase atop the branch you are branching of (master usually). Your work will be easier to read and integrate.

Rebase put changes from the branch you forked (say master) below the new commits you have done (say HHH-XXX) and thus keep the history linear. 

git checkout HHH-XXX
git rebase master

While we are at rebasing, you can rewrite your commit history to clean comments or merge some commits together (aka squashing) 

git rebase -i HEAD~6 (go back 6 commits in time)

Backporting: cherry-picking

Git made backporting fun.

Say you have done some commits on master and the sha1 of the commits are ae397d... and 87ab342...

You can apply them on an older branch very easily. 

git checkout 3.5
git cherry-pick ae397d
git cherry-pick 87ab34

Bam, you're done. Now did I tell you to do small commits? That's also for the backporters.

Aliases and configuration

Once you're fed up with typing longish command lines, use aliases. I've put a copy of my ~/.gitconfig file in case people want to copy some things including aliases (see below) 

~/.gitconfig
[user]
     name = Redacted
     email = redacted@redacted.com
     signingkey = id_key.pub
[core]
     editor = open -nW -a Smultron
[merge]
     tool = opendiff
[color]
     ui = auto
[color "branch"]
     current = yellow reverse
     local = yellow
     remote = green
[color "diff"]
     meta = yellow bold
     frag = magenta bold
     old = red bold
     new = green bold
[color "status"]
     added = yellow
     changed = green
     untracked = cyan
[github]
     user = redacted
     token = redacted
[alias]
     co = checkout
     undo = reset --hard
     cb = checkout -b
     br = branch
     cp = cherry-pick

Tools

If you use Mac OS X, GitX is a fantastic tool. In particular, you can very easily play with interactive staging and commit only some parts of a file in a couple of clicks. A typical use case is to separate the commit of a typo from the commit of a core feature. Some people like the built-in GitK GUI.

Command completion support via git-completion.bash is pretty good if you are command shell type person. The script is available in the Git project sources and in other places (including Fedora). Pro Git has some more information on it.

Various

You can also read this blog entry that was some more info for people moving from SVN to Git.

This entry is too long already, feel free to add your tips in the comments.

Back to top