cli/status(feat[detailed]): report branch divergence and update docs

Author: tony

docs/cli/list.md

@@ -130,12 +130,23 @@ $ vcspull list -f ~/projects/.vcspull.yaml
 
 ## Workspace filtering
 
-Filter repositories by workspace root (planned feature):
+Filter repositories by workspace root with `-w/--workspace/--workspace-root`:
 
 ```console
 $ vcspull list -w ~/code/
+• flask → /home/d/code/flask
+• requests → /home/d/code/requests
+```
+
+Globbing is supported, so you can target multiple related workspaces:
+
+```console
+$ vcspull list --workspace '*/work/*'
 ```
 
+The workspace filter combines with pattern filters and structured output flags,
+allowing you to export subsets of your configuration quickly.
+
 ## Color output
 
 Control colored output with `--color`:

docs/cli/status.md

@@ -23,9 +23,9 @@ Check the status of all configured repositories:
 
 ```console
 $ vcspull status
-• tiktoken → /home/d/study/ai/tiktoken (missing)
-• flask → /home/d/code/flask (exists, clean)
-• django → /home/d/code/django (exists, clean)
+✗ tiktoken: missing
+✓ flask: up to date
+✓ django: up to date
 
 Summary: 3 repositories, 2 exist, 1 missing
 ```
@@ -58,12 +58,16 @@ Show additional information with `--detailed` or `-d`:
 
 ```console
 $ vcspull status --detailed
-• flask → /home/d/code/flask
+✓ flask: up to date
   Path: /home/d/code/flask
-  Status: exists, git repository, clean
+  Branch: main
+  Ahead/Behind: 0/0
 ```
 
-This mode shows the full path and expanded status information.
+This mode shows the full path, active branch, and divergence counters (`ahead`
+and `behind`) relative to the tracked upstream. If the working tree has
+uncommitted changes the headline reports `dirty` and the JSON payloads set
+`clean` to `false`.
 
 ## JSON output
 
@@ -84,7 +88,10 @@ Output format:
     "workspace_root": "~/study/ai/",
     "exists": false,
     "is_git": false,
