Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Understanding and Using Git at Eclipse

Chris Aniszczyk (Red Hat)

Shawn Pearce (Google)Robin Rosenberg (Dewire)

Matthias Sohn (SAP)

Understanding Git at Eclipse | © 2010 by Chris Aniszczyk, Shawn Pearce and Matthias Sohn, made available under the EPL v1.0 2

Outline

IntroductionGit ConceptsGit Exercises

Installing Git and EGitSetting Up a RepositoryMaking ChangesBrowsing HistoryBranching & MergingRebasingCollaboratingReviewing and MaintainingTagging

Conclusion

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Here's the Deal

All of us want to see Git successful at Eclipse Git like any other DVCS has a bit of a learning curve

This tutorial is made up of a brief introduction followed by some exercises on using Git, EGit and Gerrit

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

No Free Lunch

The best way to learn Git is to use Git

Please stop and ask us questions at anytime

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

A History Lesson

2005 Linus Torvalds starts Git2006 Proof-of-concept, quite unusable2007 Index reader, quickdiff2008 Add history view, commit, push/fetch2009 Moved to Eclipse.org

2010 Automatic IP Logs Diff/Merge Cleanup API Exit Incubation Release 1.0

Git Concepts

We need the basics

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

What is Git?

Distributed Version Control System (DVCS) Originally created for the Linux Kernel If you want comedy, watch Linus' talk at Google http://www.youtube.com/watch?v=4XpnKHJAok8

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Centralized VCS

Examples? CVS and SVN There is one Master repository where code is shared

Everyone checks out their code (or branch) from that repository, and checks changes back in

Two major problemsYou need to be on-line to perform actionsPatches go stale

They suck

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Distributed VCS

Examples? Git and Hg Each user has a full local copy of the repository

Forks happen, deal with it

There is no real master repository like in a CVCS

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

How does it work?

A DVCS operates at the level of a changeset Logically, a repository is made up from an initial empty state, followed by many changesets Changesets are identified by a SHA-1 hash value e.g., 0878a8189e6a3ae1ded86d9e9c7cbe3f

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

It's all about the changesets

previous: 48b2179994d494485b79504e8b5a6b23ce24a026--- a/README.txt+++ b/README.txt@@ -1 +1 @@-SVN is great+Git is great

previous: 8cafc7ecd01d86977d2af254fc400cee--- a/README.txt+++ b/README.txt@@ -1 +1 @@-Git is great+SVN is great

Changesets contain pointers to the previous changeset

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Branches

The current version of your repository is simply a pointer to the end of the tree The default "trunk" in Git is called "master"

The tip of the current branch is called "HEAD" Any branch can be referred to by its hash id Creating branches in a DVCS is fast, you simply point to a different element in the tree on disk already

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Merging

DVCSs are all about merging Given that each node in the changeset tree contains a pointer to its previous node (and transitively, to the beginning of time), it's much more powerful than the standard flat CVCS diff. In other words, not only do you know what changes need to be made, but also what point in history they need to be made . So, if you have a changeset which renames a file, and then merge in a changeset which points to the file as it was before it was renamed, then a CVCS will just fall over; but a DVCS will be able to apply the change before the rename occurred, and then play forward the changes.

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Merging

Merges are just the weaving together of two (or more) local branches into one However, unlike CVCS, you don't have to specify anything about where you're merging from and to; the trees automatically know what their split point was in the past, and can work it out from there.

Merging is much easier in a DVCS like Git

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Pulling and Pushing

We've not talked about the distributed nature of DVCS Changes flow between repositories by push and pull Since a DVCS tree is merely a pointer to a branch... There's three cases to consider for comparing two trees:

Your tip is an ancestor of my tip My tip is an ancestor of your tip Neither of our tips are direct ancestors; however, we both share a common ancestor

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Cloning and Remotesgit clone git://egit.eclipse.org/egit.git Where you can push or pull to is configured on a per (local) repository basis git remote add github http://github.com/zx/myegit.git origin is the default remote; you can have many remotes

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Git Internals

Cryptographic signatures ... ensures data integrity

Snapshot based ... saves whole project

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Git Internals

Cryptographic signatures ... ensures data integrity

Snapshot based ... saves whole project History stored as graph ... accurate records

Exercises

You're armed with the basics now

Exercise - Installing Git and EGit

Git installation packages: http://git-scm.com/downloadPre-packaged with most Linux distributions as git-core

