README
¶
dot
dot is a small, single-file dotfiles manager for macOS. It compares files in a personal library with their live locations below your home directory, reports their state, and copies one selected file in one selected direction.
dot save FILE system → library
dot install FILE library → system
Both commands overwrite the destination. dot does not perform Git operations or provide whole-directory transfers.
Requirements
- macOS
Building from source requires Go 1.26 or later. Installing a compiled release does not require Go.
Install a release
Download the archive for your Mac from the latest GitHub release. For the first release:
version=v0.1.0
architecture=$(uname -m)
if [ "$architecture" = x86_64 ]; then architecture=amd64; fi
archive="dot_${version#v}_darwin_${architecture}.tar.gz"
curl -fLO "https://github.com/lukejanicke/dot/releases/download/$version/$archive"
curl -fLO "https://github.com/lukejanicke/dot/releases/download/$version/SHA256SUMS"
grep " $archive\$" SHA256SUMS | shasum -a 256 -c -
mkdir -p ~/.local/bin
tar -xzf "$archive" -C ~/.local/bin
rm "$archive" SHA256SUMS
export PATH="$HOME/.local/bin:$PATH"
dot --version
The archive contains a single executable named dot. The temporary PATH update makes it available during initial setup; configure ~/.local/bin permanently when installing your shell configuration.
Build and install from source
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, scans it, 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.
Save and install files
To add a system file to the library for the first time, give its full system path:
dot save ~/.zshrc
dot save "/Users/me/Library/Application Support/Code/User/settings.json"
The path must be below your home directory. Its library path mirrors its path relative to your home directory.
After a file is managed, you can select it by its unique basename, exact library-relative path, or a unique distinguishing suffix:
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 copies nothing.
Check status
dot status
Each file is reported as in sync, out of sync, not installed, or not saved. Status compares file contents, not modification times or permissions. It also updates dotfiles.toml by discovering new regular files in the library, refreshing observed states, and removing mappings whose library and system files are both absent.
Library scanning ignores .git directories, dotfiles.toml, .DS_Store, directories, symbolic links, and other non-regular files.
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 save FILE
dot install FILE
dot completion zsh
dot version
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.
Directories