livery.git._ops¶
livery.git._ops ¶
Local git operations for one repository, as functions of its root.
Every function takes the repository's working directory first and returns strings or raises livery.git.GitError. Nothing is held between calls: a fact is read when it is asked for, and a function that moves the repository, a fetch, a push, a commit, a switch, says so in its name.
A reader of refs, objects, history or config opens the repository's own files in-process and starts no git; a mover, and a reader of the index, the working tree or the remote, runs git through the tool store's pinned handle and carries git's own words in its error. livery.git.call is the one door every such call takes and returns the result whatever the exit code; livery.git.run raises on a non-zero exit.
Classes:
| Name | Description |
|---|---|
GitError |
A git command failed; the message carries git's words verbatim. |
Functions:
| Name | Description |
|---|---|
call |
Run git with args in root and return the result whatever the exit code. |
run |
Run git with args in root and return its standard output. |
main_checkout |
The repository's main checkout, the same from any of its worktrees. |
unmerged_paths |
The paths a stopped merge or rebase left conflicted, as git names them. |
staged_text |
path's text at index stage of a conflict; empty when that side has none. |
add |
Stage path as it stands in the working tree, a removal included. |
current_branch |
The checked-out branch name; empty when detached. |
position |
The checked-out branch name, empty when detached, and HEAD's commit. |
object_id |
The object id spec names ( |
object_ids |
The object ids ref holds at paths, read in-process. |
working_tree_id |
The tree id of the working tree as it stands. |
tree_diff |
The paths differing between the trees old and new. |
first_parent_trees |
HEAD's tree id and its first-parent ancestors', newest first. |
head_sha |
The commit HEAD points at. |
has_commits |
Whether HEAD names a commit; false with no commit or no repository. |
head_subject |
HEAD's commit subject. |
head_body |
HEAD's commit body, without the subject. |
head_message |
HEAD's commit subject and its body, read in-process. |
fetch |
Freshen |
fetch_tag |
Take tag from origin as it is there, replacing the one held here. |
switch_new |
Create or reset the branch name at start (HEAD when empty); switch to it. |
reset_hard |
Move the branch, the index and the working tree to ref; every change goes. |
clean |
Remove every untracked and ignored file but the patterns in keep; the paths. |
oneline |
The commits in span ( |
unpushed |
The commits on any local branch that origin holds on no branch, one line each. |
ls_remote |
The refs remote holds among refs (every one when none is named), by sha. |
push_refspec |
Push refspec to remote as given: a tag, or |
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. |
restore |
Put paths back as HEAD has them; empty, or git's words when it could not. |
tracks |
Whether the repository holds the object spec names: |
unstage |
Take path out of the index and leave the file; an untracked path is fine. |
ls_files |
The paths git lists under paths (the whole tree when none), sorted. |
remote_url |
The URL of the remote name. |
set_remote_url |
Point the remote name at url. |
add_remote |
Add the remote name at url. |
remotes |
The names of the repository's remotes. |
tag_dates |
Every tag under prefix with the date it was made, |
fetch_tags |
Freshen |
has_remote |
Whether this clone has a remote called name; any other failure raises. |
is_ancestor |
Whether ancestor reaches descendant in this clone. |
push |
Push branch to remote, setting upstream; force replaces what is there. |
push_force |
Force-push branch, leased on the last-seen remote state. |
subjects_ahead |
The subjects of the commits HEAD carries beyond |
behind_base |
How many commits |
conflicts_with_base |
Whether merging |
integrate |
Merge |
changed_between |
The paths matching patterns that differ between old and new. |
is_clean |
Whether the working tree has no changes, staged or not. |
dirty_paths |
The paths the working tree changed, staged or not, in status order. |
commits_since |
How many commits HEAD carries beyond ref. |
detach |
Check ref out as a detached HEAD. |
delete_branch |
Delete the local branch name, merged or not. |
create_branch |
Create and switch to name. |
switch |
Switch to the existing branch name. |
commit_all |
Stage everything and commit with message. |
amend_all |
Stage everything and fold it into HEAD, message kept. |
local_branch_exists |
Whether branch exists locally. |
remote_head |
|
author_email |
The address the next commit in root would carry as its author. |
config_get |
The repository's git config value for key; empty when unset or no repository. |
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. |
config_regexp |
Every config key matching pattern, with its value, read in-process. |
sha_of |
The commit ref resolves to; empty when this checkout cannot. |
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. |
changed_paths |
Repo-relative paths this branch touches, committed or not. |
tags |
Every tag name the repository knows. |
remote_tags |
Tag names on origin, asked of the remote. |
recent_commits |
(sha, subject) for the newest count commits reachable from ref. |
local_branches |
Local branch names under prefix ( |
remote_branches |
Branch names under prefix on origin, asked of the remote. |
tracking_branches |
Branch names under prefix among origin's remote-tracking refs. |
any_head |
branch's head sha: local when present, else the remote's, else empty. |
log_paths |
The subjects in span touching paths ( |
last_commit_touching |
The newest commit at or before ref that changed path; empty if none. |
files_in_commit |
The paths the commit at ref changed, against its first parent. |
file_at |
The contents of path as committed at ref; empty when absent. |
blob_at |
The text of the blob digest names in the object store; empty when none. |
commit_message |
ref's full commit message, subject and body. |
GitError ¶
Bases: RuntimeError
A git command failed; the message carries git's words verbatim.
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
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
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
unmerged_paths ¶
The paths a stopped merge or rebase left conflicted, as git names them.
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
add ¶
current_branch ¶
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
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
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
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
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
head_sha ¶
has_commits ¶
Whether HEAD names a commit; false with no commit or no repository.
Source code in packages/git/src/livery/git/_ops.py
head_subject ¶
head_body ¶
head_message ¶
HEAD's commit subject and its body, read in-process.
Source code in packages/git/src/livery/git/_ops.py
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.
switch_new ¶
Create or reset the branch name at start (HEAD when empty); switch to it.
reset_hard ¶
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
oneline ¶
The commits in span (a..b), one line each, newest first.
Source code in packages/git/src/livery/git/_ops.py
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
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
push_refspec ¶
Push refspec to remote as given: a tag, or :refs/tags/x to delete one.
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 ¶
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
tracks ¶
Whether the repository holds the object spec names: HEAD:uv.lock, a sha.
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.
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
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
set_remote_url ¶
add_remote ¶
remotes ¶
The names of the repository's remotes.
Source code in packages/git/src/livery/git/_ops.py
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
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
has_remote ¶
Whether this clone has a remote called name; any other failure raises.
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
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
subjects_ahead ¶
The subjects of the commits HEAD carries beyond origin/<base>.
Source code in packages/git/src/livery/git/_ops.py
behind_base ¶
How many commits origin/<base> is ahead of HEAD.
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
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
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
is_clean ¶
dirty_paths ¶
The paths the working tree changed, staged or not, in status order.
commits_since ¶
detach ¶
delete_branch ¶
create_branch ¶
switch ¶
commit_all ¶
local_branch_exists ¶
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
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
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_set ¶
config_unset ¶
Remove key from the repository's git config; a key already absent is fine.
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
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
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
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
tags ¶
Every tag name the repository knows.
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
recent_commits ¶
(sha, subject) for the newest count commits reachable from ref.
Source code in packages/git/src/livery/git/_ops.py
local_branches ¶
Local branch names under prefix (workflow/), short form.
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
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
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
log_paths ¶
The subjects in span touching paths (a..b git range).
Source code in packages/git/src/livery/git/_ops.py
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
files_in_commit ¶
The paths the commit at ref changed, against its first parent.
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
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
commit_message ¶
ref's full commit message, subject and body.