dotfiles

Note: This is a translation. Primary version (Japanese): README.ja.md

Installation

Run this:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/hikch/dotfiles/main/bootstrap.sh)"

or

git clone git@github.com:hikch/dotfiles.git ~/dotfiles
cd ~/dotfiles
make deploy

This will symlink the appropriate files in dotfiles to your home directory. Everything is configured and tweaked within ~/dotfiles.

⚠️ Please make sure you understand the script before running it!

Install packages and applications

To install the packages and applications, run:

make init

This will install Devbox, configure global packages, install Homebrew applications, setup Fish shell, and apply macOS defaults.

Usage

Core Commands

$ cd ~/dotfiles
$ make help
deploy                         Deploy dotfiles.
devbox-global-install          devbox global install
fish                           Install fish plug-ins & Add direnv hook
homebrew                       Install homebrew packages
init                           Initialize.
mac-defaults                   Setup macos settings
vim                            Install vim plug-ins

Dry-run Deploy (Safe Test)

Quickly validate what make deploy would symlink without touching your real home by using a temporary HOME:

HOME=$(mktemp -d) make deploy

This simulates deployment in an isolated sandbox directory so you can review output safely.

Homebrew Bundle Management

New Brewfile management with host-specific configuration:

# Package operations
make brew/setup                # Install/upgrade packages from .Brewfile (and host include)
make brew/check                # Check if everything is satisfied (with details)
make brew/cleanup              # Show removable packages not in Brewfiles  
make brew/cleanup-force        # Remove packages not in Brewfiles
make brew/upgrade              # Upgrade all (formulae & casks)

# Adding packages
make brew/cask-add NAME=app    # Add GUI app to common .Brewfile
make brew/host-cask-add NAME=app # Add GUI app to current host Brewfile

# Utilities
make brew/dump-actual          # Snapshot current state to Brewfile.actual

Configuration

.config and .local Management Policy

This repository follows a strict whitelist approach for managing configuration files:

What Gets Tracked:

• Only hand-edited declarative configuration files
• Files that are reproducible and meaningful across machines
• Files that contain no secrets, state, or auto-generated content

Decision Rules (all must be YES to track):

1. Did I manually edit this file?
2. Is it meaningful on other machines?
3. Is it NOT a secret, state, or auto-generated file?

.config Directory:

• Default: Exclude everything
• Explicitly include: fish/config.fish, fish/conf.d/*.fish, git/config, direnv/direnv.toml, etc.
• Explicitly exclude: fish_variables (working state), completions, auto-generated functions

.local Directory:

• Default: Exclude everything
• Exception: Self-written scripts (e.g., .local/bin/)
• Devbox: Currently managed via PARTIAL_LINKS for .local/share/devbox/global/default/

See .config/.gitignore for the complete whitelist configuration.

PARTIAL_LINKS Management

This repository provides three migration tools for managing PARTIAL_LINKS:

Plan A: One-time Rescue Migration (TOP symlink → real directory)

When to use: Migrating from legacy full-directory symlink structure (one-time only)

make migrate-top-symlink-to-real

What it does:

1. Detects if parent directories (.config, .local) are currently symlinks
2. Backs up all non-PARTIAL_LINKS content to /tmp/dotfiles-migration-*/
3. Converts symlink to real directory
4. Restores non-managed files to home directory
5. Cleans up non-PARTIAL_LINKS items from repository
6. Creates selective symlinks for PARTIAL_LINKS paths only

Example:

Before:
  ~/.config -> ~/dotfiles/.config (full symlink)

After:
  ~/.config/ (real directory)
    ├── fish -> ~/dotfiles/.config/fish (symlink, managed)
    ├── git -> ~/dotfiles/.config/git (symlink, managed)
    ├── gcloud/ (real directory, local state)
    └── gh/ (real directory, local state)

  ~/dotfiles/.config/ (repository)
    ├── fish/ (tracked)
    ├── git/ (tracked)
    └── .gitignore (gcloud, gh removed from repo)

