git-env 0.1.0__py3-none-any.whl

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/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

git_env/completions/_git-env

@@ -0,0 +1,43 @@
+#compdef git-env
+# Zsh completion for `git env` / `git-env`, following the `_git` plugin
+# convention: a function named `_git-env` is dispatched automatically by
+# zsh's bundled `_git` completion when it sees `git env <TAB>`. Placing this
+# file on $fpath also makes `git-env <TAB>` work when invoked directly.
+
+_git-env() {
+	local curcontext="$curcontext" state line
+	local -a subcommands
+	subcommands=(
+		'sync:copy env files from the primary worktree into the current linked worktree'
+	)
+
+	_arguments -C \
+		'(- *)'{-h,--help}'[show help]' \
+		'(- *)--version[print the version]' \
+		'--install-completions[print a completion snippet for a shell]:shell:(bash zsh fish)' \
+		'--write[write the completion file instead of printing a snippet]' \
+		'1: :->subcommand' \
+		'*::arg:->args'
+
+	case $state in
+		subcommand)
+			_describe -t commands 'git env subcommand' subcommands
+			;;
+		args)
+			case ${words[1]} in
+				sync)
+					_arguments \
+						'(-n --dry-run)'{-n,--dry-run}'[print actions, change nothing]' \
+						'(-f --force)'{-f,--force}'[overwrite local files even when they differ from the primary]' \
+						'(-v --verbose)'{-v,--verbose}'[print every file considered, including skips]' \
+						'(-q --quiet)'{-q,--quiet}'[suppress non-error output]' \
+						'*--pattern[glob to sync, repeatable]:glob' \
+						'--path[restrict to a subdirectory of the worktree]:subdir:_files -/' \
+						'(-h --help)'{-h,--help}'[show help]'
+					;;
+			esac
+			;;
+	esac
+}
+
+_git-env "$@"

git_env/completions/git-env.bash

@@ -0,0 +1,64 @@
+# Bash completion for `git env` / `git-env`.
+#
+# Source this file directly, or install it where bash-completion looks for
+# completions (see `git env --install-completions bash --write`).
+#
+# Defining `_git_env` lets git's own completion machinery dispatch
+# `git env <TAB>` to this function automatically once git-completion.bash is
+# loaded (it tries `_git_<subcommand>` for any subcommand it doesn't know
+# about natively). The explicit `complete`/`__git_complete` call below also
+# covers invoking the `git-env` binary directly.
+
+_git_env_subcommands="sync"
+_git_env_sync_opts="--dry-run -n --force -f --verbose -v --quiet -q --pattern --path --help -h"
+_git_env_root_opts="--help -h --version --install-completions --write"
+
+_git_env()
+{
+	local cur prev words cword
+	if declare -F _get_comp_words_by_ref >/dev/null 2>&1; then
+		_get_comp_words_by_ref -n =: cur prev words cword
+	else
+		cur="${COMP_WORDS[COMP_CWORD]}"
+		prev="${COMP_WORDS[COMP_CWORD-1]:-}"
+		words=("${COMP_WORDS[@]}")
+		cword=$COMP_CWORD
+	fi
+
+	if [[ "$prev" == "--install-completions" ]]; then
+		COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur"))
+		return
+	fi
+
+	local subcommand="" i
+	for ((i = 1; i < cword; i++)); do
+		case "${words[i]}" in
+			-*) ;;
+			*)
+				subcommand="${words[i]}"
+				break
+				;;
+		esac
+	done
+
+	if [[ -z "$subcommand" ]]; then
+		COMPREPLY=($(compgen -W "${_git_env_subcommands} ${_git_env_root_opts}" -- "$cur"))
+		return
+	fi
+
+	case "$subcommand" in
+		sync)
+			COMPREPLY=($(compgen -W "${_git_env_sync_opts}" -- "$cur"))
+			;;
+		*)
+			COMPREPLY=()
+			;;
+	esac
+}
+
+if declare -F __git_complete >/dev/null 2>&1; then
+	__git_complete git-env _git_env
+else
+	complete -o bashdefault -o default -F _git_env git-env 2>/dev/null \
+		|| complete -F _git_env git-env
+fi

git_env/completions/git-env.fish

