* 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.
5.0 KiB
sidebar_position
| sidebar_position |
|---|
| 2 |
pull
Pull from git remote and sync to all targets.
skillshare pull # Pull and sync
skillshare pull --dry-run # Preview
skillshare pull --force # Replace local with remote on first pull
When to Use
- Sync skills from another machine that pushed changes
- Get the latest skills after someone else pushed updates
- Start working on a new machine after
init --remote
What Happens
flowchart TD
CMD["skillshare pull"]
CHECK["1. Check repository status"]
PULL["2. Pull from remote"]
SYNC["3. Sync to all targets"]
CMD --> CHECK --> PULL --> SYNC
Options
| Flag | Description |
|---|---|
--dry-run, -n |
Preview without making changes |
--force, -f |
On first pull conflict, replace local skills with remote |
Git Root Scope
pull operates on the directory selected by the git_root config field (default: skills source). See commit — Git Root Scope for the scope table. If git_root was changed but the git repo still lives in another scope's directory, pull prints a "Git root mismatch" error with the exact git init / mv commands to fix it. See Changing the scope after init.
After pulling, pull syncs what the scope holds: skills runs sync, agents runs sync agents, extras runs sync extras, and root runs all three.
Plugins, MCP servers and hooks are settings in config.yaml, which no scope tracks, so pull neither brings nor applies them. See Cross-Machine Sync — Plugins, MCP and Hooks.
Prerequisites
Your source directory must be a git repository with a remote:
# Check if ready:
skillshare status
# Shows: Git: initialized with remote
Local Changes Warning
If you have uncommitted changes, pull will fail:
$ skillshare pull
Local changes detected
Run: skillshare push
Or: cd ~/.config/skillshare/skills && git stash
Solutions:
# Option 1: Commit locally first, without pushing
skillshare commit -m "Local changes"
skillshare pull
# Option 2: Push your changes first
skillshare push
skillshare pull
# Option 3: Stash your changes
cd ~/.config/skillshare/skills
git stash
skillshare pull
git stash pop
When Both Machines Committed
If this machine has commits the remote lacks and the remote has commits this machine lacks, pull merges the two histories into a merge commit, then syncs. Push afterwards to share the merge.
Both machines rewrite .metadata.json whenever they install or update a skill, so it often conflicts. pull resolves those conflicts on its own: each skill's entry is merged separately, and when both machines changed the same entry, the one with the later installed_at wins.
A conflict in any other file stops the pull, undoes the merge, and names the files:
$ skillshare pull
git pull failed
pull stopped: this machine and the remote both changed my-skill/SKILL.md; the merge was undone, resolve it with git in ~/.config/skillshare/skills
The repository is left as it was before the pull. To resolve the conflict yourself:
cd ~/.config/skillshare/skills
git pull --no-rebase # redo the merge and keep the conflicts
# edit the conflicted files, then
git add . && git commit --no-edit
skillshare push
skillshare sync
First Pull with Existing Skills
On first pull (no upstream yet), if the local repository already holds content (any directory, or any tracked or non-ignored file other than .gitignore),
pull attempts a merge to combine both sides. If the merge succeeds, both local and remote content is preserved. Only a repository with nothing else is reset to the remote branch.
If there are merge conflicts, pull fails with a non-zero exit code:
$ skillshare pull
Pull failed
Resolve manually: cd ~/.config/skillshare/skills && git merge --allow-unrelated-histories <remote branch>
Or force-pull: skillshare pull --force (replaces local with remote)
Resolve options:
# Resolve conflicts manually, then push
cd ~/.config/skillshare/skills
git add . && git commit
skillshare push
# Or discard local and take remote
skillshare pull --force
Examples
# Standard pull (most common)
skillshare pull
# Preview what would happen
skillshare pull --dry-run
# Replace local with remote on first-pull conflict
skillshare pull --force
Workflow
Typical workflow on a secondary machine:
# Start of day: get latest skills
skillshare pull
# ... work with AI tools ...
# End of day: share any new skills
skillshare collect claude # If you created new skills
skillshare push -m "Add new skill"
See Also
- commit — Commit locally without pushing
- push — Push to remote
- sync — Manual sync without pull
- Cross-Machine Sync — Full setup