zig-git #

zig-git reads, and will write, git repositories without running git. These are the words its code and documentation use for the things in a repository. They follow gitglossary(7) wherever git's own words are unambiguous.

Objects #

Object: A blob, tree, commit or tag, identified by the hash of its contents.

Object ID: The hash that identifies an object, together with the object format it was computed in. Avoid: object name, OID, SHA, hash (which is the algorithm)

Object header: The <kind> <size> and NUL that come before an object's contents wherever it is stored whole, and that its object ID is hashed over.

Loose object: An object kept in a file of its own in an objects directory, named after its object ID and compressed with zlib.

Identity line: A commit's author or committer line, or a tag's tagger line: a name, an email address, and a date with its time zone. Avoid: signature (which is the cryptographic one a gpgsig header holds), person, ident

Date mode: How a date is shown, as --date= names it: default, relative, iso, human, format: and the rest, each with a -local variant that shows it in the local zone rather than the one it was recorded in. Avoid: date format (except for a format: string)

Local zone: The time zone TZ names, as glibc reads it — a TZif file when there is one by that name, and otherwise a POSIX rule read as leniently as glibc reads one — which the -local date modes and human read the current time in. Avoid: system time zone, local time zone

Gitlink: A tree entry naming a commit rather than a blob or tree, as a submodule is recorded; its mode is 160000.

Abbreviated object ID: The first hexadecimal digits of an object ID, at least four, standing for the one object whose ID begins with them. Avoid: short hash, short SHA

Abbreviation length: The fewest digits object IDs are shortened to, as core.abbrev or --abbrev says; an object ID is shortened further only until no other object's begins the same way. auto makes it grow with the number of packed objects. Avoid: short length

Ambiguous prefix: An abbreviated object ID that more than one object's ID begins with, and that a disambiguation hint does not narrow to one; git names it in an error and lists the candidates.

Disambiguation hint: The kind of object an ambiguous prefix is meant to name — a commit, a committish, a tree, a treeish or a blob — as core.disambiguate or a suffix such as ^{commit} gives it. Avoid: type filter

Object format: The hash algorithm a repository names its objects with: SHA-1 or SHA-256. Every object in a repository shares one. Avoid: hash type, hash version

Pack: A file holding many objects, most of them stored as deltas, with a pack index beside it that finds each one by object ID. Avoid: packfile (except when naming the file format)

Pack index: The .idx file beside a pack. Never shortened to "index", which is the other thing.

Delta: An object stored as instructions for rebuilding it from another object, its base.

