New Repository Migration Guide

GITHUB PROJECT NAME CHANGES ARE COMPLETE.

If you cloned one of our projects prior to August 21, 2015 at 3:50 PDT, you will need to follow the instructions below to rebase your clone onto our new project of the same name. I.e., of you had cloned 'collect' prior to that time, the project you had cloned is now named 'collect-bad', and a new project with corrected change histories in now in its place; follow the instructions below to adjust your clone to point to this new, corrected, 'collect' project.

---

After our migration to GitHub, Jonathan Jackson discovered that the import process had broken history links, causing git-blame to incorrectly abbreviate its change reporting.

We have remigrated all of our projects using this fast-export tool. The remigrated versions of the repositories have the original repository names. The old versions with bad history have "-bad" appended to the end of their names. For example, androidcommon is the newer, fixed version of androidcommon-bad.

If you have cloned or forked the old version of our repository with the bad history you will want to switch to using the new version. If you haven't committed anything, just delete the old repo and clone/fork the new one. This is likely the case for MOST people.

If you have commits you want to preserve, we have provided migration steps below followed by an example scenario.

Migration Instructions

1. Each branch that you have committed to will need to be migrated individually. Choose a branch to begin with and proceed to the next step (the order you migrate shouldn't matter).

2. Clone the fixed version of the repository. Checkout the corresponding branch you want to update.

   git clone git@github.com:opendatakit/<repository-to-clone>.git
   git checkout <branch-to-update>
   

3. Find the common ancestor of your branch and the new branch. Note that the commit messages are the same but the git hashes are different (because of the different histories). Make a note of the git hash of both your repositories' version of the common ancestor commit and the newer repositories' version.

4. Reset all the commits on the new repository branch that have occurred since the common ancestor. There are steps to add these back at the end of this guide, if you choose to do so.

   git reset --hard <new-version-git-hash>
   

5. Add a remote link in the new repository that points to your old version of the repository. Note that this can point to a remote server or the local version of the repository on your file system.

   git remote add oldrepo <path-to-repo>
   

6. Fetch the old version of the branch you want to update.

   git fetch oldrepo <branch>
   

7. Rebase your commits onto the new version of the branch. Since the two versions do not technically share a common history (they have new git hashes), you will need to use the git hash you saved earlier to specify where to apply the rebase. You will also need to force this new hybrid version of your branch to be the canonical version.

   git rebase <old-version-git-hash> oldrepo/<branch> --onto <branch> --committer-date-is-author-date
   git branch -f <branch>
   

8. At this point if you check your history you should see that the new repository now has your commits in the exact state they are in the old repository. If you want the commits that you removed in step 4, you can merge them or rebase as you normally would when a new commit is pushed.

   git pull origin <branch>
   

or

```
git pull --rebase origin <branch>
```

1. Repeat this process for all other branches you have committed to.

Example Migration

Below I will complete the above steps using an example scenario.

1. Let's assume that I have been working on androidcommon. I have made two of my own commits on the development branch.

2. Clone the new version of androidcommon and check out the development branch.

   git clone git@github.com:opendatakit/androidcommon.git
   git checkout development
   

3. Let's assume the common ancestor is the commit with message "Migrated some tasks to common gradle config". The old version's git hash is 6ba63c0 and the new version's is 96798e4.

4. Reset back to 96798e4 on the new repository.

   git reset --hard 96798e4
   

5. Add a remote link in the new repository that points to your old version of the repository. Below you'll see a path on my local system, but you can point to any URL that you can clone from (for example git@github.com:/androidcommon)

   git remote add oldrepo /home/jbeorse/workspace/odk-test-migration/androidcommon
   

6. Fetch the old version of the development branch.

   git fetch oldrepo development
   

7. Rebase your commits onto the new version of the branch.

   git rebase 6ba63c0 oldrepo/development --onto development --committer-date-is-author-date
   git branch -f development
   

8. Let's imagine I wanted to merge all the latest changes onto the development branch.

   git pull origin development
   

You should now be fully migrated.