🧬
Perforce (Helix Core / P4) 치트시트

게임 개발 및 대규모 엔터프라이즈 버전 관리(P4) 완벽 가이드: P4PORT/P4CLIENT 환경 설정, 클라이언트 워크스페이스(Workspace/View Mapping), 에셋 동기화(sync), 변경 목록(Changelist), 체크아웃(edit/add/delete), 커밋(submit), 대용량 바이너리 독점 잠금(exclusive lock), 스트림(Streams) 및 언리얼/유니티 실무 워크플로우
#perforce#helix-core#p4#vcs#game-dev#unreal-engine#unity#version-control#binary-assets최종 업데이트: 2026-10-10
Perforce (Helix Core / P4) 치트시트 핵심 명령어 및 실전 가이드

## 1. 사전 요건 & 시스템 요구사양 (Prerequisites & Installation)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Windows 10/11, macOS, Linux (RHEL, Ubuntu) | Windows 11, Ubuntu 22.04 LTS, macOS Sonoma | 게임 개발 환경(Unreal/Unity)에서는 Windows 표준 |
| **CPU** | 2 코어 이상 | 8 코어 ~ 16 코어 이상 | 수만 개 파일의 병렬 체크아웃 및 해시 무결성 검사 |
| **메모리 (RAM)** | 2 GB 이상 | 8 GB ~ 32 GB 이상 | 대규모 게임 프로젝트(수십~수백 GB 에셋) 동기화 시 필요 |
| **디스크 (Storage)** | 1 GB 이상의 여유 공간 | 100 GB ~ 1 TB 이상의 초고속 NVMe SSD | 대용량 3D 모델(FBX), 텍스처(PSD/TGA), 빌드 바이너리 보관 |
| **네트워크 / 프로토콜** | P4 CLI / P4V (Helix Visual Client) 최신 버전 | 사내 Helix Core 서버 포트 (기본: `1666` 또는 `ssl:1666`) | 1Gbps ~ 10Gbps 고속 사내 LAN 환경 권장 |

---

### 🚀 클라이언트 설치 및 필수 환경변수 설정

Perforce는 터미널 CLI(`p4`)와 공식 GUI 클라이언트인 **P4V**를 모두 지원합니다.

#### ① OS별 P4 CLI 설치
```bash
# 🐧 Ubuntu / Debian (Perforce 공식 패키지 저장소 등록)
wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -
echo "deb http://package.perforce.com/apt/ubuntu jammy release" | sudo tee /etc/apt/sources.list.d/perforce.list
sudo apt update
sudo apt install -y helix-cli

# 🍏 macOS (Homebrew)
brew install perforce

# 🪟 Windows (공식 Helix Core Visual Client 설치 시 p4 CLI 자동 포함)
winget install Perforce.P4V
```

#### ② 필수 연결 환경변수 설정
```bash
# [1] Helix Core 서버 주소 지정 (호스트명:포트번호 또는 ssl:호스트:포트)
export P4PORT=ssl:p4.luckytech.com:1666
# Windows CMD: set P4PORT=ssl:p4.luckytech.com:1666
# PowerShell: $env:P4PORT="ssl:p4.luckytech.com:1666"

# [2] 사용자 계정명 및 워크스페이스 이름 지정
export P4USER=sulucky
export P4CLIENT=sulucky_workstation_main

# [3] 서버 연결 상태 및 인증 확인
p4 trust -y    # SSL 지문 신뢰 등록 (SSL 접속 시 최초 1회)
p4 login       # 비밀번호 입력하여 티켓 발급
p4 info        # 현재 연결된 서버 정보 및 내 워크스페이스 상태 요약 출력
```

---

## 2. Perforce 멘탈 모델: 디포(Depot) vs 워크스페이스 (Architecture)

Git이 모든 변경 이력을 로컬에 통째로 복제하는 것과 달리, **Perforce Helix Core**는 기가바이트(GB)~테라바이트(TB) 단위의 대규모 게임 바이너리 에셋을 처리하기 위해 **중앙 집중형 스트리밍 구조**를 채택합니다.

### 📐 디포, 뷰 매핑, 워크스페이스 아키텍처 (ASCII Diagram)

