git-ssh-sync 0.1.0__py3-none-any.whl

git_ssh_sync/sync.py

@@ -0,0 +1,415 @@
+"""Safe pull and checkout workflows."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import quote
+
+from git_ssh_sync import git, ssh
+from git_ssh_sync.config import ProjectConfig, get_project, load_config
+from git_ssh_sync.console import console
+from git_ssh_sync.errors import CommandExecutionError
+
+
+class SyncError(RuntimeError):
+    """Raised when a sync workflow stops for a recoverable safety reason."""
+
+
+def _cache_url(*, host: str, user: str, cache_path: str) -> str:
+    quoted_path = quote(cache_path, safe="/~")
+    return f"ssh://{user}@{host}{quoted_path}"
+
+
+def _work_url(project_config: ProjectConfig) -> str:
+    quoted_path = quote(project_config.dev.work_path, safe="/~")
+    return f"ssh://{project_config.dev.user}@{project_config.dev.host}{quoted_path}"
+
+
+def _clean_output(value: str) -> str:
+    return value.strip()
+
+
+def _ensure_gateway_repo(path: Path) -> None:
+    if not path.exists():
+        raise SyncError(f"[local] gateway repository does not exist: {path}")
+
+
+def _origin_branch_exists(local_path: Path, branch: str) -> bool:
+    result = git.run_git(
+        ["show-ref", "--verify", "--quiet", f"refs/remotes/origin/{branch}"],
+        cwd=local_path,
+        check=False,
+    )
+    if result.returncode == 0:
+        return True
+    if result.returncode == 1:
+        return False
+    raise CommandExecutionError(
+        environment=result.environment,
+        command=result.command,
+        returncode=result.returncode,
+        cwd=result.cwd,
+        stdout=result.stdout,
+        stderr=result.stderr,
+    )
+
+
+def _ensure_origin_branch(local_path: Path, branch: str) -> None:
+    if not _origin_branch_exists(local_path, branch):
+        raise SyncError(
+            f"Origin branch does not exist: {branch}\n\n"
+            "Run on the gateway repository:\n\n"
+            "  git fetch origin"
+        )
+
+
+def _ensure_origin_branch_missing(project: str, local_path: Path, branch: str) -> None:
+    if _origin_branch_exists(local_path, branch):
+        raise SyncError(
+            f"Origin branch already exists: {branch}\n\n"
+            "Run checkout without --base to use the existing branch:\n\n"
+            f"  git-ssh-sync checkout {project} {branch}"
+        )
+
+
+def _create_origin_branch(local_path: Path, branch: str, base_branch: str) -> None:
+    git.push(
+        "origin",
+        [f"refs/remotes/origin/{base_branch}:refs/heads/{branch}"],
+        cwd=local_path,
+    )
+    git.fetch(
+        "origin", [f"refs/heads/{branch}:refs/remotes/origin/{branch}"], cwd=local_path
+    )
+
+
+def _push_origin_branch_to_cache(
+    project_config: ProjectConfig, local_path: Path, branch: str
+) -> None:
+    remote_cache = _cache_url(
+        host=project_config.dev.host,
+        user=project_config.dev.user,
+        cache_path=project_config.dev.cache_path,
+    )
+    git.push(
+        remote_cache,
+        [f"refs/remotes/origin/{branch}:refs/heads/{branch}"],
+        cwd=local_path,
+    )
+
+
+def _fetch_dev_branch(project_config: ProjectConfig, branch: str) -> None:
+    ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["fetch", "gitsync", f"refs/heads/{branch}:refs/remotes/gitsync/{branch}"],
+        user=project_config.dev.user,
+    )
+
+
+def _remote_branch_exists(project_config: ProjectConfig, branch: str) -> bool:
+    result = ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
+        user=project_config.dev.user,
+        check=False,
+    )
+    if result.returncode == 0:
+        return True
+    if result.returncode == 1:
+        return False
+    raise CommandExecutionError(
+        environment=result.environment,
+        command=result.command,
+        returncode=result.returncode,
+        cwd=result.cwd,
+        stdout=result.stdout,
+        stderr=result.stderr,
+    )
+
+
+def _remote_current_branch(project_config: ProjectConfig) -> str:
+    result = ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["branch", "--show-current"],
+        user=project_config.dev.user,
+    )
+    return _clean_output(result.stdout) or "(detached)"
+
+
+def _remote_gitsync_url(project_config: ProjectConfig) -> str:
+    result = ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["remote", "get-url", "gitsync"],
+        user=project_config.dev.user,
+    )
+    return _clean_output(result.stdout)
+
+
+def _ensure_gitsync_remote_matches(project: str, project_config: ProjectConfig) -> None:
+    actual_url = _remote_gitsync_url(project_config)
+    expected_url = project_config.dev.cache_path
+    if actual_url == expected_url:
+        return
+    raise SyncError(
+        "Development work repository gitsync remote does not match the configured cache path.\n\n"
+        f"Project:\n  {project}\n\n"
+        "Development:\n"
+        f"  host: {project_config.dev.host}\n"
+        f"  path: {project_config.dev.work_path}\n\n"
+        f"Configured cache path:\n  {expected_url}\n\n"
+        f"Actual gitsync remote:\n  {actual_url}\n\n"
+        "Update the work repo remote or recreate the project clone:\n\n"
+        f"  git -C {project_config.dev.work_path} remote set-url gitsync {expected_url}"
+    )
+
+
+def _require_remote_current_branch(project_config: ProjectConfig) -> str:
+    branch = _remote_current_branch(project_config)
+    if branch == "(detached)":
+        raise SyncError(
+            "Development work repository is in detached HEAD state.\n\n"
+            "Switch to a branch on the development environment or run:\n\n"
+            "  git-ssh-sync checkout <project> <branch>"
+        )
+    return branch
+
+
+def _remote_short_head(project_config: ProjectConfig) -> str:
+    result = ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["rev-parse", "--short", "HEAD"],
+        user=project_config.dev.user,
+    )
+    return _clean_output(result.stdout)
+
+
+def _remote_status(project_config: ProjectConfig) -> str:
+    result = ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["status", "--porcelain"],
+        user=project_config.dev.user,
+    )
+    return _clean_output(result.stdout)
+
+
+def _fetch_dev_branch_to_local(
+    project_config: ProjectConfig, local_path: Path, branch: str
+) -> None:
+    git.fetch(
+        _work_url(project_config),
+        [f"refs/heads/{branch}:refs/remotes/dev/{branch}"],
+        cwd=local_path,
+    )
+
+
+def _dirty_error(project: str, project_config: ProjectConfig) -> SyncError:
+    return SyncError(
+        "Error: Development working tree is dirty.\n\n"
+        f"Project:\n  {project}\n\n"
+        "Development:\n"
+        f"  host: {project_config.dev.host}\n"
+        f"  path: {project_config.dev.work_path}\n"
+        f"  branch: {_remote_current_branch(project_config)}\n"
+        f"  commit: {_remote_short_head(project_config)}\n\n"
+        "Commit or stash changes first."
+    )
+
+
+def _ensure_dev_clean(project: str, project_config: ProjectConfig) -> None:
+    if _remote_status(project_config):
+        raise _dirty_error(project, project_config)
+
+
+def _switch_to_branch(project_config: ProjectConfig, branch: str) -> None:
+    if _remote_branch_exists(project_config, branch):
+        ssh.run_remote_git(
+            project_config.dev.host,
+            project_config.dev.work_path,
+            ["switch", branch],
+            user=project_config.dev.user,
+        )
+        return
+
+    ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["switch", "--track", "-c", branch, f"gitsync/{branch}"],
+        user=project_config.dev.user,
+    )
+
+
+def _ensure_fast_forwardable(
+    project: str, project_config: ProjectConfig, branch: str
+) -> None:
+    result = ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        [
+            "merge-base",
+            "--is-ancestor",
+            f"refs/heads/{branch}",
+            f"refs/remotes/gitsync/{branch}",
+        ],
+        user=project_config.dev.user,
+        check=False,
+    )
+    if result.returncode == 0:
+        return
+    if result.returncode == 1:
+        current_branch = _remote_current_branch(project_config)
+        current_commit = _remote_short_head(project_config)
+        raise SyncError(
+            f"Cannot fast-forward {branch}.\n\n"
+            f"origin/{branch} and dev/{branch} have diverged.\n\n"
+            f"Project:\n  {project}\n\n"
+            "Development:\n"
+            f"  host: {project_config.dev.host}\n"
+            f"  path: {project_config.dev.work_path}\n"
+            f"  branch: {current_branch}\n"
+            f"  commit: {current_commit}\n\n"
+            "Resolve on the development environment:\n\n"
+            "  git fetch gitsync\n"
+            f"  git merge gitsync/{branch}\n\n"
+            "or:\n\n"
+            f"  git rebase gitsync/{branch}"
+        )
+    raise CommandExecutionError(
+        environment=result.environment,
+        command=result.command,
+        returncode=result.returncode,
+        cwd=result.cwd,
+        stdout=result.stdout,
+        stderr=result.stderr,
+    )
+
+
+def _ensure_pushable(
+    project: str, project_config: ProjectConfig, local_path: Path, branch: str
+) -> None:
+    result = git.run_git(
+        [
+            "merge-base",
+            "--is-ancestor",
+            f"refs/remotes/origin/{branch}",
+            f"refs/remotes/dev/{branch}",
+        ],
+        cwd=local_path,
+        check=False,
+    )
+    if result.returncode == 0:
+        return
+    if result.returncode == 1:
+        current_branch = _remote_current_branch(project_config)
+        current_commit = _remote_short_head(project_config)
+        raise SyncError(
+            f"Cannot push {branch}.\n\n"
+            f"origin/{branch} has commits that are not included in dev/{branch}.\n\n"
+            f"Project:\n  {project}\n\n"
+            "Development:\n"
+            f"  host: {project_config.dev.host}\n"
+            f"  path: {project_config.dev.work_path}\n"
+            f"  branch: {current_branch}\n"
+            f"  commit: {current_commit}\n\n"
+            "Run:\n\n"
+            f"  git-ssh-sync pull {project}\n\n"
+            "Then resolve the branch on the development environment before pushing again."
+        )
+    raise CommandExecutionError(
+        environment=result.environment,
+        command=result.command,
+        returncode=result.returncode,
+        cwd=result.cwd,
+        stdout=result.stdout,
+        stderr=result.stderr,
+    )
+
+
+def _load_project(project: str) -> ProjectConfig:
+    return get_project(load_config(), project)
+
+
+def pull_project(project: str) -> None:
+    """Fetch origin changes and fast-forward the current development branch."""
+    project_config = _load_project(project)
+    local_path = Path(project_config.local.repo_path)
+
+    _ensure_gateway_repo(local_path)
+    _ensure_gitsync_remote_matches(project, project_config)
+    selected_branch = _require_remote_current_branch(project_config)
+    console.print(f"Project: {project}")
+    console.print(f"Branch: {selected_branch}")
+    console.print("Direction: origin -> development")
+    git.fetch("origin", cwd=local_path)
+    _ensure_origin_branch(local_path, selected_branch)
+    _push_origin_branch_to_cache(project_config, local_path, selected_branch)
+    _fetch_dev_branch(project_config, selected_branch)
+
+    _ensure_fast_forwardable(project, project_config, selected_branch)
+    ssh.run_remote_git(
+        project_config.dev.host,
+        project_config.dev.work_path,
+        ["merge", "--ff-only", f"gitsync/{selected_branch}"],
+        user=project_config.dev.user,
+    )
+
+
+def checkout_project(
+    project: str,
+    branch: str,
+    *,
+    create: bool = False,
+    base_branch: str | None = None,
+) -> None:
+    """Switch the development repository to a branch from origin."""
+    project_config = _load_project(project)
+    local_path = Path(project_config.local.repo_path)
+
+    _ensure_gateway_repo(local_path)
+    _ensure_gitsync_remote_matches(project, project_config)
+    git.fetch("origin", cwd=local_path)
+    if create:
+        base = base_branch or _require_remote_current_branch(project_config)
+        _ensure_origin_branch(local_path, base)
+        _ensure_origin_branch_missing(project, local_path, branch)
+        _create_origin_branch(local_path, branch, base)
+    _ensure_origin_branch(local_path, branch)
+    _push_origin_branch_to_cache(project_config, local_path, branch)
+    _fetch_dev_branch(project_config, branch)
+    _ensure_dev_clean(project, project_config)
+    _switch_to_branch(project_config, branch)
+
+
+def push_project(project: str) -> None:
+    """Push current development branch commits to origin when it has not diverged."""
+    project_config = _load_project(project)
+    local_path = Path(project_config.local.repo_path)
+
+    _ensure_gateway_repo(local_path)
+    _ensure_gitsync_remote_matches(project, project_config)
+    selected_branch = _require_remote_current_branch(project_config)
+    console.print(f"Project: {project}")
+    console.print(f"Branch: {selected_branch}")
+    console.print("Direction: development -> origin")
+    git.fetch("origin", cwd=local_path)
+    _ensure_origin_branch(local_path, selected_branch)
+    _fetch_dev_branch_to_local(project_config, local_path, selected_branch)
+    _ensure_pushable(project, project_config, local_path, selected_branch)
+
+    try:
+        git.push(
+            "origin",
+            [f"refs/remotes/dev/{selected_branch}:refs/heads/{selected_branch}"],
+            cwd=local_path,
+        )
+    except CommandExecutionError as error:
+        raise SyncError(
+            f"Failed to push {selected_branch} to origin.\n\n"
+            f"Project:\n  {project}\n\n"
+            f"Origin push failed:\n{error}"
+        ) from error

git_ssh_sync-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.3
+Name: git-ssh-sync
+Version: 0.1.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
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+[![日本語](https://img.shields.io/badge/lang-日本語-blue)](README.ja.md) [![English](https://img.shields.io/badge/lang-English-brightgreen)](README.md)
+
+# git-ssh-sync
+
+[![CI](https://github.com/devgamesan/git-ssh-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/devgamesan/git-ssh-sync/actions/workflows/ci.yml)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.12+-blue.svg)
+![Release](https://img.shields.io/github/v/release/devgamesan/git-ssh-sync)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+`git-ssh-sync` is a CLI tool for synchronizing Git commits created in a development environment that cannot directly access GitHub/GitLab to external Git services via a local machine.
+
+This is not a file synchronization tool. It synchronizes Git objects and branches. Source editing, building, testing, and committing are performed in the development environment, while communication with GitHub/GitLab is handled by the local machine.
+
+## Prerequisites
+
+`git-ssh-sync` assumes the following configuration:
+
+```text
+GitHub / GitLab
+    ↑↓
+Local machine
+    ↑↓ SSH
+Development environment
+```
+
+Local machine:
+
+- Can access GitHub / GitLab
+- Can SSH to the development environment
+- Has `git` and `uv` available
+- Uses `git-ssh-sync` for commit synchronization, status checks, and diagnostics between GitHub/GitLab and the development environment
+
+Development environment:
+
+- Can be accessed via SSH from the local machine
+- Cannot directly access GitHub / GitLab from the development environment
+- Has `git` available
+- Performs source editing, building, testing, and committing
+- Synchronizes with GitHub/GitLab via the local machine
+
+## Installation
+
+For normal use, install on your local machine using `uv tool install`.
+
+```bash
+uv tool install git-ssh-sync
+```
+
+For unreleased versions or the latest repository version, install directly from GitHub.
+
+```bash
+uv tool install git+https://github.com/devgamesan/git-ssh-sync.git
+```
+
+After installation, verify that the command can be executed.
+
+```bash
+git-ssh-sync --help
+```
+
+## Configuration
+
+First, register the project you want to synchronize.
+
+```bash
+git-ssh-sync init myproject \
+  --origin git@github.com:example/myproject.git \
+  --dev-host devserver \
+  --dev-user user \
+  --dev-path /home/user/work/myproject
+```
+
+Key parameters:
+
+- `myproject`: Project name for `git-ssh-sync`
+- `--origin`: Repository URL on the GitHub / GitLab side
+- `--dev-host`: SSH host of the development environment
+- `--dev-user`: SSH user of the development environment
+- `--dev-path`: Path to the work repository on the development environment
+
+For `--origin`, specify a remote URL that can be used with `git clone` or `git fetch`. Main formats are:
+
+```text
+git@github.com:example/myproject.git
+git@gitlab.com:example/myproject.git
+ssh://git@github.com/example/myproject.git
+https://github.com/example/myproject.git
+https://gitlab.com/example/myproject.git
+```
+
+When using SSH format, prepare SSH keys and authentication settings for connecting to GitHub/GitLab on the local machine. The development environment does not connect directly to GitHub/GitLab.
+
+To overwrite existing configuration, use `--force`.
+
+```bash
+git-ssh-sync init myproject \
+  --origin git@github.com:example/myproject.git \
+  --dev-host devserver \
+  --dev-user user \
+  --dev-path /home/user/work/myproject \
+  --force
+```
+
+## Initial Workflow
+
+For the first time, execute configuration, clone to the development environment, and diagnostics in order.
+
+```bash
+git-ssh-sync init myproject \
+  --origin git@github.com:example/myproject.git \
+  --dev-host devserver \
+  --dev-user user \
+  --dev-path /home/user/work/myproject
+git-ssh-sync clone myproject
+git-ssh-sync doctor myproject
+```
+
+`clone` creates a gateway repository on your local machine and deploys cache and work repositories on the development environment.
+
+- Gateway repository: Relay repository on the local machine
+- Cache repository: Bare repository on the development environment
+- Work repository: Repository where actual editing, building, testing, and committing are performed on the development environment
+
+Afterward, the work repository on the development environment can be used as a normal Git repository.
+
+`doctor` checks the local environment, SSH connection, fetch/push permissions to origin, and repository deployment on the development environment. Run this not only for the first time but also when synchronization is not working properly.
+
+## Daily Development Workflow
+
+For daily development, `pull` from the local machine before starting work, commit normally in the development environment, and finally `push` from the local machine.
+
+Local machine:
+
+```bash
+git-ssh-sync pull myproject
+```
+
+Development environment:
+
+```bash
+cd ~/work/myproject
+git status
+git add .
+git commit -m "Add feature"
+```
+
+Local machine:
+
+```bash
+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.
+
+## Branch Switching Workflow
+
+To switch to an existing branch, execute `checkout` from the local machine.
+
+Local machine:
+
+```bash
+git-ssh-sync checkout myproject feature/foo
+```
+
+To create a new branch, use `-b`. Use `--base` together to explicitly specify the starting point.
+
+```bash
+git-ssh-sync checkout myproject -b feature/foo --base develop
+```
+
+Development environment:
+
+```bash
+cd ~/work/myproject
+git status
+git add .
+git commit -m "Implement foo"
+```
+
+Local machine:
+
+```bash
+git-ssh-sync push myproject
+```
+
+`checkout -b feature/foo --base develop` creates `feature/foo` on origin based on `develop` from origin and switches the work repository on the development environment to that branch. If `--base` is omitted, the current branch of the work repository on the development environment is used as the starting point. If a branch with the same name already exists on origin, switch to the existing branch without `-b`.
+
+## Status Check
+
+Use `status` to check synchronization status.
+
+```bash
+git-ssh-sync status myproject
+```
+
+`status` displays the ahead/behind status between origin and the development environment, and the working tree status for the current branch of the work repository. Follow the displayed recommendation and execute `pull` or `push` as necessary.
+
+To list existence status and ahead/behind for each branch, use `branch`.
+
+```bash
+git-ssh-sync branch myproject
+```
+
+## Operational Rules
+
+When using `git-ssh-sync`, following these rules makes it easier to understand the state:
+
+- `pull` on the local machine before starting work
+- Create commits in the development environment
+- `push` on the local machine when work is done
+- Check `status` when in doubt before/after synchronization
+- Run `doctor` when concerned about connections or repository deployment
+
+Uncommitted changes are not synchronized. If there are uncommitted changes in the working tree of the development environment, the changes themselves are not sent to the local machine or origin. Please `git add` and `git commit` changes you want to synchronize in the development environment.
+
+`pull` updates the development environment branch only when fast-forward is possible. If origin and the development environment have diverged, automatic merge or automatic rebase is not performed.
+
+`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.
+
+## Common Commands
+
+```bash
+# Display help
+git-ssh-sync --help
+
+# Register a project
+git-ssh-sync init myproject \
+  --origin git@github.com:example/myproject.git \
+  --dev-host devserver \
+  --dev-user user \
+  --dev-path /home/user/work/myproject
+
+# Initial clone
+git-ssh-sync clone myproject
+
+# Check synchronization status
+git-ssh-sync status myproject
+
+# Check branch status
+git-ssh-sync branch myproject
+
+# Reflect changes from origin to development environment
+git-ssh-sync pull myproject
+
+# Reflect commits from development environment to origin
+git-ssh-sync push myproject
+
+# Switch development environment branch
+git-ssh-sync checkout myproject feature/foo
+
+# Create and switch to new branch from base branch
+git-ssh-sync checkout myproject -b feature/foo --base develop
+
+# Diagnostics
+git-ssh-sync doctor myproject
+```
+
+## For Developers
+
+To develop this repository itself, install dependencies using `uv sync`.
+
+```bash
+uv sync
+```
+
+To execute the CLI during development, you can run it via `uv run`.
+
+```bash
+uv run git-ssh-sync --help
+```
+
+Tests are executed with the following command:
+
+```bash
+uv run pytest
+```
+
+## Related Documentation
+
+- [Specification](docs/spec.md)