From bbd627c54852f62fe45d00b69857106346b8391d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 16 Aug 2017 14:05:13 +0300 Subject: Move workflow/importing/ to user/project/import/ --- app/views/shared/_import_form.html.haml | 2 +- doc/README.md | 2 +- doc/user/project/import/bitbucket.md | 62 +++++++ doc/user/project/import/fogbugz.md | 28 ++++ doc/user/project/import/gitea.md | 77 +++++++++ doc/user/project/import/github.md | 122 ++++++++++++++ doc/user/project/import/gitlab_com.md | 20 +++ .../import/img/bitbucket_import_grant_access.png | Bin 0 -> 7248 bytes .../import/img/bitbucket_import_new_project.png | Bin 0 -> 1316 bytes .../import/img/bitbucket_import_select_project.png | Bin 0 -> 8688 bytes .../project/import/img/fogbugz_import_finished.png | Bin 0 -> 17744 bytes .../project/import/img/fogbugz_import_login.png | Bin 0 -> 13751 bytes .../import/img/fogbugz_import_select_fogbogz.png | Bin 0 -> 12289 bytes .../import/img/fogbugz_import_select_project.png | Bin 0 -> 20905 bytes .../project/import/img/fogbugz_import_user_map.png | Bin 0 -> 51238 bytes doc/user/project/import/img/gitlab_importer.png | Bin 0 -> 12864 bytes .../project/import/img/gitlab_new_project_page.png | Bin 0 -> 21251 bytes .../img/import_projects_from_gitea_new_import.png | Bin 0 -> 15561 bytes .../img/import_projects_from_github_importer.png | Bin 0 -> 17953 bytes ...ort_projects_from_github_select_auth_method.png | Bin 0 -> 17612 bytes .../img/import_projects_from_new_project_page.png | Bin 0 -> 36821 bytes doc/user/project/import/index.md | 20 +++ doc/user/project/import/svn.md | 183 ++++++++++++++++++++ doc/user/project/index.md | 10 +- doc/workflow/importing/README.md | 18 +- .../fogbugz_importer/fogbugz_import_finished.png | Bin 17744 -> 0 bytes .../fogbugz_importer/fogbugz_import_login.png | Bin 13751 -> 0 bytes .../fogbugz_import_select_fogbogz.png | Bin 12289 -> 0 bytes .../fogbugz_import_select_project.png | Bin 20905 -> 0 bytes .../fogbugz_importer/fogbugz_import_user_map.png | Bin 51238 -> 0 bytes .../importing/gitlab_importer/importer.png | Bin 12864 -> 0 bytes .../importing/gitlab_importer/new_project_page.png | Bin 21251 -> 0 bytes .../img/bitbucket_import_grant_access.png | Bin 7248 -> 0 bytes .../importing/img/bitbucket_import_new_project.png | Bin 1316 -> 0 bytes .../img/bitbucket_import_select_project.png | Bin 8688 -> 0 bytes .../img/import_projects_from_gitea_new_import.png | Bin 15561 -> 0 bytes .../img/import_projects_from_github_importer.png | Bin 17953 -> 0 bytes ...ort_projects_from_github_select_auth_method.png | Bin 17612 -> 0 bytes .../img/import_projects_from_new_project_page.png | Bin 36821 -> 0 bytes .../importing/import_projects_from_bitbucket.md | 63 +------ .../importing/import_projects_from_fogbugz.md | 30 +--- .../importing/import_projects_from_gitea.md | 78 +-------- .../importing/import_projects_from_github.md | 123 +------------- .../importing/import_projects_from_gitlab_com.md | 22 +-- doc/workflow/importing/migrating_from_svn.md | 184 +-------------------- 45 files changed, 526 insertions(+), 518 deletions(-) create mode 100644 doc/user/project/import/bitbucket.md create mode 100644 doc/user/project/import/fogbugz.md create mode 100644 doc/user/project/import/gitea.md create mode 100644 doc/user/project/import/github.md create mode 100644 doc/user/project/import/gitlab_com.md create mode 100644 doc/user/project/import/img/bitbucket_import_grant_access.png create mode 100644 doc/user/project/import/img/bitbucket_import_new_project.png create mode 100644 doc/user/project/import/img/bitbucket_import_select_project.png create mode 100644 doc/user/project/import/img/fogbugz_import_finished.png create mode 100644 doc/user/project/import/img/fogbugz_import_login.png create mode 100644 doc/user/project/import/img/fogbugz_import_select_fogbogz.png create mode 100644 doc/user/project/import/img/fogbugz_import_select_project.png create mode 100644 doc/user/project/import/img/fogbugz_import_user_map.png create mode 100644 doc/user/project/import/img/gitlab_importer.png create mode 100644 doc/user/project/import/img/gitlab_new_project_page.png create mode 100644 doc/user/project/import/img/import_projects_from_gitea_new_import.png create mode 100644 doc/user/project/import/img/import_projects_from_github_importer.png create mode 100644 doc/user/project/import/img/import_projects_from_github_select_auth_method.png create mode 100644 doc/user/project/import/img/import_projects_from_new_project_page.png create mode 100644 doc/user/project/import/index.md create mode 100644 doc/user/project/import/svn.md delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png delete mode 100644 doc/workflow/importing/gitlab_importer/importer.png delete mode 100644 doc/workflow/importing/gitlab_importer/new_project_page.png delete mode 100644 doc/workflow/importing/img/bitbucket_import_grant_access.png delete mode 100644 doc/workflow/importing/img/bitbucket_import_new_project.png delete mode 100644 doc/workflow/importing/img/bitbucket_import_select_project.png delete mode 100644 doc/workflow/importing/img/import_projects_from_gitea_new_import.png delete mode 100644 doc/workflow/importing/img/import_projects_from_github_importer.png delete mode 100644 doc/workflow/importing/img/import_projects_from_github_select_auth_method.png delete mode 100644 doc/workflow/importing/img/import_projects_from_new_project_page.png diff --git a/app/views/shared/_import_form.html.haml b/app/views/shared/_import_form.html.haml index 873179339dc..233d8c95eda 100644 --- a/app/views/shared/_import_form.html.haml +++ b/app/views/shared/_import_form.html.haml @@ -13,4 +13,4 @@ %li The import will time out after 15 minutes. For repositories that take longer, use a clone/push combination. %li - To migrate an SVN repository, check out #{link_to "this document", help_page_path('workflow/importing/migrating_from_svn')}. + To migrate an SVN repository, check out #{link_to "this document", help_page_path('user/project/import/svn')}. diff --git a/doc/README.md b/doc/README.md index 547541c4876..267487520cd 100644 --- a/doc/README.md +++ b/doc/README.md @@ -102,7 +102,7 @@ Manage your [repositories](user/project/repository/index.md) from the UI (user i ### Migrate and import your projects from other platforms -- [Importing to GitLab](workflow/importing/README.md): Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. +- [Importing to GitLab](user/project/import/index.md): Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. - [Migrating from SVN](workflow/importing/migrating_from_svn.md): Convert a SVN repository to Git and GitLab. ### Continuous Integration, Delivery, and Deployment diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md new file mode 100644 index 00000000000..b22c7db0047 --- /dev/null +++ b/doc/user/project/import/bitbucket.md @@ -0,0 +1,62 @@ +# Import your project from Bitbucket to GitLab + +Import your projects from Bitbucket to GitLab with minimal effort. + +## Overview + +>**Note:** +The [Bitbucket integration][bb-import] must be first enabled in order to be +able to import your projects from Bitbucket. Ask your GitLab administrator +to enable this if not already. + +- At its current state, the Bitbucket importer can import: + - the repository description (GitLab 7.7+) + - the Git repository data (GitLab 7.7+) + - the issues (GitLab 7.7+) + - the issue comments (GitLab 8.15+) + - the pull requests (GitLab 8.4+) + - the pull request comments (GitLab 8.15+) + - the milestones (GitLab 8.15+) + - the wiki (GitLab 8.15+) +- References to pull requests and issues are preserved (GitLab 8.7+) +- Repository public access is retained. If a repository is private in Bitbucket + it will be created as private in GitLab as well. + + +## How it works + +When issues/pull requests are being imported, the Bitbucket importer tries to find +the Bitbucket author/assignee in GitLab's database using the Bitbucket ID. For this +to work, the Bitbucket author/assignee should have signed in beforehand in GitLab +and **associated their Bitbucket account**. If the user is not +found in GitLab's database, the project creator (most of the times the current +user that started the import process) is set as the author, but a reference on +the issue about the original Bitbucket author is kept. + +The importer will create any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository will be imported under the user's +namespace that started the import process. + +## Importing your Bitbucket repositories + +1. Sign in to GitLab and go to your dashboard. +1. Click on **New project**. + + ![New project in GitLab](img/bitbucket_import_new_project.png) + +1. Click on the "Bitbucket" button + + ![Bitbucket](img/import_projects_from_new_project_page.png) + +1. Grant GitLab access to your Bitbucket account + + ![Grant access](img/bitbucket_import_grant_access.png) + +1. Click on the projects that you'd like to import or **Import all projects**. + You can also select the namespace under which each project will be + imported. + + ![Import projects](img/bitbucket_import_select_project.png) + +[bb-import]: ../../../integration/bitbucket.md +[social sign-in]: ../../profile/account/social_sign_in.md diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md new file mode 100644 index 00000000000..17222c53675 --- /dev/null +++ b/doc/user/project/import/fogbugz.md @@ -0,0 +1,28 @@ +# Import your project from FogBugz to GitLab + +It only takes a few simple steps to import your project from FogBugz. +The importer will import all of your cases and comments with original case +numbers and timestamps. You will also have the opportunity to map FogBugz +users to GitLab users. + +1. From your GitLab dashboard click 'New project' +1. Click on the 'FogBugz' button + + ![FogBugz](img/fogbugz_import_select_fogbogz.png) + +1. Enter your FogBugz URL, email address, and password. + + ![Login](img/fogbugz_import_login.png) + +1. Create mapping from FogBugz users to GitLab users. + + ![User Map](img/fogbugz_import_user_map.png) + +1. Select the projects you wish to import by clicking the Import buttons + + ![Import Project](img/fogbugz_import_select_project.png) + +1. Once the import has finished click the link to take you to the project +dashboard. Follow the directions to push your existing repository. + + ![Finished](img/fogbugz_import_finished.png) diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md new file mode 100644 index 00000000000..f5746a0fb31 --- /dev/null +++ b/doc/user/project/import/gitea.md @@ -0,0 +1,77 @@ +# Import your project from Gitea to GitLab + +Import your projects from Gitea to GitLab with minimal effort. + +## Overview + +>**Note:** +This requires Gitea `v1.0.0` or newer. + +- At its current state, Gitea importer can import: + - the repository description (GitLab 8.15+) + - the Git repository data (GitLab 8.15+) + - the issues (GitLab 8.15+) + - the pull requests (GitLab 8.15+) + - the milestones (GitLab 8.15+) + - the labels (GitLab 8.15+) +- Repository public access is retained. If a repository is private in Gitea + it will be created as private in GitLab as well. + +## How it works + +Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped +to users in your GitLab's instance. This means that the project creator (most of +the times the current user that started the import process) is set as the author, +but a reference on the issue about the original Gitea author is kept. + +The importer will create any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository will be imported under the user's +namespace that started the import process. + +## Importing your Gitea repositories + +The importer page is visible when you create a new project. + +![New project page on GitLab](img/import_projects_from_new_project_page.png) + +Click on the **Gitea** link and the import authorization process will start. + +![New Gitea project import](img/import_projects_from_gitea_new_import.png) + +### Authorize access to your repositories using a personal access token + +With this method, you will perform a one-off authorization with Gitea to grant +GitLab access your repositories: + +1. Go to (replace + `you-gitea-instance` with the host of your Gitea instance). +1. Click **Generate New Token**. +1. Enter a token description. +1. Click **Generate Token**. +1. Copy the token hash. +1. Go back to GitLab and provide the token to the Gitea importer. +1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads + your repositories' information. Once done, you'll be taken to the importer + page to select the repositories to import. + +### Select which repositories to import + +After you've authorized access to your Gitea repositories, you will be +redirected to the Gitea importer page. + +From there, you can see the import statuses of your Gitea repositories. + +- Those that are being imported will show a _started_ status, +- those already successfully imported will be green with a _done_ status, +- whereas those that are not yet imported will have an **Import** button on the + right side of the table. + +If you want, you can import all your Gitea projects in one go by hitting +**Import all projects** in the upper left corner. + +![Gitea importer page](img/import_projects_from_github_importer.png) + +--- + +You can also choose a different name for the project and a different namespace, +if you have the privileges to do so. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md new file mode 100644 index 00000000000..016f98966e3 --- /dev/null +++ b/doc/user/project/import/github.md @@ -0,0 +1,122 @@ +# Import your project from GitHub to GitLab + +Import your projects from GitHub to GitLab with minimal effort. + +## Overview + +>**Note:** +If you are an administrator you can enable the [GitHub integration][gh-import] +in your GitLab instance sitewide. This configuration is optional, users will +still be able to import their GitHub repositories with a +[personal access token][gh-token]. + +>**Note:** +Administrators of a GitLab instance (Community or Enterprise Edition) can also +use the [GitHub rake task][gh-rake] to import projects from GitHub without the +constrains of a Sidekiq worker. + +- At its current state, GitHub importer can import: + - the repository description (GitLab 7.7+) + - the Git repository data (GitLab 7.7+) + - the issues (GitLab 7.7+) + - the pull requests (GitLab 8.4+) + - the wiki pages (GitLab 8.4+) + - the milestones (GitLab 8.7+) + - the labels (GitLab 8.7+) + - the release note descriptions (GitLab 8.12+) +- References to pull requests and issues are preserved (GitLab 8.7+) +- Repository public access is retained. If a repository is private in GitHub + it will be created as private in GitLab as well. + +## How it works + +When issues/pull requests are being imported, the GitHub importer tries to find +the GitHub author/assignee in GitLab's database using the GitHub ID. For this +to work, the GitHub author/assignee should have signed in beforehand in GitLab +and **associated their GitHub account**. If the user is not +found in GitLab's database, the project creator (most of the times the current +user that started the import process) is set as the author, but a reference on +the issue about the original GitHub author is kept. + +The importer will create any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository will be imported under the user's +namespace that started the import process. + +## Importing your GitHub repositories + +The importer page is visible when you create a new project. + +![New project page on GitLab](img/import_projects_from_new_project_page.png) + +Click on the **GitHub** link and the import authorization process will start. +There are two ways to authorize access to your GitHub repositories: + +1. [Using the GitHub integration][gh-integration] (if it's enabled by your + GitLab administrator). This is the preferred way as it's possible to + preserve the GitHub authors/assignees. Read more in the [How it works](#how-it-works) + section. +1. [Using a personal access token][gh-token] provided by GitHub. + +![Select authentication method](img/import_projects_from_github_select_auth_method.png) + +### Authorize access to your repositories using the GitHub integration + +If the [GitHub integration][gh-import] is enabled by your GitLab administrator, +you can use it instead of the personal access token. + +1. First you may want to connect your GitHub account to GitLab in order for + the username mapping to be correct. +1. Once you connect GitHub, click the **List your GitHub repositories** button + and you will be redirected to GitHub for permission to access your projects. +1. After accepting, you'll be automatically redirected to the importer. + +You can now go on and [select which repositories to import](#select-which-repositories-to-import). + +### Authorize access to your repositories using a personal access token + +>**Note:** +For a proper author/assignee mapping for issues and pull requests, the +[GitHub integration][gh-integration] should be used instead of the +[personal access token][gh-token]. If the GitHub integration is enabled by your +GitLab administrator, it should be the preferred method to import your repositories. +Read more in the [How it works](#how-it-works) section. + +If you are not using the GitHub integration, you can still perform a one-off +authorization with GitHub to grant GitLab access your repositories: + +1. Go to . +1. Enter a token description. +1. Check the `repo` scope. +1. Click **Generate token**. +1. Copy the token hash. +1. Go back to GitLab and provide the token to the GitHub importer. +1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads + your repositories' information. Once done, you'll be taken to the importer + page to select the repositories to import. + +### Select which repositories to import + +After you've authorized access to your GitHub repositories, you will be +redirected to the GitHub importer page. + +From there, you can see the import statuses of your GitHub repositories. + +- Those that are being imported will show a _started_ status, +- those already successfully imported will be green with a _done_ status, +- whereas those that are not yet imported will have an **Import** button on the + right side of the table. + +If you want, you can import all your GitHub projects in one go by hitting +**Import all projects** in the upper left corner. + +![GitHub importer page](img/import_projects_from_github_importer.png) + +--- + +You can also choose a different name for the project and a different namespace, +if you have the privileges to do so. + +[gh-import]: ../../../integration/github.md "GitHub integration" +[gh-rake]: ../../../administration/raketasks/github_import.md "GitHub rake task" +[gh-integration]: #authorize-access-to-your-repositories-using-the-github-integration +[gh-token]: #authorize-access-to-your-repositories-using-a-personal-access-token diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md new file mode 100644 index 00000000000..3b37da67a5b --- /dev/null +++ b/doc/user/project/import/gitlab_com.md @@ -0,0 +1,20 @@ +# Project importing from GitLab.com to your private GitLab instance + +You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if +GitLab support is enabled on your GitLab instance. +You can read more about GitLab support [here](http://docs.gitlab.com/ce/integration/gitlab.html) +To get to the importer page you need to go to "New project" page. + +>**Note:** +If you are interested in importing Wiki and Merge Request data to your new +instance, you'll need to follow the instructions for [project export](../settings/import_export.md) + +![New project page](img/gitlab_new_project_page.png) + +Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com +for permission to access your projects. After accepting, you'll be automatically redirected to the importer. + +![Importer page](img/gitlab_importer.png) + +To import a project, you can simple click "Import". The importer will import your repository and issues. +Once the importer is done, a new GitLab project will be created with your imported data. diff --git a/doc/user/project/import/img/bitbucket_import_grant_access.png b/doc/user/project/import/img/bitbucket_import_grant_access.png new file mode 100644 index 00000000000..429904e621d Binary files /dev/null and b/doc/user/project/import/img/bitbucket_import_grant_access.png differ diff --git a/doc/user/project/import/img/bitbucket_import_new_project.png b/doc/user/project/import/img/bitbucket_import_new_project.png new file mode 100644 index 00000000000..8ed528c2f09 Binary files /dev/null and b/doc/user/project/import/img/bitbucket_import_new_project.png differ diff --git a/doc/user/project/import/img/bitbucket_import_select_project.png b/doc/user/project/import/img/bitbucket_import_select_project.png new file mode 100644 index 00000000000..1bca6166ec8 Binary files /dev/null and b/doc/user/project/import/img/bitbucket_import_select_project.png differ diff --git a/doc/user/project/import/img/fogbugz_import_finished.png b/doc/user/project/import/img/fogbugz_import_finished.png new file mode 100644 index 00000000000..62c5c86c9b3 Binary files /dev/null and b/doc/user/project/import/img/fogbugz_import_finished.png differ diff --git a/doc/user/project/import/img/fogbugz_import_login.png b/doc/user/project/import/img/fogbugz_import_login.png new file mode 100644 index 00000000000..96bce70b74d Binary files /dev/null and b/doc/user/project/import/img/fogbugz_import_login.png differ diff --git a/doc/user/project/import/img/fogbugz_import_select_fogbogz.png b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png new file mode 100644 index 00000000000..b26c652e382 Binary files /dev/null and b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png differ diff --git a/doc/user/project/import/img/fogbugz_import_select_project.png b/doc/user/project/import/img/fogbugz_import_select_project.png new file mode 100644 index 00000000000..ccc82f9d4cd Binary files /dev/null and b/doc/user/project/import/img/fogbugz_import_select_project.png differ diff --git a/doc/user/project/import/img/fogbugz_import_user_map.png b/doc/user/project/import/img/fogbugz_import_user_map.png new file mode 100644 index 00000000000..28ff55a8d89 Binary files /dev/null and b/doc/user/project/import/img/fogbugz_import_user_map.png differ diff --git a/doc/user/project/import/img/gitlab_importer.png b/doc/user/project/import/img/gitlab_importer.png new file mode 100644 index 00000000000..27d42eb492e Binary files /dev/null and b/doc/user/project/import/img/gitlab_importer.png differ diff --git a/doc/user/project/import/img/gitlab_new_project_page.png b/doc/user/project/import/img/gitlab_new_project_page.png new file mode 100644 index 00000000000..c673724f436 Binary files /dev/null and b/doc/user/project/import/img/gitlab_new_project_page.png differ diff --git a/doc/user/project/import/img/import_projects_from_gitea_new_import.png b/doc/user/project/import/img/import_projects_from_gitea_new_import.png new file mode 100644 index 00000000000..a3f603cbd0a Binary files /dev/null and b/doc/user/project/import/img/import_projects_from_gitea_new_import.png differ diff --git a/doc/user/project/import/img/import_projects_from_github_importer.png b/doc/user/project/import/img/import_projects_from_github_importer.png new file mode 100644 index 00000000000..d8effaf6075 Binary files /dev/null and b/doc/user/project/import/img/import_projects_from_github_importer.png differ diff --git a/doc/user/project/import/img/import_projects_from_github_select_auth_method.png b/doc/user/project/import/img/import_projects_from_github_select_auth_method.png new file mode 100644 index 00000000000..1ccb38a815e Binary files /dev/null and b/doc/user/project/import/img/import_projects_from_github_select_auth_method.png differ diff --git a/doc/user/project/import/img/import_projects_from_new_project_page.png b/doc/user/project/import/img/import_projects_from_new_project_page.png new file mode 100644 index 00000000000..97ca30b2087 Binary files /dev/null and b/doc/user/project/import/img/import_projects_from_new_project_page.png differ diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md new file mode 100644 index 00000000000..06e8c81ef06 --- /dev/null +++ b/doc/user/project/import/index.md @@ -0,0 +1,20 @@ +# Migrating projects to a GitLab instance + +1. [From Bitbucket.org](bitbucket.md) +1. [From GitHub.com of GitHub Enterprise](github.md) +1. [From GitLab.com](gitlab_com.md) +1. [From FogBugz](fogbugz.md) +1. [From Gitea](gitea.md) +1. [From SVN](svn.md) + +In addition to the specific migration documentation above, you can import any +Git repository via HTTP from the New Project page. Be aware that if the +repository is too large the import can timeout. + +## Migrating from self-hosted GitLab to GitLab.com + +You can copy your repos by changing the remote and pushing to the new server, +but issues and merge requests can't be imported. + +If you want to retain all metadata like issues and merge requests, you can use +the [import/export feature](../settings/import_export.md). diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md new file mode 100644 index 00000000000..7a3628a39d7 --- /dev/null +++ b/doc/user/project/import/svn.md @@ -0,0 +1,183 @@ +# Migrating from SVN to GitLab + +Subversion (SVN) is a central version control system (VCS) while +Git is a distributed version control system. There are some major differences +between the two, for more information consult your favorite search engine. + +## Overview + +There are two approaches to SVN to Git migration: + +1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: + - Makes the GitLab repository to mirror the SVN project. + - Git and SVN repositories are kept in sync; you can use either one. + - Smoothens the migration process and allows to manage migration risks. + +1. [Cut over migration](#cut-over-migration-with-svn2git) which: + - Translates and imports the existing data and history from SVN to Git. + - Is a fire and forget approach, good for smaller teams. + +## Smooth migration with a Git/SVN mirror using SubGit + +[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git +migration. It creates a writable Git mirror of a local or remote Subversion +repository and that way you can use both Subversion and Git as long as you like. +It requires access to your GitLab server as it talks with the Git repositories +directly in a filesystem level. + +### SubGit prerequisites + +1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can + follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). +1. Download SubGit from https://subgit.com/download/. +1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` + command will be available at `/opt/subgit-VERSION/bin/subgit`. + +### SubGit configuration + +The first step to mirror you SVN repository in GitLab is to create a new empty +project which will be used as a mirror. For Omnibus installations the path to +the repository will be located at +`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For +installations from source, the default repository directory will be +`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a +variable: + +``` +GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git +``` + +SubGit will keep this repository in sync with a remote SVN project. For +convenience, assign your remote SVN project URL to a variable: + +``` +SVN_PROJECT_URL=http://svn.company.com/repos/project +``` + +Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following +`subgit` command is ran on behalf of the same user that keeps ownership of +GitLab Git repositories (by default `git`): + +``` +subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH +``` + +Adjust authors and branches mappings, if necessary. Open with your favorite +text editor: + +``` +edit $GIT_REPO_PATH/subgit/authors.txt +edit $GIT_REPO_PATH/subgit/config +``` + +For more information regarding the SubGit configuration options, refer to +[SubGit's documentation](https://subgit.com/documentation.html) website. + +### Initial translation + +Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the +initial translation of existing SVN revisions into the Git repository: + +``` +subgit install $GIT_REPO_PATH +``` + +After the initial translation is completed, the Git repository and the SVN +project will be kept in sync by `subgit` - new Git commits will be translated to +SVN revisions and new SVN revisions will be translated to Git commits. Mirror +works transparently and does not require any special commands. + +If you would prefer to perform one-time cut over migration with `subgit`, use +the `import` command instead of `install`: + +``` +subgit import $GIT_REPO_PATH +``` + +### SubGit licensing + +Running SubGit in a mirror mode requires a +[registration](https://subgit.com/pricing.html). Registration is free for open +source, academic and startup projects. + +We're currently working on deeper GitLab/SubGit integration. You may track our +progress at [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/990). + +### SubGit support + +For any questions related to SVN to GitLab migration with SubGit, you can +contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com). + +## Cut over migration with svn2git + +If you are currently using an SVN repository, you can migrate the repository +to Git and GitLab. We recommend a hard cut over - run the migration command once +and then have all developers start using the new GitLab repository immediately. +Otherwise, it's hard to keep changing in sync in both directions. The conversion +process should be run on a local workstation. + +Install `svn2git`. On all systems you can install as a Ruby gem if you already +have Ruby and Git installed. + +```bash +sudo gem install svn2git +``` + +On Debian-based Linux distributions you can install the native packages: + +```bash +sudo apt-get install git-core git-svn ruby +``` + +Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. +If you choose not to create the authors file then commits will not be attributed +to the correct GitLab user. Some users may not consider this a big issue while +others will want to ensure they complete this step. If you choose to map authors +you will be required to map every author that is present on changes in the SVN +repository. If you don't, the conversion will fail and you will have to update +the author file accordingly. The following command will search through the +repository and output a list of authors. + +```bash +svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq +``` + +Use the output from the last command to construct the authors file. +Create a file called `authors.txt` and add one mapping per line. + +``` +janedoe = Jane Doe +johndoe = John Doe +``` + +If your SVN repository is in the standard format (trunk, branches, tags, +not nested) the conversion is simple. For a non-standard repository see +[svn2git documentation](https://github.com/nirvdrum/svn2git). The following +command will checkout the repository and do the conversion in the current +working directory. Be sure to create a new directory for each repository before +running the `svn2git` command. The conversion process will take some time. + +```bash +svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt +``` + +If your SVN repository requires a username and password add the +`--username ` and `--password /.git +git push --all origin +git push --tags origin +``` + +## Contribute to this guide +We welcome all contributions that would expand this guide with instructions on +how to migrate from SVN and other version control systems. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 0dd0faf35e9..ba6ac2797b3 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -90,11 +90,11 @@ from your fork to the upstream project ## Import or export a project -- Import a project from: - - [GitHub to GitLab](../../workflow/importing/import_projects_from_github.md) - - [BitBucket to GitLab](../../workflow/importing/import_projects_from_bitbucket.md) - - [Gitea to GitLab](../../workflow/importing/import_projects_from_gitea.md) - - [FogBugz to GitLab](../../workflow/importing/import_projects_from_fogbugz.md) +- [Import a project](import/index.md) from: + - [GitHub to GitLab](import/github.md) + - [BitBucket to GitLab](import/bitbucket.md) + - [Gitea to GitLab](import/gitea.md) + - [FogBugz to GitLab](import/fogbugz.md) - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) diff --git a/doc/workflow/importing/README.md b/doc/workflow/importing/README.md index 2d91bee0e94..f753708ad89 100644 --- a/doc/workflow/importing/README.md +++ b/doc/workflow/importing/README.md @@ -1,17 +1 @@ -# Migrating projects to a GitLab instance - -1. [Bitbucket](import_projects_from_bitbucket.md) -1. [GitHub](import_projects_from_github.md) -1. [GitLab.com](import_projects_from_gitlab_com.md) -1. [FogBugz](import_projects_from_fogbugz.md) -1. [Gitea](import_projects_from_gitea.md) -1. [SVN](migrating_from_svn.md) - -In addition to the specific migration documentation above, you can import any -Git repository via HTTP from the New Project page. Be aware that if the -repository is too large the import can timeout. - -### Migrating from self-hosted GitLab to GitLab.com - -You can copy your repos by changing the remote and pushing to the new server; -but issues and merge requests can't be imported. +This document was moved to a [new location](../../user/project/import/index.md). diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png deleted file mode 100644 index 62c5c86c9b3..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png deleted file mode 100644 index 96bce70b74d..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png deleted file mode 100644 index b26c652e382..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png deleted file mode 100644 index ccc82f9d4cd..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png deleted file mode 100644 index 28ff55a8d89..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png and /dev/null differ diff --git a/doc/workflow/importing/gitlab_importer/importer.png b/doc/workflow/importing/gitlab_importer/importer.png deleted file mode 100644 index 27d42eb492e..00000000000 Binary files a/doc/workflow/importing/gitlab_importer/importer.png and /dev/null differ diff --git a/doc/workflow/importing/gitlab_importer/new_project_page.png b/doc/workflow/importing/gitlab_importer/new_project_page.png deleted file mode 100644 index c673724f436..00000000000 Binary files a/doc/workflow/importing/gitlab_importer/new_project_page.png and /dev/null differ diff --git a/doc/workflow/importing/img/bitbucket_import_grant_access.png b/doc/workflow/importing/img/bitbucket_import_grant_access.png deleted file mode 100644 index 429904e621d..00000000000 Binary files a/doc/workflow/importing/img/bitbucket_import_grant_access.png and /dev/null differ diff --git a/doc/workflow/importing/img/bitbucket_import_new_project.png b/doc/workflow/importing/img/bitbucket_import_new_project.png deleted file mode 100644 index 8ed528c2f09..00000000000 Binary files a/doc/workflow/importing/img/bitbucket_import_new_project.png and /dev/null differ diff --git a/doc/workflow/importing/img/bitbucket_import_select_project.png b/doc/workflow/importing/img/bitbucket_import_select_project.png deleted file mode 100644 index 1bca6166ec8..00000000000 Binary files a/doc/workflow/importing/img/bitbucket_import_select_project.png and /dev/null differ diff --git a/doc/workflow/importing/img/import_projects_from_gitea_new_import.png b/doc/workflow/importing/img/import_projects_from_gitea_new_import.png deleted file mode 100644 index a3f603cbd0a..00000000000 Binary files a/doc/workflow/importing/img/import_projects_from_gitea_new_import.png and /dev/null differ diff --git a/doc/workflow/importing/img/import_projects_from_github_importer.png b/doc/workflow/importing/img/import_projects_from_github_importer.png deleted file mode 100644 index d8effaf6075..00000000000 Binary files a/doc/workflow/importing/img/import_projects_from_github_importer.png and /dev/null differ diff --git a/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png b/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png deleted file mode 100644 index 1ccb38a815e..00000000000 Binary files a/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png and /dev/null differ diff --git a/doc/workflow/importing/img/import_projects_from_new_project_page.png b/doc/workflow/importing/img/import_projects_from_new_project_page.png deleted file mode 100644 index 97ca30b2087..00000000000 Binary files a/doc/workflow/importing/img/import_projects_from_new_project_page.png and /dev/null differ diff --git a/doc/workflow/importing/import_projects_from_bitbucket.md b/doc/workflow/importing/import_projects_from_bitbucket.md index f3c636ed1d5..248c3990372 100644 --- a/doc/workflow/importing/import_projects_from_bitbucket.md +++ b/doc/workflow/importing/import_projects_from_bitbucket.md @@ -1,62 +1 @@ -# Import your project from Bitbucket to GitLab - -Import your projects from Bitbucket to GitLab with minimal effort. - -## Overview - ->**Note:** -The [Bitbucket integration][bb-import] must be first enabled in order to be -able to import your projects from Bitbucket. Ask your GitLab administrator -to enable this if not already. - -- At its current state, the Bitbucket importer can import: - - the repository description (GitLab 7.7+) - - the Git repository data (GitLab 7.7+) - - the issues (GitLab 7.7+) - - the issue comments (GitLab 8.15+) - - the pull requests (GitLab 8.4+) - - the pull request comments (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the wiki (GitLab 8.15+) -- References to pull requests and issues are preserved (GitLab 8.7+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. - - -## How it works - -When issues/pull requests are being imported, the Bitbucket importer tries to find -the Bitbucket author/assignee in GitLab's database using the Bitbucket ID. For this -to work, the Bitbucket author/assignee should have signed in beforehand in GitLab -and **associated their Bitbucket account**. If the user is not -found in GitLab's database, the project creator (most of the times the current -user that started the import process) is set as the author, but a reference on -the issue about the original Bitbucket author is kept. - -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's -namespace that started the import process. - -## Importing your Bitbucket repositories - -1. Sign in to GitLab and go to your dashboard. -1. Click on **New project**. - - ![New project in GitLab](img/bitbucket_import_new_project.png) - -1. Click on the "Bitbucket" button - - ![Bitbucket](img/import_projects_from_new_project_page.png) - -1. Grant GitLab access to your Bitbucket account - - ![Grant access](img/bitbucket_import_grant_access.png) - -1. Click on the projects that you'd like to import or **Import all projects**. - You can also select the namespace under which each project will be - imported. - - ![Import projects](img/bitbucket_import_select_project.png) - -[bb-import]: ../../integration/bitbucket.md -[social sign-in]: ../../user/profile/account/social_sign_in.md +This document was moved to a [new location](../../user/project/import/bitbucket.md). diff --git a/doc/workflow/importing/import_projects_from_fogbugz.md b/doc/workflow/importing/import_projects_from_fogbugz.md index 71af0f9ea44..050746e2b4d 100644 --- a/doc/workflow/importing/import_projects_from_fogbugz.md +++ b/doc/workflow/importing/import_projects_from_fogbugz.md @@ -1,29 +1 @@ -# Import your project from FogBugz to GitLab - -It only takes a few simple steps to import your project from FogBugz. -The importer will import all of your cases and comments with original case -numbers and timestamps. You will also have the opportunity to map FogBugz -users to GitLab users. - -* From your GitLab dashboard click 'New project' - -* Click on the 'FogBugz' button - -![FogBugz](fogbugz_importer/fogbugz_import_select_fogbogz.png) - -* Enter your FogBugz URL, email address, and password. - -![Login](fogbugz_importer/fogbugz_import_login.png) - -* Create mapping from FogBugz users to GitLab users. - -![User Map](fogbugz_importer/fogbugz_import_user_map.png) - -* Select the projects you wish to import by clicking the Import buttons - -![Import Project](fogbugz_importer/fogbugz_import_select_project.png) - -* Once the import has finished click the link to take you to the project -dashboard. Follow the directions to push your existing repository. - -![Finished](fogbugz_importer/fogbugz_import_finished.png) +This document was moved to a [new location](../../user/project/import/fogbugz.md). diff --git a/doc/workflow/importing/import_projects_from_gitea.md b/doc/workflow/importing/import_projects_from_gitea.md index f5746a0fb31..cb90c490b0f 100644 --- a/doc/workflow/importing/import_projects_from_gitea.md +++ b/doc/workflow/importing/import_projects_from_gitea.md @@ -1,77 +1 @@ -# Import your project from Gitea to GitLab - -Import your projects from Gitea to GitLab with minimal effort. - -## Overview - ->**Note:** -This requires Gitea `v1.0.0` or newer. - -- At its current state, Gitea importer can import: - - the repository description (GitLab 8.15+) - - the Git repository data (GitLab 8.15+) - - the issues (GitLab 8.15+) - - the pull requests (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the labels (GitLab 8.15+) -- Repository public access is retained. If a repository is private in Gitea - it will be created as private in GitLab as well. - -## How it works - -Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped -to users in your GitLab's instance. This means that the project creator (most of -the times the current user that started the import process) is set as the author, -but a reference on the issue about the original Gitea author is kept. - -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's -namespace that started the import process. - -## Importing your Gitea repositories - -The importer page is visible when you create a new project. - -![New project page on GitLab](img/import_projects_from_new_project_page.png) - -Click on the **Gitea** link and the import authorization process will start. - -![New Gitea project import](img/import_projects_from_gitea_new_import.png) - -### Authorize access to your repositories using a personal access token - -With this method, you will perform a one-off authorization with Gitea to grant -GitLab access your repositories: - -1. Go to (replace - `you-gitea-instance` with the host of your Gitea instance). -1. Click **Generate New Token**. -1. Enter a token description. -1. Click **Generate Token**. -1. Copy the token hash. -1. Go back to GitLab and provide the token to the Gitea importer. -1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads - your repositories' information. Once done, you'll be taken to the importer - page to select the repositories to import. - -### Select which repositories to import - -After you've authorized access to your Gitea repositories, you will be -redirected to the Gitea importer page. - -From there, you can see the import statuses of your Gitea repositories. - -- Those that are being imported will show a _started_ status, -- those already successfully imported will be green with a _done_ status, -- whereas those that are not yet imported will have an **Import** button on the - right side of the table. - -If you want, you can import all your Gitea projects in one go by hitting -**Import all projects** in the upper left corner. - -![Gitea importer page](img/import_projects_from_github_importer.png) - ---- - -You can also choose a different name for the project and a different namespace, -if you have the privileges to do so. +This document was moved to a [new location](../../user/project/import/gitea.md). diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md index 8ed1d98d05b..13639feaa04 100644 --- a/doc/workflow/importing/import_projects_from_github.md +++ b/doc/workflow/importing/import_projects_from_github.md @@ -1,122 +1 @@ -# Import your project from GitHub to GitLab - -Import your projects from GitHub to GitLab with minimal effort. - -## Overview - ->**Note:** -If you are an administrator you can enable the [GitHub integration][gh-import] -in your GitLab instance sitewide. This configuration is optional, users will -still be able to import their GitHub repositories with a -[personal access token][gh-token]. - ->**Note:** -Administrators of a GitLab instance (Community or Enterprise Edition) can also -use the [GitHub rake task][gh-rake] to import projects from GitHub without the -constrains of a Sidekiq worker. - -- At its current state, GitHub importer can import: - - the repository description (GitLab 7.7+) - - the Git repository data (GitLab 7.7+) - - the issues (GitLab 7.7+) - - the pull requests (GitLab 8.4+) - - the wiki pages (GitLab 8.4+) - - the milestones (GitLab 8.7+) - - the labels (GitLab 8.7+) - - the release note descriptions (GitLab 8.12+) -- References to pull requests and issues are preserved (GitLab 8.7+) -- Repository public access is retained. If a repository is private in GitHub - it will be created as private in GitLab as well. - -## How it works - -When issues/pull requests are being imported, the GitHub importer tries to find -the GitHub author/assignee in GitLab's database using the GitHub ID. For this -to work, the GitHub author/assignee should have signed in beforehand in GitLab -and **associated their GitHub account**. If the user is not -found in GitLab's database, the project creator (most of the times the current -user that started the import process) is set as the author, but a reference on -the issue about the original GitHub author is kept. - -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's -namespace that started the import process. - -## Importing your GitHub repositories - -The importer page is visible when you create a new project. - -![New project page on GitLab](img/import_projects_from_new_project_page.png) - -Click on the **GitHub** link and the import authorization process will start. -There are two ways to authorize access to your GitHub repositories: - -1. [Using the GitHub integration][gh-integration] (if it's enabled by your - GitLab administrator). This is the preferred way as it's possible to - preserve the GitHub authors/assignees. Read more in the [How it works](#how-it-works) - section. -1. [Using a personal access token][gh-token] provided by GitHub. - -![Select authentication method](img/import_projects_from_github_select_auth_method.png) - -### Authorize access to your repositories using the GitHub integration - -If the [GitHub integration][gh-import] is enabled by your GitLab administrator, -you can use it instead of the personal access token. - -1. First you may want to connect your GitHub account to GitLab in order for - the username mapping to be correct. -1. Once you connect GitHub, click the **List your GitHub repositories** button - and you will be redirected to GitHub for permission to access your projects. -1. After accepting, you'll be automatically redirected to the importer. - -You can now go on and [select which repositories to import](#select-which-repositories-to-import). - -### Authorize access to your repositories using a personal access token - ->**Note:** -For a proper author/assignee mapping for issues and pull requests, the -[GitHub integration][gh-integration] should be used instead of the -[personal access token][gh-token]. If the GitHub integration is enabled by your -GitLab administrator, it should be the preferred method to import your repositories. -Read more in the [How it works](#how-it-works) section. - -If you are not using the GitHub integration, you can still perform a one-off -authorization with GitHub to grant GitLab access your repositories: - -1. Go to . -1. Enter a token description. -1. Check the `repo` scope. -1. Click **Generate token**. -1. Copy the token hash. -1. Go back to GitLab and provide the token to the GitHub importer. -1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads - your repositories' information. Once done, you'll be taken to the importer - page to select the repositories to import. - -### Select which repositories to import - -After you've authorized access to your GitHub repositories, you will be -redirected to the GitHub importer page. - -From there, you can see the import statuses of your GitHub repositories. - -- Those that are being imported will show a _started_ status, -- those already successfully imported will be green with a _done_ status, -- whereas those that are not yet imported will have an **Import** button on the - right side of the table. - -If you want, you can import all your GitHub projects in one go by hitting -**Import all projects** in the upper left corner. - -![GitHub importer page](img/import_projects_from_github_importer.png) - ---- - -You can also choose a different name for the project and a different namespace, -if you have the privileges to do so. - -[gh-import]: ../../integration/github.md "GitHub integration" -[gh-rake]: ../../administration/raketasks/github_import.md "GitHub rake task" -[gh-integration]: #authorize-access-to-your-repositories-using-the-github-integration -[gh-token]: #authorize-access-to-your-repositories-using-a-personal-access-token +This document was moved to a [new location](../../user/project/import/github.md). diff --git a/doc/workflow/importing/import_projects_from_gitlab_com.md b/doc/workflow/importing/import_projects_from_gitlab_com.md index b27125a44de..df4c180919a 100644 --- a/doc/workflow/importing/import_projects_from_gitlab_com.md +++ b/doc/workflow/importing/import_projects_from_gitlab_com.md @@ -1,21 +1 @@ -# Project importing from GitLab.com to your private GitLab instance - -You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if -GitLab support is enabled on your GitLab instance. -You can read more about GitLab support [here](http://docs.gitlab.com/ce/integration/gitlab.html) -To get to the importer page you need to go to "New project" page. - ->**Note:** -If you are interested in importing Wiki and Merge Request data to your new instance, you'll need to follow the instructions for [project export](../../user/project/settings/import_export.md) - -![New project page](gitlab_importer/new_project_page.png) - -Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com -for permission to access your projects. After accepting, you'll be automatically redirected to the importer. - - -![Importer page](gitlab_importer/importer.png) - - -To import a project, you can simple click "Import". The importer will import your repository and issues. -Once the importer is done, a new GitLab project will be created with your imported data. \ No newline at end of file +This document was moved to a [new location](../../user/project/import/gitlab_com.md). diff --git a/doc/workflow/importing/migrating_from_svn.md b/doc/workflow/importing/migrating_from_svn.md index 7a3628a39d7..81df3fbcdbb 100644 --- a/doc/workflow/importing/migrating_from_svn.md +++ b/doc/workflow/importing/migrating_from_svn.md @@ -1,183 +1 @@ -# Migrating from SVN to GitLab - -Subversion (SVN) is a central version control system (VCS) while -Git is a distributed version control system. There are some major differences -between the two, for more information consult your favorite search engine. - -## Overview - -There are two approaches to SVN to Git migration: - -1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: - - Makes the GitLab repository to mirror the SVN project. - - Git and SVN repositories are kept in sync; you can use either one. - - Smoothens the migration process and allows to manage migration risks. - -1. [Cut over migration](#cut-over-migration-with-svn2git) which: - - Translates and imports the existing data and history from SVN to Git. - - Is a fire and forget approach, good for smaller teams. - -## Smooth migration with a Git/SVN mirror using SubGit - -[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git -migration. It creates a writable Git mirror of a local or remote Subversion -repository and that way you can use both Subversion and Git as long as you like. -It requires access to your GitLab server as it talks with the Git repositories -directly in a filesystem level. - -### SubGit prerequisites - -1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can - follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). -1. Download SubGit from https://subgit.com/download/. -1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` - command will be available at `/opt/subgit-VERSION/bin/subgit`. - -### SubGit configuration - -The first step to mirror you SVN repository in GitLab is to create a new empty -project which will be used as a mirror. For Omnibus installations the path to -the repository will be located at -`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For -installations from source, the default repository directory will be -`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a -variable: - -``` -GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git -``` - -SubGit will keep this repository in sync with a remote SVN project. For -convenience, assign your remote SVN project URL to a variable: - -``` -SVN_PROJECT_URL=http://svn.company.com/repos/project -``` - -Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following -`subgit` command is ran on behalf of the same user that keeps ownership of -GitLab Git repositories (by default `git`): - -``` -subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH -``` - -Adjust authors and branches mappings, if necessary. Open with your favorite -text editor: - -``` -edit $GIT_REPO_PATH/subgit/authors.txt -edit $GIT_REPO_PATH/subgit/config -``` - -For more information regarding the SubGit configuration options, refer to -[SubGit's documentation](https://subgit.com/documentation.html) website. - -### Initial translation - -Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the -initial translation of existing SVN revisions into the Git repository: - -``` -subgit install $GIT_REPO_PATH -``` - -After the initial translation is completed, the Git repository and the SVN -project will be kept in sync by `subgit` - new Git commits will be translated to -SVN revisions and new SVN revisions will be translated to Git commits. Mirror -works transparently and does not require any special commands. - -If you would prefer to perform one-time cut over migration with `subgit`, use -the `import` command instead of `install`: - -``` -subgit import $GIT_REPO_PATH -``` - -### SubGit licensing - -Running SubGit in a mirror mode requires a -[registration](https://subgit.com/pricing.html). Registration is free for open -source, academic and startup projects. - -We're currently working on deeper GitLab/SubGit integration. You may track our -progress at [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/990). - -### SubGit support - -For any questions related to SVN to GitLab migration with SubGit, you can -contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com). - -## Cut over migration with svn2git - -If you are currently using an SVN repository, you can migrate the repository -to Git and GitLab. We recommend a hard cut over - run the migration command once -and then have all developers start using the new GitLab repository immediately. -Otherwise, it's hard to keep changing in sync in both directions. The conversion -process should be run on a local workstation. - -Install `svn2git`. On all systems you can install as a Ruby gem if you already -have Ruby and Git installed. - -```bash -sudo gem install svn2git -``` - -On Debian-based Linux distributions you can install the native packages: - -```bash -sudo apt-get install git-core git-svn ruby -``` - -Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. -If you choose not to create the authors file then commits will not be attributed -to the correct GitLab user. Some users may not consider this a big issue while -others will want to ensure they complete this step. If you choose to map authors -you will be required to map every author that is present on changes in the SVN -repository. If you don't, the conversion will fail and you will have to update -the author file accordingly. The following command will search through the -repository and output a list of authors. - -```bash -svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq -``` - -Use the output from the last command to construct the authors file. -Create a file called `authors.txt` and add one mapping per line. - -``` -janedoe = Jane Doe -johndoe = John Doe -``` - -If your SVN repository is in the standard format (trunk, branches, tags, -not nested) the conversion is simple. For a non-standard repository see -[svn2git documentation](https://github.com/nirvdrum/svn2git). The following -command will checkout the repository and do the conversion in the current -working directory. Be sure to create a new directory for each repository before -running the `svn2git` command. The conversion process will take some time. - -```bash -svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt -``` - -If your SVN repository requires a username and password add the -`--username ` and `--password /.git -git push --all origin -git push --tags origin -``` - -## Contribute to this guide -We welcome all contributions that would expand this guide with instructions on -how to migrate from SVN and other version control systems. +This document was moved to a [new location](../../user/project/import/svn.md). -- cgit v1.2.1