xUnique

xUnique, is a pure Python script to regenerate project.pbxproj, a.k.a the Xcode project file, and make it unique and same on any machine.

As you may know, the UUID generated by Xcode in the file is not unique for the same added file( or other entries like groups,build phases,etc.) on different machines, which makes it a developer's nightmare to merge and resolve conflicts in project.pbxproj.

xUnique convert all the 96bits UUID(24 hex chars) to MD5 hex digest(32 hex chars)

1. convert project.pbxproj to JSON format
2. Iterate all objects in JSON and give every UUID an absolute path, and create a new UUID using MD5 hex digest of the path
   • All elements in this json object is actually connected as a tree
   • We give a path attribute to every node of the tree using its unique attribute; this path is the absolute path to the root node,
   • Apply MD5 hex digest to the path for the node
3. Replace all old UUIDs with the MD5 hex digest and also remove unused UUIDs if any
4. Sort project file using 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
5. Sort the project file inlcuding children list, files list, PBXFileReference list and PBXBuildFile list using pure Python
   • see sort_pbxproj method in xUnique.py if you wanna know the implementation;
   • It's ported from the perl script, I have to admit that Perl is really very good at text processing...
6. All above operations are what this script done for you;)

There are many ways to use this script. I will introduce two types:

1. open Edit Scheme in Xcode (shortcut: ⌘+Shift+,)

2. choose the sheme you use to run your project

3. expand Build, select Post-actions

4. click symbol + on the left bottom corner of the right pane

5. choose New Run Script Action

6. choose your selected sheme name in Provide build settings from

7. input commands below (assume that xUnique.py is under directory of /project/dir/Scripts):

   python "${PROJECT_DIR}/Scripts/xUnique.py" "${PROJECT_FILE_PATH}/project.pbxproj"

8. click Close and it's all done.

9. Next time when you Build or Run the project, xUnique would be triggered after build success. If the build works, you could commit all files.

10. Demo gif animation is here

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 like { echo '#!/bin/sh'; echo 'python2 path/to/xUnique.py path/to/MyProject.xcodeproj'; } > .git/hooks/pre-commit
3. Add permission chmod 755 .git/hooks/pre-commit
4. xUnique will be triggered when you trying to commit: * If you added or removed files in the commit, Xcode will sort all PBXBuildFile and PBXFileReference by MD5 hex number, this will disorder the project file taht was sorted by xUnique before. * Using option -c in command would fail the commit operation if project file is modified. Then you can add the modified project file and commit all the files again. * Option -c is not activated by default. The commit operation will proceed successfully even if the project file is modified by xUnique. So do not push the commit unless you add the modified project file again and do another commit.

• -v: print verbose output, and generate debug_result.json file for debug.
• -u: uniquify project file, that is, replace UUID to MD5 digest
• -s: sort project file inlcuding children list, files list, PBXFileReference list and PBXBuildFile. Supports both original and uniquified project file
• if neither -u nor -s exists, execute both uniquify and sort
• -c: When project file was modified, xUnique quit with non-zero status. Without this option, the status code would be zero if so. This option is usually used in Git hook to submit xUnique result combined with your original new commit.

• There are still conflicts after using xUnique. That's because the incorrect merge strategy used by Git against project file.
• use Git Attributes to make git know how to deal with project.pbxproj:
• create a file named .gitattributes in git repo root directory (a.k.a the same level with .git directory) if it does not exist
• add line *.pbxproj text -crlf -diff -merge=union in the file
• save file and add this file to git repo

• APNS Pusher is a Xcode project which contains a subproject named "Fragaria" as git submodule. Use xUnique to convert it. You can clone my forked repo and try to open and build it in Xcode. You will find that xUnique does not affect the project at all.
  • The initial diff result could be found here.
  • The diff result with my modified sort-Xcode-project-file with PBXBuildFile and PBXFileReferencesort support could be found here.
  • Pure python sort result could be found here

• All project members must add the build post-action or git hook. Thus the project file would be consistent in the repository.
• Tested supported isa types:
  • PBXProject
  • XCConfigurationList
  • PBXNativeTarget
  • PBXTargetDependency
  • PBXContainerItemProxy
  • XCBuildConfiguration
  • PBXSourcesBuildPhase
  • PBXFrameworksBuildPhase
  • PBXResourcesBuildPhase
  • PBXFrameworksBuildPhase
  • PBXCopyFilesBuildPhase
  • PBXBuildFile
  • PBXReferenceProxy
  • PBXFileReference
  • PBXGroup
  • PBXVariantGroup

• Xiao Wang (seganw)

• I only tested on one single project and one project with a subproject, so maybe there should be more unconsidered conditions. If you get any problem, feel free to fire a Pull Request or Issue

• You can also buy me a cup of tea:

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.