.dotfiles

개인 macOS 개발 환경 세팅. 새 맥에서 명령어 한 줄로 재현 가능하게 만든 저장소입니다.

구성 파일

파일	역할
Brewfile.personal	회사와 무관하게 항상 쓰는 개인용 도구
Brewfile.work	현재 회사 스택 (Atlassian, GitLab, Android/Flutter, GCP) — 선택 설치
mise/config.toml	mise가 관리하는 전역 런타임 버전 (현재는 node = "lts"만)
zsh/.zshrc	쉘 설정: zinit(git 플러그인만) + starship 프롬프트 + mise + zoxide/atuin/fzf + 최신 CLI alias
git/.gitconfig	delta를 pager/diff 뷰어로 사용. 이메일/이름은 안 담음 (아래 참고)
starship.toml	Catppuccin Mocha 톤 프롬프트
ghostty/config	터미널 에뮬레이터 설정 (Catppuccin Mocha, 반투명 배경)
btop/btop.conf, btop/themes/catppuccin_mocha.theme	리소스 모니터 테마 (Catppuccin Mocha, 배경은 Ghostty 반투명과 맞춰 투명 처리)
install.sh	위 전부를 새 macOS 머신에 세팅하는 스크립트

저장소에 일부러 담지 않은 것

• API 토큰 없음. gh/glab/acli 인증 정보는 저장소 밖에 있고, 클론 후 각각 gh auth login / glab auth login / acli auth login으로 직접 로그인합니다.
• git 이름/이메일 없음. git/.gitconfig는 ~/.gitconfig.local을 include 하는데, 이 파일은 install.sh가 대화형으로 물어봐서 생성합니다 (커밋되지 않음).
• SSH 키 없음. 이전 맥에서 직접 복사하거나 ssh-keygen으로 새로 발급합니다.
• ~/.claude 설정 없음. 세션 상태나 회사 프로젝트 관련 메모는 공개 저장소에 넣지 않습니다.

설치 방법

git clone https://github.com/ykss/.dotfiles.git ~/projects/.dotfiles
cd ~/projects/.dotfiles
./install.sh

install.sh가 하는 일:

1. Homebrew가 없으면 설치
2. mise를 설치하고 mise/config.toml을 연결한 뒤 mise install 실행 — 이후 단계에서 npm install -g가 돌기 전에 Node가 먼저 준비되도록 순서를 맞춤
3. Brewfile.personal로 brew bundle install 실행 (업무용 도구도 설치할지 물어보고, 원하면 Brewfile.work도 추가 설치)
4. .zshrc, .gitconfig, starship.toml, Ghostty 설정, btop 테마를 심링크로 연결 (이미 파일이 있으면 ~/.dotfiles-backup-<타임스탬프>/로 백업 후 교체)
5. git 이름/이메일을 물어봐서 ~/.gitconfig.local 생성

zinit(쉘 플러그인 매니저)은 스크립트가 따로 설치하지 않고, .zshrc가 처음 로드될 때 스스로 ~/.local/share/zinit에 클론합니다.

재실행해도 안전합니다 — 실제 파일은 한 번만 백업되고, 이미 심링크인 건 그냥 교체됩니다.

---

도구별 설명 및 사용법

쉘 / 프롬프트

• zinit — 쉘 플러그인 매니저. oh-my-zsh 전체 프레임워크 대신 필요한 플러그인만 지연 로딩해서 시작 속도가 빠릅니다. .zshrc에서 OMZP::git(oh-my-zsh의 git 플러그인) 하나만 가져와서 gst(=git status), gaa(=git add --all) 같은 단축 명령을 씁니다.
• starship — 실제 프롬프트를 그리는 도구. 설정은 starship.toml에 있고, 디렉토리·git 브랜치·명령 실행 시간을 보여줍니다. 수정 후 저장하면 새 셸에 바로 반영됩니다.
• mise — 프로젝트별 런타임 버전 관리자 (nvm/rbenv/pyenv를 대체). 전역 기본값은 mise/config.toml에서 관리하고, 프로젝트마다 다른 버전이 필요하면 그 디렉토리에 .mise.toml을 만들면 됩니다.

  mise install          # config.toml에 적힌 버전 설치
  mise use node@22      # 현재 디렉토리에 node 22 고정
  mise ls               # 설치된 버전 목록

