git-ssh-sync 0.3.0__tar.gz → 0.4.0__tar.gz

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: git-ssh-sync
-Version: 0.3.0
+Version: 0.4.0
 Summary: Sync Git commits through a local machine for development environments without direct GitHub or GitLab access.
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: pyyaml>=6.0.3
@@ -102,9 +102,20 @@ git-ssh-sync init myproject `
   --dev-host devserver `
   --dev-user user `
   --dev-os windows `
-  --dev-path C:\Users\user\work\myproject
+  --dev-path 'C:\Users\user\work\myproject'
 ```
 
+When running the command from macOS or Linux shells such as `zsh` or `bash`,
+quote Windows paths that contain backslashes. Otherwise the shell can remove the
+backslashes before `git-ssh-sync` receives the argument. You can also use forward
+slashes, for example `C:/Users/user/work/myproject`.
+
+When `--dev-os windows` is used, the default cache path is
+`C:\Users\<dev-user>\.git-ssh-sync\cache\<project>.git`. `clone` stops if either
+the configured work path or cache path already exists on the development
+environment, so remove stale directories or use the attach/recover workflow for
+existing repositories.
+
 For `--origin`, specify a remote URL that can be used with `git clone` or `git fetch`. Main formats are:
 
 ```text
@@ -128,6 +139,59 @@ git-ssh-sync init myproject \
   --force
 ```
 
+### Configuration file
+
+Project settings are saved as YAML. The default path depends on the local
+machine where `git-ssh-sync` runs:
+
+```text
+macOS / Linux: ~/.config/git-ssh-sync/config.yaml
+Windows:       %APPDATA%\git-ssh-sync\config.yaml
+```
+
+A generated configuration looks like this:
+
+```yaml
+version: 1
+
+projects:
+  myproject:
+    origin: git@github.com:example/myproject.git
+
+    local:
+      repo_path: ~/.git-ssh-sync/repos/myproject
+
+    dev:
+      host: devserver
+      user: user
+      os: posix
+      work_path: /home/user/work/myproject
+      cache_path: /home/user/.git-ssh-sync/cache/myproject.git
+
+    options:
+      sync_tags: true
+      lfs: false
+      submodules: false
+      ff_only: true
+```
+
+Main fields:
+
+- `origin`: GitHub / GitLab repository URL used by the local gateway repository
+- `local.repo_path`: Local gateway repository path managed by `git-ssh-sync`
+- `dev.host`, `dev.user`, `dev.os`: SSH connection target and remote OS
+- `dev.work_path`: Work repository path on the development environment
+- `dev.cache_path`: Bare cache repository path on the development environment
+- `options.sync_tags`: Synchronize Git tags when pulling or pushing
+- `options.lfs`: Reserved option for Git LFS support
+- `options.submodules`: Reserved option for submodule support
+- `options.ff_only`: Keep synchronization fast-forward only
+
+In normal use, manage this file with `git-ssh-sync init` and
+`git-ssh-sync config` commands. If you edit it manually, keep the YAML
+structure unchanged and use paths that are valid on the machine or
+development environment where each field is used.
+
 You can inspect and maintain registered projects without opening the config file directly.
 
 ```bash
@@ -250,6 +314,27 @@ git-ssh-sync push myproject
 
 `pull` and `push` target the current branch of the work repository on the development environment. To synchronize a different branch, switch the work repository branch with `checkout` first.
 
+If you are not sure about the current state at the beginning of work, first check synchronization status from the local machine and run `pull` when needed.
+
+```bash
+git-ssh-sync status myproject
+git-ssh-sync pull myproject
+git-ssh-sync dev status myproject
+```
+
+If `dev status` shows a dirty working tree on the development environment, uncommitted changes are not synchronized. Inspect the diff on the development environment and commit the changes you want to synchronize before `push`.
+
+```bash
+git-ssh-sync dev diff myproject --stat
+```
+
+Before pushing, confirm that the development environment changes are committed, then run `status` and `push` from the local machine.
+
+```bash
+git-ssh-sync status myproject
+git-ssh-sync push myproject
+```
+
 Use `--dry-run` to inspect the planned operations and preflight checks before changing refs:
 
 ```bash
@@ -257,6 +342,51 @@ git-ssh-sync pull myproject --dry-run
 git-ssh-sync push myproject --dry-run
 ```
 