```text
[ Helix Core Central Server ] (중앙 서버)
  └── //depot/ (중앙 디포)
        ├── //depot/main/Source/        (C++ 소스코드)
        ├── //depot/main/Content/       (언리얼 3D 모델, 텍스처, 사운드: 500GB+)
        └── //depot/main/Config/
                   │
                   ▼ [ View Mapping (선택적 매핑 필터링) ]
                   │ //depot/main/... //sulucky_ws/...
                   ▼
[ Local Client Workspace ] (개발자 로컬 PC: C:\Projects\MyGame)
  - 기본적으로 모든 파일은 읽기 전용(Read-Only: 쓰기 방지 잠금 상태)
  - 작업할 파일만 명시적으로 쓰기 권한을 열어 체크아웃 (p4 edit)
                   │
                   ▼ [ Changelist (원자적 변경 묶음) ]
  ┌──────────────────────────────────────────────────────────┐
  │ Changelist #1024 (Pending)                               │
  │   - //depot/main/Content/Characters/Hero.uasset (edit)   │
  │   - //depot/main/Content/Textures/Hero_Albedo.png (edit) │
  └────────────────────────┬─────────────────────────────────┘
                           │ p4 submit (원자적 커밋)
                           ▼
  [ 중앙 서버에 신규 글로벌 체인지리스트 #1025로 영구 기록 완료 ]
```

### 🧩 Git vs Perforce 핵심 멘탈 모델 비교

| 비교 항목 | Git (분산 VCS) | Perforce Helix Core (엔터프라이즈 VCS) |
| :--- | :--- | :--- |
| **대용량 파일 처리** | 대규모 바이너리 저장 시 LFS 필수, 속도 급감 | **GB 단위 대용량 파일 수십만 개를 초고속 처리 (게임 업계 표준)** |
| **로컬 파일 수정 방식** | 로컬 파일 언제든 자유롭게 수정 가능 | **기본 Read-Only 상태 ➔ 작업 전 `p4 edit` 체크아웃 필수** |
| **바이너리 파일 잠금** | 불가능 (동시 수정 후 머지 실패) | **독점 잠금(`+l`)으로 다른 사람의 동시 수정 원천 차단** |
| **커밋 단위** | 로컬 Commit ➔ 원격 Push | **체인지리스트(Changelist) 단위로 중앙 서버에 즉시 Submit** |
| **브랜칭 방식** | 가벼운 로컬 브랜치 포인터 | **스트림(Streams) 기반 가시적 파이프라인 브랜칭** |

---

## 3. [초보자 1단계] 3분 헬로월드: 워크스페이스 설정 & 첫 Submit (Hello World)

### ① 클라이언트 워크스페이스 생성 (`p4 client`)

로컬 폴더와 서버 디포(Depot) 경로를 연결하는 뷰 매핑(View Mapping)을 구성합니다:

```bash
# 기본 텍스트 에디터로 워크스페이스 설정 열기
p4 client
```
설정 파일이 열리면 다음 항목을 작성하고 저장합니다:
```text
Client: sulucky_workstation_main
Owner:  sulucky
Root:   /Users/sulucky/workspace/mygame   # Windows: D:\Projects\MyGame
View:
    //depot/main/... //sulucky_workstation_main/...
```

---

### ② 최신 파일 동기화 (Sync)
```bash
# 서버의 최신 리비전 파일들을 로컬 디렉토리로 다운로드
p4 sync
# 출력: //depot/main/README.md#1 - added /Users/sulucky/workspace/mygame/README.md
```

---

### ③ 파일 추가, 수정 및 제출 (Add, Edit & Submit)

```bash
cd /Users/sulucky/workspace/mygame

# [1] 신규 텍스트 파일 생성 및 P4에 추가 등록 (p4 add)
echo "Perforce 게임 개발 프로젝트 시작!" > intro.txt
p4 add intro.txt
# 출력: //depot/main/intro.txt#1 - opened for add

# [2] 현재 열려 있는 변경 목록 확인
p4 opened
# 출력: //depot/main/intro.txt#1 - add default change (text)

# [3] 서버에 체인지리스트 제출 (p4 submit)
p4 submit -d "프로젝트 소개 텍스트 파일 신규 등록"
# 출력:
# Submitting change 1001.
# Locking 1 files ...
# add //depot/main/intro.txt#1
# Change 1001 submitted.
```

---

### ④ 기존 파일 수정 시: 반드시 `p4 edit` 먼저 실행!
```bash
# 로컬 파일이 Read-Only로 잠겨 있으므로, 수정 전 반드시 p4 edit으로 쓰기 권한을 풀어야 함!
p4 edit intro.txt
# 출력: //depot/main/intro.txt#1 - opened for edit

# 내용 수정
echo "새로운 패치 노트 추가" >> intro.txt

# 수정 사항 커밋
p4 submit -d "소개 파일 내용 업데이트"
# Change 1002 submitted.
```

---

## 4. [2단계] 핵심 기능: 일상 작업 & 변경 목록 관리 (Changelists & Shelve)

### 💻 필수 파일 상태 제어 명령어

