syncware 0.0.5

Sync selective folders from Git repositories to a target directory

syncware

A CLI tool for syncing selective folders from local Git repositories to a target directory. Think go mod vendor or npm install, but for folder-based content.

Installation

pip install syncware

Development

Clone the repository and install with dev dependencies using uv:

git clone https://github.com/youruser/syncware.git
cd syncware
uv sync --group dev

This installs build, twine, and pytest for building and testing.

Quick Start

# Initialize a new project
syncware init

# Edit syncware.yml with your repositories

# List configured folders
syncware list

# Sync folders to target
syncware sync

# Preview sync (dry run)
syncware sync --dry

# Update repos and sync
syncware update

# Generate lockfile (captures exact versions)
syncware lockfile

# Verify folders against lockfile
syncware verify

# Auto-fix drift
syncware verify --fix

Verbosity

syncware -v list      # INFO level (default)
syncware -vv list     # DEBUG level

Configuration

Create a syncware.yml file in your project root:

repos:
  - name: myrepo
    path: /path/to/local/repo
    source: path/to/folders
    folders:
      - folder1
      - folder2
      - "*"  # or all subdirectories
    target: ./output  # optional, overrides global target

target: ./output  # global target (default)

Per-Repo Target

Each repo can have its own target:

repos:
  - name: frontend
    path: ./packages/frontend
    source: dist
    folders: ["ui", "icons"]
    target: ./public/assets

  - name: backend
    path: ./packages/backend
    source: configs
    folders: ["nginx", "docker"]
    target: ./deploy/config

target: ./common/output  # used by repos without own target

Multiple Targets

Both global and per-repo targets can specify multiple destinations:

# Global multiple targets
target: ["./output1", "./output2"]

repos:
  - name: myrepo
    path: /path/to/repo
    source: dist
    folders: ["ui", "icons"]
    # folder1 and folder2 sync to BOTH ./output1 and ./output2

# Per-repo multiple targets
repos:
  - name: frontend
    path: ./packages/frontend
    source: dist
    folders: ["ui", "icons"]
    target: ["./public/assets", "./backup/assets"]
    # ui and icons sync to BOTH ./public/assets and ./backup/assets

Remote Repositories

You can also use remote Git URLs (GitHub, GitLab, etc.):

repos:
  - name: claude
    path: https://github.com/user/repo.git
    source: skills
    folders: ["docx", "xlsx"]

Remote repos are cloned to ~/.cache/syncware/<name> and reused on subsequent runs.

Config Fields

Field	Description
repos	List of source repositories
repos[].name	Namespace identifier
repos[].path	Local path or Git URL
repos[].source	Subdirectory containing folders to sync
repos[].folders	List of folder names, or "*" for all
repos[].target	Per-repo destination (string or list, overrides global)
target	Global destination directory (string or list)

How It Works

<repo.path>/<source>/<folder> → copied to <repo.target>/<folder>
                                  or <global.target>/<folder>
                                  (or to ALL targets if multiple)

Lockfile

The lockfile (syncware.lock.yml) ensures reproducible syncs:

syncware lockfile          # Generate lockfile
syncware verify           # Check for drift
syncware verify --fix     # Auto-fix drift

What gets locked:

• Git commit hash of each source repository
• Content hash (SHA256) of each synced folder

Verification detects:

• DRIFT - Folder content was modified locally
• UPDATE_AVAILABLE - Source repo has new commits
• MISSING - Source folder was deleted

Use Cases

• Skills/Plugins - Sync skill folders from a central repo
• Config Management - Keep config folders in sync across machines
• Documentation - Maintain a set of doc folders from different sources
• Assets - Bundle asset folders from multiple repositories

Comparison

Tool	Use Case
syncware	Selective folder sync from local or remote repos
go mod vendor	Vendor Go dependencies
npm install	Install package dependencies
rsync	General file/folder synchronization