git-ftp 2.0.0.dev0__py3-none-any.whl

gitftp/gitrepo.py

@@ -0,0 +1,293 @@
+"""Git access through the ``git`` binary.
+
+Nothing here changes the working directory: every command receives ``cwd``.
+Upstream ran ``set_syncroot`` before ``cd``-ing to the top level, which broke
+invocations from a subdirectory; here paths are always resolved from
+:attr:`GitRepo.root`.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+
+from gitftp.errors import GitError
+
+MIN_GIT_VERSION = (1, 7, 0)
+
+
+class UnknownCommit(Exception):
+    """A diff against a commit git does not know."""
+
+
+class GitRunner:
+    """Run git commands in a directory (which need not be a repository)."""
+
+    def __init__(self, cwd: Path) -> None:
+        self.cwd = Path(cwd)
+
+    def run(
+        self,
+        *args: str,
+        input: bytes | None = None,
+        ok_codes: Sequence[int] = (0,),
+        inherit_stdio: bool = False,
+    ) -> subprocess.CompletedProcess[bytes]:
+        env = dict(os.environ)
+        env["LC_ALL"] = "C"
+        try:
+            proc = subprocess.run(
+                ["git", *args],
+                cwd=self.cwd,
+                input=input,
+                env=env,
+                stdin=None if inherit_stdio or input is not None else subprocess.DEVNULL,
+                stdout=None if inherit_stdio else subprocess.PIPE,
+                stderr=None if inherit_stdio else subprocess.PIPE,
+                check=False,
+            )
+        except FileNotFoundError as e:
+            raise GitError("git is not installed or not on PATH.") from e
+        if ok_codes and proc.returncode not in ok_codes:
+            err = (proc.stderr or b"").decode("utf-8", "replace").strip()
+            raise GitError(f"git {args[0]} failed: {err or proc.returncode}")
+        return proc
+
+    def out(self, *args: str, ok_codes: Sequence[int] = (0,)) -> str:
+        return self.run(*args, ok_codes=ok_codes).stdout.decode("utf-8", "surrogateescape")
+
+    def check_version(self) -> None:
+        text = self.out("--version")
+        m = re.search(r"(\d+)\.(\d+)(?:\.(\d+))?", text)
+        if not m:
+            return
+        ver = (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
+        if ver < MIN_GIT_VERSION:
+            wanted = ".".join(str(n) for n in MIN_GIT_VERSION)
+            raise GitError(f"Git is too old, {wanted} or higher supported only.")
+
+    # -- config ------------------------------------------------------------
+    def config_list(self, file: Path | None = None) -> dict[str, str | None]:
+        """``git config --list -z`` as a mapping; ``None`` marks a valueless key."""
+        args = ["config"]
+        if file is not None:
+            args += ["-f", str(file)]
+        args += ["--list", "-z"]
+        proc = self.run(*args, ok_codes=(0, 128))
+        result: dict[str, str | None] = {}
+        for item in proc.stdout.split(b"\0"):
+            if not item:
+                continue
+            text = item.decode("utf-8", "surrogateescape")
+            key, has_value, value = text.partition("\n")
+            result[_normalise_key(key)] = value if has_value else None
+        return result
+
+    def config_set(self, key: str, value: str, file: Path | None = None) -> None:
+        args = ["config"]
+        if file is not None:
+            args += ["-f", str(file)]
+        self.run(*args, "--", key, value)
+
+    def config_remove_section(self, section: str) -> bool:
+        proc = self.run("config", "--remove-section", section, ok_codes=())
+        return proc.returncode == 0
+
+    def config_get(self, key: str) -> str | None:
+        proc = self.run("config", "--get", key, ok_codes=(0, 1))
+        if proc.returncode != 0:
+            return None
+        return proc.stdout.decode("utf-8", "surrogateescape").rstrip("\n")
+
+
+def _normalise_key(key: str) -> str:
+    """Lower-case section and key, keep the subsection (scope) case."""
+    parts = key.split(".")
+    if len(parts) >= 3:
+        return ".".join([parts[0].lower(), *parts[1:-1], parts[-1].lower()])
+    return key.lower()
+
+
+class GitRepo(GitRunner):
+    """A git working tree."""
+
+    def __init__(self, root: Path) -> None:
+        super().__init__(Path(root).absolute())
+        self.root = Path(root).absolute()
+
+    @classmethod
+    def discover(cls, cwd: Path) -> GitRepo:
+        runner = GitRunner(cwd)
+        proc = runner.run("rev-parse", "--show-toplevel", ok_codes=(0, 128))
+        top = proc.stdout.decode("utf-8", "surrogateescape").strip()
+        if proc.returncode != 0 or not top:
+            raise GitError("Not a Git project? Exiting...")
+        return cls(Path(top))
+
+    @classmethod
+    def init(cls, path: Path) -> GitRepo:
+        proc = GitRunner(path).run("init", ok_codes=())
+        if proc.returncode != 0:
+            raise GitError("Error initialising Git repository.")
+        return cls(path)
+
+    # -- state -------------------------------------------------------------
+    def head_sha(self) -> str:
+        return self.out("log", "-n", "1", "--pretty=format:%H").strip()
+
+    def current_branch(self) -> str:
+        proc = self.run("symbolic-ref", "-q", "--short", "HEAD", ok_codes=(0, 1))
+        if proc.returncode == 0:
+            return proc.stdout.decode("utf-8", "surrogateescape").strip()
+        return self.head_sha()
+
+    def checkout(self, ref: str) -> bool:
+        proc = self.run("checkout", "-q", ref, ok_codes=())
+        return proc.returncode == 0
+
+    def is_dirty(self) -> bool:
+        return bool(self.out("status", "-uno", "--porcelain").strip())
+
+    def has_any_changes(self) -> bool:
+        return bool(self.out("status", "--porcelain").strip())
+
+    def empty_tree(self) -> str:
+        return self.out("hash-object", "-t", "tree", os.devnull).strip()
+
+    # -- file lists (NUL separated, repo-relative, forward slashes) --------
+    def _z(self, *args: str, ok_codes: Sequence[int] = (0,)) -> list[str]:
+        data = self.run(*args, ok_codes=ok_codes).stdout
+        return [p.decode("utf-8", "surrogateescape") for p in data.split(b"\0") if p]
+
+    def ls_files(self, prefix: str = "") -> list[str]:
+        return self._z("ls-files", "-z", "--", prefix or ".")
+
+    def diff_names(self, base: str, diff_filter: str, prefix: str = "") -> list[str]:
+        proc = self.run(
+            "diff",
+            "--name-only",
+            "--no-renames",
+            f"--diff-filter={diff_filter}",
+            "-z",
+            base,
+            "--",
+            prefix or ".",
+            ok_codes=(),
+        )
+        if proc.returncode != 0:
+            raise UnknownCommit(base)
+        return [p.decode("utf-8", "surrogateescape") for p in proc.stdout.split(b"\0") if p]
+
+    def diff_quiet_changed(self, base: str, path: str) -> bool:
+        """``git diff --quiet base -- path``; any non-zero status counts as changed."""
+        proc = self.run("diff", "--quiet", base, "--", path, ok_codes=())
+        return proc.returncode != 0
+
+    def diff_names_between(self, a: str, b: str | None = None) -> list[str]:
+        args = ["diff", "--name-only", "-z", a]
+        if b:
+            args.append(b)
+        return self._z(*args)
+
+    def submodules(self, prefix: str = "") -> dict[str, bool]:
+        """Submodule paths under ``prefix`` mapped to whether they are initialised."""
+        if not (self.root / ".gitmodules").is_file():
+            return {}
+        args = ["submodule", "status"]
+        if prefix:
+            args += ["--", prefix]
+        proc = self.run(*args, ok_codes=(0, 1, 128))
+        result: dict[str, bool] = {}
+        for line in proc.stdout.decode("utf-8", "surrogateescape").splitlines():
+            if not line.strip():
+                continue
+            initialised = not line.startswith("-")
+            parts = line.strip().lstrip("-+U").split()
+            if parts and len(parts) >= 2:
+                result[parts[1]] = initialised
+        return result
+
+    def ignored(self, paths: list[str]) -> set[str]:
+        """The subset of ``paths`` (repo-relative) that git ignores."""
+        if not paths:
+            return set()
+        data = b"".join(p.encode("utf-8", "surrogateescape") + b"\0" for p in paths)
+        proc = self.run("check-ignore", "-z", "--stdin", input=data, ok_codes=(0, 1))
+        return {p.decode("utf-8", "surrogateescape") for p in proc.stdout.split(b"\0") if p}
+
+    def hooks_dir(self) -> Path:
+        path = self.out("rev-parse", "--git-path", "hooks").strip()
+        p = Path(path)
+        return p if p.is_absolute() else self.root / p
+
+    # -- mutations used by pull/snapshot -----------------------------------
+    def stash_push_untracked(self) -> bool:
+        """``git stash -u``; True when something was actually stashed."""
+        proc = self.run("stash", "push", "-u", ok_codes=(0, 1))
+        return proc.returncode == 0 and b"No local changes to save" not in proc.stdout
+
+    def stash_pop(self) -> None:
+        self.run("stash", "pop", "-q")
+
+    @contextmanager
+    def temporary_worktree(self, ref: str) -> Iterator[Path]:
+        """Check ``ref`` out into a throwaway detached worktree, then remove it.
+
+        The worktree shares the object store, so only the working copy is written
+        to disk. Reading upload contents from it isolates a deploy from edits made
+        to the live working tree while the transfer is running.
+        """
+        parent = Path(tempfile.mkdtemp(prefix="git-ftp-worktree-"))
+        tree = parent / "tree"  # must not pre-exist: git worktree add creates it
+        try:
+            self.run("worktree", "add", "--detach", "--quiet", str(tree), ref)
+        except GitError:
+            shutil.rmtree(parent, ignore_errors=True)
+            raise
+        try:
+            yield tree
+        finally:
+            self.run("worktree", "remove", "--force", str(tree), ok_codes=())
+            self.run("worktree", "prune", ok_codes=())
+            shutil.rmtree(parent, ignore_errors=True)
+
+    def add_all(self) -> None:
+        self.run("add", "--all")
+
+    def add_dot(self) -> None:
+        self.run("add", ".")
+
+    def commit(
+        self, subject: str, body: str | None = None, quiet: bool = True, allow_empty: bool = False
+    ) -> bool:
+        args = ["commit", "-m", subject]
+        if allow_empty:
+            args.append("--allow-empty")
+        if body:
+            args += ["-m", body]
+        if quiet:
+            args.append("-q")
+        proc = self.run(*args, ok_codes=())
+        return proc.returncode == 0
+
+    def diff_head_name_status(self) -> str:
+        return self.out("diff", "HEAD", "--name-status")
+
+    def merge(self, sha: str, no_commit: bool) -> int:
+        args = ["merge"]
+        if no_commit:
+            args += ["--no-commit", "--no-ff"]
+        args.append(sha)
+        return self.run(*args, ok_codes=(), inherit_stdio=True).returncode
+
+    def show(self, sha: str) -> int:
+        return self.run("show", sha, ok_codes=(), inherit_stdio=True).returncode
+
+    def log(self, sha: str) -> int:
+        return self.run("log", sha, ok_codes=(), inherit_stdio=True).returncode

gitftp/hooks.py

@@ -0,0 +1,30 @@
+"""pre-ftp-push and post-ftp-push hooks (upstream's experimental interface)."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Sequence
+
+from gitftp.gitrepo import GitRepo
+from gitftp.output import Output
+
+PRE_PUSH = "pre-ftp-push"
+POST_PUSH = "post-ftp-push"
+
+
+def run_hook(
+    repo: GitRepo, name: str, args: Sequence[str], stdin: bytes, out: Output
+) -> int | None:
+    """Run ``<hooks dir>/<name>`` if it exists and is executable; None when absent."""
+    path = repo.hooks_dir() / name
+    if not path.is_file() or not os.access(path, os.X_OK):
+        return None
+    out.debug(f"Running hook {name}.")
+    proc = subprocess.run(
+        [str(path), *args],
+        cwd=repo.root,
+        input=stdin,
+        check=False,
+    )
+    return proc.returncode

gitftp/ignore.py

@@ -0,0 +1,83 @@
+""".git-ftp-ignore: shell-glob patterns matched against the whole git path.
+
+Upstream matches with a bash ``case`` statement, so ``*`` and ``?`` also match
+``/`` and the pattern must cover the entire path (``config/*`` ignores
+``config/a/b`` but ``foo.txt`` does not ignore ``dir/foo.txt``).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+IGNORE_FILE = ".git-ftp-ignore"
+
+
+def glob_to_regex(pattern: str) -> re.Pattern[str]:
+    """Translate a bash ``case`` glob into an anchored regex."""
+    i, n = 0, len(pattern)
+    out = ["^"]
+    while i < n:
+        c = pattern[i]
+        i += 1
+        if c == "*":
+            out.append(".*")
+        elif c == "?":
+            out.append(".")
+        elif c == "\\" and i < n:
+            out.append(re.escape(pattern[i]))
+            i += 1
+        elif c == "[":
+            j = i
+            if j < n and pattern[j] in "!^":
+                j += 1
+            if j < n and pattern[j] == "]":
+                j += 1
+            while j < n and pattern[j] != "]":
+                j += 1
+            if j >= n:
+                out.append(re.escape(c))
+            else:
+                body = pattern[i:j]
+                i = j + 1
+                if body and body[0] in "!^":
+                    body = "^" + body[1:]
+                body = body.replace("\\", "\\\\")
+                out.append(f"[{body}]")
+        else:
+            out.append(re.escape(c))
+    out.append("$")
+    return re.compile("".join(out), re.DOTALL)
+
+
+class IgnoreRules:
+    def __init__(self, patterns: Iterable[str] = ()) -> None:
+        self.patterns = [p for p in patterns if p]
+        self._regexes = [glob_to_regex(p) for p in self.patterns]
+
+    @classmethod
+    def parse(cls, text: str) -> IgnoreRules:
+        patterns = []
+        for line in text.splitlines():
+            line = line.rstrip("\r")
+            if not line.strip() or line.startswith("#"):
+                continue
+            patterns.append(line)
+        return cls(patterns)
+
+    @classmethod
+    def load(cls, root: Path) -> IgnoreRules:
+        path = root / IGNORE_FILE
+        if not path.is_file():
+            return cls()
+        return cls.parse(path.read_text(encoding="utf-8", errors="surrogateescape"))
+
+    def __len__(self) -> int:
+        return len(self.patterns)
+
+    def matches(self, path: str) -> bool:
+        return any(r.match(path) for r in self._regexes)
+
+    def filter(self, paths: Iterable[str]) -> list[str]:
+        return [p for p in paths if not self.matches(p)]

gitftp/include.py

@@ -0,0 +1,94 @@
+""".git-ftp-include: upload untracked files.
+
+Formats:
+    !target              always upload ``target``
+    target:source        upload ``target`` when tracked ``source`` changed
+    target:/source       ``source`` is relative to the repository root even with --syncroot
+
+A ``target`` that is a directory expands to every file below it. A target that
+no longer exists locally is deleted remotely (directories excepted).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from gitftp.gitrepo import GitRepo
+from gitftp.output import Output
+
+INCLUDE_FILE = ".git-ftp-include"
+
+
+@dataclass(frozen=True)
+class IncludeRule:
+    target: str
+    source: str | None
+    always: bool
+
+
+def parse_rules(text: str) -> list[IncludeRule]:
+    rules = []
+    for raw in text.splitlines():
+        line = raw.rstrip("\r")
+        if not line.strip() or line.startswith("#"):
+            continue
+        if line.startswith("!"):
+            rules.append(IncludeRule(target=line[1:], source=None, always=True))
+        elif ":" in line:
+            target, _, source = line.partition(":")
+            rules.append(IncludeRule(target=target, source=source, always=False))
+    return rules
+
+
+def load_rules(root: Path) -> list[IncludeRule]:
+    path = root / INCLUDE_FILE
+    if not path.is_file():
+        return []
+    return parse_rules(path.read_text(encoding="utf-8", errors="surrogateescape"))
+
+
+def resolve_source(source: str, syncroot: str) -> str:
+    if source.startswith("/"):
+        return source.lstrip("/")
+    return f"{syncroot}{source}"
+
+
+def _walk_files(root: Path, target: str) -> list[str]:
+    base = root / target
+    files = []
+    for dirpath, _dirs, names in os.walk(base):
+        for name in names:
+            rel = Path(dirpath, name).relative_to(root).as_posix()
+            files.append(rel)
+    return sorted(files)
+
+
+def expand(
+    rules: list[IncludeRule],
+    repo: GitRepo,
+    syncroot: str,
+    against: str,
+    out: Output,
+) -> tuple[list[str], list[str]]:
+    """Return (uploads, deletes) contributed by the include rules."""
+    uploads: list[str] = []
+    deletes: list[str] = []
+    for rule in rules:
+        if not rule.always:
+            assert rule.source is not None
+            source = resolve_source(rule.source, syncroot)
+            if not repo.diff_quiet_changed(against, source):
+                continue
+        target = rule.target
+        local = repo.root / target
+        if local.is_dir():
+            uploads.extend(_walk_files(repo.root, target.rstrip("/")))
+        elif local.is_file():
+            uploads.append(target)
+        elif target.endswith("/"):
+            out.debug(f"Deletion of directory {target} is not supported.")
+        else:
+            deletes.append(target)
+    return uploads, deletes

gitftp/lock.py

@@ -0,0 +1,94 @@
+"""The remote lock file ``git-ftp.lck``.
+
+Content: ``<sha>\\n<user>@<host> on <RFC 2822 date>``. Upstream wrote a literal
+backslash-n (``echo`` without ``-e``); both forms are accepted when reading.
+"""
+
+from __future__ import annotations
+
+import getpass
+import socket
+from datetime import datetime, timezone
+from email.utils import format_datetime
+
+from gitftp.errors import RemoteLockedError, UploadError
+from gitftp.output import Output
+from gitftp.transport.base import RemoteNotFound, Transport
+
+LOCK_FILE = "git-ftp.lck"
+
+
+def parse(data: bytes) -> tuple[str, str]:
+    """Return (sha, holder) from a lock file, tolerant of upstream's literal ``\\n``."""
+    text = data.decode("utf-8", "replace")
+    if "\n" not in text and "\\n" in text:
+        text = text.replace("\\n", "\n", 1)
+    lines = text.splitlines()
+    sha = lines[0].strip() if lines else ""
+    holder = lines[1].strip() if len(lines) > 1 else ""
+    return sha, holder
+
+
+def holder_message(now: datetime | None = None) -> str:
+    when = now or datetime.now(timezone.utc)
+    try:
+        user = getpass.getuser()
+    except Exception:
+        user = "unknown"
+    return f"{user}@{socket.getfqdn()} on {format_datetime(when)}"
+
+
+class RemoteLock:
+    def __init__(
+        self,
+        transport: Transport,
+        local_sha: str,
+        *,
+        enabled: bool,
+        force: bool,
+        dry_run: bool,
+        out: Output,
+    ) -> None:
+        self.transport = transport
+        self.local_sha = local_sha
+        self.enabled = enabled
+        self.force = force
+        self.dry_run = dry_run
+        self.out = out
+        self.held = False
+
+    def check(self) -> None:
+        self.out.debug("Checking remote lock.")
+        try:
+            data = self.transport.get(LOCK_FILE)
+        except RemoteNotFound:
+            return
+        sha, holder = parse(data)
+        if sha and sha != self.local_sha:
+            raise RemoteLockedError(f"Remote locked by {holder}.")
+
+    def acquire(self) -> None:
+        """Check and write the lock; only with ``--lock``, as upstream."""
+        if not self.enabled:
+            return
+        if not self.force:
+            self.check()
+        if self.dry_run:
+            return
+        self.out.debug("Creating remote lock.")
+        content = f"{self.local_sha}\n{holder_message()}\n".encode()
+        try:
+            self.transport.put_bytes(content, LOCK_FILE)
+        except UploadError as e:
+            raise UploadError(f"Could not upload lock file. {e}") from e
+        self.held = True
+
+    def release(self) -> None:
+        if not self.held:
+            return
+        self.out.debug("Releasing remote lock.")
+        try:
+            self.transport.delete(LOCK_FILE)
+        except Exception as e:
+            self.out.warn(f"Could not remove remote lock: {e}")
+        self.held = False