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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: git-ssh-sync
-Version: 0.1.0
+Version: 0.3.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
@@ -21,6 +21,8 @@ Description-Content-Type: text/markdown
 
 `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 tool is designed for niche environments where outbound network access is restricted, such as high-security enterprises and projects that only allow limited inbound communication (e.g., SSH, RDP).
+
 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
@@ -88,8 +90,21 @@ Key parameters:
 - `--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-os`: Development environment OS, either `posix` or `windows` (default: `posix`)
 - `--dev-path`: Path to the work repository on the development environment
 
+For a Windows development environment, specify `--dev-os windows` and use Windows
+paths. Windows SSH commands are executed through PowerShell.
+
+```powershell
+git-ssh-sync init myproject `
+  --origin git@github.com:example/myproject.git `
+  --dev-host devserver `
+  --dev-user user `
+  --dev-os windows `
+  --dev-path C:\Users\user\work\myproject
+```
+
 For `--origin`, specify a remote URL that can be used with `git clone` or `git fetch`. Main formats are:
 
 ```text
@@ -113,6 +128,29 @@ git-ssh-sync init myproject \
   --force
 ```
 
+You can inspect and maintain registered projects without opening the config file directly.
+
+```bash
+# List registered projects
+git-ssh-sync config list
+
+# Show all settings for one project
+git-ssh-sync config show myproject
+
+# Update selected settings
+git-ssh-sync config set myproject \
+  --origin git@github.com:example/myproject.git \
+  --dev-host devserver \
+  --dev-os posix \
+  --dev-path /home/user/work/myproject
+
+# Remove a project after confirmation
+git-ssh-sync config remove myproject
+
+# Remove a project without an interactive prompt
+git-ssh-sync config remove myproject --yes
+```
+
 ## Initial Workflow
 
 For the first time, execute configuration, clone to the development environment, and diagnostics in order.
@@ -137,6 +175,54 @@ Afterward, the work repository on the development environment can be used as a n
 
 `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.
 
+## Attaching Existing Repositories
+
+If the gateway repository, development work repository, or cache repository already
+exists, use `attach` instead of `clone`.
+
+```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 attach myproject --dry-run
+git-ssh-sync attach myproject
+git-ssh-sync doctor myproject
+```
+
+`attach` inspects the configured origin URL, current branch, development work
+tree state, bare cache repository, and `gitsync` remote. Before changing
+anything, it prints the operations it will apply. Use `--yes` for non-interactive
+execution after reviewing the plan.
+
+```bash
+git-ssh-sync attach myproject --yes
+```
+
+If only the `gitsync` remote or cache wiring is missing or mismatched, run
+`doctor --repair` to inspect and repair it through the same preflight checks.
+
+```bash
+git-ssh-sync doctor myproject --repair
+git-ssh-sync doctor myproject --repair --yes
+```
+
+After an interrupted `pull` or `push`, use `recover` as the recovery-oriented
+entry point. Without `--yes`, it diagnoses origin, gateway, cache, and work
+repository state and prints concrete next actions. With `--yes`, it applies only
+safe wiring repairs such as creating the cache repository, seeding the cache
+branch, or fixing the `gitsync` remote.
+
+```bash
+git-ssh-sync recover myproject
+git-ssh-sync recover myproject --yes
+```
+
+`attach` and `doctor --repair` do not commit, stash, merge, or rebase existing
+work. If the development work tree is dirty, or if a path is not a compatible Git
+repository, the command stops and prints the manual recovery action.
+
 ## 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.
@@ -164,6 +250,13 @@ 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.
 
+Use `--dry-run` to inspect the planned operations and preflight checks before changing refs:
+
+```bash
+git-ssh-sync pull myproject --dry-run
+git-ssh-sync push myproject --dry-run
+```
+
 ## Branch Switching Workflow
 
 To switch to an existing branch, execute `checkout` from the local machine.
@@ -180,6 +273,13 @@ To create a new branch, use `-b`. Use `--base` together to explicitly specify th
 git-ssh-sync checkout myproject -b feature/foo --base develop
 ```
 
