tlc-shared-docs 0.1.0__tar.gz

tlc_shared_docs-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.3
+Name: tlc-shared-docs
+Version: 0.1.0
+Summary: Share documentation files between Git repositories
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: gitpython (>=3.1,<4.0)
+Description-Content-Type: text/markdown
+
+# tlc-shared-docs
+
+Share documentation files between Git repositories. Pull files from a remote repo into your local docs tree, or push local files back — all configured through a single `shared.json`.
+
+## Installation
+
+```bash
+pip install tlc-shared-docs
+```
+
+## Quick Start
+
+### 1. Create the config
+
+Create `docs/source/shared/shared.json` in your project:
+
+```json
+{
+  "source_repo": {
+    "url": "https://github.com/your-org/shared-docs.git",
+    "branch": "main"
+  },
+  "shared_files": [
+    {
+      "remote_path": "guides/getting-started.md",
+      "local_path": "getting-started.md",
+      "action": "get"
+    },
+    {
+      "remote_path": "guides/api-reference.md",
+      "local_path": "api-reference.md",
+      "action": "push"
+    }
+  ]
+}
+```
+
+### 2. Pull shared files
+
+```bash
+tlc-shared-docs get
+```
+
+This fetches every file with `"action": "get"` from the remote repo and saves it locally.
+
+### 3. Push local files
+
+```bash
+tlc-shared-docs push
+```
+
+This pushes every file with `"action": "push"` to the remote repo. If a remote file has changed since you last pulled, the command aborts with a conflict warning. Use `--force` to overwrite:
+
+```bash
+tlc-shared-docs push --force
+```
+
+### 4. Preview changes
+
+Both commands support `--dry-run`:
+
+```bash
+tlc-shared-docs get --dry-run
+tlc-shared-docs push --dry-run
+```
+
+## Configuration Reference
+
+### `shared.json`
+
+| Field | Description |
+|---|---|
+| `source_repo.url` | Git clone URL for the shared repo |
+| `source_repo.branch` | Branch to pull from / push to (default: `main`) |
+| `shared_files[].remote_path` | Path to the file in the remote repo (supports glob patterns for `get`) |
+| `shared_files[].local_path` | Local destination path (relative to `docs/source/shared/`) |
+| `shared_files[].action` | `get` (pull from remote) or `push` (push to remote). Default: `get` |
+
+### Wildcard / glob patterns
+
+The `remote_path` field supports glob patterns for `get` actions, allowing you to fetch multiple files with a single entry:
+
+```json
+{
+  "remote_path": "stories/**/*",
+  "local_path": "stories",
+  "action": "get"
+}
+```
+
+Supported patterns:
+- `*` — matches any file in a single directory (e.g., `docs/*.md`)
+- `**/*` — matches files recursively across directories (e.g., `stories/**/*`)
+- `?` — matches a single character (e.g., `chapter?.md`)
+- `[seq]` — matches any character in the set (e.g., `file[0-9].txt`)
+
+When using globs, `local_path` acts as the **destination directory**. Matched files preserve their directory structure relative to the non-glob prefix of the pattern. For example:
+
+| Pattern | Matched remote file | `local_path` | Written to |
+|---|---|---|---|
+| `stories/**/*` | `stories/ch1/intro.md` | `mystories` | `mystories/ch1/intro.md` |
+| `Global/*.gitignore` | `Global/Vim.gitignore` | `ignores` | `ignores/Vim.gitignore` |
+| `*.md` | `README.md` | `docs` | `docs/README.md` |
+
+### Local path resolution
+
+- **Relative paths** (e.g., `guide.md`) resolve relative to `docs/source/shared/`.
+- **Absolute paths** (starting with `/`, e.g., `/src/docs/guide.md`) resolve relative to the project root.
+
+### Git ignore
+
+On first run, `tlc-shared-docs get` creates `docs/source/shared/` with a `.gitignore` that tracks only `shared.json` — all fetched files are ignored so they don't bloat your repo.
+
+The auto-generated `docs/source/shared/.gitignore` contains:
+
+```gitignore
+# Auto-generated by tlc-shared-docs
+# Ignore all fetched shared files; only track the config
+*
+!.gitignore
+!shared.json
+```
+
+This means:
+- `shared.json` is committed to your repo (so teammates share the same config)
+- All fetched/pushed doc files are ignored locally
+- The `.gitignore` itself is also tracked
+
+## Requirements
+
+- Python 3.9+
+- Git installed and on `PATH`
+- Valid Git credentials for the source repo
+

tlc_shared_docs-0.1.0/README.md