EGit update site: http://download.eclipse.org/egit/updatesRequires Eclipse 3.4 or later

=> get packages from the USB stick and install them

Introduce yourself to git :$ git config --global user.name "Joe Developer"$ git config --global user.email joe.dev@example.com

Documentation

List of documentation http://git-scm.com/documentationReference http://www.kernel.org/pub/software/scm/git/docs/Git Cheat Sheet http://git.wiki.kernel.org/index.php/GitCheatSheet

EGit User Guide http://wiki.eclipse.org/EGit/User_GuideEGit Eclipse Help Help > Help Contents > EGit User GuideEGit Contributor Guide http://wiki.eclipse.org/EGit/Contributor_Guide

Git for committers http://wiki.eclipse.org/Git_for_CommittersGit for Eclipse users http://wiki.eclipse.org/EGit/Git_For_Eclipse_Users From git command line:$ git help <command>

Exercise - Setting up a repository (git)Initialize a fresh repository starting from your favorite project (or create a new one)

$ cd project$ git init Initialized empty Git repository in .git

Add a snapshot of the working tree to the index (temporary staging area)$ git add . Persist the contents of the index into the repository:

$ git commit

This will prompt you for a commit message. You just stored the first version of your project in the repository.

Exercise - Setting up a repository (EGit)

Initialize a fresh repository starting from your favorite Eclipse project

In package explorer select the project(s) you want to versionNote: if you select multiple projects they must all reside under a common folderTeam > Share Project > Git, click "Next"Select the project(s) to be sharedClick "Create Repository", then "Finish"Team > Add to Version Control adds the selected files to the index

Team > Commit opens the commit dialog prompting for a commit messageClick "Commit"You just stored the first version of your project in the repository.

Exercise - Making Changes (git)Modify or add some files ... and stage them for commit

$ git add file1 file2

to get a brief summary of the situation run

$ git status# On branch master# Changes to be committed:# (use "git reset HEAD <file>..." to unstage)## modified: file1# modified: file2

to compare working tree and index run$ git diffto compare index and last commit run$ git diff --cached then commit all staged changes$ git commit

Exercise - Making Changes (EGit)

Modify or add some files ... and stage them for commit Team > Add to Version Control adds the selected files to the index Resources are decorated according to their state following these preferences:Team > Git > Label DecorationsGeneral > Appearance > Colors and Fonts > Git

To compare working tree and index select Compare with > Git Index on modified resources

Team > Commit and provide a commit message describing your change

Exercise - Browsing History (git)

Inspect the history using$ git logif you also want to see the diffs use$ git log -p for an overview use$ git log --stat --summaryif you prefer a graphical display of the history run $ gitk or to display all branches$ gitk --all

Exercise - Browsing History (EGit)Inspect the history by selectingTeam > Show in Resource Historyfrom the context menu

Using the toggle buttons of the history view you may adapt its filtering behavior to your needs.

Select a commit to see what changes it introduced. Comparing file revisionsSelect a file in the package explorer ...

... and select a commit from the commit log pane then select Compare with working tree from the context menu ... or select two commits you want to compare then select Compare with each other from the context menu.

Exercise - Branching (git) - 1Branches are used heavily with git to isolate development on different topics from each other. To create a new branch to e.g. implement a new feature run$ git branch newfeature

list all branches( the currently checked out branch is marked with * ) $ git branch newfeature* master

check out this branch to your working tree $ git checkout newfeaturethen do some changes and commit them

$ git checkout -b newfeatureis a shortcut combining both these steps in one go

Exercise - Branching (git) -2Switch back to the master branch $ git checkout masterdo some different changes on the master branch and commit them.At this point the two branches have diverged with different changes in each.

To merge the feature into the master branch run (from the master branch)$ git merge newfeature

In case of conflicts markers are inserted into the conflicting files this can be shown with$ git diff

edit the files with conflicts to resolve the conflicts and commit the resolving changes.

Inspect the resulting version history using $ gitkThen delete the feature branch$ git branch -d newfeature

Exercise - Branching (EGit)

Repeat the previous exercise in EGit, use the following context menu on your Eclipse projectTeam > Branchto create branches and to switch between different branches.

Merging is not yet available in EGit (we are working on it)hence for now use C git for merging.

Exercise - SSH Configuration

SSH Keyscheck if your ~/.ssh already contains SSH keys, if not run (use your email)$ ssh-keygen -t rsa -C "joe@example.com"id_rsa is the default private key, id_rsa.pub is the default public keychoose a good pass phrase to protect your key

