mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
docs(backup): document backup scope and disk space, fix stale paths
The backup docs claimed per-skill symlinks were "resolved and followed" and their real content backed up, which is now the opposite of what happens. Adds a Backups & Disk Space section contrasting the three mechanisms that are easy to conflate — .gitignore (git only), ignore: (sync), and backup (local target content) — plus an ENOSPC troubleshooting entry, since disk space had no coverage anywhere in troubleshooting despite being how this surfaced. Also corrects two long-standing errors: the backup location was documented under ~/.config in the built-in skill reference and in a `backup --list` example, but backups live in the XDG data dir (config.DataDir()); and the built-in skill claimed backup was global-mode only, when project mode does support agent backups. Refs #252
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Backup & Restore
|
||||
|
||||
**Global mode only.** Not available in project mode (project targets are reproducible via `install -p && sync`).
|
||||
**Skills: global mode only** (project skill targets are reproducible via `install -p && sync`). **Agents: both modes** — `backup -p agents` works in project mode; plain `backup -p` errors.
|
||||
|
||||
## backup
|
||||
|
||||
@@ -9,11 +9,15 @@ Create backups of target skill directories.
|
||||
```bash
|
||||
skillshare backup # All targets
|
||||
skillshare backup claude # Specific target
|
||||
skillshare backup agents # Agent targets
|
||||
skillshare backup --all # Skills + agents
|
||||
skillshare backup --list # List existing backups
|
||||
skillshare backup --cleanup # Remove old backups
|
||||
```
|
||||
|
||||
**Location:** `~/.config/skillshare/backups/<timestamp>/`
|
||||
**Location:** `~/.local/share/skillshare/backups/<timestamp>/` (XDG data dir, not config). Project agent backups: `.skillshare/backups/`.
|
||||
|
||||
**Scope:** Local target content only. Merge-mode symlinks are skipped — they point into the source, which is already the source of truth, and `sync` recreates them. A target holding only symlinks produces no backup. Retention (10 snapshots / 30 days / 500 MB, newest always kept) runs automatically after every `sync`.
|
||||
|
||||
## restore
|
||||
|
||||
@@ -28,4 +32,5 @@ skillshare restore claude --from 2026-01-14_21-22 # Specific backup
|
||||
|
||||
- Run `backup` before major changes
|
||||
- Use `--dry-run` with restore to preview
|
||||
- Keep backups with `--cleanup` to save disk space
|
||||
- Run `sync` after `restore` to recreate symlinks for synced skills
|
||||
- Retention is automatic; use `--cleanup` only to prune on demand
|
||||
|
||||
@@ -28,6 +28,8 @@ Backups are created automatically before:
|
||||
|
||||
**Location:** `~/.local/share/skillshare/backups/<timestamp>/` (agent backups appear as `<target>-agents/` next to the regular `<target>/` directories).
|
||||
|
||||
**Scope:** Only local target content is captured. Merge-mode symlinks are skipped because they point into your source — `sync` recreates them. See [What Gets Backed Up](/docs/reference/commands/backup#what-gets-backed-up).
|
||||
|
||||
---
|
||||
|
||||
## Manual Backup
|
||||
@@ -114,7 +116,16 @@ flowchart TD
|
||||
skillshare backup --cleanup
|
||||
```
|
||||
|
||||
Removes backups older than the configured retention period.
|
||||
Removes backups older than the configured retention period. Retention already runs automatically after every `sync`, so this is only for pruning on demand.
|
||||
|
||||
To check how much space snapshots use:
|
||||
|
||||
```bash
|
||||
du -sh ~/.local/share/skillshare/backups
|
||||
skillshare backup --cleanup --dry-run # Preview what would be removed
|
||||
```
|
||||
|
||||
See [Backups & Disk Space](/docs/reference/commands/backup#backups--disk-space) for how backup scope differs from `.gitignore` and `ignore:`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -28,7 +28,9 @@ Backups are created **automatically** before:
|
||||
- `skillshare sync agents` (agent targets only)
|
||||
- `skillshare target remove`
|
||||
|
||||
Location: `~/.local/share/skillshare/backups/<timestamp>/`
|
||||
Location: `~/.local/share/skillshare/backups/<timestamp>/` (global), `.skillshare/backups/` (project mode, agents only)
|
||||
|
||||
Retention is applied automatically after each automatic backup, using the same policy as `--cleanup`. You do not need to prune snapshots by hand.
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -48,9 +50,9 @@ skillshare backup --list
|
||||
|
||||
```
|
||||
All backups (15.3 MB total)
|
||||
2026-01-20_15-30-00 claude, cursor 4.2 MB ~/.config/.../2026-01-20_15-30-00
|
||||
2026-01-19_10-00-00 claude 2.1 MB ~/.config/.../2026-01-19_10-00-00
|
||||
2026-01-18_09-00-00 claude, cursor 4.0 MB ~/.config/.../2026-01-18_09-00-00
|
||||
2026-01-20_15-30-00 claude, cursor 4.2 MB ~/.local/share/.../2026-01-20_15-30-00
|
||||
2026-01-19_10-00-00 claude 2.1 MB ~/.local/share/.../2026-01-19_10-00-00
|
||||
2026-01-18_09-00-00 claude, cursor 4.0 MB ~/.local/share/.../2026-01-18_09-00-00
|
||||
```
|
||||
|
||||
### Cleanup Old Backups
|
||||
@@ -65,6 +67,10 @@ Default cleanup policy:
|
||||
- Remove backups older than 30 days
|
||||
- Cap total size at 500 MB
|
||||
|
||||
The newest snapshot is always kept, even when it alone exceeds the size cap — you are never left without a restore point.
|
||||
|
||||
This same policy runs automatically after every `sync`, so `--cleanup` is only needed to prune on demand.
|
||||
|
||||
## Options
|
||||
|
||||
| Flag | Description |
|
||||
@@ -95,16 +101,44 @@ Default cleanup policy:
|
||||
└── ...
|
||||
```
|
||||
|
||||
The skill directories present depend on the target's mode — see [What Gets Backed Up](#what-gets-backed-up).
|
||||
|
||||
## What Gets Backed Up
|
||||
|
||||
- Regular directories in targets (actual skill files)
|
||||
- Per-skill symlinks in merge-mode targets are **resolved and followed** — the real content is backed up
|
||||
A backup protects only what `sync` could destroy: **local content that exists in the target but not in your source.**
|
||||
|
||||
- Regular files and directories in targets are backed up
|
||||
- Per-skill symlinks in merge-mode targets are **skipped** — they point into your source, which is the single source of truth and already safe. `skillshare sync` recreates them
|
||||
|
||||
This means:
|
||||
- In merge mode: All skills are backed up (symlinks resolved, local copies included)
|
||||
- In copy mode: All managed skill directories are backed up
|
||||
- In merge mode: Only local (non-symlinked) skills are backed up. Synced skills live in the source
|
||||
- In copy mode: All managed skill directories are backed up (they are real files)
|
||||
- In symlink mode: Nothing is backed up (entire directory is a single symlink)
|
||||
|
||||
If a target contains nothing but symlinks, no backup is created and `backup` reports nothing to do — an empty restore point is not useful.
|
||||
|
||||
## Backups & Disk Space
|
||||
|
||||
Backups never copy your source, so they stay small. Three separate mechanisms are easy to confuse:
|
||||
|
||||
| Mechanism | Scope | What it controls |
|
||||
|-----------|-------|------------------|
|
||||
| `.gitignore` in your source | Git only | What Git tracks. Ignored files still exist on disk |
|
||||
| `ignore:` in `config.yaml` | `sync` | Which files `sync` copies into targets (mainly copy mode). See [sync](/docs/reference/commands/sync) |
|
||||
| Backup | Snapshot | Local target content only — symlinks and therefore source artifacts are excluded |
|
||||
|
||||
Because symlinked skills are not followed, heavy artifacts living inside a source skill (model weights, `.venv`, browser profiles, media) are **never** copied into a snapshot, whether or not `.gitignore` or `ignore:` mentions them.
|
||||
|
||||
Retention runs automatically after every `sync`, using the default policy below. To inspect usage manually:
|
||||
|
||||
```bash
|
||||
du -sh ~/.local/share/skillshare/backups # Total size on disk
|
||||
skillshare backup --list # Per-snapshot sizes
|
||||
skillshare backup --cleanup --dry-run # Preview what retention would remove
|
||||
```
|
||||
|
||||
Copy-mode targets are the one case where snapshots can still grow: those are real files, so anything under a skill directory is copied. Keep runtime caches and large artifacts outside the skill tree, or exclude them with `ignore:` so they never reach the target in the first place.
|
||||
|
||||
## Agent Backup
|
||||
|
||||
Agents have their own backup flow that runs alongside skill backups, with two distinctions worth knowing:
|
||||
|
||||
@@ -102,18 +102,14 @@ skillshare restore claude --force
|
||||
|
||||
## After Restoring
|
||||
|
||||
After restore, your target will have regular directories instead of symlinks. To re-sync:
|
||||
`restore` replaces the target directory with the snapshot's contents. Because backups capture only local content — symlinked skills are excluded, see [What Gets Backed Up](/docs/reference/commands/backup#what-gets-backed-up) — run `sync` afterwards to bring synced skills back:
|
||||
|
||||
```bash
|
||||
skillshare restore claude # Restore backup
|
||||
skillshare sync # Re-sync from source (creates symlinks)
|
||||
skillshare restore claude # Restore local content from backup
|
||||
skillshare sync # Recreate symlinks for synced skills
|
||||
```
|
||||
|
||||
Or keep the restored state:
|
||||
```bash
|
||||
skillshare restore claude # Restore backup
|
||||
# Done - skills are now local copies
|
||||
```
|
||||
Restored content is regular files, not symlinks. If the target only ever held local skills, the restore alone is enough.
|
||||
|
||||
## Use Cases
|
||||
|
||||
|
||||
@@ -443,6 +443,8 @@ Backups are created **automatically** before `sync` and `target remove`.
|
||||
|
||||
Location: `~/.local/share/skillshare/backups/<timestamp>/`
|
||||
|
||||
A snapshot captures only **local** target content. Merge-mode symlinks are skipped — they point into your source and `sync` recreates them — so snapshots stay small no matter how large your skills are. Retention is applied automatically after each sync. See [What Gets Backed Up](/docs/reference/commands/backup#what-gets-backed-up) and [Backups & Disk Space](/docs/reference/commands/backup#backups--disk-space).
|
||||
|
||||
### Manual Backup
|
||||
|
||||
```bash
|
||||
|
||||
@@ -134,6 +134,30 @@ ignore:
|
||||
- "**/node_modules/**"
|
||||
```
|
||||
|
||||
### `no space left on device` / `ENOSPC` during sync
|
||||
|
||||
**Cause:** Something is filling the volume. Check the backup directory first, then your source.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
df -h ~ # Confirm the volume is full
|
||||
du -sh ~/.local/share/skillshare/backups # Backup usage
|
||||
du -sh ~/.config/skillshare/skills # Source usage
|
||||
```
|
||||
|
||||
If backups are large, prune them — retention runs automatically after each `sync`, but a directory grown before that can be cleared on demand:
|
||||
|
||||
```bash
|
||||
skillshare backup --cleanup --dry-run # Preview
|
||||
skillshare backup --cleanup
|
||||
```
|
||||
|
||||
If a volume is pinned at 100%, `rm` can fail with "Permission denied" until a little space is freed. Free one large file first, then prune.
|
||||
|
||||
If the **source** is large, the artifacts are inside your skills. Backups do not copy them (symlinked skills are skipped), but every target in copy mode does. Move runtime caches, model weights, and browser profiles outside the skill tree, or exclude them with `ignore:`.
|
||||
|
||||
See [Backups & Disk Space](/docs/reference/commands/backup#backups--disk-space) for how backup scope differs from `.gitignore` and `ignore:`.
|
||||
|
||||
---
|
||||
|
||||
## Git Errors
|
||||
|
||||
Reference in New Issue
Block a user