dotfiles 관리 — chezmoi vs yadm vs raw symlink, Mac 기준 셋업

새 맥을 받을 때마다 .zshrc, .gitconfig, ~/.config/... 를 직접 복사 붙여넣기 하고 있다면 dotfiles 관리 도구가 필요하다. 한 번 셋업해두면 새 머신에서 한 줄 명령으로 모든 설정이 복원된다.

이 가이드는 3가지 접근(chezmoi · yadm · raw symlink + Git)을 비교하고, 권장안인 chezmoi의 실전 셋업까지.

TL;DR

1. 왜 dotfiles 관리 도구인가

직접 Git repo에 .zshrc 등을 두고 심볼릭 링크하는 방식도 동작한다. 다만 다음 문제가 누적된다:

• 머신별 차이: 회사 Mac의 git user.email vs 개인 머신. 분기 처리가 hardcoded.
• 시크릿: API 키·SSH config가 dotfiles에 섞이면 곤란. .gitignore 누락 위험.
• 양방향: 직접 ~/.zshrc를 수정하면 repo와 갈리고, 어느 게 진실인지 모호.
• 새 머신: 클론 → 의존성 설치 → 심볼릭 링크 → 권한 설정… 매번 반복.

dotfiles 관리 도구는 이걸 일관된 워크플로로 묶는다.

2. 옵션 비교

chezmoi

Go 기반 CLI. 템플릿 엔진(머신별 분기), 시크릿(1Password·Bitwarden 통합), 양방향 (chezmoi diff / chezmoi apply).

yadm

