Git/Migrating to Git

Eclipse projects currently using CVS or SVN may migrate their repository to Git. Here is an outline of the steps:

Talk to your community, project lead

Your project lead(s) needs to endorse the move to Git. Inform your community about the desire to migrate. Keep them informed on the plan and the progress.

Understand the concept of Git repos

Since a Git repo is not the same as a CVS or SVN repo, we assume you understand the Git repository concept. More information can be found on the Git page.

Know the caveats

Git is new at Eclipse.org, and some of our existing tooling may not yet support Git. However, we expect that most of these issues will be resolved in time.

• The Web front-end to Git is not, and will not be hosted on ViewVC. Git is hosted at http://git.eclipse.org/.
• Git may not be fully integrated into the Eclipse build infrastructure.
• Due to our rigorous IP process, the Eclipse.org use-case for a DVCS is different than that of other Open Source organizations. For this reason, an update hook is installed on all Git repositories to ensure a clean IP provenance. See Git#Committing_and_pushing for more information.
  • Please see Handling Git Contributions

Plan and structure your Git space

• Webmaster will create a directory on git.eclipse.org to store your Git repositories. Although Webmaster can create your Git repos for you, you are free to do this yourself.
• Decide on a timeline: webmaster needs exclusive access to your CVS/SVN repo to import it (if that is what is decided). This will disrupt project operations. Choose a timeline to minimize impact.
• Now is a great time to refactor your code structure. Map the current CVS/SVN directories, modules, plugins, etc. to their new home in Git. Typically, one Git repository (.git) is created for each logical grouping of code -- a project, a component, and so on. The trade-off here is that each additional Git repository adds extra overhead to your development process - all Git commands and operations happen at the level of a single Git repository. On the flip side, each repository user will have an entire copy of the repository history, making very large repositories cumbersome to work with for casual contributors.

For instance, the Babel project (ViewCVS) has one CVS repository which contains a server component and a plugin component which, in turn, contains several modules. Here is one example:

   ServerRepo: org.eclipse.babel.server.git
   URL: git://git.eclipse.org/gitroot/babel/org.eclipse.babel.server.git

   Plugin Repo: org.eclipse.babel.build.git
   URL: git://git.eclipse.org/gitroot/babel/org.eclipse.babel.build.git
         will contain directories: org.eclipse.babel.build.ant, o.e.b.b.core, o.e.b.b.ui

   Plugin Repo: org.eclipse.babel.core.git
   URL: git://git.eclipse.org/gitroot/babel/org.eclipse.babel.core.git

   Plugin Repo: org.eclipse.babel.editor.git
   URL: git://git.eclipse.org/gitroot/babel/org.eclipse.babel.editor.git

   Plugin Repo: org.eclipse.babel.runtime.git
   URL: git://git.eclipse.org/gitroot/babel/org.eclipse.babel.runtime.git

Decide what to do with your existing code

You have two options for migrating your existing codebase to Git: archive your repo and start fresh, or import your complete history.

Archive your current CVS or SVN repository

• Webmaster will flag it as read-only.
• Commit the HEAD stream into Git.
• Start with a fresh, clean Git repository while preserving CVS/SVN history in its original state.
• When, and if the CVS and/or SVN service is retired at Eclipse.org, the read-only repositories will be zipped and available for download as an archive.

Import your history into git

Your CVS/SVN repo can be completely migrated into Git. See detailed instructions below.

Open a Bug

Open a bug against Eclipse Foundation > Community > Git requesting the migration. Make sure your project lead is CC'd and add a +1 to the bug. Include detailed plans for your migration:

• migration timeline
• mapping of current code to new Git repos
• your decision regarding existing code (archive or import)
• A description for each of your repositories. The description will be seen in the web view: http://git.eclipse.org/c/

Importing your CVS/SVN history into Git

Importing your repository can be done by a committer, a project lead or by the webmaster. If you're not comfortable with these import steps, please ask us to perform the import in your bug.

Using svn2git on a remote server

These notes are taken from the Github guide "Import from Subversion".

Install svn2git by following the instructions on the github repository: http://github.com/nirvdrum/svn2git

