livery-git 0.1.0__py3-none-any.whl

livery/git/__init__.py

@@ -0,0 +1,276 @@
+"""Git access for the livery ecosystem, every call a function of the repository's root.
+
+Reach for the named reader or mover first: [livery.git.position][]
+for where a checkout stands, [livery.git.fetch][] and
+[livery.git.push_force][] for the network, [livery.git.commit_all][]
+for a commit. [livery.git.run][] and [livery.git.call][] are the door
+for a subcommand no function names yet: `run` raises
+[livery.git.GitError][] on a non-zero exit, `call` returns the result
+whatever the code.
+
+Nothing is held between calls, so a function may be called from any
+process at any time and answers what git holds at that moment.
+
+The package is also a footman plugin, `plugin("livery.git")`: its hook
+gives every task's git the ssh command that shares one connection per
+host ([livery.git.ssh_environment][]), the tools' identity when the
+person has none ([livery.git.tool_identity][]), an editor that never
+opens, and what a task marks for itself with [livery.git.identity][]
+and [livery.git.unsigned][].
+
+The state store, JSON rows on git refs, is here too: a
+[livery.git.StateStore][] built with a caller's policy, the
+[livery.git.Series][] and [livery.git.Keyed][] declarations that read
+and write through it, and the snapshots that make a run's reads one
+listing and one fetch.
+"""
+
+from __future__ import annotations
+
+from livery.git._environment import (
+    config_environment,
+    identity_environment,
+    tool_identity,
+)
+from livery.git._marks import identity, unsigned
+from livery.git._ops import (
+    GitError,
+    add,
+    add_remote,
+    amend_all,
+    any_head,
+    author_email,
+    behind_base,
+    call,
+    changed_between,
+    changed_paths,
+    clean,
+    commit_all,
+    commit_message,
+    commits_since,
+    config_get,
+    config_regexp,
+    config_set,
+    config_unset,
+    conflicts_with_base,
+    create_branch,
+    current_branch,
+    delete_branch,
+    detach,
+    dirty_paths,
+    fetch,
+    fetch_tag,
+    fetch_tags,
+    file_at,
+    files_in_commit,
+    first_parent_trees,
+    has_commits,
+    has_remote,
+    head_body,
+    head_message,
+    head_sha,
+    head_subject,
+    integrate,
+    is_ancestor,
+    is_clean,
+    last_commit_touching,
+    local_branch_exists,
+    local_branches,
+    log_paths,
+    ls_files,
+    ls_remote,
+    main_checkout,
+    merge_base,
+    merge_parents,
+    merge_tree,
+    object_id,
+    object_ids,
+    oneline,
+    position,
+    push,
+    push_force,
+    push_refspec,
+    recent_commits,
+    remote_branches,
+    remote_head,
+    remote_tags,
+    remote_url,
+    remotes,
+    reset_hard,
+    restore,
+    run,
+    set_remote_url,
+    sha_of,
+    staged_text,
+    subjects_ahead,
+    switch,
+    switch_new,
+    tag_dates,
+    tags,
+    tracking_branches,
+    tracks,
+    tree_diff,
+    unmerged_paths,
+    unpushed,
+    unstage,
+    working_tree_id,
+    worktree_add,
+    worktree_remove,
+)
+from livery.git._ssh import (
+    master_up,
+    record_unsupported,
+    remote_host,
+    ssh_command,
+    ssh_environment,
+    ssh_sockets,
+)
+from livery.git._store import (
+    FETCHED,
+    FETCHED_NAMESPACE,
+    LOCAL_NAMESPACE,
+    NAMESPACE,
+    RUN_PREFIX,
+    TRACE_NAMESPACE,
+    WHOLE,
+    Fetched,
+    Keyed,
+    Read,
+    Row,
+    Rows,
+    Series,
+    Skipped,
+    StateStore,
+    drop,
+    fetch_store,
+    fetched_snapshot,
+    list_refs,
+    put,
+    read,
+    remote_snapshot,
+    slug,
+    sweep,
+)
+
+__all__ = [
+    "FETCHED",
+    "FETCHED_NAMESPACE",
+    "LOCAL_NAMESPACE",
+    "NAMESPACE",
+    "RUN_PREFIX",
+    "TRACE_NAMESPACE",
+    "WHOLE",
+    "Fetched",
+    "GitError",
+    "Keyed",
+    "Read",
+    "Row",
+    "Rows",
+    "Series",
+    "Skipped",
+    "StateStore",
+    "__version__",
+    "add",
+    "add_remote",
+    "amend_all",
+    "any_head",
+    "author_email",
+    "behind_base",
+    "call",
+    "changed_between",
+    "changed_paths",
+    "clean",
+    "commit_all",
+    "commit_message",
+    "commits_since",
+    "config_environment",
+    "config_get",
+    "config_regexp",
+    "config_set",
+    "config_unset",
+    "conflicts_with_base",
+    "create_branch",
+    "current_branch",
+    "delete_branch",
+    "detach",
+    "dirty_paths",
+    "drop",
+    "fetch",
+    "fetch_store",
+    "fetch_tag",
+    "fetch_tags",
+    "fetched_snapshot",
+    "file_at",
+    "files_in_commit",
+    "first_parent_trees",
+    "has_commits",
+    "has_remote",
+    "head_body",
+    "head_message",
+    "head_sha",
+    "head_subject",
+    "identity",
+    "identity_environment",
+    "integrate",
+    "is_ancestor",
+    "is_clean",
+    "last_commit_touching",
+    "list_refs",
+    "local_branch_exists",
+    "local_branches",
+    "log_paths",
+    "ls_files",
+    "ls_remote",
+    "main_checkout",
+    "master_up",
+    "merge_base",
+    "merge_parents",
+    "merge_tree",
+    "object_id",
+    "object_ids",
+    "oneline",
+    "position",
+    "push",
+    "push_force",
+    "push_refspec",
+    "put",
+    "read",
+    "recent_commits",
+    "record_unsupported",
+    "remote_branches",
+    "remote_head",
+    "remote_host",
+    "remote_snapshot",
+    "remote_tags",
+    "remote_url",
+    "remotes",
+    "reset_hard",
+    "restore",
+    "run",
+    "set_remote_url",
+    "sha_of",
+    "slug",
+    "ssh_command",
+    "ssh_environment",
+    "ssh_sockets",
+    "staged_text",
+    "subjects_ahead",
+    "sweep",
+    "switch",
+    "switch_new",
+    "tag_dates",
+    "tags",
+    "tool_identity",
+    "tracking_branches",
+    "tracks",
+    "tree_diff",
+    "unmerged_paths",
+    "unpushed",
+    "unsigned",
+    "unstage",
+    "working_tree_id",
+    "worktree_add",
+    "worktree_remove",
+]
+
+__version__ = "0.1.0"

