🐢
SVN (Subversion) 치트시트

Apache Subversion 중앙 집중식 버전 관리 완벽 가이드: 저장소 체크아웃(checkout), 커밋(commit), 업데이트(update), 브랜치 & 태그(copy/switch/merge), 충돌 해결(resolve), 바이너리 파일 잠금(lock/unlock), svn:ignore 속성 및 Git vs SVN 멘탈 모델 비교
#svn#subversion#vcs#apache-subversion#tortoisesvn#version-control#devops#git-svn최종 업데이트: 2026-10-10
SVN (Subversion) 치트시트 핵심 명령어 및 실전 가이드

## 1. 사전 요건 & 환경 구성 가이드 (Prerequisites & Installation)

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

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Windows, macOS, Linux (모든 OS 지원) | Ubuntu 22.04 LTS, Windows 11, macOS Sonoma | POSIX 및 Windows 환경 완전 지원 |
| **CPU** | 1 코어 이상 | 2 코어 ~ 4 코어 이상 | 저장소 diff 연산 및 네트워크 직렬화 처리 |
| **메모리 (RAM)** | 512 MB 이상 | 2 GB ~ 4 GB 이상 | 대규모 작업 사본(Working Copy) 트리 캐싱 |
| **디스크 (Storage)** | 100 MB 이상의 여유 공간 | 10 GB ~ 50 GB 이상의 SSD | 작업 사본 및 `.svn` 내부 프리스틴(Pristine) 사본 보관 |
| **네트워크 / 프로토콜** | svn CLI 1.14 LTS (최신 안정 버전) | `http://`, `https://`, `svn://`, `svn+ssh://` | 사내 인트라넷 또는 VPN 포트(3690 / 443) 허용 |

---

### 🚀 운영체제별 설치 명령어

```bash
# 🐧 [1] Ubuntu / Debian 설치
sudo apt update
sudo apt install -y subversion

# 🐧 [2] RHEL / Rocky Linux / CentOS
sudo dnf install -y subversion

# 🍏 [3] macOS (Homebrew)
brew install subversion

# 🪟 [4] Windows
# Chocolatey 또는 Winget으로 설치 (TortoiseSVN 추천)
winget install TortoiseSVN.TortoiseSVN
# 또는 순수 CLI
choco install svn

# 설치 및 버전 확인
svn --version
# 출력 예시: svn, version 1.14.3 (r1914484)
```

---

## 2. SVN 핵심 멘탈 모델: 중앙 집중식 VCS 아키텍처 (Mental Model)

SVN(Apache Subversion)은 Git과 같은 분산 버전 관리 시스템(DVCS)과 달리, 단 하나의 **중앙 서버(Central Repository)**가 모든 변경 이력과 **단일 전역 리비전 번호(Global Revision: r1, r2, r3...)**를 엄격하게 관리하는 중앙 집중식 버전 관리 시스템(CVCS)입니다.

### 📐 Git vs SVN 멘탈 모델 & 표준 레이아웃 (ASCII Diagram)

```text
[ SVN 중앙 집중식 아키텍처 ]
┌─────────────────────────────────────────────────────────────┐
│                 Central SVN Repository Server               │
│                                                             │
│  ├── /trunk       : 주 개발 메인 스트림 (Git의 main/master)  │
│  ├── /branches    : 기능 개발 및 릴리즈용 격리 브랜치         │
│  │   └── /feature-login (r12 ➔ r15)                         │
│  └── /tags        : 특정 시점 읽기 전용 릴리즈 스냅샷 (v1.0.0)│
│                                                             │
│  * 전체 저장소가 공유하는 단일 정수 리비전: r1 ➔ r2 ➔ r3...    │
└──────────────────────────────┬──────────────────────────────┘
                               │
               체크아웃 / 커밋 │ (checkout / commit)
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 Local Working Copy (로컬 작업 사본)          │
│                                                             │
│  - 로컬에는 저장소 전체 이력이 없음 (필요한 파일만 내려받음)│
│  - 숨김 폴더 `.svn` 안에 기준 원본(Pristine Base)만 보관     │
│  - 오프라인 커밋 불가 (반드시 중앙 서버와 통신해야 커밋 완료)│
└─────────────────────────────────────────────────────────────┘
```

### 🧩 Git vs SVN 핵심 차이점 한눈에 비교

