From 4525f156104f24e3c91f8f05945014d418d15b16 Mon Sep 17 00:00:00 2001 From: jordanmccullough Date: Tue, 30 Dec 2014 12:25:48 -0700 Subject: [PATCH 1/6] Bring Markdown in sync with print-ready doc --- downloads/subversion-migration.md | 132 +++++++++++++----------------- 1 file changed, 57 insertions(+), 75 deletions(-) diff --git a/downloads/subversion-migration.md b/downloads/subversion-migration.md index 5fb35fc76..f99267cc7 100644 --- a/downloads/subversion-migration.md +++ b/downloads/subversion-migration.md @@ -1,113 +1,95 @@ --- layout: cheat-sheet -title: Transitioning from Subversion to Git and GitHub -byline: When migrating from Subversion to Git, there's a vocabulary and command set to learn, in addition to the new capabilities only afforded by a DVCS such as Git. This cheat sheet aims to help you in your transition between the classic Subversion technology and the modern use of Git with the GitHub collaboration platform. +title: Subversion to Git Migration +byline: When migrating from Subversion to Git, there’s a vocabulary and command set to learn, in addition to the new capabilities only afforded by Git. This cheat sheet aims to help you in your transition between the classic Subversion technology and the modern use of Git with the GitHub collaboration platform. --- -# Transitioning from Subversion to Git and GitHub - -When migrating from Subversion to Git, there's a vocabulary and command set to learn, in addition to the new capabilities only afforded by a DVCS such as Git. This cheat sheet aims to help you in your transition between the classic Subversion technology and the modern use of Git with the GitHub collaboration platform. +## Migrating -## Vocabulary +### GitHub importer -| Git command | SVN | SVN equivalent | Git Behavior | -|---|---|---|---| -| `status` | ✓ | | Report the state of working tree | -| `add` | ✓ | | Required for each path before making a commit | -| `commit` | ✓ | | Store prepared changes in local revision history | -| `rm` | ✓ | `rm`, `delete` | Prepare paths for deletion in next commit | -| `mv` | ✓ | `move` | Prepare relocated content for next commit | -| `branch` | ✓ | | Create local context for commits | -| `checkout` | ✓ | | Switch branches, or rewrite working tree from commit | -| `merge` | ✓ | | Join branch histories and changes to working tree | -| `log` | ✓ | | No network required | -| `clone` | ✗ | `checkout` | Acquire the entire history of a project locally for the first time | -| `push` | ✗ | `commit` | Upload commit history to GitHub/centralized Git host | -| `pull` | ✗ | | Download and integrate GitHub repository history with local one | -| `fetch` | ✗ | | Download GitHub repository history with no other action | +For Internet-accessible projects, GitHub.com provides Importer for automatic migration and repository creation from Subversion, Team Foundation Server, Mercurial, or alternatively-hosted Git version controlled projects. -**Key:** ✓ yes, ✗ no +The process is as simple, needing only you to sign into your GitHub account, if you aren’t already, entering your existing project’s version control URL in the repository field, and initiating the conversion. -## Leveraging Git's support of SVN -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-commands provide the ability to interact with Subversion's repositories while using all the benefits of Git on the command line or with graphical clients. +Depending on the detected version control system, Importer may request additional information for migration. This includes a mapping file for associating Subversion usernames with Git fields. -Acquire an SVN repository, with a resulting Git repository locally: +Begin migrating repositories by visiting the Importer home page: -`git svn clone [svn-repo-url]` +[https://importer.github.com](https://importer.github.com) -**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: +### SVN2Git Utility -* `-T [trunk]` for alternate main source convention -* `-b [branches]` for alternate branch location -* `-t [tags]` for alternate tag structure location +When access limitations or non-public Subversion repositories need porting to Git, the SVN2Git utility is the command line utility of choice and provides control through every step of the process. -Once the clone operation completes, you can proceed with any standard Git interactions, commands and processes. +Subversion presents distinct differences in structure to that of a Git repository, and SVN2Git provides the flexibility and configuration for traditional and custom Subversion layouts. This ensures the resulting Git repository aligns with standard best practices for commits, branches, and tags for the entire project’s history. -## Synchronizing with SVN repository +Notable features of SVN2Git include: -Once local history within a `git svn clone` repository has occurred, the commits must be published to the Subversion repository. +- Converting all SVN conventions to traditional Git structure +- Providing SVN users field to name and email data in Git commits +- Permiting exclusion patterns for precise Git repository content -`git svn dcommit` +Learn more about SVN2Git at the project’s official home page: -If the Subversion repository has commits not yet on the local Git-equivalent, a `rebase` must first be performed. +[https://github.com/nirvdrum/svn2git](https://github.com/nirvdrum/svn2git) -`git svn rebase` -Keep in mind this rewrites local Git history and your Git commit refs will be different than before the command is run. +## Bridging -## Subversion tooling bridge via GitHub +### Leveraging Git’s support of SVN -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 be automatically converted to Git commits. +Often times, during a transition to Git, the Subversion infrastructure remains in place while users become acquianted with local Git repository interactions, local workflows, and desktop applications. -* [Topics about branch strategies with SVN](https://github.com/blog/1178-collaborating-on-github-with-subversion) -* Patterns for updating `trunk` or GitHub default branch equivalent +The `git svn` command permits users to synchronize with a centralized Subversion repository host while taking advantage of all the benefits local Git command line and graphical clients have to offer. +To acquire a Subversion repository as a resulting local Git repository, download the project in its entirety with this command: -## Migrating +``` +git svn clone [svn-repo-url] --std-layout +``` -The use of `git svn` should be a temporary bridge and complete migration to Git repositories for both local and upstream destinations is optimal. +Make certain you are familiar with the targeted Subversion repository’s structure and whether it follows the standard layout or not. For non-traditional `trunk`, `branches`, and `tags` layouts, the following option switches should be specified during the `svn clone`: -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: +- `T [trunk]` for alternate main source convention +- `b [branches]` for alternate branch location +- `t [tags]` for alternate tag structure location -* Subversion commits cease prior to initiating the process -* One machine serves as intermediary during conversion -* GitHub "upstream" repository initialized and ready to receive history, branches, tags +Once the clone operation completes, you can proceed with any local Git interactions on the command line or with graphical clients. -### Git-SVN conversion method -* Create email/username mapping file -* Begin `git svn clone` -* Add `git remote add origin [GitHub-URL]` +### Synchronizing with Subversion -Run each `ref` publish separately: +Publishing local Git history back to a central Subversion repository acquired with git svn clone is performed with one command: -* Run `git push --all origin` -* Run `git push --tags origin` +``` +git svn dcommit +``` -Or upload all `ref`s (branches, tags,) to upstream: +If the hosted Subversion repository’s history possesses commits not yet in the local Git repository, the `dcommit` operation will be rejected until the commits are acquired with this command: -* `git push --mirror origin` +``` +git svn rebase +``` -### SVN2Git method +Keep in mind this action rewrites your local Git history and your commit identifiers will be different. -* Install Ruby Gem [SVN2Git](https://github.com/nirvdrum/svn2git) -* Identify the projects in the Subversion repository -* Run `svn list [svn-repo-url]` -* Start `svn2git [repo-root|repo-root/project]` -Considerations on migration: +## Understanding -* Convert "flat" history across all projects -* Utilize Git `filter-branch --subdirectory-filter` -* Migrate on a project-by-project basis -* Use `--trunk`, `--nobranches`, `--notags` or `--rootistrunk` for non-standard layouts -* Limit history from starting point ``--revision <>``, or range `--revision <>` +Subversion and Git share similar vocabularies, but the commonality often is only is command names. Behavior and functionality are quite distinct given the unique qualities Git provides as a distributed version control system when compared to the centralized aspects of Subversion. -https://github.com/nirvdrum/svn2git -### GitHub importer (Porter) method -* [Read the import tool documentation](https://help.github.com/articles/importing-from-other-version-control-systems-to-github/) -* Expose the Subversion repository publicly -* [Visit the GitHub import tool page](https://porter.github.com/new) -* Point the import tool at your Subversion, TFS, or Mercurial repository -* Create the username mappings -* Wait for the tool to work in the background and complete the conversion +| SVN command | Git command | Git behavior | +| --- | --- | --- | +| `status` | `status` | Report the state of working tree | +| `add` | `add` | Required for each path before making a commit | +| `commit` | `commit | Store prepared changes in local revision history | +| `rm`, `delete | `rm` | Prepare paths for deletion in next commit | +| `move` | `mv` | Prepare relocated content for next commit | +| `checkout` | `clone` | Acquire the entire history of a project locally for the first tim | +| | `branch` | Create local context for commits | +| | `merge` | Join branch histories and changes to working tree | +| | `log` | No network required | +| | `push` | Upload commit history to GitHub/centralized Git host | +| | `pull` | Download and integrate GitHub repository history with local on | +| | `fetch` | Download GitHub repository history with no other action | From ef3bcc6200153b013977a2aa41c39851a4bc683c Mon Sep 17 00:00:00 2001 From: jordanmccullough Date: Tue, 30 Dec 2014 12:52:35 -0700 Subject: [PATCH 2/6] Adjust cheat sheet style for column breaks/spans --- _stylesheets/page.scss | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_stylesheets/page.scss b/_stylesheets/page.scss index 2bd9e206a..98f941503 100644 --- a/_stylesheets/page.scss +++ b/_stylesheets/page.scss @@ -201,6 +201,12 @@ footer { -moz-column-gap: 4em; column-gap: 4em; + h2, h3, table{ + -webkit-column-span: all; + -moz-column-span: all; + column-span: all; + } + h1, h1+p{ display: none; } From 71c6c856ecd09e6c484630ec3904671568f99920 Mon Sep 17 00:00:00 2001 From: jordanmccullough Date: Tue, 30 Dec 2014 21:54:43 -0700 Subject: [PATCH 3/6] Nest cheat-sheet wrapper div Avoid collision and any unexpected same-div styles applying to Bootstrap container --- _layouts/cheat-sheet.html | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/_layouts/cheat-sheet.html b/_layouts/cheat-sheet.html index 5b845d8c2..67588993b 100644 --- a/_layouts/cheat-sheet.html +++ b/_layouts/cheat-sheet.html @@ -2,6 +2,8 @@ layout: site --- -
-{{ content }} +
+
+ {{ content }} +
From 30dbb0849d946e8664e0bcf3870ce4d44f87dd30 Mon Sep 17 00:00:00 2001 From: jordanmccullough Date: Tue, 30 Dec 2014 21:55:11 -0700 Subject: [PATCH 4/6] Apply column formatting with minimally invasive non-Markdown --- downloads/subversion-migration.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/downloads/subversion-migration.md b/downloads/subversion-migration.md index f99267cc7..c9cc9401b 100644 --- a/downloads/subversion-migration.md +++ b/downloads/subversion-migration.md @@ -4,8 +4,8 @@ title: Subversion to Git Migration byline: When migrating from Subversion to Git, there’s a vocabulary and command set to learn, in addition to the new capabilities only afforded by Git. This cheat sheet aims to help you in your transition between the classic Subversion technology and the modern use of Git with the GitHub collaboration platform. --- +{% capture migration %} ## Migrating - ### GitHub importer For Internet-accessible projects, GitHub.com provides Importer for automatic migration and repository creation from Subversion, Team Foundation Server, Mercurial, or alternatively-hosted Git version controlled projects. @@ -33,8 +33,13 @@ Notable features of SVN2Git include: Learn more about SVN2Git at the project’s official home page: [https://github.com/nirvdrum/svn2git](https://github.com/nirvdrum/svn2git) +{% endcapture %} +
+{{ migration | markdownify }} +
+{% capture bridging %} ## Bridging ### Leveraging Git’s support of SVN @@ -72,6 +77,11 @@ git svn rebase ``` Keep in mind this action rewrites your local Git history and your commit identifiers will be different. +{% endcapture %} + +
+{{ bridging | markdownify }} +
## Understanding From 079996bd45c55c108d773c18b06f28a26f09c7b0 Mon Sep 17 00:00:00 2001 From: jordanmccullough Date: Tue, 30 Dec 2014 21:56:23 -0700 Subject: [PATCH 5/6] Remove all specialized cheat-sheet styling Favoring site-wide styles and Bootstrap container and column layouts over specialized `column-count` that results in unexpected overflow. --- _stylesheets/page.scss | 35 ----------------------------------- 1 file changed, 35 deletions(-) diff --git a/_stylesheets/page.scss b/_stylesheets/page.scss index 98f941503..85a43aa65 100644 --- a/_stylesheets/page.scss +++ b/_stylesheets/page.scss @@ -190,38 +190,3 @@ footer { } } } - - -.cheat-sheet{ - -webkit-column-count: 2; - -moz-column-count: 2; - column-count: 2; - - -webkit-column-gap: 4em; - -moz-column-gap: 4em; - column-gap: 4em; - - h2, h3, table{ - -webkit-column-span: all; - -moz-column-span: all; - column-span: all; - } - - h1, h1+p{ - display: none; - } - - h2:first-of-type{ - margin-top: 0; - } - - h2:last-of-type{ - -webkit-column-span: all; - -moz-column-span: all; - column-span: all; - - padding-top: 1em; - margin-top: 1em; - border-top: solid 1px $mono-light; - } -} From a1d018ad057e8fea669fb113828747c19f36b14d Mon Sep 17 00:00:00 2001 From: jordanmccullough Date: Tue, 30 Dec 2014 21:58:50 -0700 Subject: [PATCH 6/6] Fix code-block Markdown on comparison table --- downloads/subversion-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/downloads/subversion-migration.md b/downloads/subversion-migration.md index c9cc9401b..c59245342 100644 --- a/downloads/subversion-migration.md +++ b/downloads/subversion-migration.md @@ -93,8 +93,8 @@ Subversion and Git share similar vocabularies, but the commonality often is only | --- | --- | --- | | `status` | `status` | Report the state of working tree | | `add` | `add` | Required for each path before making a commit | -| `commit` | `commit | Store prepared changes in local revision history | -| `rm`, `delete | `rm` | Prepare paths for deletion in next commit | +| `commit` | `commit` | Store prepared changes in local revision history | +| `rm`, `delete` | `rm` | Prepare paths for deletion in next commit | | `move` | `mv` | Prepare relocated content for next commit | | `checkout` | `clone` | Acquire the entire history of a project locally for the first tim | | | `branch` | Create local context for commits |