VSSから分散型バージョン管理システムに移行するための another way


今更ながら、10年以上使用してきたバージョン管理システム[Microsoft Visual Source Safe](http://msdn.microsoft.com/library/3h0544kx(v=vs.80).aspx)をようやく卒業し、分散型バージョン管理システム[Git](http://git-scm.com)に移行しました。
この際に使用した移行ツール[**vss2git.rb**](https://github.com/hanaguro8/vss2git)を紹介します。

## 初めに

移行に際しては、まず初めに、巷で評判の良さそうな移行ツール[vss2git.exe](https://code.google.com/p/vss2git/)を検討しました。[vss2git.exe](https://code.google.com/p/vss2git/)はWindows GUIアプリケーションで、使用方法も簡単、[vss2git.exe](https://code.google.com/p/vss2git/)を使った移行記事もインターネットにたくさん公開されています。一般的には、たぶんこれが一番のおすすめツールなんだと思います。

しかし私の環境では、10個程度のVSSリポジトリのうち、どうしても特定のリポジトリで変換エラーが発生してしまいました。VSSリポジトリの修復、VSSのバージョン変更、[vss2git.exe](https://code.google.com/p/vss2git/)ソースファイルの解析、他の移行ツール[vss2svn.pl](http://miau.s9.xrea.com/blog/index.php?itemid=528)の検討、などなどしているうちに、結局自分で作ってしまった方が早いという結論に達し、移行ツール[**vss2git.rb**](https://github.com/hanaguro8/vss2git)を作成しました。

もし私と同じようにお悩みの方がいらっしゃいましたら、[vss2git.rb](https://github.com/hanaguro8/vss2git)をお試しください。
なお、ツールの品質には十分注意を払っているつもりですが、不測の事態に備え、ツール使用前には、変換元のVSSリポジトリや、PC上の重要なファイルをバックアップしてからご使用ください。

## [vss2git.rb](https://github.com/hanaguro8/vss2git)で何ができるの?

[vss2git.exe](https://code.google.com/p/vss2git/)と機能的にはほとんど変わらないと思います。

* VSSリポジトリを、分散型バージョン管理システム[Git](http://git-scm.com), [Mercurial](http://mercurial.selenic.com), [Bazaar](http://bazaar.canonical.com/en/)リポジトリに変換する
* 日本語のコメントを正しく変換できる
* 近接したチェックイン、同一のチェックインコメントを持つ履歴は、同一コミットにまとめられる([vss2git.exe](https://code.google.com/p/vss2git/)のアイディア)
* VSSサブプロジェクトを指定した変換も可能
* ターゲットバージョン管理システムで使用するユーザメールアドレス生成のため、E-mail domainが指定可能
* [JSON](http://ja.wikipedia.org/wiki/JavaScript_Object_Notation)フォーマットで、VSSユーザIDと、ターゲットバージョン管理システムで使用するユーザID、E-mailアドレスのペアを定義しておき、マイグレーション時にユーザIDの変換が可能
* VSSのTagを元に、ターゲットバージョン管理システムで[A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/)への変換が可能
* タイムゾーン指定が可能
* VSSの継続的ミラーリング(差分更新)が可能

## ライセンス
MITライセンスに従います。詳細は[GitHub](https://github.com/hanaguro8/vss2git)のLICENSE.txtを参照ください。

## 必要なもの
[vss2git.rb](https://github.com/hanaguro8/vss2git)の実行には以下が必要です。

### Microsoft Windows オペレーティングシステム

* Windows 7 or
* Windows XP or
* Windows 8, VISTA … 未確認ですが、たぶんOK

### Microsoft Visual Source Safe

* VSS 2005 … 言語設定をEnglishに設定する必要あり
* VSS 6.0d … 英語バージョンが必要 (日本語版のSSJP.DLLをリネームして、無効にしても良い)

### ターゲットのバージョン管理システム
[vss2git.rb](https://github.com/hanaguro8/vss2git)実行前に、ターゲットバージョン管理システムコマンドへのパスを、実行パスPATHに設定してください。

* [Git](http://git-scm.com) or
* [Mercurial](http://mercurial.selenic.com) or
* [Bazaar](http://bazaar.canonical.com/en/)

### Ruby
  * [Ruby](http://rubyinstaller.org) 2.0 or 1.9.3 (32 bit version)

### [vss2git.rb](https://github.com/hanaguro8/vss2git)
分散バージョン管理システム移行ツール

## 使用方法
```
ruby vss2git.rb -r <runmode> -s <vssdir> -u <user> [-p <password>]
                [-c <vcs>] [-d <email domain>] [-l <user list>]
                [-b <branch>] [-e <verbose>] [-t <time>]
                [-w <workingdir>] [-r] VSS_PROJECT

  -r|--runmode      Run mode (0, 1, 2) (defualt:0)
                      0: Analyze
                      1: Full migration
                      2: Continuous migration
  -s|--vssdir       Absolute path to VSS repository
  -u|--user         VSS user name
  -p|--password     VSS password
  -c|--vcs          Target version control system
                    "git", "hg" or "bzr"
  -d|--emaildomain  e-mail domain
  -l|--userlist     User list file (JSON format)
                      Ex.
                      {
                        "user name on VSS":
                         ["user name on VCS", "e-mail address"],
                        "user name on VSS":
                         ["user name on VCS", "e-mail address"],
                        ...
                      }
  -b|--branch       A successful Git branching model (0, 1, 2) (default:0)
                      0: No branching model
                      1: Branching model type 1
                         master:  Production branch
                         develop: Development branch
                      2: Branching model type 2
                         master:  Development branch
                         product: Production branch
  -e|--verbose      Verbose mode (0, 1, 2) (default:1)
                      STDOUT
                        0-1: VSS information, user list, migration log
                        2:   + dump of internal objest (for debug)
                      STDERR
                        0:   No output
                        1-2: Processing status
  -t|--timeshift    Time to shift (-12 .. 12)
  -w|--workingdir   Path to the root of working folder
  -r|--update       Update mode
  -v|--version      Print version
  -h|--help         Print help
```

#### -r [0 | 1 | 2]
RUNモード指定です。

* -r0: VSSを解析して、VSS情報およびVSSのユーザリストを取得します。migrationは実行しません。
* -r1: VSSからVCSへのFull migrationを実行します。（デフォルト）  
ターゲットVCSの新規リポジトリが作成され、VSSの全履歴がターゲットVCSに変換されます。
* -r2: VSSからVCSへのContinuous migrationを実行します。  
VSSをターゲットバージョン管理システムに変換した後に、変換元VSSが更新された場合、差分履歴を抽出して、ターゲットバージョン管理システムのリポジトリに反映します。継続してVSSをターゲットバージョンシステムにミラーリングしたい場合に使用します。

#### -s \<vssdir>
VSSリポジトリのパスを設定してください。UNCの指定も可能です。

#### -u \<user>
VSSにアクセスするためのユーザIDを指定してください。

#### -p \<password>
VSSユーザIDのパスワードを指定してください。

#### -c [git | hg | bzr]
ターゲットバージョン管理システム名を指定してください。
“[git](http://git-scm.com)” or “[hg](http://mercurial.selenic.com)” or “[bzr](http://bazaar.canonical.com/en/)”

#### -d \<email domain>
VSSのチェックインユーザIDに、指定したE-mailドメイン名を付加して、E-mailアドレスを生成します。同一サイトでVSSを運用していて、VSSユーザIDとE-mailアドレスIDが同じ場合に有効な設定です。

#### -l \<user list>
VSSのチェックインユーザIDのE-mailドメインが異なる場合や、変換時にユーザIDを変更したい場合に有効な方法です。[JSON](http://ja.wikipedia.org/wiki/JavaScript_Object_Notation)フォーマットで、あらかじめ、VSSのチェックインユーザIDと、ターゲットバージョン管理システムで使用するユーザID、E-mailアドレスのペアを指定して下さい。

```
{
  “VSSユーザID 1”: [“ターゲットバージョン管理システムユーザID 1”, “E-mailアドレス 1”],
  “VSSユーザID 2”: [“ターゲットバージョン管理システムユーザID 2”, “E-mailアドレス 2”],
  …
}

例)
{
  “taro”: [“Taro.Tanaka”, “taro.tanaka@mail.abcdef.co.jp”],
  “hanako”: [“Hanako.Kobayashi”, “hanako.kobayashi@mail.ghijkl.co.jp”]
}
```

#### -b [0 | 1 | 2]
[A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/)を適用するかどうかを指定します。

* -b0: A Successful Git Branching model を適用しない (デフォルト)
* -b1: A Successful Git Branching model type 1 を適用
* -b2: A Successful Git Branching model type 2 を適用

-b1, -b2 を適用すると、VSSでタグ付けされた履歴は製品ブランチに、タグなしの履歴は開発ブランチにコミットされます。

* type 1では、”master”, “develop”の2つのブランチが作成され、”master”は製品ブランチ、”develop”は開発ブランチになります。
* type 2では、”master”, “product”の2つのブランチが作成され、”master”は開発ブランチ、”product”は製品ブランチになります。(私はtype 2を使ってます)

#### -e [0 | 1 | 2 ]
STDOUT, STDERRへのログの出力を指定します。

* -e0: STDOUTにVSSの情報、ユーザIDリスト([JSON](http://ja.wikipedia.org/wiki/JavaScript_Object_Notation)フォーマット)、変換ログを出力します。STDERRには何も出力しません。
* -e1: STDOUTにVSSの情報、ユーザIDリスト([JSON](http://ja.wikipedia.org/wiki/JavaScript_Object_Notation)フォーマット)、変換ログを出力します。STDERRには変換ステータスを出力します。（デフォルト）
* -e2: STDOUTにVSSの情報、ユーザIDリスト([JSON](http://ja.wikipedia.org/wiki/JavaScript_Object_Notation)フォーマット)、変換ログ、内部オブジェクト情報を出力します。STDERRには変換ステータスを出力します。vss2git.rbのデバッグ用の設定です。

#### -t \<time shift>
タイムゾーンを設定します。設定可能な値は、-12〜12（時間)です。
単一サイトでVSSを使用していた場合には、本指定は不要です。タイムゾーンの異なるサイトでVSSを共有していた場合に指定してください。

#### -w \<workingdir>
VSS_PROJECT で指定したプロジェクトを、カレントフォルダ以外に展開したい場合に指定してください。例えば、-w a\b\c 指定すると、指定したプロジェクトを、.\a\b\c\フォルダ以下に展開します。

#### -v
vss2git.rb のバージョンを表示します。

#### -h
vss2git.rb のhelpを表示します。

## 使用例
#### Case 1
* VSSリポジトリ:		c:\vssrepo\library
* VSSプロジェクト:	$/
* VSSユーザID:		taro
* ターゲットVCS:		git

```
ruby vss2git.rb -r1 -s c:\vssrepo\library -u taro -c git $/ > migration.log
```

#### Case 2
* VSSリポジトリ:		\\\\vssrepo\library
* VSSプロジェクト:	$/PRODUCT-1
* VSSユーザID:		taro
* VSSパスワード:		abc123
* ターゲットVCS:		git
* ユーザリストファイル:	C:\doc\user.json
* ブランチモデル:	type 2
* ワーキングフォルダ:	PRODUCT-1

```
ruby vss2git.rb -r1 -s \\vssrepo\library -u taro -p abc123 -c git -l c:\doc\user.json -b2 -w PRODUCT-1 $/PRODUCT-a > migration.log
```

## サンプル
簡単なサンプルを用意しました。
以下の手順で、簡単に[*vss2git.rb*](https://github.com/hanaguro8/vss2git)をお試しいただけます。

#### 1. 初めに、上記「必要なもの」が準備できていることを確認してください。

#### 2. githubから[vss2git.rbリポジトリ](https://github.com/hanaguro8/vss2git)をcloneします。

#### 3. 変換元のVSSリポジトリ(サンプル)を作成します。  
“sample”フォルダに移動して、”mk_sample_vss.rb”を実行してください。
“Enter VSS command directory:” が表示されますので、VSSのインストールディレクトリを入力してください。

```
> cd sample
\sample> ruby mk_sample_vss.rb
Enter VSS command directory: C:\Program Files (X86)\Microsoft Visual SourceSafe
```
”sample\vss”フォルダにサンプル用のVSSリポジトリが作成されます。

#### 4. 上記VSSリポジトリをGitレポジトリに変換します。

サンプルフォルダで、”migrate.bat”を実行して下さい。

```
\sample> migrate
```

“sample\git”フォルダに、Gitリポジトリが作成されます。