Changing Xcode Header Comment

Have you ever wanted to change the standard header comment that Xcode automatically puts at the top of ever new source file you add to a project? Maybe you just don’t like the default or need to include your own copyright or license text. Xcode 9 added a FILEHEADER text macro to allow you to do just that.

Last updated: Mar 7, 2023

FILEHEADER Text Macro

When you add a new source file to Xcode it expands the contents of the FILEHEADER text macro. The default value of this macro gives you the standard file header comment:

//  ___FILENAME___
//  ___PACKAGENAME___
//
//  Created by ___FULLUSERNAME___ on ___DATE___.
//  ___COPYRIGHT___
//

You can include any Xcode text macro in the FILEHEADER by adding three leading and trailing underscores (_). The full list of possible text macros is in the Xcode help guide (or see Help > Xcode Help in Xcode).

To use a different format for new files:

  1. Create a plist file named IDETemplateMacros.plist.
  2. Add an entry in the plist file for the FILEHEADER macro with your format.
  3. Move the plist file into the right location.

Creating The Text Macro File

Creating the plist file can be a pain with Xcode. I find the easiest way, if you do not have a separate plist editor, is as follows:

  1. Open Xcode. Close any projects that are open.
  2. Use File > New File... (⌘N) and choose Property List from the Resource section of the templates browser.
  3. Name the file IDETemplateMacros.plist and save it to a temporary location.
  4. Add a new entry to the Root dictionary named FILEHEADER and enter the new format in the value field.
  5. Save the file once you have finished editing.

Text Macro plist

Note: You may find it easier to type your new format into a text editor and then copy and paste into the plist file (step 4).

Format Examples

Note: To use an Xcode text macro add three underscore (_) characters before and after the macro name.

A single line showing the default copyright:

 ___COPYRIGHT___

Note that there is a leading space but you do not include the // for the comment on the first line.

A two line header showing creation date and copyright:

 Created ___DATE___
// ___COPYRIGHT___

A header with some project and toolchain details:

 Created for ___PROJECTNAME___ in ___YEAR___
// Using Swift ___DEFAULTTOOLCHAINSWIFTVERSION___
// Running on macOS ___RUNNINGMACOSVERSION___

I am not sure how useful it is but for a project named TextMacros this gives me:

// Created for TextMacros in 2017
// Using Swift 4.0
// Running on macOS 10.13

It may be a bug or a feature but I also noticed that changing the FILEHEADER macro has no effect on .strings files.

Text Macro File Locations

Once you have your new text macro file move it to the right location. You can override the text macros globally, or for an individual workspace or project. You can also decide to keep the macros for a single user or share it for all users.

The full list of locations that Xcode searches, in order of priority:

Project - single user

<ProjectName>.xcodeproj/xcuserdata/[username].xcuserdatad/

Project - shared by all users

<ProjectName>.xcodeproj/xcshareddata/

Workspace - single user

<WorkspaceName>.xcworkspace/xcuserdata/[username].xcuserdatad/

Workspace - shared by all users

<WorkspaceName>.xcworkspace/xcshareddata/

Globally for Xcode

~/Library/Developer/Xcode/UserData/

So you might create a default IDETemplateMacros.plist in ~/Library/Developer/Xcode/UserData/ and then override it with a project specific template created at the workspace or project level.

Note: You may need to create the xcshareddata folder if it does not already exist. I find that easiest to do from the command line but if you are using Finder then right-click on the xcodeproj or the xcworkspace file and use Show Package Contents to navigate.