ZENO — 웹 개발, 디자인, 자격증 정리

📌 들어가며

이 글은 프로젝트를 시작할 때 Git과 GitHub를 처음부터 끝까지 제대로 설정하는 방법을 다룹니다. 특히 보안에 치명적인 .gitignore 설정을 중심으로, 실무에서 바로 사용할 수 있는 완벽한 초기 설정 방법을 소개합니다.

---

🎯 전체 흐름 한눈에 보기

 

 

1. 로컬에서 Git 초기화
2. GitHub에 저장소 생성
3. 로컬과 GitHub 연결
4. .gitignore 설정 (필수!)
5. 첫 커밋 및 업로드

이 5단계만 제대로 하면 프로젝트의 기초가 완벽하게 갖춰집니다.

---

🔧 1단계: Git 저장소 초기화

프로젝트 폴더로 이동

터미널(CMD, PowerShell, Git Bash)을 열고 프로젝트 폴더로 이동합니다:

 

 

bash

cd 프로젝트폴더경로

Git 초기화

 

 

bash

git init
```

**실행 결과**:
```
Initialized empty Git repository in 프로젝트경로/.git/

의미: 이제 이 폴더는 Git으로 버전 관리가 가능한 저장소가 되었습니다.

초기화 확인

 

 

bash

git status
```

**정상 출력 예시**:
```
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)

---

🔧 2단계: GitHub 저장소 생성

GitHub에서 새 저장소 만들기

1. GitHub에 로그인
2. 우측 상단 + 버튼 → New repository 클릭
3. 저장소 정보 입력:
   • Repository name: 프로젝트 이름 입력
   • Description: 프로젝트 설명 (선택사항)
   • Public / Private: 원하는 공개 범위 선택
4. ⚠️ 중요: 다음 옵션들은 모두 체크 해제
   • ❌ Add a README file
   • ❌ Add .gitignore
   • ❌ Choose a license
5. Create repository 버튼 클릭

왜 옵션을 체크 해제하나요?

이미 로컬에서 Git을 초기화했기 때문에, GitHub에서 파일을 자동 생성하면 충돌이 발생합니다. 빈 저장소를 만들고 로컬에서 직접 관리하는 것이 더 깔끔합니다.

---

🔧 3단계: 로컬과 GitHub 연결

원격 저장소 연결

GitHub에서 저장소를 생성하면 다음과 같은 명령어가 표시됩니다:

 

 

bash

git remote add origin https://github.com/사용자명/저장소명.git

터미널에 그대로 복사해서 실행하세요.

의미:

• origin: 원격 저장소의 별칭 (관례상 origin 사용)
• 뒤의 URL: GitHub 저장소 주소

연결 확인

 

 

bash

git remote -v
```

**정상 출력 예시**:
```
origin  https://github.com/사용자명/저장소명.git (fetch)
origin  https://github.com/사용자명/저장소명.git (push)

• (fetch): 원격에서 코드를 받아올 때 사용하는 주소
• (push): 원격으로 코드를 올릴 때 사용하는 주소

---

🔧 4단계: .gitignore 설정 (가장 중요!)

.gitignore가 뭔가요?

Git에 절대 올리면 안 되는 파일들을 지정하는 설정 파일입니다.

왜 중요한가요?

잘못 올리면 다음과 같은 문제가 발생합니다:

• 🔥 .env 파일 올림 → API 키 유출 → 해킹 + 과금 폭탄
• 💣 node_modules 올림 → 저장소 용량 폭발 (수백 MB ~ GB)
• 🗑️ 빌드 파일 올림 → Git 이력 더러워짐
• ⚙️ IDE 설정 올림 → 다른 사람 환경 망가짐

.gitignore 파일 생성 및 설정

프로젝트 루트 폴더에 .gitignore 파일을 생성하고 다음 내용을 붙여넣으세요:

 

 

gitignore

# ========================================
# 환경 변수 (보안 최우선!)
# ========================================
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env.*.local

# ========================================
# Node.js 의존성
# ========================================
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# ========================================
# 빌드 출력물
# ========================================
.next/
out/
dist/
build/
.nuxt/
.cache/

# ========================================
# 로그 파일
# ========================================
*.log
logs/

# ========================================
# IDE 설정 파일
# ========================================
.vscode/
.idea/
*.swp
*.swo

