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

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

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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

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.

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)