Git wrapper. .zshrc 같은 점 파일을 ~에서 직접 관리하는 Git 저장소처럼. 학습 비용 0. 머신별 분기는 alt 파일(.zshrc##os.Darwin)로 제한적 지원.

raw symlink + Git

~/dotfiles/ 에 파일 두고 install 스크립트로 심볼릭 링크. 가장 투명하지만 도구 기능이 없으니 모든 걸 직접 구현.

권장: chezmoi

1인 운영 1~3 머신 시나리오에서 chezmoi가 압도적. 처음 학습 1시간 투자로 평생 사용.

3. chezmoi 셋업

3.1 설치

brew install chezmoi

3.2 GitHub repo 준비

GitHub에 dotfiles private repo 생성 (이름 자유). 비어 있는 상태로 OK.

3.3 chezmoi 초기화

chezmoi init github.com/yourname/dotfiles
# 또는 SSH 가능하면:
chezmoi init git@github.com:yourname/dotfiles.git

~/.local/share/chezmoi/ 가 작업 영역 (실제 Git repo).

3.4 파일 추가

# .zshrc를 chezmoi 관리에 추가
chezmoi add ~/.zshrc
 
# 또는 여러 개 한 번에
chezmoi add ~/.gitconfig ~/.tmux.conf ~/.config/starship.toml

~/.local/share/chezmoi/dot_zshrc 같은 형태로 복사됨 (점 → dot_ prefix).

3.5 commit + push

chezmoi cd          # 작업 영역으로 이동
git add .
git commit -m "init dotfiles"
git push -u origin main
exit                # 원래 위치로

3.6 새 머신에서 복원

# 새 맥에서
brew install chezmoi
chezmoi init --apply github.com/yourname/dotfiles

끝. 모든 dotfiles가 ~로 복원되고 즉시 적용.

4. 머신별 분기 (템플릿)

chezmoi의 가장 강한 기능. 같은 .gitconfig를 회사/개인 머신에 다르게 적용:

~/.local/share/chezmoi/dot_gitconfig.tmpl

내용:

[user]
    name = Your Name
{{- if eq .chezmoi.hostname "Work-MacBook" }}
    email = me@company.com
    signingkey = AAAA....
{{- else }}
    email = personal@example.com
{{- end }}
 
[core]
    editor = nvim
    autocrlf = input

.tmpl 확장자 = 템플릿. chezmoi가 적용 시 hostname 기반으로 분기.

4.1 사용 가능 변수

chezmoi data       # 모든 컨텍스트 변수 출력

자주 쓰는 것:

• .chezmoi.os — darwin / linux / windows
• .chezmoi.hostname — 머신 이름
• .chezmoi.arch — arm64 / amd64
• 사용자 정의 — chezmoi edit-config 로 커스텀 변수 추가

4.2 OS별 파일

dot_zshrc 대신 dot_zshrc.tmpl 로 두고 OS 분기:

{{ if eq .chezmoi.os "darwin" -}}
# macOS 전용
export HOMEBREW_PREFIX="/opt/homebrew"
eval "$($HOMEBREW_PREFIX/bin/brew shellenv)"
{{ else if eq .chezmoi.os "linux" -}}
# Linux 전용
export PATH="$HOME/.linuxbrew/bin:$PATH"
{{ end -}}
 
# 공통
alias ll='ls -lah'

5. 시크릿 통합

dotfiles에 API 키·토큰 직접 작성 금지. chezmoi의 secret 도구 통합 사용:

1Password CLI

brew install --cask 1password 1password-cli
op signin

dot_ssh/config.tmpl:

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  PreferredAuthentications publickey

dot_env.tmpl 에 시크릿 참조:

export ANTHROPIC_API_KEY={{ onepasswordRead "op://Private/Anthropic/api_key" }}
export GITHUB_TOKEN={{ onepasswordRead "op://Private/GitHub/token" }}

chezmoi apply 시 1Password에서 값 fetch → 평문 .env로 작성. 이 평문 파일은 .gitignore되므로 repo에 안 들어감.

Bitwarden / pass / age

각각 chezmoi 공식 통합 — docs.chezmoi.io 참고.

6. 워크플로

일상

# 직접 ~/.zshrc 수정 후
chezmoi diff       # 변경 사항 확인
chezmoi add ~/.zshrc   # repo에 반영
chezmoi cd && git commit -am "tweak zshrc" && git push

다른 머신 동기화

chezmoi update     # git pull + apply

변경 미리보기

chezmoi diff       # 적용 전 변경 사항
chezmoi apply -v   # verbose 적용

일시적 변경

chezmoi edit ~/.zshrc   # source(=repo) 편집 후 자동 적용

7. yadm — 가장 가벼운 대안

학습 비용 0가 매력이라면 yadm:

brew install yadm
yadm init
yadm add ~/.zshrc
yadm commit -m "init"
yadm remote add origin git@github.com:yourname/dotfiles.git
yadm push -u origin main
 
# 다른 머신
yadm clone git@github.com:yourname/dotfiles.git

명령이 git과 똑같다 (sub-command만 yadm). 단점: 머신별 분기는 .zshrc##os.Darwin 같은 alt 파일로 제한적.

8. raw symlink + Git

최소 의존성:

mkdir ~/dotfiles && cd ~/dotfiles
git init
mv ~/.zshrc ~/dotfiles/zshrc
ln -s ~/dotfiles/zshrc ~/.zshrc
 
# install.sh
#!/usr/bin/env bash
for f in zshrc gitconfig tmux.conf; do
  ln -sf "$HOME/dotfiles/$f" "$HOME/.$f"
done

깨끗하지만 시크릿·분기 처리·새 머신 부트스트랩을 직접 구현해야 함. 1년 후 chezmoi로 이주하게 될 가능성 높음.

검증 방법

1. chezmoi diff → 변경 없음 (모두 적용된 상태)
2. ~/.zshrc 직접 수정 → chezmoi diff → 차이 표시
3. 새 머신(또는 클린 VM)에서 chezmoi init --apply github.com/you/dotfiles → 모든 dotfiles 복원
4. 템플릿 변경 후 chezmoi apply -v → hostname 기반 다른 결과
5. 1Password CLI 통합 — chezmoi apply 시 ~/.env에 평문 값 들어가지만 repo에는 안 들어감 확인

트러블슈팅

chezmoi apply가 변경 안 함

• chezmoi diff 로 의도 변경 확인. 차이가 없으면 정상.
• 파일 권한 차이로 chezmoi가 변경 감지 못 하는 경우 — chezmoi apply --force.

템플릿 문법 오류

{{ ... }} Go 템플릿. 닫는 -}} 빠뜨림, 변수 오타 흔함. chezmoi execute-template < dot_gitconfig.tmpl 로 dry-run.

1Password 통합이 안 됨

• op signin 후 세션 유지 시간 (기본 30분). eval $(op signin) 다시.
• chezmoi.toml (chezmoi edit-config)에 1Password 활성화 명시.

다른 머신에서 SSH 키 누락

SSH 키 자체는 dotfiles에 두지 말 것 (보안). 새 머신은 별도로 키 생성 + GitHub 등록. chezmoi는 ~/.ssh/config 같은 설정만.

~/.zshrc가 직접 수정 안 됨

chezmoi edit ~/.zshrc 사용 (source 파일 편집 후 자동 apply). 또는 source 파일을 직접 수정 후 chezmoi apply.

참고

• Mac 초기 셋업 — Homebrew 등 dotfiles 적용 전 사전 셋업
• Mac↔Win 파일 동기화 — dotfiles와 별개로 노트·프로젝트는 Syncthing
• chezmoi 공식 문서
• yadm

변경 이력

• 2026-05-12: 첫 작성. 3가지 접근 비교 + chezmoi 실전 셋업(템플릿·시크릿·워크플로) + 트러블슈팅 5종.