Understanding and Using Git at Eclipse
Chris Aniszczyk (Red Hat)
Shawn Pearce (Google)
Robin Rosenberg (Dewire)
Matthias Sohn (SAP)
Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn
Outline
• Introduction
• Git Concepts
• Git Exercises
o Installing Git and EGit
o Setting Up a Repository
o Making Changes
o Browsing History
o Branching & Merging
o Rebasing
o Collaborating
o Reviewing and Maintaining
o Tagging
• Conclusion
2
Understanding Git at Eclipse | © 2010 by Chris Aniszczyk, Shawn Pearce and Matthias Sohn, made available under the EPL v1.0
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
2006
2007
2008
2009
Linus Torvalds starts Git
Proof-of-concept, quite unusable
Index reader, quickdiff
Add history view, commit, push/fetch
Moved to Eclipse.org
2010 Automatic IP Logs
Diff/Merge
Cleanup API
Exit Incubation
Release 1.0
Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn
Git Concepts
We need the basics
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 problems
• You need to be on-line to perform actions
• Patches 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
Changesets contain pointers to the previous changeset
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
+SVNUnderstanding
is great
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 Remotes
git 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
Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn
Exercises
You're armed with the
basics now
Exercise - Installing Git and EGit
Git installation packages:
http://git-scm.com/download
Pre-packaged with most Linux distributions as git-core
EGit update site:
http://download.eclipse.org/egit/updates
Requires 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
Reference
Git Cheat Sheet
http://git-scm.com/documentation
http://www.kernel.org/pub/software/scm/git/docs/
http://git.wiki.kernel.org/index.php/GitCheatSheet
EGit User Guide
http://wiki.eclipse.org/EGit/User_Guide
EGit Eclipse Help
Help > Help Contents > EGit User Guide
EGit Contributor Guide http://wiki.eclipse.org/EGit/Contributor_Guide
Git for committers
Git for Eclipse users
From git command line:
$ git help <command>
http://wiki.eclipse.org/Git_for_Committers
http://wiki.eclipse.org/EGit/Git_For_Eclipse_Users
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 version
Note: if you select multiple projects they must all reside under a common
folder
• Team > Share Project > Git, click "Next"
• Select the project(s) to be shared
• Click "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 message
• Click "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 diff
to 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 Decorations
General > 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 log
if you also want to see the diffs use
$ git log -p
for an overview use
$ git log --stat --summary
if 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 selecting
Team > Show in Resource History
from 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 revisions
Select 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) - 1
Branches 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 newfeature
then do some changes and commit them
$ git checkout -b newfeature
is a shortcut combining both these steps in one go
Exercise - Branching (git) -2
Switch back to the master branch
$ git checkout master
do 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
$ gitk
Then 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 project
Team > Branch
to 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 Keys
check 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 key
choose 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 guide
• Add a remote for the review server
• Start 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 repository
cd to your Eclipse workspace
via anonymous git: protocol
$ git clone git://egit.eclipse.org/Mail.git
via 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 topic
refresh projects in Eclipse & start editing
commit change to local topic branch
Exercise - Collaborating (git) - 2
push your change back (from local topic branch to Gerrit)
$ git push review
this pushes back all changes which are on the current branch
but not in remote master
Go to Gerrit and review the change you just uploaded
http://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.git
via filesystem
file:///copied/from/usb-stick/egit.git
via ssh
ssh://[<user@>]egit.eclipse.org/egit.git
create a new local topic branch topic
start doing changes
and commit them to the local branch
Exercise - Collaborating (EGit) - 2
push your changes back (from local topic branch to remote Gerrit)
Team > Push To
Select Configured Remote Repository > origin
click Next
Source Ref: refs/heads/topic Target Ref: refs/for/master
click Add Spec
click 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 Repository
• Source Ref: refs/heads/* Target Ref: refs/remotes/origin/*
• Finish
Rebase
Rewrite your project history!
You want to base your work on the latest version
Upstream changed while you work
You 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 push
• Eclipse review via Bugzilla
format patch
Upload as attachment
• Linux 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?
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/
Understanding and Using Git at Eclipse | © 2010 by C. Aniszczyk, S. Pearce, R. Rosenberg and M. Sohn