Skip to content
dot
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 update fetches your repo from GitHub, moves the live copy to its main branch, and runs dot check to show what the new version would change. It never applies.
  • dot upgrade upgrades packages and tools to their newest versions (below).
  • dot doctor checks 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 status checks each login: the 1Password CLI, gh, SSH to GitHub, vercel, and each AWS organization in dot.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 list brew outdated shows. Homebrew leaves out most apps that update themselves, unless one falls behind (Chrome before its own update runs). A formula you pinned with brew pin stays 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.

Was this page helpful?