-    "clean": null
+    "clean": null,
+    "branch": null,
+    "ahead": null,
+    "behind": null
   },
   {
     "reason": "status",
@@ -93,7 +100,10 @@ Output format:
     "workspace_root": "~/code/",
     "exists": true,
     "is_git": true,
-    "clean": true
+    "clean": true,
+    "branch": "main",
+    "ahead": 0,
+    "behind": 0
   },
   {
     "reason": "summary",
@@ -113,7 +123,9 @@ Each status entry includes:
 - `workspace_root`: Configuration section this repo belongs to
 - `exists`: Whether the directory exists
 - `is_git`: Whether it's a Git repository
-- `clean`: Git working tree status (null if not a Git repo or doesn't exist)
+- `clean`: Git working tree status (`null` if not a git repo or missing)
+- `branch`: Current branch (when detailed information is available)
+- `ahead`, `behind`: Divergence counts relative to the upstream branch
 
 Filter with [jq]:
 

docs/cli/sync.md

@@ -41,21 +41,42 @@ Use `--dry-run` or `-n` to:
 Export sync operations as JSON for automation:
 
 ```console
-$ vcspull sync --json '*'
-```
-
-This is a planned feature that will output structured sync results including:
-- Repository names and paths
-- Sync status (cloned, updated, skipped, error)
-- Commit information
-- Error messages
+$ vcspull sync --dry-run --json '*'
+[
+  {
+    "reason": "sync",
+    "name": "flask",
+    "path": "/home/d/code/flask",
+    "workspace_root": "~/code/",
+    "status": "preview"
+  },
+  {
+    "reason": "summary",
+    "total": 3,
+    "synced": 0,
+    "previewed": 3,
+    "failed": 0
+  }
+]
+```
+
+Each event emitted during the run includes:
+
+- `reason`: `"sync"` for repository events, `"summary"` for the final summary
+- `name`, `path`, `workspace_root`: Repository metadata from your config
+- `status`: `"synced"`, `"preview"`, or `"error"` (with an `error` field)
+
+Use `--json` without `--dry-run` to capture actual sync executions—successful
+and failed repositories are emitted with their final state.
 
 ## NDJSON output
 
 Stream sync events line-by-line with `--ndjson`:
 
 ```console
-$ vcspull sync --ndjson '*'
+$ vcspull sync --dry-run --ndjson '*'
+{"reason":"sync","name":"flask","path":"/home/d/code/flask","workspace_root":"~/code/","status":"preview"}
+{"reason":"summary","total":3,"synced":0,"previewed":3,"failed":0}
 ```
 
 Each line is a JSON object representing a sync event, ideal for:

src/vcspull/cli/status.py

@@ -5,6 +5,7 @@
 import argparse
 import logging
 import pathlib
+import subprocess
 import typing as t
 
 from vcspull.config import filter_repos, find_config_files, load_configs
@@ -74,6 +75,23 @@ def create_status_subparser(parser: argparse.ArgumentParser) -> None:
     )
 
 
+def _run_git_command(
+    repo_path: pathlib.Path,
+    *args: str,
+) -> subprocess.CompletedProcess[str] | None:
+    """Execute a git command and return the completed process."""
+    try:
+        return subprocess.run(
+            ["git", *args],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
 def check_repo_status(repo: ConfigDict, detailed: bool = False) -> dict[str, t.Any]:
     """Check the status of a single repository.
 
@@ -100,6 +118,9 @@ def check_repo_status(repo: ConfigDict, detailed: bool = False) -> dict[str, t.A
         "exists": False,
         "is_git": False,
         "clean": None,
+        "branch": None,
+        "ahead": None,
+        "behind": None,
     }
 
     # Check if repository exists
@@ -110,12 +131,52 @@ def check_repo_status(repo: ConfigDict, detailed: bool = False) -> dict[str, t.A
         if (repo_path / ".git").exists():
             status["is_git"] = True
 
-            # TODO: Add more detailed status checks when detailed=True
-            # - Check if clean/dirty
-            # - Check if ahead/behind remote
-            # - Check current branch
-            # For now, just mark as clean if .git exists
-            status["clean"] = True
+            porcelain_result = _run_git_command(repo_path, "status", "--porcelain")
+            if porcelain_result is not None:
+                status["clean"] = porcelain_result.stdout.strip() == ""
+            else:
+                status["clean"] = True
+
+            if detailed:
+                branch_result = _run_git_command(
+                    repo_path,
+                    "rev-parse",
+                    "--abbrev-ref",
+                    "HEAD",
+                )
+                if branch_result is not None:
+                    status["branch"] = branch_result.stdout.strip()
+
+                ahead = 0
+                behind = 0
+                upstream_available = _run_git_command(
+                    repo_path,
+                    "rev-parse",
+                    "--abbrev-ref",
+                    "@{upstream}",
+                )
+                if upstream_available is not None:
+                    counts = _run_git_command(
+                        repo_path,
+                        "rev-list",
+                        "--left-right",
+                        "--count",
+                        "@{upstream}...HEAD",
+                    )
+                    if counts is not None:
+                        parts = counts.stdout.strip().split()
+                        if len(parts) == 2:
+                            behind, ahead = (int(parts[0]), int(parts[1]))
+                status["ahead"] = ahead
+                status["behind"] = behind
+
+                # Maintain clean flag if porcelain failed
+                if status["clean"] is None:
+                    status["clean"] = True
+            else:
+                status["branch"] = None
+                status["ahead"] = None
+                status["behind"] = None
 
     return status
 
@@ -249,10 +310,32 @@ def _format_status_line(
         status_color = colors.error(message)
     elif status["is_git"]:
         symbol = colors.success("✓")
-        message = "up to date" if status["clean"] else "dirty"
-        status_color = (
-            colors.success(message) if status["clean"] else colors.warning(message)
-        )
+        clean_state = status["clean"]
+        ahead = status.get("ahead")
+        behind = status.get("behind")
+        if clean_state is False:
+            message = "dirty"
+            status_color = colors.warning(message)
+        elif isinstance(ahead, int) and isinstance(behind, int):
+            if ahead > 0 and behind > 0:
+                message = f"diverged (ahead {ahead}, behind {behind})"
+                status_color = colors.warning(message)
+            elif ahead > 0:
+                message = f"ahead by {ahead}"
+                status_color = colors.info(message)
+            elif behind > 0:
+                message = f"behind by {behind}"
+                status_color = colors.warning(message)
+            else:
+                message = "up to date"
+                status_color = colors.success(message)
+        else:
+            message = "up to date" if clean_state else "dirty"
+            status_color = (
+                colors.success(message)
+                if clean_state in {True, None}
+                else colors.warning(message)
+            )
     else:
         symbol = colors.warning("⚠")
         message = "not a git repo"
@@ -262,3 +345,10 @@ def _format_status_line(
 
     if detailed:
         formatter.emit_text(f"  {colors.muted('Path:')} {status['path']}")
+        branch = status.get("branch")
+        if branch:
+            formatter.emit_text(f"  {colors.muted('Branch:')} {branch}")
+        ahead = status.get("ahead")
+        behind = status.get("behind")
+        if isinstance(ahead, int) and isinstance(behind, int):
+            formatter.emit_text(f"  {colors.muted('Ahead/Behind:')} {ahead}/{behind}")