```bash
# [1] 파일 수정 준비 (체크아웃 - 쓰기 권한 활성화)
p4 edit <file>

# [2] 신규 파일 추가
p4 add <file>

# [3] 파일 삭제 (서버에서 삭제 예약)
p4 delete <file>

# [4] 작업 취소 (수정을 버리고 서버 최신본으로 원상 복구)
# 파일 내용이 수정되지 않았다면 자동으로 닫힘
p4 revert <file>
# 내용이 수정되었어도 강제로 변경 사항을 폐기하고 롤백 (-a 또는 무조건 되돌리기)
p4 revert -k <file>   # 로컬 파일은 남기고 P4 열린 상태만 취소
p4 revert <file>      # 로컬 수정 버리고 원본으로 덮어쓰기

# [5] 내가 현재 수정 중인 모든 파일 목록 확인
p4 opened
```

---

### 📦 번호 매겨진 변경 목록 (Numbered Changelist) 생성

여러 작업을 동시에 진행할 때, 특정 버그 수정 파일들만 하나의 체인지리스트로 묶어 관리합니다:

```bash
# 신규 체인지리스트 생성 (대화형 에디터 실행)
p4 change
```
```text
Change: new
Description:
    [BUG-104] 플레이어 캐릭터 점프 애니메이션 글리치 수정
Files:
    //depot/main/Source/PlayerController.cpp
    //depot/main/Content/Anims/Jump.uasset
```
저장 시 `Change 1005 created.`와 같이 번호가 발급됩니다.

```bash
# 특정 체인지리스트만 단독 제출
p4 submit -c 1005
```

---

### 🛡️ 변경 사항 임시 보관 (Shelve / Unshelve)

작업 도중 급한 핫픽스를 해야 하거나, 동료에게 내 작업 코드를 서버에 올려 리뷰받고 싶을 때 로컬 변경 사항을 서버의 임시 보관함에 셸브(Shelve)합니다:

```bash
# [1] 번호 매겨진 체인지리스트의 변경 사항을 서버에 셸브 (백업)
p4 shelve -c 1005
# 출력: Shelving files for change 1005 ...

# [2] 로컬 작업 파일을 안전하게 되돌리고 다른 작업 수행
p4 revert -c 1005 //...

# [3] 나중에 또는 동료 PC에서 해당 작업 복원 (Unshelve)
p4 unshelve -s 1005
```

---

## 5. [2단계] 핵심 기능: 바이너리 독점 잠금 (Exclusive Locking: `+l`)

게임 개발에서 **3D 모델(FBX), 텍스처(PNG/PSD), 언리얼 블루프린트(`.uasset`), 유니티 프리팹(`.prefab`)** 등은 두 사람이 동시에 고치면 병합(Merge)이 불가능하여 작업물이 유실됩니다.
Perforce의 **배타적 잠금(Exclusive Lock: `+l`)** 속성을 사용하면 한 사람이 `p4 edit`하는 순간 다른 사람의 수정을 원천 차단합니다.

### ① 파일 타입에 `+l` (Exclusive Lock) 부여

```bash
# 파일 추가 시 배타적 잠금 바이너리 타입 지정
p4 add -t binary+l Characters/Monster.uasset

# 이미 등록된 파일의 타입을 배타적 잠금으로 변경
p4 edit -t binary+l Weapons/Sword.fbx
p4 submit -d "무기 모델에 독점 잠금 타입 부여"
```

### ② 전역 파일 타입 매핑 규칙 설정 (`p4 typemap`)
관리자가 서버 전역에서 특정 확장자는 무조건 독점 잠금이 되도록 강제합니다:
```bash
p4 typemap
```
```text
TypeMap:
    binary+l //depot/.../*.uasset
    binary+l //depot/.../*.umap
    binary+l //depot/.../*.fbx
    binary+l //depot/.../*.psd
    binary+l //depot/.../*.blend
```
> **효과**: 이제 어떤 아티스트가 `Monster.uasset`에 대해 `p4 edit`을 실행하는 순간, 다른 팀원은 "Monster.uasset is locked by artist_kim"이라는 경고와 함께 수정을 시작할 수 없게 됩니다.

---

## 6. [3단계] 실무 응용: 스트림(Streams) 브랜칭 워크플로우 (Streams)

Helix Core의 **스트림(Streams)**은 복잡한 브랜치 간의 관계와 코드 병합 흐름을 시각적인 컨테이너로 구조화한 모던 파이프라인입니다.

### 📐 스트림 흐름 원칙 (Merge Down, Copy Up)