livery/git/_docs/index.md

@@ -0,0 +1,94 @@
+# livery-git
+
+Git access for the livery ecosystem. Every call is a function of the
+repository's root: `git.position(root)` says where a checkout stands,
+`git.fetch(root)` and `git.push_force(root, branch)` reach the network,
+`git.commit_all(root, message)` commits. A reader of refs, objects,
+history or config opens the repository's own files in-process, through
+dulwich, and starts no git; a mover, and a reader of the index, the
+working tree or the remote, runs the git the tool store pins, never one
+found on the path. Every function returns strings or raises `GitError`,
+with git's own words where git ran.
+
+```python
+from pathlib import Path
+
+from livery import git
+
+root = Path(".")
+branch, head = git.position(root)
+if git.conflicts_with_base(root, "main"):
+    raise SystemExit("resolve the conflict first")
+```
+
+Nothing is held between calls. A function answers what git holds at the
+moment it is called, so a flow that needs one fact twice reads it twice,
+and a function that moves the repository says so in its name: `fetch`,
+`push`, `commit_all`, `switch`, `integrate`.
+
+`git.run(root, *args)` and `git.call(root, *args)` are the door for a
+subcommand no function names: `run` raises on a non-zero exit, `call`
+returns the result whatever the code, for a caller that reads the exit
+code as an answer.
+
+## The plugin
+
+`plugin("livery.git")` in a project's `tasks.py` mounts the package as a
+footman plugin; a project that depends on `livery-git` directly gets it
+through footman's project rung, and every workshop project runs with it.
+Its one hook writes into each task's own environment, which the task's
+subprocesses see:
+
+- `GIT_SSH_COMMAND`, so every network call shares one ssh connection per
+  remote host: a master opens on the first call and lingers ten minutes
+  after the last, with its socket under the runner's data directory. A
+  `GIT_SSH_COMMAND` or `core.sshCommand` of your own wins, and a file named
+  `unsupported` in the socket directory turns it off with the words it
+  holds; delete the file to try again. `fm doctor` says which it is.
+- The tools' identity, `<prog>` at `<prog>@<prog>.invalid`, as author and
+  committer, when git's config names no `user.email`; a person's own
+  identity stands.
+- `GIT_EDITOR=true`, unless one is set already: no verb reads a message
+  from an editor.
+
+A task marks itself for the cases it knows better: `@git.identity(name,
+email)` commits as that identity whatever the config says, and
+`@git.unsigned` turns commit and tag signing off for the task's git. The
+plugin never turns signing off on its own.
+
+Any process of the same user may reuse the open connection for its
+window, without the agent's consent: the same trust boundary as
+`SSH_AUTH_SOCK`.
+
+## The state store
+
+JSON rows on git refs, in a namespace a default clone or fetch never
+downloads: `refs/workshop/*` on the remote and `refs/workshop-local/*`
+in the checkout's git directory. A `StateStore` is a checkout and the
+policy its builder gave it: whether this process is a CI run, the
+identity every commit carries, and the variable a published listing
+travels in. A `Series` declares one ref's rows and reads and writes
+through the store; a `Keyed` family declares one series per key.
+
+```python
+from livery import git
+
+store = git.StateStore(
+    root, in_ci=False, identity=("fm", "fm@fm.invalid"), snapshot_variable="MY_SNAPSHOT"
+)
+rows = git.Series("metrics", window=300)
+print(rows.rows(store).rows[:3])
+```
+
+A write is a compare-and-swap on the sha the read returned. Only the
+wire is a git process: a remote read is one fetch, a remote write one
+fetch and one push, a local read or write none, whatever the series
+holds, since every tree is read and every commit written in the
+checkout's own object store. A `remote_snapshot` block makes every read
+inside one listing and one fetch. `sweep` is the janitor. Every failure
+is a printed reason, never a boolean.
+
+## What is not here
+
+Porcelain that waits on a person, a signer, is the caller's to arrange:
+the functions pass git's own words back and never answer a prompt.

