📦 ImportFormatter

A beautiful and intelligent Swift import formatter that keeps your code organized and consistent.

✨ What is ImportFormatter?

ImportFormatter is a command-line tool that automatically organizes and sorts your Swift import statements according to best practices. It intelligently groups system frameworks, third-party libraries, and testable imports while maintaining proper spacing and formatting.

🎯 Key Features

• 🔄 Smart Sorting: Automatically sorts imports alphabetically with system frameworks first
• 📱 System Framework Recognition: Identifies and prioritizes Apple's system frameworks
• 🧪 Testable Import Handling: Properly groups @testable imports separately
• ⚡ Fast Processing: Built with Swift Syntax for lightning-fast parsing
• 🔍 Check Mode: Verify formatting without modifying files
• 📁 Batch Processing: Format multiple files at once
• 🎨 Clean Output: Maintains proper spacing and code structure

🚀 Installation

Prerequisites

• macOS 10.15 or later
• Swift 6.1 or later

Building from Source

git clone https://github.com/annurdien/ImportFormatter.git
cd ImportFormatter
swift build -c release
cp .build/release/importformatter /usr/local/bin/

Using Swift Package Manager

Add ImportFormatter as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/annurdien/ImportFormatter.git", branch: "main")
]

📖 Usage

Basic Usage

Format a single Swift file:

importformatter MyFile.swift

Format multiple files:

importformatter file1.swift file2.swift file3.swift

Check Mode

Verify if files need formatting without modifying them:

importformatter --check Sources/**/*.swift

Help

Display usage information:

importformatter --help

🎨 Before & After Examples

Before Formatting:

import MyCustomModule
import Foundation
@testable import SomeTestModule
import UIKit
import CoreData
import NetworkExtension

class MyViewController: UIViewController {
    // Your code here
}

After Formatting:

import CoreData
import Foundation
import NetworkExtension
import UIKit
import MyCustomModule
@testable import SomeTestModule

class MyViewController: UIViewController {
    // Your code here
}

🔧 How It Works

ImportFormatter uses Apple's SwiftSyntax library to:

1. Parse your Swift files into an Abstract Syntax Tree (AST)
2. Identify import statements and classify them by type
3. Sort imports according to these rules:
   • System frameworks first (Foundation, UIKit, SwiftUI, etc.)
   • Third-party and custom modules second
   • @testable imports last
   • Alphabetical ordering within each group
4. Format with proper spacing and preserve existing code structure

Supported System Frameworks

ImportFormatter recognizes these system frameworks and prioritizes them:

• Foundation
• UIKit
• SwiftUI
• Combine
• CoreData
• CoreGraphics
• QuartzCore
• AVFoundation
• CloudKit
• CoreLocation
• MapKit
• WebKit
• Network
• os

🎛️ Command Line Options

Option	Description
--check	Check if files are formatted without modifying them
--help, -h	Show help message

🔄 Integration

Xcode Build Phase

Add a new "Run Script Phase" to your Xcode project:

if which importformatter >/dev/null; then
    find "${SRCROOT}" -name "*.swift" -not -path "*/.*" | xargs importformatter
else
    echo "warning: ImportFormatter not installed"
fi

Git Pre-commit Hook

Create a pre-commit hook to automatically format imports:

#!/bin/sh
git diff --cached --name-only --diff-filter=ACM | grep '\.swift$' | xargs importformatter --check
if [ $? -ne 0 ]; then
    echo "Import formatting issues found. Run 'importformatter' on your Swift files."
    exit 1
fi

🛠️ Development

Building for Development

swift build

Running Tests

swift test

Project Structure

ImportFormatter/
├── Sources/
│   └── ImportFormatter/
│       └── ImportFormatter.swift    # Main formatter logic
├── Tests/
│   └── importformatterTests/
│       └── importformatterTests.swift
├── Package.swift                    # Package manifest
├── LICENSE                         # MIT License
└── README.md                       # This file

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. ✨ Commit your changes (git commit -m 'Add amazing feature')
4. 🚀 Push to the branch (git push origin feature/amazing-feature)
5. 📬 Open a Pull Request

Contribution Guidelines

• Write clear, concise commit messages
• Add tests for new functionality
• Follow Swift coding conventions
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with SwiftSyntax by Apple
• Inspired by the need for consistent Swift code formatting
• Thanks to the Swift community for feedback and suggestions

📞 Support

• 🐛 Report Issues
• 💡 Request Features
• 📧 Contact

---

Made with ❤️ for the Swift community