Delta base: The object a delta is applied to. An OFS_DELTA names it by where it is in the same pack; a REF_DELTA by its object ID. Avoid: source, parent (which is a commit's)

Delta chain: A delta, its base, its base's base, and so on down to an object stored whole; its depth is how many deltas it has.

Thin pack: A pack holding deltas whose bases it leaves out, for sending to a repository that already has them; git index-pack --fix-thin appends the bases before it is kept on disk.

Pack entry: One object in a pack: a header giving its type and size, a delta's base, and the zlib stream of the object or the delta.

Multi-pack-index: One table finding the objects of many packs at once, so that looking an object up takes one search rather than one per pack. Avoid: MIDX (except when naming the file format)

Incremental multi-pack-index: A multi-pack-index kept as a chain of layers, each naming only packs the layers before it do not, in objects/pack/multi-pack-index.d/.

Object database: Where a repository's objects are kept and found by object ID, whatever the storage behind it. Avoid: ODB, object store

Objects directory: One directory of loose objects and packs. A repository's object database on disk is its own objects directory and those of its alternates. Avoid: object source, object store

Alternate: Another repository's objects directory that a repository reads objects from as though they were its own. Avoid: borrowed repository, shared repository

Replace ref: A ref under refs/replace/, named for an object, that makes the object read as another one: its replacement, whose kind and contents it takes while keeping its own object ID. Avoid: replacement ref

Graft: Parents given to a commit in place of the ones it was made with, by info/grafts; a shallow clone's boundary commits are grafted to have none.

Shallow commit: A commit listed in a shallow clone's shallow file, read as having no parents, which together make the shallow boundary. Avoid: grafted commit (which is any graft)

Refs #

Ref: A name under refs/, or HEAD, that points at an object ID or, for a symbolic ref, at another ref. Avoid: reference, pointer

Ref store: Where a repository's refs are kept and found by name, whatever the storage behind it. Avoid: ref database, refdb

Symbolic ref: A ref whose value is the name of another ref rather than an object ID, as HEAD names the current branch. Avoid: symref, alias

Loose ref: A ref kept as a file of its own, named after the ref.

Packed refs: Refs kept together in one file, packed-refs, which a loose ref of the same name overrides.

Reftable: A file of refs and reflog entries in git's binary reftable format. A repository that uses them keeps a stack of reftables, each newer one overriding the older.

Reflog: The record of the values a ref has had, one entry for each change, with who made it, when and why.

Per-worktree ref: A ref that each worktree has its own of, such as HEAD or those under refs/bisect/, rather than one shared by every worktree.

Root ref: A ref outside refs/, in the root of the ref namespace: HEAD, a name of upper-case letters and underscores ending in _HEAD, or one of the few irregular names gitglossary(7) lists. Every root ref is per-worktree.

Pseudoref: FETCH_HEAD or MERGE_HEAD: a root ref that may hold several object IDs and more besides, kept as a file in the git directory whatever the ref storage, and read for its first object ID.

Peeled: Said of the object an annotated tag leads to through however many tags: the first that is not a tag. packed-refs and reftables may record it beside the tag's object ID.

Reftable stack: The reftables of one reftable/ directory, named oldest first in its tables.list; a newer table's record for a name overrides the older ones', and a deletion record hides it.

Broken ref: A ref git lists only to pass over with a warning, or to stop at: one whose contents are not a ref, whose name is not well formed, or whose object ID is all zeros.

Ref transaction: A set of ref updates that all happen or none do, each one checked against the value the ref was expected to have.

The repository on disk #

Repository: The whole of one git repository: its object database, its ref store, its configuration, and its working tree if it has one. Avoid: repo (in documentation)

Git directory: The directory holding a repository's administrative files — .git in a working tree, or the repository itself when it is bare. Avoid: dot-git, gitdir

Common directory: The git directory that linked worktrees share, holding the objects and the refs other than each worktree's own HEAD. Avoid: main git dir

Working tree: The checked-out files of a repository, outside its git directory. Avoid: worktree (except for a linked worktree), checkout, workspace

Bare repository: A repository with no working tree, whose directory is its git directory.

Linked worktree: A second working tree of a repository, made by git worktree add, with a git directory of its own under the common directory's worktrees/ holding its HEAD and index, and a commondir file naming the common directory. The repository's first working tree is its main worktree.

.git file: A file named .git at the top of a working tree, holding gitdir: and the path of the git directory, as a linked worktree or a submodule has. Avoid: gitfile (except when quoting git)

Discovery: Finding a repository as git does: from a starting directory up towards the root, or where GIT_DIR says, settling its git directory, common directory and working tree.

Ceiling directory: A directory, named in GIT_CEILING_DIRECTORIES, that discovery does not move up into.

Prefix: Where discovery started, relative to the top of the working tree, with a trailing slash; empty at the top.

Repository format: The version a repository's configuration declares in core.repositoryformatversion, 0 or 1, and the extensions.* it uses; a version 1 repository with an extension a reader does not know is not to be read.

Protected configuration: The system, global and command scopes, which alone may set safe.directory and safe.bareRepository, since a repository could otherwise vouch for itself.

Dubious ownership: A repository found by discovery whose directory, .git or git directory belongs to someone other than the user, which git refuses unless safe.directory names it.

Index: The file listing what the next commit's tree will hold, with the stat data that tells whether a working tree file has changed. Avoid: staging area, cache

Index entry: One path in the index, with the object it names, its mode, its stage and what the working tree file looked like when it last matched. Avoid: cache entry

Stage: Which version of a path an index entry is: 0 for an ordinary entry, or, while a merge is unresolved, 1 for the common ancestor's, 2 for ours and 3 for theirs. Avoid: slot

Cache tree: The trees the index is known to make, directory by directory, kept in the index so that a commit need not build them again; a directory with changed entries has none until the next tree is written.

Resolve-undo: What a conflict's stages were before it was resolved, kept in the index so that the conflict can be recreated.

Split index: An index kept as two files: a shared index holding most entries, and a smaller one recording what has changed since.

Shared index: The file sharedindex.<id> holding most of a split index's entries, which the index file's link extension names and says which of to replace and delete. Avoid: base index

Sparse index: An index in which a directory outside a sparse checkout is one entry for its tree rather than an entry for each file in it.

Sparse directory: The one entry a sparse index has for such a directory: mode 040000, a path ending in /, skip-worktree set, and the tree's object ID.

Skip-worktree: An index entry's flag saying its path is outside the sparse checkout, so the working tree is not expected to have it.

Intent-to-add: An index entry's flag saying the path was added with git add -N: it is tracked, but its contents are not yet staged.

Assume-unchanged: An index entry's flag, which the format calls assume-valid, telling git to take the working tree file as unchanged without looking.

Index extension: A block after the index entries, named by a four-byte signature: the cache tree, resolve-undo, the split index's link, the untracked cache, the fsmonitor cache and others. One whose signature begins with a capital letter may be passed over by a reader that does not know it.

Untracked cache: What git status last found untracked, directory by directory, kept in the index with what it needs to tell whether it still holds.

Fsmonitor cache: Which index entries a file system monitor has vouched for as unchanged, and the point its answers were last relative to.

EWAH bitmap: A run-length-compressed bitmap, as the split index, untracked cache and fsmonitor extensions keep sets of entries or directories.

Configuration #

Configuration: The variables that shape how git behaves, read from every source in turn, a later value taking precedence over an earlier one. Avoid: settings, options (which are a command's)

Key: A variable's full name: section, subsection if any, and name, joined by dots. The section and the name are compared without regard to case; the subsection is not. Avoid: config name

Scope: Which group of sources a variable came from: system, global, local, worktree, or command (the environment and -c). Avoid: level

Origin: The file, or the command line, a variable was read from.

Include: A variable, include.path or includeIf.<condition>.path, naming a file whose variables are read in its place; a conditional one only when its condition holds.

Glob: A pattern in git's dialect, as wildmatch matches it: *, **, ? and bracket expressions, and \ to escape. Avoid: fnmatch pattern

History #

Revision: A name for an object as gitrevisions(7) spells it: an object ID or an abbreviation of one, a ref name, or either followed by suffixes such as ~2, ^{tree} or :path that move from one object to another. Avoid: rev, revspec

Ref expression: The part of a revision that names a ref before any suffix: a name, @, @{-<n>} for the branch checked out n checkouts ago, and @{upstream} or @{push} taken of one.

Reflog entry: A ref's value at a point in its reflog, named by <ref>@{<n>}, counting back from now, or <ref>@{<date>}.

Message search: :/<text> or <rev>^{/<text>}: the youngest commit, from every ref or from one revision, whose message matches a regular expression.

Peel (verb): To step from an object to the one it leads to until reaching one of the kind wanted: through annotated tags, and from a commit to its tree, as ^{<kind>} does. ^{} peels through tags alone, to what is peeled.

Upstream: The branch a branch merges from by default, as its branch.<name>.merge setting names it and its remote's fetch refspecs map it to a remote-tracking ref; @{upstream} names it. Avoid: tracking branch

Push branch: The remote-tracking ref for where a branch would be pushed if git push were run on it, as push.default, the push remote and any push refspecs decide; @{push} names it. In a triangular workflow it differs from the upstream.

Remote-tracking ref: A ref, usually under refs/remotes/, recording where a remote's branch was when last fetched, as the remote's fetch refspecs map it. Avoid: tracking branch (ambiguous with the upstream)

Refspec: A mapping between one repository's refs and another's, [+]<src>:<dst>, with an optional * on each side; a remote's fetch refspecs map its branches to remote-tracking refs, its push refspecs ours to its.

Merge base: A best common ancestor of two commits: one that both reach and that no other common ancestor reaches. Two commits can have several.

Merge-base search: Finding merge bases by painting commits from each side down their parents, newest first, until only commits both sides reach are left; the commits it reads are part of what a later walk can see. Avoid: LCA

Fork point: The merge base of a commit and every value a ref's reflog records, when it is one of those values: where a branch was built on an earlier tip of the ref.

Commit walk: Listing the commits reachable from some starting points and not from others, in an order, as git rev-list lists them. Avoid: traversal, revwalk (except when naming RevWalk)

Excluded commit: A commit a walk does not list because an excluded starting point, ^A, reaches it; git calls it uninteresting. Avoid: hidden, uninteresting (except when quoting git)

Symmetric difference: A...B: the commits either side reaches and the other does not, each on the left side (reachable from A) or the right (from B).

Boundary commit: A parent of a commit in a walk's output that is not in the output itself, such as the commit A in A..B that B's history starts from.

Pathspec: The paths that limit a history or a diff: each a path that matches itself and everything under it, or a pattern with wildcards.

Pathspec magic: What a pathspec's :(...) or short : prefix says of it: top, literal, glob, icase, exclude, and attr, which this library refuses.

Tree comparison: Two trees walked in step under a pathspec, yielding each entry — file, symbolic link or gitlink — added, deleted or modified between them. Avoid: tree diff (except when naming TreeDiff), which is a patch

TREESAME: Said of a commit that changes nothing in the paths a history is limited to, compared with a parent or, for a merge, with the parents that matter.

Relevant parent: A parent that counts in deciding whether a merge is TREESAME: one that is not excluded, or that is an excluded starting point. A commit with one parent always counts it.

History simplification: Which commits a history limited to paths lists, and which parents it follows from each: --full-history, --sparse, --simplify-merges and the rest, or git's default of following one TREESAME parent.

Parent rewriting: Replacing each parent of a listed commit with the nearest ancestor that is listed or excluded, as --parents and --children show a simplified history.

Pull: With --show-pulls, a merge listed because it is TREESAME to a later parent and not to its first.

Mailmap: The names and email addresses people are to be shown under, in place of those their commits were made with, read from .mailmap, mailmap.file and mailmap.blob.

Pretty format: How a commit is described, as --pretty or --format names it: one of the built-in formats (oneline, medium, email and the rest) or a format string. Avoid: log format, output format

Format string: A pretty format spelled out with placeholders, after format: or tformat: or bare when it holds a %; format: separates commits with a line feed and tformat: ends each with one.

Placeholder: A % and what follows it in a format string, standing for something about the commit (%h, %an, %(trailers)) or saying how what follows is written (%C(...), %<(<n>), %w(...)). Avoid: format specifier, atom (which is for-each-ref's)

Trailer: A Key: value line at the end of a commit message, such as Signed-off-by:, its value possibly continued on lines beginning with blank space.

Trailer block: The last paragraph of a commit message when it holds trailers enough to count as one, as git-interpret-trailers(1) decides.

Commit search: Choosing the commits a walk lists by what their messages, authors and committers match, as --grep, --author and --committer do. Avoid: grep (except when naming grep.zig), filter

Decoration: A name shown beside a commit by --decorate, %d or %D: a ref that points at it or at a tag that peels to it, HEAD, or grafted or replaced.

Source: What --source and %S say a commit was reached from: the starting point, as it was named, that the walk first reached it from.

Description: A commit named by the nearest tag it descends from, as git describe names it: the tag alone for its own commit, else the tag, the depth and an abbreviated object ID. Avoid: describe output

Candidate: A named commit git describe weighs on its way back from the commit it describes; the one with the smallest depth names it.

Reachability filter: --contains, --no-contains, --merged, --no-merged or --points-at, choosing refs by what their commits reach or are reached from, or what they point at.

Revision arguments: What a caller would have given git log — revisions, ranges, options and paths — written in git's own syntax. Avoid: rev-list args

Revision query: The structured form of revision arguments: which commits to start from and exclude, which to keep, in what order, and which paths limit them. Avoid: filter, log options

Unsupported option: A revision argument that git accepts and this library does not, named back to the caller rather than ignored.

Commit-graph: A file, or a chain of them, listing commits with their trees, parents, commit dates and generation numbers, so that a walk need not read the commits; it may carry changed-path Bloom filters. Avoid: commit graph (for the file)

Split commit-graph chain: A commit-graph kept as several files named in info/commit-graphs/commit-graph-chain, each above the first listing only commits the files below it do not, and naming them in its base graphs chunk.

Generation number: A number for each commit no larger than any of its children's, so that a commit with a smaller one cannot reach a commit with a larger: the corrected commit date or, without one, the topological level.

Corrected commit date: A commit's commit date, or one more than its parents' largest corrected commit date if that is later: a generation number that is close to the date.

Topological level: One for a root commit, and otherwise one more than the largest of its parents' levels.

Changed-path Bloom filter: A small bit array kept for each commit in a commit-graph, saying which paths the commit may have changed relative to its first parent; a path it rules out was certainly not changed.

Diffs #

Line diff: Two texts compared line by line: which lines of the old text are deleted, which of the new are added, and which are matched one for one, in the edit script git chooses (LineDiff).

Edit script: The deletions and additions that turn one text into the other. Many are shortest; git's is one in particular, and only that one is correct here.

Change: A run of deleted lines and the added lines that replace them, with matched lines on either side.

Hunk: The part of a patch that shows one or more changes with their context, introduced by @@ -<old> +<new> @@.

Context: The matched lines a hunk shows around its changes: -U<n> of them on each side, three by default.

Function name: The text after the second @@ of a hunk: the nearest line before it in the old text that git's rule takes for the start of a function.

Provisional line: A line that occurs so often in the other text (frequentLimit) that whether it takes part in the comparison is decided by the lines around it.

Middle snake: In Myers' algorithm, the diagonal run of matched lines through which an edit script of the least length is split in two, each half found the same way.

Cost limit: How many steps the search for a middle snake runs before git gives up and splits where the search has reached (costLimit): 256, and more for a comparison of more than 65,532 lines. A search that would run past 256 steps is refused, because there git may also split early at a snake it has found, by a rule only partly matched (plain_steps).

Sliding: Moving a run of changed lines up or down over equal lines, which leaves the texts the same, to merge it with others or to line it up with a change in the other text.

Indent heuristic: git's further sliding, on by default, which chooses where a run of changes goes by the indentation and blank lines around it, when the run lines up with no change in the other text (indent.zig).

Split: The boundary just above a line of the text holding a run of changes. A placement of the run has two, above its first line and below its last; the indent heuristic measures each and scores the placement by them.

Placement: One of the places a run of changes can be slid to. The indent heuristic considers those at most the run's length plus one line (and at most 100 lines) above the lowest.

Common tail: The bytes two texts end with alike. For a patch without context (-U0) git sets it aside in whole blocks of 1024 bytes before comparing (LineDiff.keptLength), so the lines in it take no part, not even in the indent heuristic's measurements.

Patch: The text git diff writes for one pair of files: the diff --git header, mode and index lines, --- and +++, and the hunks. Avoid: diff, for the text (it is the comparison)

Writing #

Signer: Whatever produces the signature for a tag or commit being written — usually the program gpg.program names.

Talking to other repositories #

Transport: The connection over which this repository talks to another one — file://, ssh:// or https:// — and the protocol spoken across it. Avoid: remote (which is the configured name of the other repository)