# ========================================
# 운영체제 자동 생성 파일
# ========================================
.DS_Store
Thumbs.db

# ========================================
# 임시 폴더
# ========================================
tmp/
temp/

---

📚 .gitignore 항목별 상세 설명

🔐 1. 환경 변수 파일

 

 

gitignore

.env
.env.local
.env.*.local

무엇이 들어있나요?

• API 키 (OpenAI, Google Maps, AWS 등)
• 데이터베이스 비밀번호
• 비밀 토큰
• OAuth 클라이언트 시크릿

왜 절대 올리면 안 되나요?

• GitHub에 올라가는 순간 전 세계에 공개됨
• 봇들이 자동으로 키를 탐지해서 악용
• 실제 피해 사례: AWS 키 유출로 수백만 원 과금

올바른 관리 방법:

 

 

env

# .env (절대 Git에 올리지 않음)
API_KEY=sk-1234567890abcdefghijklmnop
DATABASE_URL=postgresql://user:password@localhost/db

 

 

env

# .env.example (이건 Git에 올려도 됨 - 구조만 공유)
API_KEY=여기에_실제_API_키를_입력하세요
DATABASE_URL=여기에_데이터베이스_URL을_입력하세요

---

📦 2. node_modules 폴더

 

 

gitignore

node_modules/

무엇인가요?

• npm install로 설치되는 모든 라이브러리 파일

왜 무시해야 하나요?

• ✅ 용량이 엄청 큼 (수백 MB ~ 수 GB)
• ✅ OS/환경마다 다를 수 있음
• ✅ package.json만 있으면 언제든 npm install로 재생성 가능
• ✅ 올려봤자 Git 저장소만 무거워짐

다른 사람이 프로젝트를 받으면?

 

 

bash

# 다른 사람이 실행하는 명령어
git clone 저장소주소
cd 프로젝트폴더
npm install  ← node_modules 자동 생성

---

🏗️ 3. 빌드 출력물

 

 

gitignore

.next/
dist/
build/

무엇인가요?

• React, Next.js, Vue 등이 자동으로 만드는 결과물 폴더

왜 무시해야 하나요?

• ✅ 소스 코드가 아닌 결과물일 뿐
• ✅ 언제든 npm run build로 재생성 가능
• ✅ 용량이 크고 불필요
• ✅ 배포 시 자동으로 새로 빌드됨

---

🧾 4. 로그 파일

 

 

gitignore

npm-debug.log*
yarn-debug.log*
*.log

무엇인가요?

• 에러 발생 시 자동 생성되는 로그 기록

왜 무시해야 하나요?

• ✅ 내 PC에서만 의미 있음
• ✅ 다른 사람에게는 쓸모없음
• ✅ 계속 쌓이면 Git 이력만 더러워짐

---

💻 5. IDE 설정 파일

 

 

gitignore

.vscode/
.idea/

무엇인가요?

• VS Code, IntelliJ 등의 개인 개발 환경 설정

왜 무시해야 하나요?

• ✅ 사람마다 선호하는 설정이 다름
• ✅ 강제로 공유하면 팀원 환경을 망칠 수 있음
• ✅ 프로젝트 코드와 무관한 개인 취향

예외: 팀 전체가 사용할 설정은 공유 가능

 

 

json

// .vscode/settings.json (팀 전체가 사용할 설정은 Git에 포함 가능)
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

---

🖥️ 6. 운영체제 자동 생성 파일

 

 

gitignore

.DS_Store    # macOS
Thumbs.db    # Windows

무엇인가요?

• macOS: 폴더 보기 설정을 저장하는 파일
• Windows: 이미지 미리보기 캐시 파일

왜 무시해야 하나요?

• ✅ 개발과 아무 관련 없음
• ✅ OS가 자동으로 만드는 쓰레기 파일
• ✅ 올라가면 "왜 이런 게 있냐" 지적받음

---

🗑️ 7. 임시 폴더

 

 

gitignore

tmp/
temp/

무엇인가요?

• 임시 파일을 저장하는 폴더

왜 무시해야 하나요?

• ✅ 언제든 지워도 되는 임시 데이터
• ✅ 공유할 가치가 없음

---

🔧 5단계: 첫 커밋 및 GitHub 업로드

변경사항 확인

 

 

bash