Once it is installed, run a command similar to this one: svn2git svn+ssh://atoulme@dev.eclipse.org/svnroot/stp/org.eclipse.stp.bpmn-modeler --authors ~/users.txt

Make sure to fill the authors in the users.txt file, using this syntax: %svnusername% = %First name% %Last name% %email%

If one is missing, the process will stop and you will have the opportunity to amend the file, and enter the same command to continue.

When you are done creating the git repository locally:

• Edit the .git/description file

It should contain a one-liner description of your repository.

• rsync it to git.eclipse.org:

rsync . atoulme@git.eclipse.org:/gitroot/bpmnmodeler -r

Using svn2git on build.eclipse.org

1. Ask webmaster to create a container if you don't already have one
2. ssh to build.eclipse.org
3. cd to container directory (cd /gitroot/tmf)
4. export GIT_DIR=org.eclipse.osee.git <-- name of the repo to create
5. svn2git -v --exclude _Retired svn://dev.eclipse.org/technology/org.eclipse.osee

Using git-cvsimport

Git cvsimport allows incremental import and tracking of a CVS repo while evaluating git

Warning: The import may be imperfect. Tags and branches may be missing entirely or contain missing / corrupted files. For a correct one-time conversion cvs2git should be preferred (or the import should be verified using a script like: verify-cvs2svn.py)

1. Ask webmaster to create a container if you don't already have one
2. ssh to git.eclipse.org (I found it had to be dev2 - pwebster)
3. cd to container directory (cd /gitroot/tmf)
4. export GIT_DIR=org.eclipse.xpand.git
5. /usr/local/libexec/git-core/git-cvsimport -v -i -p -x -o master -d :local:/home/data/cvs/modeling org.eclipse.m2t/org.eclipse.xpand -C ./
   • Alternative: cvs --git-dir=org.eclipse.xpand.git cvsimport -v -i -p -x -o master -d :local:/home/data/cvs/modeling org.eclipse.m2t/org.eclipse.xpand
   • Note that difficult-to-decipher errors will occur if you add a trailing slash on the CVS path (don't do that).
6. verify the conversion using verify-cvs2svn.py from cvs2git.

Using cvs2git

cvs2git is the git equivalent of cvs2svn. It provides verifiable one-time conversions of a cvs repo. including all (wanted) tags and branches. It doesn't support incremental import.

1. See: http://cvs2svn.tigris.org/cvs2git.html for detailed instructions.

Trunk of cvs2git contains a number of bugfixes and should be preferred to the now old release version.

The CDT team is migrating to git using cvs2git, see: https://bugs.eclipse.org/316208 for more info.

Convert .cvsignore to .gitignore

There are subtle differences in semantics between .cvsignore and .gitignore, so you shouldn't just rename these files when moving to Git. At least prepend a "/" to each line in .gitignore, to ensure a pattern doesn't match in all subfolders.

Good practice is to create a .gitignore directly in the top-level folder of the Git repository and add /*/bin/ or /*/*/bin/ (depending on repo layout). Then, you can remove the bin entry from project-level ignore files (and also remove the ignore file if that was the only entry).

Git Team Provider

The EGit project is responsible for providing a Git Team Provider.

EGit can be installed via the Eclipse Marketplace Client or directly from the project's distribution repository.

Git Resources

• Pro Git Online book
• Git with Eclipse (EGit) Tutorial

Git Task Force

To help with moving to Git, a team of experienced eclipse.org committers lead by Chris Aniszczyk and Dave Carver are monitoring the git-dev mailing list. If you have trouble moving or have any questions, please send an email to this list and these people will help you. These folks will be available for you to help you with the migration, from migrating your repository to setting up your new build.

Migrating Your Project Website

There are a few odd 'gotchas' when migrating project websites: it's just easier to let the Webmaster do it for you. Starting in August, we are looking for projects to volunteer to migrate. Starting in September, we will work our way through all projects and compel them to move.

To request migration of your website, open a bug that blocks bug 324116 (under Community/Website, or add webmaster@eclipse.org to the cc list) and the Webmaster team will add your migration to their busy schedule.