livery.git¶
livery.git ¶
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.
Classes:
| Name | Description |
|---|---|
GitError |
A git command failed; the message carries git's words verbatim. |
Fetched |
What |
Keyed |
A family of series under one prefix, one ref per key. |
Read |
What a read found: the files, the lease, and whether it could answer. |
Row |
One row of a series: the file it came from and its fields. |
Rows |
What a series read found: the rows, what it skipped, and whether it could answer. |
Series |
A shared ref's declaration: its rows' schema, its window, and who may write it. |
Skipped |
A file a read passed over: its name and why. |
StateStore |
A checkout's state store and the policy its builder gave it. |
Functions:
| Name | Description |
|---|---|
config_environment |
pairs as git configuration riding the environment, after what it carries. |
identity_environment |
The variables that make every commit and tag by name and email. |
tool_identity |
The name and address a tool called prog commits under. |
identity |
Make the decorated task's commits carry name and email, whatever git says. |
unsigned |
Turn commit and tag signing off for the decorated task's git. |
add |
Stage path as it stands in the working tree, a removal included. |
add_remote |
Add the remote name at url. |
amend_all |
Stage everything and fold it into HEAD, message kept. |
any_head |
branch's head sha: local when present, else the remote's, else empty. |
author_email |
The address the next commit in root would carry as its author. |
behind_base |
How many commits |
blob_at |
The text of the blob digest names in the object store; empty when none. |
call |
Run git with args in root and return the result whatever the exit code. |
changed_between |
The paths matching patterns that differ between old and new. |
changed_paths |
Repo-relative paths this branch touches, committed or not. |
clean |
Remove every untracked and ignored file but the patterns in keep; the paths. |
commit_all |
Stage everything and commit with message. |
commit_message |
ref's full commit message, subject and body. |
commits_since |
How many commits HEAD carries beyond ref. |
config_get |
The repository's git config value for key; empty when unset or no repository. |
config_regexp |
Every config key matching pattern, with its value, read in-process. |
config_set |
Set key to value in the repository's git config. |
config_unset |
Remove key from the repository's git config; a key already absent is fine. |
conflicts_with_base |
Whether merging |
create_branch |
Create and switch to name. |
current_branch |
The checked-out branch name; empty when detached. |
delete_branch |
Delete the local branch name, merged or not. |
detach |
Check ref out as a detached HEAD. |
dirty_paths |
The paths the working tree changed, staged or not, in status order. |
fetch |
Freshen |
fetch_tag |
Take tag from origin as it is there, replacing the one held here. |
fetch_tags |
Freshen |
file_at |
The contents of path as committed at ref; empty when absent. |
files_in_commit |
The paths the commit at ref changed, against its first parent. |
first_parent_trees |
HEAD's tree id and its first-parent ancestors', newest first. |
has_commits |
Whether HEAD names a commit; false with no commit or no repository. |
has_remote |
Whether this clone has a remote called name; any other failure raises. |
head_body |
HEAD's commit body, without the subject. |
head_message |
HEAD's commit subject and its body, read in-process. |
head_sha |
The commit HEAD points at. |
head_subject |
HEAD's commit subject. |
integrate |
Merge |
is_ancestor |
Whether ancestor reaches descendant in this clone. |
is_clean |
Whether the working tree has no changes, staged or not. |
last_commit_touching |
The newest commit at or before ref that changed path; empty if none. |
local_branch_exists |
Whether branch exists locally. |
local_branches |
Local branch names under prefix ( |
log_paths |
The subjects in span touching paths ( |
ls_files |
The paths git lists under paths (the whole tree when none), sorted. |
ls_remote |
The refs remote holds among refs (every one when none is named), by sha. |
main_checkout |
The repository's main checkout, the same from any of its worktrees. |
merge_base |
The merge base of HEAD and |
merge_parents |
HEAD's two parents when HEAD is a merge: the base, then the head merged in. |
merge_tree |
The tree a merge of head onto base yields, written to this clone. |
object_id |
The object id spec names ( |
object_ids |
The object ids ref holds at paths, read in-process. |
oneline |
The commits in span ( |
position |
The checked-out branch name, empty when detached, and HEAD's commit. |
push |
Push branch to remote, setting upstream; force replaces what is there. |
push_force |
Force-push branch, leased on the last-seen remote state. |
push_refspec |
Push refspec to remote as given: a tag, or |
recent_commits |
(sha, subject) for the newest count commits reachable from ref. |
remote_branches |
Branch names under prefix on origin, asked of the remote. |
remote_head |
|
remote_tags |
Tag names on origin, asked of the remote. |
remote_url |
The URL of the remote name. |
remotes |
The names of the repository's remotes. |
reset_hard |
Move the branch, the index and the working tree to ref; every change goes. |
restore |
Put paths back as HEAD has them; empty, or git's words when it could not. |
run |
Run git with args in root and return its standard output. |
set_remote_url |
Point the remote name at url. |
sha_of |
The commit ref resolves to; empty when this checkout cannot. |
staged_text |
path's text at index stage of a conflict; empty when that side has none. |
subjects_ahead |
The subjects of the commits HEAD carries beyond |
switch |
Switch to the existing branch name. |
switch_new |
Create or reset the branch name at start (HEAD when empty); switch to it. |
tag_dates |
Every tag under prefix with the date it was made, |
tags |
Every tag name the repository knows. |
tracking_branches |
Branch names under prefix among origin's remote-tracking refs. |
tracks |
Whether the repository holds the object spec names: |
tree_diff |
The paths differing between the trees old and new. |
unmerged_paths |
The paths a stopped merge or rebase left conflicted, as git names them. |
unpushed |
The commits on any local branch that origin holds on no branch, one line each. |
unstage |
Take path out of the index and leave the file; an untracked path is fine. |
working_tree_id |
The tree id of the working tree as it stands. |
worktree_add |
Check ref out as a linked worktree at path, detached under detach. |
worktree_remove |
Remove the linked worktree at path, its changes with it. |
master_up |
Whether a master for url's host is up under socket_dir. |
record_unsupported |
Turn multiplexing off under socket_dir with words; the file written. |
remote_host |
The user, host and port an ssh remote url names; None for any other transport. |
ssh_command |
The |
ssh_environment |
The environment that multiplexes a spawned git's ssh, or why not. |
ssh_sockets |
Where the plugin keeps its sockets: |
drop |
Delete ref, on origin or in the checkout; |
fetch_store |
Mirror the row series series under |
fetched_snapshot |
Read the remote namespace from the checkout's mirror of origin, for the block. |
list_refs |
The refs under prefix by sha, remote or local; |
put |
Write files onto ref, keeping what it already holds; |
read |
Read ref's files, saying whether a miss is absence or failure. |
remote_snapshot |
Read the remote namespace through one listing for the block. |
slug |
name as a ref-safe and file-safe token: every other character is a dash. |
sweep |
The store's janitor: every series bounded, every orphan dropped; the lines. |
Attributes:
| Name | Type | Description |
|---|---|---|
FETCHED |
|
|
FETCHED_NAMESPACE |
|
|
LOCAL_NAMESPACE |
|
|
NAMESPACE |
|
|
RUN_PREFIX |
|
|
TRACE_NAMESPACE |
|
|
WHOLE |
tuple[str, ...]
|
|
__version__ |
|
FETCHED
module-attribute
¶
FETCHED = Series('fetched', window=1, ci_only=False, schema=2, local=True)
__all__
module-attribute
¶
__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', 'blob_at', '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']
GitError ¶
Bases: RuntimeError
A git command failed; the message carries git's words verbatim.
Fetched ¶
Bases: NamedTuple
What fetch_store did: the mirror's size, why it failed, the refs that moved.
Attributes:
| Name | Type | Description |
|---|---|---|
held |
int
|
The refs the mirror holds after the fetch; zero when it failed. |
why |
str
|
Empty, or why the fetch or the stamp failed, in git's words. |
changed |
int
|
The refs this fetch added, moved or pruned; zero on a quiet origin. |
Keyed
dataclass
¶
Keyed(name: str, keys: tuple[str, ...], window: int | None = None, ci_only: bool = True, schema: int = 1, local: bool = False, namespace: str = '', stale_after: timedelta | None = None, current: Callable[[Path], set[tuple[str, ...]] | None] | None = None, linger: timedelta | None = None, keep: Callable[[Path], int | None] | None = None, holds_rows: bool = True, blobs: str = '')
A family of series under one prefix, one ref per key.
The coverage record keeps one series per base and leg, the
per-run halves one per run and leg. A family declares its key
parts once: series makes the series of one key, with every
part made ref-safe, and listed reads the keys the remote
holds, so no caller spells a ref of the family itself.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The family's name under the namespace ( |
keys |
tuple[str, ...]
|
The names of the key's parts, in ref order
( |
window |
int | None
|
Every series' window; |
ci_only |
bool
|
Whether only a CI run may write the family. |
schema |
int
|
The rows' schema, shared by every series. |
local |
bool
|
Whether every series of the family is local, as for a livery.git.Series. |
namespace |
str
|
The prefix every series of the family lives under, as for a livery.git.Series. |
stale_after |
timedelta | None
|
How long a key's ref may live, by its commit
time, before the janitor drops it as an orphan; |
current |
Callable[[Path], set[tuple[str, ...]] | None] | None
|
The keys the world still produces, from the checkout
root, or |
linger |
timedelta | None
|
How long a key outside the current ones stays, by its
ref's commit time, before the janitor drops it, so a run
in flight that relies on it can still read it: a branch's
coverage record is read by main's run for the squash that
merged it, minutes after the branch is gone. |
keep |
Callable[[Path], int | None] | None
|
How many values of the key's first part the family
keeps, read from the checkout root; the rest go. The parts
are ranked by value, as numbers where they are numbers, so
a forge's run id ranks by age without reading a commit.
For a family keyed by a run, this is how many runs are
kept. |
holds_rows |
bool
|
Whether the family's series hold JSON rows the
janitor bounds like any other series. A family of blobs (a
leg's trace) says false: its files are not rows, and
|
blobs |
str
|
The directory of every series' blobs, as for a livery.git.Series. |
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
series |
The series of one key, one part per declared key name. |
at |
The series of a key as its ref spells it, every part verbatim. |
listed |
The keys the remote holds under the leading parts head. |
current
class-attribute
instance-attribute
¶
__post_init__ ¶
series ¶
The series of one key, one part per declared key name.
Raises:
| Type | Description |
|---|---|
ValueError
|
When key has another number of parts. |
at ¶
The series of a key as its ref spells it, every part verbatim.
listed returns keys as their refs spell them, and a key
written before the family made its parts ref-safe may spell a
part another way; series would re-spell it and name a ref
that does not exist. A listed key comes back through here.
Raises:
| Type | Description |
|---|---|
ValueError
|
When key has another number of parts. |
Source code in packages/git/src/livery/git/_store.py
listed ¶
listed(store: StateStore, *head: str) -> list[tuple[str, ...]] | None
The keys the remote holds under the leading parts head.
None when the remote cannot be listed. A ref under the
prefix with another number of parts is not the family's and
is left out.
Source code in packages/git/src/livery/git/_store.py
Read
dataclass
¶
Read(files: dict[str, str] | None, sha: str | None, failed: bool, reason: str = '', names: tuple[str, ...] = ())
What a read found: the files, the lease, and whether it could answer.
Attributes:
| Name | Type | Description |
|---|---|---|
files |
dict[str, str] | None
|
The tree's files by name, or |
sha |
str | None
|
The commit the ref points at on the remote, the lease a
write carries; |
failed |
bool
|
Whether |
reason |
str
|
The transport's words when it could not answer. |
names |
tuple[str, ...]
|
The name of every file the tree holds, read or not, sorted; empty when there is nothing to read. |
Row
dataclass
¶
Rows
dataclass
¶
Rows(rows: tuple[Row, ...], skipped: tuple[Skipped, ...] = (), failed: bool = False, reason: str = '', unread: tuple[str, ...] = (), blobs: Mapping[str, str] = dict())
What a series read found: the rows, what it skipped, and whether it could answer.
Attributes:
| Name | Type | Description |
|---|---|---|
rows |
tuple[Row, ...]
|
The rows of the series' schema, newest first. |
skipped |
tuple[Skipped, ...]
|
One entry per file that is not such a row, naming the file and why; printing one gives the line. |
failed |
bool
|
Whether the transport could not answer for a ref that exists, or reach the remote at all. An absent ref reads as no rows and no failure. |
reason |
str
|
Why it could not answer, in the store's one wording. |
unread |
tuple[str, ...]
|
The files a read that named the ones it wants passed over, by name, never read. |
blobs |
Mapping[str, str]
|
The blobs the read was asked for, by name, each the
text its writer wrote (livery.git.Series's |
Series
dataclass
¶
Series(name: str, window: int | None = None, ci_only: bool = True, schema: int = 1, local: bool = False, age: timedelta | None = None, namespace: str = '', blobs: str = '')
A shared ref's declaration: its rows' schema, its window, and who may write it.
A series is one ref holding JSON rows of one schema, one file per
row. rows and row read, put writes; the store stamps the
schema and the time, keeps the window, and refuses what the
declaration forbids, so a caller never parses a row, checks a
schema, or trims a ref itself.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The ref's name under the namespace. |
window |
int | None
|
The newest rows kept after every write, by the time
the store stamped them; |
ci_only |
bool
|
Whether only a CI run may write it. Local runs read. |
schema |
int
|
The rows' schema. A reader skips a row of another version and names it; a new field is the same version, a changed meaning is the next. |
local |
bool
|
Whether the series lives in the checkout's git directory
under |
age |
timedelta | None
|
How long a row stays before the janitor drops it, by the
store's stamp; |
namespace |
str
|
The prefix the ref lives under, when it is neither
the shared namespace nor the local one:
livery.git.TRACE_NAMESPACE is the one
such prefix, pushed to origin and mirrored by nothing.
Empty means the class |
blobs |
str
|
The directory, ending in a slash, of the files the
series keeps beside its rows as their writer wrote them,
such as a file named by its own content ( |
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
blob |
Whether the file name is one of the series' blobs, not a row. |
rows |
Every row of the series, newest first, with what was skipped and why. |
row |
The row in the file name. |
file |
The text of the file name on the ref, or why it could not be read. |
put |
Write rows, stamped, and blobs by file name; |
__post_init__ ¶
Source code in packages/git/src/livery/git/_store.py
blob ¶
rows ¶
rows(store: StateStore, *, only: Callable[[str], bool] | None = None) -> Rows
Every row of the series, newest first, with what was skipped and why.
An absent ref is no rows and no failure. A ref the transport
could not read is a failure with its reason, so every caller
falls open the same way. A file that does not parse or is of
another schema is skipped and named, and the rest stand. A blob
the read accepts comes back as text in blobs. With
only, the files whose names it accepts are read and parsed,
and every other file is named in unread, never read: a
series of large rows answers a reader of a few of them at the
cost of those few.
Source code in packages/git/src/livery/git/_store.py
row ¶
row(store: StateStore, name: str) -> tuple[Row | None, str]
The row in the file name.
(None, "") when the ref or the file is absent, and
(None, reason) when the ref could not be read or the file
is not a row of the schema. The ref's other files are not read.
Source code in packages/git/src/livery/git/_store.py
file ¶
file(store: StateStore, name: str) -> tuple[str | None, str]
The text of the file name on the ref, or why it could not be read.
For a series whose files are not rows: a leg's trace, kept as
its writer wrote it. (None, "") is absence, of the ref or
of the file. The ref's other files are not read.
Source code in packages/git/src/livery/git/_store.py
put ¶
put(store: StateStore, rows: Mapping[str, Mapping[str, Any]], *, message: str, remove: Iterable[str] = (), blobs: Mapping[str, str] | None = None) -> str
Write rows, stamped, and blobs by file name; "" or the reason.
Every row is written with the schema and the time stamped on
it, and the stamp wins over a schema or when the row
carries. Each blob is written as the text given, so a blob of
the same text is the same object git already holds. The files
the series already holds stand, less the file names in
remove, so a caller replacing a record in place names what
goes and puts what changed.
The window keeps the newest rows by their stamps, so a series
keyed by something other than time (a tree id) keeps its
newest too. A write the declaration forbids is refused with
the rule, and so is a row named as a blob, or a blob named
outside the series' blobs; the transport's refusals come
back as they are.
Source code in packages/git/src/livery/git/_store.py
Skipped
dataclass
¶
StateStore
dataclass
¶
StateStore(root: Path, in_ci: bool, identity: tuple[str, str], snapshot_variable: str, prog: str = 'fm')
A checkout's state store and the policy its builder gave it.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
Path
|
The checkout whose origin holds the remote namespace and whose git directory holds the local one. |
in_ci |
bool
|
Whether this process is a CI run: a put to a series
declared |
identity |
tuple[str, str]
|
The name and address every commit the store makes carries, author and committer. |
snapshot_variable |
str
|
The environment variable a published listing's path travels in, from a parent process to its children. |
prog |
str
|
The runner's command name, for the words a refusal
gives a person ( |
config_environment ¶
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.
Source code in packages/git/src/livery/git/_environment.py
identity_environment ¶
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.
Source code in packages/git/src/livery/git/_environment.py
tool_identity ¶
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.
Source code in packages/git/src/livery/git/_environment.py
identity ¶
Make the decorated task's commits carry name and email, whatever git says.
Source code in packages/git/src/livery/git/_marks.py
unsigned ¶
add ¶
add_remote ¶
any_head ¶
branch's head sha: local when present, else the remote's, else empty.
A root that is no repository has no local branch, so the remote is asked.
Source code in packages/git/src/livery/git/_ops.py
author_email ¶
The address the next commit in root would carry as its author.
Resolved as git resolves it, the environment's GIT_AUTHOR_EMAIL
ahead of the config, so a checkout whose identity rides the
environment answers the same as one configured.
Source code in packages/git/src/livery/git/_ops.py
behind_base ¶
How many commits origin/<base> is ahead of HEAD.
blob_at ¶
The text of the blob digest names in the object store; empty when none.
digest is a full blob id, forty hex digits. The blob is read by its id alone, so a content no tree names any more, one a change replaced, is still read while the object store holds it. Empty when the store holds no such object, when digest is no full id, and when the id names a tree or a commit.
Raises:
| Type | Description |
|---|---|
GitError
|
When root is not inside a repository. |
Source code in packages/git/src/livery/git/_ops.py
call ¶
Run git with args in root and return the result whatever the exit code.
The one door every git call takes. A caller that treats a non-zero
exit as an answer reads the code; one that treats it as a failure
calls livery.git.run instead. Each argument reaches the tool
handle as the object it is, so a livery.footman.Secret stays
marked, and every command line footman shows, a profile trace
included, carries *** in its place.
Source code in packages/git/src/livery/git/_ops.py
changed_between ¶
The paths matching patterns that differ between old and new.
Repo-relative, as git prints them; empty when nothing matching changed. A pattern is a path or a glob as git reads one.
Source code in packages/git/src/livery/git/_ops.py
changed_paths ¶
Repo-relative paths this branch touches, committed or not.
The committed half diffs against the merge base with
origin/<base>; the uncommitted half comes from the status
listing, renames counted on both sides and untracked files
named one by one (a collapsed directory reads as neither
prose nor package).
Source code in packages/git/src/livery/git/_ops.py
clean ¶
Remove every untracked and ignored file but the patterns in keep; the paths.
Under dry_run nothing goes and the paths are what would.
Source code in packages/git/src/livery/git/_ops.py
commit_all ¶
commit_message ¶
ref's full commit message, subject and body.
Source code in packages/git/src/livery/git/_ops.py
commits_since ¶
config_get ¶
The repository's git config value for key; empty when unset or no repository.
Read in-process from the config files git itself reads.
Source code in packages/git/src/livery/git/_ops.py
config_regexp ¶
Every config key matching pattern, with its value, read in-process.
Empty when nothing matches or root is no repository; a key set twice keeps its last value.
Source code in packages/git/src/livery/git/_ops.py
config_set ¶
config_unset ¶
Remove key from the repository's git config; a key already absent is fine.
conflicts_with_base ¶
Whether merging origin/<base> into HEAD would conflict.
Probed with git merge-tree so nothing in the working tree
moves; exit 1 with conflicts is the answer, any other failure
raises.
Source code in packages/git/src/livery/git/_ops.py
create_branch ¶
current_branch ¶
delete_branch ¶
detach ¶
dirty_paths ¶
The paths the working tree changed, staged or not, in status order.
fetch ¶
Freshen origin/*, or the refs named, from origin.
prune drops the remote-tracking refs origin no longer has, so a branch the forge deleted does not linger; force takes a ref that moved to an unrelated commit, a receipt tag recut by a later wave.
Source code in packages/git/src/livery/git/_ops.py
fetch_tag ¶
Take tag from origin as it is there, replacing the one held here.
fetch_tags ¶
fetch_tags(root: Path) -> None
Freshen origin/* and take every tag origin holds.
A tag cut on the remote at a commit this clone already has is fetched here too, which a plain fetch's tag following does not promise.
Source code in packages/git/src/livery/git/_ops.py
file_at ¶
The contents of path as committed at ref; empty when absent.
Source code in packages/git/src/livery/git/_ops.py
files_in_commit ¶
The paths the commit at ref changed, against its first parent.
Source code in packages/git/src/livery/git/_ops.py
first_parent_trees ¶
HEAD's tree id and its first-parent ancestors', newest first.
count commits deep at most.
Source code in packages/git/src/livery/git/_ops.py
has_commits ¶
Whether HEAD names a commit; false with no commit or no repository.
Source code in packages/git/src/livery/git/_ops.py
has_remote ¶
Whether this clone has a remote called name; any other failure raises.
Source code in packages/git/src/livery/git/_ops.py
head_body ¶
head_message ¶
HEAD's commit subject and its body, read in-process.
Source code in packages/git/src/livery/git/_ops.py
head_sha ¶
head_subject ¶
integrate ¶
Merge origin/<base> into the current branch, after a fetch.
A conflict raises livery.git.GitError with git's words and leaves the merging state in place for a person to resolve; re-running the caller after the resolution is the recovery.
Source code in packages/git/src/livery/git/_ops.py
is_ancestor ¶
Whether ancestor reaches descendant in this clone.
A commit this clone does not know cannot be an ancestor, so an unknown ancestor answers False rather than raising.
Source code in packages/git/src/livery/git/_ops.py
is_clean ¶
last_commit_touching ¶
The newest commit at or before ref that changed path; empty if none.
Source code in packages/git/src/livery/git/_ops.py
local_branch_exists ¶
local_branches ¶
Local branch names under prefix (workflow/), short form.
Source code in packages/git/src/livery/git/_ops.py
log_paths ¶
The subjects in span touching paths (a..b git range).
Source code in packages/git/src/livery/git/_ops.py
ls_files ¶
The paths git lists under paths (the whole tree when none), sorted.
cached lists what the index holds, others the untracked files
the ignore rules do not cover; both together are what a check
reads. Names come back as written, through -z.
Raises:
| Type | Description |
|---|---|
GitError
|
When git cannot list, with its words. |
Source code in packages/git/src/livery/git/_ops.py
ls_remote ¶
The refs remote holds among refs (every one when none is named), by sha.
tags lists the tags alone, the peeled entries left out; remote is a name or a URL, and asking a URL needs no remote configured.
Source code in packages/git/src/livery/git/_ops.py
main_checkout ¶
The repository's main checkout, the same from any of its worktrees.
Every worktree shares the main checkout's .git directory,
which git reports as the common directory; its parent is the
main checkout.
Source code in packages/git/src/livery/git/_ops.py
merge_base ¶
The merge base of HEAD and origin/<base>; raises without one.
A shallow clone, or a base the fetch did not bring, has none.
Raises:
| Type | Description |
|---|---|
GitError
|
When HEAD and |
Source code in packages/git/src/livery/git/_ops.py
merge_parents ¶
HEAD's two parents when HEAD is a merge: the base, then the head merged in.
A pull request's run on GitHub checks out the merge the forge made of the pull request's head onto its base branch; any other checkout answers None.
Source code in packages/git/src/livery/git/_ops.py
merge_tree ¶
The tree a merge of head onto base yields, written to this clone.
No working tree or index is touched; only the objects are written.
Raises:
| Type | Description |
|---|---|
GitError
|
On a conflict, with git's words. |
Source code in packages/git/src/livery/git/_ops.py
object_id ¶
The object id spec names (HEAD:packages/forge is a tree id).
Raises:
| Type | Description |
|---|---|
GitError
|
When spec names nothing. |
Source code in packages/git/src/livery/git/_ops.py
object_ids ¶
The object ids ref holds at paths, read in-process.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The repository's working directory. |
required |
ref
|
str
|
The commit or tree to read, |
required |
paths
|
Sequence[str]
|
Repository-relative paths, files or directories. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
Each path the tree holds, mapped to its object id: a tree |
dict[str, str]
|
id for a directory, a blob id for a file. A path the tree |
dict[str, str]
|
lacks is absent, so a caller that tolerates one reads the |
dict[str, str]
|
mapping and a caller that does not raises on its own |
dict[str, str]
|
behalf. |
Source code in packages/git/src/livery/git/_ops.py
oneline ¶
The commits in span (a..b), one line each, newest first.
Source code in packages/git/src/livery/git/_ops.py
position ¶
The checked-out branch name, empty when detached, and HEAD's commit.
Both read in-process from the checkout's own files, so a flow that asks where it stands pays no process for either.
Raises:
| Type | Description |
|---|---|
GitError
|
When HEAD names no commit yet. |
Source code in packages/git/src/livery/git/_ops.py
push ¶
Push branch to remote, setting upstream; force replaces what is there.
A bare force, for a repository seconds old whose history this checkout authored; a branch others may have moved takes livery.git.push_force and its lease.
Source code in packages/git/src/livery/git/_ops.py
push_force ¶
Force-push branch, leased on the last-seen remote state.
--force-with-lease, never a bare force: the push is
refused when origin moved past what this clone last fetched,
so a colleague's commits pushed since then cannot be
clobbered blind.
Source code in packages/git/src/livery/git/_ops.py
push_refspec ¶
Push refspec to remote as given: a tag, or :refs/tags/x to delete one.
recent_commits ¶
(sha, subject) for the newest count commits reachable from ref.
Source code in packages/git/src/livery/git/_ops.py
remote_branches ¶
Branch names under prefix on origin, asked of the remote.
ls-remote, never the remote-tracking refs: a plain fetch
does not prune, so a stale tracking ref outlives the forge's
auto-delete and would resurrect a finished workflow.
Source code in packages/git/src/livery/git/_ops.py
remote_head ¶
origin/<branch>'s commit, or empty when it does not exist.
Reads the local remote-tracking ref, so call livery.git.fetch first for a fresh answer.
Source code in packages/git/src/livery/git/_ops.py
remote_tags ¶
Tag names on origin, asked of the remote.
ls-remote, never the local list: a tag cut elsewhere (a
CI wave's receipt) is only guaranteed visible at the remote.
Source code in packages/git/src/livery/git/_ops.py
remote_url ¶
The URL of the remote name.
Raises:
| Type | Description |
|---|---|
GitError
|
When root has no such remote. |
Source code in packages/git/src/livery/git/_ops.py
remotes ¶
The names of the repository's remotes.
Source code in packages/git/src/livery/git/_ops.py
reset_hard ¶
restore ¶
Put paths back as HEAD has them; empty, or git's words when it could not.
A path HEAD lacks refuses the whole pathspec, so a caller restoring several files it is unsure of restores them one by one.
Source code in packages/git/src/livery/git/_ops.py
run ¶
Run git with args in root and return its standard output.
Raises:
| Type | Description |
|---|---|
GitError
|
On a non-zero exit, with git's words. The message
names the call with |
Source code in packages/git/src/livery/git/_ops.py
set_remote_url ¶
sha_of ¶
The commit ref resolves to; empty when this checkout cannot.
For a caller taking a commit-ish from a person: a sha, a branch,
a tag, HEAD, HEAD~3. The common grammar resolves in-process;
anything else is asked of git, and a name that resolves to nothing
is an empty answer the caller reports.
Source code in packages/git/src/livery/git/_ops.py
staged_text ¶
path's text at index stage of a conflict; empty when that side has none.
Stage 1 is the common ancestor, 2 the side being merged into (the base, in a rebase), 3 the side merged in (the commit replayed, in a rebase).
Source code in packages/git/src/livery/git/_ops.py
subjects_ahead ¶
The subjects of the commits HEAD carries beyond origin/<base>.
Source code in packages/git/src/livery/git/_ops.py
switch ¶
switch_new ¶
Create or reset the branch name at start (HEAD when empty); switch to it.
tag_dates ¶
Every tag under prefix with the date it was made, YYYY-MM-DD.
Source code in packages/git/src/livery/git/_ops.py
tags ¶
Every tag name the repository knows.
Source code in packages/git/src/livery/git/_ops.py
tracking_branches ¶
Branch names under prefix among origin's remote-tracking refs.
Read locally, so no network and no wait, and as fresh as the last fetch: a branch pushed since is missing, and one the forge deleted lingers until a fetch prunes it. A caller that only names a branch takes that; one that deletes or protects asks origin through livery.git.remote_branches.
Source code in packages/git/src/livery/git/_ops.py
tracks ¶
Whether the repository holds the object spec names: HEAD:uv.lock, a sha.
Source code in packages/git/src/livery/git/_ops.py
tree_diff ¶
The paths differing between the trees old and new.
A rename is both sides.
Source code in packages/git/src/livery/git/_ops.py
unmerged_paths ¶
The paths a stopped merge or rebase left conflicted, as git names them.
unpushed ¶
The commits on any local branch that origin holds on no branch, one line each.
Source code in packages/git/src/livery/git/_ops.py
unstage ¶
Take path out of the index and leave the file; an untracked path is fine.
working_tree_id ¶
The tree id of the working tree as it stands.
Tracked changes and untracked files count and ignored files do
not, the view status gives, written through a scratch copy
of the index so the real index is never touched. A clean
checkout answers HEAD's tree, so a commit that takes everything
has the id a check on the dirty tree recorded.
Source code in packages/git/src/livery/git/_ops.py
worktree_add ¶
Check ref out as a linked worktree at path, detached under detach.
Source code in packages/git/src/livery/git/_ops.py
worktree_remove ¶
master_up ¶
Whether a master for url's host is up under socket_dir.
ssh -O check asks the master over its socket and opens no
connection; a remote that is not ssh has no master and answers
False.
Source code in packages/git/src/livery/git/_ssh.py
record_unsupported ¶
Turn multiplexing off under socket_dir with words; the file written.
Source code in packages/git/src/livery/git/_ssh.py
remote_host ¶
The user, host and port an ssh remote url names; None for any other transport.
Both spellings ssh remotes take: git@github.com:owner/repo.git
and ssh://git@host:2222/owner/repo.git. An http, https or
file remote opens no ssh connection.
Source code in packages/git/src/livery/git/_ssh.py
ssh_command ¶
The GIT_SSH_COMMAND that multiplexes over a master under socket_dir.
ControlMaster=auto reuses a master when one is up and opens one
otherwise, replacing a stale socket from an unclean exit; two
spawns racing to open a master is allowed, one wins and the other
connects directly. ControlPersist=<idle> keeps the master that
long after the last client. The path is quoted twice over: git
hands the command to a shell, and ssh then splits an option's
value on spaces unless it is double-quoted, and footman's data
directory on macOS has a space in it.
Source code in packages/git/src/livery/git/_ssh.py
ssh_environment ¶
ssh_environment(socket_dir: Path, *, idle: str = '10m', environ: Mapping[str, str] | None = None, configured: str = '') -> tuple[dict[str, str], str]
The environment that multiplexes a spawned git's ssh, or why not.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
socket_dir
|
Path
|
Where the sockets live; owner-only and short. |
required |
idle
|
str
|
How long a master lingers after its last client, in ssh's
own spelling ( |
'10m'
|
environ
|
Mapping[str, str] | None
|
The environment the spawn would inherit; the process's own when omitted. |
None
|
configured
|
str
|
What git's |
''
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
The mapping to merge into the spawn's environment, holding |
str
|
|
tuple[dict[str, str], str]
|
the reason multiplexing is not used. The reason is empty when |
tuple[dict[str, str], str]
|
the person's own setting won, which is theirs to know about. |
Source code in packages/git/src/livery/git/_ssh.py
ssh_sockets ¶
Where the plugin keeps its sockets: ssh under the runner's data_dir.
The data directory is owner-only and durable, which a socket wants, and short enough on every platform for the socket path limit below.
Source code in packages/git/src/livery/git/_ssh.py
drop ¶
drop(store: StateStore, ref: str) -> str
Delete ref, on origin or in the checkout; "" when gone, else the reason.
A ref that is already absent counts as gone: the janitor re-runs as its own recovery, and a second sweep must find nothing to do.
Source code in packages/git/src/livery/git/_store.py
fetch_store ¶
fetch_store(store: StateStore, *, series: Iterable[str], branches: bool = False) -> Fetched
Mirror the row series series under FETCHED_NAMESPACE and stamp it.
One fetch, pruned, with one refspec per name below NAMESPACE:
metrics lands at refs/workshop-origin/metrics, a series
origin holds no ref for yet costs nothing, and a ref origin
dropped goes from the mirror. Afterwards the mirror holds the
named series alone: every ref under it that is not one of them,
such as a family's key a fetch of a wider scope left, is deleted
here. Then the origin row of FETCHED records the time, the
count of refs, and the names, sorted. The names are the mirror's
scope: a fetched_snapshot reads a missing ref of a named series
as absent and fails a read of any other remote ref. With
branches the same fetch brings origin's heads into
refs/remotes/origin/, pruned the same way, so a sync that
needs both pays one round trip. A fetch transfers only what the
checkout lacks: on a quiet origin the round trip is the whole
cost and nothing changes. Named no series and no branches, the
fetch is skipped and the mirror is emptied.
Returns:
| Type | Description |
|---|---|
Fetched
|
The refs the mirror holds and how many this fetch changed, or |
Fetched
|
zero of each and the reason when the fetch, the prune or the |
Fetched
|
stamp failed, with git's words; nothing here raises or prints. |
Source code in packages/git/src/livery/git/_store.py
fetched_snapshot ¶
fetched_snapshot(store: StateStore) -> Generator[None]
Read the remote namespace from the checkout's mirror of origin, for the block.
Nothing inside reaches origin. The listing is the mirror
fetch_store took, with origin's branches beside it from the
remote-tracking refs, every commit is local already, and a write
of a remote series is refused with its reason; a local series
reads and writes as ever. The series the stamp names are the
mirror's scope: a read of one of them answers from the mirror, a
missing ref among them is absence, and a read or a listing of any
other remote ref, a keyed family's refs among them, fails naming
the ref and the scope, never as an absence, since the mirror never
held it; a live remote_snapshot reads those. In a checkout
fetch_store never stamped, or stamped under another schema, the
listing is a failure naming the sync, so every read inside fails
the way an unreachable origin fails, never as an absence, and
every caller falls open on it. A block opened inside another
snapshot for the same checkout shares the outer one.
Source code in packages/git/src/livery/git/_store.py
list_refs ¶
list_refs(store: StateStore, prefix: str) -> dict[str, str] | None
The refs under prefix by sha, remote or local; None when unlistable.
A prefix under the local namespace, the mirror, or the remote-tracking refs is listed from the checkout's git directory; any other answers from the open snapshot when one covers it, and from origin otherwise. A snapshot of the mirror covers the branches and a prefix at or below one of its series; a wider prefix under a remote namespace, a keyed family's, is unlistable from it, never empty, since the mirror holds none of its refs.
Source code in packages/git/src/livery/git/_store.py
put ¶
put(store: StateStore, ref: str, files: dict[str, str], *, message: str, window: int | None = None, ci_only: bool = False, order: Order | None = None, remove: Iterable[str] = (), attempts: int = ATTEMPTS) -> str
Write files onto ref, keeping what it already holds; "" or the reason.
The tree is the ref's current files, less remove, with files laid over them, trimmed to the newest window files when one is given, ranked by order or, without one, by name. The push is a compare-and-swap on the sha the read returned: a ref another writer moved in between refuses the push, and the write re-reads, merges, and retries up to attempts times. ci_only refuses a write from outside CI, naming the rule. Every refusal is the returned reason; nothing here raises or prints.
Source code in packages/git/src/livery/git/_store.py
1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 | |
read ¶
Read ref's files, saying whether a miss is absence or failure.
A remote ref is fetched from origin: the fetch lands in
FETCH_HEAD and creates no local ref, so a checkout accrues
only unreachable objects git's own gc prunes. A failed fetch is a
failure only when the ref is there: a ref that does not exist
also fails the fetch, and that is the ordinary first-run case. A
remote that cannot answer the probe either counts as failed: an
unreachable forge must never read as "there was never a stamp".
A local ref, or one of the mirror under FETCHED_NAMESPACE, is
read from the checkout's own git directory: a missing ref is
absence, and anything else git refuses is a failure with git's
words. With only, the files whose names it accepts are read and
the rest are named in names alone, never read.
Source code in packages/git/src/livery/git/_store.py
remote_snapshot ¶
remote_snapshot(store: StateStore, *, fetch: Iterable[str] = (), publish: bool = False) -> Generator[str | None]
Read the remote namespace through one listing for the block.
One ls-remote of the store's namespace and the branches when
the block opens; every read and listing of a remote ref inside
answers from it, and a ref whose commit the checkout already
holds is read with no network at all. The refs whose names start
with a prefix in fetch (spelled below the namespace, metrics
or run/1400/, or in full from refs/ for another namespace,
refs/workshop-trace/about/) and whose commits the checkout
lacks are fetched together, one round trip, when the block opens.
A read of a ref outside them brings the ref's whole key group in
one fetch (_key_group), so a loop over a family's keys costs one
round trip whichever ref it reads first. A ref another writer
moved after the listing is listed again and read at its current
commit, so a concurrent writer never turns a read into a failure.
A write inside keeps its compare-and-swap on the listed sha: a
refused push lists again and retries, and a successful write
records its new sha, so a read after it sees it. A listing the
forge could not answer makes every read inside a failure naming
the reason and every listing unlistable, never an absence. A block
opened inside another for the same checkout shares the outer
listing and brings what its own fetch names against it.
With publish the listing is written to a file whose path the
block yields, for the caller to hand its child processes under
SNAPSHOT_VARIABLE: a block a child opens reads that file
instead of listing, and the child's writes record their shas in
it for the children after it. A listing the parent could not
take is not published and the block yields None, so a child
lists for itself; a file a child cannot read, or one taken for
another checkout, counts as none. Without publish the block
yields None.
Source code in packages/git/src/livery/git/_store.py
slug ¶
sweep ¶
sweep(store: StateStore, declared: tuple[Series | Keyed, ...], *, remote: bool, dry_run: bool = False, now: datetime | None = None) -> list[str]
The store's janitor: every series bounded, every orphan dropped; the lines.
The scope is the run's: the local series always, the remote ones
only under remote, which a caller sets inside CI, since a local
run never writes the remote store. A series is trimmed to its
window, and the rows older than the age it declares go. A
family's keys are listed and each key's series is bounded the
same way, after its orphans go: a key whose ref is older than the
family's stale_after, or one the family's current keys no
longer include. A family that cannot be listed, or whose current
keys cannot be told, drops nothing and says so. Under dry_run
every line says what would go and nothing is written. Every line
names what happened; a failure is a line, never a raise, and a
second sweep finds nothing to do. A remote sweep reads through one
snapshot of the namespace, its caller's when one is open, so a
family's keys, rows and commit times cost a fetch per key group,
never one per key.