Groups and Folders

Xcode handles folders in 2 different levels: groups and references.

Groups are logical folders that allow to organized your project but it might not reflect the actual folder structure of the files in it. Groups appear in Xcode as yellow folder icons in the project navigator.

On the other hand, references are a physical representation of your folder structure. But Xcode does not stop there, it also treats both differently. References are associated to assets structures and are copied 1:1 into the compiled app, disregarding what file types are inside such folder. So, be careful when using references, if you place a source file there, it will end up in your app uncompiled.

Create or get a group

You can search or create them if they don't exists with a single method call:

group = project.get_or_create_group('my folder')

The function requires a name and 2 optional parameters:

• path: String, represents the relative physical path to the parent group. For instance, if your files are in Classes/Module/, and you want to add the Module group, path has to be 'Module'
• parent: String or PBXGroup object, represents the group that will act as the parent. if you want to add a group under another, you have to retrieve the parent first and pass it to this method as the parent.

Create groups recursively

This will recursively create groups and add the directory's contents to the project. You can optionally turn off the recursion.

project.add_folder('/path/to/folder')

You can supply an array of regular expressions for files you want to skip. This won't add any pdfs or mdown files found as it recurses.

project.add_folder('/path/to/folder', excludes=["^.*\.mdown$", "^.*\.pdf$"])

Other optional parameters of this function:

• parent: String or PBXGroup object, represents the group that will act as the parent. if you want to add a group under another, you have to retrieve the parent first and pass it to this method as the parent.
• excludes: An array of regular expressions to be evaluated against the folder/file to be added, if it matches it gets excluded
• recursive: Add subfolders as groups recursively. Enabled by default.
• create_groups: Allows to chose how to add the folder, as a group (default) or as reference.
• target_name: Add the files to the given target name or all targets if no name is specified (default).
• file_options: Allows to provide extra flags to be applied to the files added.

Remove group by ID

You need to have the ID of the group. The ID is a string of hexadecimal of 24 characters

project.remove_group('AF62C671190997D50075DD39')

Optionally, you can remove everything recursively

• recursive: Boolean, remove all children groups and files from the project. Default true.

Remove group by name

You can remove the group by it's human-readable name.

project.remove_group_by_name('Classes')

Optionally, you can remove everything recursively

• recursive: Boolean, remove all children groups and files from the project. Default true.

Caution: If many groups match the same name all will be removed as well.