+## Workflow When Push Stops
+
+`push` executes only when the branch on the origin side is an ancestor of the branch on the development environment side. It stops when origin has commits that have not been pulled yet, or when origin and the development environment have diverged.
+
+In that case, run `pull` from the local machine to deliver origin changes to the development environment.
+
+```bash
+git-ssh-sync pull myproject
+```
+
+If `pull` cannot fast-forward, `git-ssh-sync` does not automatically merge or rebase. Resolve it with normal Git operations on the development environment, using either merge or rebase, then run `push` again from the local machine.
+
+Example using merge:
+
+```bash
+cd ~/work/myproject
+git fetch gitsync
+git merge gitsync/main
+# If there are conflicts, edit the files
+git status
+git add <resolved-files>
+git commit
+```
+
+Example using rebase:
+
+```bash
+cd ~/work/myproject
+git fetch gitsync
+git rebase gitsync/main
+# If there are conflicts, edit the files
+git status
+git add <resolved-files>
+git rebase --continue
+```
+
+If the branch is not `main`, replace `gitsync/main` with the target branch. After merge or rebase completes, check status from the local machine and push.
+
+```bash
+git-ssh-sync status myproject
+git-ssh-sync push myproject
+```
+
+After rebase, only rewrite commits that exist only on the development environment and have not been pushed to origin yet. If you want to avoid rewriting history on a shared branch, use merge.
+
 ## Branch Switching Workflow
 
 To switch to an existing branch, execute `checkout` from the local machine.
@@ -343,7 +473,7 @@ Uncommitted changes are not synchronized. If there are uncommitted changes in th
 
 `push` executes only when the branch on the origin side is an ancestor of the branch on the development environment side. If there are unobtained commits on origin, it stops.
 
-When diverged, automatic resolution is not performed. Execute `pull` on the local machine, follow the displayed instructions to merge or rebase in the development environment, then `push` again.
+When diverged, automatic resolution is not performed. Follow "Workflow When Push Stops", merge or rebase in the development environment, then `push` again.
 
 ## Common Commands
 

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/README.md

@@ -91,9 +91,20 @@ git-ssh-sync init myproject `
   --dev-host devserver `
   --dev-user user `
   --dev-os windows `
-  --dev-path C:\Users\user\work\myproject
+  --dev-path 'C:\Users\user\work\myproject'
 ```
 
+When running the command from macOS or Linux shells such as `zsh` or `bash`,
+quote Windows paths that contain backslashes. Otherwise the shell can remove the
+backslashes before `git-ssh-sync` receives the argument. You can also use forward
+slashes, for example `C:/Users/user/work/myproject`.
+
+When `--dev-os windows` is used, the default cache path is
+`C:\Users\<dev-user>\.git-ssh-sync\cache\<project>.git`. `clone` stops if either
+the configured work path or cache path already exists on the development
+environment, so remove stale directories or use the attach/recover workflow for
+existing repositories.
+
 For `--origin`, specify a remote URL that can be used with `git clone` or `git fetch`. Main formats are:
 
 ```text
