If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/EugenMayer/docker-sync shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 31+ active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live EugenMayer/docker-sync repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/EugenMayer/docker-sync.

What it runs against: a local clone of EugenMayer/docker-sync — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in EugenMayer/docker-sync | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 190 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of EugenMayer/docker-sync. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/EugenMayer/docker-sync.git
#   cd docker-sync
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of EugenMayer/docker-sync and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "EugenMayer/docker-sync(\\.git)?\\b" \\
  && ok "origin remote is EugenMayer/docker-sync" \\
  || miss "origin remote is not EugenMayer/docker-sync (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/docker-sync.rb" \\
  && ok "lib/docker-sync.rb" \\
  || miss "missing critical file: lib/docker-sync.rb"
test -f "lib/docker-sync/command.rb" \\
  && ok "lib/docker-sync/command.rb" \\
  || miss "missing critical file: lib/docker-sync/command.rb"
test -f "lib/docker-sync/sync_manager.rb" \\
  && ok "lib/docker-sync/sync_manager.rb" \\
  || miss "missing critical file: lib/docker-sync/sync_manager.rb"
test -f "lib/docker-sync/config/project_config.rb" \\
  && ok "lib/docker-sync/config/project_config.rb" \\
  || miss "missing critical file: lib/docker-sync/config/project_config.rb"
test -f "lib/docker-sync/sync_strategy/native.rb" \\
  && ok "lib/docker-sync/sync_strategy/native.rb" \\
  || miss "missing critical file: lib/docker-sync/sync_strategy/native.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 190 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~160d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/EugenMayer/docker-sync"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

docker-sync is a Ruby CLI tool that synchronizes code changes between your local filesystem and Docker containers in real-time on macOS, Windows, and Linux. It solves the performance problem where Docker bind mounts are slow on non-Linux hosts by using native filesystem watchers and optimized sync strategies (unison, rsync, native) to keep container volumes updated while maintaining full development speed. Monolithic Ruby gem structure: bin/ contains three entry points (docker-sync, docker-sync-daemon, docker-sync-stack), Gemfile/docker-sync.gemspec define dependencies, and docs/ (Sphinx-based) lives alongside the code. The tool likely uses a single lib/ directory (not shown in top 60) with strategy classes for each sync backend. Orchestration happens via Thor (Thorfile present).

Full-stack developers (PHP, Node.js, Ruby) who run containerized applications locally and need instant code-to-container sync for fast feedback loops without sacrificing Docker's isolation benefits. DevOps engineers and team leads setting up development environments for teams that can't use Linux natively.

Actively maintained but showing signs of selective attention. The repo has CI/CD via Travis CI (.travis.yml), clear versioning (VERSION file), and is published as a RubyGem (docker-sync.gemspec). Multiple core contributors are listed, but the codebase is heavily Ruby (152KB) with sparse recent activity visible in file dates. Production-ready for established use cases, but not aggressively developed for new features.

Moderate risk: single primary maintainer (EugenMayer) with distributed contributor responsibility creates bus-factor concerns. The tool's core function depends on external sync engines (unison, rsync) and Docker daemon availability—failures in those systems propagate. No visible test directory in the top 60 files is a red flag for regression safety. Platform-specific code for macOS/Windows adds maintenance burden and potential breakage across OS updates.

No specific recent activity visible in the file list snapshot, but the repo explicitly solicits help with labels 'help wanted' and 'documentation needed' (visible in README). The Sphinx docs are actively maintained (.readthedocs.yaml present), and the project tracks issues for platform-specific bugs and feature requests.

git clone https://github.com/EugenMayer/docker-sync.git
cd docker-sync
bundle install
bin/docker-sync --help

For development: bundle exec bin/docker-sync to test CLI locally.

Daily commands: Development mode: bundle exec bin/docker-sync start (after docker-sync.yml config). Run as daemon: bundle exec bin/docker-sync-daemon start. Stack integration: bundle exec bin/docker-sync-stack start. All commands require a docker-sync.yml config file in working directory (see docs/getting-started/configuration.rst).

