From 12776c6b74c70625d2e4f37b0144d3780ede3cfb Mon Sep 17 00:00:00 2001 From: brady gaster Date: Sun, 23 Aug 2026 11:43:33 -0700 Subject: [PATCH] docs: document .local-backup customization backups in squad upgrade `squad upgrade` has backed up locally customized Squad-owned files to `.local-backup` for a while, and #1709 extended that to workflow files, but the behavior was never documented outside .squad/decisions.md. Adds a section to the self-upgrade feature docs covering: - which files are covered (squad.agent.md + managed workflows) - how to restore from a backup - version stamps are stripped before comparison, so a version-only diff does not trigger a spurious backup - only the most recent backup is kept per file - backups are not gitignored - --dry-run previews the squad.agent.md backup only; it returns before workflow files are processed Also cross-references the behavior from the `squad upgrade` row in the CLI reference for discoverability. Docs-only, no changeset required. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2af08ff0-56a4-43e4-903b-3153c0910a13 --- .../src/content/docs/features/self-upgrade.md | 26 +++++++++++++++++++ docs/src/content/docs/reference/cli.md | 2 +- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/features/self-upgrade.md b/docs/src/content/docs/features/self-upgrade.md index fb97f56de..76cf173a0 100644 --- a/docs/src/content/docs/features/self-upgrade.md +++ b/docs/src/content/docs/features/self-upgrade.md @@ -121,6 +121,32 @@ squad upgrade --self --skip-repo-upgrade *(This flag may not exist yet — just showing the pattern. For now, self-upgrade always runs repo upgrade.)* +### Your Customizations Are Backed Up + +`squad upgrade` overwrites Squad-owned files with the latest templates. Before it overwrites a file you've edited locally, it saves your version alongside it as `.local-backup` and prints a warning. + +This covers `.github/agents/squad.agent.md` and the Squad-managed workflow files in `.github/workflows/`. + +```text +⚠ squad.agent.md has local customizations — backed up to squad.agent.md.local-backup + To restore: copy squad.agent.md.local-backup → squad.agent.md +⚠ squad-ci.yml has local customizations — backed up to squad-ci.yml.local-backup +``` + +To restore your version, copy the backup back over the refreshed file: + +```bash +cp .github/agents/squad.agent.md.local-backup .github/agents/squad.agent.md +``` + +Three things worth knowing: + +- **Version stamps don't count as customizations.** The `` line in `squad.agent.md` changes on every release, so it's stripped before comparing. A file that differs only by its version stamp is refreshed silently, with no backup. +- **Only the most recent backup is kept.** Backups are written to a fixed path, so re-customizing a file and upgrading again overwrites the previous `.local-backup`. Move anything you want to keep somewhere safe before your next upgrade. +- **Backups aren't gitignored.** They show up as untracked files in `git status`. Delete them once you've merged back what you need. + +`squad upgrade --dry-run` previews the upgrade and will tell you if `squad.agent.md` would be backed up. It stops short of the workflow files, so it won't flag customized workflows — check those yourself before upgrading if you've edited them. + --- ## Permission Errors diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md index e4810ab70..b7001c7b2 100644 --- a/docs/src/content/docs/reference/cli.md +++ b/docs/src/content/docs/reference/cli.md @@ -39,7 +39,7 @@ squad init | `squad start [--tunnel] [--port N] [--command cmd]` | Start Copilot with remote phone access via PTY and WebSocket | No | | `squad status` | Show which squad is active and why | Yes | | `squad doctor` | Validate squad setup integrity and diagnose issues (alias: `heartbeat`) | Yes | -| `squad upgrade` | Upgrade Squad-owned files to latest version | Yes | +| `squad upgrade` | Upgrade Squad-owned files to latest version; locally customized files are saved as `.local-backup` | Yes | | `squad upgrade --state-backend ` | Migrate state backend (`orphan`, `two-layer`); installs git hooks automatically | Yes | | `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` directory to `.squad/` | Yes | | `squad triage` | Auto-triage issues and assign to team (primary name; `watch` is an alias) | Yes |