+To preview a branch switch or branch creation without changing origin, cache, or work repo refs:
+
+```bash
+git-ssh-sync checkout myproject feature/foo --dry-run
+git-ssh-sync checkout myproject -b feature/foo --base develop --dry-run
+```
+
 Development environment:
 
 ```bash
@@ -213,6 +313,20 @@ To list existence status and ahead/behind for each branch, use `branch`.
 git-ssh-sync branch myproject
 ```
 
+To inspect the development work repo directly from the local machine, use the
+read-only `dev` commands.
+
+```bash
+git-ssh-sync dev status myproject
+git-ssh-sync dev diff myproject
+git-ssh-sync dev diff myproject --stat
+git-ssh-sync dev log myproject --max-count 5
+```
+
+These commands run `git status`, `git diff`, or `git log` on the development
+work repo over SSH. They do not update origin, the local gateway repo, the
+development cache repo, or the development work repo refs.
+
 ## Operational Rules
 
 When using `git-ssh-sync`, following these rules makes it easier to understand the state:
@@ -244,6 +358,12 @@ git-ssh-sync init myproject \
   --dev-user user \
   --dev-path /home/user/work/myproject
 
+# List registered project settings
+git-ssh-sync config list
+
+# Show registered project settings
+git-ssh-sync config show myproject
+
 # Initial clone
 git-ssh-sync clone myproject
 
@@ -253,6 +373,12 @@ git-ssh-sync status myproject
 # Check branch status
 git-ssh-sync branch myproject
 
+# Inspect development work repo status
+git-ssh-sync dev status myproject
+
+# Inspect development work repo diff
+git-ssh-sync dev diff myproject --stat
+
 # Reflect changes from origin to development environment
 git-ssh-sync pull myproject
 
@@ -267,8 +393,61 @@ git-ssh-sync checkout myproject -b feature/foo --base develop
 
 # Diagnostics
 git-ssh-sync doctor myproject
+
+# Diagnose and optionally repair after an interrupted sync
+git-ssh-sync recover myproject
+git-ssh-sync recover myproject --yes
+```
+
+## Logging
+
+`git-ssh-sync` supports detailed logging for troubleshooting and monitoring synchronization operations.
+
+### Log Levels
+
+By default, only warnings and errors are displayed. You can increase verbosity using the following options:
+
+- `--verbose`, `-v`: Enable INFO level logging (operation progress, Git/SSH commands)
+- `--debug`, `-d`: Enable DEBUG level logging (all debug information, command output, stack traces)
+
+### Log File Output
+
+Logs are automatically saved to `~/.cache/git-ssh-sync/logs/git-ssh-sync.log`. The log file contains all log levels (DEBUG and above) regardless of console output settings.
+
+You can specify a custom log file path using `--log-file`:
+
+```bash
+git-ssh-sync pull myproject --log-file /tmp/my-sync.log
 ```
 
+### Usage Examples
+
+```bash
+# Default (warnings and errors only)
+git-ssh-sync pull myproject
+
+# Verbose output (operation progress)
+git-ssh-sync pull myproject --verbose
+
+# Debug output (all details including command execution)
+git-ssh-sync pull myproject --debug
+
+# Verbose with custom log file
+git-ssh-sync push myproject --verbose --log-file /tmp/sync.log
+
+# Debug output for diagnostics
+git-ssh-sync doctor myproject --debug
+```
+
+### Log Content
+
+- **INFO**: Operation progress (pull/push/checkout), success messages
+- **DEBUG**: Git/SSH commands executed, return codes, stdout/stderr, working directories
+- **WARNING**: Recoverable issues (LFS, submodules detected)
+- **ERROR**: Failures, execution errors
+
+Logs are particularly useful when troubleshooting SSH connection issues, Git command failures, or understanding the synchronization flow.
+
 ## For Developers
 
 To develop this repository itself, install dependencies using `uv sync`.
@@ -277,6 +456,16 @@ To develop this repository itself, install dependencies using `uv sync`.
 uv sync
 ```
 
+To install from TestPyPI:
+
+```bash
+uv tool install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  --index-strategy unsafe-best-match \
+  git-ssh-sync
+```
+
 To execute the CLI during development, you can run it via `uv run`.
 
 ```bash

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

@@ -10,6 +10,8 @@
 
 `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 tool is designed for niche environments where outbound network access is restricted, such as high-security enterprises and projects that only allow limited inbound communication (e.g., SSH, RDP).
