@sebastienrousseau/dotfiles 0.2.520 → 0.2.522

package/docs/migration/README.md

@@ -1,81 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Migration guides
-
-Coming from another dotfiles manager. One guide per tool, each with
-real commands, a rollback path, and an honest section on what you lose
-by switching.
-
-| You use | Guide | Rough effort |
-|---|---|---|
-| [yadm](https://yadm.io/) | [`from-yadm.md`](from-yadm.md) | 30 min — closest model, both wrap git and template |
-| [GNU Stow](https://www.gnu.org/software/stow/) | [`from-gnu-stow.md`](from-gnu-stow.md) | 1–2 h — symlink farm to managed copies is a real change |
-| A bare git repo (`--git-dir=$HOME/.dotfiles`) | [`from-bare-git-repo.md`](from-bare-git-repo.md) | 45 min |
-| Plain chezmoi, no framework | [`from-plain-chezmoi.md`](from-plain-chezmoi.md) | 10 min — same engine underneath |
-
-Upgrading between versions of *this* project is a different document:
-[`../operations/MIGRATION.md`](../operations/MIGRATION.md).
-
-## Read this first
-
-Three facts that apply to every guide.
-
-**chezmoi is the engine.** This project is a framework *over*
-[chezmoi](https://www.chezmoi.io/), not a replacement for it. Files
-live in a source tree, `chezmoi apply` renders them into `$HOME`, and
-`dot` is a control plane over that. If you already know chezmoi, you
-already know 80% of this.
-
-**Nothing is destroyed without asking.** `chezmoi apply` shows a diff
-first when you run `dot diff`, and `dot sync --check` previews without
-writing. Every guide below tells you to take a backup anyway, because
-"nothing is destroyed" is a claim about the tool, not about your typos.
-
-**You can leave.** `scripts/uninstall.sh --force` runs `chezmoi purge`
-and removes the repo, the chezmoi config and state, caches, and logs.
-Your files stay where they were applied; nothing phones home and
-nothing is left behind to reinstall itself. Each guide ends with the
-rollback for that specific migration.
-
-## The shape of every migration
-
-```sh
-# 1. Back up. Always.
-tar -czf ~/dotfiles-backup-$(date +%F).tar.gz -C "$HOME" \
-  .bashrc .zshrc .config .gitconfig 2>/dev/null || true
-
-# 2. Install the framework (does not touch your files yet).
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-
-# 3. Bring your own files under management, one at a time.
-dot add ~/.gitconfig
-dot add ~/.config/nvim
-
-# 4. Preview, then apply.
-dot diff
-dot sync
-
-# 5. Check the result.
-dot doctor
-```
-
-Step 3 is where the guides differ, because it depends on how your
-current tool stores things.
-
-## Choosing not to switch
-
-Genuinely reasonable reasons to stay where you are:
-
-- **You only symlink a handful of files and never templated anything.**
-  GNU Stow is simpler and does that job well.
-- **You need Windows-native support without WSL or PowerShell 7.**
-- **You do not want a CLI layer.** Plain chezmoi is a smaller surface.
-
-The case for switching is multi-machine fleets, per-host templating,
-multi-shell parity, and signed/attested releases. If none of those
-describe you, the migration cost may not repay itself.

package/docs/migration/from-bare-git-repo.md

@@ -1,156 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Migrating from a bare git repo
-
-The `git --git-dir=$HOME/.dotfiles --work-tree=$HOME` pattern, usually
-behind a `config` alias. No dependencies, no symlinks, no templating —
-and `$HOME` is the work tree, which is the part that has to change.
-
-## Concept mapping
-
-| Bare repo | Here |
-|---|---|
-| `config add ~/.bashrc` | `dot add ~/.bashrc` |
-| `config commit` / `config push` | ordinary `git` inside `$(dot cd)` |
-| `config status` | `dot status` |
-| `config checkout` on a new machine | `dot init <user>` |
-| `.gitignore` with `*` at `$HOME` | not needed — `$HOME` is not a work tree |
-| `showUntrackedFiles = no` | not needed, same reason |
-| Per-host: branches | `.tmpl` files with `{{ if }}` |
-| Nothing | `dot doctor`, `dot heal`, `dot rollback`, secrets, provisioning |
-
-## 1. Inventory and back up
-
-```sh
-alias config='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'
-
-config ls-files > ~/bare-inventory.txt
-wc -l ~/bare-inventory.txt
-tar -czf ~/bare-backup-$(date +%F).tar.gz -C "$HOME" -T ~/bare-inventory.txt
-```
-
-Push first if the repo has a remote — the safest rollback is a clone:
-
-```sh
-config status
-config push
-```
-
-## 2. Note your branch layout
-
-Per-host branches are the one thing that needs a design decision. List
-them before you start:
-
-```sh
-config branch -a
-config log --oneline --graph --all | head -20
-```
-
-Every branch becomes conditional blocks in one file. Diff two branches
-now, while the context is fresh:
-
-```sh
-config diff main work-laptop -- .bashrc
-```
-
-## 3. Install
-
-The bare repo is at `$HOME/.dotfiles`, which is also this project's
-default clone location. The installer detects and refuses to clobber
-it, but move it first to avoid the confusion entirely:
-
-```sh
-mv "$HOME/.dotfiles" "$HOME/.dotfiles.bare.bak"
-alias config='git --git-dir=$HOME/.dotfiles.bare.bak --work-tree=$HOME'
-
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-```
-
-Your files in `$HOME` are untouched by the move — only the git
-metadata directory changed name.
-
-## 4. Import
-
-```sh
-while read -r f; do
-  [ -e "$HOME/$f" ] && dot add "$HOME/$f"
-done < ~/bare-inventory.txt
-
-dot status
-```
-
-## 5. Collapse branches into templates
-
-Take the differences you diffed in step 2 and express them as
-conditions in a single `.tmpl`:
-
-```text
-export EDITOR=nvim
-{{ if eq .chezmoi.hostname "work-laptop" }}
-export HTTP_PROXY=http://proxy.corp:3128
-export NPM_CONFIG_REGISTRY=https://nexus.corp/repository/npm/
-{{ end }}
-{{ if eq .chezmoi.os "darwin" }}
-export HOMEBREW_NO_ANALYTICS=1
-{{ end }}
-```
-
-Rendering is testable without applying:
-
-```sh
-chezmoi execute-template < defaults/dot_bashrc.tmpl
-```
-
-## 6. Apply and verify
-
-```sh
-dot diff
-dot sync
-dot doctor
-
-while read -r f; do
-  [ -e "$HOME/$f" ] || echo "MISSING: $f"
-done < ~/bare-inventory.txt
-```
-
-## 7. Clean up
-
-```sh
-# Only if you had the $HOME/.gitignore containing '*' trick:
-grep -q '^\*$' "$HOME/.gitignore" 2>/dev/null && $EDITOR "$HOME/.gitignore"
-
-# Remove the alias from your shell rc, then, once confident:
-rm -rf "$HOME/.dotfiles.bare.bak"
-```
-
-Do not remove the backup until you have pushed the new source tree
-somewhere and used it for a while.
-
-## Rolling back
-
-```sh
-bash ~/.dotfiles/scripts/uninstall.sh --force
-mv "$HOME/.dotfiles.bare.bak" "$HOME/.dotfiles"
-git --git-dir=$HOME/.dotfiles --work-tree=$HOME checkout -- .
-```
-
-Or, if you pushed in step 1, clone the remote bare again — which is
-why step 1 says to push.
-
-## What you gain, what you lose
-
-**Gain:** templating instead of branch-per-host (the bare-repo
-pattern's real weakness: merging a change across five host branches);
-a CLI with diagnostics and repair; secrets; provisioning hooks;
-multi-shell parity; signed releases.
-
-**Lose:** zero dependencies. The bare-repo trick needs nothing but
-git, and that is a genuine virtue — especially on a locked-down host.
-You also lose `$HOME` as a work tree, so `git status` there no longer
-tells you what changed; `dot status` does. And the setup no longer
-fits in a three-line shell alias you can retype from memory.

package/docs/migration/from-gnu-stow.md

@@ -1,165 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Migrating from GNU Stow
-
-Stow builds a symlink farm: `~/.bashrc` is a symlink into
-`~/dotfiles/bash/.bashrc`. This framework renders real files into
-`$HOME` from a source tree. That difference is the whole migration —
-everything else follows from it.
-
-Be honest about whether you want this. If your setup is "symlink a
-dozen files on one machine", Stow is doing that job well and the
-migration will not repay itself. The reason to move is templating,
-multiple machines, or the tooling around the files.
-
-## Concept mapping
-
-| Stow | Here |
-|---|---|
-| `~/dotfiles/<package>/` | `defaults/` (one tree, not per-package) |
-| `stow bash` | `dot sync` (applies everything) |
-| `stow -D bash` | `chezmoi forget <file>`, then `dot sync` |
-| `stow -n` (simulate) | `dot diff` or `dot sync --check` |
-| `.stow-local-ignore` | `.chezmoiignore` |
-| Symlinks in `$HOME` | Real files in `$HOME` |
-| Per-host: separate packages or branches | `.tmpl` files with `{{ if }}` |
-
-## 1. Record what Stow currently owns
-
-Symlinks are self-describing, which makes this the easiest inventory
-of any migration:
-
-```sh
-find "$HOME" -maxdepth 3 -type l -lname "*dotfiles*" \
-  -printf '%p -> %l\n' 2>/dev/null | tee ~/stow-inventory.txt
-```
-
-On macOS (BSD `find` has no `-printf`):
-
-```sh
-find "$HOME" -maxdepth 3 -type l | while read -r l; do
-  case "$(readlink "$l")" in *dotfiles*) echo "$l -> $(readlink "$l")";; esac
-done | tee ~/stow-inventory.txt
-```
-
-Back up the real content, following the links:
-
-```sh
-tar -czhf ~/stow-backup-$(date +%F).tar.gz -C "$HOME" \
-  $(sed 's| ->.*||; s|^'"$HOME"'/||' ~/stow-inventory.txt)
-```
-
-`-h` is the important flag: it dereferences symlinks and archives the
-actual files.
-
-## 2. Unstow before installing
-
-This is the step people skip, and it is the one that matters. If you
-install over a live symlink farm, `chezmoi apply` will try to replace
-symlinks with regular files and the result is confusing.
-
-```sh
-cd ~/dotfiles
-stow -D */          # remove every package's links
-find "$HOME" -maxdepth 3 -type l -lname "*dotfiles*" 2>/dev/null   # expect empty
-```
-
-Your `~/dotfiles` directory still holds the real files. Nothing is lost.
-
-## 3. Install
-
-```sh
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-```
-
-## 4. Import your files
-
-Stow packages flatten into a single tree. Copy each package's contents
-into `$HOME` and add them:
-
-```sh
-cd ~/dotfiles
-for pkg in */; do
-  pkg="${pkg%/}"
-  echo "== $pkg"
-  ( cd "$pkg" && find . -type f -print0 ) | while IFS= read -r -d '' rel; do
-    rel="${rel#./}"
-    mkdir -p "$(dirname "$HOME/$rel")"
-    cp "$pkg/$rel" "$HOME/$rel"
-    dot add "$HOME/$rel"
-  done
-done
-```
-
-Review before committing anything — this is a good moment to drop the
-files you have not opened in three years:
-
-```sh
-dot status
-cd "$(dot cd)" && git status
-```
-
-## 5. Replace per-host packages with templates
-
-If you had `bash-work/` and `bash-home/` packages, collapse them:
-
-```text
-{{ if eq .chezmoi.hostname "work-laptop" }}
-export HTTP_PROXY=http://proxy.corp:3128
-{{ end }}
-```
-
-Available variables: `.chezmoi.os`, `.chezmoi.arch`, `.chezmoi.hostname`,
-`.chezmoi.username`, `.chezmoi.osRelease.id`, plus this project's
-`.profile` and `.features.*` from `defaults/.chezmoidata.toml`.
-
-Test a template without applying:
-
-```sh
-chezmoi execute-template < defaults/dot_bashrc.tmpl
-```
-
-## 6. Apply and verify
-
-```sh
-dot diff
-dot sync
-dot doctor
-
-# Nothing should be a symlink into ~/dotfiles any more:
-find "$HOME" -maxdepth 3 -type l -lname "*dotfiles*" 2>/dev/null
-```
-
-## 7. Retire the old tree
-
-After a few days:
-
-```sh
-mv ~/dotfiles ~/dotfiles.stow.bak     # rename, do not delete
-# delete ~/dotfiles.stow.bak once you are sure
-```
-
-## Rolling back
-
-```sh
-bash ~/.dotfiles/scripts/uninstall.sh --force
-mv ~/dotfiles.stow.bak ~/dotfiles     # if you renamed it
-cd ~/dotfiles && stow */
-```
-
-## What you gain, what you lose
-
-**Gain:** templating (the thing Stow structurally cannot do); one tree
-instead of a package-per-tool layout; the `dot` CLI; multi-shell
-parity; secrets management; signed releases.
-
-**Lose:** the elegance of the symlink model — editing `~/.bashrc` no
-longer edits your repo directly, so you edit the source and run
-`dot sync` (or `dot add` after the fact). Stow is ~5k lines of Perl
-with essentially no runtime dependencies; this pulls in chezmoi. And
-Stow's mental model fits in a paragraph, which has real value.

package/docs/migration/from-plain-chezmoi.md

@@ -1,148 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Migrating from plain chezmoi
-
-The shortest migration here, because there is no engine change: this
-framework *is* chezmoi, plus a source-tree layout, a CLI, and the
-tooling around them. Your templates, your `.chezmoidata`, and your
-muscle memory all carry over.
-
-You can also stop after step 2 and keep using `chezmoi` commands
-directly forever. Nothing here replaces chezmoi; `dot` shells out to it.
-
-## What actually changes
-
-| Plain chezmoi | Here |
-|---|---|
-| Source at `~/.local/share/chezmoi` | Source at `~/.dotfiles`, with `.chezmoiroot` pointing chezmoi at `defaults/` |
-| Everything at the source root | `defaults/` = your files; `bin/`, `lib/`, `scripts/`, `docs/`, `tests/` = the framework |
-| `chezmoi apply` | `dot sync` (which runs `chezmoi apply` with sensible exclusions) |
-| `chezmoi diff` / `status` | `dot diff` / `dot status` — same thing, prettier |
-| — | `dot doctor`, `dot health`, `dot heal`, `dot rollback`, `dot attest` |
-| `chezmoi secret` | `dot secrets` (age + sops) |
-| `run_onchange_` scripts | same, plus `install/provision/` |
-
-**`.chezmoiroot` is the key idea.** It contains `defaults`, so chezmoi
-treats `~/.dotfiles/defaults/` as the source root. Framework code sits
-outside that directory and is therefore never deployed to `$HOME`.
-
-## 1. Back up and record
-
-```sh
-chezmoi source-path
-chezmoi managed > ~/chezmoi-managed.txt
-wc -l ~/chezmoi-managed.txt
-
-cp -a "$(chezmoi source-path)" ~/chezmoi-source-backup-$(date +%F)
-tar -czf ~/chezmoi-backup-$(date +%F).tar.gz -C "$HOME" -T ~/chezmoi-managed.txt
-```
-
-Commit and push your existing source repo if it has a remote. That is
-the real backup.
-
-## 2. Two paths
-
-**A. Keep your own repo** (you have a dotfiles repo you want to keep
-as the source of truth): install the framework, then move your files
-into `defaults/`.
-
-**B. Adopt this repo's defaults** and layer your changes on top:
-
-```sh
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-```
-
-Path A continues below.
-
-## 3. Install and relocate your source tree
-
-```sh
-old_source="$(chezmoi source-path)"
-
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-
-# Copy your source files under defaults/, preserving chezmoi's naming.
-rsync -av --exclude '.git' "$old_source/" ~/.dotfiles/defaults/
-```
-
-Then reconcile the chezmoi-metadata files, which now exist in both
-places — merge yours into the framework's rather than overwriting:
-
-| File | What to do |
-|---|---|
-| `.chezmoidata.toml` | **Merge.** The framework's carries `dotfiles_version`, `profile`, and `features`; keep those and add your keys. |
-| `.chezmoiignore` | Merge; the framework's entries are feature-flag-gated. |
-| `.chezmoi.toml.tmpl` | Merge your prompts into the framework's. |
-| `.chezmoitemplates/` | Merge; name collisions are the only risk. |
-| `.chezmoiscripts/`, `run_*` | Copy across as-is. |
-
-Sanity-check the merge before applying anything:
-
-```sh
-cd ~/.dotfiles
-chezmoi --source "$PWD" data | head -40
-chezmoi --source "$PWD" managed | head
-```
-
-## 4. Preview, then apply
-
-```sh
-dot diff              # or: chezmoi diff — identical underneath
-dot sync --check      # dry run
-dot sync
-dot doctor
-```
-
-Confirm nothing was dropped:
-
-```sh
-while read -r f; do
-  [ -e "$f" ] || echo "MISSING: $f"
-done < ~/chezmoi-managed.txt
-```
-
-## 5. Optional: adopt the extras
-
-None of these are required; adopt them when you want them.
-
-```sh
-dot secrets-init      # age-based secrets
-dot theme list        # wallpaper-driven theming
-dot profile show      # profiles and feature flags
-dot completion fish > ~/.config/fish/completions/dot.fish
-```
-
-## Rolling back
-
-The gentlest rollback of any of these guides, because chezmoi is still
-the engine:
-
-```sh
-chezmoi --source ~/chezmoi-source-backup-<date> apply
-bash ~/.dotfiles/scripts/uninstall.sh --force
-```
-
-Or simply point chezmoi back at your old source and carry on:
-
-```sh
-chezmoi init --source ~/chezmoi-source-backup-<date>
-```
-
-## What you gain, what you lose
-
-**Gain:** the `dot` CLI (diagnostics, repair, rollback, attestation,
-fleet); a curated multi-shell configuration with parity across bash,
-zsh, fish, nushell and PowerShell; secrets, theming and provisioning
-already wired; a test suite and CI you can run against your own
-changes; signed, attested releases.
-
-**Lose:** simplicity. Plain chezmoi is one binary and your files;
-this adds a source-tree convention, a CLI layer, and opinions about
-shell configuration you may not share. If you already have a chezmoi
-setup you are happy with, "it works and I understand every line" is a
-perfectly good reason to stay.