Published in


Intro to XcodeGen

Written by: Matheus Ruschel, Agile Software Engineer, TribalScale

Photo by Zan on Unsplash

Xcodegen is a command line tool that can be used by iOS developers to automatically generate an Xcode project file based on your project folder structure and parameters provided to a project.yml file that includes everything from targets, schemes to code signing and everything that your project file already contains.

On a client project, we had a team of 6 iOS developers writing code at the same time. There was a point in which we were all working on different features across the project, but the project file was almost always modified while another team also worked on it.

Why use this tool?

A co-worker who had previous experience with these kinds of issues and introduced our team to the tool. Adopting it was a no-brainer, as it would allow us to stop tracking the project file and instead generate one locally through the command line, solving all our issues with project file conflicts.

How it works

Given the nature of how Xcode works, everytime you add a new file or delete a new file, the project file changes. So when the time came to create a Merge Request, we’d usually see conflicts within the file and as every iOS developer knows, project file conflicts are no fun. There are symbols that only Xcode can understand and unless you designed Xcode, most people are not going to be 100% sure on how to solve those conflicts.

With XcodeGen it’s possible to effectively solve this issue by automatically generating the project file based on your folder structure and specifications. It works by reading a project.yml file located in the root directory of your project, that contains all the information that a project file would normally have, like folders, app signing, schemes, run scripts, etc.

Here’s an example of a simple project.yml file:

After you finish specifying your file, you need to delete your current project file and run xcodegen in the command line in your root project folder directory and that’s it, the project file will be generated for you!

If you use any CI/CD integrations in your project, you’ll probably have to add an extra step in your CI tool to run xcodegen before it can run any pipelines, otherwise it’s possible your build will fail given the non-existence of a project file.

Why it worked for us

If you work on a team with multiple iOS developers that are working on different branches and features, the advantage of using XcodeGen is clear. It’ll avoid a lot of headaches and save you a lot of time with project file merge conflicts. It’s something that is unavoidable when you’re working on a large team where the project file is constantly changing.

It also provides a more organized way of keeping track of project file changes since it’s all made in the project.yml file as opposed to different places in the project file itself. Additionally, in big projects sometimes it’s easy for developers to remove files from the project but forget to delete these files, so you end up with unused files that don’t show up in the project, XcodeGen will include all files in your folder structure so you’re able to easily spot files that are not used.


Matheus is an Agile Software Engineer at TribalScale. He is passionate about following technology and discovering new tools that make his work more efficient. He also enjoys reading about the economy and investments, and in his free time he is a big gym rat and loves keeping healthy.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
TribalScale Inc.

TribalScale Inc.


A digital innovation firm with a mission to right the future.