Add a file to .PBXproj in programmatically way

Behrad Kazemi
2 min readJan 11, 2020

Since I started to create a command-line tool for Xcode that makes files and folders for the project automatically, I found many new things that can help you to create a new command-line tool on your own.

In this tutorial, you’ll learn how to create a module to modify your Xcode project with Swift code. You’ll also learn all about .pbxproj files.

First of all, we should take a brief look at the .pbxproj file and see what’s going on with it. there is a complete reference in:

Adding a file

If you add a file to your project manually you will see some git diff changes on .pbxproj file, so we need to perform these changes programmatically:

Step 1

First, a record will add to the ‘PBXBuildFile’ section that describes a reference of the file you added in the ‘PBXFileReference’ section.

1363D7D923C9C87500003F3E /* filename.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1363D7D823C9C87500003F3E /* filename.swift */; };

At the beginning we must create :

  • a UUID ( A 96 bits identifier ) for section reference.
  • a description of file (eg. /* filename in Sources */ and /* test.swift */).
  • a UUID for file reference.

Step 2

In the ‘PBXFileReference’ section a record will add that describes the file’s details like type, path, etc.

1363D7D823C9C87500003F3E /* filename.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = filename.swift; path = relativePathTo/filename.swift; sourceTree = SOURCE_ROOT; };

Note: The identifier in the code above is the same ‘fileRef’ property on the ‘step 1’.

Step 3

When you ‘drag and drop’ a file into a specific group folder of your project, a record that describes your file’s destination group, will add to the ‘PBXGroup’ section.

In this section, each group has the following format:

133D660B23C75BA100C7C358 /* GroupName */ = {
isa = PBXGroup;
children = (
1363D7D823C9C87500003F3E /* filename.swift */,
); path = relativePathToGroup; sourceTree = “<group>”;};

As you can see the filename.swift is added into the ‘children’ property inside the group scope, and the identifier behind the filename.swift is the same identifier used in the ‘fileRef’ property defined in step 1.

Step 4

Finally, you need to add the filename.swift inside the ‘PBXSourcesBuildPhase’ section at the list of ‘files’ with the following format:

1363D7D923C9C87500003F3E /* filename.swift in Sources */,

This identifier behind the ‘filename.swift’ is the ‘PBXBuildFile’ identifier defined in Step 1.


In the next article, I will show you how to create an application to modify the .pbxproj file.