@@ -0,0 +1,133 @@
+# tlc-shared-docs
+
+Share documentation files between Git repositories. Pull files from a remote repo into your local docs tree, or push local files back — all configured through a single `shared.json`.
+
+## Installation
+
+```bash
+pip install tlc-shared-docs
+```
+
+## Quick Start
+
+### 1. Create the config
+
+Create `docs/source/shared/shared.json` in your project:
+
+```json
+{
+  "source_repo": {
+    "url": "https://github.com/your-org/shared-docs.git",
+    "branch": "main"
+  },
+  "shared_files": [
+    {
+      "remote_path": "guides/getting-started.md",
+      "local_path": "getting-started.md",
+      "action": "get"
+    },
+    {
+      "remote_path": "guides/api-reference.md",
+      "local_path": "api-reference.md",
+      "action": "push"
+    }
+  ]
+}
+```
+
+### 2. Pull shared files
+
+```bash
+tlc-shared-docs get
+```
+
+This fetches every file with `"action": "get"` from the remote repo and saves it locally.
+
+### 3. Push local files
+
+```bash
+tlc-shared-docs push
+```
+
+This pushes every file with `"action": "push"` to the remote repo. If a remote file has changed since you last pulled, the command aborts with a conflict warning. Use `--force` to overwrite:
+
+```bash
+tlc-shared-docs push --force
+```
+
+### 4. Preview changes
+
+Both commands support `--dry-run`:
+
+```bash
+tlc-shared-docs get --dry-run
+tlc-shared-docs push --dry-run
+```
+
+## Configuration Reference
+
+### `shared.json`
+
+| Field | Description |
+|---|---|
+| `source_repo.url` | Git clone URL for the shared repo |
+| `source_repo.branch` | Branch to pull from / push to (default: `main`) |
+| `shared_files[].remote_path` | Path to the file in the remote repo (supports glob patterns for `get`) |
+| `shared_files[].local_path` | Local destination path (relative to `docs/source/shared/`) |
+| `shared_files[].action` | `get` (pull from remote) or `push` (push to remote). Default: `get` |
+
+### Wildcard / glob patterns
+
+The `remote_path` field supports glob patterns for `get` actions, allowing you to fetch multiple files with a single entry:
+
+```json
+{
+  "remote_path": "stories/**/*",
+  "local_path": "stories",
+  "action": "get"
+}
+```
+
+Supported patterns:
+- `*` — matches any file in a single directory (e.g., `docs/*.md`)
+- `**/*` — matches files recursively across directories (e.g., `stories/**/*`)
+- `?` — matches a single character (e.g., `chapter?.md`)
+- `[seq]` — matches any character in the set (e.g., `file[0-9].txt`)
+
+When using globs, `local_path` acts as the **destination directory**. Matched files preserve their directory structure relative to the non-glob prefix of the pattern. For example:
+
+| Pattern | Matched remote file | `local_path` | Written to |
+|---|---|---|---|
+| `stories/**/*` | `stories/ch1/intro.md` | `mystories` | `mystories/ch1/intro.md` |
+| `Global/*.gitignore` | `Global/Vim.gitignore` | `ignores` | `ignores/Vim.gitignore` |
+| `*.md` | `README.md` | `docs` | `docs/README.md` |
+
+### Local path resolution
+
+- **Relative paths** (e.g., `guide.md`) resolve relative to `docs/source/shared/`.
+- **Absolute paths** (starting with `/`, e.g., `/src/docs/guide.md`) resolve relative to the project root.
+
+### Git ignore
+
+On first run, `tlc-shared-docs get` creates `docs/source/shared/` with a `.gitignore` that tracks only `shared.json` — all fetched files are ignored so they don't bloat your repo.
+
+The auto-generated `docs/source/shared/.gitignore` contains:
+
+```gitignore
+# Auto-generated by tlc-shared-docs
+# Ignore all fetched shared files; only track the config
+*
+!.gitignore
+!shared.json
+```
+
+This means:
+- `shared.json` is committed to your repo (so teammates share the same config)
+- All fetched/pushed doc files are ignored locally
+- The `.gitignore` itself is also tracked
+
+## Requirements
+
+- Python 3.9+
+- Git installed and on `PATH`
+- Valid Git credentials for the source repo

tlc_shared_docs-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "tlc-shared-docs"
+version = "0.1.0"
+description = "Share documentation files between Git repositories"
+authors = []
+readme = "README.md"
+packages = [{include = "tlc_shared_docs"}]
+
+[tool.poetry.scripts]
+tlc-shared-docs = "tlc_shared_docs.cli:main"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+gitpython = "^3.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: marks tests that hit real git repos (deselect with '-m \"not integration\"')",
+]

tlc_shared_docs-0.1.0/tlc_shared_docs/__init__.py

@@ -0,0 +1,3 @@
+"""tlc-shared-docs: Share documentation files between Git repositories."""
+
+__version__ = "0.1.0"

