Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/Process/Git"

(How do I get started?)
 
(112 intermediate revisions by 8 users not shown)
Line 6: Line 6:
 
This page is for the Git usage portion of the dev process. It does not discuss issues with the build in Git, for more information on that please see: [http://wiki.eclipse.org/EclipseLink/Build/Git wiki.eclipse.org/EclipseLink/Build/Git] .  
 
This page is for the Git usage portion of the dev process. It does not discuss issues with the build in Git, for more information on that please see: [http://wiki.eclipse.org/EclipseLink/Build/Git wiki.eclipse.org/EclipseLink/Build/Git] .  
  
This page is a work in progress, posing the questions that need to be answered.  If you feel that you have more questions, please post them, if you can answer a question, please do.  
+
It is highly recommended to read through the whole great [http://git-scm.com/book/en/v2 ProGit] book before starting working with EclipseLink git.
  
== EclipseLink Git FAQ  ==
+
=== EclipseLink Git Repositories ===
  
=== Brief Overview and History of Git ===
+
The EclipseLink runtime repository is located here:
Git is a <b>D</b>istributed <b>V</b>ersion <b>C</b>ontrol <b>S</b>ystem (DVCS), which means there is no single point-of-failure and one can do useful work without a server. The ability to work while disconnected is very useful if a server is down or if the network connection to a server is unreliable (slow or firewalled).
+
  
The distributed nature of Git means that the source code is inherently backed-up across all the various 'clones' that may exist 'out there.' In addition, Git supports types of work-flows that are different from those supported by Subversion; these work-flows, while unfamiliar, are quite powerful and can 'overlap' - one developer may prefer a 'golden repository' work-flow while another likes 'trusted-lieutenants'; both can be supported simultaneously by the same repository.
+
http://git.eclipse.org/gitroot/eclipselink/eclipselink.runtime.git
  
Git was created by Linus Torvalds in 2005 to handle the source control requirements of the Linux kernel project. Linus previously used a for-pay DVCS called BitKeeper and grew to like the 'trusted -lieutenants' work-flow; however, the special license grant that let him use BitKeeper for free for kernel development changed. Shortly thereafter, he created Git. By 2008, other major open-source projects (Ruby-on-Rails, Android, etc.) moved to it as well.
+
Full list of EclipseLink repositories can be found here:
  
[[Image:gitArch.png|center|frame|100px]]
+
http://git.eclipse.org/c/eclipselink
  
=== How do I get started? ===
+
A useful urls to browse history of the git repo:
As shown in the picture above, graphical clients are typically not shipped with the 'core' Git distribution. There are a number of use-cases that only make sense (or only work!) from the command-line.
+
# [http://git.eclipse.org/c/eclipselink/eclipselink.runtime.git EclipseLink Git]
 +
# [https://fisheye2.atlassian.com/changelog/eclipselinkgit FishEye]
  
The 'core' Git distribution can be downloaded from the [http://git-scm.com/download Git download site (http://git-scm.com/download)] - there are links for a variety of operating systems (Linux, Mac OS X, Windows). Once you have the Git tools, you can always get the latest_&_greatest version of Git directly from its own repository:
+
== Accessing the EclipseLink Git repository ==
<source lang="text">
+
=== Read-only access through HTTP ===
prompt > git clone git://github.com/gitster/git.git
+
Read-only access to the EclipseLink Git repository can be achieved through HTTP.
</source>
+
If you have problems connecting (Git uses port 9418), you can try to access the repository over the HTTP protocol<br/>
+
(typically most Git server administrators setup HTTP access as read-only):
+
<source lang="text">
+
prompt > git clone http://github.com/gitster/git.git
+
</source>
+
  
==== Windows  ====
+
$ git clone http://git.eclipse.org/gitroot/eclipselink/eclipselink.runtime.git
  
For those currently using Tortise SVN with Windows, I would recommend using Tortoise Git.
+
=== Committer access through SSH ===
 +
==== Step 1: Git Committer Identity ====
 +
When a commit is made in Git, the commit has metadata identifying two things:
 +
# the author (name and email): who created the change, and
 +
# the committer (name and email): who committed the change to the repository
 +
(of course for many commits the author IS the committer so only the author is identified)
  
Download and install the latest Git for Windows All the versions appear to be beta/preview, so just pick the latest.  
+
The Eclipse Foundation uses these fields as part of its IP process - only committers to a project can change source stored on a Foundation's server. However, a committer may make changes on behalf of others - this enables collaboration with parties that have not gone through the Eclipse IP due diligence process. This especially is useful if say the third-party just wanted to contribute a few one-of patches: the administrative overhead of the Eclipse IP due diligence process would likely 'scare-off' most contributions (for more information, please see [http://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions Handling Git Contributions])
  
*[http://code.google.com/p/msysgit/downloads/list http://code.google.com/p/msysgit/downloads/list]Install Wizard (accept most defaults)
+
First setup your <tt>~/.gitconfig</tt> file:
*Command Line: Use Git Bash Only
+
<source lang="text">
*Choosing the SSH executable: Use (Tortoise)Plink
+
[user]
 +
        # email address linked to my EclipseLink committer id minorman
 +
        email = michael.norman@oracle.com
 +
        name = Mike Norman
 +
</source>
  
Download and install tortoisegit tortoisegit has the same look &amp; feel as tortoisesvn&lt;span id="fck_dom_range_temp_1332162837456_947" /&gt;
+
NB. Windows often has difficulty with 'dot-files' in its 'home' directory - you may have to create this file from the command-line. In addition, if your 'home' directory is on a UNC fileshare directory, the <tt>msysgit</tt> Windows-version of git tools may not be able to read or write it. I solved this issue by redefining two Windows environment variables (<tt>HOME</tt> and <tt>HOMEDRIVE</tt>):<br/>
 +
[[Image:envvar.png|center|frame|100px]]
  
*[http://code.google.com/p/tortoisegit/ http://code.google.com/p/tortoisegit/]
+
==== Step 2: SSH identity ====
*Install Wizard:
+
As mentioned above, most Git servers are set up so that HTTP access is read-only - in order to be able to commit, one must connect to the Eclipse Foundation Git servers over SSH:
*Choose SSH Client: TortoisePLink, coming from Putty, integrates with Windows better,
+
  
=== How does Git differ from SVN? ===
+
<h5>Creating an SSH identity</h5>
 +
You need to generate an SSH public/private key-pair from the command prompt:
 +
<source lang="text">
 +
prompt > ssh-keygen -t rsa -C "your_eclipse_committer_id@dev.eclipse.org" -f committerid
 +
Generating public/private rsa key pair.
 +
Enter passphrase (empty for no passphrase):
 +
Enter same passphrase again:
 +
Your identification has been saved in commiterid
 +
Your public key has been saved in commiterid.pub.
 +
prompt > ls committerid*
 +
commiterid            commiterid.pub
 +
</source>
 +
The file ending in <tt>.pub</tt> is the public portion of the key-pair. SFTP the public key, or send an email message asking 'webmaster@eclipse.org' to place it in the appropriate place in your home directory on the Eclipse Foundation's server. The private portion must be moved to your local home directory <tt>~/.ssh/committer.ppk</tt>. Now set permissions on your private key:
 +
<source lang="text">
 +
prompt > chmod 700 ~/.ssh
 +
prompt > chmod 600 ~/.ssh/committer.ppk
 +
</source>
  
==== How do patches in Git differ from in SVN? ====
+
Instead of emailing 'webmaster@eclipse.org' you can upload the key yourself:
  
==== How is merging different between Git and SVN ====
+
<source lang="text">
 +
sftp dev.eclipse.org
 +
cd /home/data/users/<your_user_name>/.ssh/
 +
put committer.pub
 +
mv committer.pub authorized_keys
 +
chmod 700 authorized_keys
 +
</source>
  
=== How do I work on two different tasks at the same time? ===
+
<h5>Creating an SSH identify on Windows</h5>
 +
PuttyGen is an alternative to "ssh-keygen" for generating a key pair.  (In general, ssh-keygen is preferable as the final step with puttygen involves cut/pasting the public key, which is more error prone)
 +
* run PUTTYGEN.EXE - make sure that SSH-2 RSA/1024 is selected
 +
* Press 'Generate'
 +
* In the 'Key comment' field, replace the entry starting with 'rsa-key ...' with your_eclipse_committer_id@dev.eclipse.org
 +
* Save the private key to %HOMEDIR%\.ssh\committer.ppk
 +
* Save the text from the box "Public key" into a new file: %HOMEDIR%\.ssh/authorized_keys
  
=== What do I do when I am working on a large task, and have to put it aside to complete a shorter task? ===
+
The last step is necessary because PUTTYGEN has a custom format for the public portion of the key-pair that will not work when uploaded to the Eclipse Foundation's server. You must save the text from the box 'for pasting' - the key is in the same format as generated by <tt>ssh-keygen</tt>
  
=== What is the difference between a git fetch, git pull and git clone? ===
+
<h5>Getting through a firewall</h5>
 +
In your home <tt>~/.ssh/</tt> directory, you must create a <tt>config</tt> file
 +
<source lang="text">
 +
prompt > cd ~/.ssh
 +
prompt > touch config
 +
prompt > chmod 600 config
 +
</source>
 +
The documentation for the <tt>~/.ssh/config</tt> file can be found [http://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=2&ved=0CDUQFjAB&url=http%3A%2F%2Flinux.die.net%2Fman%2F5%2Fssh_config&ei=ETRrT5a5LNGDsgKakfyMBg&usg=AFQjCNE0sSuRCi-RugxZduFvp_AW-bO7gQ&sig2=dolfHcFjjA8V5D2WjtKzQg here]. The particular features to focus upon are:
 +
* the ability to specify a particular identity file, and
 +
* the ability to specify a command to be run whenever we attempt to connect to a specific host:
 +
<pre>
 +
Host git.eclipse.org
 +
Hostname git.eclipse.org
 +
User committer
 +
IdentityFile ~/.ssh/committer.ppk
 +
ProxyCommand /c/windows/connect.exe -H firewall_host:firewall_port %h %p
 +
or
 +
ProxyCommand /usr/local/bin/corkscrew firewall_host firewall_port %h %p
 +
</pre>
 +
The Windows executable <tt>connect.exe</tt> file can be found [http://www.taiyo.co.jp/~gotoh/ssh/connect.exe here]; the <tt>corkscrew</tt> package (which supports many Unix-style operating systems) can be found [http://www.agroman.net/corkscrew here]
  
=== When/how do I create branches? ===
+
=== Cloning the EclipseLink repositories ===
 
+
You should now be able to use SSH to clone the EclipseLink Git repositories
=== After the server branches, how do I get the information to my local repo? ===
+
<source lang="text">
 
+
prompt > git clone ssh://committerid@git.eclipse.org/gitroot/eclipselink/eclipselink.runtime.git
=== What tools do you recommend, what are their strengths and weaknesses?  ===
+
</source>
 
+
=== I've seen some issues with renaming things and how those things behave when other people update. Are there any gotchas? ===
+
 
+
=== What is Git Rebase? When would I use it? ===
+
 
+
=== How do I verify that 'what I push to the repo is actually there'? ===
+

Latest revision as of 01:30, 18 April 2015

EclipseLink Development in Git

This page is for the Git usage portion of the dev process. It does not discuss issues with the build in Git, for more information on that please see: wiki.eclipse.org/EclipseLink/Build/Git .

It is highly recommended to read through the whole great ProGit book before starting working with EclipseLink git.

EclipseLink Git Repositories

The EclipseLink runtime repository is located here:

http://git.eclipse.org/gitroot/eclipselink/eclipselink.runtime.git

Full list of EclipseLink repositories can be found here:

http://git.eclipse.org/c/eclipselink

A useful urls to browse history of the git repo:

  1. EclipseLink Git
  2. FishEye

Accessing the EclipseLink Git repository

Read-only access through HTTP

Read-only access to the EclipseLink Git repository can be achieved through HTTP.

$ git clone http://git.eclipse.org/gitroot/eclipselink/eclipselink.runtime.git

Committer access through SSH

Step 1: Git Committer Identity

When a commit is made in Git, the commit has metadata identifying two things:

  1. the author (name and email): who created the change, and
  2. the committer (name and email): who committed the change to the repository

(of course for many commits the author IS the committer so only the author is identified)

The Eclipse Foundation uses these fields as part of its IP process - only committers to a project can change source stored on a Foundation's server. However, a committer may make changes on behalf of others - this enables collaboration with parties that have not gone through the Eclipse IP due diligence process. This especially is useful if say the third-party just wanted to contribute a few one-of patches: the administrative overhead of the Eclipse IP due diligence process would likely 'scare-off' most contributions (for more information, please see Handling Git Contributions)

First setup your ~/.gitconfig file:

[user]
        # email address linked to my EclipseLink committer id minorman
        email = michael.norman@oracle.com
        name = Mike Norman

NB. Windows often has difficulty with 'dot-files' in its 'home' directory - you may have to create this file from the command-line. In addition, if your 'home' directory is on a UNC fileshare directory, the msysgit Windows-version of git tools may not be able to read or write it. I solved this issue by redefining two Windows environment variables (HOME and HOMEDRIVE):

Envvar.png

Step 2: SSH identity

As mentioned above, most Git servers are set up so that HTTP access is read-only - in order to be able to commit, one must connect to the Eclipse Foundation Git servers over SSH:

Creating an SSH identity

You need to generate an SSH public/private key-pair from the command prompt:

prompt > ssh-keygen -t rsa -C "your_eclipse_committer_id@dev.eclipse.org" -f committerid
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in commiterid
Your public key has been saved in commiterid.pub.
prompt > ls committerid*
commiterid             commiterid.pub

The file ending in .pub is the public portion of the key-pair. SFTP the public key, or send an email message asking 'webmaster@eclipse.org' to place it in the appropriate place in your home directory on the Eclipse Foundation's server. The private portion must be moved to your local home directory ~/.ssh/committer.ppk. Now set permissions on your private key:

prompt > chmod 700 ~/.ssh
prompt > chmod 600 ~/.ssh/committer.ppk

Instead of emailing 'webmaster@eclipse.org' you can upload the key yourself:

sftp dev.eclipse.org
cd /home/data/users/<your_user_name>/.ssh/
put committer.pub
mv committer.pub authorized_keys
chmod 700 authorized_keys
Creating an SSH identify on Windows

PuttyGen is an alternative to "ssh-keygen" for generating a key pair. (In general, ssh-keygen is preferable as the final step with puttygen involves cut/pasting the public key, which is more error prone)

  • run PUTTYGEN.EXE - make sure that SSH-2 RSA/1024 is selected
  • Press 'Generate'
  • In the 'Key comment' field, replace the entry starting with 'rsa-key ...' with your_eclipse_committer_id@dev.eclipse.org
  • Save the private key to %HOMEDIR%\.ssh\committer.ppk
  • Save the text from the box "Public key" into a new file: %HOMEDIR%\.ssh/authorized_keys

The last step is necessary because PUTTYGEN has a custom format for the public portion of the key-pair that will not work when uploaded to the Eclipse Foundation's server. You must save the text from the box 'for pasting' - the key is in the same format as generated by ssh-keygen

Getting through a firewall

In your home ~/.ssh/ directory, you must create a config file

prompt > cd ~/.ssh
prompt > touch config
prompt > chmod 600 config

The documentation for the ~/.ssh/config file can be found here. The particular features to focus upon are:

  • the ability to specify a particular identity file, and
  • the ability to specify a command to be run whenever we attempt to connect to a specific host:
Host git.eclipse.org
	Hostname git.eclipse.org
	User committer
 	IdentityFile ~/.ssh/committer.ppk
	ProxyCommand /c/windows/connect.exe -H firewall_host:firewall_port %h %p
or 
	ProxyCommand /usr/local/bin/corkscrew firewall_host firewall_port %h %p

The Windows executable connect.exe file can be found here; the corkscrew package (which supports many Unix-style operating systems) can be found here

Cloning the EclipseLink repositories

You should now be able to use SSH to clone the EclipseLink Git repositories

prompt > git clone ssh://committerid@git.eclipse.org/gitroot/eclipselink/eclipselink.runtime.git

Back to the top