• lib/docker-sync.rb — Main entry point and library loader; every contributor must understand the module structure and initialization flow.
• lib/docker-sync/command.rb — CLI command dispatcher that routes user requests to sync managers; core interface between user and sync logic.
• lib/docker-sync/sync_manager.rb — Orchestrates sync operations and manages lifecycle; every contributor working on sync features must understand this.
• lib/docker-sync/config/project_config.rb — Parses and manages project-level docker-sync.yml configuration; essential for understanding how sync configurations are loaded.
• lib/docker-sync/sync_strategy/native.rb — Reference implementation of a sync strategy (likely native Docker volumes); demonstrates how sync backends are plugged in.
• bin/docker-sync — Executable entry point invoked by users; routes to command.rb for CLI dispatch.
• docker-sync.gemspec — Gem dependencies and metadata; defines all external libraries and versioning strategy.

• CLI Command Router (command.rb) (Thor, shell execution) — Receives user commands, routes to appropriate handlers, returns status to user
  • Failure mode: Invalid command or missing args → user sees error; dev must check docker-sync help
• Configuration Loader (YAML, file I/O, validation logic) — Discovers docker-sync.yml, parses YAML, validates schema, merges global + project config
  • Failure mode: Missing config or invalid YAML → startup fails; user must create/fix docker-sync.yml
• Dependency Checker — Verifies Docker,

Add a new sync strategy backend

1. Create a new strategy class inheriting from base sync strategy in lib/docker-sync/sync_strategy/ (lib/docker-sync/sync_strategy/your_strategy.rb)
2. Implement required methods: start, stop, and any strategy-specific initialization (lib/docker-sync/sync_strategy/your_strategy.rb)
3. Register the strategy in sync_manager.rb so it can be selected via docker-sync.yml (lib/docker-sync/sync_manager.rb)
4. Add configuration schema and validation in project_config.rb for your strategy options (lib/docker-sync/config/project_config.rb)
5. Document the strategy in docs/advanced/sync-strategies.rst (docs/advanced/sync-strategies.rst)

Add a new dependency checker

1. Create a new dependency class in lib/docker-sync/dependencies/ (lib/docker-sync/dependencies/your_tool.rb)
2. Implement check methods that verify installation and version requirements (lib/docker-sync/dependencies/your_tool.rb)
3. Register the dependency checker in lib/docker-sync/dependencies.rb (lib/docker-sync/dependencies.rb)
4. Add package manager support in lib/docker-sync/dependencies/package_managers/ if tool installation is needed (lib/docker-sync/dependencies/package_managers/base.rb)

Add a new CLI command

1. Define the command handler method in lib/docker-sync/command.rb (lib/docker-sync/command.rb)
2. Use Thor for argument/option parsing; map command name to method (lib/docker-sync/command.rb)
3. Call appropriate sync_manager methods to perform the operation (lib/docker-sync/sync_manager.rb)
4. Add help text and document in docs/getting-started/commands.rst (docs/getting-started/commands.rst)

• Ruby + Thor — Lightweight CLI framework enabling easy command routing and argument parsing for cross-platform dev tools
• Docker & Docker Compose — Core target platform; docker-sync bridges file sync between host and containers for development workflows
• Rsync / Unison — Proven, efficient file synchronization tools; rsync for one-way, unison for bidirectional sync
• fswatch — Cross-platform file system event monitoring to trigger syncs when source files change
• YAML configuration — Human-readable project and global config format familiar to Docker Compose users

• Pluggable sync strategies (native, rsync, unison) instead of single unified approach

  • Why: Different workflows and platforms benefit from different sync technologies (native volumes faster on some OSes, rsync more portable)
  • Consequence: More complex strategy selection and validation logic; users must understand their strategy choice implications

• Daemon mode vs. one-shot sync

  • Why: Daemon provides persistent sync; one-shot gives fine-grained control but requires manual restart on config changes
  • Consequence: Requires managing daemon lifecycle and logs; debugging harder with persistent background process

• File-system-level sync (rsync/unison) rather than Git-aware syncing

  • Why: Simpler, more universal; works with any project structure not just VCS repos
  • Consequence: Cannot skip ignored files automatically; syncs everything including node_modules, .git, etc. unless explicitly filtered

• Real-time code execution within containers (docker-sync only syncs files, containers must be managed separately)
• Cross-platform GUI or IDE integration (CLI-first tool; integrations built externally)
• Container orchestration beyond Docker Compose (not a Kubernetes tool)
• Persistent data container backup or disaster recovery (focuses on dev-time file sync only)