+
 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
@@ -77,8 +79,21 @@ Key parameters:
 - `--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-os`: Development environment OS, either `posix` or `windows` (default: `posix`)
 - `--dev-path`: Path to the work repository on the development environment
 
+For a Windows development environment, specify `--dev-os windows` and use Windows
+paths. Windows SSH commands are executed through PowerShell.
+
+```powershell
+git-ssh-sync init myproject `
+  --origin git@github.com:example/myproject.git `
+  --dev-host devserver `
+  --dev-user user `
+  --dev-os windows `
+  --dev-path C:\Users\user\work\myproject
+```
+
 For `--origin`, specify a remote URL that can be used with `git clone` or `git fetch`. Main formats are:
 
 ```text
@@ -102,6 +117,29 @@ git-ssh-sync init myproject \
   --force
 ```
 
+You can inspect and maintain registered projects without opening the config file directly.
+
+```bash
+# List registered projects
+git-ssh-sync config list
+
+# Show all settings for one project
+git-ssh-sync config show myproject
+
+# Update selected settings
+git-ssh-sync config set myproject \
+  --origin git@github.com:example/myproject.git \
+  --dev-host devserver \
+  --dev-os posix \
+  --dev-path /home/user/work/myproject
+
+# Remove a project after confirmation
+git-ssh-sync config remove myproject
+
+# Remove a project without an interactive prompt
+git-ssh-sync config remove myproject --yes
+```
+
 ## Initial Workflow
 
 For the first time, execute configuration, clone to the development environment, and diagnostics in order.
@@ -126,6 +164,54 @@ Afterward, the work repository on the development environment can be used as a n
 
 `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.
 
+## Attaching Existing Repositories
+
+If the gateway repository, development work repository, or cache repository already
+exists, use `attach` instead of `clone`.
+
+```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 attach myproject --dry-run
+git-ssh-sync attach myproject
+git-ssh-sync doctor myproject
+```
+
+`attach` inspects the configured origin URL, current branch, development work
+tree state, bare cache repository, and `gitsync` remote. Before changing
+anything, it prints the operations it will apply. Use `--yes` for non-interactive
+execution after reviewing the plan.
+
+```bash
+git-ssh-sync attach myproject --yes
+```
+
+If only the `gitsync` remote or cache wiring is missing or mismatched, run
+`doctor --repair` to inspect and repair it through the same preflight checks.
+
+```bash
+git-ssh-sync doctor myproject --repair
+git-ssh-sync doctor myproject --repair --yes
+```
+
+After an interrupted `pull` or `push`, use `recover` as the recovery-oriented
+entry point. Without `--yes`, it diagnoses origin, gateway, cache, and work
+repository state and prints concrete next actions. With `--yes`, it applies only
+safe wiring repairs such as creating the cache repository, seeding the cache
+branch, or fixing the `gitsync` remote.
+
+```bash
+git-ssh-sync recover myproject
+git-ssh-sync recover myproject --yes
+```
+
+`attach` and `doctor --repair` do not commit, stash, merge, or rebase existing
+work. If the development work tree is dirty, or if a path is not a compatible Git
+repository, the command stops and prints the manual recovery action.
+
 ## 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.
@@ -153,6 +239,13 @@ 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.
 
+Use `--dry-run` to inspect the planned operations and preflight checks before changing refs:
+
+```bash
+git-ssh-sync pull myproject --dry-run
+git-ssh-sync push myproject --dry-run
+```
+
 ## Branch Switching Workflow
 
 To switch to an existing branch, execute `checkout` from the local machine.
@@ -169,6 +262,13 @@ To create a new branch, use `-b`. Use `--base` together to explicitly specify th
 git-ssh-sync checkout myproject -b feature/foo --base develop
 ```
 
+To preview a branch switch or branch creation without changing origin, cache, or work repo refs:
+
+```bash
+git-ssh-sync checkout myproject feature/foo --dry-run
+git-ssh-sync checkout myproject -b feature/foo --base develop --dry-run
+```
+
 Development environment:
 
 ```bash
