📁 Swift 프로젝트의 Group vs Folder 정리

개요

Swift(Xcode) 프로젝트를 관리할 때, 파일을 구성하는 방식에는 Group과 Folder 두 가지가 있습니다.
겉보기에는 비슷해 보이지만, Xcode 내부에서 관리되는 방식과 실제 파일 시스템에서의 구조가 다르기 때문에 명확한 구분이 필요합니다.

---

Group과 Folder의 차이

구분	Group	Folder
저장 위치	Xcode 내부에서만 존재 (가상 구조)	실제 macOS 파일 시스템의 폴더 구조
파일 경로	Xcode 프로젝트(.xcodeproj)에만 기록	실제 Finder 폴더로 반영됨
외부 파일 연동	외부에서 추가된 파일은 자동 반영되지 않음	외부 파일 추가/삭제가 Xcode에도 반영됨
색상 구분	노란색 아이콘	파란색 아이콘
용도	Xcode 내부 정리용 (코드 분류 목적)	실제 파일 관리용 (Git, 협업에 적합)
Git 동기화	구조 변경이 반영되지 않음	실제 디렉터리 변경이 Git에 반영됨

💡 정리:
Group은 Xcode 프로젝트 파일 안에만 존재하는 “논리적 분류”,
Folder는 실제 macOS 디렉터리 구조에 존재하는 “물리적 분류”입니다.

---

문제 사례

❌ Group만 사용했을 때 발생할 수 있는 문제

1. 파일이 실제 폴더에 존재하지 않음
   • Finder에서는 “파일이 보이지 않음”
2. Git 협업 시 충돌
   • 다른 개발자의 로컬 환경에서는 경로가 불일치할 수 있음
3. 빌드 오류
   • 경로가 유효하지 않거나, DerivedData에서 “Content Missing From Group” 오류 발생
4. 자동화 스크립트나 도구 사용 시 문제
   • find, swiftlint, fastlane 등의 툴이 파일을 찾지 못함

---

팀 규칙: “실제 폴더(Folder) 사용 원칙”

우리 팀은 폴더(Folder) 구조를 표준으로 사용합니다.
이는 협업, Git 관리 및 안정성을 높이기 위함입니다.

✅ 원칙

1. 모든 새 파일은 실제 폴더 안에 생성
   • Finder나 Xcode에서 생성 시 “Create folder references” 옵션 확인
2. Group 대신 Folder를 사용
   • Xcode 내에서 파란색 아이콘으로 표시되어야 함
3. 폴더 구조와 네임스페이스 일치
   • 예: Views/Components/Growth/GrowthDatePickerSheet.swift
4. 폴더 이름은 PascalCase 또는 명확한 기능 단위로
   • 예: Views, Models, ViewModels, Utils, Resources
5. Git에 전체 폴더 구조 포함
   • .gitignore에서 폴더 제외 금지

---

📘 폴더 구조와 실제 파일 경로가 완전히 일치해야 함.

---

생성 시 주의사항

• Xcode에서 새 폴더로 만든다.
• Group은 선택하지 않는다.
• xCode최신 버젼을 유진한다.
• 폴더 이름과 실제 파일명은 일관성을 유지합니다.

---

유지보수 가이드

• 새로운 기능(feature)을 추가할 때는 해당 기능 단위별 하위 폴더를 생성합니다.
• 불필요한 Group은 모두 삭제하고 Folder 기반으로 정리합니다.
• 폴더 구조 변경 시 반드시 Git 커밋 로그에 구조 변경 이유를 명시합니다.