@@ -117,6 +128,59 @@ git-ssh-sync init myproject \
   --force
 ```
 
+### Configuration file
+
+Project settings are saved as YAML. The default path depends on the local
+machine where `git-ssh-sync` runs:
+
+```text
+macOS / Linux: ~/.config/git-ssh-sync/config.yaml
+Windows:       %APPDATA%\git-ssh-sync\config.yaml
+```
+
+A generated configuration looks like this:
+
+```yaml
+version: 1
+
+projects:
+  myproject:
+    origin: git@github.com:example/myproject.git
+
+    local:
+      repo_path: ~/.git-ssh-sync/repos/myproject
+
+    dev:
+      host: devserver
+      user: user
+      os: posix
+      work_path: /home/user/work/myproject
+      cache_path: /home/user/.git-ssh-sync/cache/myproject.git
+
+    options:
+      sync_tags: true
+      lfs: false
+      submodules: false
+      ff_only: true
+```
+
+Main fields:
+
+- `origin`: GitHub / GitLab repository URL used by the local gateway repository
+- `local.repo_path`: Local gateway repository path managed by `git-ssh-sync`
+- `dev.host`, `dev.user`, `dev.os`: SSH connection target and remote OS
+- `dev.work_path`: Work repository path on the development environment
+- `dev.cache_path`: Bare cache repository path on the development environment
+- `options.sync_tags`: Synchronize Git tags when pulling or pushing
+- `options.lfs`: Reserved option for Git LFS support
+- `options.submodules`: Reserved option for submodule support
+- `options.ff_only`: Keep synchronization fast-forward only
+
+In normal use, manage this file with `git-ssh-sync init` and
+`git-ssh-sync config` commands. If you edit it manually, keep the YAML
+structure unchanged and use paths that are valid on the machine or
+development environment where each field is used.
+
 You can inspect and maintain registered projects without opening the config file directly.
 
 ```bash
@@ -239,6 +303,27 @@ git-ssh-sync push myproject
 
 `pull` and `push` target the current branch of the work repository on the development environment. To synchronize a different branch, switch the work repository branch with `checkout` first.
 
+If you are not sure about the current state at the beginning of work, first check synchronization status from the local machine and run `pull` when needed.
+
+```bash
+git-ssh-sync status myproject
+git-ssh-sync pull myproject
+git-ssh-sync dev status myproject
+```
+
+If `dev status` shows a dirty working tree on the development environment, uncommitted changes are not synchronized. Inspect the diff on the development environment and commit the changes you want to synchronize before `push`.
+
+```bash
+git-ssh-sync dev diff myproject --stat
+```
+
+Before pushing, confirm that the development environment changes are committed, then run `status` and `push` from the local machine.
+
+```bash
+git-ssh-sync status myproject
+git-ssh-sync push myproject
+```
+
 Use `--dry-run` to inspect the planned operations and preflight checks before changing refs:
 
 ```bash
@@ -246,6 +331,51 @@ git-ssh-sync pull myproject --dry-run
 git-ssh-sync push myproject --dry-run
 ```
 
+## Workflow When Push Stops
+
+`push` executes only when the branch on the origin side is an ancestor of the branch on the development environment side. It stops when origin has commits that have not been pulled yet, or when origin and the development environment have diverged.
+
+In that case, run `pull` from the local machine to deliver origin changes to the development environment.
+
+```bash
+git-ssh-sync pull myproject
+```
+
+If `pull` cannot fast-forward, `git-ssh-sync` does not automatically merge or rebase. Resolve it with normal Git operations on the development environment, using either merge or rebase, then run `push` again from the local machine.
+
+Example using merge:
+
+```bash
+cd ~/work/myproject
+git fetch gitsync
+git merge gitsync/main
+# If there are conflicts, edit the files
+git status
+git add <resolved-files>
+git commit
+```
+
+Example using rebase:
+
+```bash
+cd ~/work/myproject
+git fetch gitsync
+git rebase gitsync/main
+# If there are conflicts, edit the files
+git status
+git add <resolved-files>
+git rebase --continue
+```
+
+If the branch is not `main`, replace `gitsync/main` with the target branch. After merge or rebase completes, check status from the local machine and push.
+
+```bash
+git-ssh-sync status myproject
+git-ssh-sync push myproject
+```
+
+After rebase, only rewrite commits that exist only on the development environment and have not been pushed to origin yet. If you want to avoid rewriting history on a shared branch, use merge.
+
 ## Branch Switching Workflow
 
 To switch to an existing branch, execute `checkout` from the local machine.
@@ -332,7 +462,7 @@ Uncommitted changes are not synchronized. If there are uncommitted changes in th
 
 `push` executes only when the branch on the origin side is an ancestor of the branch on the development environment side. If there are unobtained commits on origin, it stops.
 
