xcrename

A Swift command-line tool that safely renames your entire Xcode project. It updates file names, folder names, and text content throughout your project while avoiding generated files and dependencies.

What It Does

When you rename an Xcode project, you need to update:

• File and folder names containing the old project name
• Text occurrences in source files, project files, schemes, and plists
• Bundle identifiers (optional)

xcrename does all of this automatically and safely.

Quick Start

Step 1: Build the tool

swift build

Step 2: Preview what will change (always do this first!)

./.build/debug/xcrename --path ./MyApp --old MyApp --new NewApp --dry-run

Step 3: Apply the rename

./.build/debug/xcrename --path ./MyApp --old MyApp --new NewApp

Step 4: Open in Xcode and verify

That's it! The tool creates backups (.xcrename.bak) of all modified files.

Installation

Build from Source

git clone <your-repo-url>
cd xcrename
swift build

After building, run the tool from .build/debug/xcrename or install it system-wide (see below).

Install System-Wide (Optional)

Recommended: Install to ~/bin (no sudo needed)

mkdir -p ~/bin
cp .build/debug/xcrename ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Alternative: Install to /usr/local/bin (requires sudo)

sudo cp .build/debug/xcrename /usr/local/bin/

After installation, you can use xcrename from anywhere.

Examples

Basic Usage

Rename a project from MyApp to NewApp:

# Preview first
./.build/debug/xcrename --path ./MyApp --old MyApp --new NewApp --dry-run

# Then apply
./.build/debug/xcrename --path ./MyApp --old MyApp --new NewApp

Also Rename the Project Folder

If your project folder is named MyApp and you want it renamed to NewApp:

./.build/debug/xcrename --path ./MyApp --old MyApp --new NewApp --rename-root

Update Bundle Identifier

Set a specific bundle identifier during rename:

./.build/debug/xcrename \
  --path ./MyApp \
  --old MyApp \
  --new NewApp \
  --bundle-id com.company.newapp

Using Different Paths

You can use relative or absolute paths:

# Relative path
./.build/debug/xcrename --path ./MyApp --old MyApp --new NewApp

# Absolute path
./.build/debug/xcrename --path ~/Projects/MyApp --old MyApp --new NewApp

# Path with spaces (use quotes)
./.build/debug/xcrename --path "./My App" --old MyApp --new NewApp

Command Reference

Required Arguments

• --path <folder> - Path to your Xcode project folder (contains .xcodeproj or .xcworkspace)
• --old <name> - Current project name to find and replace
• --new <name> - New project name to replace with

Options

• --dry-run - Preview changes without modifying files (use this first!)
• --rename-root - Also rename the root project folder if it contains the old name
• --bundle-id <id> - Set bundle identifier to this exact value (e.g., com.company.app)
• --skip-scheme-rename - Don't rename .xcscheme files
• -h, --help - Show help

What Gets Updated

✅ Updated:

• File and folder names containing the old name
• Text in Swift/Objective-C source files
• Project files (.pbxproj, .xcscheme, .plist)
• Bundle identifiers (when using --bundle-id)

❌ Skipped:

• Generated folders: Pods, .build, DerivedData, Carthage, build, node_modules
• Git folder (.git)
• Binary files
• Files larger than 25MB
• Symlinks

Safety Features

• Backups: Every modified file gets a .xcrename.bak backup
• Dry-run mode: Preview all changes before applying
• Bundle ID protection: Bundle identifiers are protected unless you use --bundle-id
• Collision detection: Stops if renaming would overwrite existing files

Typical Workflow

1. Commit your project to git (good practice)
2. Run with --dry-run to see what will change
3. Review the output carefully
4. Run without --dry-run to apply changes
5. Open in Xcode and verify everything works
6. Build and test your project

Requirements

• macOS
• Xcode / Swift toolchain
• Swift 5.9+

Troubleshooting

• "No such file or directory": Make sure the --path points to your project folder
• "Permission denied": Make sure you have write access to the project folder
• Files not updating: Check that the --old name matches what's actually in your project
• Want to undo: Restore from .xcrename.bak backup files or use git