| 비교 항목 | Git (분산 VCS) | SVN (중앙 집중 VCS) |
| :--- | :--- | :--- |
| **저장소 위치** | 모든 개발자 PC가 완전한 로컬 저장소를 복제 | **오직 원격 서버 1곳에만 저장소 존재** |
| **리비전 식별자** | 40자리 SHA-1 해시 (`a1b2c3d...`) | **순차적인 정수 번호 (`r1, r2, r100`)** |
| **부분 체크아웃** | 저장소 전체를 무조건 clone 해야 함 | **특정 하위 디렉토리만 단독 checkout 가능** |
| **파일 잠금 (Lock)** | 원칙적으로 불가능 (동시 편집 후 Merge) | **바이너리 파일 독점 잠금(`svn lock`) 완벽 지원** |
| **오프라인 작업** | 로컬에서 커밋, 브랜치, 로그 조회 가능 | **서버 네트워크 단절 시 커밋 불가능** |

---

## 3. [초보자 1단계] 3분 헬로월드: 체크아웃부터 첫 커밋까지 (Hello World)

로컬 테스트용 저장소를 생성하고, 작업 사본을 체크아웃하여 파일을 커밋하는 전체 라이프사이클입니다.

### ① 로컬 테스트 저장소 생성 및 표준 레이아웃 초기화
```bash
# 1. 로컬 파일 기반 SVN 저장소 생성
svnadmin create /tmp/svn-repo

# 2. 표준 3대 디렉토리(/trunk, /branches, /tags) 생성
svn mkdir file:///tmp/svn-repo/trunk file:///tmp/svn-repo/branches file:///tmp/svn-repo/tags -m "표준 디렉토리 구조 생성"
# 출력: Committed revision 1.
```

### ② 작업 사본 체크아웃 (Checkout)
```bash
# trunk 디렉토리만 로컬 작업 사본으로 체크아웃
svn checkout file:///tmp/svn-repo/trunk my-project
cd my-project
# 출력: Checked out revision 1.
```

### ③ 파일 생성, 추가 및 커밋 (Add & Commit)
```bash
# 신규 파일 생성
echo "Hello, SVN World!" > hello.txt

# 버전 관리에 파일 등록 (svn add)
svn add hello.txt
# 출력: A         hello.txt

# 상태 확인 (A: 추가 대기)
svn status
# 출력: A       hello.txt

# 중앙 저장소로 커밋 (svn commit)
svn commit -m "첫 번째 텍스트 파일 등록"
# 출력:
# Adding         hello.txt
# Transmitting file data .done
# Committing transaction...
# Committed revision 2.
```

### ④ 변경 이력 로그 확인 (Log)
```bash
svn log
```
```text
------------------------------------------------------------------------
r2 | sulucky | 2026-10-10 22:20:00 +0900 (Sat, 10 Oct 2026) | 1 line

첫 번째 텍스트 파일 등록
------------------------------------------------------------------------
r1 | sulucky | 2026-10-10 22:19:30 +0900 (Sat, 10 Oct 2026) | 1 line

표준 디렉토리 구조 생성
------------------------------------------------------------------------
```

---

## 4. [2단계] 핵심 기능: 일상 작업 & 상태 기호 해독 (Daily Work & Diff)

### 📋 `svn status` 기호 완전 해독표

`svn status` 실행 시 파일명 앞의 첫 번째 문자는 작업 사본의 변경 상태를 나타냅니다:

| 기호 | 영문 명칭 | 상태 설명 및 대처 방법 |
| :---: | :--- | :--- |
| **`?`** | Unversioned | 버전 관리에 포함되지 않은 신규 파일 ➔ `svn add` 또는 ignore 처리 |
| **`A`** | Added | 저장소에 추가 예정 상태 (다음 commit 시 반영) |
| **`M`** | Modified | 파일 내용이 로컬에서 수정됨 (다음 commit 시 반영) |
| **`D`** | Deleted | 삭제 예약 상태 (`svn delete` 실행됨) |
| **`C`** | Conflict | **충돌 발생!** 서버 원격본과 로컬 수정본이 충돌함 ➔ 해결 필수 |
| **`!`** | Missing | OS 명령어로 임의 삭제됨 ➔ `svn delete`로 공식 삭제하거나 `svn revert`로 복구 |
| **`~`** | Type Replaced | 파일이 디렉토리로 바뀌는 등 객체 타입이 교체됨 |

---

### 💻 일상 개발 필수 명령어 치트시트

