Files
skillshare/website/docs/reference/commands/pull.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

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