Xcode: Groups And Folder References

In Xcode you can add folders as groups or as folder references. So what are the differences between these two?


If you drag a folder to the project navigator, the following window appears:


If you choose “create groups”, then the corresponding folder appears with a yellow icon in the project navigator:


This means that this folder does not represents the file system. So you can move a file out of the group into another without moving the corresponding file on the file system. And you can add a file into the “real” folder on the file systems and the file will not appear automatically in the project navigator. So it is just a virtual folder.

Most of the times, you have groups in your project. There are some advantages in using groups:

  • you can choose to which target each file in the group should belong
  • the interface builder sees all files in groups
  • file operations doesn’t accidentally add files to the project

Most of the times you should groups to structure your project.

Folder References

If you are choosing “create folder references”, then the folder appears with a blue icon in the project navigator:


Now this folder is mapped one-to-one to the folder on the file system: If you remove a file from the folder on the file system, then it will also be removed from the project navigator. The same holds true if you add a file or if you rename it.

On the other hand, you can set the target membership only for the whole folder and not for separate files. And the interface builders doesn’t see those files.

Which One To Choose?

In almost all cases you should use groups. But there are some cases where it does make sense to use folder references:

  • Sometimes you want to place files during the build process into the project. That could be for example the most recent assets. So if these are not always the same files, you have to choose a folder reference for that folder, so that the project can access those files.
  • If someone outside of the developer team should be able to add asset files to the project, it could also make sense to use folder references.

So you should use folder references only, if some kind of assets should be dynamically inserted into the project. For normal project files like classes it is good practice to use groups.


Main Image: @ Andrey VP / shutterstock.com

Book Tip

Big Nerd Range Guide: iOS Programming: Excellent introduction to iOS development. Some programming experience is recommended.