xUnique – Xcode project file merge with no conflicts


If you are an Objective C developer using Xcode, and push your code to Git/SVN like other guys did in the team, I think you most probably have encountered the merge conflicts of project.pbxproj file.

It’s such a pain to merge this file by searching the file with <<<,>>> and ===, and then deleting and keeping lines by your judge. It would leave some unused lines or even make Xcode build fail due to wrong decision.

Since UUID generated by Xcode in project.pbxproj file is not unique for all machines, different Xcode got different UUID for the same file or filegroup. That’s why it created conflicts.


I just found that Xcode does not care the UUID in the file, it just needs to be unique in the file. So I made xUnique to fix the merge conflicts issue.

How it works

  • All elements in project file are actually connected as a tree
  • We give a path to every node of the tree using its unique attribute; this path is the absolute path to the root node connected by these attributes
  • Apply MD5 hex digest to the path for the node
  • these digests are the new UUIDs in the project file
  • Sort project file using my pure Python implementation of my modified sort-Xcode-project-file, supports following new features:
    • sort PBXFileReference and PBXBuildFile sections
    • avoid modified changes in Git/SVN if no change made in the project file

How to use

  1. Put xUnique.py file in your project repository somewhere and add it as track file via git add path/to/xUnique.py, so all members could use the same script
  2. create a git hook: ln -s path/to/xUnique.py .git/hooks/pre-push
  3. Add permission chmod 555 .git/hooks/pre-push
    • use hook pre-push instead of pre-commit is a safe consideration: you decide to commit the newly generated project file or not
  4. In all your branches, uniquify project.pbxproj file in either way:
    • make some changes and commit. Try to push, git hook would be triggered
    • manually run script: python path/to/xUnique.py path/to/MyProject.xcodeproj and then committing changes.
  5. All Done;)