sshmirror 0.1.0

SSH directory synchronization library and CLI

SSHMirror

Sync a working directory with a remote server over SSH, inspect diffs before applying changes, and keep a lightweight local history for rollback-oriented workflows.

SSHMirror is both:

• a Python library you can import;
• a CLI you can run inside a project folder;
• a sync workflow that keeps local and remote changes inspectable.

It can also be used as a lightweight sync workflow for a shared project: multiple developers can make changes to the same remote-backed codebase and inspect differences before pulling or pushing updates.

Why It Stands Out

• Preview first. Inspect current file changes and version-to-version diffs before syncing. 🔍
• Built for real SSH workflows. Passwords, SSH keys, passphrases, and ssh-agent fallback are supported. 🔐
• Keeps local state. SSHMirror stores version and migration metadata under .sshmirror/. 🗂️
• Works as a library or a command-line tool. 🐍
• Useful for team workflows. Several developers can work on one project and sync changes through the same remote environment. 🤝
• Optional remote container restart after sync. 🐳

Install 🚀

pip install sshmirror

For local development:

pip install -e .

Quick Start ⚡

1. Create a config file:

   sshmirror
   

   On first interactive launch, SSHMirror can create sshmirror.config.yml for you.

2. Start from this minimal config:

   host: '192.168.12.22'
   port: '50022'
   username: 'root'
   localdir: '.'
   remotedir: '/app'
   author: your-name
   

3. Check status or connect-test before syncing:

   sshmirror --status
   sshmirror --test-connection
   

Example Configuration ⚙️

The full example lives in sshmirror.config.example.yml.

Supported auth patterns:

• password auth;
• private key auth;
• private key with passphrase;
• default SSH keys or ssh-agent when no key and no password are provided.

Example with optional container restart:

host: '192.168.12.22'
port: '50022'
username: 'root'
localdir: '.'
remotedir: '/app'
author: your-name

restart_container:
   # Optional. If omitted, host/port/user are reused from the main SSH config.
   # host: '192.168.12.22'
   # port: '23322'
   # user: user
  sudo: true
  container_name: testcontainer

restart_container connects to the Docker host where the container is running. If host, port, or user are not specified there, SSHMirror uses the main connection values.

CLI Commands 🧰

sshmirror --help

Main non-interactive flags:

• --status show local and remote sync status;
• --current-diff inspect current local versus remote differences;
• --version-diff inspect changes between remote versions;
• --pull only pull from remote;
• --stash-changes stash local changes before syncing;
• --restore-stash restore previously stashed changes;
• --force-pull overwrite local files from remote;
• --discard discard all local changes;
• --discard-files <paths...> discard only selected files;
• --downgrade downgrade remote version;
• --test-connection validate SSH access to the remote host and configured Docker host.

Library Usage 📦

from sshmirror import SSHMirror, SSHMirrorConfig

mirror = SSHMirror(
    config=SSHMirrorConfig(
        host='127.0.0.1',
        port=22,
        username='root',
        localdir='.',
        remotedir='/app',
    )
)

The public API is exported from sshmirror/init.py.

Project Layout

sshmirror/
  sshmirror/          # importable package
  tests/              # smoke tests
  pyproject.toml      # packaging metadata
  sshmirror.config.example.yml

Development 🛠️

Run tests:

python -m unittest discover -s tests -p "test_*.py"

Build locally:

python -m build

Status

This repository is structured as a Python package with a CLI entry point. If you plan to publish to PyPI, keep package metadata, README, and license in sync with actual behavior.