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:
- Create a
- Add an entry in the
plistfile for the
FILEHEADERmacro with your format.
- Move the
plistfile 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:
- Open Xcode. Close any projects that are open.
File > New File... (⌘N)and choose
Property Listfrom the Resource section of the templates browser.
- Name the file
IDETemplateMacros.plistand save it to a temporary location.
- Add a new entry to the Root dictionary named
FILEHEADERand enter the new format in the value field.
- Save the file once you have finished editing.
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).
Note: To use an Xcode text macro add three underscore (_) characters before and after the macro name.
A single line showing the default 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
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
Project - shared by all users
Workspace - single user
Workspace - shared by all users
Globally for Xcode
So you might create a default
~/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.