livery/git/_docs/nav.toml

@@ -0,0 +1,12 @@
+# This package's section of the workspace site, hand-authored.
+# Labels map to pages relative to this docs/ tree, or to nested
+# lists. Every authored page must appear here, and every entry must
+# name a real page. A generator owns a block between `# nav:begin
+# <name>` and `# nav:end <name>` markers (tasks, tools); the emitter's
+# own sections, changelog, coverage and api, are blocks too: place a
+# pair where one belongs, and a section without one lands after the
+# authored entries, changelog and coverage ahead of the tasks block,
+# api last.
+nav = [
+    { "Index" = "index.md" },
+]

livery/git/_environment.py

@@ -0,0 +1,50 @@
+"""The tools' identity, and git settings that ride the environment."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+
+def tool_identity(prog: str) -> tuple[str, str]:
+    """The name and address a tool called *prog* commits under.
+
+    For every commit a verb makes when the person has no identity of
+    their own: a release, a loop's scratch, the state store's rows.
+    The domain is `.invalid`, reserved for names that resolve nowhere.
+    """
+    return prog, f"{prog}@{prog}.invalid"
+
+
+def identity_environment(name: str, email: str) -> dict[str, str]:
+    """The variables that make every commit and tag by *name* and *email*.
+
+    Author and committer both: git reads the four variables ahead of
+    any config, so a checkout's own identity is left as it is.
+    """
+    return {
+        "GIT_AUTHOR_NAME": name,
+        "GIT_AUTHOR_EMAIL": email,
+        "GIT_COMMITTER_NAME": name,
+        "GIT_COMMITTER_EMAIL": email,
+    }
+
+
+def config_environment(
+    environ: Mapping[str, str], pairs: Sequence[tuple[str, str]]
+) -> dict[str, str]:
+    """*pairs* as git configuration riding the environment, after what it carries.
+
+    git reads `GIT_CONFIG_COUNT` with a key and a value per index, so an
+    entry the outer environment already carries keeps its index and
+    these follow it. The mapping returned holds the new entries and the
+    count; merge it over *environ*.
+    """
+    raw = environ.get("GIT_CONFIG_COUNT", "")
+    count = int(raw) if raw.isdigit() else 0
+    made: dict[str, str] = {}
+    for offset, (key, value) in enumerate(pairs):
+        index = count + offset
+        made[f"GIT_CONFIG_KEY_{index}"] = key
+        made[f"GIT_CONFIG_VALUE_{index}"] = value
+    made["GIT_CONFIG_COUNT"] = str(count + len(pairs))
+    return made

livery/git/_marks.py

@@ -0,0 +1,34 @@
+"""Marks a task sets on itself for the git plugin: an identity, or unsigned commits.
+
+A mark is an attribute on the task's function, written by a decorator
+below or above `@task` and read by the plugin's hook through the
+handle's `task.mark(...)`. The decorators import nothing of footman,
+so a module that only marks its tasks stays importable without it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+_F = TypeVar("_F", bound=Callable[..., object])
+
+#: The attribute names the plugin's hook reads off a task.
+IDENTITY_MARK = "livery_git_identity"
+UNSIGNED_MARK = "livery_git_unsigned"
+
+
+def identity(name: str, email: str) -> Callable[[_F], _F]:
+    """Make the decorated task's commits carry *name* and *email*, whatever git says."""
+
+    def mark(fn: _F) -> _F:
+        setattr(fn, IDENTITY_MARK, (name, email))
+        return fn
+
+    return mark
+
+
+def unsigned(fn: _F) -> _F:
+    """Turn commit and tag signing off for the decorated task's git."""
+    setattr(fn, UNSIGNED_MARK, True)
+    return fn