Synx, keep Xcode folder structure organized

Xcode is a tool that doesn’t force developers to have any particular folder structure: everything can be managed using groups, virtual folders that lives in your .xcodeproj file.
This give you a lot of freedom but on the long period it can create some problems: how to refactor the folder structure quickly?

In my previous projects I’ve always divided the source code based on the type:

  • controllers
  • views
  • models
  • helpers
  • libraries

Each group has different subgroups, but only the one from the list are linked to physical folder.
I like it: every time I open the project I already know where to search; the problem is that if you project became really big your folders will contain hundreds of file.

I’ve always searched for a way to fix it and the answer is Synx: I’ve found it thanks to a post on Little Bites of Cocoa and I’ve decided to give it a try.


Synx is “A command-line tool that reorganizes your Xcode project folder to match your Xcode groups.“.

A good project that we can use to test it is Alamofire: it is open source and its folder structure is different from the group structure. After downloading the code, the folder “Source” structure is like this:

Before structure

As you can see, all of the files are in the same folder while the group folder in the project’s structure is different. Synx can help us refactoring the folders to match Xcode structure in few steps.

⚠️ Be sure to backup your project before starting the process
⛔️ Are you sure you did it?


Open your Terminal application and perform:

$ gem install synx


To start the process, go inside your Alamofire folder, open your Terminal application and perform:

$ synx Alamofire.xcodeproj

In case you use Cocoapods, remember to do a pod install since Synx is not able to fix the manage it.

Synx will do the dirty work for you and it will create directories and moving files to match your group structure. At the end of the process, the structure of the folder “Source” will be like this:

After structure


Synx supports advanced option too:

--prune, -p                   // remove source files and image resources that are not referenced by the the Xcode project
--no-color                    // removes all color from the output
--no-default-exclusions       // doesn't use the default exclusions of /Libraries, /Frameworks, and /Products
--no-sort-by-name             // disable sorting groups by name
--quiet, -q                   // silence all output
--exclusion, -e EXCLUSION     // ignore an Xcode group while syncing

Happy Xcode structure,