Why Your pbxproj Is Bloated (and How to Fix It)

If you've worked on an iOS project with a team, you've likely dealt with .pbxproj conflicts.

The .pbxproj file is your project's registry. It stores build settings, targets, and a unique ID and location for every file in your project.

Any change you make through Xcode gets written into it.

The problem is everyone on the team constantly changes it.

If you add a file, rename something, change a build setting, etc, it all changes the  .pbxproj. So even when two developers haven't touched the same code, they've both changed this file, and that will create a merge conflict in something that's not exactly easy to read.

The bigger the team, the more often it happens.

That's why you can simplify and heavily reduce the amount of conflicts your team experiences by doing this change.

First, let's understand the difference between folders and groups.

Folder Vs. Group

Folder: A file-system directory that Xcode references directly. Xcode includes the folder's contents in the project but doesn't need to track each file individually. This means:

• Much smaller representation in the .pbxproj file
• Adding/removing files on disk doesn't modify the project file
• The project file auto-updates as the file system changes

Group: A virtual collection of resources inside the project. By default each group is mapped to a group on disk, but it doesn't have to be, you can have groups with no underlying folder. Because Xcode tracks every file individually inside a group:

• Every file added or removed writes a change to the .pbxproj
• Renames, moves, deletes, and copies all go through Xcode and are recorded in the project file

You can actually remove the tracking of the files in the .pbxproj if you just track the folders instead.

To do this, you just need to select any folder you have on your project and select Convert to Folder

Why does this work?

This works because the project used groups to organise the files in the project.

That's why the configuration file needed to keep track of every single file, each one got its own entry with a UUID.

By converting the groups into folders, we're now using real file system directories instead. Xcode no longer needs to record every file in the project file, resulting in fewer changes to the .pbxproj and fewer merge conflicts.

Thank you to my coworker Lukasz for teaching me about this topic.

References

[1] Organising project files in the navigator: Apple Developer Documentation