tlc_shared_docs-0.1.0/tlc_shared_docs/cli.py

@@ -0,0 +1,95 @@
+"""Command-line interface for tlc-shared-docs."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tlc_shared_docs import __version__
+from tlc_shared_docs.core import get_files, push_files
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tlc-shared-docs",
+        description="Share documentation files between Git repositories.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # --- get: pull shared files from the remote repo ---
+    get_parser = sub.add_parser("get", help="Pull shared files from the remote repo")
+    get_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without making changes",
+    )
+    get_parser.add_argument(
+        "--central",
+        metavar="URL",
+        default=None,
+        help="Use central control mode: fetch config from this repo URL",
+    )
+
+    # --- push: push local shared files to the remote repo ---
+    push_parser = sub.add_parser("push", help="Push local shared files to the remote repo")
+    push_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without making changes",
+    )
+    push_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force-push even if remote files have changed",
+    )
+    push_parser.add_argument(
+        "--central",
+        metavar="URL",
+        default=None,
+        help="Use central control mode: fetch config from this repo URL",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for the CLI. Parses arguments and dispatches to
+    the appropriate get/push handler."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        # Dispatch to the correct command handler
+        if args.command == "get":
+            messages = get_files(dry_run=args.dry_run, central_url=args.central)
+        elif args.command == "push":
+            messages = push_files(dry_run=args.dry_run, force=args.force, central_url=args.central)
+        else:
+            parser.print_help()
+            sys.exit(1)
+
+        for msg in messages:
+            print(msg)
+
+        # Exit with error code if there were conflicts or aborted operations
+        if any("CONFLICT" in m or "aborted" in m for m in messages):
+            sys.exit(1)
+
+    except FileNotFoundError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

tlc_shared_docs-0.1.0/tlc_shared_docs/config.py

@@ -0,0 +1,228 @@
+"""Configuration loading and project root detection."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+
+logger = logging.getLogger(__name__)
+
+SHARED_DIR = Path("docs") / "source" / "shared"
+CONFIG_FILE = "shared.json"
+HASHES_FILE = ".shared-hashes.json"
+CENTRAL_CONFIG_DIR = ".configs"
+
+# .gitignore content for the shared directory:
+# ignore everything except the config and .gitignore itself
+GITIGNORE_CONTENT = """\
+# Auto-generated by tlc-shared-docs
+# Ignore all fetched shared files; only track the config
+*
+!.gitignore
+!shared.json
+"""
+
+
+@dataclass
+class SourceRepo:
+    url: str
+    branch: str = "main"
+
+
+@dataclass
+class SharedFile:
+    remote_path: str
+    local_path: str
+    action: str = "get"  # "get" or "push"
+
+
+@dataclass
+class SharedConfig:
+    source_repo: SourceRepo
+    shared_files: List[SharedFile] = field(default_factory=list)
+    mode: str = "local"  # "local" or "central"
+
+
+_GLOB_CHARS = set("*?[")
+
+
+def is_glob(path: str) -> bool:
+    """Return True if *path* contains glob wildcard characters."""
+    return bool(_GLOB_CHARS & set(path))
+
+
+def glob_prefix(pattern: str) -> str:
+    """Return the non-glob prefix of a pattern.
+
+    For ``stories/**/*.md`` this returns ``stories``.
+    For ``*.md`` this returns an empty string.
+    """
+    # Split on forward slashes and collect segments until we hit a glob char
+    parts = pattern.replace("\\", "/").split("/")
+    prefix_parts = []
+    for p in parts:
+        if _GLOB_CHARS & set(p):
+            break
+        prefix_parts.append(p)
+    return "/".join(prefix_parts)
+
+
+def find_project_root(start: Optional[Path] = None) -> Path:
+    """Walk up from *start* (default: cwd) to find the nearest directory
+    that contains a ``.git`` folder, ``pyproject.toml``, or ``setup.py``."""
+    current = (start or Path.cwd()).resolve()
+    for directory in [current, *current.parents]:
+        if any((directory / marker).exists() for marker in (".git", "pyproject.toml", "setup.py")):
+            return directory
+    raise FileNotFoundError(
+        "Could not locate project root (no .git, pyproject.toml, or setup.py found)"
+    )
+
+
+def shared_dir_path(project_root: Path) -> Path:
+    """Return the shared directory path for the given project root."""
+    return project_root / SHARED_DIR
+
+
+def config_path(project_root: Path) -> Path:
+    """Return the shared.json config path for the given project root."""
+    return shared_dir_path(project_root) / CONFIG_FILE
+
+
+def hashes_path(project_root: Path) -> Path:
+    """Return the .shared-hashes.json path for the given project root."""
+    return shared_dir_path(project_root) / HASHES_FILE
+
+
+def ensure_shared_dir(project_root: Path) -> Path:
+    """Create the shared directory and its .gitignore if they don't exist."""
+    sdir = shared_dir_path(project_root)
+    sdir.mkdir(parents=True, exist_ok=True)
+
+    # Write .gitignore to keep fetched docs out of version control
+    gitignore = sdir / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text(GITIGNORE_CONTENT, encoding="utf-8")
+
+    return sdir
+
+
+def load_hashes(project_root: Path) -> dict[str, str]:
+    """Load the stored ``{remote_path: blob_sha}`` mapping.
+
+    Returns an empty dict if the file doesn't exist or is corrupt.
+    """
+    hp = hashes_path(project_root)
+    if not hp.exists():
+        return {}
+    try:
+        return json.loads(hp.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Failed to load hashes from %s: %s", hp, exc)
+        return {}
+
+
+def save_hashes(project_root: Path, hashes: dict[str, str]) -> None:
+    """Persist the ``{remote_path: blob_sha}`` mapping."""
+    hp = hashes_path(project_root)
+    hp.write_text(json.dumps(hashes, indent=2) + "\n", encoding="utf-8")
+
+
+def resolve_local_path(project_root: Path, local_path_str: str) -> Path:
+    """Resolve a local_path from shared.json.
+
+    - Paths starting with ``/`` are relative to the project root.
+    - All other paths are relative to the shared directory.
+    """
+    if local_path_str.startswith("/"):
+        return project_root / local_path_str.lstrip("/")
+    return shared_dir_path(project_root) / local_path_str
+
+
+def extract_org_repo(url: str) -> str:
+    """Extract ``org/repo`` from a Git URL (HTTPS or SSH).
+
+    Handles HTTPS, SSH shorthand (git@host:org/repo), and
+    full SSH URLs (ssh://git@host/org/repo). Strips trailing .git.
+    """
+    url = url.rstrip("/")
+    if url.endswith(".git"):
+        url = url[:-4]
+
+    # SSH shorthand: git@host:org/repo
+    m = re.match(r"^[\w.-]+@[\w.-]+:(.*)", url)
+    if m:
+        return m.group(1)
+
+    # HTTPS / SSH-URL: extract last two path segments
+    m = re.search(r"/([\w._-]+/[\w._-]+)$", url)
+    if m:
+        return m.group(1)
+
+    raise ValueError(f"Cannot extract org/repo from URL: {url}")
+
+
+def detect_repo_identity(project_root: Path) -> str:
+    """Detect the current repo's ``org/repo`` from its git remote origin."""
+    try:
+        from git import Repo
+        repo = Repo(project_root)
+        origin_url = repo.remotes.origin.url
+        return extract_org_repo(origin_url)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Cannot detect repo identity from {project_root}: {exc}"
+        ) from exc
+
+
+def central_config_path(org_repo: str) -> str:
+    """Return the path inside the source repo where the central config lives.
+
+    Example: ``org/repo`` -> ``.configs/org/repo.json``
+    """
+    return f"{CENTRAL_CONFIG_DIR}/{org_repo}.json"
+
+
+def parse_shared_files(data: dict) -> List[SharedFile]:
+    """Parse the shared_files list from a config dict."""
+    shared_files: List[SharedFile] = []
+    for entry in data.get("shared_files", []):
+        shared_files.append(
+            SharedFile(
+                remote_path=entry["remote_path"],
+                local_path=entry["local_path"],
+                action=entry.get("action", "get"),
+            )
+        )
+    return shared_files
+
+
+def load_config(project_root: Path) -> SharedConfig:
+    """Read and parse shared.json from the project's shared directory."""
+    cfg_path = config_path(project_root)
+    if not cfg_path.exists():
+        raise FileNotFoundError(f"Config not found: {cfg_path}")
+
+    data = json.loads(cfg_path.read_text(encoding="utf-8"))
+
+    # Parse the source repo connection info
+    repo_data = data["source_repo"]
+    source_repo = SourceRepo(
+        url=repo_data["url"],
+        branch=repo_data.get("branch", "main"),
+    )
+
+    mode = data.get("mode", "local")
+    shared_files = parse_shared_files(data)
+
+    return SharedConfig(
+        source_repo=source_repo,
+        shared_files=shared_files,
+        mode=mode,
+    )