```bash
# [1] 작업 시작 전: 서버의 최신 변경 사항으로 내 작업 사본 갱신 (매일 아침 필수!)
svn update

# [2] 내가 수정한 내용과 원본의 차이점 확인
svn diff
# 특정 파일만 diff 확인
svn diff hello.txt

# [3] 로컬 수정을 취소하고 서버 상태로 되돌리기 (Undo)
svn revert hello.txt
# 현재 디렉토리 이하 모든 수정을 일괄 롤백
svn revert -R .

# [4] 파일 이름 변경 및 이동 (히스토리 보존)
svn move old-name.txt new-name.txt

# [5] 파일 삭제
svn delete obsolete.txt

# [6] 특정 과거 리비전(r2)의 내용을 로컬로 임시 확인
svn cat -r 2 hello.txt
```

---

## 5. [2단계] 핵심 기능: 브랜치(Branch) & 태그(Tag) 관리 (Branching & Tagging)

SVN에서 브랜치와 태그는 독립적인 메커니즘이 아니며, 내부적으로 저장소 경로를 복사하는 **저렴한 복사(Cheap Copy)**로 동작합니다. 하드링크처럼 메타데이터만 복사하므로 용량을 차지하지 않습니다.

### ① 브랜치 생성 및 전환 (Branch & Switch)

```bash
# [1] trunk에서 새로운 기능 브랜치 생성 (서버 상에서 즉시 복사)
svn copy file:///tmp/svn-repo/trunk file:///tmp/svn-repo/branches/feature-auth \
    -m "인증 기능 개발용 브랜치 생성"

# [2] 내 로컬 작업 사본을 해당 브랜치로 즉시 전환 (Switch)
# 전체를 다시 받지 않고 trunk와 브랜치의 차이점만 고속 갱신!
svn switch file:///tmp/svn-repo/branches/feature-auth

# 현재 내가 어느 브랜치를 바라보고 있는지 확인
svn info | grep URL
# URL: file:///tmp/svn-repo/branches/feature-auth
```

---

### ② 브랜치 작업 후 trunk로 병합 (Merge)

```bash
# 1. 로컬 작업 사본을 다시 trunk로 전환
svn switch file:///tmp/svn-repo/trunk

# 2. 최신 trunk 상태로 갱신
svn update

# 3. feature-auth 브랜치에서 작업된 모든 커밋을 trunk 작업 사본으로 자동 병합
svn merge file:///tmp/svn-repo/branches/feature-auth

# 4. 병합 결과 확인 및 최종 커밋
svn diff
svn commit -m "feature-auth 브랜치 개발 완료 ➔ trunk 병합"
```

---

### ③ 릴리즈 태그 생성 (Tag)
태그는 절대 수정하지 않는 읽기 전용 릴리즈 스냅샷 관례입니다:
```bash
svn copy file:///tmp/svn-repo/trunk file:///tmp/svn-repo/tags/v1.0.0 \
    -m "프로덕션 v1.0.0 릴리즈 태그 생성"
```

---

## 6. [3단계] 실무 응용: 충돌 해결 & 바이너리 파일 독점 잠금 (Conflict & Locking)

### 💥 커밋/업데이트 충돌(Conflict) 완벽 해결법

다른 개발자가 먼저 커밋한 라인과 내가 수정한 라인이 겹치면 `svn update` 시 대화형 프롬프트가 뜹니다:

```text
Conflict discovered in 'hello.txt'.
Select: (p) postpone, (df) diff-full, (e) edit, (mc) mine-conflict,
        (tc) theirs-conflict, (s) show all options:
```

| 선택 옵션 | 동작 설명 |
| :---: | :--- |
| **`p`** (Postpone) | 충돌을 연기하고 파일 안에 `<<<<<<< .mine` 충돌 마커를 남김 (수동 병합용) |
| **`tc`** (Theirs Conflict) | 내 수정을 버리고 **서버(남의 것)** 코드를 전면 채택 |
| **`mc`** (Mine Conflict) | 서버 변경을 덮어쓰고 **내 로컬 코드**를 전면 채택 |
| **`e`** (Edit) | 기본 에디터를 열어 충돌 부분을 직접 실시간 수정 |

```bash
# p(연기)를 선택한 경우: 직접 파일을 수정한 뒤 충돌 해결 선언
vi hello.txt  # 충돌 마커(<<<<, ====, >>>>)를 수동 정리

# SVN에게 "충돌 해결 완료" 통보
svn resolve --accept working hello.txt

# 정상 커밋 완료
svn commit -m "충돌 수동 해결 후 커밋"
```

---

### 🔒 바이너리 파일 독점 잠금 (Lock / Unlock)

텍스트 파일과 달리 **엑셀 문서(`.xlsx`), 포토샵 파일(`.psd`), 3D 모델링, 컴파일된 바이너리**는 줄 단위 병합(Merge)이 불가능합니다. SVN의 비관적 락(Lock) 기능으로 한 번에 한 명만 수정하도록 잠급니다.

