Migrating From One macOS Install to Another and Setting Up Your Developer Environment

Got a shiny new Mac or Hackintosh setup and want to move stuff to your new setup? Having issues that you just can't fix and want to reinstall macOS? Just sick of all the clutter and want to start over? This guide is for you.

This guide assumes that you're reinstalling macOS on the same Mac, so if you're going from one Mac to another you can take some shortcuts. Don't think that you have to follow every step; every user is different, so just follow the steps that apply. If you just use your mac for web browsing and email, this will still work for you-- just skip the steps that look foreign to you.

Backup

Make a list. On your backup media, create a new text file. This is where you'll store information that you need for the eventual restore. Many of these Backup steps involve taking note of something, and this is a good place for it.
Put away your stuff. I use the desktop as a kind of temporary active workspace. I’ll stash things there for easy access if I’m going to be using it soon, but I’m not always diligent about putting away my toys when I’m done. Delete stuff on your desktop or move it to where it should be. If you use the desktop for more permanent storage, be sure to include it in step 5.
Make note of open browser tabs, or save them. I frequently keep open tabs for things I want to follow up on but don't have time or drive to do them when I first opened them. Don't do this. This is bad practice, and a crash bad enough to mess up your browser session will make you lose all of your tabs. But yeah, I'm guilty of it. These are generally things that I don’t want bookmarked and I never remove "temporary" bookmarks, leading to quite a mess, so I tend to have that massive mess of tabs. If you're like me and you leave a ton open, this step is for you. Go through them and close any you don't need, then if you have a browser that will sync bookmarks to the cloud you can save them to a new bookmark folder (and maybe confirm on another device that they're synced before wiping your system). If not, just copy/paste them into your note.
Pre-backup steps to make things easier
- Show hidden files. By default you probably don’t want these shown, but there might be some hidden files you need now, so run this and relaunch finder to show you those files:
  defaults write com.apple.finder AppleShowAllFiles YES
  Alt/Option + Right Click on the finder icon and relaunch it.
