Monday, 14 May 2012

Homepage: http://www.eclipse.org/egit
Update Site: http://download.eclipse.org/egit/updates

Introduction to Git

Read: http://wiki.eclipse.org/EGit/Git_For_Eclipse_Users and http://wiki.eclipse.org/EGit/User_Guide

Some excerpts:
... a DVCS (distributed versioning control system) operates at the level of a changeset. Logically, a repository is made up of an initial (empty) state, followed by many changesets. (A changeset is merely a change to a set of files; if you think 'patch' from CVS or SVN, you're not far off.) ...

... a changeset is represented as a hash of its contents ... we can create a 'hash' using (for example) md5, to generate the string  0878a8189e6a3ae1ded86d9e9c7cbe3f. When referring to our change with  others, we can use this hash to identify the change in question. ...

... a changeset contains two things; the change itself, and a  back-pointer to the previous changeset. ...

... The default 'trunk' is called 'master' in Git ... The tip of the current branch is referred to as 'HEAD' ... Creating, and switching between, branches is fast ...

... Because branching is so fast, branches get used for things where a user of a CVCS wouldn't normally use branching. For example, each bug in Bugzilla could have a new branch associated with it; if a couple of independent features are being worked on concurrently, they'd get their own branch; if you needed to drop back to do maintenance work on an ECLIPSE_35 branch, then you'd switch to a branch for that as well. Branches get created at least as frequently as changesets might in CVS, if not more so. ...

... Merges are just the weaving together of two (or more) local branches into one. The git merge documentation has some graphical examples of this; but basically, it's just like any other merge you've seen. 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. ...

... Changes flow between repositories by push and pull operations. In essence, it doesn't matter whether I push my changes to you, or you pull my changes from me; the net result is the same.
However, in the case of Eclipse.org infrastructure, it's likely that a central Git repository will be writable only by Eclipse committers.
Thus, if I contribute a fix, I can ask a committer to pull the fix from my repository, and then they (after reviewing, and optionally rebasing) can push the fix to the Eclipse.org repository. ...
... Often, you'll work on a branch for a while and then want to commit it to the repository. You can do this at any point, but it's considered good practice to rebase your local branch before doing so. For example, you can end up with multiple branches in the log (with git log --graph --oneline):

*   f0fde4e Merge change I11dc6200
|\
| * 86dfb92 Mark the next version as 0.6
* |   0c8c04d Merge change I908e4c77
|\ \
| |/
|/|
| * 843dc8f Add support for logAllRefUpdates configuration parameter
* | 74ba6fc Remove TODO file and move to bugzilla
* | ba7c6e8 Fix SUBMITTING_PATCHES to follow the Eclipse IP process
* | c5e8589 Fix tabs-to-spaces in SUBMITTING_PATCHES
* | 677ca7b Update SUBMITTING_PATCHES to point to Contributor Guide
* | 8847865 Document protected members of RevObjectList
* | a0a0ce8 Make it possible to clear a PlotCommitList
* | 4a3870f Include description for missing bundle prereqs
|/
* 144b16d Cleanup MANIFEST.MF in JGit

What happened here was that two branches split off from change 144b16d, ultimately driving another branch at 74ba6fc and a few merges (at 0c8c04d and f0fde4e). ...
Ultimately, whilst the DVCS can handle these long-running branches and subsequent merges, humans tend to prefer to see fewer branches in the final repository.

A fast-forward merge (in Git terms) is one which doesn't need any kind of merge operation. This usually happens when you are moving from an older branch to a newer branch on the same timeline; such as when updating to a newer version from a remote repository. These are essentially just moving the HEAD pointer further down the branch.

A rebase is uprooting the branch from the original commit, and re-writing history as if it had been done from the current point in time. For example, in the above Git trace, 1441b16d to 843dc8f to 0c8c0fd was  only one commit off the main tree. Had the change been rebased on 74ba6fc, then we would have only seen a single timeline across those commits.
It's generally considered good practice to rebase changes prior to pushing to a remote tree to avoid these kind of fan-outs, but it's not necessary to do so. Furthermore, the rebase operation changes the sha1 hashes of your tree, which can affect those who have forked your
repository. Best practice is to frequently rebase your changes in your own local repository, but once they've been made public (by pushing to a shared repository) to avoid rebasing further. ...

EGit Plugin Installation

"Eclipse - Help - Install Software ..."
Install:
  • Eclipse Git Team Provider (without EGit - Source)
  • JGit (without JGit - Source)

Configuration

Source see here: http://programmingandelse.blogspot.de/2011/02/eclipse-egit-github-quick-guide-to.html

Configuring ssh keys


Create .ssh folder:
$ mkdir ~/.ssh
If the directory already exists, it will simply throw an error and skip. Generate rsa key pair:
$ ssh-keygen -t rsa -C "youremail@yourdomain.com"

Generating public/private rsa key pair.
Enter file in which to save the key (/home/ralf/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/ralf/.ssh/id_rsa.
Your public key has been saved in /home/ralf/.ssh/id_rsa.pub.
...
The -C is just an optional comment. By default, it will be saved in ~/.ssh/ directory. For now leave the passphrase empty!
This is important, since Eclipse has a bug handling passphrase protected keys. We will give it a passphrase later. Now, go to your account on github, go to "Account Settings" (top right), than click on "SSH Keys" on the left menu and "Add SSH key". The title should be some comment that identifies which computer this key is from (such as "T500-notebook"), and the "key" should be the exact contents of the file ~/.ssh/id_rsa.pub.
$ cat ~/.ssh/id_rsa
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
Only the lines between the two markers should be copied. But just marking this doesn't work: "Key is invalid. It cannot contain newlines. Ensure you've copied the file correctly"...
There is a neat trick using xclip to copy the contents of the file to the clipboard without messing anything (such as adding whitespace and newlines):
$ sudo apt-get install xclip

$ cat ~/.ssh/id_rsa.pub | xclip -sel clip
Those commands copy the contents of the file to your clipboard. Now just ctrl+v in the "Key" box in github and you should be done. Confirm with your github's password.

To test everything is working, try running:
$ ssh -T git@github.com
And you should receive a message that looks like:
Hi datazuul! You've successfully authenticated, but GitHub does not provide shell access.
One possible problem here is getting a message that looks like:
Permission denied( publickey).
If you do, try manually adding your generated key to ssh path and checking permissions are correct:
$ chmod 700 ~/.ssh/id_rsa
$ ssh-add ~/.ssh/id_rsa
I had this problem because I regenerated the pairs a few times and ssh somehow couldn't find my key anymore. If that doesn't work, please refer to git troubleshooting guide [http://help.github.com/ssh-issues/] for other possible problems.

Configuring Eclipse

Configure SSH

Here, we need to configure SSH.
  1. Go to "Windows - Preferences" and filter SSH. Select "SSH2" on the left tab (should be under "General - Network connections").
  2. Check that "SSH2 home" is set to "/home/<yourusername>/.ssh" and "id_rsa" is in "Private Keys".
  3. On "Key Management" tab, click on "Load Existing Key..." and select your id_rsa (private) key under "~/.ssh/id_rsa". If your key has a non-empty passphrase, eclipse will not be able to load it, even if you provide the correct password.
  4. Now, just save it in the same location you loaded it from, confirm empty passphrase, overwrite it, apply and click ok.

Adding a passphrase to your ssh key

After configuring Eclipse, you should probably set a non-empty passphrase to your ssh key. It is not the scope of this post to discuss why you shouldn't leave your passphrase empty, but here is how:
$ cd ~/.ssh
$ ssh-keygen -f id_rsa -p
This command will prompt for a new passphrase and you are done!

Usage

Create a New Repository on GitHub

  • Project Name: datazuul
  • Description: datazuul's project
Output:
Global setup:
  git config --global user.name "Your Name"
  git config --global user.email ralf.eichinger@pixotec.de
Next steps:
  mkdir datazuul
  cd datazuul
git init

Initialized empty Git repository in /home/ralf/Desktop/Daten/Git-Repositories/datazuul/.git/

  touch README
  git add README
  git commit -m 'first commit'

if you forgot to set global config:

[master (root-commit) 8450c25] first commit
Committer: Ralf Eichinger <ralf@T500.(none)>
Your name and email address were configured automatically based
on your username and hostname. Please check that they are accurate.
You can suppress this message by setting them explicitly:

  git config --global user.name "Your Name"
  git config --global user.email you@example.com

After doing this, you may fix the identity used for this commit with:

  git commit --amend --reset-author

0 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 README

  git remote add origin git@github.com:datazuul/datazuul.git
  git push -u origin master

Enter passphrase for key '/home/ralf/.ssh/id_rsa':
Counting objects: 3, done.
Writing objects: 100% (3/3), 214 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To git@github.com:datazuul/datazuul.git
* [new branch]      master -> master
Branch master set up to track remote branch master from origin.


Existing Git Repo?
  cd existing_git_repo
  git remote add origin git@github.com:datazuul/datazuul.git
  git push -u origin master

Pushing your project to your github repo

Final step is to push your project to your remote repository on github.
  1. Finally, select the project you want to push to your created repository, right click it, go to "Team - Share Project..." and select git.
  2. Select your project, click on "Create Repository" and "Finish". Now you should be able to commit and update changes to your "local git repository".
  3. To push it to your remote github repo, right click your project, select "Team - Remote - Push..."
  4. Fill the URI with your project "SSH" address, which is shown when you enter your repository page on github.
  5. Select "ssh" protocol, user is "git" and empty password.
  6. Cross your fingers, hit next. If it doesn't work for some reason at this point, try restarting Eclipse (it worked for me after restart).
  7. Select "Source Ref" and "Destination Ref" (basically the branch), click on "Add Spec" and "Finish" on the next screen.
  8. Hopefully everything goes well.

Importing a project from a github repo

Easier than pushing is checking out a project.
  1. From Eclipse, select "File - Import" and select "Projects from Git" under Git.
  2. Select "Clone" and fill this form just like step 4 of the previous section.
  3. Select the branch you would like to check out.
  4. Select the location you would like to checkout to.
  5. You should be back to "Import Projects from Git" window with your newly cloned repo showing.
  6. Select your repository and follow the instructions (defaults should be fine).