tlc_shared_docs-0.1.0/tlc_shared_docs/core.py

@@ -0,0 +1,353 @@
+"""Core get/push logic."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+from pathlib import Path, PurePosixPath
+from types import ModuleType
+from typing import Callable, List, Optional
+
+import tlc_shared_docs.config as cfg
+import tlc_shared_docs.git_ops as git_ops
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_config(
+    root: Path,
+    conf: cfg.SharedConfig,
+    central_url: Optional[str] = None,
+    _detect_identity: Callable[[Path], str] = cfg.detect_repo_identity,
+    _fetch_file: Callable[..., bytes | None] = git_ops.fetch_single_file,
+) -> tuple[cfg.SharedConfig, List[str]]:
+    """If *conf* is in central mode, fetch the config from the source repo.
+
+    Returns ``(resolved_config, messages)``.
+    """
+    messages: List[str] = []
+
+    # CLI --central flag overrides the mode field in shared.json
+    source_url = central_url or (conf.source_repo.url if conf.mode == "central" else None)
+    if not source_url:
+        return conf, messages
+
+    # Detect this repo's org/repo identity from git remote
+    org_repo = _detect_identity(root)
+    config_path = cfg.central_config_path(org_repo)
+
+    # Build source repo settings, allowing CLI override of URL
+    source = cfg.SourceRepo(
+        url=source_url,
+        branch=conf.source_repo.branch if conf.source_repo.url == source_url else "main",
+    )
+    if central_url:
+        source = cfg.SourceRepo(url=central_url, branch=conf.source_repo.branch)
+
+    messages.append(f"Central mode: looking up {config_path} from {source.url}")
+
+    # Fetch the central config file from the shared docs repo
+    content = _fetch_file(source.url, source.branch, config_path)
+    if content is None:
+        raise FileNotFoundError(
+            f"Central config not found: {config_path} in {source.url} ({source.branch})"
+        )
+
+    central_data = json.loads(content.decode("utf-8"))
+    central_files = cfg.parse_shared_files(central_data)
+
+    # Warn if local config also had shared_files -- central wins
+    if conf.shared_files:
+        messages.append(
+            "WARNING: Local shared.json contains shared_files entries, "
+            "but central mode is active. Central config takes precedence."
+        )
+
+    return cfg.SharedConfig(
+        source_repo=source,
+        shared_files=central_files,
+        mode="central",
+    ), messages
+
+
+def _expand_get_entries(
+    conf: cfg.SharedConfig,
+    _list_remote: Callable[..., List[str]] = git_ops.list_remote_files,
+) -> tuple[List[cfg.SharedFile], List[str]]:
+    """Expand glob entries in the get list into concrete SharedFile objects.
+
+    Returns ``(expanded_files, messages)``.  Messages contain
+    warning info for glob resolution.
+    """
+    plain: List[cfg.SharedFile] = []
+    glob_entries: List[cfg.SharedFile] = []
+    messages: List[str] = []
+
+    # Separate plain paths from glob patterns
+    for sf in conf.shared_files:
+        if sf.action != "get":
+            continue
+        if cfg.is_glob(sf.remote_path):
+            glob_entries.append(sf)
+        else:
+            plain.append(sf)
+
+    # Resolve each glob pattern against the remote tree
+    for sf in glob_entries:
+        matched = _list_remote(
+            conf.source_repo.url,
+            conf.source_repo.branch,
+            sf.remote_path,
+        )
+        if not matched:
+            messages.append(f"WARNING: No remote files matched pattern: {sf.remote_path}")
+            continue
+
+        # Strip the non-glob prefix to preserve relative directory structure
+        prefix = cfg.glob_prefix(sf.remote_path)
+
+        for remote_path in matched:
+            # Build a local path that preserves directory structure under local_path
+            if prefix:
+                relative = remote_path[len(prefix):].lstrip("/")
+            else:
+                relative = remote_path
+            local_path = sf.local_path.rstrip("/") + "/" + relative
+
+            plain.append(cfg.SharedFile(
+                remote_path=remote_path,
+                local_path=local_path,
+                action="get",
+            ))
+
+        messages.append(
+            f"Glob '{sf.remote_path}' matched {len(matched)} file(s)"
+        )
+
+    return plain, messages
+
+
+def get_files(
+    project_root: Optional[Path] = None,
+    dry_run: bool = False,
+    central_url: Optional[str] = None,
+    _get_shas: Callable[..., dict[str, str]] = git_ops.get_remote_blob_shas,
+    _sparse_checkout: Callable[..., tuple] = git_ops.sparse_checkout_files,
+    _read_clone: Callable[..., bytes] = git_ops.read_file_from_clone,
+    _cleanup: Callable[..., None] = git_ops.cleanup,
+    _detect_identity: Callable[[Path], str] = cfg.detect_repo_identity,
+    _fetch_file: Callable[..., bytes | None] = git_ops.fetch_single_file,
+    _list_remote: Callable[..., List[str]] = git_ops.list_remote_files,
+) -> List[str]:
+    """Pull shared files from the remote repo.
+
+    Returns a list of human-readable status messages.
+    Dependency parameters (prefixed with _) allow test injection.
+    """
+    root = project_root or cfg.find_project_root()
+    cfg.ensure_shared_dir(root)
+    conf = cfg.load_config(root)
+
+    # Resolve central mode if applicable
+    conf, resolve_msgs = _resolve_config(
+        root, conf, central_url,
+        _detect_identity=_detect_identity,
+        _fetch_file=_fetch_file,
+    )
+    messages: List[str] = list(resolve_msgs)
+
+    # Expand any glob patterns into concrete file entries
+    files_to_get, expand_msgs = _expand_get_entries(conf, _list_remote=_list_remote)
+    messages.extend(expand_msgs)
+    if not files_to_get:
+        if not messages:
+            messages.append("No files with action=get found in shared.json")
+        return messages
+
+    remote_paths = [f.remote_path for f in files_to_get]
+
+    # Query remote blob SHAs to detect unchanged files (cheap, no blobs)
+    stored_hashes = cfg.load_hashes(root)
+    remote_shas = _get_shas(
+        conf.source_repo.url,
+        conf.source_repo.branch,
+        remote_paths,
+    )
+
+    # Filter: only fetch files whose SHA changed or that don't exist locally
+    files_needed: List[cfg.SharedFile] = []
+    for sf in files_to_get:
+        remote_sha = remote_shas.get(sf.remote_path)
+        if remote_sha is None:
+            # File doesn't exist on remote -- will produce a warning later
+            files_needed.append(sf)
+            continue
+        stored_sha = stored_hashes.get(sf.remote_path)
+        local = cfg.resolve_local_path(root, sf.local_path)
+        if stored_sha == remote_sha and local.exists():
+            messages.append(f"SKIP (unchanged): {sf.remote_path}")
+        else:
+            files_needed.append(sf)
+
+    # Dry-run: show what would be fetched, then exit
+    if dry_run:
+        messages.extend(f"[dry-run] Would get: {sf.remote_path}" for sf in files_needed)
+        return messages
+
+    if not files_needed:
+        messages.append("All files up to date.")
+        return messages
+
+    # Sparse-checkout only the files that actually changed
+    needed_paths = [sf.remote_path for sf in files_needed]
+    clone_dir, _repo = _sparse_checkout(
+        conf.source_repo.url,
+        conf.source_repo.branch,
+        needed_paths,
+    )
+
+    try:
+        for sf in files_needed:
+            try:
+                content = _read_clone(clone_dir, sf.remote_path)
+            except FileNotFoundError:
+                messages.append(f"WARNING: Remote file not found: {sf.remote_path}")
+                continue
+
+            # Write the fetched content to the local destination
+            local = cfg.resolve_local_path(root, sf.local_path)
+            local.parent.mkdir(parents=True, exist_ok=True)
+            local.write_bytes(content)
+            messages.append(f"OK: {sf.remote_path} -> {local.relative_to(root)}")
+
+            # Track the blob SHA so we can skip this file next time
+            sha = remote_shas.get(sf.remote_path)
+            if sha:
+                stored_hashes[sf.remote_path] = sha
+    finally:
+        _cleanup(clone_dir)
+
+    # Persist updated hashes for future runs
+    cfg.save_hashes(root, stored_hashes)
+
+    return messages
+
+
+def push_files(
+    project_root: Optional[Path] = None,
+    dry_run: bool = False,
+    force: bool = False,
+    central_url: Optional[str] = None,
+    _sparse_checkout: Callable[..., tuple] = git_ops.sparse_checkout_files,
+    _cleanup: Callable[..., None] = git_ops.cleanup,
+    _push: Callable[..., None] = git_ops.push_files,
+    _detect_identity: Callable[[Path], str] = cfg.detect_repo_identity,
+    _fetch_file: Callable[..., bytes | None] = git_ops.fetch_single_file,
+) -> List[str]:
+    """Push local shared files to the remote repo.
+
+    Returns a list of human-readable status messages.
+    Dependency parameters (prefixed with _) allow test injection.
+    """
+    root = project_root or cfg.find_project_root()
+    conf = cfg.load_config(root)
+
+    # Resolve central mode if applicable
+    conf, resolve_msgs = _resolve_config(
+        root, conf, central_url,
+        _detect_identity=_detect_identity,
+        _fetch_file=_fetch_file,
+    )
+    messages: List[str] = list(resolve_msgs)
+
+    files_to_push = [f for f in conf.shared_files if f.action == "push"]
+    if not files_to_push:
+        messages.append("No files with action=push found in shared.json")
+        return messages
+
+    if dry_run:
+        messages.extend(
+            f"[dry-run] Would push: {f.local_path} -> {f.remote_path}"
+            for f in files_to_push
+        )
+        return messages
+
+    # Build the file map: remote_path -> local file bytes
+    file_map: dict[str, bytes] = {}
+
+    for sf in files_to_push:
+        local = cfg.resolve_local_path(root, sf.local_path)
+        if not local.exists():
+            messages.append(f"WARNING: Local file not found, skipping: {local}")
+            continue
+        file_map[sf.remote_path] = local.read_bytes()
+
+    if not file_map:
+        messages.append("No files to push (all missing locally).")
+        return messages
+
+    # Conflict check: verify remote files haven't changed since last pull
+    if not force:
+        remote_paths = list(file_map.keys())
+        clone_dir = None
+        try:
+            clone_dir, _repo = _sparse_checkout(
+                conf.source_repo.url,
+                conf.source_repo.branch,
+                remote_paths,
+            )
+            for remote_path, local_content in file_map.items():
+                remote_file = clone_dir / remote_path
+                if remote_file.exists():
+                    remote_content = remote_file.read_bytes()
+                    if remote_content != local_content:
+                        messages.append(
+                            f"CONFLICT: {remote_path} differs on remote. "
+                            f"Use --force to overwrite."
+                        )
+            if any("CONFLICT" in m for m in messages):
+                messages.append("Push aborted due to conflicts. Use --force to overwrite.")
+                return messages
+        except git_ops.GitError as exc:
+            # If we can't fetch to check conflicts, let the push attempt
+            # handle the error -- log so it's not silently swallowed
+            logger.warning("Could not check remote for conflicts: %s", exc)
+        finally:
+            if clone_dir:
+                _cleanup(clone_dir)
+
+    # Build the commit message from the local repo identity
+    repo_name = _repo_name_from_root(root)
+    branch_name = _current_branch(root)
+    commit_msg = f"Updated by {repo_name} on {branch_name}"
+
+    _push(
+        url=conf.source_repo.url,
+        branch=conf.source_repo.branch,
+        file_map=file_map,
+        commit_message=commit_msg,
+        force=force,
+    )
+
+    for remote_path in file_map:
+        messages.append(f"OK: pushed {remote_path}")
+
+    return messages
+
+
+def _repo_name_from_root(root: Path) -> str:
+    """Best-effort repo name from the project root directory name."""
+    return root.name
+
+
+def _current_branch(root: Path) -> str:
+    """Best-effort current branch name of the local repo."""
+    try:
+        from git import Repo
+        repo = Repo(root)
+        return str(repo.active_branch)
+    except Exception as exc:
+        logger.warning("Could not detect current branch: %s", exc)
+        return "unknown"

tlc_shared_docs-0.1.0/tlc_shared_docs/git_ops.py

@@ -0,0 +1,200 @@
+"""Low-level Git helpers using GitPython (and the ``git`` CLI it wraps)."""
+
+from __future__ import annotations
+
+import fnmatch
+import shutil
+import tempfile
+from pathlib import Path
+from typing import List
+
+from git import Repo, GitCommandError
+
+
+class GitError(RuntimeError):
+    """Raised when a git operation fails."""
+
+
+def _tmp_clone_dir() -> Path:
+    """Return a fresh temporary directory for cloning."""
+    return Path(tempfile.mkdtemp(prefix="tlc_shared_docs_"))
+
+
+def list_remote_files(
+    url: str,
+    branch: str,
+    pattern: str,
+) -> List[str]:
+    """Return remote file paths matching a glob *pattern*.
+
+    Uses a treeless clone (``--filter=tree:0``) so only the tree metadata
+    is fetched -- no file blobs are downloaded.
+    """
+    clone_dir = _tmp_clone_dir()
+    try:
+        repo = Repo.init(clone_dir)
+        repo.git.remote("add", "origin", url)
+
+        # Treeless fetch: downloads tree objects but no blobs
+        repo.git.fetch("origin", branch, depth=1, filter="tree:0")
+
+        # List every file path in the tree
+        output = repo.git.ls_tree("-r", "--name-only", f"origin/{branch}")
+        all_files = output.splitlines() if output else []
+
+        # Filter with fnmatch (supports *, ?, [seq], **)
+        matched = [f for f in all_files if fnmatch.fnmatch(f, pattern)]
+        return matched
+    except GitCommandError as exc:
+        raise GitError(f"Failed to list files from {url}: {exc}") from exc
+    finally:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+
+
+def get_remote_blob_shas(
+    url: str,
+    branch: str,
+    file_paths: List[str],
+) -> dict[str, str]:
+    """Return ``{file_path: blob_sha}`` for each of *file_paths* that exists
+    on *branch* of *url*.
+
+    Uses a treeless fetch so no file content is downloaded -- only
+    tree metadata needed to read the blob SHA per path.
+    """
+    clone_dir = _tmp_clone_dir()
+    try:
+        repo = Repo.init(clone_dir)
+        repo.git.remote("add", "origin", url)
+        repo.git.fetch("origin", branch, depth=1, filter="tree:0")
+
+        # Parse full ls-tree output: "<mode> <type> <sha>\t<path>"
+        output = repo.git.ls_tree("-r", f"origin/{branch}")
+        if not output:
+            return {}
+
+        sha_map: dict[str, str] = {}
+        wanted = set(file_paths)
+        for line in output.splitlines():
+            parts = line.split(None, 3)  # mode, type, sha, path
+            if len(parts) == 4:
+                path = parts[3]
+                if path in wanted:
+                    sha_map[path] = parts[2]
+        return sha_map
+    except GitCommandError as exc:
+        raise GitError(f"Failed to get blob SHAs from {url}: {exc}") from exc
+    finally:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+
+
+def sparse_checkout_files(
+    url: str,
+    branch: str,
+    file_paths: List[str],
+) -> tuple[Path, Repo]:
+    """Clone *url* at *branch* with a **sparse checkout** containing only
+    *file_paths*.  Returns ``(clone_dir, Repo)``.
+
+    Depth=1 avoids fetching full history -- we only need latest content.
+    """
+    clone_dir = _tmp_clone_dir()
+    try:
+        # Initialise an empty repo and configure sparse-checkout
+        repo = Repo.init(clone_dir)
+        repo.git.remote("add", "origin", url)
+        repo.git.config("core.sparseCheckout", "true")
+
+        # Write the sparse-checkout patterns so only requested files appear
+        sparse_file = Path(repo.git_dir) / "info" / "sparse-checkout"
+        sparse_file.parent.mkdir(parents=True, exist_ok=True)
+        sparse_file.write_text("\n".join(file_paths) + "\n", encoding="utf-8")
+
+        # Fetch only the requested branch (shallow, single-branch)
+        repo.git.fetch("origin", branch, depth=1)
+        repo.git.checkout(f"origin/{branch}", b=branch)
+
+        return clone_dir, repo
+    except GitCommandError as exc:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+        raise GitError(f"Failed to sparse-checkout from {url}: {exc}") from exc
+
+
+def read_file_from_clone(clone_dir: Path, remote_path: str) -> bytes:
+    """Read a single file out of a sparse clone."""
+    target = clone_dir / remote_path
+    if not target.exists():
+        raise FileNotFoundError(f"File not found in clone: {remote_path}")
+    return target.read_bytes()
+
+
+def push_files(
+    url: str,
+    branch: str,
+    file_map: dict[str, bytes],
+    commit_message: str,
+    force: bool = False,
+) -> None:
+    """Clone *url*, write *file_map* ``{remote_path: content}``, commit, and
+    push to *branch*.
+
+    If *force* is ``True`` the push uses ``--force``.
+    """
+    clone_dir = _tmp_clone_dir()
+    try:
+        # Shallow clone with the target branch checked out
+        repo = Repo.init(clone_dir)
+        repo.git.remote("add", "origin", url)
+        repo.git.fetch("origin", branch, depth=1)
+        repo.git.checkout(f"origin/{branch}", b=branch)
+
+        # Write each file and stage it for commit
+        changed = False
+        for remote_path, content in file_map.items():
+            dest = clone_dir / remote_path
+            dest.parent.mkdir(parents=True, exist_ok=True)
+
+            # Skip files that already match to avoid empty commits
+            if dest.exists() and dest.read_bytes() == content:
+                continue
+
+            dest.write_bytes(content)
+            repo.index.add([remote_path])
+            changed = True
+
+        if not changed:
+            return  # nothing to push
+
+        repo.index.commit(commit_message)
+
+        push_args = ["origin", branch]
+        if force:
+            push_args.insert(0, "--force")
+        repo.git.push(*push_args)
+    except GitCommandError as exc:
+        raise GitError(f"Failed to push to {url}: {exc}") from exc
+    finally:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+
+
+def fetch_single_file(url: str, branch: str, file_path: str) -> bytes | None:
+    """Fetch a single file from a remote repo via sparse checkout.
+
+    Returns the file contents, or ``None`` if the file does not exist.
+    """
+    clone_dir = _tmp_clone_dir()
+    try:
+        clone_dir, _repo = sparse_checkout_files(url, branch, [file_path])
+        target = clone_dir / file_path
+        if not target.exists():
+            return None
+        return target.read_bytes()
+    except GitError:
+        raise
+    finally:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+
+
+def cleanup(clone_dir: Path) -> None:
+    """Remove a temporary clone directory."""
+    shutil.rmtree(clone_dir, ignore_errors=True)