<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
<p align="center">
<img src="https://cloudcdn.pro/dotfiles/v2/images/logos/dotfiles.svg" alt="Dotfiles logo" width="128" />
</p>
<h1 align="center">.dotfiles</h1>
<p align="center">
macOS, Linux, WSL 및 Windows-native PowerShell 7.5+를 위한 선언적(Declarative) dotfiles. 기본적으로 다중 쉘을 지원합니다. 100ms 미만의 <code class="language-text">dot</code> 콜드 스타트 속도. 배경화면 기반 테마. 서명 및 증명된 릴리스. SSH를 통한 Fleet 적용.
</p>
<p align="center">
<a href="https://github.com/sebastienrousseau/dotfiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white" alt="Build" /></a>
<a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.536-blue?style=for-the-badge&logo=semanticrelease&logoColor=white" alt="Version" /></a>
<a href="https://www.npmjs.com/package/@sebastienrousseau/dotfiles"><img src="https://img.shields.io/npm/v/@sebastienrousseau/dotfiles?style=for-the-badge&logo=npm&logoColor=white&label=npm" alt="npm" /></a>
<a href="https://doc.dotfiles.io/"><img src="https://img.shields.io/badge/Manual-doc.dotfiles.io-66c2a5?style=for-the-badge&labelColor=555555" alt="Manual" /></a>
<a href="https://github.com/sebastienrousseau/dotfiles/releases"><img src="https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge&logo=github&logoColor=white" alt="Downloads" /></a>
<a href="https://codespaces.new/sebastienrousseau/dotfiles"><img src="https://img.shields.io/badge/Open%20in-Codespaces-blue?style=for-the-badge&logo=github&logoColor=white" alt="Open in GitHub Codespaces" /></a>
</p>
<a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/dotfiles?style=for-the-badge&logo=linuxfoundation&logoColor=white&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard" /></a>
<a href="https://www.bestpractices.dev/projects/12840"><img src="https://img.shields.io/cii/level/12840?style=for-the-badge&logo=linuxfoundation&logoColor=white&label=OpenSSF%20Best%20Practices" alt="OpenSSF Best Practices" /></a>
<a href="#license"><img src="https://img.shields.io/badge/License-Apache--2.0%20OR%20MIT-green?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="License: Apache-2.0 OR MIT" /></a>
<a href="#requirements"><img src="https://img.shields.io/badge/toolchain-bash%205.0%20%C2%B7%20chezmoi%202.40-93450a?style=for-the-badge&logo=gnubash&logoColor=white" alt="Minimum toolchain: bash 5.0, chezmoi 2.40" /></p>
목차 (Contents)
시작하기 (Getting started)
- 설치 — 원라인 설치기, 검증된 설치기, 릴리스 아카이브, Homebrew, Scoop, AUR, npm, Nix, chezmoi, 소스
- 요구 사항 — 툴체인 최소 사양 (toolchain floor), 플랫폼, 셸
- 빠른 시작 (Quick Start) — 설치, 검증, 테마 전환, 여섯 개의 명령어로 적용하기
dotfiles 패밀리 (The dotfiles family) (프레임워크 + 저장소 내 네 개의 위성)
- dotfiles 패밀리 소개 —
dot, dot-ui, dot-ai-tui, dot mcp, dot-mcp, dot-sys 모듈 레지스트리 한눈에 보기
프레임워크 참고 자료 (Framework reference)
무엇을 하는가(What it does)
운영적 측면 (Operational)
설치 (Install)
검증된 릴리스 설치 프로그램 (Verified release installer)
기본 설치 경로는 특정 릴리스에 고정되어 있으며, 설치 프로그램 바이트가 검토된 SHA256과 일치하지 않으면 실행 전에 실패합니다. 절대로 변경되는 main 브랜치를 셸로 직접 파이프(pipe)하지 마십시오. 릴리스별 해시 및 해당 릴리스 프로세스는 docs/security/INSTALL_VERIFICATION.md에 문서화되어 있습니다.
curl -fsSL -o /tmp/dotfiles-install.sh \
https://github.com/sebastienrousseau/dotfiles/releases/download/v0.2.536/dotfiles-install-0.2.536.sh
if command -v sha256sum >/dev/null 2>&1; then
...
이 스크립트는 git, curl, 그리고 sha256sum 또는 shasum을 필요로 합니다. 이 스크립트는 체크섬 검증된 chezmoi 바이너리를 다운로드하고, 고정된 릴리스를 ~/.dotfiles에 클론(clone)한 다음, 이를 적용하고 PATH에 dot을 추가합니다. 설치 프로그램은 macOS, Ubuntu, Debian, Arch, WSL2, 그리고 GitHub Codespaces에서 모두 **멱등성(idempotent)**을 가집니다.
사전 빌드 릴리스 아카이브 (dot CLI 전용)
모든 태그는 디스패처(dispatcher), lib/dot, 매뉴얼 페이지, zsh / bash / fish 자동 완성 기능, 그리고 일반적인 설치 접두사 및 스테이징 디렉토리를 준수하는 Makefile을 포함하여 dot-<버전>.tar.gz와 .zip 파일을 게시합니다. 이 아카이브는 SLSA 빌드 출처(provenance)를 담고 있습니다 (Fulcio + Rekor를 통한 키리스 방식):
gh release download v0.2.536 --repo sebastienrousseau/dotfiles --pattern 'dot-*.tar.gz'
gh attestation verify dot-0.2.536.tar.gz --repo sebastienrousseau/dotfiles
tar -xzf dot-0.2.536.tar.gz
...
release-install-smoke.yml은 모든 릴리스 후에 깨끗한 Ubuntu 및 macOS 러너에서 정확히 이 순서(provenance 검증, 빈 스테이징 디렉토리에 make install 실행, dot version 실행, make uninstall 실행, 아무것도 남지 않았는지 확인)를 반복합니다.
패키지 관리자
chezmoi를 직접 사용하는 경우
이 저장소는 chezmoi 소스 트리(.chezmoiroot가 defaults/를 가리킴)이므로, chezmoi 자체의 부트스트랩 기능이 작동합니다:
chezmoi init --apply sebastienrousseau
이는 install.sh가 사전 검사(preflight checks)를 거친 후 실행하는 방식이며, 사용자는 검증된 chezmoi 다운로드 및 git/curl 검사를 생략할 수 있습니다.
소스에서 빌드하기
git clone https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
...
./install.sh --minimal은 셸과 핵심 도구만 설치합니다.
dot bundle ~/Downloads는 에어갭(air-gapped) 환경의 호스트를 위한 오프라인 .tar.zst 파일을 빌드하며, 이를 압축 해제하고 ./install.sh --force를 실행해야 합니다.
<details>
<summary>CI/CD 및 Docker 옵션</summary>
사일런트 설치 (프롬프트 없음):
DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
bash /tmp/dotfiles-install.sh --force
Docker 샌드박스:
docker run --rm -e DOTFILES_NONINTERACTIVE=1 ubuntu:24.04 bash -c \
'apt-get update -qq && apt-get install -y -qq git curl sudo >/dev/null 2>&1 \
&& git clone --depth 1 https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles \
...
dot sandbox는 설치된 머신에서 Docker 또는 Podman을 통해 동일한 프리뷰를 실행합니다.
프로필 및 세션 플래그 (Profiles and session flags)
기본적으로 모든 무거운 기능은 비활성화되거나(off), 연기되거나(deferred), 캐싱됩니다(cached). 머신별로 프로필을 선택하고, 더 적은 리소스가 필요할 때 세션 플래그를 변경하세요.
| 스위치 (Switch) | 위치 (Where) | 효과 (Effect) | 문서화된 곳 (Documented in) |
|---|
profile = "laptop" (기본값) | ~/.config/chezmoi/chezmoi.toml | 모든 도구, AI CLI, 테마, 자동 완성 기능 | docs/reference/PROFILES.md |
| ... | | | |
요구 사항 (Requirements)
-
Bash 5.0 이상, zsh 5.8 이상. 이들은 Tier-1 셸이며 테스트 스위트가 실행되는 최소 기준입니다: Ubuntu, macOS (Intel 및 Apple Silicon), 그리고 모든 푸시 시 Windows 러너에서 사용됩니다. install.sh와 lib/dot은 macOS의 기본 /bin/bash 3.2가 실행해야 하는 bash-4 전용 구문을 피합니다(참고 사항은 lib/dot/ui.sh에 있습니다). 하지만 3.2는 지원되는 인터랙티브 셸이 아닙니다.
-
chezmoi 2.40 이상, git 2.35 이상, curl. CI는 chezmoi 2.72.2를 고정하고 체크섬 검증을 거친 가져오기(fetch)를 통해 설치합니다. install.sh도 사용자 머신에서 동일한 작업을 수행합니다.
-
지원되는 플랫폼. macOS 14 이상 (Apple Silicon 및 Intel), Ubuntu 22.04 이상, Debian 12 이상, WSL2, NixOS 23.11 이상은 CI 테스트를 거쳤거나 지원됩니다. Fedora와 Arch는 커뮤니티에서 지원합니다. 도구별 최소 사양을 포함한 전체 표는 docs/MINIMUM-TOOLCHAIN.md입니다.
-
Windows. PowerShell 7.5 이상은 일일 워크플로우(apply, status, doctor, mise inventory, agent checks, fleet status)를 위해 네이티브한 dot.ps1을 실행합니다. Test / Windows 작업은 모든 푸시 시 windows-latest에서 cmdlets를 테스트합니다.
최소 도구 체인 정책(Minimum-toolchain policy). 기준은 가장 오래 작동하는 버전이 아니라 CI가 실행하는 버전을 따릅니다. 이 정책은 CHANGELOG.md 항목에서 새로운 기준과 그 이유를 명시한 릴리스에서만 상향 조정되며, 절대 조용히 이루어지지 않습니다. 이 정책이 이동할 수 있는 버전 축과 모든 지원 플랫폼 및 도구를 해당 기준으로 매핑하는 표는 docs/MINIMUM-TOOLCHAIN.md에 있습니다. 본 README는 해당 표가 보장하지 않는 배포판 호환성 주장을 하지 않습니다.
빠른 시작 (Quick Start)
bash /tmp/dotfiles-install.sh
dot doctor
...
첫 5분 (First 5 Minutes)
- 확인(Check) —
dot doctor는 도구, 경로 및 보안을 검증합니다.
- 탐색(Explore) —
dot learn은 셸, 비밀값(secrets), 테마 및 성능에 대해 안내합니다.
- 사용자 정의(Customize) — 개별 기기 설정을 위해
~/.config/chezmoi/chezmoi.toml을 편집합니다 (프로필(Profiles)).
- 기능 토글(Toggle features) —
.chezmoidata.toml에서 플래그를 전환합니다 (기능 플래그(Feature Flags)).
- 적용(Apply) —
dot sync가 설정을 적용하고, 다음 대화형 셸은 _cached_eval을 통해 캐시를 활성화합니다.
버전 간 업그레이드는 docs/operations/MIGRATION.md에서 다룹니다.
dotfiles 패밀리 (The dotfiles family)
하나의 저장소, 하나의 릴리스 트레인: dot 프레임워크와 그 안에 포함되어 함께 버전 관리되는 네 개의 위성(satellites)으로 구성됩니다. .chezmoidata.toml에 있는 버전 번호는 호환성 계약이며, CI의 Generators / version-consistency 작업은 모든 푸시에서 여덟 개의 사람이 볼 수 있는 표면(package.json, bin/dot, man 페이지, bento 배너, 이 README의 배지, CLAUDE.md, AGENTS.md)과 비교하여 확인합니다.
| 컴포넌트 | 설명 | 사용 사례 |
|---|
dot (bin/dot + lib/dot) | Bash 디스패처 및 공유 라이브러리 — 생명 주기(lifecycle), 진단(diagnostics), 테마, 비밀(secrets), 플릿(fleet), 에이전트(agents) | 아래 모든 것; 또한 릴리스 아카이브로 단독 배포됨. |
| ... | | |
구성 요소 설치하기
bash /tmp/dotfiles-install.sh
...