I did it. I caved and I bought myself one of the new MacBook Pros with the scissors keyboard switches. (Which hopefully mean I can leave the house with my laptop without living in fear.) But that meant I had to migrate all my files and settings to this new machine.

I like setting things up from scratch and starting with a completely new setup, but that’s rarely feasible these days. Between my Linux VMs, my Git repositories, and even all the fonts I have installed, setting up a new machine would be a laborious practice.

So I used Migration Assistant for the first time. I wanted to write some tips and tricks about this process, because Apple’s kbase article isn’t particularly clear. And next time I need to do this, I’ll refer to this post as a starting point.

In the past, I’ve used SuperDuper to handle my migrations. That takes a lot of time and often encounters strange bugs. Rather than go down that route this time, Migration Assistant — which I’ve only ever heard good things about — seemed like a good bet.

But it’s not all smooth, of course. Here are some tips, tricks, and gotchas about this migration.

  1. Everything from your user account appears to get migrated over. This even includes anything you may have installed on the command line, which is great. It included all my virtual machines, which is also great. It does not include the cache, which is also probably for the best.
  2. It does not appear to matter if one machine is on a different OS from the other. I upgraded from Mojave to Catalina and, for the most part, everything went smoothly. (Related: Catalina is nicer than I thought it would be, although I’m unsure how to approach Zsh.)
  3. The fastest way to do this is to boot up your old machine in target disk mode and connect them via a cable. If you just run Migration Assistant on your old machine, the entire process will run over wifi. That’s too slow and unreliable for my liking. Boot into target disk mode and save yourself some trouble.
  4. Target disk mode means you can connect your two machines together with a good old Thunderbolt or USB‑C cable. You can use the USB‑C cable that came with your Mac. Generally, that’s a good idea. I bought this Thunderbolt cable to make this process faster, but the transfer was never faster than 90mb/​s. And you don’t need Thunderbolt 3 for that throughput. USB‑C will be just fine. (Because of this, I’ll be returning the cable I bought.)
  5. Most of your software does not need to be re-authenticated. 1Password, for example, was automatic. This was very nice.
  6. Some software, like Office, needs to be re-activated. Office is the only major culprit I’ve found, but I like to fix this stuff right away, so give each of your major apps a first-run experience. 
  7. If you use Git, you’ll need to hop into your directories and run git status to force the connection. (Or, at least, I had to.)
  8. I don’t know if this was because of Catalina or because of Migration Assistant, but I had to upgrade my VM software (VirtualBox) to the latest version. The documentation said to uninstall VirtualBox and re-install it. Uninstalling VirtualBox did not work, but reinstalling it did. If you encounter any issues with your local server setup (i.e. Homestead for Laravel or anything like that), your VM software is likely corrupted from the transfer.
  9. Similarly, Creative Cloud breaks when you run Migration Assistant. (It refused to let me log in and kept crashing.) I couldn’t uninstall Creative Cloud because that required uninstalling and later re-installing Lightroom Classic, Photoshop, Lightroom, InDesign, Illustrator, Première, and Audition. Ain’t nobody got time for that. It turns out, if you simply run the Creative Cloud installer again, the CC app will run without issue.
  10. None of your wallpapers migrate (boo!), but all your virtual desktops and their settings do (yay!).
  11. Finally: if you run Backblaze, read their kbase article before upgrading or you’ll have a rough time.