Safety: Destructive (requires backup), run only once during initial migration.

---

Plan B: Adding to PARTIAL_LINKS (real directory → symlink)

When to use: After adding new path to PARTIAL_LINKS file

# 1. Edit PARTIAL_LINKS to add .config/uv
# 2. Run migration
make migrate-add-partial-link path=.config/uv

What it does:

1. Backs up existing ~/.config/uv to /tmp/partial-link-add-*/
2. Removes real directory
3. Creates symlink ~/dotfiles/.config/uv -> ~/.config/uv
4. Prompts manual review of backup content

Important: Does NOT auto-copy files. Review backup and manually copy desired configuration to repository.

---

Plan C: Removing from PARTIAL_LINKS (symlink → real directory)

When to use: After removing path from PARTIAL_LINKS file

# 1. Edit PARTIAL_LINKS to remove .config/git
# 2. Run migration
make migrate-remove-partial-link path=.config/git

What it does:

1. Backs up repository content to /tmp/partial-link-remove-*/
2. Removes symlink
3. Creates real directory and copies content from repository
4. Preserves repository content (manual cleanup needed)

Important: Repository content is preserved. Add to .gitignore or manually remove if no longer needed.

Package Management Strategy

This repository uses a hybrid approach for optimal package management:

• Devbox: CLI tools and development utilities (Node.js, jq, ripgrep, mas, etc.)
• Homebrew Cask: GUI applications only (browsers, editors, productivity apps)
• Host-specific configuration: Different packages per machine via hosts/ directory

Service Management Policy

Background services are managed based on their scope:

• brew services: System-wide, always-on daemons (tailscaled, syncthing, shared databases, GUI agents)
  • Integrated with macOS LaunchAgents/Daemons
  • Persist across reboots and user sessions
• devbox services: Project-scoped, version-pinned dependencies (development databases, local services)
  • Started/stopped with project environments
  • Ensures reproducibility across different projects

Rule of thumb: System-wide → brew services, project-specific → devbox services

Homebrew Host Configuration

The .Brewfile supports automatic host-specific includes:

dotfiles/
  .Brewfile                    # Common GUI applications
  hosts/
    iMac-2020.Brewfile        # iMac-specific packages (e.g., server tools)
    MacBookAir2025.Brewfile   # MacBookAir-specific packages (e.g., dev tools)

Host files are automatically detected using hostname -s and included during brew bundle operations.

Deployment Settings

The deployment behavior is controlled by external configuration files:

• CANDIDATES - Files and directories to be symlinked to $HOME (whitelist)
• EXCLUSIONS - Files and directories to exclude from deployment
• PARTIAL_LINKS - Nested paths to symlink individually (parent dirs auto-excluded)

To modify what gets deployed:

1. Edit CANDIDATES to add new deploy targets
2. Edit EXCLUSIONS to exclude files/directories
3. Edit PARTIAL_LINKS to add selective nested path symlinks
4. Run make deploy to apply changes

Syncthing Usage

Syncthing installation varies by host:

Common (all machines):

• GUI application via cask "syncthing"

Host-specific (iMac only):

• CLI version via brew "syncthing" for server functionality

Usage:

# Desktop use (all machines)
open /Applications/Syncthing.app

# Server use (iMac only)  
brew services start syncthing
brew services stop syncthing

Toolset

• devbox - Primary package manager for development tools
• direnv
• fish - Shell with Fisher plugin management
• homebrew - macOS applications and some CLI tools
• jq
• macvim
• ripgrep
• tmux and more...

TODO

• Make script for creating ssh settings when adding a remote host.
• Split Makefile into modular files (make/deploy.mk, make/homebrew.mk, make/devtools.mk, make/macos.mk)
• Use the defaults command to automate MacOS settings
• Switch to package management using Devbox
• Migrate from Nix to Devbox for better compatibility