git-env 0.1.0__tar.gz

git_env-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,214 @@
+<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/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "git-env"
+version = "0.1.0"
+description = "Sync environment files across linked git worktrees"
+readme = "README.md"
+authors = [
+    { name = "Alex Ward", email = "alxwrd@googlemail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "arguably>=1.2.2",
+]
+
+[project.scripts]
+git-env = "git_env:main"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

git_env-0.1.0/src/git_env/__init__.py

@@ -0,0 +1,16 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("git-env")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+
+def main() -> None:
+    import __main__
+
+    __main__.__version__ = __version__
+
+    from .cli import main as cli_main
+
+    cli_main()

git_env-0.1.0/src/git_env/cli.py

@@ -0,0 +1,183 @@
+"""Top-level CLI: dispatches `git env <subcommand>` via arguably.
+
+Exit codes are part of the spec's contract (see spec.md):
+  0 success, 1 sync conflicts skipped, 2 refused to run, 3 usage error, 4 I/O error.
+argparse itself always raises `SystemExit(2)` for usage errors (bad flag, unknown
+subcommand), which collides with our "refused to run" code. `GitEnvExit` lets
+command bodies signal an intentional exit code; any other `SystemExit(2)` reaching
+`main()` therefore came from argparse and is remapped to 3.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import arguably
+
+from .config import ConfigError, load_config
+from .output import Reporter
+from .repo import RepoError, check_primary_clean, detect_repository
+from .shell_completions import SUPPORTED_SHELLS
+from .shell_completions import install_completions as render_completions_install
+from .sync import SyncIOError, run_sync
+
+#: Names set aside for future official subcommands (see spec.md Extensibility).
+RESERVED_SUBCOMMANDS = frozenset({"push", "diff", "status", "list", "edit", "check"})
+
+
+class GitEnvExit(Exception):
+    """Raised by command bodies to request a specific process exit code."""
+
+    def __init__(self, code: int) -> None:
+        super().__init__(code)
+        self.code = code
+
+
+@arguably.command
+def __root__(
+    *, porcelain: bool = False, install_completions: str | None = None, write: bool = False
+) -> None:
+    """
+    git env: sync environment files across linked git worktrees.
+
+    Args:
+        porcelain: reserved for a future machine-readable output mode (not yet supported)
+        install_completions: print a completion snippet for [bash|zsh|fish]; combine with
+            --write to install the completion file instead of printing it
+        write: used with --install-completions, write the completion file to its standard
+            location instead of printing a snippet
+    """
+    if porcelain:
+        print(
+            "git env: --porcelain is reserved for a future version and is not yet"
+            " supported",
+            file=sys.stderr,
+        )
+        raise GitEnvExit(3)
+    if install_completions is not None:
+        if install_completions not in SUPPORTED_SHELLS:
+            print(
+                "git env: --install-completions expects one of "
+                f"{', '.join(SUPPORTED_SHELLS)}, got {install_completions!r}",
+                file=sys.stderr,
+            )
+            raise GitEnvExit(3)
+        print(render_completions_install(install_completions, write=write))
+        raise GitEnvExit(0)
+    if write:
+        print("git env: --write requires --install-completions", file=sys.stderr)
+        raise GitEnvExit(3)
+    if arguably.is_target():
+        arguably.error("a subcommand is required, try 'git env --help'")
+
+
+@arguably.command
+def sync(
+    *,
+    dry_run: bool = False,
+    force: bool = False,
+    verbose: bool = False,
+    quiet: bool = False,
+    pattern: list[str] | None = None,
+    path: str | None = None,
+) -> None:
+    """
+    Copy env files from the primary worktree into the current linked worktree.
+
+    Args:
+        dry_run: [-n] print actions, change nothing
+        force: [-f] overwrite local files even when they differ from the primary
+        verbose: [-v] print every file considered, including skips
+        quiet: [-q] suppress non-error output
+        pattern: glob to sync, repeatable; overrides configured patterns for this run
+        path: restrict to a subdirectory of the worktree
+    """
+    if verbose and quiet:
+        print("git env sync: --verbose and --quiet are mutually exclusive", file=sys.stderr)
+        raise GitEnvExit(3)
+
+    reporter = Reporter(verbose=verbose, quiet=quiet)
+
+    try:
+        repo = detect_repository()
+    except RepoError as exc:
+        reporter.error(str(exc))
+        raise GitEnvExit(2) from None
+
+    try:
+        config = load_config(repo.primary_root)
+    except ConfigError as exc:
+        reporter.error(str(exc))
+        raise GitEnvExit(3) from None
+
+    if pattern:
+        config = type(config)(**{**config.__dict__, "patterns": tuple(pattern)})
+
+    if not force:
+        dirty = check_primary_clean(repo.primary_root, config.patterns, config.exclude)
+        if dirty:
+            reporter.error(
+                "primary worktree has uncommitted changes to tracked env files: "
+                f"{', '.join(dirty)} (use --force to override)"
+            )
+            raise GitEnvExit(2)
+
+    try:
+        result = run_sync(
+            repo,
+            config,
+            dry_run=dry_run,
+            force=force,
+            path=path,
+            reporter=reporter,
+        )
+    except SyncIOError as exc:
+        reporter.error(str(exc))
+        raise GitEnvExit(4) from None
+
+    if dry_run:
+        raise GitEnvExit(1 if result.would_change or result.conflicts else 0)
+    raise GitEnvExit(result.exit_code)
+
+
+def _rewrite_help_subcommand(argv: list[str]) -> list[str]:
+    """Translate `git env help [subcommand]` into `git env [subcommand] --help`."""
+    if argv and argv[0] == "help":
+        rest = argv[1:]
+        return [*rest, "--help"]
+    return argv
+
+
+def _reject_reserved_subcommand(argv: list[str]) -> None:
+    """Give a clearer error than argparse's "invalid choice" for reserved names."""
+    for token in argv:
+        if token == "--":
+            return
+        if token.startswith("-"):
+            continue
+        if token in RESERVED_SUBCOMMANDS:
+            print(
+                f"git env: '{token}' is reserved for future use and is not yet"
+                " implemented",
+                file=sys.stderr,
+            )
+            raise GitEnvExit(3)
+        return
+
+
+def main() -> None:
+    argv = _rewrite_help_subcommand(sys.argv[1:])
+    sys.argv = [sys.argv[0], *argv]
+    try:
+        _reject_reserved_subcommand(argv)
+        arguably.run(
+            name="git env",
+            version_flag=True,
+        )
+    except GitEnvExit as exc:
+        sys.exit(exc.code)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        if code == 2:
+            sys.exit(3)
+        raise