- Consider running Onyx or CCleaner to clean up user caches. This will make your backups smaller. There’s no reason to copy most application caches. USE THESE TOOLS CAREFULLY. You can do some damage with them if you aren’t careful. Do not use this to clean your Downloads folder, we’ll be getting to that in another step.
- Consider using Disk Inventory X to see what’s using up the most disk space in your home directory and remove things you don’t need.
- Inspect the files in your Downloads folder. If there are things you want to save and have a better place for them, move them there now. Remove things that you don’t need, are obsolete, or that you can easily download again. This step is up to you. For my use case, it makes sense to include this folder in the backup for some things, but you almost definitely won’t need all of it.
Backup the essentials. This will differ based on your use case. Open your Home folder and you’ll see a ton of stuff you aren’t used to seeing since you’ve un-hidden the hidden files. Backup all of these files to external or network storage. This will probably be the longest step. Luckily you can do the next few while you wait. You can either choose to back up all of this just in case, or get more granular if time and disk space on your backup device are a concern. Be sure to get these default folders in your home directory.:
- ~/Applications (again, in your home directory. You probably don't want the system Applications directory since you can just download/reinstall those (see step 6). if you have any user apps, grab this directory)
- ~/Desktop (if there’s anything left on your desktop)
- ~/Documents
- ~/Downloads (that you’ve previously cleaned out)
- ~/Library (you won’t be restoring this in its entirety, but it’s good to have around)
- ~/Movies (if you store movies here)
- ~/Music (if you keep your music here or use iTunes)
- ~/Pictures
  And then get any other folders you may need. These are mine, but yours may differ. Look for any application settings files/folders (these will begin with a .) that you think would be hard to re-create. If you use Mackup (see step 9) you can automate some of these but too many backups is far preferable to not enough
- ~/.atom
- ~/.bash* (there will be a few for bash)
- ~/.get_iplayer
- ~/.oh-my-zsh
- ~/.pia_manager
- ~/.ssh
- ~/.zsh* (there will be a few for zsh)
- ~/Calibre Library
- ~/Dropbox (yes, I could wait for this to download itself but it’s quite large)
- ~/projects (where I store my dev work)
- ~/scripts (a folder where I store various scripts I’ve written/downloaded for specific tasks)
Note installed applications. Run ls /Applications to get a list of all installed applications. As in step 5, save this list so you can ensure you are getting all the previous applications installed. If any of these are huge or a hassle to re-download, consider backing them up.
Get your Homebrew list. If you use homebrew to install things, run ‘brew list’ and save the output to make it easier to install them when you’re up and running on the fresh install. ‘brew cask list’ will do the same for any casks you’ve installed.
Time Machine exclusions. Make a note of your Time Machine exclusions so you can add those to your new setup.
Consider using Mackup. This is an optional step but makes things a bit easier. Mackup will back up many of your dotfiles and other preferences to Dropbox (or other optional cloud storage providers) and symlink them on your system. Any changes will automatically go to Dropbox. If you have homebrew install it with

brew install mackup

Then kick it off with

mackup backup
If you don't use Dropbox, consult the documentation for setting it up with different providers. This is good to keep around and occasionally run mackup backup to get new supported files backed up.
One last full system backup. Make sure Time Machine is finished. Better yet, kick off a fresh backup once you’ve completed everything above. If your manual backups and Time Machine backups are both going over the network or to the same device, you may want to wait for the backups from step 4 to finish before kicking this off. You won’t be restoring from Time Machine so that you can keep that new computer feel, but you may need to grab some stuff from it. If you use other cloud storage services (Dropbox, Google Drive) make sure they’re finished as well.
Check it twice. Look over the list you've made and double-check everything. Ensure that this list is safely on your backup media and not on the hard drive you're going to wipe soon. Go back over your home folder and make sure you have everything backed up that you want.
Prepare USB media to install macOS. You may be able to do this from a recovery partition, but sometimes whatever is causing you grief has affected that as well. This gives you a bootable USB drive to install macOS. First you must download the latest version from the app store (currently Sierra) but DO NOT start the install from this app. Then…
- Connect the USB drive
- Open Disk Utility and format the drive as follows:
  - Mac OS Extended (Journaled)
  - GUID Partition Mac scheme
  - Named ‘HighSierra’
- From the terminal, paste this command: sudo /Applications/Install\ macOS\ High\ Sierra.app/Contents/Resources/createinstallmedia --volume /Volumes/HighSierra --applicationpath /Applications/Install\ macOS\ High\ Sierra.app --nointeraction
- Type your password and wait!
- Wait some more.
- It will eventually tell you it's complete.

Now, boot from that bad boy and install macOS! Once the installer finishes booting, be sure to use Disk Utility to erase your drive before installing, taking care not to erase your Boot Camp partition if you use it.

Setting up the New macOS Install

Once you're in the brand new fresh install of macOS, follow these steps (as they apply to you) to get back up and running.

Optional Paranoia Security

This one is for the security conscious / paranoid. If you don't plan on using a firewall or VPN of any kind, skip this one.

After the initial setup is complete, pick and choose any of these steps you'd like to perform...

Disconnect from the internet entirely if you're paranoid about the few minutes the next steps will take.
Turn on the Firewall in System Preferences. This protects from unauthorized incoming connections, NOT outgoing. Your router does this to a point, but if someone gets into your network, this will help stop unauthorized access.
Install an outgoing firewall like Little Snitch to allow you to monitor outgoing connections. I personally use Radio Silence which isn't as robust but focuses on simple application blocking. If you feel like getting even more nerdy with it, you can use pf and a front-end app like Murus.
Install a VPN client to encrypt your outgoing traffic. I use Private Internet Access or Windscribe, depending on whether one is saturated or acting up at the moment. You really get what you pay for with VPNs so do your homework and choose the one that's right for you. The cost is minimal for quite a bit of peace of mind.
Install a Hosts file manager. This protects you from ads/malware before they can even hit your browser. It can be an alternative to a browser extension or used together. I personally use Gasmask which lets you easily change up your hosts file, and use the Unified hosts + gambling + fakenews list from Steven Black's hosts repository.
Reconnect to the internet and fire up that VPN!

For more security considerations, please see the excellent macOS Security and Privacy Guide and pick and choose what suits you. I don't do nearly all of it and many people call me paranoid so you may do even less!

Restore

Update! Before doing anything else, get yourself updated! Check for updates in the App Store to make sure you have the latest patches.
Have a script do some things for you. If you know your way around shell scripts, you may want to start things off with a script to set some defaults. I've customized this to my needs, and run it immediately after a new install. Download it, customize it to your preferences, and run it. Be sure you read every line so that you know what it's going to do.
Make it your own. Next up, I like to take a spin through all the preference panes in System Preferences, changing things to my liking. This one is entirely up to you; you know what you like. If you did step 2 this will take less time.
Restore your files. Let's get those files copied back over! First up, run that same command from earlier to unhide the hidden files:

defaults write com.apple.finder AppleShowAllFiles YES

Then Alt/Option + Right Click on the finder icon and relaunch it. Now, browse out to your backup, and copy the contents of each of the default folders into the ones on your new install. DON'T just overwrite the folders. Occasionally you'll run into some weird issues with permissions. That may be an edge case, but it only takes a few seconds longer to be safe. Then copy over any of the other folders you think you'll need. Don't worry if you miss some stuff, you can go back to the backup to grab it later. DO NOT copy the Library folder into your new Home folder. This is only for grabbing settings that would be hard to re-create. Once you're done, hide those files again by running the opposite command:

defaults write com.apple.finder AppleShowAllFiles NO

And again Alt/Option + Right Click on the finder icon and relaunch it.
Restore Messages. DO THIS AT YOUR OWN RISK. BACKUP EVERYTHING YOU REPLACE. THIS IS FOR ADVANCED USERS OR PEOPLE WHO KNOW ADVANCED USERS. If you want to get your Messages from the old install, it's possible but a bit involved.
- On the new install, backup ~/Library/Messages to a temporary location.
- On the new install, go to ~/Library/Preferences and search for "iChat." Back up all the files that you find.
- In the same folder, search for "Messages" and back these up as well.
- Copy ~/Library/Messages from your backup to your new install.
- In your backup, go to ~/Library/Preferences and search for iChat, and copy these files over to your new install's ~/Library/Preferences.
- In your backup, go to ~/Library/Preferences and search for Messages, and copy these files over to your new install's ~/Library/Preferences.
- Reboot, and your messages should be there. Send yourself a test message and reboot yet again, to make sure the message is still there. If you don't see the messages or your test message doesn't stick around, it could indicate permissions issues. You can either choose to fix the permissions issues or restore the backup of the fresh files you made earlier.
Install your preferred applications. Now go through and install everything that you want from the list you made earlier. If you've downloaded things from the App Store, they're listed under your 'Purchased' tab. Don't be in a hurry to reinstall everything. Get the stuff you know you need, and then get the other stuff as you need it. It's possible that you have tons of stuff out here that has built up over the years that you don't need. This is entirely up to your discretion. Again, you know what you like. If you want to know what I install, here's my list:
- Browsers. Like all of them. I do web dev work so I need to see what works in each one.
- Adobe Creative Cloud (though usually not everything. I just install things as I need them)
- Bitwarden (password manager)
- Calibre (e-book manager)
- Canary Mail (an awesome mail client)
- Cryptomator (encrypted volumes that seamlessly integrate into your preferred Cloud storage)
- Dropbox
- F.lux (easier on the eyes at night)
- Garage Band
- iTerm (the best Terminal replacement)
- Kid3 (a really solid mp3 tagger)
- Kindle
- Macdown (Markdown editor)
- MP4Tools (lets you modify and repack video files)
- Parallels (Virtual Machine software)
- Microsoft Office (yeah, I know)
- Parcel (package tracking)
- Pixelmator (not quite as good as Photoshop but it's neat)
- Private Internet Access (VPN)
- Radio Silence (Firewall)
- Scrivener (for that book I'm eventually going to write)
- Simple Comic (cbr reader)
- Skype and Call Recorder for Skype
- Skype for Business
- Slack (collaboration software)
- SquidMan (a front end for the Squid proxy)
- Steam (gotta have games!)
- TextMate (I'm in love with this text editor still, even as amazing as Atom and Sublime are)
- The Unarchiver (for archives the built-in stuff won't open)
- Transmission (bittorrent client)
- Veracrypt (for standalone encrypted volumes)
- VLC (the Swiss army media player)
- VOX (AMAZING music player)
- Weather Indicator (menu bar weather app)
- Wunderlist (though I should use it more)
Set some sane Time Machine exclusions. This is my preferred list. Adjust this to your needs.

/BOOTCAMP (the Boot Camp partition. Should be added automatically if you use it)

/Applications (LARGE files, frequent changes, and all recoverable. Unless bandwidth is an issue, you shouldn't need this)

/Users/Shared/adi (Added automatically)

~/Desktop (I have frequent temp files here, some large, and I don't need this backed up)

~/Downloads (Same reasoning as /Applications and ~/Desktop)

~/Dropbox (These are already backed up in the cloud)

~/Library/Application Support/Google (You don't need your browser cache backed up)

~/Library/Application Support/Steam (Steam can get really huge)

~/Library/Caches (Temporary caches that are unneeded)

~/Library/Logs (Logs that can grow quite large and shouldn't need to be restored)

At this point, you may be done. If so, kick off that first, long-ass Time Machine backup. Read on for some more advanced steps and see if they apply to you.
Install Homebrew. If you do a lot of development or advanced stuff with your Mac, Homebrew is your homeboy. If you want to read up on what it does, visit http://brew.sh and decide if it's for you. Install it with this command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Don't run this with sudo. It will ask you for your password when it needs it. This process will also download the Xcode command line tools for you, which you'll need for various development tasks. You probably don't need the whole Xcode package from the App Store, and if you do, you already know you do and you have probably downloaded it in the last step.
Restore your Homebrew installs. Simply type brew install followed by a list of all the programs in your list from before. If you get errors you may need to tap into a specific repository. Consult the documentation for the erroring program to fix it.
Restore your settings from Mackup. If Mackup wasn't installed with the rest of your Homebrew installs in the last step, install it now with

brew install Mackup

Then kick off the restore with

mackup restore

This replaces the dotfiles and preferences on your system with symlinks to your Dropbox.
You're done restoring! Congrats! If there are any applications that you need to restore the settings for, I leave that to you. They're all in that Library folder. There are countless different possibilities here, so get comfy with your favorite search engine. Alternatively, take this opportunity to go in fresh and set them up again. You may find that your preferences have changed or find options you didn't know were there!

Setting Up the Dev Environment

From here on this guide gets even more opinionated. This is my setup, yours will be different. Many steps in the rest of this guide assume that you have Homebrew installed. Check out step 8 in the Restore section to install it.

iTerm

The default Terminal.app is not very robust. iTerm makes things much more pleasant. Grab it here: http://www.iterm2.com/

Once you're in, head to Profiles -> Terminal and make sure your Report Terminal Type is set to xterm-256color so you get some pretty colors.

Install a theme or two! My preference is Tomorrow Night by Chris Kempson

zsh

Zsh replaces the bash shell. I prefer zsh because of how much you can customize the shell, loading plugins, etc.

I use the simple oh-my-zsh to configure zsh. Some call it bloated, but it's never been anything but peppy for me.

First off, upgrade your zsh with home-brew:

brew install zsh

Then change your shell with chsh at the prompt.

Check out the oh-my-zsh github and read the documentation thoroughly. My configuration is not really extensive: here's the gist of the major changes to my .zshrc file:

ZSH_THEME="Powerlevel9k"

DEFAULT_USER="travis"

plugins=(git ruby sublime rails textmate brew bundle gem osx zsh-syntax-highlighting history-substring-search)

The big one for me is git. It can show your git status by different colored prompts.

In order to use the agnoster theme you'll need to get some powerline fonts. I use Source Code for Powerline but I tend to just grab this whole batch. You'll need to change this font in your iTerm profile under Profiles -> Text.

That should get you a highly useful and awesome looking iTerm!

TextMate

TextMate is my text editor of choice. You can grab it at https://macromates.com/.
Be sure to get 2.0! It says it's beta but it's very stable.

I also use Chris Kempson's Tomorrow Night theme for this.

There's not much to say about setting it up. I tend to move the file browser to the left but I don't change many defaults. There are plugins available for a wide variety of functionality. It doesn't come near to what you can get from Sublime Text or Atom, but there are some behaviors that I just couldn't change to my liking in those, so I've stuck with TextMate.

Eclipse

I don't love Eclipse but when writing PHP its massive extensibility keeps me coming back. What I prefer is PHP Storm, and it's semi-expensive. Worth it, but not enough for me to pull the trigger on my home setups. Shocker, I use the same theme in Eclipse that I do everywhere else, Tomorrow Night. I've tried for hours to replace some of this functionality in Atom and other editors but I always come up short. My setup changes regularly but what's always there is the eclipse color theme plugin (gotta have Tomorrow Night) and the PHP Getter/Setter generator.

Dreamweaver

Wait, hear me out. Don't leave yet! I never (ever, ever) use the WYSIWYG mode. Do you want spaghetti code? That's how you get spaghetti code. It's not Front Page bad but you're really better off writing by hand. But when I'm doing plain HTML/CSS and a smidge of Javascript, it's actually pretty nice for those situations where you're trying to get something just right. The live preview as you're writing code is very useful for those pesky situations. And honestly, the newest version is much better. Don't buy it just for this use case, but if you have an Adobe Creative Cloud subscription, it's worth keeping in your toolbox.

MAMP

MAMP is a simple-to-install and simple-to-use web server to get up and running quickly with Apache, PHP, and MySQL. If you just need to test some simple stuff out, this is a great way to get up and going fast. You'll just start this when you need it and stop when you're done. Don't try to host anything important on this. There are "better" ways of doing this. This is just the quick and dirty route.

GNU Core Utilities

On to the fun stuff! If you're in the Terminal a lot, you'll want more up to date core utilities than the golden oldies that come with your Mac. Make use of that awesome iTerm you set up earlier and fire off this to update them:

brew install coreutils findutils

To get these working, you'll have to add this to your .bash_profile

export PATH="/usr/local/opt/findutils/libexec/gnubin:$PATH"

Vim/Neovim

I don't always use vim, in fact I should get more used to it. I can feel the power under my fingertips but it takes some getting used to. The version of vim installed by default is an older model (you'll notice this pattern a lot) so let's grab a new version!

brew install vim --with-override-system-vi

Neovim is an extension of vim with some extra features. If you want to use Neovim...

brew install neovim/neovim/neovim

Why are you typing "neovim" three times? You're tapping into the neovim tap run by neovim, and downloading neovim from it.

Configuration is a very opinionated topic so I'll leave you with my .vimrc but with a warning: don't just stop with mine. Learn what vim can do and customize it yourself. There are thousands of plugins out there and millions of possible configurations.

Ruby, Rails, rbenv

RVM is dead, long live rbenv! Maybe? That's still a debate, and now chruby is here to add more to the debate. If you have a strong opinion on this, don't let me stop you, but here's what I do.

brew install rbenv

Then do what homebrew tells you and run this to do the first time setup.

rbenv init

This will tell you what you should do to make rbenv load automatically depending on your shell.

Then, to list all available ruby versions to install, run

rbenv install -l

Then pick one and run this (depending on your version) to install and set this version as the default

rbenv install 2.4.0

rbenv global 2.4.0

In order to use these new ruby versions instead of the system version, use this for bash:

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile

Or if you use zsh:

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc

Install bundler and rails with

gem install bundler

gem install rails

These gems are installed in the .rbenv directory under this specific version, so you can have a different set of gems for each.
The power of rbenv is that you can have different ruby versions for different projects. So if your project needs an older ruby version, you can use it only in that project.
More detailed info on rbenv here: https://github.com/rbenv/rbenv

== Heroku ==
Even if you aren't deploying to Heroku for production, it's a great testbed for quick apps. Have an account and want to install it? To homebrew!

brew install heroku-toolbelt

heroku update

heroku login

Note that in order to use heroku you may need to disconnect from any VPNs in use. For more information on usage, check out https://devcenter.heroku.com/

PostgreSQL

Another database provider, frequently preferred over MySQL. If you need this, guess where we're going. HOMEBREW!

brew install postgresql

To make things easier, I alias pgup and pgdown in my zshrc or .bash_profile

alias pgdown='pg_ctl -D /usr/local/var/postgres stop -s -m fast'

alias pgup='pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start'

Start up the server with pgup, then use this to create your db

createdb

Type psql at the prompt to see if you get a SQL prompt and make sure the database exists. Then use pgdown to stop the server until you need it.

Bash

You may not want to use ZSH like I do. The default version of bash is also outdated, so add that if you like. This also grabs the bash completion package to let you hit tab to autocomplete some commands/paths.

brew install bash bash-completion

Edit your /etc/shells file to include /usr/local/bin/bash at the end, and then you can change to this using chsh.

Add this line if you want to use bash completions:

[ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion

Git

You're gonna want to version your stuff, so get git!

brew install git

I use Mathias Bynen's gitconfig as a start, backing up the one that's there first.

cd ~

mv .gitconfig .gitconfig.old

curl -O https://raw.githubusercontent.com/mathiasbynens/dotfiles/master/.gitconfig

Then add yourself as the global user.

git config --global user.name "Your Name Here"

git config --global user.email "[email protected]"

Then add git to the keychain so you don't have to type your password all the time.

git config --global credential.helper osxkeychain

Python

I haven't done much in Python myself but I seem to end up frequently using utilities that require installing via pip, so I always have it close by. This is also outdated on your Mac, so install a newer version like so:

brew install python

pip install --upgrade pip

Node.js

Same as before, I have barely touched Node, but I frequently use things from it. Install it like so:

brew install node

Everything Else

This guide isn't one-size-fits-all by any means. It doesn't cover nearly everything, not by a long shot. This is just (basically) everything I do. If you have suggestions for things to make this more efficient and complete for what's listed, please let me know or submit a PR, or fork it and add your own stuff that benefits you.

Sources

Comments

Blog