dot

README

dot

Install

Download and install the archive for your Mac from the latest GitHub release.

curl -fLO https://github.com/lukejanicke/dot/releases/latest/download/dot_darwin_arm64.tar.gz
mkdir -p ~/.local/bin
tar -xzf dot_darwin_arm64.tar.gz -C ~/.local/bin
rm dot_darwin_arm64.tar.gz
export PATH="$HOME/.local/bin:$PATH"
dot --version

The archive contains a single executable named dot. An Intel Mac binary is also available. SHA-256 checksums are provided for release downloads.

Add ~/.local/bin to your shell configuration to keep it on your PATH in new terminal sessions. Installing a release binary does not require Go.

Overview

dot is a small, single-file dotfiles manager for macOS. It explicitly manages mappings between system files below your home directory and saved copies in a personal library.

dot manage FILE      add a system file to the manifest
dot save FILE        system → library
dot install FILE     library → system
dot unmanage FILE    remove the mapping and library copy; keep system

Save and install overwrite the destination. Unmanage never deletes the system file. dot does not perform Git operations or provide whole-directory transfers.

Build and install from source

Building from source requires Go 1.26 or later. From the project directory:

go test ./...
go vet ./...
go build -o dot ./cmd/dot
mkdir -p ~/.local/bin
cp ./dot ~/.local/bin/dot

Ensure ~/.local/bin is on your PATH.

Configure a library

Choose the directory where saved copies will be stored:

dot library ~/Documents/dotfiles

dot creates the directory and its dotfiles.toml manifest when necessary, records it as the active library, and prints the status of every managed file. Selecting another library replaces the previous active-library setting; files are not migrated.

The active library is recorded in ~/.config/dot/config.toml. If XDG_CONFIG_HOME is set, dot uses $XDG_CONFIG_HOME/dot/config.toml instead.

Manage system files

Manage an existing system file before saving it:

dot manage ~/.zshrc
dot manage "/Users/me/Library/Application Support/Code/User/settings.json"

manage also accepts a path relative to the current directory:

cd ~
dot manage .zshrc

The file must exist, be regular, and resolve below your home directory without symbolic-link components. Its library path mirrors its path relative to home. Managing adds the manifest mapping and reports its state but does not copy the file.

Save and install files

Save copies a managed system file to the library. Install copies a managed library file to its system path. Managed files can be selected by unique basename, exact library-relative path, unique distinguishing suffix, or full system path:

dot save .zshrc
dot install .zshrc
dot install Library/Application\ Support/Code/User/settings.json

If a selector matches more than one file, dot lists the candidates and performs no operation. Save and install never create manifest mappings implicitly.

Unmanage a system file

dot unmanage .zshrc

Unmanage deletes the library copy when present, removes the manifest mapping, and leaves the system file untouched. It requires the system file to exist, so it refuses a library-only entry. Managing the file again requires dot manage FILE.

Check status

dot status

Each managed file is reported as in sync, out of sync, not installed, or not saved. Status compares file contents, not modification times or permissions. It updates dotfiles.toml by refreshing observed states and removing mappings whose library and system files are both absent.

Files present in the library but absent from the manifest are ignored and are not managed automatically.

dot rejects symbolic links in managed file paths and in its configuration and manifest paths. Configuration and manifest updates are written to a temporary regular file in the destination directory and atomically renamed into place.

Commands

dot library PATH
dot status
dot manage FILE
dot save FILE
dot install FILE
dot unmanage FILE
dot completion zsh
dot version
dot --version
dot -v
dot help
dot --help
dot -h

Zsh completion

Generate the completion function into a directory on your $fpath:

mkdir -p ~/.zsh/completions
dot completion zsh > ~/.zsh/completions/_dot

Alternatively, copy completions/_dot there after building from source. Configure ~/.zsh/completions on fpath before Zsh runs compinit.

Development

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/dot

The project uses only the Go standard library.