Files
skillshare/ai_docs/tests/push_pull_runbook.md
T
Willie 5d269e8e4c feat(push): add --pull for two-way sync in one command (#354)
* feat(push): add --pull for two-way sync in one command

Users editing skills on several machines have to remember push on one and pull on the other, and a push from a machine that is behind fails until they pull first. push --pull commits local changes, merges the remote with the same merge semantics pull uses, pushes, and syncs the git root scope.

A conflict stops before anything is pushed and keeps the local commit; a target sync failure after a successful push is reported separately so the user knows the remote is already updated. It never rebases or force-pushes. commit rejects --pull instead of silently ignoring it, since both commands share the argument parser.

* docs(push): document push --pull across guides and translations

Cover the new flag on the push reference, the cross-machine sync guide, the quick reference, the daily workflow and the cross-machine recipe, in English and the ja, ko, zh-Hans and zh-Hant translations, plus the built-in skill's sync reference.

* fix(push): print the scope's sync command when --pull sync fails

A bare 'skillshare sync' retry hint defaults to skills and may pick project mode, so it does not redo an agents, extras, or root sync. Derive both the sync and the hint from one per-scope list.

* fix(pull): sync extras for the root git scope

The root scope versions skills, agents and extras, but pull and push --pull only synced skills and agents, so merged extras changes never reached their targets.

* fix(server): sync extras after a root-scope pull

The root scope versions extras too, but the dashboard pull only synced skills and agents, so merged extras never reached their targets. Matches the CLI fix.

* feat(ui): add a Sync both ways action to Git Sync

Mirrors skillshare push --pull: commit local changes, merge the remote and sync targets, then push, in one click. A pull conflict stops at the existing review before anything is pushed.

* feat(ui): confirm Sync both ways and list what it will do

Sync both ways commits, merges and pushes in one click, so ask first and show the concrete outcome (files to commit, remote commits to merge, scope, push target, conflict behavior) before changing anything.

* fix(ui): make Sync both ways match push --pull

It skipped target sync when the pull was already up to date, stopped on an empty remote instead of pushing, and the pull dropped extras warnings. Add alwaysSync and a remote_empty code to /api/pull and surface all extras warnings.
2026-10-03 18:53:08 +08:00

4.3 KiB

CLI E2E Runbook: push --pull

Validates the two-way skillshare push --pull round trip between two machines sharing one git remote.

Origin: push --pull — one explicit command to commit, merge the remote, push, and sync targets.

Scope

  • First run against an empty remote pushes and sets upstream.
  • Changes from another machine are merged, pushed back, and synced to targets.
  • A content conflict pushes nothing and keeps the local commit.
  • --dry-run changes neither the local repository nor the remote.
  • commit --pull is rejected instead of silently ignored.

Environment

Run inside the devcontainer with ssenv isolation. The bare remote and the "other machine" clone live under ~/pp inside the isolated HOME. Steps resolve the skills source and the claude target from ss status --json, because mdproof isolates HOME separately from the ssenv config paths.

Steps

1. Setup: connect the source to an empty bare remote

rm -rf ~/pp && mkdir -p ~/pp
git init -q --bare ~/pp/remote.git
ss init -g --remote ~/pp/remote.git
git -C "$(ss status --json | jq -r '.source.path')" remote get-url origin

Expected:

  • exit_code: 0
  • pp/remote.git

2. First push --pull against the empty remote

SRC=$(ss status --json | jq -r '.source.path')
mkdir -p $SRC/local-skill && printf -- '---\nname: local-skill\n---\n# Local\n' > $SRC/local-skill/SKILL.md
ss push --pull -m "Add local skill"
git -C $SRC rev-parse --abbrev-ref --symbolic-full-name '@{u}'
git -C ~/pp/remote.git ls-tree -r --name-only HEAD

Expected:

  • exit_code: 0
  • Push complete
  • local-skill/SKILL.md
  • regex: origin/\S+

3. Merge another machine's change, push, and sync

SRC=$(ss status --json | jq -r '.source.path')
BRANCH=$(git -C $SRC rev-parse --abbrev-ref HEAD)
rm -rf ~/pp/other && git clone -q ~/pp/remote.git ~/pp/other
git -C ~/pp/other config user.email other@example.com
git -C ~/pp/other config user.name other
mkdir -p ~/pp/other/remote-skill && printf -- '---\nname: remote-skill\n---\n# Remote\n' > ~/pp/other/remote-skill/SKILL.md
git -C ~/pp/other add -A && git -C ~/pp/other commit -qm "other machine" && git -C ~/pp/other push -q origin HEAD:$BRANCH
mkdir -p $SRC/second-skill && printf -- '---\nname: second-skill\n---\n# Second\n' > $SRC/second-skill/SKILL.md
ss push --pull -m "Add second skill"
git -C ~/pp/remote.git ls-tree -r --name-only HEAD
CLAUDE=$(ss status --json | jq -r '.targets[] | select(.name=="claude") | .path')
test -e "$CLAUDE/remote-skill/SKILL.md" && echo REMOTE_SKILL_SYNCED

Expected:

  • exit_code: 0
  • Push complete
  • remote-skill/SKILL.md
  • second-skill/SKILL.md
  • REMOTE_SKILL_SYNCED

4. Dry-run changes nothing

SRC=$(ss status --json | jq -r '.source.path')
printf '\nedit\n' >> $SRC/local-skill/SKILL.md
HEAD_BEFORE=$(git -C $SRC rev-parse HEAD)
REMOTE_BEFORE=$(git -C ~/pp/remote.git rev-parse HEAD)
ss push --pull --dry-run
[ "$(git -C $SRC rev-parse HEAD)" = "$HEAD_BEFORE" ] && [ "$(git -C ~/pp/remote.git rev-parse HEAD)" = "$REMOTE_BEFORE" ] && echo NOTHING_CHANGED
git -C $SRC checkout -q -- local-skill/SKILL.md

Expected:

  • exit_code: 0
  • Would pull from remote (merge)
  • Would sync targets
  • NOTHING_CHANGED

5. A conflict pushes nothing and keeps the local commit

SRC=$(ss status --json | jq -r '.source.path')
BRANCH=$(git -C $SRC rev-parse --abbrev-ref HEAD)
git -C ~/pp/other pull -q --no-rebase origin $BRANCH
printf -- '---\nname: local-skill\n---\n# Remote edit\n' > ~/pp/other/local-skill/SKILL.md
git -C ~/pp/other commit -qam "remote edit" && git -C ~/pp/other push -q origin HEAD:$BRANCH
REMOTE_BEFORE=$(git -C ~/pp/remote.git rev-parse HEAD)
printf -- '---\nname: local-skill\n---\n# Local edit\n' > $SRC/local-skill/SKILL.md
ss push --pull -m "Local edit" && echo UNEXPECTED_SUCCESS || echo FAILED_AS_EXPECTED
[ "$(git -C ~/pp/remote.git rev-parse HEAD)" = "$REMOTE_BEFORE" ] && echo REMOTE_UNCHANGED
git -C $SRC log -1 --format=%s

Expected:

  • exit_code: 0
  • FAILED_AS_EXPECTED
  • REMOTE_UNCHANGED
  • Local edit

6. commit rejects --pull

ss commit --pull && echo UNEXPECTED_SUCCESS || echo REJECTED

Expected:

  • exit_code: 0
  • REJECTED
  • --pull is only supported by push

Pass Criteria

  • All steps marked PASS.
  • Step 5 leaves the remote untouched and the local "Local edit" commit in place.