|
| 1 | +--- |
| 2 | +layout: cheat-sheet |
| 3 | +title: Subversion to Git migration |
| 4 | +byline: From understanding the vocabularies of Subversion and Git technologies to migrating a project to GitHub, this cheat sheet can help. |
| 5 | +--- |
| 6 | + |
| 7 | +# Subversion to Git migration |
| 8 | + |
| 9 | +From understanding the vocabularies of Subversion and Git technologies to migrating a project to GitHub, this cheat sheet can help. |
| 10 | + |
| 11 | + |
| 12 | +## Vocabulary |
| 13 | + |
| 14 | +| Git command | SVN | SVN equivalent | Git Behavior | |
| 15 | +|---|---|---|---| |
| 16 | +| `status` | ✓ | status | Report the state of working tree | |
| 17 | +| `add` | — | add | Required for each path before making a commit | |
| 18 | +| `commit` | — | commit | Store prepared changes in local revision history | |
| 19 | +| `rm` | ✓ | `rm`, `delete` | Prepare paths for deletion in next commit | |
| 20 | +| `mv` | ✓ | `move` | Prepare relocated content for next commit | |
| 21 | +| `branch` | — | | Create local context for commits | |
| 22 | +| `checkout` | — | | Switch branches, or rewrite working tree from commit | |
| 23 | +| `merge` | ✓ | | Join branch histories and changes to working tree | |
| 24 | +| `log` | — | | No network required | |
| 25 | +| `clone` | ✗ | `checkout` | Acquire the entire history of a project locally for the first time | |
| 26 | +| `push` | ✗ | `commit` | Upload commit history to GitHub/centralized Git host | |
| 27 | +| `pull` | ✗ | | Download and integrate GitHub repository history with local one | |
| 28 | +| `fetch` | ✗ | | Download GitHub repository history with no other action | |
| 29 | + |
| 30 | +**Key:** ✓ yes, ✗ no, — partial |
| 31 | + |
| 32 | +## Leveraging Git's support of SVN |
| 33 | +During a VCS change, there may be a need to begin using Git locally while the hosted repositories remain under Subversion control. The `git svn` command and sub-commends provide the ability to interact with Subversion's repositories while using all the benefits of Git on the command line or with graphical clients. |
| 34 | + |
| 35 | +Acquire an SVN repository, with a resulting Git repository locally: |
| 36 | + |
| 37 | +`git svn clone [svn-repo-url]` |
| 38 | + |
| 39 | +**Note:** Keep in mind the *layout* of the SVN repository and whether this follows the standard pattern or not. If the Subversion repository follows the traditional `trunk`, `branches`, and `tags` pattern, supply the `--std-layout` option. When the Subversion repository is non-standard or organized in a more custom structure, the following options switches should be specified during the clone: |
| 40 | + |
| 41 | +* `-T [trunk]` for alternate main source convention |
| 42 | +* `-b [branches]` for alternate branch location |
| 43 | +* `-t [tags]` for alternate tag structure location |
| 44 | + |
| 45 | +Once the clone operation completes, you can proceed with any standard Git interactions, commands and processes. |
| 46 | + |
| 47 | +## Synchronizing with SVN repository |
| 48 | + |
| 49 | +Once local history within a `git svn clone` repository has occurred, the commits must be published to the Subversion repository. |
| 50 | + |
| 51 | +`git svn dcommit` |
| 52 | + |
| 53 | +If the Subversion repository has commits not yet on the local Git-equivalent, a `rebase` must first be performed. |
| 54 | + |
| 55 | +`git svn rebase` |
| 56 | + |
| 57 | +Keep in mind this rewrites local Git history and your Git commit refs will be different than before the command is run. |
| 58 | + |
| 59 | +## Subversion tooling bridge via GitHub |
| 60 | + |
| 61 | +For users familiar with Subversion toolsets and clients, [GitHub fully supports and bridges communications to the central repository](https://help.github.com/articles/support-for-subversion-clients/). All Subversion commits directed at a GitHub hosted repository will automatically be converted to Git commits. |
| 62 | + |
| 63 | +* [Topics about branch strategies with SVN](https://github.com/blog/1178-collaborating-on-github-with-subversion) |
| 64 | +* Patterns for updating `trunk` or GitHub default branch equivalent |
| 65 | + |
| 66 | + |
| 67 | +## Migrating |
| 68 | + |
| 69 | +The use of `git svn` should be a temporary bridge and complete migration to Git repositories for both local and upstream destinations is optimal. |
| 70 | + |
| 71 | +The most lightweight approach is by utilizing `git svn` as a one-time conversion from Subversion to Git repository. To migrate a Subversion repository, several aspects must be ensured: |
| 72 | + |
| 73 | +* Subversion commits cease prior to initiating the process |
| 74 | +* One machine serves as intermediary during conversion |
| 75 | +* GitHub "upstream" repository intialized and ready to receive history, branches, tags |
| 76 | + |
| 77 | +### Git-SVN conversion method |
| 78 | +* Create email/username mapping file |
| 79 | +* Begin `git svn clone` |
| 80 | +* Add `git remote add origin [GitHub-URL]` |
| 81 | + |
| 82 | +Run each `ref` publish separately: |
| 83 | + |
| 84 | +* Run `git push --all origin` |
| 85 | +* Run `git push --tags origin` |
| 86 | + |
| 87 | +Or upload all `ref`s (branches, tags,) to upstream: |
| 88 | + |
| 89 | +* `git push --mirror origin` |
| 90 | + |
| 91 | +### SVN2Git method |
| 92 | + |
| 93 | +* Install Ruby Gem [SVN2Git](https://github.com/nirvdrum/svn2git) |
| 94 | +* Identify the projects in the Subversion repository |
| 95 | +* Run `svn list [svn-repo-url]` |
| 96 | +* Start `svn2git [repo-root|repo-root/project]` |
| 97 | + |
| 98 | +Considerations on migration: |
| 99 | + |
| 100 | +* Convert "flat" history across all projects |
| 101 | +* Utilize Git `filter-branch --subdirectory-filter` |
| 102 | +* Migrate on a project-by-project basis |
| 103 | +* Use `--trunk`, `--nobranches`, `--notags` or `--rootistrunk` for non-standard layouts |
| 104 | +* Limit history from starting point ``--revision <<starting_rev>>``, or range `--revision <<start:end>>` |
| 105 | + |
| 106 | +https://github.com/nirvdrum/svn2git |
| 107 | + |
| 108 | +### GitHub importer (Porter) method |
| 109 | +* [Read the import tool documentation](https://help.github.com/articles/importing-from-other-version-control-systems-to-github/) |
| 110 | +* Expose the Subversion repository publicly |
| 111 | +* [Visit the GitHub import tool page](https://porter.github.com/new) |
| 112 | +* Point the import tool at your Subversion, TFS, or Mercurial repository |
| 113 | +* Create the username mappings |
| 114 | +* Wait for the tool to work in the background and complete the conversion |
0 commit comments