1. docker-sync requires an active Docker daemon running; it will fail silently if Docker is not available or not mounted at /var/run/docker.sock. 2) Sync strategies (unison vs rsync vs native) require different native tools installed on host; unison is 3-way merge aware but slower, rsync is faster but one-way, native is fastest but platform-dependent. 3) Performance degrades if docker-sync.yml syncs entire large directories (node_modules, .git); requires explicit ignore lists. 4) On macOS, requires osxfs or native Docker Desktop backend; behavior differs between Intel and Apple Silicon. 5) Daemon mode (docker-sync-daemon) keeps file watchers open; may require increased ulimit for projects with many files.

• Filesystem watching (inotify/FSEvents) — docker-sync uses native filesystem watchers (FSEvents on macOS, inotify on Linux, Directory Watcher on Windows) to detect local file changes and trigger sync; understanding watch event semantics prevents sync lag and missed changes
• Unison two-way merge synchronization — Unison is docker-sync's default strategy and detects conflicts (both sides changed same file), preserves deletions, and handles renames; knowing its limitations (3-way merge, slower than rsync) informs strategy selection
• rsync delta algorithm — docker-sync's rsync strategy sends only changed blocks, not whole files; understanding checksums and rolling hash prevents full-directory re-syncs and enables efficient incremental updates
• Docker volume bind mounts vs named volumes — docker-sync intercepts bind mounts (local filesystem paths) and uses named volumes for synced state; misunderstanding this breaks the sync—changes go to bind mount source, not container volume
• Container overlay filesystem (UnionFS) — Docker layers images via UnionFS; docker-sync must sync at the volume layer to bypass the read-only image layers and persist changes during development
• osxfs (macOS filesystem shim) — On macOS Docker Desktop, bind mounts go through osxfs (slow FUSE-like layer); docker-sync bypasses this by using native-layer syncing strategies, critical for understanding performance bottleneck
• Thor task framework — docker-sync CLI is built on Thor (Thorfile), not plain optparse; understanding Thor's invocation, task dependencies, and option parsing is needed to add/modify commands

• docker/cli — Official Docker CLI that docker-sync wraps; understanding docker commands and volume flags is foundational
• gvaughn/unison — Ruby wrapper around unison sync engine; docker-sync depends on unison as default strategy implementation
• vagrant/vagrant — Predecessor tool that also solved sync problems in virtualized dev environments; docker-sync evolved patterns from Vagrant's shared folder solutions
• docker/docker-compose — Companion repo that docker-sync integrates with via docker-sync-stack; users chain docker-compose with docker-sync for orchestration
• rbenv/rbenv — Ruby version manager frequently used by docker-sync developers; the tool assumes Ruby 2.4+ is available locally to run the CLI

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow to replace Travis CI

The repo uses .travis.yml for CI, but Travis CI has sunset free tier support for public repos. GitHub Actions is now the standard. This would modernize the CI/CD pipeline and ensure builds continue to run. The repo has bin/ scripts and a Gemfile indicating Ruby testing is needed.

• [ ] Create .github/workflows/test.yml to run Gemfile-based tests (bundle exec tests)
• [ ] Add workflow steps for linting the Ruby code in bin/ and lib/ directories
• [ ] Add workflow to validate docker-sync.gemspec and gem dependencies
• [ ] Test against multiple Ruby versions (2.6, 2.7, 3.0+) to ensure compatibility
• [ ] Add workflow status badges to README.md to replace Travis CI badge

Add integration tests for sync strategies in docs/advanced/sync-strategies.rst

The file docs/advanced/sync-strategies.rst documents multiple sync strategies, but there's no corresponding test suite to validate these strategies work correctly. Given the complexity of file syncing across OSX/Windows/Linux, automated integration tests would prevent regressions.

• [ ] Create spec/integration/ directory for integration tests
• [ ] Add tests for each sync strategy mentioned in sync-strategies.rst (unison, native_osx, etc.)
• [ ] Use example/ Docker setup to test real sync scenarios
• [ ] Add test documentation in docs/miscellaneous/development-and-testing.rst with instructions to run integration tests
• [ ] Include tests that verify file permissions and symlink handling across platforms

Document and add CLI argument validation tests for bin/docker-sync commands

The repo has three CLI entry points (bin/docker-sync, bin/docker-sync-daemon, bin/docker-sync-stack) but docs/getting-started/commands.rst appears incomplete and there are no unit tests for argument parsing. New contributors often break CLI compatibility unknowingly.