@@ -202,6 +302,20 @@ To list existence status and ahead/behind for each branch, use `branch`.
 git-ssh-sync branch myproject
 ```
 
+To inspect the development work repo directly from the local machine, use the
+read-only `dev` commands.
+
+```bash
+git-ssh-sync dev status myproject
+git-ssh-sync dev diff myproject
+git-ssh-sync dev diff myproject --stat
+git-ssh-sync dev log myproject --max-count 5
+```
+
+These commands run `git status`, `git diff`, or `git log` on the development
+work repo over SSH. They do not update origin, the local gateway repo, the
+development cache repo, or the development work repo refs.
+
 ## Operational Rules
 
 When using `git-ssh-sync`, following these rules makes it easier to understand the state:
@@ -233,6 +347,12 @@ git-ssh-sync init myproject \
   --dev-user user \
   --dev-path /home/user/work/myproject
 
+# List registered project settings
+git-ssh-sync config list
+
+# Show registered project settings
+git-ssh-sync config show myproject
+
 # Initial clone
 git-ssh-sync clone myproject
 
@@ -242,6 +362,12 @@ git-ssh-sync status myproject
 # Check branch status
 git-ssh-sync branch myproject
 
+# Inspect development work repo status
+git-ssh-sync dev status myproject
+
+# Inspect development work repo diff
+git-ssh-sync dev diff myproject --stat
+
 # Reflect changes from origin to development environment
 git-ssh-sync pull myproject
 
@@ -256,8 +382,61 @@ git-ssh-sync checkout myproject -b feature/foo --base develop
 
 # Diagnostics
 git-ssh-sync doctor myproject
+
+# Diagnose and optionally repair after an interrupted sync
+git-ssh-sync recover myproject
+git-ssh-sync recover myproject --yes
+```
+
+## Logging
+
+`git-ssh-sync` supports detailed logging for troubleshooting and monitoring synchronization operations.
+
+### Log Levels
+
+By default, only warnings and errors are displayed. You can increase verbosity using the following options:
+
+- `--verbose`, `-v`: Enable INFO level logging (operation progress, Git/SSH commands)
+- `--debug`, `-d`: Enable DEBUG level logging (all debug information, command output, stack traces)
+
+### Log File Output
+
+Logs are automatically saved to `~/.cache/git-ssh-sync/logs/git-ssh-sync.log`. The log file contains all log levels (DEBUG and above) regardless of console output settings.
+
+You can specify a custom log file path using `--log-file`:
+
+```bash
+git-ssh-sync pull myproject --log-file /tmp/my-sync.log
 ```
 
+### Usage Examples
+
+```bash
+# Default (warnings and errors only)
+git-ssh-sync pull myproject
+
+# Verbose output (operation progress)
+git-ssh-sync pull myproject --verbose
+
+# Debug output (all details including command execution)
+git-ssh-sync pull myproject --debug
+
+# Verbose with custom log file
+git-ssh-sync push myproject --verbose --log-file /tmp/sync.log
+
+# Debug output for diagnostics
+git-ssh-sync doctor myproject --debug
+```
+
+### Log Content
+
+- **INFO**: Operation progress (pull/push/checkout), success messages
+- **DEBUG**: Git/SSH commands executed, return codes, stdout/stderr, working directories
+- **WARNING**: Recoverable issues (LFS, submodules detected)
+- **ERROR**: Failures, execution errors
+
+Logs are particularly useful when troubleshooting SSH connection issues, Git command failures, or understanding the synchronization flow.
+
 ## For Developers
 
 To develop this repository itself, install dependencies using `uv sync`.
@@ -266,6 +445,16 @@ To develop this repository itself, install dependencies using `uv sync`.
 uv sync
 ```
 
+To install from TestPyPI:
+
+```bash
+uv tool install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  --index-strategy unsafe-best-match \
+  git-ssh-sync
+```
+
 To execute the CLI during development, you can run it via `uv run`.
 
 ```bash

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

@@ -1,6 +1,6 @@
 [project]
 name = "git-ssh-sync"
-version = "0.1.0"
+version = "0.3.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.1.0 → git_ssh_sync-0.3.0}/src/git_ssh_sync/__init__.py

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