livery.git._objects¶
livery.git._objects ¶
Refs, objects and config read in-process, and a root commit written in-process.
Every reader here opens the repository with dulwich, reads the files
git itself would read, and closes it again: no process starts, and
nothing is held between calls. A revision a reader cannot resolve on
its own, a reflog spelling or a date, is handed to git by the caller;
what this module resolves is the common grammar: a sha, HEAD, a
branch, a tag, origin/<branch>, a full ref, <rev>~<n>,
<rev>^{commit}, <rev>^{tree} and <rev>:<path>.
A ref write takes git's lock file beside the ref, as git does. Every
worktree of a checkout shares one git directory, so two processes
writing the same ref is ordinary, and a write that finds the lock held
waits LOCK_WAIT seconds for it before raising RefLocked.
Classes:
| Name | Description |
|---|---|
Unresolved |
A revision the in-process resolver cannot name; git may still. |
RefLocked |
A ref's lock file stayed held for the whole wait. |
Functions:
| Name | Description |
|---|---|
opened |
The repository at root, a worktree included, closed after the block. |
holds |
Whether the object store has the object sha names. |
ref_value |
The sha the ref name points at, followed to its end; |
head_target |
What |
point |
Point ref at sha, whatever it held before. |
commit_of |
The commit sha names, a tag peeled; raises |
name_of |
The object id rev names in the common grammar, a tag left unpeeled. |
resolve |
The commit sha rev names, in the common grammar, a tag peeled. |
tree_at |
The tree of the commit sha, or the tree sha itself. |
entry |
The mode and sha of path under tree, or |
object_named |
The object id spec names: |
message_of |
The commit's whole message as text. |
blob_text |
The blob sha as text; empty when sha names no blob. |
subject_and_body |
A commit message as git prints |
walk |
The commits reachable from include and not from exclude, newest first. |
changed_paths_between |
The paths that differ between the trees old (none for a root) and new. |
config_value |
The config value key ( |
config_matching |
Every config key matching pattern, spelled |
refs_under |
The refs under prefix ( |
when_made |
When the commit or tag sha was made, as an aware moment. |
is_ancestor |
Whether ancestor reaches descendant. |
merge_base |
The merge base of the two commits, or |
tree_files |
The blobs of the tree sha names (a commit's tree, or a tree), and every path. |
root_commit |
Write a root commit holding files and return its sha; nothing else moves. |
set_ref |
Point ref at new when it is at old ( |
drop_ref |
Delete ref; whether it was there. |
Attributes:
| Name | Type | Description |
|---|---|---|
LOCK_WAIT |
|
|
LOCK_PAUSE |
|
__all__
module-attribute
¶
__all__ = ['LOCK_PAUSE', 'LOCK_WAIT', 'NotGitRepository', 'RefLocked', 'Unresolved', 'blob_text', 'changed_paths_between', 'commit_of', 'config_matching', 'config_value', 'drop_ref', 'entry', 'head_target', 'holds', 'is_ancestor', 'merge_base', 'message_of', 'name_of', 'object_named', 'opened', 'point', 'ref_value', 'refs_under', 'resolve', 'root_commit', 'set_ref', 'subject_and_body', 'tree_at', 'tree_files', 'walk', 'when_made']
Unresolved ¶
Bases: LookupError
A revision the in-process resolver cannot name; git may still.
RefLocked ¶
Bases: OSError
A ref's lock file stayed held for the whole wait.
An OSError, so a caller that turns a failed write into its reason
reads this one the same way.
Attributes:
| Name | Type | Description |
|---|---|---|
lock |
The lock file's path. |
|
waited |
How long the write waited, in seconds. |
Name the lock file and how long the write waited for it.
Source code in packages/git/src/livery/git/_objects.py
opened ¶
The repository at root, a worktree included, closed after the block.
Raises:
| Type | Description |
|---|---|
NotGitRepository
|
When root is not inside a repository. |
Source code in packages/git/src/livery/git/_objects.py
holds ¶
ref_value ¶
The sha the ref name points at, followed to its end; None when absent.
point ¶
Point ref at sha, whatever it held before.
Raises:
| Type | Description |
|---|---|
RefLocked
|
When another process holds the ref's lock for the whole wait. |
Source code in packages/git/src/livery/git/_objects.py
commit_of ¶
commit_of(repo: Repo, sha: bytes) -> Commit
The commit sha names, a tag peeled; raises Unresolved for anything else.
Source code in packages/git/src/livery/git/_objects.py
name_of ¶
The object id rev names in the common grammar, a tag left unpeeled.
Raises:
| Type | Description |
|---|---|
Unresolved
|
When rev is outside the grammar or names nothing. |
Source code in packages/git/src/livery/git/_objects.py
resolve ¶
The commit sha rev names, in the common grammar, a tag peeled.
Raises:
| Type | Description |
|---|---|
Unresolved
|
When rev is outside the grammar or names no commit. |
Source code in packages/git/src/livery/git/_objects.py
tree_at ¶
tree_at(repo: Repo, sha: bytes) -> Tree
The tree of the commit sha, or the tree sha itself.
Source code in packages/git/src/livery/git/_objects.py
entry ¶
The mode and sha of path under tree, or None when the tree lacks it.
Source code in packages/git/src/livery/git/_objects.py
object_named ¶
The object id spec names: <rev>:<path>, <rev>^{tree}, a revision.
None when the revision resolves and the path is absent;
Unresolved when the revision itself cannot be named.
Source code in packages/git/src/livery/git/_objects.py
blob_text ¶
The blob sha as text; empty when sha names no blob.
subject_and_body ¶
A commit message as git prints %s and %b: first paragraph, and rest.
Source code in packages/git/src/livery/git/_objects.py
walk ¶
walk(repo: Repo, include: list[bytes], *, exclude: list[bytes] | None = None, paths: list[bytes] | None = None, limit: int | None = None) -> Generator[Commit]
The commits reachable from include and not from exclude, newest first.
Source code in packages/git/src/livery/git/_objects.py
changed_paths_between ¶
The paths that differ between the trees old (none for a root) and new.
Source code in packages/git/src/livery/git/_objects.py
config_value ¶
The config value key (section.name or section.sub.name) or empty.
Source code in packages/git/src/livery/git/_objects.py
config_matching ¶
Every config key matching pattern, spelled section.sub.name, by value.
The files are read from the least to the most specific, so the repository's own value wins over the person's, as git resolves it.
Source code in packages/git/src/livery/git/_objects.py
refs_under ¶
The refs under prefix (refs/heads/), loose and packed, by sha.
With whole, the prefix names whole path components, as a
for-each-ref pattern does: refs/tags/pkg lists
refs/tags/pkg/v1 and not refs/tags/pkgx.
Source code in packages/git/src/livery/git/_objects.py
when_made ¶
When the commit or tag sha was made, as an aware moment.
Source code in packages/git/src/livery/git/_objects.py
is_ancestor ¶
Whether ancestor reaches descendant.
merge_base ¶
The merge base of the two commits, or None without one.
Source code in packages/git/src/livery/git/_objects.py
tree_files ¶
tree_files(repo: Repo, sha: bytes, wanted: Callable[[str], bool] | None = None) -> tuple[dict[str, bytes], tuple[str, ...]]
The blobs of the tree sha names (a commit's tree, or a tree), and every path.
Returns the blobs by path, and the path of every blob the tree holds, sorted. With wanted, a blob whose path it refuses is named among the paths and never read: a caller that needs a few of many large blobs decompresses those alone.
Source code in packages/git/src/livery/git/_objects.py
root_commit ¶
root_commit(repo: Repo, files: dict[str, bytes], message: str, *, identity: tuple[str, str], when: datetime) -> bytes
Write a root commit holding files and return its sha; nothing else moves.
Every object is written loose, as git writes a small commit: a
pack written per commit would be walked against the pack list
on its way in (dulwich 1.2.17, _complete_pack), and a pack
that git's own background gc --auto removed between the
listing and the walk raises there, where the loose path lists
nothing. Git packs the loose objects at its own pace, after the
refs that reach them are in place.
Source code in packages/git/src/livery/git/_objects.py
set_ref ¶
Point ref at new when it is at old (None: absent); whether it moved.
The comparison is made under the ref's lock, so of two writers that
read the same old, one moves the ref and the other gets False.
Raises:
| Type | Description |
|---|---|
RefLocked
|
When another process holds the ref's lock for the whole wait. |
Source code in packages/git/src/livery/git/_objects.py
drop_ref ¶
Delete ref; whether it was there.
Raises:
| Type | Description |
|---|---|
RefLocked
|
When another process holds the ref's lock, or the packed refs' lock, for the whole wait. |