Migration of an existing SVN Project to Git

This page describes the Git migration of an existing SVN project using the Script provided by Andreas Schaller. For simplicity, this HowTo is targeted only at migrating one project for the first time. It describes, what needs to be configured and performed for successful migration.

As a more advanced step, if your project is a regular project, you will also need to update Jenkins. Also you want to eventually rename the project during migration. All these steps necessary around the pure project migration are described here: 15 steps to migrating a project including Jenkins and project renaming.

1. Choosing or creating the corresponding organization in Git

1.1 Organizations in Git

Each Git organization groups a bunch of repositories. Typically for APP projects, an organization is either a bigger project (such as "lsa", "zks", ..) or there is one big organization for all control room applications called "fcc-applications". These organizations group repositories with a common topic, team members, ownerships etc. Please refer to the Git structuring and naming guidelines for more details.

1.2 Standard organization "fcc-applications" for applications

For applications, typically the organization called "fcc-applications" is used and you can skip to chapter 2.

1.3 Creating a new organization

If the organzation - here zks in this example - does not yet exist, you can create it within Gitea. Go to https://git.acc.gsi.de/, log in with your cluster account. Press the "+" sign in the upper right corner to create the organization.

The default visibility is Public, which we want to use for all of our applications and libraries.

(The only exception for the time being is zks itself, since there we deal with personnel data and therefore restrict the visibility to private).

2. Prepare logins and ssh keys

To later upload the project from SVN to Git, we first have to make our public ssh user key known to Git (more detailed information about using ssh keys for connecting to Git can be found here https://help.github.com/en/articles/connecting-to-github-with-ssh).

Warning: Can't find topic Applications.APHowToGitPrepareSshKey Warning: Can't find topic Applications.APHowToGitPrepareSshKey

3. Migrating the project

To migrate an existing SVN project, please make sure, that you do not have any open changes left to commit to SVN.

3.1 Configure Git

Warning: Can't find topic Applications.ApHowToGitConfigure

3.2 Get the migration script

You can get the migration script by cloning the corresponding Git repository with the command line or within Eclipse if you are already familiar with Git. In this case just clone the repository and proceed to the next step to execute the script.

The migration script can also be directly downloaded, which we recommend and describe here, for the case that you have not worked with Git so far.

By convention in APP, the repositories are stored within ~/path_to_eclipse_workspace/repos/git/. Therefore we first switch to this directory or create it, if it is not yet there.

cd ~/path_to_eclipse_workspace/repos/git

or

mkdir -p ~/path_to_eclipse_workspace/repos/git
cd ~/path_to_eclipse_workspace/repos/git

respectively for creating this directory and going there. Use pwd to check, if you are correctly in this directory full_path_to_eclipse_workspace/repos/git/.

Execute

wget https://git.acc.gsi.de/schaller/GitMigrationScript/archive/master.zip
unzip master.zip

to get the repository which contains the needed scripts.

3.3 Executing the migration script

Go to the git repositories directory in your Eclipse workspace (if you executed the above steps, you are already there).

cd ~/path_to_eclipse_workspace/repos/git

Before running the migration script, please check its description and full options here. In the simple case, you can just use:

 ./gitmigrationscript/git_migration.sh --project zks-app-selection --svnGroup personnel-safety --svnPath zks-db/app --organization zks --add-gitignore

Typically used options are:

• --project the name of the SVN project
• --svnGroup the name of the existing SVN repository, e.g. applications (https://www-acc.gsi.de/svn/applications), lsa, personnel-safety, etc.
• --svnPath the path within the SVN repository
• --organization the Git organization name
• --add-gitignore should be there always to get a predefined gitignore file (something similar to .svnIgnore)
• --svnLayout=none this is not needed for the standard case, when your project directory in SVN contains trunk/tag/branches, e.g. zks-app-selection/trunk/ source code. --svnLayout=none is needed, when your project directory does not contain trunk/tag/branches, e.g. the directory looks like zks-app-selection/ source code.
• --gitProject new-project-name if you do not want to keep the same name, but rename the project while migrating it, e.g.

  ./gitmigrationscript/git_migration.sh --project app-ionsrc --svnGroup applications --organization fcc-applications --gitProject ionsource-app --add-gitignore

The output of the script should look as follows:

You should now follow the hints of the script, e.g updating your pom.xml to not use svn anymore.

3.4 View the newly created repositories and their contents

After successfully migrating your projects, you can view them using the dashboard of Gitea.
Here you can browse the newly created repositories.

4. How to move on

4.1 Oooops, we have SVN updates after migrating the project to Git

If by any chance changes have been made to the SVN project after migrating it to Git, there is also a script provided by Andreas that allows migrating SVN updates to Git. Please refer to the Git Migration Script, especially the script called git_svn_update.sh.

WARNING: this can only be done on exactly that repository which was created by the git_migration.sh script. Also it may not work properly if there are also changes on the Git repository itself.

4.2 Prevent changes to SVN

After migrating the project to Git, it makes sense not to allow updates on the obsolete SVN project any more. However, the whole SVN repository can be set to read-only (and will be latest in April 2020), but not the single project. We recommend moving your SVN project within SVN to a direcotry called e.g. "moved_to_git_svn_not_available_anymore" (like in the lsa SVN repository). Like this, people that have still checked out the project from SVN will get errors and cannot commit changes any more that easily. After all projects of an SVN repository have been successfully migrated to Git, please contact Christoph Handel to finally set the repository to read-only.

4.3 Git, here we come

When your project is successfully migrated to Git, please remove the old SVN project from your Eclipse (right mouse click -> delete -> "delete project contents on disk"). Then get it again by cloning the corresponding repository from Git. How this is done is described in the Git in Eclipse for Beginners.

When you get your Git project for the first time, please make sure to update your pom.xml, i.e. please change at least the <code><scm></code>-tags to point to Git as described in the 15 steps to migrating a project including Jenkins and project renaming.

-- JuttaFitzek - 24 Jul 2019