-When diverged, automatic resolution is not performed. Execute `pull` on the local machine, follow the displayed instructions to merge or rebase in the development environment, then `push` again.
+When diverged, automatic resolution is not performed. Follow "Workflow When Push Stops", merge or rebase in the development environment, then `push` again.
 
 ## Common Commands
 

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "git-ssh-sync"
-version = "0.3.0"
+version = "0.4.0"
 description = "Sync Git commits through a local machine for development environments without direct GitHub or GitLab access."
 readme = "README.md"
 requires-python = ">=3.12"

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/__init__.py

@@ -1,3 +1,3 @@
 """git-ssh-sync package."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/attach.py

@@ -422,6 +422,7 @@ def _apply_operation(
             cache_url,
             [f"refs/remotes/origin/{branch}:refs/heads/{branch}"],
             cwd=local_path,
+            env=ssh.git_ssh_environment(project_config.dev.os),
         )
         return
 

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/branch.py

@@ -146,6 +146,7 @@ def inspect_project_branch(project: str, project_config: ProjectConfig) -> Branc
             dev_repo_url,
             [f"refs/heads/{branch}:refs/remotes/dev/{branch}"],
             cwd=local_path,
+            env=ssh.git_ssh_environment(project_config.dev.os),
         )
 
     rows: list[BranchRow] = []

git_ssh_sync-0.4.0/src/git_ssh_sync/clone.py

@@ -0,0 +1,171 @@
+"""Project clone workflow."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from git_ssh_sync import git, ssh
+from git_ssh_sync.config import get_project, load_config
+from git_ssh_sync.errors import CommandExecutionError
+from git_ssh_sync.logging_config import logger
+
+
+class CloneError(RuntimeError):
+    """Raised when the clone workflow would overwrite existing data."""
+
+
+def _ensure_local_missing(path: Path) -> None:
+    if path.exists():
+        raise CloneError(f"[local] path already exists: {path}")
+
+
+def _ensure_remote_missing(
+    *, host: str, user: str, path: str, remote_os: ssh.RemoteOS
+) -> None:
+    result = ssh.remote_path_exists(
+        host, path, user=user, remote_os=remote_os, path_type="any"
+    )
+    if result.returncode == 0:
+        raise CloneError(f"[{result.environment}] path already exists: {path}")
+    if result.returncode == 1:
+        return
+    raise CommandExecutionError(
+        environment=result.environment,
+        command=result.command,
+        returncode=result.returncode,
+        cwd=result.cwd,
+        stdout=result.stdout,
+        stderr=result.stderr,
+    )
+
+
+def _local_current_branch(local_path: Path) -> str:
+    result = git.run_git(["branch", "--show-current"], cwd=local_path)
+    branch = result.stdout.strip()
+    if not branch:
+        raise CloneError("Could not determine the cloned repository's current branch.")
+    return branch
+
+
+def _cleanup_local_path(path: Path) -> None:
+    if not path.exists():
+        return
+    try:
+        if path.is_dir() and not path.is_symlink():
+            shutil.rmtree(path)
+            return
+        path.unlink()
+    except OSError as error:
+        logger.debug("Failed to clean up local path %s: %s", path, error)
+
+
+def _cleanup_remote_path(
+    *, host: str, user: str, path: str, remote_os: ssh.RemoteOS
+) -> None:
+    result = ssh.remote_remove(host, path, user=user, remote_os=remote_os)
+    if result.returncode != 0:
+        logger.debug(
+            "Failed to clean up remote path %s on %s: %s",
+            path,
+            result.environment,
+            result.stderr.strip(),
+        )
+
+
+def clone_project(project: str) -> None:
+    """Clone a configured project and initialize its development repositories."""
+    app_config = load_config()
+    project_config = get_project(app_config, project)
+
+    local_path = Path(project_config.local.repo_path)
+    dev_host = project_config.dev.host
+    dev_user = project_config.dev.user
+    dev_os = project_config.dev.os
+    cache_path = project_config.dev.cache_path
+    work_path = project_config.dev.work_path
+
+    _ensure_local_missing(local_path)
+    _ensure_remote_missing(
+        host=dev_host, user=dev_user, path=cache_path, remote_os=dev_os
+    )
+    _ensure_remote_missing(
+        host=dev_host, user=dev_user, path=work_path, remote_os=dev_os
+    )
+
+    local_started = False
+    cache_started = False
+    work_started = False
+    try:
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        local_started = True
+        git.run_git(["clone", project_config.origin, str(local_path)])
+        git.fetch("origin", cwd=local_path)
+        branch = _local_current_branch(local_path)
+
+        ssh.remote_mkdir(
+            dev_host,
+            ssh.remote_parent(cache_path, dev_os),
+            user=dev_user,
+            remote_os=dev_os,
+        )
+        cache_started = True
+        ssh.run_remote_command(
+            dev_host,
+            ["git", "init", "--bare", cache_path],
+            user=dev_user,
+            remote_os=dev_os,
+        )
+
+        remote_cache = ssh.remote_git_url(
+            host=dev_host, user=dev_user, repo_path=cache_path, remote_os=dev_os
+        )
+        git.push(
+            remote_cache,
+            [f"refs/remotes/origin/{branch}:refs/heads/{branch}"],
+            cwd=local_path,
+            env=ssh.git_ssh_environment(dev_os),
+        )
+        if project_config.options.sync_tags:
+            git.push(
+                remote_cache,
+                ["--tags"],
+                cwd=local_path,
+                env=ssh.git_ssh_environment(dev_os),
+            )
+
+        ssh.remote_mkdir(
+            dev_host,
+            ssh.remote_parent(work_path, dev_os),
+            user=dev_user,
+            remote_os=dev_os,
+        )
+        work_started = True
+        ssh.run_remote_command(
+            dev_host,
+            ["git", "clone", cache_path, work_path],
+            user=dev_user,
+            remote_os=dev_os,
+        )
+        ssh.run_remote_git(
+            dev_host,
+            work_path,
+            ["remote", "rename", "origin", "gitsync"],
+            user=dev_user,
+            remote_os=dev_os,
+        )
+        ssh.run_remote_git(
+            dev_host, work_path, ["switch", branch], user=dev_user, remote_os=dev_os
+        )
+    except Exception:
+        if work_started:
+            _cleanup_remote_path(
+                host=dev_host, user=dev_user, path=work_path, remote_os=dev_os
+            )
+        if cache_started:
+            _cleanup_remote_path(
+                host=dev_host, user=dev_user, path=cache_path, remote_os=dev_os
+            )
+        if local_started:
+            _cleanup_local_path(local_path)
+        raise

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/config.py

