Documentation
¶
Overview ¶
Package revision is what git says about the **code** branch: the commit at `HEAD`, the blob id of an artefact as the working tree holds it, and whether any artefact a Run read differs from `HEAD` or is untracked (§7, issue #136).
It is the other half of internal/store, and the two are deliberately not one package. That one is the record — an orphan branch hyper writes and no human authors — and this one is the repository the artefacts sit in, which hyper only ever reads. Nothing here writes an object, moves a ref, reaches a remote or names a commit identity, so the environment its subprocesses run with carries none of those; and nothing in internal/store reads a path in the working tree, which is what keeps *hyper never checks the Store out* (ADR-0075) a fact about one package.
What it answers is Provenance's own three members and nothing else: `repo_revision`, the two blob-id members through Blob, and the `repo_dirty` marker (§7, ADR-0043). It derives no Provenance value itself — which member goes on which file is internal/store's split, and which artefacts a Run read is the Run's own fact.
A blob id is computed here rather than asked of git, because it is computable: git's object id is a SHA-1 over a header and the content, so an artefact hyper has already read is one subprocess it does not have to start. The test of that claim is `git hash-object` answering the same string.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AtPath ¶
AtPath names one file inside a commit's tree, in git's own notation. It is the object name a range opens at where the artefact carries no revision of its own: the file's blob under the `repo_revision` the supplying Run recorded (§8, ADR-0067).
It is spelled here rather than at the call site so that the one place that composes a commit and a path is the package that reads the object — a caller building `commit + ":" + path` is a caller that can build it wrong, and git's answer to a name that means something else is a blob id like any other.
func Blob ¶
Blob is the git blob id of content: SHA-1 over `blob <length>\0` and the bytes, which is git's object id and not a digest hyper chose.
hyper names the algorithm where hyper chose it (§7), and here it did not: the two revision members are written bare because the algorithm is the repository's, and a reader verifies one with `git hash-object`.
func Committed ¶
Committed is the blob id one commit holds at one path, and "" where it holds no file there.
It is the question `not-in-clone` splits on (§8, issue #239). A revision the clone cannot resolve has two causes and one of them names an act: the object may be one this clone was never given — shallow, partial, a rewritten history — or it may be one nothing ever wrote, the Run having read the file out of a working tree that was never committed. The commit the same entry recorded tells the two apart without asking a remote: where it names exactly that revision at that path, the artefact was committed and this clone does not hold the object; where it names something else or nothing at all, the bytes are in no commit and never were.
**It reads the tree and never the blob**, which is what keeps the answer true on a partial clone: a blobless clone holds every tree and none of the files under them, so a reader that asked for the content would call the one case this exists to tell apart *never committed*.
**The absence is answered and a read that could not be performed is not.** A path the commit's tree does not carry is an ordinary fact and comes back empty, and so does a tree or a submodule standing where a file was named — what the caller asked about is an artefact's own revision, and neither of those is one. A commit this clone does not hold is the other half: it says nothing about whether the file under it was committed, so it is reported as the read it is and the caller keeps the weaker sentence (§8, ADR-0071).
Types ¶
type Facts ¶
type Facts struct {
// Head is the commit at `HEAD`, whole. It is what a reaper loads the
// Procedure sequence at, which a blob id could not do (§7).
Head string
// Dirty says some artefact the Run read differs from `HEAD` or is
// untracked — exactly the file set §8's catch-all row counts the moved
// lines of, which is what makes the marker and the count agree by
// construction (§7).
Dirty bool
}
Facts is what the code branch says about the code a Run performed.
func Read ¶
Read answers the facts, over the artefacts the Run read.
It answers an error where `HEAD` resolves to no commit, which is a repository with nothing committed at all. That is not an empty answer: `repo_revision` is a member every Run's Provenance carries (§7, ADR-0043), so a Run that cannot name one has nothing to write and stops before it has written anything.
A file set of nothing is dirty-free by construction, and correctly: a Run that read no artefact — which no Run does, every Run being a Run of a Procedure (ADR-0036) — has no code to have moved.
type File ¶
File is one artefact a Run read: where it sits in the repository, relative to the root and with forward slashes, and the exact bytes it was read as.
The bytes travel with the path because the comparison is against what the Run actually read and never against what the file says now: an artefact edited between the load and this call is a repository nobody was running, and re-reading it here would let one appear.
func ArtefactsAt ¶
ArtefactsAt answers the artefacts one revision held, and whether this clone holds that revision at all.
The selection is the caller's, because what counts as an artefact is internal/repository's rule and this package's subject is git: a listing filtered here would be the five artefact locations spelled in a second place, which is where the day comes that the walk and the revision disagree about what a repository is.
**A revision this clone does not hold is answered and never errored.** A Run recorded on a runner names a commit a laptop may never have fetched, and a shallow clone holds a Store branch whole while holding one code commit — so *not held* is an ordinary fact about the clone rather than the world resisting, and what a reaper does with it is write the closing write it can establish and omit the code facts it cannot (§7).
The order is git's own, which is the tree's: sorted by path, one answer for two reads of one commit.
type Moved ¶
type Moved struct {
// Count is git's own total: every `+` and every `-` line of every hunk
// of every wanted path.
Count int
// Before and After are the lines each path's hunks touched, at the
// first revision and at the second. A path with no hunk is absent from
// both, which is the ordinary absence: a file that did not move has no
// line that did.
Before, After map[string]map[int]bool
}
Moved is what one `git diff` said: how many lines moved over the file set the caller wanted, and which lines they were at each of the two revisions.
The two line sets are keyed by repository path and are separate because a fact occupies different lines at the two revisions — a `bound:` that moved down four lines is one line at each end, and subtracting one for both would leave the catch-all reporting a line it never counted.
func Between ¶
Between answers what moved between two revisions over the paths wanted.
The selection is the caller's, exactly as it is for ArtefactsAt one file over: what counts as an artefact is internal/repository's rule and this package's subject is git, and a listing filtered here would be the five artefact locations spelled in a second place. **The generated workflow falls outside that rule and is therefore out** — it is projected rather than authored and byte-exact against what `project` would write (ADR-0046), so a change in it is a `hyper` version move already in Provenance, a Procedure move already classed, or a hand-edit, and a hand-edit is `check`'s Refusal rather than a row here.
**A revision this clone does not hold is answered and never errored**, which is this package's rule wherever it names an object somebody else's Run recorded: what the caller does with it is render the absence §8 names, and the count is the part that needed the bytes (ADR-0071).
Renames are off, so a moved file is a deletion and an addition and its lines are counted as git counts them there. Following a rename would report one path's lines under another path's name, which is exactly the map the caller subtracts a fact's own lines out of.
type Object ¶
Object is one git object as this reader answers it: the blob id the name resolved to, and the bytes it holds.
The two come back together because one read answers both and a caller wanting one always wants the other: a review names the blob on its header's range line and reads the bytes to mark the lines that moved, and a second call for the second half would be one subprocess spent re-asking a question already answered (§8).
func Held ¶
Held answers the object an object name resolves to and whether this clone holds it.
It answers false for an object the clone does not hold, for a name that resolves to nothing at all, and for one that resolves to something that is not a blob: what the caller asked for is a file's bytes, and a commit standing where a blob was named is an object it cannot read those from.
**It never fetches.** Every git subprocess this package starts runs with lazy fetching off (environment, git.NoLazyFetch), so on a partial clone a promisor object that would need fetching answers *not held* like any other absent one rather than reaching a remote nobody asked it to (§8, ADR-0071).
The name goes to git NUL-delimited and the answer is read as one record, which is what makes a path holding any byte at all — a space, a newline — answerable rather than a parse this reader gets wrong. One object is asked about per call, so the record is the whole answer, and the content is read by the size git states rather than by scanning for a separator: an artefact may hold any byte at all, a newline among them.
Source Files