Add a .gitignore File in Xcode Project

Vanessa Flores -

In this article, we are going to add a .gitignore file in our Xcode project. When you have an Xcode project under source control, git will track every file in the project unless you tell it not to. When you’re ready to make a commit you can choose not to commit certain files, but you’ll run into the issue where you won’t be able to switch branches because of those uncommitted changes. That is where the .gitignore file comes in handy.

Requirements:

  • An Xcode project (preferably one not already under source control)

The .gitignore file is a text file named “.gitignore” with a list of files and directories we want source control to ignore. Open up the Terminal and navigate to your project directory. A quick way to do this:

In the terminal, type cd and then drag and drop your project’s highest level folder from Finder into the terminal.

$ cd <.../Project's root folder>

Now that you are in your project directory, from the terminal type:

$ touch .gitignore

This will add the .gitignore file to your project.

Github provides a .gitignore template for Swift. I’ll be using their template, but only keeping some of the basics. Adjustments can be made down the road as needed.

xcuserdata

This directory keeps track of things like userstate, last opened file, folders opened and build schemes. It’s safe to ignore xcuserdata when you’re working on an individual project. However, when working on a team and using a Continuous Integration (CI) tool, you’ll run into problems when adding xcuserdata to .gitignore because there won’t be schemes to build against.

A workaround if you run into this issue is to share your schemes. In your project, go to Manage Schemes and select which scheme will be used by the CI tool. Then change the Settings for that scheme and select Share Schemes. This removes the schemes from under the individual xcuserdata and into a shared folder that can be committed and tracked via source control to be used by the CI tool.

Build and DerivedData

The build directory has been replaced by DerivedData. When Xcode builds your project, the files generated get placed in this directory.

*.moved-aside

The * means whatever file that ends with some extension. .moved-aside files are where Xcode puts deprecated files.

*.pbxuser

Whatever file that ends with .pbxuser. .pbxuser files contain local user preferences such as window settings, build preferences, project directories, and others. These local settings don’t need to be tracked. However, there are some common preferences that you may want when working with a team and those preferences can be set in default.pbxuser.

!default.pbxuser

The ! means to negate a pattern. So in the case of default.pbxuser, which was previously matched and excluded through *.pbxuser, adding ! in front of default.pbxuser means that this particular file will become included again.

*.mode1v3

The different *.mode* files contain layout information such as the window positions of your workspace configuration.

*.perspectivev3

*.perspective* files save the preferences of your perspective in Xcode, such as if the console is open, its window size and placement on the screen are saved.

*.hmap

.hmap files, or “header map” files, are used by Xcode to provide the compiler with the locations of headers used in a target.

*.ipa

A file with an .ipa file extension is an iOS app file that functions as a container for holding different pieces of data that make up an iOS app.

*.dSYM

A .dSYM file is a “debug symbols file” that is generated when the settings are enabled to “Generate Debug Symbols” and you build the project for a real device.

The rest are temporary files that shouldn’t be tracked. You can also check out Git documentation to get a better idea of how .gitignore works and how to pattern match.

If you’ve already put your project under source control and are adding a .gitignore file later on, you are going to need to remove the files you no longer wish to track from the git cache. Here is an article that shows you how to do that.