@@ -3,12 +3,19 @@
 from __future__ import annotations
 
 import os
+import re
 import sys
 from pathlib import Path
 from typing import Any, Literal
 
 import yaml
-from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+)
 
 
 class ConfigError(Exception):
@@ -31,6 +38,29 @@ def _expand_path(value: str) -> str:
     return str(Path(value).expanduser())
 
 
+def _default_dev_cache_path(
+    project: str, dev_user: str | None, dev_os: Literal["posix", "windows"]
+) -> str:
+    if dev_os == "windows":
+        return f"C:\\Users\\{dev_user}\\.git-ssh-sync\\cache\\{project}.git"
+    return f"/home/{dev_user}/.git-ssh-sync/cache/{project}.git"
+
+
+def _looks_like_unquoted_windows_path(value: str) -> bool:
+    return bool(re.match(r"^[A-Za-z]:[^\\/]", value))
+
+
+def _validate_windows_path_input(field_name: str, value: str | None) -> None:
+    if value is None or not _looks_like_unquoted_windows_path(value):
+        return
+    raise ConfigError(
+        f"{field_name} looks like a Windows path whose separators were removed "
+        "by the shell. Quote backslash paths, for example "
+        r"'C:\Users\user\work\repo', or use forward slashes like "
+        "C:/Users/user/work/repo."
+    )
+
+
 class LocalConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
@@ -48,9 +78,6 @@ class DevConfig(BaseModel):
     work_path: str = Field(min_length=1)
     cache_path: str = Field(min_length=1)
 
