윈도우에서 Claude Code를 쓰려면 Git for Windows가 먼저 깔려 있어야 합니다. 문제는 설치 마법사가 영어로 열 몇 단계나 이어진다는 점입니다. 대부분은 그냥 Next를 눌러도 되지만, 딱 5군데는 잘못 고르면 나중에 반드시 문제가 터집니다. 그 5개가 어디인지, 왜 그렇게 골라야 하는지를 화면 순서대로 정리했습니다.
설치 전 확인 (Before You Start)
| 항목 | 내용 |
|---|---|
| 다운로드 | git-scm.com/downloads/win |
| 용도 | 코드 버전관리 + Claude Code의 Bash 도구 제공 |
| 필수 여부 | 필수 |
| 관리자 권한 | 필수는 아니지만 권장 |
| 소요 시간 / 용량 | 다운로드 포함 5~10분 / 디스크 약 400MB |
- 이미 깔려 있는지 확인 — PowerShell에서
git --version을 입력해 버전이 나오면 이미 설치된 상태입니다. 이 경우 신규 설치가 아니라 업그레이드로 진행되며, 기존.gitconfig설정은 그대로 유지됩니다. - 관공서·회사 PC 주의 — 백신이나 보안 프로그램이 설치 파일을 차단·격리할 수 있습니다. 또 내부망에 SSL 검사 장비가 있으면 10단계에서 선택을 달리해야 합니다.
잘못 고르면 실제로 문제가 되는 화면은 5개뿐입니다.
05(구성요소) · 07(에디터) · 08(브랜치명) · 09(PATH) · 10(HTTPS)
나머지는 기본값 그대로 Next를 눌러도 무방합니다.
01. Download the Installer (설치 파일 다운로드)
브라우저에서 git-scm.com/downloads/win에 접속합니다.
- 받을 파일은 64-bit Git for Windows Setup(Standalone Installer)입니다. Windows 10/11이면 사실상 전부 64-bit입니다.
- Portable(thumbdrive edition)은 받지 마세요. PATH에 등록되지 않아 VS Code와 Claude Code가 git을 찾지 못합니다.
- 다운로드가 백신에 차단된다면 파일이 손상된 게 아니라 정책 문제입니다. 임시로 실시간 감시를 끄거나 IT 담당자에게 예외 처리를 요청하세요.
02. Run as Administrator (관리자 권한으로 실행)
다운로드한 .exe 파일을 우클릭 → 관리자 권한으로 실행합니다.
- 관리자 권한은 필수가 아니지만 권장입니다. 권한이 있으면
C:\Program Files\Git에 모든 사용자용으로 설치되고, 없으면 사용자 폴더(AppData)에 설치되어 다른 계정에서는 git을 쓸 수 없습니다. - UAC(사용자 계정 컨트롤) 창이 뜨면 예를 누릅니다.
- 설치 중에는 VS Code, PowerShell, Git Bash 등 git을 쓰는 프로그램을 모두 닫아두세요. 열려 있으면 파일 잠금 때문에 설치가 실패할 수 있습니다.
03. Information (라이선스 고지)
GNU GPL 라이선스 고지 화면입니다. 읽지 않고 Next를 눌러도 무방합니다.
다만 화면 상단(또는 설치 파일명)의 버전 번호는 메모해두세요. 나중에 오류가 났을 때 버전에 따라 해결법이 달라집니다.
04. Select Destination Location (설치 경로 선택)
기본값 C:\Program Files\Git 유지를 권장합니다.
- 피해야 할 경로: 한글이 포함된 경로, OneDrive·구글드라이브 동기화 폴더(파일 잠금 충돌), 네트워크 드라이브. 경로에 한글이 있으면 일부 Unix 계열 도구가 경로를 인식하지 못합니다.
- 재설치·업그레이드 시에는 기존 경로가 자동으로 채워집니다. 여기서 다른 경로를 지정하면 git이 두 벌 설치되어 PATH가 충돌하므로 그대로 두세요.
05. Select Components (구성 요소 선택) ⚠️
| 항목 | 권장 | 설명 |
|---|---|---|
| Windows Explorer integration | 체크 유지 | 폴더 우클릭에 "Git Bash Here"가 생김. 작업 폴더에서 바로 터미널을 열 수 있어 실사용 편의가 가장 큼 |
| Git LFS (Large File Support) | 체크 유지 | 엑셀·이미지·수집 데이터 등 대용량 바이너리를 버전관리할 때 필요. 지금 안 써도 켜두면 손해 없음 |
| Associate .git* / .sh files | 체크 유지 | 설정 파일과 셸 스크립트 연결. 기본값 유지 |
| Add a Git Bash Profile to Windows Terminal | 체크 권장 | Windows Terminal 사용 시 탭에서 바로 Git Bash 실행 |
| Check daily for updates | 선택 | 업데이트 알림. 기관 PC라면 해제해도 무방 |
| (NEW!) Scalar | 해제 가능 | 초대형 저장소 관리 도구. 개인 프로젝트에는 불필요 |
06. Select Start Menu Folder (시작 메뉴 폴더)
기본값 Git 그대로 Next를 누르면 됩니다.
"Don't create a Start Menu folder"를 체크하면 시작 메뉴에서 Git Bash를 찾을 수 없어 불편해집니다. 굳이 체크하지 마세요.
07. Choosing the Default Editor (기본 편집기 선택) ⚠️
기본값은 Vim인데, 이 화면의 최대 함정입니다. Vim은 종료 방법(Esc → :q! → Enter)을 모르면 커밋 메시지 창에서 아예 빠져나오지 못합니다. 반드시 기본값을 바꾸세요.
- VS Code가 이미 설치되어 있다면 → Use Visual Studio Code as Git's default editor
- 아직 없다면 → Use Notepad as Git's default editor
나중에 변경하려면 재설치 없이 명령 한 줄이면 됩니다.
git config --global core.editor "code --wait"08. Adjusting the Name of the Initial Branch (초기 브랜치명 설정) ⚠️
Override the default branch name for new repositories를 선택하고 입력란에 main을 입력하세요.
- 이 설정은 앞으로
git init으로 만드는 저장소의 첫 브랜치 이름을 정합니다. 기존 저장소에는 영향이 없습니다. - 기본값 "Let Git decide"는
master를 사용합니다. 그런데 GitHub의 기본은main이라 이름이 서로 어긋납니다.
초기 브랜치명을
master로 두면 GitHub와 불일치해서 첫 push 때 문제가 발생합니다. 반드시main으로 지정하세요.
09. Adjusting Your PATH Environment (PATH 환경 설정) ⚠️
이 화면을 잘못 고르면 Claude Code와 VS Code가 git을 아예 못 찾습니다. 반드시 가운데를 선택하세요.
| 선택지 | 동작 | 판단 |
|---|---|---|
| Use Git from Git Bash only | Git Bash 안에서만 git 명령 사용 가능 | 선택 금지. PowerShell·CMD·VS Code 터미널에서 git이 동작하지 않음 |
| Git from the command line and also from 3rd-party software | git과 최소한의 Unix 도구만 PATH에 추가 | 권장(기본값). 어떤 터미널에서도 git이 동작 |
| Use Git and optional Unix tools from the Command Prompt | find, sort 등 Unix 도구까지 전부 PATH에 추가 | 비권장. Windows 기본 명령(find, sort)이 Unix 버전으로 덮여 배치파일·VBA의 Shell 호출이 오작동할 수 있음 |
10. Choosing the HTTPS Transport Backend (HTTPS 통신 방식) ⚠️
개인 PC는 기본값, 기관 내부망 PC는 두 번째를 고르세요.
| 선택지 | 인증서 출처 | 판단 |
|---|---|---|
| Use the OpenSSL library | Git이 자체 보유한 인증서 목록(ca-bundle.crt) | 기본값. 일반 인터넷 환경에서 권장 |
| Use the native Windows Secure Channel library | Windows 인증서 저장소 | 회사·관공서망처럼 보안장비가 SSL 트래픽을 검사(SSL Inspection)하는 환경에서 권장. 사내 루트 인증서를 그대로 사용 |
OpenSSL로 설치했다가 SSL certificate problem: unable to get local issuer certificate 오류가 나면, 재설치 없이 아래 명령으로 전환하면 됩니다.
git config --global http.sslBackend schannel
http.sslVerify false(인증서 검증 끄기)로 우회하지 마세요. 통신 내용이 검증 없이 전송되어 보안상 위험합니다.
11. Configuring the Line Ending Conversions (줄바꿈 변환 설정)
Windows는 줄바꿈이 CRLF, Linux·Mac은 LF입니다. 이 차이를 Git이 자동으로 변환할지 정하는 화면입니다.
| 선택지 | 설정값 | 판단 |
|---|---|---|
| Checkout Windows-style, commit Unix-style | core.autocrlf=true |
권장(기본값). 내려받을 때 CRLF, 커밋할 때 LF로 자동 변환 |
| Checkout as-is, commit Unix-style | core.autocrlf=input |
Mac·Linux와 함께 작업할 때 사용 |
| Checkout as-is, commit as-is | core.autocrlf=false |
비권장. 협업 시 줄바꿈이 뒤섞임 |
- 기본값을 임의로 바꾸면 나중에 Git이 "파일 전체가 변경됨"으로 잘못 인식합니다. 한 글자도 안 고쳤는데 변경 내역이 온통 빨갛게 뜨는 상황입니다.
.bat,.cmd파일은 CRLF가 아니면 실행이 깨질 수 있습니다. 저장소 단위로 확실히 고정하려면 프로젝트 루트에.gitattributes를 두는 것이 정석입니다.
12. Configuring the Terminal Emulator (터미널 환경 선택)
| 선택지 | 장점 | 단점 |
|---|---|---|
| Use MinTTY (기본값) | 색상·유니코드 표시가 깔끔하고 창 크기 조절이 자유로움 | Git Bash에서 python, node 같은 대화형 프로그램 실행 시 멈춤 → 앞에 winpty를 붙여야 함 |
| Use Windows' default console window | Windows 프로그램과의 호환성 문제 없음 | 복사·붙여넣기와 화면 표시가 다소 불편 |
판단 기준: 작업을 주로 PowerShell이나 VS Code 터미널에서 한다면 어느 쪽을 골라도 차이가 없습니다. Git Bash를 주력 터미널로 쓸 계획이면 MinTTY가 낫습니다.
13. Choose the Default Behavior of 'git pull' (git pull 기본 동작)
원격 저장소와 내 로컬이 서로 다르게 변경됐을 때 git pull이 어떻게 처리할지 정하는 화면입니다.
| 선택지 | 동작 | 판단 |
|---|---|---|
| Merge (기본값, 화면에는 "Default (fast-forward or merge)") | 분기가 생기면 병합 커밋을 만들어 합침 | 권장. 어떤 상황에서도 pull이 실패하지 않음 |
| Rebase | 내 로컬 커밋을 원격 뒤로 다시 씀 | 히스토리는 깔끔하지만, 충돌 시 해결 절차가 복잡함 |
| Fast-forward only | 분기가 생기면 아예 중단 | 안전하지만 초보자에게는 "왜 안 되지?" 상황이 잦음 |
혼자 쓰는 저장소라면 세 선택지의 실질적 차이는 거의 없습니다. 다만 GitHub 웹에서 README를 직접 수정한 뒤 로컬에서도 뭔가 고친 상황처럼 분기가 생겼을 때, Merge만 아무 설정 없이 그냥 통과합니다.
나중에 바꾸고 싶으면 재설치 없이 명령 한 줄이면 됩니다.
git config --global pull.rebase true14. Choose a Credential Helper (인증 정보 관리 방식)
Git Credential Manager(기본값)를 선택하세요. 최초 push 때 브라우저 로그인 창이 뜨고, 이후 인증 정보는 Windows 자격 증명 관리자에 암호화되어 저장됩니다.
- 중요: GitHub는 2021년 8월부터 계정 비밀번호로는 push할 수 없습니다. 비밀번호 입력창이 뜨면 비밀번호가 아니라 PAT(Personal Access Token)를 넣거나, 브라우저 OAuth 로그인을 이용해야 합니다.
- "None"을 선택하면 push할 때마다 인증 정보를 다시 입력해야 합니다. 특별한 이유가 없으면 고르지 마세요.
- 계정을 바꾸거나 인증 오류가 반복될 때는 제어판 → 자격 증명 관리자 → Windows 자격 증명에서
git:https://github.com항목을 삭제한 뒤 다시 로그인하면 해결됩니다.
15. Configuring Extra Options (추가 옵션 설정)
- Enable file system caching — 체크 유지. 파일 상태 조회 속도가 빨라집니다.
- Enable symbolic links — 기본 해제 유지. 체크해도 Windows에서는 관리자 권한이나 개발자 모드가 있어야 동작하고, 없으면 오히려 오류가 납니다.
- 다음 화면에 Experimental options(pseudo consoles, built-in file system monitor 등)가 나오면 모두 해제하세요. 이름 그대로 실험 기능이라 원인 파악이 어려운 오류의 출처가 됩니다.
16. Installing (설치 진행)
- 보통 1~2분이면 끝납니다. 백신이 검사 중이면 더 걸릴 수 있습니다.
- 진행 중 취소하지 마세요. 중단하면 파일이 일부만 남아 재설치 시 오류가 납니다. 이 경우 제어판에서 제거 후 다시 설치해야 합니다.
17. Completing the Setup (설치 완료)
- "View Release Notes" 체크는 해제해도 무방합니다.
- 확인 방법: 새로 PowerShell 창을 열고
git --version입력 → 버전이 출력되면 성공.
PATH는 새로 여는 프로그램에만 적용됩니다. 설치 전부터 열려 있던 터미널이나 VS Code에서는 "git을 찾을 수 없습니다" 오류가 그대로 납니다. VS Code는 완전히 종료 후 재실행하세요. 그래도 안 되면 재부팅.
18. Initial Configuration (설치 후 최초 1회 설정)
Git은 "누가 이 코드를 고쳤는지"를 커밋마다 기록합니다. 그래서 이름과 이메일을 한 번은 등록해 줘야 합니다. 시작 메뉴에서 PowerShell을 실행한 뒤 아래를 입력하세요.
git config --global user.name "본인이름"
git config --global user.email "본인이메일@example.com"
git config --global core.quotepath false세 번째 줄이 핵심입니다. 이 설정이 없으면 한글 파일명이 \355\225\234\352\270\200 같은 숫자 코드로 표시되어, git status를 찍어도 무슨 파일이 바뀐 건지 알아볼 수 없습니다.
여기에 더해 아래 네 줄까지 넣어두면, 이후 겪을 문제 상당수를 미리 막을 수 있습니다.
git config --global init.defaultBranch main
git config --global core.autocrlf true
git config --global core.longpaths true
git config --global pull.rebase falseinit.defaultBranch main— 08단계 설정을 명령으로 재확인·수정core.autocrlf true— 11단계 줄바꿈 설정 고정core.longpaths true— Windows의 260자 경로 제한 때문에 생기는Filename too long오류 방지pull.rebase false— 13단계의 Merge 방식 고정
이메일 두 가지 주의점
①user.email은 GitHub 계정에 등록된 이메일과 일치해야 커밋이 본인 기록(잔디)으로 집계됩니다.
② 공개 저장소에 push하면 이 이메일이 그대로 공개됩니다. 노출을 원치 않으면 GitHub 설정에서 제공하는아이디@users.noreply.github.com형식의 비공개 이메일을 사용하세요.
19. Verifying the Configuration (설정 결과 확인)
git config --global --list
git config --list --show-origin- 첫 번째 명령은 전체 설정을, 두 번째는 어떤 파일에서 온 설정인지까지 보여줍니다.
- 설정 파일의 실제 위치는
C:\Users\<사용자명>\.gitconfig이며, 메모장으로 직접 편집할 수 있습니다. - 이
.gitconfig파일 하나만 백업해두면 PC를 바꿔도 설정을 그대로 복원할 수 있습니다.
오류 대처표 (Troubleshooting)
| 증상 | 원인 | 해결 |
|---|---|---|
'git'은(는) 내부 또는 외부 명령... 이 아닙니다 |
PATH 미적용, 또는 09단계에서 첫 번째 선택 | 터미널·VS Code를 완전히 종료 후 재실행 → 안 되면 재부팅 → 여전하면 재설치 후 09단계 가운데 선택 |
SSL certificate problem |
내부망 SSL 검사 장비 | git config --global http.sslBackend schannel |
한글 파일명이 \355\225\234 형태로 표시됨 |
core.quotepath 기본값 |
git config --global core.quotepath false |
Filename too long |
Windows 260자 경로 제한 | git config --global core.longpaths true |
| 커밋 메시지 창에서 빠져나올 수 없음 | 기본 에디터가 Vim | Esc → :q! → Enter. 이후 07단계 에디터 변경 |
LF will be replaced by CRLF 경고 |
줄바꿈 자동 변환 안내 | 정상 동작. 무시해도 됨 |
| push 시 인증 실패 반복 | 저장된 옛 계정 정보 | 제어판 → 자격 증명 관리자 → git:https://github.com 삭제 후 재로그인 |
src refspec main does not match any |
로컬 브랜치가 master |
git branch -m master main |
설치와 무관하게 반드시 기억할 것
- Git은 되돌리기 도구이지 백업 도구가 아닙니다. 커밋하지 않은 작업은 어떤 명령으로도 복구되지 않습니다.
- 개인정보와 인증정보는 절대 커밋하지 마세요. API 키, 비밀번호, 개인정보가 포함된 데이터 파일은
.gitignore에 먼저 등록한 뒤 작업을 시작합니다. 한 번 push된 파일은 이후 삭제해도 커밋 히스토리에 영구히 남습니다. - 업무 자료를 개인 GitHub 저장소에 올리지 않도록 주의하세요. 개인 저장소는 기본이 Public이 아니지만, 실수로 공개 전환되는 사고가 흔합니다.
여기까지 하면 로컬 환경의 첫 번째 조각이 완성됐습니다. 다음 글에서는 이 위에 얹을 나머지 도구를 이어서 설치합니다.