debian-mirror-gitlab/doc/user/project/import/svn.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

191 lines
7.2 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
type: howto
stage: Manage
group: Import
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2021-09-04 01:27:46 +05:30
# Migrating from SVN to GitLab **(FREE)**
2018-03-17 18:26:18 +05:30
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.
There are two approaches to SVN to Git migration:
2021-06-08 01:23:25 +05:30
- [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 you to manage migration risks.
2018-03-17 18:26:18 +05:30
2021-06-08 01:23:25 +05:30
- [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.
2018-03-17 18:26:18 +05:30
## 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
2021-03-11 19:13:27 +05:30
directly in a file system level.
2018-03-17 18:26:18 +05:30
### 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).
2019-09-30 21:07:59 +05:30
1. Download SubGit from <https://subgit.com/download>.
2018-03-17 18:26:18 +05:30
1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit`
2021-06-08 01:23:25 +05:30
command is available at `/opt/subgit-VERSION/bin/subgit`.
2018-03-17 18:26:18 +05:30
### SubGit configuration
The first step to mirror you SVN repository in GitLab is to create a new empty
2021-06-08 01:23:25 +05:30
project that is used as a mirror. For Omnibus installations the path to
the repository is
2018-03-17 18:26:18 +05:30
`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For
2021-06-08 01:23:25 +05:30
installations from source, the default repository directory is
2018-03-17 18:26:18 +05:30
`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a
variable:
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git
```
2021-06-08 01:23:25 +05:30
SubGit keeps this repository in sync with a remote SVN project. For
2018-03-17 18:26:18 +05:30
convenience, assign your remote SVN project URL to a variable:
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
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`):
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH
```
Adjust authors and branches mappings, if necessary. Open with your favorite
text editor:
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
edit $GIT_REPO_PATH/subgit/authors.txt
edit $GIT_REPO_PATH/subgit/config
```
For more information regarding the SubGit configuration options, refer to
2018-12-05 23:21:45 +05:30
[SubGit's documentation](https://subgit.com/documentation/) website.
2018-03-17 18:26:18 +05:30
### Initial translation
2020-06-23 00:09:42 +05:30
Now that SubGit has configured the Git/SVN repositories, run `subgit` to perform the
2018-03-17 18:26:18 +05:30
initial translation of existing SVN revisions into the Git repository:
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
subgit install $GIT_REPO_PATH
```
2021-06-08 01:23:25 +05:30
After the initial translation is completed, `subgit` keeps the Git repository and the SVN
project sync - new Git commits are translated to
SVN revisions and new SVN revisions are translated to Git commits. Mirror
2018-03-17 18:26:18 +05:30
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`:
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
subgit import $GIT_REPO_PATH
```
### SubGit licensing
Running SubGit in a mirror mode requires a
2019-12-21 20:55:43 +05:30
[registration](https://subgit.com/pricing). Registration is free for open
2018-03-17 18:26:18 +05:30
source, academic and startup projects.
### 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
2021-09-04 01:27:46 +05:30
NOTE:
Any issues with svn2git should be directed to the [relevant project and maintainer](https://github.com/nirvdrum/svn2git).
Check for existing issues and history for update frequency.
2018-03-17 18:26:18 +05:30
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.
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
sudo gem install svn2git
```
On Debian-based Linux distributions you can install the native packages:
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
sudo apt-get install git-core git-svn ruby
```
Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors.
2021-06-08 01:23:25 +05:30
If you choose not to create the authors file then commits are not attributed
2018-03-17 18:26:18 +05:30
to the correct GitLab user. Some users may not consider this a big issue while
2021-06-08 01:23:25 +05:30
others want to ensure they complete this step. If you choose to map authors,
you must map every author present on changes in the SVN
repository. If you don't, the conversion fails and you have to update
the author file accordingly. The following command searches through the
2018-03-17 18:26:18 +05:30
repository and output a list of authors.
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
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.
2020-03-13 15:44:24 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
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
2021-06-08 01:23:25 +05:30
running the `svn2git` command. The conversion process takes some time.
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt
```
If your SVN repository requires a username and password add the
2020-06-23 00:09:42 +05:30
`--username <username>` and `--password <password>` flags to the above command.
2021-06-08 01:23:25 +05:30
`svn2git` also supports excluding certain file paths, branches, tags, and so on. See
2018-03-17 18:26:18 +05:30
[svn2git documentation](https://github.com/nirvdrum/svn2git) or run
`svn2git --help` for full documentation on all of the available options.
2021-06-08 01:23:25 +05:30
Create a new GitLab project, into which you push your converted code.
2018-03-17 18:26:18 +05:30
Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab
2021-06-08 01:23:25 +05:30
repository as a Git remote and push all the changes. This pushes all commits,
2018-03-17 18:26:18 +05:30
branches and tags.
2020-03-13 15:44:24 +05:30
```shell
2018-03-17 18:26:18 +05:30
git remote add origin git@gitlab.com:<group>/<project>.git
git push --all origin
git push --tags origin
```
## Contribute to this guide
2018-12-05 23:21:45 +05:30
2018-03-17 18:26:18 +05:30
We welcome all contributions that would expand this guide with instructions on
how to migrate from SVN and other version control systems.