```text
       [ Mainline Stream ] (안정화된 프로덕션 메인 줄기: //stream/main)
             ▲           │
     Copy Up │           │ Merge Down
     (상향 복사)         │ (하향 병합)
             │           ▼
     [ Development Stream ] (기능 개발 줄기: //stream/dev)
```
- **Merge Down (하향 병합)**: 메인라인의 최신 변경 사항을 항상 먼저 개발 브랜치로 내려받아 충돌을 해결.
- **Copy Up (상향 복사)**: 완벽히 검증되고 안정화된 코드만 메인라인으로 올림.

```bash
# [1] 하향 병합 (Mainline ➔ Dev)
p4 merge -S //stream/dev
p4 resolve -am       # 충돌 자동 해결 (텍스트 안전 병합)
p4 submit -d "메인라인 최신 변경 사항을 개발 브랜치로 병합"

# [2] 상향 복사 (Dev ➔ Mainline)
p4 copy -S //stream/dev
p4 submit -d "개발 완료된 기능 메인라인으로 릴리즈 복사"
```

---

## 7. [3단계] 실무 응용: 리비전 지정자 & 파일 추적 (Revisions & Diff)

### 🏷️ P4 리비전 지정자(Revision Specifier) 문법

| 지정자 문법 | 의미 및 설명 | 사용 예시 |
| :--- | :--- | :--- |
| **`#head`** | 저장소의 가장 최신 리비전 | `p4 sync file.cpp#head` |
| **`#have`** | 내 로컬 워크스페이스가 현재 보유한 리비전 | `p4 diff file.cpp#have` |
| **`#<number>`** | 특정 리비전 번호 (1부터 시작) | `p4 diff file.cpp#3` |
| **`@<changelist>`**| 특정 체인지리스트 시점의 상태 | `p4 sync //depot/...@1020` |
| **`@<date>`** | 특정 날짜/시간 시점의 상태 | `p4 sync //depot/...@2026/10/10` |

```bash
# [1] 파일의 변경 히스토리 및 누가 수정했는지 확인
p4 filelog Content/Characters/Hero.uasset

# [2] 파일 라인별 작성자 추적 (Git blame과 동일)
p4 annotate -u Source/GameEngine.cpp

# [3] 내 로컬 수정본과 서버 최신본의 차이점 diff
p4 diff -du Source/Player.cpp
```

---

## 8. 실무 주의사항 & 게임 엔진 연동 모범 사례 (Best Practices)

### ⚠️ 초보자가 가장 흔히 겪는 5대 실수 및 해결책

| 증상 및 문제점 | 원인 분석 | 확실한 해결 가이드 |
| :--- | :--- | :--- |
| **P4 외부에서 파일 수정 후 파일이 여전히 Read-Only** | `p4 edit`을 실행하지 않고 에디터나 툴에서 강제 저장함 | **`p4 reconcile`** (또는 `p4 status`)를 실행하여 오프라인 변경 사항을 P4 작업 목록에 자동 반영 |
| **Submit 시 `File is out of date` 에러 발생** | 내가 작업하는 동안 다른 사람이 새 리비전을 먼저 올림 | **`p4 sync`** ➔ **`p4 resolve`** (충돌 해결) ➔ 다시 **`p4 submit`** |
| **동료가 파일을 락(`+l`) 걸어놓고 퇴근/휴가 감** | 독점 잠금이 유지되어 다른 작업자가 블로킹됨 | 관리자 권한으로 강제 잠금 해제: `p4 unlock -f //depot/.../file.uasset` |
| **불필요한 임시 파일이 P4에 대량 add 됨** | `.p4ignore` 파일 누락 | 워크스페이스 루트에 `.p4ignore` 파일 생성 후 `P4IGNORE=.p4ignore` 설정 |
| **워크스페이스를 잘못 삭제하여 파일 전체가 사라짐** | `p4 client -d` 시 로컬 파일 동기화 옵션 혼동 | 새 워크스페이스를 만들고 `p4 sync -f`로 강제 재동기화 |

---

### 🎮 언리얼 엔진 / 유니티 전용 `.p4ignore` 템플릿

프로젝트 루트에 `.p4ignore` 파일을 생성하고 환경변수로 등록합니다:
```bash
p4 set P4IGNORE=.p4ignore
```

```ini
# .p4ignore - Unreal Engine & Unity 표준 제외 목록

# 언리얼 엔진 (Unreal Engine 5)
Binaries/
Build/
DerivedDataCache/
Intermediate/
Saved/
.vscode/
.vs/
*.sln
*.vcxproj

# 유니티 (Unity)
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Mm]emoryCaptures/
*.csproj
*.unityproj
```
💬
Perforce (Helix Core / P4) 치트시트

의견 및 질문

댓글 수정

댓글 삭제
