Hugo로 멋진 블로그나 웹사이트를 만들고, Git으로 소스 코드를 관리하는 것은 이제 많은 분들에게 익숙한 과정입니다. 하지만 git add .과 git commit을 실행하기 전에, 우리는 한 가지 중요한 질문을 스스로에게 던져봐야 합니다. “어떤 파일을 Git으로 관리하고, 어떤 파일은 무시해야 할까?”
이 질문에 대한 해답을 주는 것이 바로 .gitignore 파일입니다. 잘 구성된 .gitignore 파일은 깨끗하고 효율적인 저장소 관리의 첫걸음이자, 개발자의 전문성을 보여주는 작지만 중요한 지표입니다.
오늘은 어떤 Hugo 프로젝트에도 바로 적용할 수 있는 표준 .gitignore 템플릿을 제공하고, 각 항목을 왜 추가해야 하는지 그 이유까지 명확하게 설명해 드리겠습니다.
왜 .gitignore 설정이 중요한가요?#
Git 관리의 핵심 원칙은 “소스 코드는 추적하고, 자동으로 생성되는 파일이나 민감한 정보는 제외한다” 는 것입니다. 만약 이 원칙을 지키지 않으면 다음과 같은 문제들이 발생할 수 있습니다.
- 저장소 용량 낭비 및 속도 저하:
hugo명령어를 실행하면public폴더에 수많은 HTML, CSS 파일들이 생성됩니다. 이 파일들을 모두 Git으로 관리하면 저장소 용량이 불필요하게 커지고, clone 이나 push/pull 속도가 느려집니다. - 의미 없는 충돌(Conflict) 발생: 협업 시 각자 생성한
public이나resources폴더 내용이 달라져 불필요한 병합 충돌이 발생합니다. 이는 해결하는 것 자체가 시간 낭비입니다. - 보안 사고 발생: API 키나 비밀번호가 담긴
.env파일이 실수로 GitHub Public 저장소에 올라가면, 심각한 보안 사고로 이어질 수 있습니다.
이 모든 문제를 예방하는 것이 바로 .gitignore의 역할입니다.
Hugo .gitignore 표준 템플릿#
아래는 어떤 Hugo 프로젝트에도 적용할 수 있는 표준 템플릿입니다. 이 내용을 프로젝트 최상위 폴더에 있는 .gitignore 파일에 그대로 복사해서 사용하세요.
코드 스니펫
# =========================================
# Hugo 생성 파일 (Hugo Generated Files)
# =========================================
# 'hugo' 빌드 시 생성되는 최종 결과물 폴더.
# 소스 코드만 있으면 언제든 재생성 가능하므로 반드시 제외.
/public/
# 이미지 처리, 에셋 번들링 등 Hugo Pipes 결과물이 캐시되는 폴더.
# 이 역시 소스로부터 재생성되므로 제외.
/resources/
# Hugo 빌드 중 생성되는 임시 잠금 파일.
.hugo_build.lock
# =========================================
# Node.js 의존성 (Node.js Dependencies)
# =========================================
# Tailwind CSS 등 Node.js 기반 도구 사용 시 생성되는 패키지 폴더.
# 'npm install' 명령어로 언제든 복구 가능하므로 제외.
/node_modules/
# =========================================
# OS 및 시스템 파일 (OS & System Files)
# =========================================
# macOS 시스템 파일
.DS_Store
# Windows 시스템 파일
Thumbs.db
# =========================================
# IDE 및 에디터 설정 (IDE & Editor Settings)
# =========================================
# Visual Studio Code 에디터 설정 폴더
.vscode/
# JetBrains 계열 에디터(GoLand, WebStorm 등) 설정 폴더
.idea/
# =========================================
# 민감한 정보 및 로그 (Sensitive Info & Logs)
# =========================================
# API 키, 비밀번호 등 민감한 정보를 담는 환경 변수 파일.
# 보안을 위해 절대로 Git에 커밋 금지!
.env
# 각종 로그 파일
*.log
내 프로젝트에 적용하는 방법#
적용 방법은 간단합니다. 하지만 이미 관련 파일들을 커밋한 이력이 있다면, 추가적인 명령어가 필요합니다.
.gitignore 파일 생성 및 내용 붙여넣기#
프로젝트 최상위 폴더에 .gitignore 파일이 없다면 생성하고, 위 템플릿 내용을 모두 복사하여 붙여넣습니다.
이미 커밋된 파일들을 Git 추적에서 제외하기#
만약 위 템플릿에 있는 파일이나 폴더(예: public, resources)를 이미 커밋한 적이 있다면, .gitignore에 추가해도 Git은 계속해서 해당 파일들을 추적합니다. 따라서 아래 명령어를 통해 Git의 추적 목록에서 명시적으로 제거해주어야 합니다.
# Git의 추적 목록(Staging Area)에서만 제거합니다.
# --cached 옵션 덕분에 내 컴퓨터에 있는 실제 폴더와 파일은 삭제되지 않습니다.
git rm -r --cached public/
git rm -r --cached resources/
# 만약 다른 파일들도 이미 커밋했다면 같은 방식으로 추가합니다.
# 예: git rm -r --cached .vscode/
# 이제 .gitignore 파일과 추적 제외 상태를 함께 커밋합니다.
git add .gitignore
git commit -m "Feat: Setup .gitignore and untrack generated files"
git push
이 과정을 거치면 앞으로 해당 파일들은 git status에 나타나지 않으며, 여러분은 오직 중요한 소스 코드 변경에만 집중할 수 있게 됩니다.
마무리하며#
.gitignore를 올바르게 설정하는 것은 단순히 몇 줄의 텍스트를 추가하는 행위가 아닙니다. 내 프로젝트의 무엇이 ‘소스’이고 무엇이 ‘결과물’인지를 명확히 정의하는 설계 과정의 일부이며, 깨끗하고 안전한 버전 관리를 위한 가장 기본적이고 중요한 습관입니다.
지금 바로 여러분의 Hugo 프로젝트에 이 표준 .gitignore 템플릿을 적용하여, 보다 전문적인 개발 환경을 구축해 보세요.