• [ ] Audit all three bin/ scripts to document all CLI flags and options
• [ ] Update docs/getting-started/commands.rst with complete argument reference for each command
• [ ] Create spec/unit/cli/ tests for argument parsing (validate required args, flag combinations, error handling)
• [ ] Add tests that verify backward compatibility when users upgrade docker-sync versions
• [ ] Document common CLI error scenarios in docs/troubleshooting/common-issues.rst

• Add integration tests for sync-strategy.rst strategies: the docs/advanced/ directory exists but no visible test/ directory in top 60 files suggests unison/rsync behavior isn't validated in CI. Write Ruby tests that verify each sync backend correctly copies a test file and respects ignore patterns.: Prevents silent regressions when dependencies (unison, rsync versions) change
• Document platform-specific quirks in docs/getting-started/: currently no section explicitly warns Windows users about WSL2 docker.sock path differences or macOS users about gRPC socket issues. Add platform-specific installation/troubleshooting sections.: Reduces support burden and improves first-run success rate on non-Linux hosts
• Implement a docker-sync diagnose command in bin/ that checks prerequisites (Docker availability, unison/rsync installed, file watcher limits) and reports sync strategy recommendations based on OS/project size. Output JSON for CI/CD pipelines.: Unblocks users stuck on setup; provides actionable feedback instead of cryptic daemon failures

The docker-sync codebase demonstrates reasonable security practices with dependency locking (Gemfile.lock) and configuration management. However, several areas require attention: (1) Regular dependency vulnerability scanning should be implemented for both Ruby gems and Python packages; (2) Shell scripts containing Docker and system commands need careful review for injection vulnerabilities; (3) IDE configuration files should be excluded from version control; (4) Documentation should emphasize security best practices for production deployments. The project appears to be actively maintained with CI/CD (Travis CI), which is positive. No obvious hardcoded secrets or credentials were detected in the file structure provided.

• Medium · Outdated Sphinx RTD Theme Dependency — docs/requirements.txt. The sphinx_rtd_theme==2.0.0 dependency is pinned to a specific version. While this provides reproducibility, it may not receive security updates if a newer patch version is available. Version 2.0.0 was released in 2023 and should be monitored for security advisories. Fix: Regularly update dependencies to their latest patch versions. Consider using a version constraint like sphinx_rtd_theme>=2.0.0,<3.0.0 to allow security patches while maintaining stability. Implement automated dependency scanning using tools like Dependabot.
• Medium · Potential Command Injection in Shell Scripts — bin/*, example/create-data/entrypoint.sh, deploy_locally.sh. The repository contains shell scripts (bin/docker-sync, bin/docker-sync-daemon, bin/docker-sync-stack, example/create-data/entrypoint.sh, deploy_locally.sh) that interact with Docker and system commands. Without reviewing the actual content, there is a risk of command injection if user input or configuration values are not properly sanitized before being passed to shell commands. Fix: Review all shell scripts for proper input validation and escaping. Use parameterized arguments instead of string concatenation. Avoid using eval() or backticks with untrusted input. Use proper quoting and consider using safer alternatives like array arguments in modern shell syntax.
• Medium · Ruby Gem Dependency Management Risk — Gemfile, Gemfile.lock, docker-sync.gemspec. The project uses a Gemfile for Ruby dependencies. While a Gemfile.lock exists (which is good), the actual gem versions and their security status cannot be determined from the provided information. Ruby gems may contain known vulnerabilities. Fix: Regularly run 'bundle audit' to check for known vulnerabilities in dependencies. Keep gems updated to their latest secure versions. Consider using Dependabot or similar tools for automated vulnerability scanning of Ruby dependencies.
• Low · Sensitive Configuration Examples in Repository — example/ directory. The repository contains example configuration files (example/docker-sync.yml, example/docker-compose.yml) that may serve as templates for users. While no hardcoded credentials were identified, these files could accidentally be used as a basis for production configurations without proper security hardening. Fix: Ensure example configuration files include security best practices and comments about sensitive configuration options. Add a security checklist in the documentation for production deployments. Consider adding .env.example with notes about which variables should never be committed.
• Low · IDE Configuration Files in Repository — .idea/ directory. The .idea/ directory (JetBrains IDE configuration) is committed to the repository. While not a direct security vulnerability, this is a best practice violation that can expose IDE settings and potentially sensitive workspace configurations. Fix: Add .idea/ to .gitignore to prevent IDE-specific configuration files from being committed. IDE configuration files should remain local to each developer's machine.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.