Skip to content

docs: document .local-backup customization backups in squad upgrade #1843

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bradygaster merged 1 commit into from
Aug 23, 2026
Merged

docs: document .local-backup customization backups in squad upgrade #1843

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/src/content/docs/features/self-upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<file>.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 `<!-- squad-cli vX.Y.Z -->` 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
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<file>.local-backup` | Yes |
| `squad upgrade --state-backend <type>` | 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 |
Expand Down