In Eclipse check that you point at the right keys (you may also generate them from here)Preferences > General > Network Connections > SSH2

Gerrit Registration

To demonstrate collaboration using git and Gerrit we invite you to play contributor on the simple RCP mail example

Follow registration instructions in EGit contributor guideAdd a remote for the review serverStart Eclipse 3.5 or 3.6

The workflow we cover in this tutorial is the exact workflow that you would use if you wanted to contribute to the EGit and JGit projects

Exercise - Collaborating (git)

Clone a remote upstream repositorycd to your Eclipse workspacevia anonymous git: protocol $ git clone git://egit.eclipse.org/Mail.gitvia filesystem$ git clone file:///copied/from/usb-stick/Mail.git via ssh $ git clone ssh://[<user@>]egit.eclipse.org:29418/Mail.git

import projects into Eclipse Import > Existing Projects

create a new local topic branch topicrefresh projects in Eclipse & start editingcommit change to local topic branch

Exercise - Collaborating (git) - 2

push your change back (from local topic branch to Gerrit)$ git push reviewthis pushes back all changes which are on the current branch but not in remote master Go to Gerrit and review the change you just uploadedhttp://egit.eclipse.org/r/#mine

EMail based collaboration

create patch file (for last commit)$ git format-patch -1... attach patch file to Bugzilla ... or send it to mailing list for review ... or directly to another developer

... as receiver apply patch file to another repository$ git am <patch-file>check that the patch has been applied to your current branch$ git log -p

Generating patch for attachment to Bugzilla

Exercise - Collaborating (EGit)

Clone a remote upstream repository (this time egit)Import > Git > Git Repository, click Next

URL via anonymous git: protocol git://egit.eclipse.org/egit.gitvia filesystemfile:///copied/from/usb-stick/egit.git via ssh ssh://[<user@>]egit.eclipse.org:29418/egit.git

create a new local topic branch topicstart doing changesand commit them to the local branch

Exercise - Collaborating (EGit) - 2

push your changes back (from local topic branch to remote Gerrit)Team > Push ToSelect Configured Remote Repository > origin click NextSource Ref: refs/heads/topic Target Ref: refs/for/masterclick Add Specclick Next, click Finish

Staying up to date

pull new upstream changes from remote master branch to current local branch$ git pull [origin]

In two steps$ git fetch origin$ git merge origin/master

pull new upstream changes from remote stable-0.7 to local my-0.7$ git pull origin stable-0.7:my-0.7

pull is fetch + merge and may lead to conflicts

EGit:fetch is available from Team > Fetch from... select origin as Configured Remote RepositorySource Ref: refs/heads/* Target Ref: refs/remotes/origin/*Finish

Rebase

Rewrite your project history!

You want to base your work on the latest versionUpstream changed while you workYou haven't published yet

Solution: Reapply every change onto the latest upstream.Rebase automates this

on the branch you want to rebase onto latest upstream run$ git fetch [origin]$ git rebase origin/master

Rebase may lead to conflicts

Rebasing (interactive)A tool for cleaning up history before sharing your version

- change something a- change something else b- oops, not so good, fix a- changed my mind about b- Shawn didn't like some piece of a

rebase into- Change something a- Change something else b

Start with the last commit you want to retain as-is:git rebase -i <after-this-commit>then follow section "Interactive Mode" of git-rebase reference

Now other people can understand your work better

Reviewing and Maintaining

Gerrit workflow git pushEclipse review via Bugzillaformat patchUpload as attachmentLinux kernel process via mailing list send a patch via mail to your neighbor, he applies it to his repo and vice versa

Inline patches and comments:> if ( foo <= size) {You should use strictly less than here

Tagging

List tags$ git tag -l Make lightweight tag$ git tag v1.0

Make unsigned annotated tag, prompts for tag message$ git tag -a v1.0 Make a GPG-signed tag, using the default e-mail address's key$ git tag -s v1.0 Delete tag$ git tag -d v1.0

Conclusion

Do we love Git yet?

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Conclusion

DVCS like Git are powerful

Git supports convenient branching and merging Git is very fast and scales well Gerrit enables a nice code review workflow

Git is the future SCM of Eclipse

Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn

Resources

Ask questions on the EGit/JGit forums http://git-scm.com/documentation is your friend

Read the Pro Git book - http://progit.org/book/