Skip to content

docs: align external-state page with actual externalize/internalize behavior #1466

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
tamirdresher merged 1 commit into from
Jul 13, 2026
Merged

docs: align external-state page with actual externalize/internalize behavior #1466

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
30 changes: 18 additions & 12 deletions docs/src/content/docs/features/external-state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,13 +94,16 @@ squad externalize
**What happens:**
1. Resolves platform-specific global path (e.g., `~/Library/Application Support/squad/projects/my-repo/`)
2. Moves `.squad/` contents to global path
3. Creates thin marker file `.squad/config.json` in working tree:
3. Creates thin marker file `.squad/config.json` in working tree (existing config fields are preserved):
```json
{
"version": 1,
"teamRoot": ".",
"projectKey": "my-repo",
"stateLocation": "external"
}
```
4. Adds `.squad/` to `.gitignore` (if not already present)
4. Adds `.squad/config.json` to `.gitignore` (if not already present) — the marker is machine-specific and must not be committed

**After externalization:**
- Working tree has only `.squad/config.json` (gitignored marker)
Expand All @@ -119,9 +122,9 @@ squad internalize

**What happens:**
1. Reads marker file to find external state location
2. Moves state from global directory back to `.squad/`
3. Removes marker file
4. Removes `.squad/` from `.gitignore`
2. Copies state from the global directory back to `.squad/` (the external copy is left in place)
3. Removes the external-state fields (`stateLocation`, `teamRoot`, `projectKey`) from `.squad/config.json` — the file is deleted when no other settings remain
4. Leaves `.gitignore` unchanged

**After internalization:**
- `.squad/` lives in working tree again
Expand All @@ -136,19 +139,22 @@ The thin marker file `.squad/config.json` tracks state location:

```json
{
"version": 1,
"teamRoot": ".",
"projectKey": "my-repo",
"stateLocation": "external"
}
```

| Value | Meaning |
| `stateLocation` | Meaning |
|-------|---------|
| `"internal"` | State lives in working tree (`.squad/` in repo) |
| absent (or no marker file) | State lives in working tree (`.squad/` in repo) |
| `"external"` | State lives in global directory (platform-specific path) |

**Notes:**
- Marker file is created by `squad externalize`
- Marker file is gitignored — not committed to repo
- Marker file is removed by `squad internalize`
- `squad internalize` removes the external-state fields from the file (and deletes it when nothing else remains)

---

Expand Down Expand Up @@ -210,19 +216,19 @@ No cross-repo state pollution.

## Git Integration

After externalization, `.squad/` is gitignored. Only the thin marker file exists in the working tree:
After externalization, only the thin marker file exists in the working tree, and it is gitignored:

```bash
$ git status
On branch feature-branch
Untracked files:
.squad/config.json # gitignored marker — not committed
nothing to commit, working tree clean
# .squad/config.json exists on disk but is gitignored — not committed
```

This means:
- PRs never show squad state changes
- Branch switches don't affect squad data
- `git clean -fdx` doesn't delete squad state
- `git clean -fdx` doesn't delete squad state (it lives outside the repo — though it does remove the gitignored marker, which `squad externalize` can recreate)

---

Expand Down