Documentation

Migrating from Git

Migrate projects from GitHub to Unity Version Control.

Read time 19 minutes

Last updated 21 days ago

Intro

Unity Version Control System (UVCS) is a full-featured DVCS (Distributed Version Control Software). And, UVCS also speaks the Git network protocol. UVCS can push and pull changes directly to any remote Git server. This is because UVCS supports the

https://

and

git://

protocols for pushing and pulling changesets. This feature immediately turns UVCS into a DVCS fully compatible with Git. The advantage of this is that you can use UVCS or Git on your workstation and still participate in Git projects (GitHub, CodePlex, and many more).

What is GitSync?

This can be a first approach: GitSync is a native Windows DVCS connected to GitHub. So, it virtually turns UVCS into a full-fledged Windows client for Git.

Note

GitSync is not technically a new Git client: You would be using UVCS on the client-side but can push/pull to Git servers (using https or Git protocols).

Imagine that you're a developer using GitHub (or Bitbucket, or maybe CodePlex). In any case, there are things you like: using a cloud-based repository for your code and Windows to develop. And things you don't like: being forced to use the CLI and lacking really awesome GUI tools. So, you wish you had everything: Cloud repositories, the DVCS power, and awesome tools for Windows. That's what you get with GitSync.

Feature list

The capabilities of GitSync are:

