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
plist
file namedIDETemplateMacros.plist
. - Add an entry in the
plist
file for theFILEHEADER
macro with your format. - 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:
- Open Xcode. Close any projects that are open.
- Use
File > New File... (⌘N)
and chooseProperty List
from the Resource section of the templates browser. - Name the file
IDETemplateMacros.plist
and save it to a temporary location. - Add a new entry to the Root dictionary named
FILEHEADER
and 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).
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.