-    _expand_work_path = field_validator("work_path")(_expand_path)
-    _expand_cache_path = field_validator("cache_path")(_expand_path)
-
 
 class OptionsConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
@@ -194,6 +221,13 @@ def update_project(
         raw["dev"]["cache_path"] = dev_cache_path
         updated = True
 
+    effective_dev_os = raw["dev"].get("os")
+    if effective_dev_os == "windows":
+        if dev_work_path is not None:
+            _validate_windows_path_input("dev.work_path", dev_work_path)
+        if dev_cache_path is not None:
+            _validate_windows_path_input("dev.cache_path", dev_cache_path)
+
     for key, value in {
         "sync_tags": sync_tags,
         "lfs": lfs,
@@ -234,6 +268,10 @@ def build_project_config(
     options: OptionsConfig | None = None,
 ) -> ProjectConfig:
     """Build and validate a project config, applying init defaults."""
+    if dev_os == "windows":
+        _validate_windows_path_input("dev.work_path", dev_work_path)
+        _validate_windows_path_input("dev.cache_path", dev_cache_path)
+
     raw: dict[str, Any] = {
         "origin": origin,
         "local": {
@@ -245,7 +283,7 @@ def build_project_config(
             "os": dev_os,
             "work_path": dev_work_path,
             "cache_path": dev_cache_path
-            or f"/home/{dev_user}/.git-ssh-sync/cache/{project}.git",
+            or _default_dev_cache_path(project, dev_user, dev_os),
         },
         "options": (options or OptionsConfig()).model_dump(mode="json"),
     }

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/doctor.py

@@ -621,6 +621,7 @@ def _check_repository(
             cache_repo_url,
             [f"refs/heads/{branch}:refs/remotes/dev-cache/{branch}"],
             cwd=local_path,
+            env=ssh.git_ssh_environment(project_config.dev.os),
         )
     except CommandExecutionError as error:
         checks.append(
@@ -647,6 +648,7 @@ def _check_repository(
             dev_repo_url,
             [f"refs/heads/{branch}:refs/remotes/dev/{branch}"],
             cwd=local_path,
+            env=ssh.git_ssh_environment(project_config.dev.os),
         )
     except CommandExecutionError as error:
         checks.append(

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/git.py

@@ -57,6 +57,7 @@ def _run_command(
         env=_merged_env(env),
         capture_output=True,
         text=True,
+        errors="replace",
         check=False,
     )
 

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/ssh.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import shlex
+import sys
+from base64 import b64encode
 from collections.abc import Mapping, Sequence
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Literal
@@ -86,9 +88,10 @@ def run_powershell(
     check: bool = True,
 ) -> CommandResult:
     """Run a PowerShell script on an SSH host."""
+    encoded_script = b64encode(script.encode("utf-16le")).decode("ascii")
     remote_command = (
-        "powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "
-        f"{_powershell_quote(script)}"
+        "powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass "
+        f"-EncodedCommand {encoded_script}"
     )
     return _run_ssh_command_string(
         host,
@@ -183,15 +186,31 @@ def run_remote_git(
 
 def remote_git_url(*, host: str, user: str, repo_path: str, remote_os: RemoteOS) -> str:
     """Build an SSH Git URL for a remote repository path."""
-    normalized_path = (
-        repo_path.replace("\\", "/") if remote_os == "windows" else repo_path
-    )
+    if remote_os == "windows":
+        normalized_path = repo_path.replace("\\", "/")
+        return f"{user}@{host}:{normalized_path}"
+
+    normalized_path = repo_path
     quoted_path = quote(normalized_path, safe="/~:")
-    if remote_os == "windows" and not quoted_path.startswith("/"):
-        quoted_path = f"/{quoted_path}"
     return f"ssh://{user}@{host}{quoted_path}"
 
 
+def git_ssh_environment(
+    remote_os: RemoteOS, env: Mapping[str, str] | None = None
+) -> Mapping[str, str] | None:
+    """Return environment overrides for local Git SSH transport."""
+    if remote_os != "windows":
+        return env
+
+    git_env = dict(env or {})
+    if existing_command := git_env.get("GIT_SSH_COMMAND"):
+        git_env["GIT_SSH_SYNC_BASE_SSH_COMMAND"] = existing_command
+    git_env["GIT_SSH_COMMAND"] = (
+        f"{shlex.quote(sys.executable)} -m git_ssh_sync.windows_git_ssh"
+    )
+    return git_env
+
+
 def remote_parent(path: str, remote_os: RemoteOS) -> str:
     """Return the parent directory using the remote operating system's path rules."""
     if remote_os == "windows":
@@ -237,6 +256,23 @@ def remote_mkdir(
     return run_ssh(host, ["mkdir", "-p", path], user=user)
 
 
+def remote_remove(
+    host: str,
+    path: str,
+    *,
+    user: str,
+    remote_os: RemoteOS,
+) -> CommandResult:
+    """Remove a remote path recursively if it exists."""
+    if remote_os == "windows":
+        script = (
+            "Remove-Item -LiteralPath "
+            f"{_powershell_quote(path)} -Recurse -Force -ErrorAction SilentlyContinue"
+        )
+        return run_powershell(host, script, user=user, check=False)
+    return run_ssh(host, ["rm", "-rf", "--", path], user=user, check=False)
+
+
 def remote_command_exists(
     host: str,
     command: str,

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/status.py

@@ -134,7 +134,10 @@ def inspect_project_status(project: str, project_config: ProjectConfig) -> Statu
         host=dev_host, user=dev_user, repo_path=dev_work_path, remote_os=dev_os
     )
     git.fetch(
-        dev_repo_url, [f"refs/heads/{branch}:refs/remotes/dev/{branch}"], cwd=local_path
+        dev_repo_url,
+        [f"refs/heads/{branch}:refs/remotes/dev/{branch}"],
+        cwd=local_path,
+        env=ssh.git_ssh_environment(dev_os),
     )
 
     origin_ref = f"origin/{branch}"

{git_ssh_sync-0.3.0 → git_ssh_sync-0.4.0}/src/git_ssh_sync/sync.py

@@ -123,6 +123,7 @@ def _push_origin_branch_to_cache(
         remote_cache,
         [f"refs/remotes/origin/{branch}:refs/heads/{branch}"],
         cwd=local_path,
+        env=ssh.git_ssh_environment(project_config.dev.os),
     )
 
 
@@ -239,6 +240,7 @@ def _fetch_dev_branch_to_local(
         _work_url(project_config),
         [f"refs/heads/{branch}:refs/remotes/dev/{branch}"],
         cwd=local_path,
+        env=ssh.git_ssh_environment(project_config.dev.os),
     )
 
 

git_ssh_sync-0.4.0/src/git_ssh_sync/windows_git_ssh.py

@@ -0,0 +1,52 @@
+"""SSH command wrapper for Git protocol commands targeting Windows hosts."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+from base64 import b64encode
+
+GIT_PROTOCOL_COMMANDS = {"git-receive-pack", "git-upload-pack", "git-upload-archive"}
+
+
+def _powershell_quote(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _base_ssh_command() -> list[str]:
+    command = os.environ.get("GIT_SSH_SYNC_BASE_SSH_COMMAND", "ssh")
+    return shlex.split(command)
+
+
+def _powershell_command(remote_command: str) -> str | None:
+    try:
+        parts = shlex.split(remote_command, posix=True)
+    except ValueError:
+        return None
+    if len(parts) < 2 or parts[0] not in GIT_PROTOCOL_COMMANDS:
+        return None
+
+    script = "& " + " ".join(_powershell_quote(part) for part in parts)
+    encoded_script = b64encode(script.encode("utf-16le")).decode("ascii")
+    return (
+        "powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass "
+        f"-EncodedCommand {encoded_script}"
+    )
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    base_command = _base_ssh_command()
+    if len(args) < 2:
+        os.execvp(base_command[0], [*base_command, *args])
+
+    remote_command = _powershell_command(args[-1])
+    if remote_command is None:
+        os.execvp(base_command[0], [*base_command, *args])
+
+    os.execvp(base_command[0], [*base_command, *args[:-1], remote_command])
+
+
+if __name__ == "__main__":
+    main()

git_ssh_sync-0.3.0/src/git_ssh_sync/clone.py

@@ -1,113 +0,0 @@
-"""Project clone workflow."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from git_ssh_sync import git, ssh
-from git_ssh_sync.config import get_project, load_config
-from git_ssh_sync.errors import CommandExecutionError
-
-
-class CloneError(RuntimeError):
-    """Raised when the clone workflow would overwrite existing data."""
-
-
-def _ensure_local_missing(path: Path) -> None:
-    if path.exists():
-        raise CloneError(f"[local] path already exists: {path}")
-
-
-def _ensure_remote_missing(
-    *, host: str, user: str, path: str, remote_os: ssh.RemoteOS
-) -> None:
-    result = ssh.remote_path_exists(
-        host, path, user=user, remote_os=remote_os, path_type="any"
-    )
-    if result.returncode == 0:
-        raise CloneError(f"[{result.environment}] path already exists: {path}")
-    if result.returncode == 1:
-        return
-    raise CommandExecutionError(
-        environment=result.environment,
-        command=result.command,
-        returncode=result.returncode,
-        cwd=result.cwd,
-        stdout=result.stdout,
-        stderr=result.stderr,
-    )
-
-
-def _local_current_branch(local_path: Path) -> str:
-    result = git.run_git(["branch", "--show-current"], cwd=local_path)
-    branch = result.stdout.strip()
-    if not branch:
-        raise CloneError("Could not determine the cloned repository's current branch.")
-    return branch
-
-
-def clone_project(project: str) -> None:
-    """Clone a configured project and initialize its development repositories."""
-    app_config = load_config()
-    project_config = get_project(app_config, project)
-
-    local_path = Path(project_config.local.repo_path)
-    dev_host = project_config.dev.host
-    dev_user = project_config.dev.user
-    dev_os = project_config.dev.os
-    cache_path = project_config.dev.cache_path
-    work_path = project_config.dev.work_path
-
-    _ensure_local_missing(local_path)
-    _ensure_remote_missing(
-        host=dev_host, user=dev_user, path=cache_path, remote_os=dev_os
-    )
-    _ensure_remote_missing(
-        host=dev_host, user=dev_user, path=work_path, remote_os=dev_os
-    )
-
-    local_path.parent.mkdir(parents=True, exist_ok=True)
-    git.run_git(["clone", project_config.origin, str(local_path)])
-    git.fetch("origin", cwd=local_path)
-    branch = _local_current_branch(local_path)
-
-    ssh.remote_mkdir(
-        dev_host, ssh.remote_parent(cache_path, dev_os), user=dev_user, remote_os=dev_os
-    )
-    ssh.run_remote_command(
-        dev_host,
-        ["git", "init", "--bare", cache_path],
-        user=dev_user,
-        remote_os=dev_os,
-    )
-
-    remote_cache = ssh.remote_git_url(
-        host=dev_host, user=dev_user, repo_path=cache_path, remote_os=dev_os
-    )
-    git.push(
-        remote_cache,
-        [f"refs/remotes/origin/{branch}:refs/heads/{branch}"],
-        cwd=local_path,
-    )
-    if project_config.options.sync_tags:
-        git.push(remote_cache, ["--tags"], cwd=local_path)
-
-    ssh.remote_mkdir(
-        dev_host, ssh.remote_parent(work_path, dev_os), user=dev_user, remote_os=dev_os
-    )
-    ssh.run_remote_command(
-        dev_host,
-        ["git", "clone", cache_path, work_path],
-        user=dev_user,
-        remote_os=dev_os,
-    )
-    ssh.run_remote_git(
-        dev_host,
-        work_path,
-        ["remote", "rename", "origin", "gitsync"],
-        user=dev_user,
-        remote_os=dev_os,
-    )
-    ssh.run_remote_git(
-        dev_host, work_path, ["switch", branch], user=dev_user, remote_os=dev_os
-    )