diff options
author | Marcia Ramos <virtua.creative@gmail.com> | 2017-08-17 17:56:56 +0300 |
---|---|---|
committer | Marcia Ramos <virtua.creative@gmail.com> | 2017-08-17 17:56:56 +0300 |
commit | f0ac0daf6a8788f57b98eaf29b0056899027ae68 (patch) | |
tree | eeaadf629e2308540334b91efd0bc9c2d03e7461 | |
parent | eed96cbde1c579f5d45d13d18c8e6024e3026db8 (diff) | |
parent | bbd627c54852f62fe45d00b69857106346b8391d (diff) |
Merge branch 'docs/importing-refactor' into 'master'
Move workflow/importing/ to user/project/import/
See merge request !13593
-rw-r--r-- | app/views/shared/_import_form.html.haml | 2 | ||||
-rw-r--r-- | doc/README.md | 2 | ||||
-rw-r--r-- | doc/user/project/import/bitbucket.md | 62 | ||||
-rw-r--r-- | doc/user/project/import/fogbugz.md | 28 | ||||
-rw-r--r-- | doc/user/project/import/gitea.md | 77 | ||||
-rw-r--r-- | doc/user/project/import/github.md | 122 | ||||
-rw-r--r-- | doc/user/project/import/gitlab_com.md | 20 | ||||
-rw-r--r-- | doc/user/project/import/img/bitbucket_import_grant_access.png (renamed from doc/workflow/importing/img/bitbucket_import_grant_access.png) | bin | 7248 -> 7248 bytes | |||
-rw-r--r-- | doc/user/project/import/img/bitbucket_import_new_project.png (renamed from doc/workflow/importing/img/bitbucket_import_new_project.png) | bin | 1316 -> 1316 bytes | |||
-rw-r--r-- | doc/user/project/import/img/bitbucket_import_select_project.png (renamed from doc/workflow/importing/img/bitbucket_import_select_project.png) | bin | 8688 -> 8688 bytes | |||
-rw-r--r-- | doc/user/project/import/img/fogbugz_import_finished.png (renamed from doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png) | bin | 17744 -> 17744 bytes | |||
-rw-r--r-- | doc/user/project/import/img/fogbugz_import_login.png (renamed from doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png) | bin | 13751 -> 13751 bytes | |||
-rw-r--r-- | doc/user/project/import/img/fogbugz_import_select_fogbogz.png (renamed from doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png) | bin | 12289 -> 12289 bytes | |||
-rw-r--r-- | doc/user/project/import/img/fogbugz_import_select_project.png (renamed from doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png) | bin | 20905 -> 20905 bytes | |||
-rw-r--r-- | doc/user/project/import/img/fogbugz_import_user_map.png (renamed from doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png) | bin | 51238 -> 51238 bytes | |||
-rw-r--r-- | doc/user/project/import/img/gitlab_importer.png (renamed from doc/workflow/importing/gitlab_importer/importer.png) | bin | 12864 -> 12864 bytes | |||
-rw-r--r-- | doc/user/project/import/img/gitlab_new_project_page.png (renamed from doc/workflow/importing/gitlab_importer/new_project_page.png) | bin | 21251 -> 21251 bytes | |||
-rw-r--r-- | doc/user/project/import/img/import_projects_from_gitea_new_import.png (renamed from doc/workflow/importing/img/import_projects_from_gitea_new_import.png) | bin | 15561 -> 15561 bytes | |||
-rw-r--r-- | doc/user/project/import/img/import_projects_from_github_importer.png (renamed from doc/workflow/importing/img/import_projects_from_github_importer.png) | bin | 17953 -> 17953 bytes | |||
-rw-r--r-- | doc/user/project/import/img/import_projects_from_github_select_auth_method.png (renamed from doc/workflow/importing/img/import_projects_from_github_select_auth_method.png) | bin | 17612 -> 17612 bytes | |||
-rw-r--r-- | doc/user/project/import/img/import_projects_from_new_project_page.png (renamed from doc/workflow/importing/img/import_projects_from_new_project_page.png) | bin | 36821 -> 36821 bytes | |||
-rw-r--r-- | doc/user/project/import/index.md | 20 | ||||
-rw-r--r-- | doc/user/project/import/svn.md | 183 | ||||
-rw-r--r-- | doc/user/project/index.md | 10 | ||||
-rw-r--r-- | doc/workflow/importing/README.md | 18 | ||||
-rw-r--r-- | doc/workflow/importing/import_projects_from_bitbucket.md | 63 | ||||
-rw-r--r-- | doc/workflow/importing/import_projects_from_fogbugz.md | 30 | ||||
-rw-r--r-- | doc/workflow/importing/import_projects_from_gitea.md | 78 | ||||
-rw-r--r-- | doc/workflow/importing/import_projects_from_github.md | 123 | ||||
-rw-r--r-- | doc/workflow/importing/import_projects_from_gitlab_com.md | 22 | ||||
-rw-r--r-- | doc/workflow/importing/migrating_from_svn.md | 184 |
31 files changed, 526 insertions, 518 deletions
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 <https://you-gitea-instance/user/settings/applications> (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 <https://github.com/settings/tokens/new>. +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/workflow/importing/img/bitbucket_import_grant_access.png b/doc/user/project/import/img/bitbucket_import_grant_access.png Binary files differindex 429904e621d..429904e621d 100644 --- a/doc/workflow/importing/img/bitbucket_import_grant_access.png +++ b/doc/user/project/import/img/bitbucket_import_grant_access.png diff --git a/doc/workflow/importing/img/bitbucket_import_new_project.png b/doc/user/project/import/img/bitbucket_import_new_project.png Binary files differindex 8ed528c2f09..8ed528c2f09 100644 --- a/doc/workflow/importing/img/bitbucket_import_new_project.png +++ b/doc/user/project/import/img/bitbucket_import_new_project.png diff --git a/doc/workflow/importing/img/bitbucket_import_select_project.png b/doc/user/project/import/img/bitbucket_import_select_project.png Binary files differindex 1bca6166ec8..1bca6166ec8 100644 --- a/doc/workflow/importing/img/bitbucket_import_select_project.png +++ b/doc/user/project/import/img/bitbucket_import_select_project.png diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png b/doc/user/project/import/img/fogbugz_import_finished.png Binary files differindex 62c5c86c9b3..62c5c86c9b3 100644 --- a/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png +++ b/doc/user/project/import/img/fogbugz_import_finished.png diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png b/doc/user/project/import/img/fogbugz_import_login.png Binary files differindex 96bce70b74d..96bce70b74d 100644 --- a/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png +++ b/doc/user/project/import/img/fogbugz_import_login.png diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png Binary files differindex b26c652e382..b26c652e382 100644 --- a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png +++ b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png b/doc/user/project/import/img/fogbugz_import_select_project.png Binary files differindex ccc82f9d4cd..ccc82f9d4cd 100644 --- a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png +++ b/doc/user/project/import/img/fogbugz_import_select_project.png diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png b/doc/user/project/import/img/fogbugz_import_user_map.png Binary files differindex 28ff55a8d89..28ff55a8d89 100644 --- a/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png +++ b/doc/user/project/import/img/fogbugz_import_user_map.png diff --git a/doc/workflow/importing/gitlab_importer/importer.png b/doc/user/project/import/img/gitlab_importer.png Binary files differindex 27d42eb492e..27d42eb492e 100644 --- a/doc/workflow/importing/gitlab_importer/importer.png +++ b/doc/user/project/import/img/gitlab_importer.png diff --git a/doc/workflow/importing/gitlab_importer/new_project_page.png b/doc/user/project/import/img/gitlab_new_project_page.png Binary files differindex c673724f436..c673724f436 100644 --- a/doc/workflow/importing/gitlab_importer/new_project_page.png +++ b/doc/user/project/import/img/gitlab_new_project_page.png diff --git a/doc/workflow/importing/img/import_projects_from_gitea_new_import.png b/doc/user/project/import/img/import_projects_from_gitea_new_import.png Binary files differindex a3f603cbd0a..a3f603cbd0a 100644 --- a/doc/workflow/importing/img/import_projects_from_gitea_new_import.png +++ b/doc/user/project/import/img/import_projects_from_gitea_new_import.png diff --git a/doc/workflow/importing/img/import_projects_from_github_importer.png b/doc/user/project/import/img/import_projects_from_github_importer.png Binary files differindex d8effaf6075..d8effaf6075 100644 --- a/doc/workflow/importing/img/import_projects_from_github_importer.png +++ b/doc/user/project/import/img/import_projects_from_github_importer.png diff --git a/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png b/doc/user/project/import/img/import_projects_from_github_select_auth_method.png Binary files differindex 1ccb38a815e..1ccb38a815e 100644 --- a/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png +++ b/doc/user/project/import/img/import_projects_from_github_select_auth_method.png diff --git a/doc/workflow/importing/img/import_projects_from_new_project_page.png b/doc/user/project/import/img/import_projects_from_new_project_page.png Binary files differindex 97ca30b2087..97ca30b2087 100644 --- a/doc/workflow/importing/img/import_projects_from_new_project_page.png +++ b/doc/user/project/import/img/import_projects_from_new_project_page.png 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 <janedoe@example.com> +johndoe = John Doe <johndoe@example.com> +``` + +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 <username>` and `--password <password` flags to the above command. +`svn2git` also supports excluding certain file paths, branches, tags, etc. See +[svn2git documentation](https://github.com/nirvdrum/svn2git) or run +`svn2git --help` for full documentation on all of the available options. + +Create a new GitLab project, where you will eventually push your converted code. +Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab +repository as a Git remote and push all the changes. This will push all commits, +branches and tags. + +```bash +git remote add origin git@gitlab.com:<group>/<project>.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/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 <https://you-gitea-instance/user/settings/applications> (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 <https://github.com/settings/tokens/new>.
-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 <janedoe@example.com> -johndoe = John Doe <johndoe@example.com> -``` - -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 <username>` and `--password <password` flags to the above command. -`svn2git` also supports excluding certain file paths, branches, tags, etc. See -[svn2git documentation](https://github.com/nirvdrum/svn2git) or run -`svn2git --help` for full documentation on all of the available options. - -Create a new GitLab project, where you will eventually push your converted code. -Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab -repository as a Git remote and push all the changes. This will push all commits, -branches and tags. - -```bash -git remote add origin git@gitlab.com:<group>/<project>.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). |