git status
```

**출력 예시**:
```
Untracked files:
  .gitignore
  index.html
  package.json
  src/

모든 파일 스테이징

 

 

bash

git add .

의미: 현재 폴더의 모든 파일을 커밋 대기 상태로 등록 (.gitignore에 있는 파일은 자동 제외됨)

스테이징 확인

 

 

bash

git status
```

**출력 예시**:
```
Changes to be committed:
  new file:   .gitignore
  new file:   index.html
  new file:   package.json
  new file:   src/App.js

.env나 node_modules가 여기 나타나면 안 됩니다!

첫 커밋 생성

 

 

bash

git commit -m "init: 프로젝트 초기 구조 설정"

커밋 메시지 작성 팁:

 

 

bash

git commit -m "init: 프로젝트 초기화"
git commit -m "feat: 로그인 기능 추가"
git commit -m "fix: 회원가입 버그 수정"
git commit -m "docs: README 업데이트"
git commit -m "style: 코드 포맷팅"

GitHub에 업로드

 

 

bash

git push -u origin main

각 부분의 의미:

• git push: GitHub에 업로드
• -u: 앞으로는 git push만 입력해도 자동으로 origin main으로 보내기
• origin: 원격 저장소 별칭
• main: 메인 브랜치 이름

첫 업로드 후에는 간단하게:

 

 

bash

git push

---

✅ 전체 명령어 흐름 정리

 

 

bash

# 1. Git 초기화
git init

# 2. 원격 저장소 연결
git remote add origin https://github.com/사용자명/저장소명.git

# 3. 연결 확인
git remote -v

# 4. .gitignore 파일 생성 (위 내용 참고)

# 5. 파일 스테이징
git add .

# 6. 커밋 생성
git commit -m "init: 프로젝트 초기 구조 설정"

# 7. GitHub에 업로드
git push -u origin main

---

🔄 일상적인 Git 작업 흐름

프로젝트를 계속 개발하면서 사용하는 명령어:

 

 

bash

# 1. 코드 수정 작업

# 2. 변경사항 확인
git status

# 3. 변경된 파일 스테이징
git add .

# 4. 커밋 생성
git commit -m "feat: 새로운 기능 추가"

# 5. GitHub에 업로드
git push

---

🚨 자주 하는 실수와 해결법

실수 1: .env 파일을 커밋했을 때

 

 

bash

# 즉시 실행!
git rm --cached .env

# .gitignore에 추가 (없다면)
echo ".env" >> .gitignore

# 변경사항 커밋
git add .gitignore
git commit -m "fix: .env 파일 추적 제거"
git push

⚠️ 매우 중요: 이미 GitHub에 올라간 API 키는 이력에 남으므로 즉시 재발급해야 합니다!

실수 2: node_modules를 커밋했을 때

 

 

bash

# Git 추적에서 제거
git rm -r --cached node_modules

# .gitignore 확인 (있어야 함)
# node_modules/ 가 .gitignore에 있는지 확인

# 변경사항 커밋
git add .gitignore
git commit -m "fix: node_modules 추적 제거"
git push

실수 3: 커밋 메시지를 잘못 작성했을 때

 

 

bash

# 마지막 커밋 메시지만 수정 (아직 push 안 했을 때)
git commit --amend -m "올바른 메시지"

# 이미 push 했다면 그냥 놔두는 게 나음

실수 4: 잘못된 파일을 스테이징했을 때

 

 

bash

# 특정 파일만 스테이징 취소
git reset HEAD 파일명

# 전체 스테이징 취소
git reset HEAD

---

📋 프로젝트 시작 체크리스트

새 프로젝트를 시작할 때 확인하세요:

필수 단계

• git init - Git 저장소 초기화
• .gitignore 파일 생성 및 설정
• GitHub에서 저장소 생성
• git remote add origin - 원격 저장소 연결
• git remote -v - 연결 확인

보안 확인

• .env 파일이 .gitignore에 포함되었는지 확인
• node_modules가 .gitignore에 포함되었는지 확인
• git status로 민감한 파일이 추적되지 않는지 확인

첫 커밋

• git add . - 파일 스테이징
• git commit -m "init" - 첫 커밋
• git push -u origin main - GitHub 업로드

추가 작업

• README.md 파일 작성
• .env.example 파일 생성 (구조 공유용)