@@ -0,0 +1,32 @@
+# Fish completions for `git-env` (and `git env`, which fish resolves to the
+# same binary once `complete -c git-env` rules exist).
+
+set -l subcommands sync
+
+complete -c git-env -f
+
+complete -c git-env -n "not __fish_seen_subcommand_from $subcommands" -a sync \
+	-d "Sync env files from the primary worktree into the current linked worktree"
+complete -c git-env -n "not __fish_seen_subcommand_from $subcommands" -l version \
+	-d "Print the version"
+complete -c git-env -n "not __fish_seen_subcommand_from $subcommands" -l install-completions \
+	-x -a "bash zsh fish" -d "Print a completion snippet for a shell"
+complete -c git-env -n "not __fish_seen_subcommand_from $subcommands" -l write \
+	-d "Write the completion file instead of printing a snippet"
+complete -c git-env -n "not __fish_seen_subcommand_from $subcommands" -s h -l help \
+	-d "Show help"
+
+complete -c git-env -n "__fish_seen_subcommand_from sync" -s n -l dry-run \
+	-d "Print actions, change nothing"
+complete -c git-env -n "__fish_seen_subcommand_from sync" -s f -l force \
+	-d "Overwrite local files even when they differ from the primary"
+complete -c git-env -n "__fish_seen_subcommand_from sync" -s v -l verbose \
+	-d "Print every file considered, including skips"
+complete -c git-env -n "__fish_seen_subcommand_from sync" -s q -l quiet \
+	-d "Suppress non-error output"
+complete -c git-env -n "__fish_seen_subcommand_from sync" -l pattern -r \
+	-d "Glob to sync (repeatable)"
+complete -c git-env -n "__fish_seen_subcommand_from sync" -l path -r -a "(__fish_complete_directories)" \
+	-d "Restrict to a subdirectory of the worktree"
+complete -c git-env -n "__fish_seen_subcommand_from sync" -s h -l help \
+	-d "Show help"

git_env/config.py