• zsh-autosuggestions — 히스토리 기반으로 입력하는 줄 오른쪽에 회색으로 자동완성을 제안합니다. →(오른쪽 화살표)나 End로 그대로 수락.
• zsh-syntax-highlighting — 명령어를 입력하는 동안 실시간으로 문법 검사해서 색을 입힙니다 (존재하지 않는 명령어는 빨간색). zinit이 다른 플러그인들 다음에 이 둘을 가장 마지막에 로드하도록 되어 있는데, zle(라인 에디터) 위젯을 감싸는 방식이라 순서가 중요하기 때문입니다 — .zshrc 맨 아래에 있는 이유.
• direnv — 디렉토리에 .envrc 파일을 두면 cd로 들어갈 때 자동으로 환경변수를 로드하고, 나갈 때 자동으로 해제합니다. 프로젝트별 API 키/설정을 셸 전역에 안 흘리고 관리할 때 유용. 최초 사용 시 direnv allow로 승인 필요 (보안상 임의의 .envrc를 바로 실행하지 않음).

터미널

• Ghostty — GPU 가속 터미널 에뮬레이터. 설정은 ghostty/config에 있고 (cmd+d로 세로 분할, cmd+shift+d로 가로 분할, cmd+alt+방향키로 분할 창 이동).

최신 CLI 도구 (기존 명령어를 alias로 대체)

alias	실제 도구	설명 / 자주 쓰는 예시
ls, ll, lt	eza	--icons --git로 파일 아이콘과 git 상태 컬럼을 함께 보여주는 ls. lt는 --tree로 트리 뷰
cat	bat	문법 하이라이팅 있는 페이저. Catppuccin Mocha 테마로 터미널/starship과 톤을 맞춤 (BAT_THEME env). bat file.js
find	fd	빠르고 직관적인 파일 검색. fd 파일이름
grep	rg (ripgrep)	.gitignore를 자동으로 무시하는 고속 검색. rg "패턴"
top	btop	그래픽 리소스 모니터. Catppuccin Mocha 테마 (btop/), 배경은 Ghostty 반투명에 맞춰 투명 처리
df	duf	디스크 사용량을 표로 보여줌
du	dust	디렉토리별 용량을 트리로 시각화
vim, vi	nvim	Neovim

이 외에 alias 없이 직접 활성화해서 쓰는 도구:

• fzf — 퍼지 파인더. Ctrl+R로 셸 히스토리 검색, Ctrl+T로 파일 검색, **<Tab>으로 아무 명령어에서나 경로 자동완성.
• zoxide — cd를 대체하는 게 아니라 보완하는 도구. z 디렉토리이름일부만 치면 예전에 자주/최근에 갔던 디렉토리로 바로 이동합니다. (cd는 그대로 둠)
• atuin — 셸 히스토리를 SQLite에 저장해서 Ctrl+R 검색을 fzf보다 더 강력하게 만듦 (같은 명령어를 여러 번 써도 안 겹치고, 실행 시간/디렉토리 기준으로도 검색 가능). 여러 대의 맥을 쓴다면 atuin login으로 히스토리 동기화도 가능.

에디터

• Cursor — AI 통합 코드 에디터. VS Code는 따로 설치하지 않고, code CLI가 Cursor로 리다이렉트되도록 되어 있어서 Brewfile의 vscode "..." 항목들이 실제로는 Cursor 확장으로 설치됩니다.

버전 관리

• git-delta — .gitconfig가 pager = delta로 지정해놔서 git diff, git log -p, git show를 칠 때 자동으로 사이드바이사이드 하이라이팅된 화면이 뜹니다. 따로 실행할 명령어는 없습니다.
• gh — GitHub CLI. gh pr create, gh issue list, gh repo clone owner/repo 등.
• glab (업무용) — GitLab CLI. 사용법은 gh와 거의 동일 (glab mr create 등).
• lazygit (lg alias) — 스테이징/커밋/브랜치/리베이스를 TUI로 처리. 프로젝트 디렉토리에서 lg 한 번이면 뜨고, space로 스테이징, c로 커밋, p로 push.

컨테이너

• OrbStack — Docker Desktop 대체. docker, docker compose 명령어는 완전히 동일하게 쓰면 됩니다. 앱을 한 번 열어서 초기 설정만 해두면 이후엔 백그라운드로 동작. orb 명령으로 Linux VM에 직접 접속하는 것도 가능 (orb -m <머신이름>).

클립보드 / 미디어

• Maccy — 클립보드 히스토리 매니저. 기본 단축키 Cmd+Shift+V로 최근 복사 목록을 불러옵니다.
• yt-dlp — 동영상 다운로드. yt-dlp <URL>.
• ffmpeg — 오디오/비디오 변환. ffmpeg -i input.mov output.mp4.

AI / 생산성 도구

