Hi there! In this short article, I explain how to completely rename an Xcode project, including subfolders and schemas.

Eventually you will find yourself in the need of renaming a project. Maybe you are making a copy of one of your projects to use as the basis of another one, or maybe your startups changed its branding and name completely.

Whatever the reason, it’s a complex process that can cause you lots of headaches. Here, I describe how you can avoid them and easily rename your projects.

I happen to be working on a series of tutorials about how to debug iOS Apps. As a sample project, I am using “My First App“, the sample App for the tutorial and blog teaching you how to create your first “Hello World” app.

However, I wanted to rename it to “BrokenHelloWorld” to better illustrate its purpose. Thus, I thought it would be a perfect example to show how to rename a project completely.

Thus, as a use case, imagine that we want to rename a project called “MyFirstApp” to “BrokenHelloWorld”.

Steps Needed To Rename An Xcode Project

These are the steps you need to take to rename an Xcode project:

Rename the project

How to Rename An Xcode ProjectFirst, we need to change the name of the project and target in properties. In order to do so, go to the Project Navigator, choose the root of the project, and then click on it again.

It should allow you to edit the name and type the new one.

Enter the new name (in our case “BrokenHelloWorld”) and push Enter.

You will be shown a dialog with all the modifications that Xcode will perform. The picture below shows this dialog in our example:

How to Rename An Xcode Project

Click on “Rename” and let Xcode do its magic.

Rename The Schema

Then, we need to rename the schema. In order to do that we go to the menu and choose Product > Scheme > Manage Schemes. A dialog with our current scheme will appear.

How to Rename An Xcode Project

 

Simply click on the name until it allows you to change it. Type the new name for the project (in our case: “BrokenHelloWorld”).

Rename The Main Files Folder

Now, time to close Xcode and change the name of the folder that contains the project’s files.

Go to a terminal (you can open it by pressing Cmd+Space) and typing “terminal”. If you are familiar with the terminal, CD to the directory of your project.

cd /Users/YourUserName/PathToYourProject

However, if you never faced this black text screen, fear not. Just type “cd” and a whitespace. Then, in Finder, locate the folder with your project inside, the one that has a folder called “YourProjectName” and an archive called “YourProjectName.xcodeproj”, and drag and drop that folder inside the terminal.

As a result, you should end up having something like this:

cd /Users/YourUserName/PathToYourProject

You can easily check that you are in the correct place by doing an “ls” command. It should show something like:

-rw-r--r--@ 1 Nacho staff 6148 3 jun 13:50 .DS_Store
drwxr-xr-x  7 Nacho staff 238 3  jun 17:27 YourOldProjectName
drwxr-xr-x@ 5 Nacho staff 170 3  jun 13:18 YourNewProjectName.xcodeproj

As you see, the xcodeproj archive has been renamed (in step 2), but the folder that contains the files still has the old name.

Type the following to rename it:

mv YourOldProjectName YourNewProjectName

Obviously, replace these names with your old and new project names. In our case it will be:

mv MyFirstApp BrokenHelloWorld

Then, if you ask for an “ls” again, you should see the folder renamed:

-rw-r--r--@ 1 Nacho staff 6148 3 jun 13:50 .DS_Store
drwxr-xr-x  7 Nacho staff 238 3  jun 17:27 YourNewProjectName
drwxr-xr-x@ 5 Nacho staff 170 3  jun 13:18 YourNewProjectName.xcodeproj

Replace All Occurrences Of The Old Project’s Name

Now that we have replaced the folder name, we need to replace all the occurrences of that name in our files with the new one.

In order to do this, don’t leave the terminal, but type:

grep -Rl "YourOldProjectName" * | xargs sed -i "" "s/YourOldProjectName/YourNewProjectName/"

For example, in our case, it will be:

grep -Rl "MyFirstApp" * | xargs sed -i "" "s/MyFirstApp/BrokenHelloWorld/"

If you receive an error message:

sed: RE error: illegal byte sequence

Don’t worry, it’s just sed telling you that it was unable to modify a binary file containing that name.

Commit All Changes (If you are using Git)

Finally, you can open Xcode and your project again. Hopefully, you won’t have any errors. Nevertheless, if you use Source Control, there surely be some warnings in the Issue Navigator.

These warnings indicate that Source Control wasn’t able to find the files it tracks for the current project.

To solve this, just do a commit and include all the files.

Run Your New Project

By now, everything should be ready to compile and run your new project. Run the project and Voila! Your project has successfully been renamed.

If you find some problems or the new project won’t compile, review all the steps and check that everything’s been completely renamed.

Also, do a full cleaning of the project files (Cmd+Alt+Shift+K) and try again.

What We Learned Today

In this article, I showed you how to rename an Xcode project easily. This can be useful to copy a project to use it as basis of a new project, or if your App specifications or branding changes.

I hope you will find it useful. If you find any difficulty in any of the steps, don’t hesitate to ask for help in the comments below!