Direct push/pull: Including all commits, comments, branches, merge tracking, and tags.
Adding/deleting or moving files: No limits at any of the two sides.
Full merge tracking: You can merge on the Git side, and UVCS will recognize the merge tracking. And, the same is true in the UVCS-to-Git direction. That's the benefit of UVCS and Git being full DVCS!
Conflict management: You can make changes on the same branch on the Git and UVCS sides concurrently and UVCS will handle the data exchange, pull the changes, request the user to run a merge, then push the solved conflict (as you'd do if you just were using a full Git setup).

How does it work?

An entire push and pull process will show you GitSync works.

Initial scenario

You have a Git repo, and you pull it on UVCS. As a result, you get an exact clone with the branches and commits you had in Git now converted to UVCS, and what's best about this is UVCS is able to render those branches and commits in the Branch Explorer:

Creating a new commit in the Git repo

The following image shows what happens when a new commit is created on the Git side and how the pull from UVCS retrieves it. Instead of just performing a simple change, the figure shows a merge from

big\_feature

branch into master. The result in UVCS mimics what happened at the Git side, adding the merge link (which is rendered as a green line) on the UVCS Branch Explorer:

How GitSync works - Creating new commit on the Git side

Creating a new changeset in the UVCS repo

The next step is performing a change in UVCS and pushing the change to Git. To create a more complete example, a merge will also be made instead of just creating a new changeset. The changesets 6 and 7 are created on the UVCS side, then they're pushed to Git. As you can see in the figure below, the merge information (multiple parents on the Git repo) is also sent from UVCS to Git.

How GitSync works - Creating new commit on the UVCS side

So far, the changes were done at one side or the other, but not at the two sides concurrently.

Performing changes concurrently: conflicts

The following picture shows what happens when developers work on the same branch at the same time. A new commit is created in Git (on green) and another in UVCS (orange):

If the UVCS developer tries to push to Git, an error will show up since there are conflicting changes (which would happen on a similar scenario on a pure UVCS or pure Git setup). The steps to follow are:

First, pull the changes from Git.
A new "subbranch" will be created, placing the 88ffa changeset correctly.

The next steps will be resolving the merge conflict at the UVCS side and then completing the push:

Both repositories will look the same at the end of the interaction and let developers work together on both sides.

Note

Since UVCS is a full DVCS (like Git), it can clone a Git repository and later push changes to it... entirely! We do not restrict to a single branch. You can create branches on UVCS and push them to Git and create branches on Git and pull them to UVCS.

The gitsync.conf file

The GitSync configuration file (

gitsync.conf

) lets you include information automatically used during the GitSync operations. This information is related to the mapping between two UVCS and Git objects:

User accounts
Xlinks/Submodules information

Important

The

gitsync.conf

file must be located in:

In the UVCS client folder.

In the

plastic4

directory (under

$HOME/.plastic4

on Linux/Mac systems or

C:\Users\_user_\AppData\Local\plastic4

on Windows).

Mapping user accounts

In the

gitsync.conf

file, we can define a mapping between UVCS and Git (emails). This information will be used as author and committer when committing to Git. This info is added on the

email-mapping

section in the following format:


plastic_user = git_email_address

An example of

gitsync.conf

file:


[email-mapping]asalim = asalim@mymailprovider.comubuntu = ubuntu@linuxprovider.com

Mapping UVCS Xlinks and Git submodules

A Git submodule is just a pointer to a commit in a different repository. It doesn't propagate operations between submodules or handle the branching between the repositories, so this very basic information is enough for the submodules work. A UVCS Xlink object is more complex than the Git submodule: the Xlinks allow the user to set relative servers, set rules for the branch expansion, and define whether the Xlink is writable or not. In general terms, we can say that Git submodules and UVCS Xlinks have the same mission: pointing to a commit in a different repository. So a direct mapping can be established between:

A Git commit ↔ A UVCS changeset
A Git repository URL ↔ A UVCS repository specification

GitSync lets you create UVCS Xlinks from Git submodules and vice versa. The Git submodules and the UVCS Xlinks can be synchronized using GitSync:

The Git submodules are converted into UVCS Xlinks during the pull operation.
The UVCS Xlinks are converted into Git submodules during the push operation.

Before synchronizing a repository with Xlinks/Submodules, the target repositories must be synchronized. To synchronize a repository with Xlinks/Submodules, the mapping information must be added on the

gitsync.conf

file. This info is added on the submodules section with the following format:


git_repository_url -> plastic_repository_spec [writable:true|false] [relativeserver:true|false]

If the Git submodule has to be converted on a writable UVCS Xlink, the
```
writable
```
field must be included as
```
writable:true
```
. If the
```
writable
```
field is omitted or set to false, the Xlink is created as read only.
If the Git submodule must be converted on a UVCS Xlink with a relative server, the field
```
relativeserver
```
must be included as
```
relativeserver:true
```
. If the
```
relativeserver
```
field is omitted or it is set to false, then the Xlink is created against the UVCS repository server (as non-relative Xlink).

This would be a valid configuration example:


[submodules]git://localhost/code -> code@localhost:8084 writable:true relativeserver:truegit://localhost/doc -> doc@localhost:8084 writable:false relativeserver:true

GitSync restrictions

Two Git operations are restricted when using GitSync:

```
rebase
```
command
```
merge
```
(fast-forward) command

These Git commands don't take into account the history of your changes. Although the user can work in a parallel way, Git talks about history like something linear. But UVCS prioritizes keeping the changes history. UVCS takes into account the whole history of the changes you make. This means that UVCS doesn't rewrite history (a design decision). The changes history is reflected when working on branches and merging. Because UVCS can solve and show how the history is, we recommend you avoid using those Git commands when working with GitSync.

Rebasing is a subtle topic in Git - You can only do it before you push (in fact, many recommend that you never use it). Most of the time, it is used to understand the history without going crazy with all the merging:
GitSync restrictions - Git rebase

Note
We don't handle rebases in Git fashion.
The Git fast-forward merge command does something similar, linearly solving the merge:
GitSync restrictions - Git fast-forward merge
Note
Use the
merge --no-ff
command to keep the history.

UVCS has the Branch Explorer, which lets you understand what is going on graphically. This way, you are not distracted and you don't miss rebasing. When you diff a branch with several merges, it is hard to see what you really changed on the branch and what comes from the merge... this is also solved in UVCS:

Important

We recommend not using the Git rebase and merge (fast-forward) command to avoid issues when synchronizing your UVCS-Git repositories.

In general, do not use those commands that rewrite the history of the repository. For example, delete or move changeset, delete or move labels.

Direct push-pull

As we've seen previously, UVCS can push and pull directly to remote Git servers using both native Git and HTTPS protocols, including well-known sites such as GitHub, BitKeeper, CodePlex, and many more. When we started developing the Git-bidirectional synchronization with UVCS, we had the following scenarios in mind:

Developers already using UVCS want to contribute to projects on GitHub, CodePlex, BitKeeper, and others.
Developers working on teams using Git as a primary server prefer to use UVCS but need to contribute changes back to the main server.
Teams gradually adopting UVCS need to contribute to other teams on Git.

We went the hard way for a solution: we didn't come up with some sort of intermediate script to convert changes from one system to the other or do fast-import/export, imposing a ton of limitations. But we actually implemented was the Git network protocols in UVCS as a layer able to directly pull and push to Git. UVCS starts a negotiation phase with the remote Git server, as a Git command would do, speaking the Git protocol. It is a core feature, not an add-on script. As we've said, GitSync implements the smart-protocol and:

It can negotiate with a remote Git receive-pack to upload data (negotiating which changesets/commits are needed and generating the correct pack file from UVCS repository data to be sent to Git).
It can also negotiate with a remote upload-pack to decide which commits need to be packaged, download the pack and import it into UVCS.

The first pull

Let's start by connecting to a GitHub repository.

If you go to GitHub and browse the repos, you'll probably find a list of "trendy" repos. The corefx repository is used in the example below:

GitSync - First pull - Select GitHub repo

Now, to pull it to UVCS, a repo is created to "host it" (called corefx too) and in the initially empty Branch Explorer, the context menu option to launch Sync with Git:

Then you launch the Sync dialog (which is very similar to the replication dialog to push/pull changes between UVCS servers) and enter the URL of the Git repo. No need for credentials now since we're just pulling (cloning) from a public repo. You'll need to specify them if you need to push, and the server requires you to be an authenticated user.

Note

If you use Github and need authentication, you must use a token and not a password. For more information, see Creating a personal access token

Press Sync, and the process (pull) will start up as follows:

Note

This operation can be done by using the command line in the following way:

cm sync corefx git https://github.com/corefx/corefx.git

Assuming the local corefx repo is empty, it will calculate the changesets and branches it needs to pull from the remote GitHub repo and will pull them:

GitSync - First pull - Sync command line

To pull new changes done on the GitHub side, simply re-run the same command, and it will now calculate and pull only the new changes made on the Git side if any.


cm sync corefx git https://github.com/corefx/corefx.git

You're currently pulling Git changesets and branches directly to your local UVCS repository:
Once the replication is complete, go back to the workspace explorer and update the workspace to download the source files.
Refresh the Branch Explorer and you'll be able to render the just imported Git changesets in a typical UVCS way:
And now, right-clicking any changeset (commit in Git jargon), you'll be able to check differences with our built-in diff system:

Now you're ready to do more changes in UVCS, whether branches, merges, anything. Then repeat the same process to sync to Git (which will in turn push or pull changes and even ask you to solve merges before pushing back to Git if concurrent changes were done on the same branches).

Pushing to Git

We're going to push one of our UVCS repositories to GitHub. This process is similar to the previous one.

Create a new GitHub repository to export your UVCS repository to GitHub:
In this example, the dokancode UVCS repo is used. In the Branch Explorer view, right-click one of its branches and select the Sync with Git menu option:
The Sync dialog will be launched.
Enter the GitHub repository URL and the credentials if needed:
Click the Sync button to start the synchronization. In this case, you're pushing (or exporting) your UVCS repository:
We're currently pushing UVCS changesets and branches directly to my GitHub repository.
Note: This operation can be done by using the command line in the following way:
```
cm sync dokancode git https://github.com/mbctesting/dokancode.git
```
Assuming the GitHub dokancode repo is empty, GitSync will calculate the changesets and branches it needs to push from the UVCS repo, and will push them:
Once the push operation is finished, you can see a summary of the objects that have been exporting:
If you go back to GitHub and refresh the dokancode repository, you'll see the exported objects from UVCS:

Now you're ready to work with the repository in both sides: UVCS and GitHub. You'll be able to create branches, do changes, and synchronize again by pulling/pushing.

Working on both sides

This section explains how to work with the dokancode repo, in the GitHub and UVCS sides, applying some basic operations. Important! Before performing any changes at either of the sides, you must synchronize your repo (using the Sync with Git action) to avoid conflicts.

Changes on the Git side

As an example, some operations will be run on the master branch:

Delete the license.txt file:
Edit the dokan-net-0.6.0\readme_dokan.txt file:
And move it to dokan-net-0.6.0\DokanNet folder:
And then, create a new branch (scm007).
Add two new files:
And edit one of those files:

The commits are done, and you can see them on the UVCS side. GitSync can calculate what's new on the other side, negotiate with the remote server, and push the changes.

Go to synchronize the UVCS repo with the GitHub one by running Sync with Git:
By clicking Sync, the synchronization will begin and will pull to the UVCS repo the changes you performed on the GitHub side:
Once the synchronization is complete:
You can see a summary with the imported objects:
If you go back to the Branch Explorer and refresh the view, you'll see the changes done on GitHub that have been imported to UVCS:
You can open the Changesets view to see these GitHub changes:
And, if you want to go deeper, you can confirm the changes done with the readme_dokan.txt file on GitHub. You can see the history of that file to check that those changes have been applied with the synchronization:

Now you can continue performing changes on UVCS.

Changes on the UVCS side

As an example, changes are made to the scm005 branch. At this point, both the Git and UVCS have the same content. You can check it on both sides:

In this branch:

Add a new file:
Edit the DokanOperation.cs file:
These are the new changes:
Once the changes are done, synchronize the GitHub repository by running Sync with Git:
Once the synchronization is done, you can see the summary:
The summary tells you that the synchronization has sent two changesets involved in one branch:
If you go to GitHub, you can see these new changes that were done on UVCS:

UVCS and Git branches conversion

Note that the UVCS main branch is mapped to the Git master branch. This mapping is also considered for the children branches of main on UVCS. This means that the UVCS branches are converted into Git branches by removing the hierarchy and replacing the / with -. And this rule is also valid when a Git branch is converted into a UVCS branch: the - character is used to recreate the hierarchy in UVCS. In the examples before, the UVCS branch /main/scm005 is converted to master-scm005. And the Git branch scm007 under master is converted to /main/scm007:

The - character is also allowed as part of the branch name like the following examples:

Branch - Git side	Branch - UVCS side
master	/main
master-fix-5.0	/main/fix-5.0
master-fix-5.0-task1	/main/fix-5.0/task1

Full merge tracking

Since UVCS handles the same concepts as Git (DAG, commits, merge links, and so on), it is straightforward to share the merge tracking. You do a merge in Git, you can get it back to UVCS. If you do a merge in UVCS, you can even push the merge link back to Git. The most difficult feature for us to handle is the "precise item tracking"; we do (and Git doesn't). UVCS has an internal id associated with each file and directory. It means we can easily handle tons of merge conflicts that are hard to track for Git (like a divergent move, something trivial for UVCS). In the following examples, you'll see how the merge tracking works when using GitSync.

Merge on the UVCS side

In the following example, two branches are created:

Branch scm008 - The DokanResetTimeout method is edited in the DokanNet.cs file, moved, and a new field is added:
Branch scm009 - The DokanNet.cs file is moved to another folder, then the method DokanResetTimeout is moved to another class and edited:
Once the changes are done on different branches, they'll be merged to the main branch:
Now the repositories will be synchronized on both sides using the Sync with Git. This will push the merges on the Git side.

The new branches have been pushed and the merge tracking looks like this on Git:

Merge on the Git side

Now we're going to see how a merge in Git is tracked on UVCS.

Create new branch in Git, create a new file and edit another one:
Once the commits are done, perform a merge from the branch (in this case, scm010) to the master branch:
Note: The merge is done using the --no-ff option as we've seen in the GitSync restrictions section.
The merge is complete, and these changes have to be pulled to the remote Git repo:
Once the local Git changes have been pulled to the remote Git repo, synchronize your repos. This means that the latest changes will be pulled to the UVCS repo. Run Sync with Git:
Refresh the Branch Explorer once the synchronization is finished. You'll see how the changes and merge done on Git have been pulled into UVCS:

Conflict management

As seen in the How it works section, you can make changes concurrently both in UVCS and Git. This means that you can work on the same branch on the two systems and reconcile changes (as you do when using a pure UVCS or Git environment). In the Changes on the Git side section, some changes were made on GitHub:

In the master branch - The license.txt file was deleted, the dokan-net-0.6.0\readme_dokan.txt file was edited, and moved to the dokan-net-0.6.0\DokanNet folder.
Then a new branch was created (scm007) where - two new files were added (ArrayIndex.cs and ArrayInitialization.cs) and (ArrayIndex.cs) was edited.

Now, to perform some changes in UVCS:

In the main branch, edit the DokanNet.cs file:
Add 3 new files:

Once the changes are done, synchronize both repos using Sync with Git:

GitSync - Conflict management - Sync with Git

When the synchronization is finished, a message will pop up saying a merge is needed.

GitSync - Conflict management - Merge needed

This is because we made some changes in the same branch in Git and UVCS. In the summary, you'll see that the main (or master) branch is the one that requires a merge operation:

GitSync - Conflict management - Merge needed - Summary

Changes were made in the master branch in Git, and some other changes in the main branch on the UVCS side. Remember, that main and master is the same branch but using different names (see the Git-UVCS Dictionary for further information). As seen in the How it works section, you have to resolve the merge conflict at the UVCS side.

If you update the Branch Explorer, you'll see that:
- First, the main branch has multiple "heads" that must be merged. This is because these conflicts are handled as a subbranch in UVCS.
- Second, the scm007 branch has been synchronized (pulled from GitHub to UVCS).
To solve this conflict, run a merge from the "GitHub" head (the head of the subbranch):
The changes that are going to be merged:
Click the Process all merges button to automatically merge all items.
The last step is to checkin (confirm) the changes in the Pending changes view:
Once you click the Checkin button, you'll see that the two "heads" are merged into only one head, the one from the main branch:
The merge conflict is now solved. Complete the synchronization by pushing in the Git side the changes done in the UVCS one. This is done by using Sync with Git.

Once this operation is finished, both repos are fully synchronized. This means that you have the same content on both sides.

SSH protocol support

GitSync supports sync with Git repositories using the SSH protocol. The SSH protocol lets you connect and authenticate to remote servers and services.

Prerequisites

To use this feature:

You must have the command line SSH client ssh in your PATH environment variable.
You must add your private SSH key to your ssh-agent. Follow these instructions to add your SSH key to the ssh-agent. The SSH agent now manages your SSH keys and remembers your passphrase.

How to use it

You can use GitSync the same way as you usually do with HTTP protocol, by using the UVCS GUI or the CLI. Let's see an example. If you use the command line, you have to specify the URL accordingly for the SSH protocol:

$ cm sync rep2 git git@github.com:PlasticSCM/Myrepo.git

instead of the HTTPS one:

$ cm sync rep2 git https://github.com/PlasticSCM/Myrepo.git

Migrating from Git

Intro

What is GitSync?

Feature list

How does it work?

Initial scenario

Creating a new commit in the Git repo

Creating a new changeset in the UVCS repo

Performing changes concurrently: conflicts

The gitsync.conf file

Mapping user accounts

Mapping UVCS Xlinks and Git submodules

GitSync restrictions

Direct push-pull

The first pull

Pushing to Git

Working on both sides

Changes on the Git side

Changes on the UVCS side

UVCS and Git branches conversion

Branch - Git side

Branch - UVCS side

Full merge tracking

Merge on the UVCS side

Merge on the Git side

Conflict management

SSH protocol support

Prerequisites

How to use it