• Claude Code — 이 저장소를 세팅하는 데 쓰인 CLI 에이전트 자체.
• rtk — Claude Code 훅으로 명령어를 가로채서 토큰 소비를 줄이는 프록시. rtk gain으로 지금까지 얼마나 절약했는지 확인 가능.
• claude-monitor (uv로 설치) — Claude 사용량/비용을 실시간으로 모니터링. claude-monitor 실행하면 대시보드가 뜸.
• codex (@openai/codex) — OpenAI의 코딩 에이전트 CLI.
• playwright/cli (@playwright/cli) — 브라우저 자동화/테스트 도구.
• ntn, oh-my-claude-sisyphus — 개인 생산성 자동화 스크립트.

Node / npm

• Node는 mise로만 관리합니다 (Homebrew node는 의도적으로 뺐습니다 — 예전엔 둘 다 깔려있어서 버전이 서로 다르게 따로 놀았던 적이 있음). npm install -g 하면 항상 mise/config.toml이 가리키는 버전(lts) 밑에 설치됩니다.

  node -v          # mise가 관리하는 버전 확인
  mise use -g node@22   # 전역 기본 버전을 바꾸고 싶을 때

---

업무용 도구 (Brewfile.work, 회사 머신에서만)

• jira-cli — 터미널에서 Jira 티켓 조회/코멘트. jira issue list.
• acli — Atlassian 통합 CLI (Jira/Confluence). 별도 설치 방법은 공식 문서 참고 (이 tap만으로는 바이너리가 안 깔립니다).
• maven, openjdk@17 — Java 빌드 환경.
• msmtp — 터미널에서 SMTP로 메일 발송.
• cocoapods — iOS 네이티브 의존성 관리자 (Flutter iOS 빌드용).
• android-commandlinetools, android-platform-tools — Android 빌드/디버깅 도구.
• flutter — 크로스플랫폼 모바일 UI 프레임워크.
• gcloud-cli — GCP 리소스 관리. 최초 1회 gcloud auth login 필요.
• @googleworkspace/cli (gws) — Google Workspace 관리용 CLI.

---

도구 선택 이유 메모

• mise가 node의 유일한 출처. 예전엔 Homebrew node와 mise가 같이 깔려있어서 Homebrew node는 v26, mise node는 v24로 서로 다르게 놀았고, npm install -g를 대화형 셸에서 치는지 스크립트에서 치는지에 따라 어느 쪽에 설치되는지가 갈리는 버그가 있었습니다. 지금은 mise 하나로 통일했고, install.sh가 brew bundle install 실행 전에 mise install을 먼저 돌려서 npm 관련 항목들이 비대화형 환경에서도 정상 동작하도록 순서를 맞췄습니다.
• mise가 nvm을 대체. 예전엔 nvm을 썼지만, mise 하나로 node/python/ruby 등을 같은 방식으로 관리할 수 있어서 정리했습니다.
• 프롬프트는 starship, 프레임워크는 zinit. starship이 프롬프트를 전부 그리는데 oh-my-zsh 프레임워크까지 같이 로드하는 건 순수 오버헤드라서, zinit으로 바꾸고 oh-my-zsh의 git 플러그인만 스니펫으로 가져왔습니다.
• eza가 lsd를 대체. 둘 다 Rust로 만든 ls 대체제인데, eza가 exa의 활성 포크로 커뮤니티 표준이 됐습니다.
• OrbStack이 Docker Desktop을 대체. CLI는 100% 호환이고 macOS에서 훨씬 가볍습니다. 기존 머신에서 Docker Desktop을 지울 땐 권한 상승이 필요한 헬퍼 파일 정리 단계가 있어서 스크립트로 자동화가 안 되고, sudo brew uninstall --cask docker-desktop --force를 직접 실행해야 합니다.
• git-delta, neovim은 옵션이 아니라 필수로 Brewfile에 있음. .gitconfig가 pager로 delta를 하드코딩하고 .zshrc가 vim/vi를 nvim으로 alias하기 때문에, 둘 중 하나라도 Brewfile에서 빠지면 새 머신에서 조용히 깨집니다.
• Ghostty/starship/bat/btop을 전부 Catppuccin Mocha로 통일. 터미널·프롬프트·페이저· 리소스 모니터가 각자 다른 기본 테마를 쓰면 툴을 오갈 때마다 톤이 튀는데, 넷 다 같은 팔레트를 쓰면 하나의 화면처럼 보입니다. btop/bat는 배경을 투명 처리해서(theme_background = false, BAT_THEME) Ghostty의 반투명 블러가 그대로 비칩니다.