Stay up to date
Pull the latest config, upgrade your packages, and keep dot's own requirements healthy.
dot update # pull the repo, move the live copy to it, show what would change
dot apply # apply it, when you're ready
dot upgrade # newer versions of your packages and tools
dot doctor # dot's own requirements
dot auth status # every login dot uses
dot updatefetches your repo from GitHub, moves the live copy to its main branch, and runsdot checkto show what the new version would change. It never applies.dot upgradeupgrades packages and tools to their newest versions (below).dot doctorchecks what dot itself needs: the Command Line Tools, Homebrew, 1Password with its CLI and SSH agent,gh, Varlock,dot.toml(errors, and values missing from it), and the shell setup. Each problem comes with its fix. No Touch ID.dot auth statuschecks each login: the 1Password CLI,gh, SSH to GitHub,vercel, and each AWS organization indot.toml. It asks for Touch ID (Accounts).
Newer versions
config/ says which packages you want, not which version, so a new release
never shows up in dot check. dot upgrade takes care of that:
dot upgrade # list what's outdated, then ask
dot upgrade --yes # upgrade without asking
It refreshes Homebrew’s package list, then shows each package and tool with a newer version, one per line:
brew formula gh 2.101.0 → 2.102.0
brew cask slack 4.52.162 → 4.52.178
mise uv 0.12.18 → 0.12.23
- Homebrew: everything it installed, not only what
config/lists: exactly the listbrew outdatedshows. Homebrew leaves out most apps that update themselves, unless one falls behind (Chrome before its own update runs). A formula you pinned withbrew pinstays where it is. Upgrading an app may ask for your password. - mise: the global tools, within the versions
their config asks for:
node = "24"moves to a newer 24, never to 25, and the previous version stays for a day before mise removes it. A project’s own versions are that project’s business.
Without a terminal to ask on and without --yes, it lists the upgrades and
exits 1, changing nothing.
The live copy
What runs on your Mac comes from ~/.local/share/dotfiles/live, a copy of
your repo at its main branch on GitHub: ~/.zshrc loads dot from it, and
every file dot links into ~ (the gh and vercel shims, Zed’s settings,
Hammerspoon) points into it. Your repo is where you work: a branch you check
out there, or a change you haven’t merged, runs nowhere until it’s on main
and you run dot update. To try a change first, run that copy’s bin/dot.
dot update creates the live copy the first time and only ever moves it
forward along main. dot check says when it’s behind. If it’s missing,
nothing falls back to your repo: ~/.zshrc says so, and dot apply stops
at every setting that needs it until you run bin/dot update in the repo.
Protect main
The live copy runs whatever reaches main on GitHub, so it’s only as safe as main. Two things keep anything unreviewed off it:
-
A ruleset on main: changes arrive only through pull requests, with the required checks, and nobody can force-push or delete the branch. As the repo’s admin you may merge a pull request that skips the rules, but direct pushes are refused, also from your SSH key, which agents use too:
gh api -X POST repos/<you>/dotfiles/rulesets --input - <<'JSON' { "name": "main: pull requests only", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } }, "rules": [ { "type": "deletion" }, { "type": "non_fast_forward" }, { "type": "pull_request", "parameters": { "required_approving_review_count": 0, "dismiss_stale_reviews_on_push": false, "require_code_owner_review": false, "require_last_push_approval": false, "required_review_thread_resolution": false } }, { "type": "required_status_checks", "parameters": { "strict_required_status_checks_policy": false, "required_status_checks": [{ "context": "validate-pr" }] } } ], "bypass_actors": [{ "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "pull_request" }] } JSON -
Merging stays with you. A token acts as you on GitHub, admin rights included, so an agent token with Contents Read and write could merge its own pull request. Give the agent token Contents Read-only: agents push branches over SSH and open pull requests, and you merge them (GitHub).
Changes you make on the Mac
Some apps edit their own settings files, and dot links those files from the
live copy (Editor), so a change you make in
the app lands there, and dot check names the file. To keep it, bring it
into your repo and merge it:
git -C ~/.local/share/dotfiles/live diff | git -C ~/code/<you>/dotfiles apply
To drop it: git -C ~/.local/share/dotfiles/live checkout -- <file>. Until
main has the change, dot update leaves the live copy where it is, so
nothing is lost. A preference you change in System Settings shows up in
dot check as a difference: put it back with dot apply, or change the line
in config/ to keep it.
Upstream improvements
Your fork is a normal git repo. To bring in changes from the original, add it as a remote once and merge when you want:
dot cd
git remote add upstream git@github.com:rbadillap/dotfiles.git
git pull upstream main
Conflicts, if any, will be in config/, where your choices differ.