```bash
# [1] 파일에 배타적 잠금(Lock) 획득 (다른 개발자는 커밋 불가)
svn lock design.psd -m "UI 디자인 시안 수정 작업 중입니다."
# 출력: 'design.psd' locked by user 'sulucky'.

# [2] 현재 잠금 상태 확인
svn status
# 출력: K       design.psd  (K: 내가 락을 쥐고 있음 / O: 남이 락을 쥠)

# [3] 수정 및 커밋 (커밋 완료 시 잠금이 자동 해제됨)
svn commit -m "디자인 시안 업데이트"

# [4] 작업 도중 수동으로 잠금 반납 (수정 취소 시)
svn unlock design.psd

# [5] 휴가자/퇴사자의 잠금을 관리자 권한으로 강제 해제 (Break Lock)
svn unlock --force design.psd
```

---

## 7. [3단계] 실무 응용: `svn:ignore` 및 속성 관리 (Properties)

Git의 `.gitignore` 파일 대신, SVN은 디렉토리 자체에 **메타데이터 속성(Property)**을 부여합니다.

### 🚫 특정 파일/디렉토리 무시 (`svn:ignore`)

```bash
# [1] 단일 파일이나 패턴 무시 등록
svn propset svn:ignore "*.log" .
svn propset svn:ignore "node_modules" .

# [2] 여러 줄의 무시 목록을 텍스트 에디터로 직접 편집 (가장 추천)
svn propedit svn:ignore .
# 에디터가 열리면 무시할 파일/폴더를 한 줄씩 입력:
# target/
# build/
# *.class
# .env

# [3] 하위 모든 디렉토리에 재귀적으로 적용
svn propset svn:ignore -R "*.tmp" .

# [4] 속성 변경 사항도 반드시 커밋해야 서버에 반영됨!
svn commit -m "빌드 아티팩트 svn:ignore 속성 등록"
```

---

### 🔗 외부 저장소 서브모듈 연동 (`svn:externals`)

다른 공통 라이브러리 저장소를 특정 폴더로 자동 마운트합니다:
```bash
svn propedit svn:externals .
# 입력 형식: <로컬폴더명> <원격SVN_URL>
# lib/common file:///tmp/svn-repo/common/trunk
```

---

## 8. 실무 주의사항 & Git 마이그레이션 (Troubleshooting & Git Interop)

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

| 증상 및 문제점 | 원인 분석 | 확실한 해결 가이드 |
| :--- | :--- | :--- |
| **커밋 시 `Out of date` 에러 발생** | 원격 저장소에 다른 사람이 먼저 커밋을 올림 | 커밋 전 항상 **`svn update`**를 먼저 실행하여 최신 리비전을 병합한 후 커밋 |
| **탐색기에서 직접 파일 삭제 후 `!` 상태로 고정** | SVN 추적을 거치지 않고 OS 레벨에서 파일 삭제 | `svn delete <file>`로 SVN에게 알리거나, 복구하려면 `svn revert <file>` |
| **`.svn` 폴더를 손으로 건드렸다가 작업 사본 잠김** | 내부 sqlite DB 및 Pristine 파일 손상 | `svn cleanup` 명령어로 작업 사본 락을 풀고 정리 |
| **작업 사본 전체가 깨졌거나 멈춤 (`Working copy locked`)** | 프로세스가 강제 종료되어 락이 남음 | 프로젝트 루트에서 **`svn cleanup`** 실행 |
| **과거 특정 리비전으로 영구 롤백하고 싶음** | Git과 달리 리셋(reset) 개념이 없음 | 역병합(Reverse Merge) 수행: `svn merge -c -r15 .` 후 commit |

---

### 🔀 `git-svn`으로 Git 환경에서 SVN 저장소 다루기

사내 인프라가 SVN으로 묶여 있어도, 로컬에서는 Git의 강력한 로컬 커밋과 브랜칭을 그대로 활용할 수 있습니다:

```bash
# [1] SVN 저장소를 로컬 Git 리포지토리로 복제
git svn clone file:///tmp/svn-repo -s my-git-project
cd my-git-project

# [2] 로컬에서는 일반 Git처럼 자유롭게 작업
git add .
git commit -m "로컬 오프라인 커밋 1"
git commit -m "로컬 오프라인 커밋 2"

# [3] SVN 서버의 최신 변경 사항 풀 (rebase)
git svn rebase

# [4] 로컬 Git 커밋들을 SVN 중앙 서버로 일괄 푸시
git svn dcommit
```
💬
SVN (Subversion) 치트시트

의견 및 질문

댓글 수정

댓글 삭제
