git-env 0.1.0__py3-none-any.whl

git_env/sync.py

@@ -0,0 +1,243 @@
+"""Core `git env sync` logic: copy env files from the primary worktree into
+the current linked worktree.
+
+Implements the "Copy semantics" and "Conflict handling" rules from spec.md,
+including line-diff summaries, `.envsync.bak` backups, and the
+`env.sync.onConflict` modes. The safety-rail refusals beyond repository
+detection are tracked as separate follow-up work.
+"""
+
+from __future__ import annotations
+
+import difflib
+import filecmp
+import fnmatch
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import SyncConfig
+from .discovery import DiscoveredFile, discover_env_files
+from .output import Reporter
+from .repo import Repository
+
+#: Suffix used for the atomic-write temp file (spec: copy to `<dest>.envsync.tmp`
+#: then `rename(2)` over the destination).
+_TMP_SUFFIX = ".envsync.tmp"
+
+
+class SyncIOError(Exception):
+    """Raised on an I/O failure during copy. Always corresponds to exit code 4."""
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    """Outcome of a sync run, used to derive the process exit code."""
+
+    synced: int = 0
+    skipped_unchanged: int = 0
+    conflicts: int = 0
+    would_change: int = 0
+    """Files that would be copied/overwritten; only meaningful for --dry-run."""
+
+    @property
+    def exit_code(self) -> int:
+        if self.conflicts:
+            return 1
+        return 0
+
+
+def _filter_path(files: list[DiscoveredFile], path: str | None) -> list[DiscoveredFile]:
+    if path is None:
+        return files
+    prefix = Path(path)
+    return [f for f in files if prefix in (f.relative_path, *f.relative_path.parents)]
+
+
+def _resolve_dest(worktree_root: Path, relative_path: Path) -> Path:
+    """Resolve `relative_path` against `worktree_root`, refusing escapes.
+
+    Guards against a pattern or symlinked source resolving outside the
+    current worktree (spec: "Never write outside the current worktree root").
+    """
+    dest = (worktree_root / relative_path).resolve()
+    if worktree_root not in dest.parents and dest != worktree_root:
+        raise SyncIOError(
+            f"refusing to write outside the worktree: {relative_path}"
+        )
+    return dest
+
+
+def _diff_summary(src: Path, dest: Path) -> str:
+    """Describe how `dest` differs from `src`, e.g. "3 lines differ"."""
+    try:
+        src_lines = src.read_text().splitlines()
+        dest_lines = dest.read_text().splitlines()
+    except (UnicodeDecodeError, OSError):
+        return "binary files differ"
+    matcher = difflib.SequenceMatcher(a=dest_lines, b=src_lines)
+    changed = sum(
+        max(i2 - i1, j2 - j1)
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes()
+        if tag != "equal"
+    )
+    noun = "line" if changed == 1 else "lines"
+    return f"{changed} {noun} differ"
+
+
+def _backup(dest: Path) -> None:
+    """Back up `dest`'s current content to `<dest>.envsync.bak` before an
+    overwrite (spec: "single backup, overwritten on subsequent forces").
+    """
+    backup_path = dest.with_name(dest.name + ".envsync.bak")
+    try:
+        shutil.copyfile(dest, backup_path)
+        shutil.copymode(dest, backup_path)
+    except OSError as exc:
+        raise SyncIOError(f"failed to back up {dest}: {exc}") from exc
+
+
+def _prompt_overwrite(rel: Path, diff_desc: str, reporter: Reporter) -> bool:
+    try:
+        answer = input(f"{rel}: {diff_desc}. Overwrite? [y/N] ")
+    except EOFError:
+        reporter.warn(f"{rel}: cannot prompt for input, skipping")
+        return False
+    return answer.strip().lower() in {"y", "yes"}
+
+
+def _atomic_copy(src: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_name(dest.name + _TMP_SUFFIX)
+    try:
+        shutil.copyfile(src, tmp)
+        shutil.copymode(src, tmp)
+        os.replace(tmp, dest)
+    except OSError as exc:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise SyncIOError(f"failed to copy {src} -> {dest}: {exc}") from exc
+
+
+def _cleanup_excluded_in_linked(
+    worktree_root: Path,
+    config: SyncConfig,
+    path: str | None,
+    *,
+    dry_run: bool,
+    reporter: Reporter,
+) -> int:
+    """Remove files from the linked worktree that match include AND exclude patterns.
+
+    Excluded patterns are for committed templates (e.g. .env.example) that git
+    checks out into linked worktrees but that sync should never treat as env files.
+    """
+    root = worktree_root
+    search_root = (root / path) if path else root
+    if not search_root.is_dir():
+        return 0
+
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(search_root):
+        dir_path = Path(dirpath)
+        dirnames[:] = [d for d in dirnames if d != ".git"]
+        for filename in filenames:
+            if not any(fnmatch.fnmatch(filename, p) for p in config.patterns):
+                continue
+            if not any(fnmatch.fnmatch(filename, p) for p in config.exclude):
+                continue
+            abs_path = dir_path / filename
+            if abs_path.is_symlink():
+                continue
+            rel_path = abs_path.relative_to(root)
+            if dry_run:
+                reporter.detail(f"would remove {rel_path} (excluded template)")
+            else:
+                abs_path.unlink()
+                reporter.detail(f"removed {rel_path} (excluded template)")
+            count += 1
+    return count
+
+
+def run_sync(
+    repo: Repository,
+    config: SyncConfig,
+    *,
+    dry_run: bool = False,
+    force: bool = False,
+    path: str | None = None,
+    reporter: Reporter,
+) -> SyncResult:
+    """Sync env files from `repo.primary_root` into `repo.worktree_root`."""
+    files, warnings = discover_env_files(repo.primary_root, config)
+    files = _filter_path(files, path)
+
+    for warning in warnings:
+        reporter.warn(f"{warning.relative_path}: {warning.message}")
+
+    synced = 0
+    skipped_unchanged = 0
+    conflicts = 0
+    would_change = 0
+
+    for discovered in files:
+        rel = discovered.relative_path
+        dest = _resolve_dest(repo.worktree_root, rel)
+
+        if not dest.exists():
+            if dry_run:
+                would_change += 1
+                reporter.info(f"would sync {rel}")
+                continue
+            _atomic_copy(discovered.absolute_path, dest)
+            synced += 1
+            reporter.info(f"synced {rel}")
+            continue
+
+        if filecmp.cmp(discovered.absolute_path, dest, shallow=False):
+            skipped_unchanged += 1
+            reporter.detail(f"unchanged {rel}")
+            continue
+
+        diff_desc = _diff_summary(discovered.absolute_path, dest)
+        should_overwrite = force or config.on_conflict == "overwrite"
+
+        if not should_overwrite and config.on_conflict == "prompt" and not dry_run:
+            should_overwrite = _prompt_overwrite(rel, diff_desc, reporter)
+
+        if should_overwrite:
+            if dry_run:
+                would_change += 1
+                reporter.info(f"would overwrite {rel} ({diff_desc})")
+                continue
+            if config.backup:
+                _backup(dest)
+            _atomic_copy(discovered.absolute_path, dest)
+            synced += 1
+            reporter.info(f"synced {rel} (overwrote, {diff_desc})")
+            continue
+
+        conflicts += 1
+        reporter.warn(f"{rel}: {diff_desc}, skipping (use --force to overwrite)")
+
+    cleaned = _cleanup_excluded_in_linked(
+        repo.worktree_root, config, path, dry_run=dry_run, reporter=reporter
+    )
+    if dry_run:
+        would_change += cleaned
+
+    total_changes = synced + (would_change if dry_run else 0)
+    reporter.info(
+        f"{total_changes if dry_run else synced} files synced, "
+        f"{skipped_unchanged} unchanged, {conflicts} conflicts skipped"
+    )
+
+    return SyncResult(
+        synced=synced,
+        skipped_unchanged=skipped_unchanged,
+        conflicts=conflicts,
+        would_change=would_change,
+    )

git_env-0.1.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.3
+Name: git-env
+Version: 0.1.0
+Summary: Sync environment files across linked git worktrees
+Author: Alex Ward
+Author-email: Alex Ward <alxwrd@googlemail.com>
+Requires-Dist: arguably>=1.2.2
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <h1><code>git-env</code></h1>
+    <p align="center"><i>
+        Environment file syncronisation to your linked git worktrees
+    </i></p>
+    <img width="256px" src="https://github.com/alxwrd/git-env/raw/main/.github/assets/man-reading-the-mail-768.png">
+    <div align="center">
+        <a href="https://github.com/alxwrd/git-env/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/alxwrd/git-env/test.yml?branch=main&label=main"></a>
+        <a href="https://pypi.python.org/pypi/git-env"><img src="https://img.shields.io/pypi/v/git-env.svg"></a>
+        <a href="https://github.com/alxwrd/git-env/blob/main/LICENCE"><img src="https://img.shields.io/pypi/l/git-env.svg?"></a>
+    </div>
+
+Copies untracked env files to your worktrees.
+</div>
+
+
+## Example
+
+```sh
+cd ~/repos/myproject                       # primary worktree, has .env
+git worktree add ~/worktrees/myproject-feature      # create a linked worktree
+cd ~/worktrees/myproject-feature
+git env sync                               # copies .env from the primary
+```
+
+```plain
+$ git env sync
+
+copied  .env
+copied  .env.local
+
+2 files synced.
+```
+
+Run it again later to pick up any changes made in the primary. By default,
+`sync` won't clobber a file that has diverged locally — pass `--force` if
+you want the primary's copy to win.
+
+
+## Installation
+
+```shell
+uv tool install git-env
+```
+
+Or, with pipx:
+
+```shell
+pipx install git-env
+```
+
+This installs a `git-env` executable on your `PATH`, which git picks up
+automatically as the `env` subcommand:
+
+```sh
+git env --version
+```
+
+
+## Syncing
+
+`git env sync` copies env files from the primary worktree into the linked
+worktree you're standing in. The primary worktree is the original clone — the
+one whose `.git` is a real directory, not a file. `sync` locates it via
+`git rev-parse --git-common-dir`.
+
+Files are matched by glob against the entire primary worktree tree.
+`.gitignore` is **not** consulted (env files are normally gitignored, which is
+the point), but a `.envsyncignore` file at the primary root is. A file that
+doesn't exist at the destination is copied. A file that's byte-identical is
+skipped silently. A file that differs is skipped with a warning and a one-line
+diff summary, unless `--force` is given.
+
+Writes are atomic: each file is written to `<dest>.envsync.tmp` then renamed
+over the destination. Mode bits (including the executable bit) are preserved;
+mtimes are not, so a synced file's timestamp tells you when it was synced.
+
+`sync` must run from a **linked** worktree — it refuses to run from the
+primary itself, and refuses on bare repositories.
+
+```
+git env sync [--dry-run] [--force] [--verbose | --quiet]
+             [--pattern <glob>]... [--path <subdir>]
+```
+
+| Flag | Short | Meaning |
+|---|---|---|
+| `--dry-run` | `-n` | Print what would happen; change nothing. |
+| `--force` | `-f` | Overwrite local files that differ from the primary, backing up the previous content first. |
+| `--verbose` | `-v` | Print every file considered, including skips. |
+| `--quiet` | `-q` | Suppress non-error output. |
+| `--pattern <glob>` | | Override configured patterns for this run. Repeatable. |
+| `--path <subdir>` | | Restrict the sync to a subdirectory of the worktree. |
+
+`--verbose` and `--quiet` are mutually exclusive.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success, or dry-run with nothing to change. |
+| `1` | Sync completed but one or more files were skipped due to conflicts. |
+| `2` | Refused to run (not a git worktree, bare repo, invoked from the primary worktree, or the primary has uncommitted changes to tracked env files). |
+| `3` | Usage error (bad flag, unknown or reserved subcommand). |
+| `4` | I/O error while copying. |
+
+These codes are part of the contract — scripts can rely on them.
+
+
+## Configuration
+
+All keys live under `env.sync.*` and are read with standard git config
+precedence (system → global → local → worktree):
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `env.sync.patterns` | multi-value | `.env`, `.env.*` | Globs to sync. Multi-value, so additional `git config --add` calls append rather than replace. |
+| `env.sync.exclude` | multi-value | `.env.example`, `.env.sample`, `.env.template` | Patterns never synced, even if they match `patterns` (typically committed templates). |
+| `env.sync.followSymlinks` | bool | `false` | Follow symlinked env files instead of skipping them. |
+| `env.sync.maxFileSize` | int (bytes) | `1048576` | Files larger than this are skipped with a warning. |
+| `env.sync.onConflict` | enum | `skip` | `skip`, `overwrite`, or `prompt`. |
+| `env.sync.backup` | bool | `true` | Whether `--force` writes a `<dest>.envsync.bak` backup before overwriting. |
+
+Set per-repo in the primary worktree's `.git/config`, or per-worktree in
+that worktree's own config:
+
+```sh
+git config env.sync.onConflict overwrite
+git config --add env.sync.patterns ".env.local"
+```
+
+### `.envsync`
+
+An optional `key=value` file at the primary worktree root, for pinning
+patterns into version control so the whole team gets the same defaults
+without everyone running `git config`. Same keys as above, minus the
+`env.sync.` prefix:
+
+```
+patterns=.env
+patterns=.env.*
+exclude=.env.example
+followSymlinks=false
+```
+
+Repeated keys accumulate (for multi-value settings). `git config` values,
+if set, always take precedence over `.envsync`.
+
+### `.envsyncignore`
+
+A `gitignore`-syntax file at the primary worktree root. Paths it matches
+are excluded from sync regardless of `env.sync.patterns` — use it to opt a
+specific file or directory out without changing the glob patterns themselves.
+
+
+## Shell completion
+
+```sh
+git env --install-completions bash   # print a snippet for your rc file
+git env --install-completions zsh --write   # install the completion file directly
+git env --install-completions fish
+```
+
+Supported shells: `bash`, `zsh`, `fish`. Without `--write`, the command
+prints what to add to your shell config; with `--write`, it installs the
+completion file to a standard location for that shell.
+
+
+## FAQ
+
+**Why not just symlink the env files instead?**
+A symlink means there's only ever one copy, so editing the file in a linked
+worktree edits the primary too — that defeats the purpose of having isolated
+worktrees in the first place (e.g. running two branches with different API
+keys or feature flags side by side). `git env sync` gives each worktree its
+own independent copy, seeded from the primary, that you can then diverge from
+intentionally.
+
+**Does this work with bare repositories?**
+No. `git env sync` requires a primary worktree with a real working tree to
+copy *from*. Bare repos are detected and rejected with exit code `2`.
+
+**What about secrets in env files?**
+`git env sync` only ever copies bytes between worktrees on your local
+filesystem — it doesn't transmit, log, or store file contents anywhere else,
+and it never touches git history (env files are normally gitignored and stay
+that way). The usual rules still apply: don't commit secrets, and be mindful
+that `--force` backups (`<dest>.envsync.bak`) leave a second copy of the
+previous content on disk.
+
+**Can I sync changes back from a worktree to the primary?**
+Not yet. `sync` is one-way (primary → linked). A `git env push` for the
+reverse direction is planned but not implemented in v1 — see Limitations.
+
+
+## Limitations
+
+- **One-way sync only.** `git env sync` copies primary → linked. There is no
+  bidirectional sync in v1; pushing changes from a linked worktree back to the
+  primary isn't supported yet.
+- **Submodules aren't traversed.** Env files inside submodules are not
+  discovered or synced.
+- **Single primary per invocation.** The tool assumes one primary worktree and
+  doesn't support syncing between two linked worktrees directly.
+- **No format parsing.** Env files are treated as opaque bytes; `git env`
+  doesn't understand `KEY=VALUE` syntax, so it can't merge or diff values
+  semantically — only whole-file conflict detection.
+- **`--porcelain` is reserved but not implemented.** Passing it is a usage
+  error in v1, by design, so scripts don't silently depend on output that may
+  change later.
+
+`push`, `diff`, `status`, `list`, `edit`, and `check` are reserved for
+future official subcommands and will error if invoked, so a third-party
+`git-env-<name>` script doesn't collide with them later.

git_env-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+git_env/__init__.py,sha256=tk97bBRWI7MgDIPVeB7TEsKQEX9g1g4xhGyR51qimRw,303
+git_env/cli.py,sha256=uZxcICdbmwLwlAfkqWzwlFx0zusZyKxYHCp4ttLIf-g,6107
+git_env/completions/_git-env,sha256=rKY9vn5BzLKDf4FltOEOmU3AmfWv0daFDEiNJ-PDeyk,1482
+git_env/completions/git-env.bash,sha256=VMDt8C2o3roJ9c6wcjn1MExNwAFC3hiBOmZe_-7FICY,1758
+git_env/completions/git-env.fish,sha256=RQJ0a10TpH_iI5-pN_Hphg_tM77ZXEvjJm8ZEwHmNKk,1691
+git_env/config.py,sha256=6J9LKCCIb9sd4DWoEprK5McCkPi0jCogHUB4v6nQONI,6226
+git_env/discovery.py,sha256=QPuPOs4MhL3v_atuAXi9oRBDmUxHMqsx5vKgHQsudTU,6631
+git_env/output.py,sha256=Du4j64mVcWsURYDG_JRvq9HmZcz5TG4EH0iFuY40FW8,1137
+git_env/repo.py,sha256=o8B4HypFlytwHiqWQqgrzf608fcAsapAQpzk0peL6Dw,5210
+git_env/shell_completions.py,sha256=Htbb5J_jVhTcKfz1rbYyw4xDjHQ_vsDr2qSohH3ZF7U,3049
+git_env/sync.py,sha256=m9moOKaUPfK6NmCpu9Kz-_wlQz4qjXWkq8Lej1ACqo8,7897
+git_env-0.1.0.dist-info/WHEEL,sha256=jROcLULcdzropX2J55opKw4UHhPFREZax2XzS-Mvpxs,80
+git_env-0.1.0.dist-info/entry_points.txt,sha256=2HJnPa1q9g0KpBhhZOlq-wI8_vozgLnrm5aLLKJPGM4,42
+git_env-0.1.0.dist-info/METADATA,sha256=vz_a2r2YcbSdu6q1PezZWyrzHud-TZXjpJJgvAR2SrY,8677
+git_env-0.1.0.dist-info/RECORD,,

git_env-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.0
+Root-Is-Purelib: true
+Tag: py3-none-any

git_env-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+git-env = git_env:main
+