@@ -0,0 +1,196 @@
+"""Configuration: read env.sync.* settings via `git config` and the optional
+`.envsync` file, with standard git config precedence (system -> global ->
+local -> worktree) handled natively by `git config --get[-all]`.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_PATTERNS = (".env", ".env.*")
+DEFAULT_EXCLUDE = (".env.example", ".env.sample", ".env.template")
+DEFAULT_FOLLOW_SYMLINKS = False
+DEFAULT_MAX_FILE_SIZE = 1048576
+DEFAULT_ON_CONFLICT = "skip"
+DEFAULT_BACKUP = True
+
+VALID_ON_CONFLICT = frozenset({"skip", "overwrite", "prompt"})
+
+_TRUE_VALUES = frozenset({"true", "yes", "on", "1"})
+_FALSE_VALUES = frozenset({"false", "no", "off", "0"})
+
+
+class ConfigError(Exception):
+    """Raised when a configuration value is malformed or invalid."""
+
+
+@dataclass(frozen=True)
+class SyncConfig:
+    """Resolved `env.sync.*` configuration for a sync run."""
+
+    patterns: tuple[str, ...] = DEFAULT_PATTERNS
+    exclude: tuple[str, ...] = DEFAULT_EXCLUDE
+    follow_symlinks: bool = DEFAULT_FOLLOW_SYMLINKS
+    max_file_size: int = DEFAULT_MAX_FILE_SIZE
+    on_conflict: str = DEFAULT_ON_CONFLICT
+    backup: bool = DEFAULT_BACKUP
+
+
+def _git_config_get_all(key: str, cwd: Path) -> list[str] | None:
+    """Return every value of a multi-value key, or None if unset.
+
+    `git config --get-all` itself walks system -> global -> local ->
+    worktree, so this already reflects standard precedence.
+    """
+    result = subprocess.run(
+        ["git", "config", "--get-all", key],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None
+    values = [line for line in result.stdout.split("\n") if line != ""]
+    return values or None
+
+
+def _git_config_get(key: str, cwd: Path) -> str | None:
+    result = subprocess.run(
+        ["git", "config", "--get", key],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None
+    value = result.stdout.rstrip("\n")
+    return value or None
+
+
+def _parse_envsync_file(path: Path) -> dict[str, list[str]]:
+    """Parse a `.envsync` file: gitignore-flavored `key=value` lines, no
+    `env.sync.` prefix. Repeated keys accumulate (for multi-value keys).
+    """
+    values: dict[str, list[str]] = {}
+    if not path.is_file():
+        return values
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            continue
+        values.setdefault(key, []).append(value)
+    return values
+
+
+def _parse_bool(value: str, *, source: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in _TRUE_VALUES:
+        return True
+    if lowered in _FALSE_VALUES:
+        return False
+    raise ConfigError(f"invalid boolean value for {source}: {value!r}")
+
+
+def _parse_int(value: str, *, source: str) -> int:
+    try:
+        return int(value.strip())
+    except ValueError as exc:
+        raise ConfigError(f"invalid integer value for {source}: {value!r}") from exc
+
+
+def _resolve_multi(
+    config_key: str, envsync: dict[str, list[str]], envsync_key: str, default: tuple[str, ...], cwd: Path
+) -> list[str]:
+    values = _git_config_get_all(config_key, cwd)
+    if values is not None:
+        return values
+    if envsync_key in envsync:
+        return list(envsync[envsync_key])
+    return list(default)
+
+
+def _resolve_bool(
+    config_key: str, envsync: dict[str, list[str]], envsync_key: str, default: bool, cwd: Path
+) -> bool:
+    value = _git_config_get(config_key, cwd)
+    if value is not None:
+        return _parse_bool(value, source=config_key)
+    if envsync_key in envsync:
+        return _parse_bool(envsync[envsync_key][-1], source=f".envsync:{envsync_key}")
+    return default
+
+
+def _resolve_int(
+    config_key: str, envsync: dict[str, list[str]], envsync_key: str, default: int, cwd: Path
+) -> int:
+    value = _git_config_get(config_key, cwd)
+    if value is not None:
+        return _parse_int(value, source=config_key)
+    if envsync_key in envsync:
+        return _parse_int(envsync[envsync_key][-1], source=f".envsync:{envsync_key}")
+    return default
+
+
+def _resolve_str(
+    config_key: str, envsync: dict[str, list[str]], envsync_key: str, default: str, cwd: Path
+) -> str:
+    value = _git_config_get(config_key, cwd)
+    if value is not None:
+        return value
+    if envsync_key in envsync:
+        return envsync[envsync_key][-1]
+    return default
+
+
+def load_config(primary_root: Path) -> SyncConfig:
+    """Resolve `env.sync.*` configuration for `primary_root`.
+
+    Precedence per key: git config (system -> global -> local -> worktree)
+    overrides the primary's `.envsync` file, which overrides built-in
+    defaults.
+    """
+    envsync = _parse_envsync_file(primary_root / ".envsync")
+
+    patterns = _resolve_multi(
+        "env.sync.patterns", envsync, "patterns", DEFAULT_PATTERNS, primary_root
+    )
+    exclude = _resolve_multi(
+        "env.sync.exclude", envsync, "exclude", DEFAULT_EXCLUDE, primary_root
+    )
+    follow_symlinks = _resolve_bool(
+        "env.sync.followSymlinks",
+        envsync,
+        "followSymlinks",
+        DEFAULT_FOLLOW_SYMLINKS,
+        primary_root,
+    )
+    max_file_size = _resolve_int(
+        "env.sync.maxFileSize", envsync, "maxFileSize", DEFAULT_MAX_FILE_SIZE, primary_root
+    )
+    on_conflict = _resolve_str(
+        "env.sync.onConflict", envsync, "onConflict", DEFAULT_ON_CONFLICT, primary_root
+    )
+    if on_conflict not in VALID_ON_CONFLICT:
+        raise ConfigError(
+            f"invalid env.sync.onConflict value: {on_conflict!r}"
+            f" (expected one of {sorted(VALID_ON_CONFLICT)})"
+        )
+    backup = _resolve_bool(
+        "env.sync.backup", envsync, "backup", DEFAULT_BACKUP, primary_root
+    )
+
+    return SyncConfig(
+        patterns=tuple(patterns),
+        exclude=tuple(exclude),
+        follow_symlinks=follow_symlinks,
+        max_file_size=max_file_size,
+        on_conflict=on_conflict,
+        backup=backup,
+    )