- Zig 99.7%
- Nix 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01P9FTtTrkEbuvbZnRyJCBir |
||
| .forgejo/workflows | ||
| docs/adr | ||
| LICENSES | ||
| src | ||
| tools | ||
| .gitignore | ||
| build.zig | ||
| build.zig.zon | ||
| build.zig.zon.nix | ||
| CONTRIBUTING.md | ||
| flake.lock | ||
| flake.nix | ||
| GLOSSARY.md | ||
| package.nix | ||
| README.md | ||
| REUSE.toml | ||
zig-git
A library for reading git repositories from Zig 0.17 without running git,
written in Zig alone: no libgit2, no C zlib, nothing to link. It is meant to
answer the questions a history browser asks git — what a commit holds, what a
revision range means, what a diff says — with the same answers git gives,
and to grow into writing to repositories and talking to remote ones.
It is early. What works so far is the core layer, the first
parts of the revision layer — revisions, walking commits, history limited
to paths, describing commits as git log does, and naming them by refs —
and the first two parts of the diff layer, comparing two texts as git diff --no-index does, and comparing trees, the index and the working
tree as git diff, git diff-tree, git diff-index and git diff-files
do:
- object formats and object IDs, SHA-1 and SHA-256 alike, chosen per repository at run time, and hashing an object to its ID;
- object headers, read exactly as strictly as git reads them;
- commits, trees, annotated tags and their author, committer and tagger lines, read without allocating and as forgivingly as git reads them, their oddities included;
- loose objects: finding, inflating and checking them, whole, header only or streamed, refusing each corruption git refuses and in the same circumstances;
- packs and their indexes (versions 1 and 2 of the index, versions 2 and 3 of the pack, offsets past 2 GiB), with OFS_DELTA and REF_DELTA chains resolved without recursion and bounded in depth, so that a chain that loops is an error rather than a hang; reading an object's kind and size applies no delta;
- a cache of the delta bases built while reading packed objects, shared by
every pack of the object database, so that reading the objects of one
delta chain one after another, as a walk through history reads every
version of a tree, builds each base once rather than resolving the
chain from its start every time. It holds 96 MiB by default, as git's own cache does, evicting
the least recently used base first:
cache_limitin the options for opening a repository or its object database sets it, and zero turns it off. It changes only how fast an object is read, never what is read or which error a corrupt one gives; - pack entries inflated by a DEFLATE decoder of its own, written from RFC 1951 for streams held whole in memory, several times faster than the standard library's and checked against it: it accepts no stream the standard library's decoder refuses, makes the same bytes of every one it accepts, and hands anything it does not finish to that decoder, which says what is wrong with it in zlib's words as before. Loose objects and objects streamed in bounded memory are inflated by the standard library's decoder;
- the multi-pack-index, and incremental chains of them, as a faster way of finding objects in the packs they name;
- alternates, from
objects/info/alternatesand from aGIT_ALTERNATE_OBJECT_DIRECTORIESvalue the caller passes in, nested as deep as git nests them; - abbreviated object IDs, both ways: a prefix expanded to the objects it
begins, found by binary search in every pack index and
multi-pack-index layer and by listing one fan-out directory of loose
objects, in every objects directory and alternate; an ambiguous one
told apart by kind as
core.disambiguateand^{commit}tell it, and described as git's ambiguity hint describes each candidate; and object IDs shortened to the fewest digits no other object shares, at leastcore.abbrev's, whoseautogrows with the number of packed objects as git's does; - replace refs, as git-replace(1) describes them: every object read
through the refs under
refs/replace/(orGIT_REPLACE_REF_BASE) as its replacement, commits, trees, blobs and tags alike, keeping its own object ID, chains followed four deep with git's errors for a deeper one and a missing replacement, and its warning for a name it passes over; not whencore.useReplaceRefsis false,GIT_NO_REPLACE_OBJECTSis set or--no-replace-objectsgiven; - grafts and the shallow boundary:
info/grafts(orGIT_GRAFT_FILE) read as git reads it, with its deprecation hint and its errors for bad and duplicate lines, and theshallowfile (orGIT_SHALLOW_FILE) with its fatal bad line, giving commits the parents the walk,<rev>^,<rev>~<n>,%Pandmerge-basefollow; and, as git was seen to, the commit-graph left unread when anything is replaced or grafted or the repository is shallow; - all of that as one object database, which asks its objects directories, packs and loose objects in the order git can be seen to ask them, passes over a broken copy for the next as git does, and names each corruption it meets;
- a limit on the size of an object read whole, which git does not have:
max_object_sizein the options for opening a repository or its object database, a gigabyte by default andnullfor none. A loose object's header, a pack entry's size and the result size each delta of a chain declares are all checked against it before anything of that size is allocated, so that a delta of a few bytes claiming, or really making, an enormous result is refused withObjectTooLargerather than taking the memory. Reading only an object's kind and size reports any size, and streaming an object stored whole needs no more memory however big it is; a server reading repositories it does not trust should set the limit lower; - configuration: the file syntax read on bytes, every corner git accepts
and every malformed line it refuses at the line it names; the system,
global, local and worktree files,
GIT_CONFIG_COUNT,GIT_CONFIG_PARAMETERSand-c, in git's order and with every path and environment value passed in;include.pathandincludeIfwithgitdir:,gitdir/i:,onbranch:,worktree:andhasconfig:remote.*.url:, its conditions answered by the caller; booleans, integers with their units, and paths with~and%(prefix); and lookups that spell keys as git does; - wildmatch, git's glob dialect, as a module of its own for refs,
pathspecs and attributes to use, with the corners
git check-attrandgit tag -lshow; - discovering a repository as git does: walking up from a starting
directory,
.gitdirectories and.gitfiles (linked worktrees and submodules,commondirincluded), bare repositories,GIT_DIR,GIT_WORK_TREE,GIT_COMMON_DIR,GIT_OBJECT_DIRECTORY,GIT_CEILING_DIRECTORIESwith its empty-entry and symbolic link rules, filesystem boundaries andGIT_DISCOVERY_ACROSS_FILESYSTEM,core.worktreeandcore.bare,safe.directoryand ownership,safe.bareRepository, and what git requires of a git directory before it trusts one; the environment, the starting directory and the user are all passed in; - the repository format: versions 0 and 1 and every extension git 2.56
knows, refused with git's own message where git refuses them, and by
name where this library cannot read what git can
(
extensions.compatObjectFormat, arefStoragepayload); - refs: ref names checked by git-check-ref-format(1)'s rules, root refs,
pseudorefs and per-worktree refs told apart, and
main-worktree/andworktrees/<name>/followed; loose refs (symbolic refs, symbolic links, CRLF and trailing garbage read as git reads them),packed-refswith its traits and peel lines, sorted or not; reftables of both versions, SHA-1 and SHA-256, their blocks, prefix compression, ref, obj, log and index blocks and checksums, and stacks of them with their updates and deletions; reflogs from both; all of it behind one ref store that follows symbolic refs as far as git does (five refs, cycles caught), lists refs in git's order, peels tags from the storage or the object database, and shortens names as%(refname:short)does; - dates: every
--date=mode git-log(1) documents, their-localvariants,auto:, andformat:andformat-local:with strftime — flags, field widths, modifiers and the conversions glibc copies as text included — shown as git shows them;TZread as a glibc-linked git reads it, a POSIX rule as leniently as glibc reads one; and git's strict and approximate date parsers — the calendar, the time zone database, strftime and the parsers all from zig-datetime; - the index: versions 2, 3 and 4 (version 4's prefix-compressed paths
included), stat data, modes, stages, the assume-valid, skip-worktree
and intent-to-add flags, padding and the trailing checksum, all zeros
under
index.skipHash; the cache tree with its invalidated nodes, resolve-undo, the untracked cache, the fsmonitor cache, the end of index entries and the index entry offset table; the split index, its EWAH bitmaps and its shared index merged into one list of entries; the sparse index, its sparse directories expanded through their trees when asked; unknown extensions passed over or refused by git's rule, and every complaint git makes of a malformed one in git's words; Repository, the library's way in: a discovered repository opened with its configuration from every source,config.worktreeincluded, itsincludeIfconditions answered by the repository itself (onbranch:from its refs, in either storage), its object database and its ref store, and its index, fromGIT_INDEX_FILEwhen the caller passes it;- revisions, the first of the revision layer: every way gitrevisions(7)
names a single object, read into a structured form with no I/O and
then resolved — object IDs and their abbreviations, ref names by
git's ordered rules with its warnings for names that are more than one
thing,
git describeoutput,@,^<n>,~<n>, every^{...},:/<text>and^{/<text>}with POSIX extended regular expressions (searched newest first, among commits of one date the starting points first, the one named last first, then the commits queued, first queued first; the parents of the commit found read, as git reads them, so that excluding it reaches past them),<rev>:<path>with./and../,:[<n>:]<path>in the index, reflog entries by count and by date (the current time passed in),@{-<n>}, and@{upstream}and@{push}from branches, remotes andpush.defaultin every mode — each failure named and carrying git's message, and ranges and other sets of commits parsed for the walk to come and refused here; - refspecs, fetch and push, read with git's rules and mapped both ways;
- the commit-graph: its file and split chains of them, every chunk — fanout, object IDs, commit data, extra edges, corrected commit dates and their overflow, changed-path Bloom filters of both hash versions, base graphs — and git's rules for passing over a file, dropping a chunk or cutting a chain short, each found by corrupting files git wrote and said in git's words; commits read from it, with the object as the fallback, and generation numbers as corrected commit dates or topological levels;
- walking commits as
git rev-listwalks them: starting points and exclusions,--not,X^@,X^!andX^-<n>(each turned about by a^before it, as--notturns it),--alland the ref listings (the commits named as themselves read first; then, in the order given, a commit named through an annotated tag read and given the tag's exclusion, and each excluded one passing its exclusion to its parents through the commits read by then), the default order with git's handling of equal dates and of clocks that run backwards,--date-order,--author-date-order,--topo-order,--reverse,--max-count,--skip, the parent counts,--first-parent,--ancestry-pathand--ancestry-path=<commit>(descendants through every parent, even with--first-parent, and never through a commit another exclusion excludes; a named commit's ancestors found as git finds them, in one pass down the list, along first parents with--first-parent, and only when it is named by its ID or through a tag that is also a starting point; the commits off the path counted by the sort and--childrenbefore they are left out),--since,--until,--since-as-filter,--boundary, the sides of a symmetric difference (its merge bases queued before either side, which orders commits of one date, and a boundary commit on the left only where the left side reached it or named it, as--count --left-rightcounts them; a listed commit on the side it had when it was listed, so that a walk showing commits as they come out of the queue — one with no exclusions, such as a symmetric difference of unrelated commits, even with--boundary— shows a commit on the right that a commit of the left side reaches only after it came out, where an ordering or--reverse, which list once the walk is done, show it on the left),--left-onlyand--right-only(which leave out of the boundary a commit of the other side the walk took into its list, even one found excluded after it was taken, where a further revision's commits name it as a parent; a parent the walk never took, past the first under--first-parent, is a boundary commit whatever its side) and children — every rule found by comparing a model with git over thousands of generated histories, merges, octopus merges and criss-cross merges included — and, with a commit-graph, git's walk of--topo-order,--date-orderand--author-date-orderby generation number, its three interleaved walks modeled step by step, down to the order its queues give commits they have not yet read, so that--first-parent,--since,--until,--since-as-filter, exclusions and paths list what git lists however the dates run, rewriting through a merge counts its parents relevant as rewriting reaches it, an excluded commit rewriting stops at passes its exclusion on to its parents there, ahead of the explore walk, and a commit rewriting went through before the explore walk found it older than--sincepasses that exclusion on once it is found; where an option such as--ancestry-path,--children,--right-onlyor--simplify-mergesmakes git work out the whole list instead (as--left-onlyand--right-onlymake it for a symmetric difference of unrelated commits, which excludes nothing), it stops by the walk by date's rule, so that it can list a commit an exclusion reaches only through commits dated far back; - merge bases as
git merge-basefinds them,--allin git's order for criss-cross histories,--octopus,--independent,--is-ancestorand--fork-pointfrom the reflog, reading the commits git reads to find them (with a commit-graph, stopping once no commit queued could lead to another base, a base queued a second time not counted), which a symmetric difference's exclusions then reach through. - pathspecs as gitglossary(7) describes them and
git ls-filesandgit logmatch them: literal paths and directories, wildcards matched against whole paths, thetop,literal,glob,icaseandexcludemagic in their long and short forms, paths relative to the current directory with git's errors for one outside the working tree, and theGIT_LITERAL_PATHSPECS,GIT_GLOB_PATHSPECS,GIT_NOGLOB_PATHSPECSandGIT_ICASE_PATHSPECSsettings, all read with no I/O; - two trees compared in step under a pathspec, passing over every subtree
that is the same on both sides or that the pathspec cannot reach, and
yielding each file, symbolic link or gitlink added, deleted or modified,
as
git diff-tree -rlists them; - history limited to paths, simplified as git-rev-list(1)'s "History
Simplification" describes and as git was seen to do where it does not:
the default mode,
--full-history,--dense,--sparse,--simplify-merges,--show-pullsand--remove-empty(whose roots pass on no exclusion, and which leaves a commit listed before it made it a root the parents it was listed with, unless--reverseshows it only after, and one--skippassed none), merges' parents counted only when they are relevant, parents rewritten for--parentsand--childrenwith git's reading ahead,--first-parentwith each of them (a later parent the walk never queued is where rewriting stops, and git counts it as processed without simplifying it, so that should the walk reach it later it is listed and nothing past it is — in a walk that works out its list first (with exclusions, an ordering,--children,--ancestry-path,--simplify-merges,--left-onlyor--right-only) always, and otherwise only while nothing has read it: one the search for a symmetric difference's merge bases read, where it found none, is processed as any other commit, its parents queued; a merge whose first parent is excluded is TREESAME, compared with nothing, when its second parent is relevant (but one found to differ from its first parent before that parent was excluded, even by a symmetric difference's exclusions that the search for its merge bases did not read through, stays as it was found), and is compared with its first parent alone otherwise, whatever its later parents; with parents rewritten, such a merge is listed when more than one of its parents is relevant, and under--show-pullswhenever its first parent differs),--show-pullswith exclusions (under--full-historyor--first-parent, a merge pulls when its first parent is relevant and differs and it is TREESAME to a later parent, relevant or not, as git decides once it knows every exclusion — under--sparse, as it knew them when the merge was simplified; one whose first parent is excluded and differs pulls from none, but with parents rewritten is listed anyway while rewriting goes through it), rewriting stopping at an excluded commit (before processing it, in a walk that works out its list first) and going through a merge--skippassed when one of the parents it was rewritten to is relevant, merges shown against their parents (-m,--dd,--diff-merges), under which git walks the history as--full-historywalks it once any such option is given, even one a later option took back, and the commit-graph's changed-path Bloom filters asked before trees are compared, in the cases git asks them (an item with a wildcard by the directories before it) and with git's own count of what they answered — and asked, as git asks them, under--remove-empty, where a commit that only adds to its first parent takes it for empty when that parent's own filter, which is of what it changed from its first parent, rules the paths out, so that git makes a root of a parent that holds them, and a limited diff of the commit--simplify-mergesleaves no parent is against the empty tree; and--ancestry-path(or--ancestry-path=<commit>) with every mode and option, under which git walks the history as--full-historywalks it and counts a commit off the path as excluded — an irrelevant parent, where rewriting stops and which--boundaryshows — deciding TREESAME again once it knows them, except for a commit--remove-emptymade a root, which keeps what it had; descendants are found through no parent of a commit--remove-emptymade a root, and a named commit's ancestors through none of one it made a root before the commit was simplified; a commit--untilor--since-as-filterkeeps out is not counted off the path, so that rewriting and--simplify-mergesgo through it; --simplify-merges(and--simplify-by-decoration, which simplifies as it does) with every other option, a commit-graph or none, as git was seen to: an excluded parent counts as off the path, as under--ancestry-path, so that a commit TREESAME to its parents with one left besides it is replaced by that one; whether a parent is an ancestor of another is reckoned through the parents each listed commit was simplified to, and through real parents below any commit not in the list (excluded, or off the ancestry path), a listed one simplification replaced included; and a merge that loses a parent for being an ancestor of another, or as a root TREESAME to the empty tree, is TREESAME when it is TREESAME to every parent left on the path (having lost an ancestor, before the roots go, so that a root it is TREESAME to may be all it keeps); a root excluded only after it was found TREESAME counts as a TREESAME root, without--first-parent, for a TREESAME merge and for any merge (with--first-parent, a merge whose first parent was excluded when it was simplified, TREESAME for being compared with nothing, keeps such a root as its first parent: shown, counted, a boundary commit and diffed against), which keeps the first such root it is TREESAME to when it is left none other it is TREESAME to and it is the first parent the merge is TREESAME to (one before it that it lost as an ancestor of another parent it keeps instead, as below, and one in the list it loses, the root too), while a commit with one parent keeps it; a TREESAME merge that would lose every parent it is TREESAME to keeps the first of them, however it lost it, and a merge that would lose every parent keeps the first it is TREESAME to, TREESAME or not (so that a merge TREESAME to a root--remove-emptymade, which its changed-path Bloom filter takes for TREESAME to the empty tree though it holds what the pathspec matches, is replaced by it, and a pull--show-pullskeeps so holds it but shows no parent, and is shown as nothing in its children's parents); git holds, once it has simplified the merges, the parents left and, when none is left, the roots TREESAME to the empty tree they lost (a merge, only those it is TREESAME to), or, when those left are none it is TREESAME to, the first parent it is TREESAME to (shown as well when it is no root, or is one excluded only after it was found TREESAME, and diffed against under--full-diff, a root--remove-emptymade as much as a true one), with the later parents unreplaced under--first-parent, and drops the roots and replaces the later parents only as it shows a commit — so the parent counts count what it holds, and a boundary commit shows it; under--simplify-by-decoration, a decorated merge left no parent is taken for a root TREESAME to the empty tree only when its parents were not all replaced by one; a merge left more than one parent, none of them on the path (every one excluded, or off the ancestry path), keeps them and is TREESAME when it is TREESAME to all of them or was TREESAME already, so that, none of them being relevant, it is not listed but shown as their child (a boundary commit, with--boundary); a merge left only parents off the path, holding on it the first parent it is TREESAME to, counts that one among the parents left when it holds fewer than it had (as when it lost two roots TREESAME to the empty tree), and so is replaced by it; and a TREESAME merge listed with rewritten parents for having more than one relevant parent counts them among the parents it holds once the merges are simplified; ancestry for dropping parents goes through no parent of a commit--remove-emptymade a root, excluded or not and whenever it made it one, and, with exclusions,--sinceor--ancestry-path, through the parents simplification left each commit rather than its real ones (so that under--sparsea merge whose excluded parent is reached only through a commit replaced without it keeps that parent, off the path, and is replaced by the one it has on the path); with--sparse, no commit with one parent is replaced, nor a merge left one parent only by dropping others (ancestors, roots TREESAME to the empty tree, or parents replaced by one another parent is), a merge whose parents are all replaced by one root TREESAME to the empty tree keeping that root as a commit with one parent keeps it, but one left a single parent on the path besides excluded ones it kept is replaced by it, a merge is TREESAME as it was found before the exclusions were known, and the parents are shown as simplification left them (with--first-parent, a later parent the first is replaced by shown twice, and a commit replaced, so shown and so a boundary commit, shown with what it was replaced by and its later parents as they are), with no commit with one parent losing a root; the boundary is sorted by the parents it was found through; with--show-pulls, a pull is listed and kept for the ancestry of the commits naming it, which show it as its one parent when it holds one, and a merge listed anyway (its first parent excluded and different), or a pull left one parent on the path besides others off it, is kept with the parents left before those off the path go (roots TREESAME to the empty tree among them gone, but for the first it is TREESAME to under--sparse), counting the first parent it is TREESAME to among them for--min-parentsand--max-parentswhen it holds none, and shown as it holds them by the commits naming it, as rewriting goes through it, nothing where that reaches such a root (--full-diffdiffs them against the pull or merge itself, and the pull or merge against the first parent it is TREESAME to as well, where that is a root it lost); a commit--skippasses in a walk with exclusions has its parents rewritten, as one outside such a walk does; and a TREESAME parent printed before its child, as one reached through a commit--untilor--since-as-filterkeeps out of the sort can be (a merge counting as TREESAME when it is TREESAME to every parent simplification left it on the path), is lost from the parents the child shows and is diffed against, as git has let go of its parents by then (but--full-diffstill diffs the child against it, so that a merge losing one stays a merge for its diff, shown against each parent under-m), and so is a parent shown for a pull or a merge listed anyway that rewriting goes through when that was printed before the child; and with--first-parent, git simplifies a commit--untilor--since-as-filterkeeps out only when a commit it keeps reaches it through first parents, so that a boundary commit kept out that none does is shown, and diffed, with its parents as they are;- describing commits as
git log --prettydoes, as a library that writes to anIo.Writerand nothing else: the built-in formatsoneline,short,medium,full,fuller,reference,email(with its RFC 2047 encoded words and folded headers),mboxrdandraw, written in the output encoding (--encoding,i18n.logOutputEncoding,i18n.commitEncoding) with commits converted as git, through glibc'siconv, converts them — between UTF-8 and 49 legacy charsets, by every name glibc has for them (ASCII, ISO-8859-1 to -11 and -13 to -16, TIS-620, Windows code pages 874, 932, 949 and 1250 to 1258, KOI8-R, KOI8-U, KOI8-RU, IBM866, the Macintosh Roman and Cyrillic sets, the EBCDIC code pages 037, 500, 875 and 1026, EUC-KR and Johab, EUC-JP with JIS X 0212, Shift_JIS as JIS X 0208 has it (glibc'sSJIS, not code page 932), GBK (code page 936), EUC-CN (GB 2312), GB18030, Big5 (code page 950), ISO-2022-JP as RFC 1468 has it, and as output encodings UTF-16, UTF-32, UCS-2 and UCS-4 in every byte order glibc has, with the byte order mark glibc writes), byte for byte through zig-charset, failing where glibc fails and leaving the commit as it is then, as git does; a name glibc does not know converts nothing, as in git, andlatin-1, which glibc does not know, is ISO-8859-1, as git has it; a format string is written from the commit in UTF-8 and converted whole, its own characters included, as git converts it; ISO-2022-JP is written as git leaves it, with no escape back to ASCII after its last character, so a format string ending in Japanese ends in JIS X 0208 before the line feed; CP1255 and CP1258 compose a base and a combining mark when read and spell a character they lack as base and mark when written, as glibc does, and a text in either that ends in a character glibc holds back for a mark that might follow loses that character, as it does in git;emailencodes a name or subject holding an ESC, as ISO-2022-JP's escape sequences do, as it encodes one past ASCII, and names the output encoding in its encoded words andContent-Type; andformat:,tformat:and bare%strings with every placeholder that needs no decorations, notes, signatures or reflogs — object IDs whole and shortened, identities in every date mode and through the mailmap, the subject, body and sanitized subject,%x00, colors with%C(auto), padding and truncation in all eight forms,%w(...)wrapping, the+,-and space magic, and%(trailers)with every option — down to what git does with a NUL, a control character or a placeholder it cannot answer, found by comparing with git over thousands of generated formats and commits; andpretty.<name>aliases; - trailers found as git-interpret-trailers(1) finds them, with
trailer.separators, configured trailers and the comment string; - mailmaps as gitmailmap(5) describes them, every line form, with git's
rules for repeated and conflicting lines found by experiment, read from
the work tree,
mailmap.file,mailmap.bloband a bare repository'sHEAD:.mailmap; - choosing commits by their messages and identities as
--grep,--authorand--committerdo, with--all-match,--invert-grep,-i, and glibc's basic and extended regular expressions with GNU's escapes, or fixed strings, and the mailmap applied to identities when git applies it; - decorations as
git log --decorateshows them: the refs,HEAD -> <branch>,tag:,graftedandreplaced, in git's order, short or whole, chosen by--decorate-refs,--decorate-refs-exclude,--clear-decorations,log.excludeDecorationandlog.initialDecorationSetwith git's rules for its patterns, colored bycolor.decorate.*;%d,%Dand%(decorate:...)with every option;--sourceand%S(each commit named for the first starting point whose walk reached it, the commits ofX^@,X^!andX^-<n>named forX, a commit excluded when it was walked passing its name to none of its parents, so that a boundary commit is named for a commit listed or listable); and--simplify-by-decoration, simplified as git simplifies it, from a range with exclusions too, with or without--ancestry-path(or--ancestry-path=<commit>), where git lets go of parents off the path as it was seen to — an excluded commit counts as off it unless it is an excluded starting point, a commit with one parent left counts as TREESAME to it when that parent is irrelevant, and a merge it keeps is listed for its relevant parents on the path among those it was left, and loses a root off the path TREESAME to the empty tree as it loses a listed one, unless--first-parentis given — with several exclusions and with--first-parent, with the parent counts,--sparse,--boundary,--show-pullsand--remove-emptyas--simplify-mergestakes them (below), and with paths, where a commit is kept when it is decorated or changes them; a root, decorated or not, is kept only when it holds something they match (without paths, anything at all), and likewise a decorated merge simplification leaves no parent, which git takes for such a root — though--show-pullsand--sparsestill list it, and--first-parent, which leaves it one parent to decide by, keeps it — so that its children lose it as they lose a root, holding it for the parent counts only where they are TREESAME to it, and ancestry goes no further; - naming commits by the nearest tag, as
git describedoes: annotated tags, lightweight ones or every ref,--matchand--exclude, git's choice among the names of one commit, its choice among candidates of every kind (the nearest, whatever kind it is, the first found among equals), where its search gives up (at the commit after the last candidate it weighs, at most 28 of them and no more than there are named objects), and its depth, which is counted as git counts it rather than as git-describe(1) says, all found by comparing with git over every commit of generated histories; a tag whose own name is not its ref's, which git warns is "externally known" by it and writes by that name with its depth and object; and%(describe:...)with every option; - the reachability filters
--contains,--no-contains,--merged,--no-mergedand--points-at, asgit branch,git tagandgit for-each-refanswer them; - two texts compared line by line in the edit script git chooses, not
merely a shortest one: the linear-space refinement of Myers' algorithm
as his paper gives it, with what git was seen to add — lines that occur
only in one text taken out first, lines that occur very often taken out
where the lines around them say so, the search for a middle snake given
up at git's cost limit on large, much-changed texts, and split early
past 256 steps as git splits it (refused in a few places, see below),
runs of changes
slid and merged as git slides them, git's indent heuristic (on by
default) placing each run by the indentation and blank lines around it,
and the common tail git sets aside for a patch without context — and
--minimal, all found by comparing a model with git over many thousands of generated texts;--patience(src/diff/patience.zig): Bram Cohen's patience diff, the lines unique to each side matched along a longest increasing subsequence found by patience sorting, with every detail git adds found by experiment — which ranges are trimmed of their common head first, how matched lines are extended, and the range with no unique line compared as Myers compares it;--anchored=<text>, the new text's lines that start with one of the texts kept as git keeps them;--histogram(src/diff/histogram.zig), a model of git's choices (see below): the run of matching lines with the fewest occurrences in the old text, then the longest, found by reading the new text from its start, a later equal run from the same old line taking its place where it reaches the end of the texts, lines occurring more than 64 times passed over, and Myers for a range with nothing else to match, the texts the other way round before such a later run; the algorithm chosen as git chooses it — the last of--minimal,--patience,--histogramand--diff-algorithm,--patienceforgetting earlier anchors,diff.algorithmbeneath them, and adiff=<driver>attribute'sdiff.<driver>.algorithmabovediff.algorithmand--anchoredbut below the rest, for patches and the counts but not, as git was seen not to, for combined diffs, which also leave the anchors out; the whitespace options-w,-b,--ignore-space-at-eoland--ignore-cr-at-eol; hunks with-U<n>,--inter-hunk-context,--ignore-blank-linesand-I<regex>, merged and left out as git does, git's own notion of a blank line included (-Imatches each line with its newline, lines apart asREG_NEWLINEkeeps them, with GNU's escapes, so^$matches every line that ends in a newline and hides an added file's lines and counts, whilex.andx[^a]do not matchxat a line's end); function names after@@by git's default rule or a diff driver's, cut as git cuts them;-W, each hunk reaching over the whole of the functions its changes are in as git's hunks were seen to reach, the lines just above a function line and git's odd ends of the text included; and the patch for a pair of files — thediff --githeader, mode lines,new file modeanddeleted file mode, theindexline in SHA-1 or SHA-256,---and+++with prefixes and quoted paths,\ No newline at end of file, and binary files told apart as git tells them; - attributes, as gitattributes(5) gives them: the system and global
files, every
.gitattributesfrom the top down to a path's directory andinfo/attributes, read lazily and in git's order, from the working tree with the index behind it, the index alone or a tree (attr.tree,GIT_ATTR_SOURCE); patterns matched as gitignore(5) reads them, macros (binarybuilt in) expanded where they are set, and git's warnings about bad lines, said as often as git says them; - diff drivers' function lines:
diff.<driver>.xfuncnameandfuncname, whichever was set last, as several patterns one to a line with!for those that rule a line out, the text git shows being the first group of the match where it took part, and git's errors for a malformed or wrongly negated pattern, said when git says them; the regular expressions match as glibc's do, the leftmost-longest match and glibc's choice of groups within it (which is not POSIX's), found by comparing with git over thousands of random patterns; and all 28 of git's built-in drivers (ada,bash,bibtex,cpp,csharp,css,dts,elixir,fortran,fountain,golang,html,ini,java,kotlin,markdown,matlab,objc,pascal,perl,php,python,r,ruby,rust,scheme,swiftandtex), as patterns of zig-git's own fitted to which lines git takes and what it shows of them, each over at least 3,000 random lines (18,000 and more for most) with no difference left; their word patterns are not done; - the index compared with a tree and with the working tree from the stat
data it holds, without refreshing or writing it: modification and
change times in whole seconds, inode, owner, group, size and mode, as
experiments showed git compares them, racily clean files hashed, and
intent-to-add, assume-unchanged, skip-worktree and unmerged entries as
git treats them; or, as
git diffdoes after refreshing, a file whose stat data alone changed taken to be unchanged by its contents; - files in the working tree converted on their way in as git converts
them before comparing (
convert): line endings undercore.autocrlf,core.eoland thetext,eoland legacycrlfattributes,auto's test of what looks binary and its "safer autocrlf" look at the blob the index holds,ident's$Id$, andworking-tree-encodingthrough zig-charset — the legacy charsets above and UTF-16, UTF-32, UCS-2 and UCS-4 in every byte order glibc has, with git's byte order mark rules forUTF-16,UTF-32and theirLEandBEforms (a mark required without a byte order in the name, prohibited with one, git's hint and error written, incolor.advice.hintundercolor.advice=always), and//TRANSLITand//IGNOREchanging nothing, as glibc acts on them only for the charset converted to — with git'score.safecrlfwarnings and encoding errors on standard error as often as git writes them in the common cases (not yet-wwith--check, with--dirstatand a patch, or with--summaryalone, nor the filesgit diffwas seen to read again outside the paths given); afilterdriver with no command configured is passed over, and onerequiredstops as git stops. All of it was found by experiment with git 2.56 and checked over 300 random repositories (11,700 invocations of the commands grebe runs and the plumbing), and again over 300 with a third of their files in UTF-16 and UTF-32. What still differs is git reading a file in the working tree in place of the blob the index holds when its stat data vouches for it: zig-git reads the blob, which shows otherwise only when a file was rewritten without its size or time changing, or when a conversion of it would have failed; - every format git writes for a list of changed paths: the raw format
(
--abbrev,-z),--name-only,--name-status,--diff-filter,--numstat,--statwith git's layout (fitted to over a thousand of git's outputs: the widths,COLUMNS,diff.statNameWidth,diff.statGraphWidth,--stat-count, and the bars' scaling),--compact-summary(what--summarysays, in brief, beside each name in the diffstat),--shortstat,--summaryand the patch, in git's order, with-R, binary files told by attributes, contents andcore.bigFileThreshold, gitlinks asSubproject commitlines, and what whitespace options and-Idrop from each format; - the values of the diff options read and checked as git reads and
checks them, with its messages and exit statuses:
--abbrev=with any text (read as C'satoi, below 4 as 4, negative as the whole ID),--stat=with fields left empty or negative,--stat-width,--stat-countand the other widths as numbers with a sign (0 and -1 the defaults, a negative count no files),--unified=with nothing as 0,--inter-hunk-contextin octal, hexadecimal and with a unit,--dirstat=with nothing,-land-Iwithout a value or with a bad one; and--color-moved,--color-moved-ws,--ws-error-highlightand--word-diff, whose values are checked and, since they only color (or change only a patch), otherwise change nothing here. Short options run together (-pw,-pU5,-pS x) are read each as on its own, and what follows the first letter that is none is read as one of the command's own options where git reads it so (diff-index -pm,diff-files -pq,diff-tree -p-stdin), and otherwise refused in git's words (--no-index'sunknown switch); - the pickaxe, as gitdiffcore(7) describes it and as git was seen to
count:
-S<string>(occurrences counted without overlapping, NUL bytes and binary files searched),--pickaxe-regex(matches counted as git resumes its search, the rest of the text not beginning a line, empty matches included),-G<regex>(each line a diff adds or deletes matched alone, with its newline, binary files passed over without--text),--find-object(either side, a blob or a submodule's commit; a working tree file whose object git has not computed, never),--pickaxe-all, and-i, indiff,diff-tree,diff-index,diff-files,log(choosing the commits shown) andshow, withlog --find-objectwalking paths as--full-historydoes, as git was seen to; inlogthe diff (the pickaxe,--diff-filter,--follow) leaves a commit out after--skiphas counted it and before--max-countdoes, after its parents are rewritten (and, once--max-countcommits are shown, git takes no other, so a--boundarycommit after them shows the parents it had), lets go of the parents of the commits it leaves out as of those it shows, and shows a--boundarycommit only where it would show its diff, the parents of the commits it left out counted among the boundary and the order kept that the boundary has with every one of them, with git's errors for patterns and for options it refuses together: a-Gor-S --pickaxe-regexpattern git cannot compile stops it where it first works out a diff, which for a merge shown combined (-c,--cc) is after the merge is written, under-sand--no-patchtoo; matched over 2,400 random cases; - orderfiles (
-O<orderfile>,diff.orderFilefor the porcelain, read, with git's error when they cannot be, only once a diff git works out has a pair left to order after the pickaxe: before the commit is written for a commit's diff against its parent and a merge's against its first parent or each parent, and for a merge shown combined only once the commit and its empty line are written, when a path is left that differs from every parent or, with--statand the other counts, when the diff against the first parent has a pair;--diff-mergesalone, or with every format taken back by-sor--no-patch, works out the merges' diffs and no others, and the diff filter, which may look at every commit before any is written, stops nothing until the commit it stops at comes to be written),--skip-toand--rotate-to(inlogandshow, from the first path at or after the one named; in a merge's combined diff only where each parent's diff is made on its own, as below, and otherwise passed over, even naming a path not in the diff),--relative[=<path>]anddiff.relative(the prefix matched as a string and cut off every path but--summary's, a bare--relativeafter--relative=<path>taking that path, even with a--no-relativebetween them; the orderfile and the rotation still match the whole paths, so--relative=dir/ --rotate-to=dir/xstarts at what is written asx, and of the pairs taking one deleted source the last in the new order is the rename),--line-prefix(before every linelogandshowwrite, the porcelain's--statnarrowed by its width, and before each commit and each diff wherever the line before it was left, so that a description that writes nothing still writes the prefix, and a description that does not end its line is followed by the prefix before the diff's empty line; under-zthe prefix starts each commit after the NUL, the NUL between two commits goes without it, and so does the line feed between two after a description that did not end its line;showwrites tags, trees and blobs without it; a--line-prefix=<prefix>that is the value of another option, as in--rotate-to --line-prefix=x, is that option's value, and no option before--takes--as its value) and-D(--irreversible-delete, a rewrite's hunk counting its old lines as-?,?); --check: trailing whitespace, a space before a tab in the indent, an indent of spaces (tabwidth), a tab in the indent, new blank lines at the end of a file (counted, as git counts them, only from where a line ends at least two bytes into the file, which in a file of blank lines alone leaves out its first line or two), a last line without a newline and leftover conflict markers (conflict-marker-size, read as git reads it: a whole number within 32 bits, signs and leading zeros allowed, 7 kept for one that is not positive, and a warning for each path checked whose value is not a number), ascore.whitespaceand thewhitespaceattribute choose (whose words may be cut short, as git matches them), each found by probing git line by line, with git's exit statuses 2 and 3 (which--quietleaves out, exiting 1 when anything differs as the options compare it, and 0 otherwise); a file whose changes a whitespace option or-I(with--ignore-blank-linesbeside them) hide whole is passed over, unless it was added, rewritten, renamed or copied or its mode changed, and--exit-codecounts what differs as those options compare it;--textleaves binary files unchecked, as it does in git; and-Bbreaking a type change between a file and a symbolic link, shown asT100;- a
whitespaceattribute asking for bothtab-in-indentandindent-with-non-tab, on which git stops with "cannot enforce both" where it comes to that path: under--check, before anything is said of it; in a patch, as it comes to a text file's lines, after the header of a file added or deleted, renamed, copied, rewritten or whose mode changed and before a plain change's; and where git compares contents first (a whitespace option or-I,--exit-codeor--quiet), before the raw or name line of any text file, with everything before it written; --dirstat(-X,--dirstat-by-file,--cumulative,diff.dirstatwith git's warning) in itschanges,linesandfilesmodes, the damage of each path measured as git was seen to measure it (the kept chunks rename detection counts, lines, 64-byte pieces of a binary file), directories folded and shown as git shows them, in path order whatever order--rotate-toor-Ogives the pairs, with--relative's paths counted whole except inlinesmode, a rename or copy at the whole path it went to;-tinlog,showanddiff(between two trees; elsewhere it changes nothing) as indiff-tree: the trees on the way to each path differing shown as pairs of their own in the raw, name and summary formats, and counted by--dirstatas one changed file each (one byte underchanges, nothing underlines). Wherever git compares contents to decide what differs, under a whitespace option,-I, ordiff's--exit-codeand--quiet, the raw and name formats leave the trees out, as they leave out any path whose patch would show nothing, and the exit status does not count them; the summary keeps them. With merges' diffs (-m,--first-parent,--diff-merges),-tasks for a diff as--full-diffdoes: the patch--diff-mergesimplies goes to every commit, and-mshows a merge once for each parent even with no diff written.-rchanges nothing else inlogandshow, whose diffs go into subdirectories anyway, but asks for merges' diffs as-tdoes. A merge's combined diff (-c,--cc, a mergeshowis given) lists a tree where its entries differ from every parent's, a tree's entry paired only with a tree's, and stops at the first tree in a patch, or in the pickaxe, with git'sfatal:message, after what came before it (its counts against the first parent among them). The pickaxe stops so at a tree in any commit's diff aslogandshowcome to show that commit, once those before it are written, in a walk with exclusions,--reverseor--boundaryas well, and under-mafter the parents before; and-v, which changes nothing they write; andzig-git whatchanged, with--i-still-use-thisas git 2.56 asks,logwith the raw format and commits whose diff is empty (unless--always) left out, and merges given no diff unless-masks for them (paths, with which git was seen to walk otherwise, are refused). What only zig-git refuses or fails at names the command run,whatchanged,logorrev-list, though each runs through the next; where git names one itself, aslog's usage does forwhatchanged, its naming is kept.
zig-git diff --no-index compares two files, or two directories file by
file, and prints what git diff --no-index prints, with its exit status
and its errors: every option above, --diff-algorithm, -R, --quiet,
--exit-code, --output, --text, --full-index, --abbrev,
--no-prefix, --src-prefix, --dst-prefix, --default-prefix, and
diff.algorithm, diff.context, diff.interHunkContext,
diff.indentHeuristic, diff.noprefix, diff.mnemonicPrefix (1/ and
2/ without an index), diff.suppressBlankEmpty, core.quotePath,
diff.renames and diff.autoRefreshIndex (each stopping, as git
stops, at a value that is not a boolean, without naming the file);
symbolic links compare as their targets (a link against a file as a
deletion and an addition), executable files by mode, and
directories by name, a file on one side and a directory on the other
shown as git shows them. Colors (where git would color), --binary, --stat and the other
summaries, word diffs, rename detection, pickaxe and - for standard
input are refused there by name, and so are two directories with a file
only on each side that git could take for a rename (the same contents,
or two files at least half alike) unless diff.renames is false or
--no-renames is given.
zig-git diff in a repository compares the index with the working tree,
a commit with the index (--cached, --staged) or the working tree, and
two commits or trees (A B, A..B), with pathspecs, every format and
option above, and the configuration git diff reads (diff.context,
diff.interHunkContext, diff.algorithm, diff.noprefix,
diff.mnemonicPrefix, diff.srcPrefix, diff.dstPrefix, the stat
widths, diff.renames), where diff-tree reads none of that
configuration but heeds --no-prefix as it does the other prefix
options; zig-git diff-tree compares two trees, a
commit with its parents (-r, -t, --root, -m, --always,
--no-commit-id, --stdin), or two commits' merge base with the second
(--merge-base), shows a merge as a combined diff (-c, --cc,
--combined-all-paths), and with -v, --pretty, --format or
--oneline describes each commit as git log would in place of its
line (--abbrev-commit, --date, --expand-tabs, --encoding,
i18n.logOutputEncoding), as git was seen to: its object IDs whole
unless --abbrev is given, none of the log.* settings or
format.pretty read, email without [PATCH], the commit separated from
its diff as log separates them, --always writing it once where
nothing differs, and --first-parent changing nothing;
zig-git diff-index a tree with the index
or the working tree (--cached, -m), and zig-git diff-files the
index with the working tree (-0, -1, -2, -3, --base, --ours,
--theirs, -q), each reading only the configuration git's plumbing
reads. Their exit status under --exit-code is git's, its quirks
included: diff exits 0 when --summary or --dirstat measuring changes
or files is all it writes, whatever changed, and the other three do the
same under a whitespace option or -I; asked for its exit status
(--exit-code, --quiet), diff compares contents as a whitespace
option makes the others do, so that a path whose patch would show
nothing (a tree -t lists, a change --ignore-blank-lines hides)
neither counts nor shows in the raw and name formats, and a working
tree file shows its object ID; under --quiet it looks for no renames
or copies, whatever asked for them, though -B still breaks rewrites; and diff-tree's is that of the
last comparison it made (a merge's last parent under -m, the last line
of --stdin compared), one left out under --quiet after a difference
counting as none, though with --diff-filter or --skip-to every
comparison is made. Under a whitespace option or -I, which compare
contents, a difference any comparison found counts; but where the counts
(--stat, --numstat, --shortstat) are written, without --quiet,
it is that of the last comparison with any path to count. Under
--quiet no format is written, and what differs is decided as with none. diff-tree --stdin reads its lines as git was seen to:
as far as a NUL; a line not starting with an object ID in full (an
abbreviated one, a name, garbage, an empty line) written back as it came;
a commit compared with its parents, or with the commits whose IDs follow
it, each after one space, tab or carriage return; a tree with exactly one
more tree, the pair written before what differs whatever the options;
and git's errors for a blob, a tag, a missing parent or a lone tree;
diff-tree writes its usage for an option it does not know once the
revisions are read and the options checked against each other, as git
does.
Every one of them finds renames and copies as git does: -M[<n>],
-C[<n>], --find-copies-harder (or -C a second time; copies, and
so renames, are then looked for harder until --no-find-copies-harder,
whatever --no-renames or -M says between, and under -t the
unchanged trees are sources as well, copied from whole as git copies
them), -l<n> and
diff.renameLimit with
git's warnings when the limit is reached (once at the end of log,
diff-tree --stdin, a show given a count and the others, with the most any diff needed; after
each commit show is given, saying again what the last one needed when
that commit needed nothing; and never for a merge's combined diff or
under --follow, whose search for where a file came from is still cut
short by diff.renameLimit, though not by -l<n>), --no-renames,
--rename-empty, and diff.renames (on by default) for diff, log
and show, the pairs scored on the chunks git counts them by
(src/diff/similarity.zig) and chosen as git chooses them
(src/diff/renames.zig: among sources equally good, one with the
destination's file name, the path --relative cuts to nothing having
its directory's name), and written in every format: R096 and C100
in the raw and name formats, similarity index, rename from and copy to in the patch, a/{b => c} in --stat, --numstat and
--summary. -B[<n>][/<m>] breaks rewrites into a deletion and an
addition for renames to take, and shows those nothing took as rewrites
(M100, dissimilarity index, the whole file's lines, rewrite in
--summary, B for --diff-filter). zig-git log --follow <path>
(and log.follow with one path) follows a file back through its renames
and copies, as git does: commits chosen by the pathspec they followed,
and where the path it names was added, its source looked for among every
path, unchanged ones included; -S and -G then choose among those
commits, the renames still followed where the pickaxe leaves them out.
Which path a commit is looked at with depends, as it does in git, on the
order the walk takes commits in: it is the one the commit's child came
away with (the child looked at last, where there are several), or, for
a commit none of whose children was looked at yet, the one the commit
looked at just before came away with. So a rename found on one branch is
followed on another branch the walk comes to next, though not on a
branch whose commits it had already reached. Merges the walk leaves out
(--no-merges, --max-parents=1) are not looked at, and pass no path
on to their parents. Under --follow every commit's diff is written
where --diff-merges asks only for the merges' (as -c and --cc do).
zig-git log and zig-git show write each commit's diff in any
of these formats after its message (--full-diff, --first-parent,
log.showRoot, and --root, which shows the root commits' diffs
whatever log.showRoot says), with the separators git puts there in each pretty
format (under --no-commit-id each commit comes after its diff, with no
separator between them and no (from <parent>), and only where every
commit listed is shown whatever its diff: never under --diff-filter, the
pickaxe or --follow, nor in whatchanged without --always, where the
commits left unwritten are not counted by -n; --always lists the
commits whatchanged would leave out for an empty diff, merges among
them, and changes nothing in log and show), show defaulting to the patch, and show merges as -m,
--diff-merges=off|on|first-parent|separate (each merge once per parent,
with (from <parent>) on its first line), --dd, --no-diff-merges
and log.diffMerges ask, or as combined diffs (-c,
--diff-merges=combined) and dense combined diffs (--cc, --dd's
merges aside, --diff-merges=dense-combined, and git show's default
for a merge): the raw format with a colon per parent, the names with a
status per parent, and the combined patch with its column per parent
(src/diff/combined.zig), the raw format, the names and the counts for
merges of any number of parents and the patch for up to 62 (where a
parent loses a line an earlier one lost, the 33rd on marking it in the
column 32 places before its own and not counting it among its lines,
and the 32nd marking it in its own column and every one after, the
parents after it counting it, as git was seen to mark and count them),
paths
renamed or copied against a parent compared with their source there
(and each parent's path named with --combined-all-paths, which git
forgets at any later option choosing how merges are shown, and refuses
without -c or --cc), each parent's line diff made as a patch without
context makes it (its common tail set aside), the lines different
parents lost merged as the whitespace options compare them
(--ignore-cr-at-eol merging lines that differ in any blank space at
their ends, as --ignore-space-at-eol would), and a parent
the same as an earlier one marked wherever that one is,
its function names found as git finds them there (by the default rule
whatever the diff driver, from no further back than the hunk before, cut
short at 40 bytes and then by one more) and binary files, as attributes
and drivers decide them, said to differ. The dense form leaves out each
stretch of changes where the parents have only two versions and the
result takes one of them as it is, as git-diff-tree(1) describes it,
and the same parents make every change of it (where parents lost the
same lines at different places, git shows the stretch);
which changes make one stretch, and how a hunk is counted around a
change left out, were found by experiment and matched over thousands of
generated merges of two to four parents. Without context (-U0) only
the changes are written, with git's counts, even the one less it gives
a hunk reaching past the end of the file. -W and
--inter-hunk-context leave a combined patch as it is, as they do
git's, and -I stops at the first merge as git does. --diff-filter
and the pickaxe are applied to each parent's diff, and a combined diff
keeps a path only where every parent's diff kept it, found by walking
the parents' diffs together and comparing paths as git was seen to
compare them: as tree entries, where a path the merge has as a tree goes
on with a / and a deleted tree's does not. So a path --rotate-to or
--skip-to moved ahead of where the walk has reached is left out, a
deleted file is paired with a deleted tree of the same path, and under
-t a later parent's tree can be paired with a path inside it, which
git writes as a raw line and then stops at in a patch (--pickaxe-all
keeping a parent's whole diff when any of its paths matches). git makes
a combined diff of each parent's diff on its own only when it looks for
renames, copies or rewrites (-M, -C, --find-copies-harder, -B,
diff.renames, on by default in log and show), or filters the pairs
(a --diff-filter that is not empty, -S, -G); otherwise it writes
the diff as though -R and --relative were not given, and keeps a path
for --find-object where any parent's side or the merge's is the
object. Made of each parent's diff, -R turns each pair about before
--diff-filter sees it, so that the parents' columns show the merge's
side and the result is the first parent's; --relative keeps only the
paths under its prefix, before renames are looked for, and they are
written whole; a combined patch keeps the a/ and b/ prefixes either
way. Under --ignore-blank-lines a change of blank lines alone, as a
patch without context would leave it out, is no change to the parent it
is against: its lines in the result count as that parent's, its lines of
the parent are not shown as lost, and the parent's line numbers in the
hunk headers count as git counts them, one for each result line not
added against it and each line it lost. A rewrite -B broke is
compared as any other change, its status M. The names a combined diff
lists (--name-only, --name-status) and its patch's mode and
Binary files differ lines go without --line-prefix; with --check
a combined diff writes nothing in any format after its empty line, and
the empty
line before a combined patch is written after --stat and the other
counts even when they show nothing: when the whitespace options leave
them empty, or when --relative leaves the diff against the first
parent no pair while the combined diff, not made of each parent's diff,
does not heed it. A merge
shown combined is listed whatever they leave of its diff, while other
commits, and under -m a merge's entry for a parent, are left out when
they leave nothing, before a count (show -1 -S<string>) counts them.
--diff-merges alone patches only the merges, and every commit under
whatchanged, --diff-filter, the pickaxe or --full-diff; -c,
--cc and --dd patch every commit. A later -m, --no-diff-merges
or --diff-merges takes back the patch either implied, as git was seen
to (log -c -m writes no diff, whatchanged -c -m the raw format).
Under --first-parent, log and show show a merge they would show
against each parent (-m, --diff-merges=separate, log.diffMerges)
against its first parent alone, and a combined diff as it is, whichever
order the options come in; whatchanged still shows it against each
parent.
Which parents log diffs a commit against was found by comparing its
diffs, commit by commit, with git diff-tree --stdin given each
candidate list of parents, under every way of simplifying history:
- without paths, and with
--follow, the commit's own parents; - with paths, the parents history simplification left it, which are
the commit's own except for a merge TREESAME to a parent, which has
that parent alone (only
--sparselists such a merge;log --sparse --format=%pshows the one parent as well); - when parents are rewritten (
--parents,--children) and the diff is limited to the paths, the rewritten parents instead: two parents rewritten to the same commit make a merge a commit with one parent, diffed two ways, and a commit whose parents are rewritten to none is diffed as a root. Under--full-diffit is the parents simplification left, not the rewritten ones, and a boundary commit is diffed as a root; - under
--simplify-mergesand--simplify-by-decoration, with or without--parents, the parents they show, or, where a commit shows none, the root TREESAME to the empty tree that it reached (its whole tree is then diffed against that root's; a merge, only against those of the roots it lost it is TREESAME to, and against the empty tree when it is TREESAME to none); under--full-diff, the parents they show and, when the commit is TREESAME to none of those, the first parent it is TREESAME to where that is a root TREESAME to the empty tree it lost (directly, or through a parent replaced by it), in its order — with--first-parent, which decides by the first parent alone and shows the later ones replaced, that is the first parent even where it was dropped, followed by the later parents as they are, not replaced. A boundary commit--sparseshows with what it was replaced by is diffed against the parents it shows.
A merge shown against each parent (-m, --diff-merges=separate)
that has no entry left, nothing differing from any parent, is written
once, as a commit with an empty diff, as git does. A boundary commit
nothing has read (a later parent under --first-parent that neither
the walk, nor a symmetric difference's search for merge bases, nor
resolving the revisions — HEAD~5 reads HEAD to HEAD~4, and a
message search the commits it looks through and the parents of the one
it finds — read)
shows its own parents in %p and %P, and none after --parents
unless a diff was made for it; it is dated zero where the boundary is
ordered by commit date (where it is ordered by author date, git reads
its author date for the sort), and its parents are not known to the
boundary's order, unless a listed commit was diffed against it before
the boundary was gathered (the one parent of a commit with one, the
first parent of a merge shown against it, every parent of one shown
against each; git was seen to read none for a combined diff). No diff
is made then under --reverse, which holds the whole list back first,
and where no format writes one (-s) git works out the diffs of every
commit only while -c, --cc or --dd makes the patch the default,
only the merges' after --diff-merges, and none otherwise. Under
--simplify-by-decoration a boundary commit is diffed against the
parents it shows.
In a combined diff, a parent's status for a type change (a file
becoming a symlink or a submodule) is written M, as git writes it,
except that it is T while renames, copies or rewrites are looked for
(-M, -C, -B, diff.renames, which log and show turn on by
default).
-S, -G, --find-object and --diff-filter choose commits by the
same diffs.
zig-git diff-tree takes --diff-merges, --no-diff-merges and --dd
as git's diff-tree does (on meaning separate whatever
log.diffMerges says, and --dd keeping the raw format). zig-git check-attr reports
attributes as git check-attr does (-a, --cached, --source,
--stdin, -z, builtin_objectmode).
zig-git cat-file (-t, -s, -e, -p and <kind> <object>) answers
from the library for objects named by any single revision
(cat-file -p HEAD~2:src/x.zig), wherever they are stored, printing what
git cat-file prints, its error messages, explanations of paths not
found and ambiguity hints included; like git's, it takes no range and
searches no message.
zig-git show-index and zig-git verify-pack [-v] [-s] print what git's
do, the delta chain histogram included. zig-git config reads
configuration as git config does — --get, --get-all,
--get-regexp, --list, the get and list subcommands, with
--show-origin, --show-scope, -z, --name-only, the types bool,
int, bool-or-int and path, and every file option — its output,
errors and exit statuses included. It writes nothing, and refuses by name
what it does not do: --blob, --url, the color and expiry-date
types, and GNU's regular expression extensions and back references.
zig-git rev-parse answers the questions about where a repository is —
--git-dir, --absolute-git-dir, --git-common-dir, --show-toplevel,
--show-prefix, --show-cdup, the --is-* questions,
--show-object-format, --show-ref-format, --local-env-vars and
--path-format — as git rev-parse does, and answers single revisions
with --verify, -q, --short[=<n>], --symbolic,
--symbolic-full-name, --abbrev-ref[=(strict|loose)], --default,
--end-of-options, --, --not, --revs-only (keeping the options
git keeps for rev-list, which were found by trying every one its manual
names) and --disambiguate=<prefix>, telling revisions from paths as git
does, and lists refs with --all, --branches, --tags, --remotes,
--glob and --exclude. It prints ranges and the other sets of commits
as the revisions they stand for (A..B as B and ^A), in each of its
ways of naming them, and refuses by name the options it does not have
(--sq, --no-revs, --since and the like).
zig-git rev-list walks commits as git rev-list does, with every
option above and --parents, --children, --timestamp,
--left-right, --count (boundary commits counted too), --abbrev-commit,
--max-age and --min-age (seconds read as git reads them: 64 bits
without a sign, a negative number counted back from 2^64, -1 setting no
limit, the last of each and --since or --until deciding), the searches by message
and identity, and every format log has; it takes paths, after -- or, where they
are there, without it, with git's complaints about an argument that is
both a revision and a file, a later one that is neither, and an option
after a path, and simplifies the history they limit in every mode above.
It reads the diff options as git's rev-list does, writing no diff. Each
is checked as log checks it, a bad value said in git's words as it is
read (--unified=x, --diff-filter=Q, -l3000000000,
--max-depth=2g, --patience=1, an object --find-object cannot
find), and the options git refuses together once it has read them all
are refused as git refuses them (-S with -G, --name-only with
--name-status). Most are then ignored: the commits are listed as
without them (--word-diff, --patience, -M, --relative,
--exit-code, -W, -I<regex> and the rest). git's usage is written,
once every argument is read, for an output format left chosen (-p,
--stat, --raw, --name-only, -U<n>, --binary; a later -s or
--no-patch takes it back), for the pickaxes (-S, -G,
--find-object), for --diff-filter with any class, --full-diff,
and a bundle of short options (-ps is read as -p -s) ending in a
letter that is none of them. How merges are shown: -m, --dd,
--remerge-diff and every --diff-merges format but the combined ones
and off walk paths' history as --full-history once given at all,
whatever log.diffMerges says; -c, --cc, --dd and
--remerge-diff choose the patch as well, which only a later -m or
--diff-merges takes back; and --combined-all-paths is refused, in
git's words and git's order, unless the last of them chose a combined
diff. -v is rev-list's --header. -z is refused wherever it is, as
an option's value or a path after -- too, since git's rev-list ends
its commits with NULs for it there as well, though not their count.
With a format (--format, --pretty, --oneline, --header, -v),
--left-right or --timestamp, git stops with -z option used with unsupported option instead, before it walks, whether or not a commit
would be listed and with --count too, after a pathspec it cannot read
and an option it does not know and before its usage for no revision;
that is matched.
--output is refused, since git creates the file it names, and so is
--no-ignore-matching-lines, at which git aborts. It looks for the repository
before it reads its arguments, answering
-h or --help-all on its own with git's usage first, outside a
repository too; reads its arguments in order, as log does (below); and
writes git's usage, once the revisions are found, for an option it does
not know or nothing to start from. --log-size is accepted and, as in
git's rev-list, changes nothing. It refuses by name --follow, --default, --objects,
the options of packing and partial clones (--no-kept-objects,
--exclude-promisor-objects, --missing-only, --no-filter and the
rest),
the patch-equivalence options (--cherry-pick, --cherry-mark and
--cherry, which need diffs), reflog walks and the rest. zig-git merge-base answers in all five of git's modes, and zig-git describe
names commits with every option above, --long, --abbrev,
--candidates, --exact-match, --first-parent and --always
included. zig-git log walks as
rev-list does, every option above included (but --count, which git's
log, show and whatchanged take and do nothing with, and
--timestamp, --commit-header and --no-commit-header, rev-list's own,
which all three call unrecognized as git's do), and describes each commit
in any format above, with --oneline, --abbrev-commit (which alone
abbreviates the raw format, not --oneline before it nor
log.abbrevCommit), --date,
--expand-tabs, --use-mailmap, --color, -z (a NUL where a line
feed ends a commit or separates two, and before a merge's combined
diff), the searches, decorations and --source, and
format.pretty, pretty.<name>, log.date, log.abbrevCommit,
log.mailmap, log.decorate, color.ui, color.diff,
color.diff.commit and color.decorate.*; zig-git rev-list takes the same formats, --header and --no-commit-header, in
rev-list's framing. zig-git show -s shows commits, annotated tags, trees
and blobs as git show does, each commit once however often it is given
or tagged and the rest as often as they are given; given a count (-<n>, -n <n>,
--max-count), it walks from the commits it is given, or those they tag,
as log walks, leaving trees and blobs out, as git was seen to (with
--no-walk as well, and with a range, it refuses by name). zig-git check-mailmap maps contacts.
They refuse by name what needs what the library does not have yet:
notes (--notes, %N), signatures
(--show-signature, %G? and the rest), reflog walks and %g*,
--graph, Perl's regular expressions (-P and
grep.patternType=perl), and commits or output in a charset glibc has
and zig-charset does not convert yet, and --end-of-options. Both read through the
commit-graph when git would, say what git says of a corrupt one, and walk
the history replace refs, grafts and a shallow boundary make.
zig-git log -h, zig-git show -h and zig-git whatchanged -h write
the usage git 2.56 writes for all three (one text, naming git log and
git show, which changes as git's options change) to standard output
with status 0, and --help-all the same with --i-still-use-this
listed. As git was seen to, they read the arguments once for -h and
the options that usage lists before anything else: -h before -- or
--end-of-options, after other arguments (even ones git refuses) or
run together with -q (-qh), is the usage, unless -L or
--decorate-refs took it as a value, or an option before it failed as
git fails (--quiet=x, -L or --decorate-refs with no value, with
status 129; --decorate= with no mode, 128). -h or --help-all on
its own is answered outside a repository too, with any other argument
it is git's "not a git repository" there, and whatchanged -h needs no
--i-still-use-this. The configuration is read first, but its values
are checked only as opening any repository checks them (core.abbrev):
git also stops at a bad log.date, diff.renames, color.ui and the
rest of what these commands read before it writes the usage, where
zig-git writes it. -h on its own in a repository whose format version
or extensions git does not read, which git warns of and carries on
without, is refused by name.
The rest of the options that first reading reads are taken out of the
arguments wherever they are, so that one after a path is no option after
a path: -q (--quiet, -qq) acts as -s given before every other
argument, so that a later -p or --stat still asks for its diff,
--no-quiet undoes it, and -qx is read as -x; --no-source undoes
--source; --no-decorate-refs and --no-decorate-refs-exclude each
empty their own list and nothing else; and --i-still-use-this does
nothing in log and show. Outside a repository every argument but a
lone -h or --help-all is answered with git's "not a git repository",
which git looks for first. An argument none of the three knows is
unrecognized in git's words once the rest are read and the revisions they
name found, after a bad format or date, diff formats that exclude each
other, --follow without one path and --children with --parents,
--simplify-merges or --simplify-by-decoration (the last two rewrite
parents as --parents does),
and whatchanged without --i-still-use-this refuses after all of
these, as git does. Before that, the arguments are read in order, as git
reads them: -- is found first (an option before it takes no value
after it, and a name before it that is no revision is a bad revision),
each revision is found and each path checked before an option after it
is read (a revision naming an object the repository lacks, a ref to one
included, is a bad object there, named as given or as --source names
a listed ref, and a range or symmetric difference with such an end is
invalid whole), and an option whose value git refuses (--stat=x, -Ux,
--date=bogus, --pretty=bogus, --find-object naming nothing) is
said only once the revisions before it are found; and once all are
read, a pathspec git cannot read (bad magic, a path outside the
repository) is said first, then --combined-all-paths without a
combined diff, the diff formats that exclude each other and the pickaxes
given together, and then --follow's pathspec. Short diff options run together are read each as
on its own (-ps is -p -s, -pU5 is -p -U5, -pS x takes x),
and what follows the first letter that is no diff option (-q of
-pq, -xy of -pxy) is unrecognized. show refuses by name the options of log's walk
it does not take, and calls the rest unrecognized as git does.
zig-git check-ref-format (--normalize, --allow-onelevel,
--refspec-pattern), zig-git show-ref (--head, --branches,
--tags, -d, -s, --hash[=<n>], --abbrev[=<n>], --verify,
--exists, -q, patterns),
zig-git for-each-ref (patterns, --exclude, --sort=[-]refname,
--count, the reachability filters, and the --format atoms refname with its :short,
:lstrip and :rstrip, objectname and *objectname with their
:short[=<n>], objecttype, symref, *objecttype, HEAD,
subject and contents:subject, and %(if), %(if:equals=...),
%(if:notequals=...), %(then), %(else) and %(end), nested, with
git's complaints about them) and
zig-git symbolic-ref (-q, --short, --no-recurse) read refs as
git's do, warnings about broken refs included, and refuse by name the
atoms and options they do not have. zig-git branch and zig-git tag
list branches (-a, -r, --show-current, a detached HEAD described
from its reflog) and tags, with patterns and the reachability filters;
they create, rename and delete nothing, and refuse by name every option
that would, and verbose, sorted, formatted, columned and colored output.
zig-git ls-files lists the index as git ls-files does — --cached,
--stage, --unmerged, --resolve-undo, -z, -t, -v, -f,
--debug with its stat data and flags, --deduplicate, --sparse,
--full-name, --abbrev[=<n>], and --format with the atoms objectmode,
objecttype, objectname, objectsize, stage and path — from
any directory, with pathspecs, a sparse index expanded with git's hint,
and every message git gives a corrupt index. It refuses by name what
needs the working tree (--others, --modified, --deleted,
--ignored, --killed, the exclude options, --eol), the attr
pathspec magic, --error-unmatch, --with-tree and
--recurse-submodules. Every command stops at a bad core.abbrev or
core.disambiguate as git does.
Every command finds its repository the way git does, takes -C, -c,
--git-dir, --work-tree and --no-replace-objects before its name, and says what git says
when there is none, or one it will not use.
Every command but config, check-ref-format, show-index and the
refused name-rev reads the settings git reads whatever the command
(core.abbrev, core.disambiguate, core.autocrlf, core.safecrlf,
push.default and core.whitespace) before it looks at its arguments,
as git does,
and stops at the first bad one in the order the configuration was read,
even if a later value would override it. A core.whitespace asking for
both tab-in-indent and indent-with-non-tab, its words cut short or
not (in,tab), stops it with git's "cannot enforce both" before it
writes anything, and a tabwidth out of range is warned of once. The
diff commands read these in the same pass as their own settings, so a
bad diff.renameLimit before them stops them first, as it stops git.
ls-files, branch and rev-list take -h on its own before reading
the configuration, as git does; rev-parse reads it before its first
argument other than --local-env-vars, or with no argument, stopping
there without a repository.
verify-pack itself reads only the configuration outside any
repository, and each pack it checks is found bad, after git's message,
when the repository's asks for both indent rules.
The differences are deliberate or not yet matched:
- an object holding fewer bytes than its header says is refused, where git shows whatever its buffer held in their place;
- a REF_DELTA chain that loops is
DeltaChainTooDeep, where git never returns; - git never resolves a REF_DELTA whose base is outside its own pack, and
nor does the library unless asked to (
resolve_external_bases); - what git says on standard error of a corrupt delta, of a corrupt pack
found by
verify-pack, and of a broken pack met on the way to a copy that could be read, is not matched; the answers and exit statuses are; - a
format:string is refused where git would write it differently from strftime: where git's own pass over%s,%zand%Zpairs%signs differently (%E%s,%5%%s),%swith a flag (the C library'smktime),%zand%Zwith a flag informat:(written at UTC's offset), git's own%sand%zwhere they are not the timestamp and the offset strftime writes (a local time from 2100 on, or a recorded zone such as+0099), a local abbreviation longer than six bytes, and a field width past 255; strftime is theClocale's only; - a date whose year does not fit in 32 bits is refused in every mode that shows a calendar date, where git wraps the year;
- a
TZrule naming daylight saving time without its dates while the database has aposixrulesfile to supply them, or with a month of 0 or past 12, is refused rather than guessed at; relativeandhumanare matched for a current time before 2038, the latestGIT_TEST_DATE_NOWcan set;zig-git configexpands%(prefix)/only when given a prefix, since it is not git and has none of its own;- a repository with
extensions.compatObjectFormatis refused, where git reads it (and crashes when it names the object format itself); safe.bareRepositorywith no value is refused as a bad setting, where git crashes;- a
commondirthat begins with blank space names no repository, where git names a path part-way through resolving it; - a bad
core.useReplaceRefsstopszig-gitonly once it opens the repository, where git stops even to answerrev-parse --git-dir; GIT_REPLACE_REF_BASEnot ending in/is refused, where git stops on a bug of its own; a replace ref that is a broken or dangling symbolic ref replaces nothing, where git cannot read the object; a replaced empty tree is read as its replacement, where git'scat-file -preports a hash mismatch; and a commit replaced by an object of another kind is not matched;- the warning for a replace ref's bad name is written when the command
first reads commits or, in
cat-file, an object, which may come after other warnings git writes after it; - grafts or replacements that make a cycle are walked, where git's
--topo-orderlists nothing; zig-git name-rev, anddescribe --contains, which names commits as it does, are refused: no rule tried matched git's choice among the names that reach a commit, which sometimes prefers a name through a merge to a nearer one along first parents;zig-git describerefuses--dirty,--broken,--debugand describing a blob;- ownership and filesystem boundaries are found with
statx, so only on Linux; elsewhere a caller supplies its own answers or discovery says it cannot check; - a reftable stack git cannot read, git treats as empty without a word; the library names what is wrong, and the commands fail;
- a malformed
packed-refsis refused whole, where git's single-ref lookups in a file that says it is sorted may pass over the bad line, andshow-refprints the refs before it; - a malformed reflog line is passed over as git passes it over, but the identity and message are read as the identity line and everything after the tab, where git reads some malformed lines differently;
- an index entry or extension running past the end of the file, or a
path whose length disagrees with its flags, is refused, where git shows
whatever lies past it or crashes; so is an entry with an empty path,
which git shows as
./, and alinkextension of the object ID alone, which crashes git; - a sparse directory whose tree cannot be read is refused, where git crashes, and an fsmonitor bitmap longer than the index is dropped with a warning, where git stops on a bug of its own;
- like git, the index's checksum is not checked unless asked for;
- a revision whose search pattern uses GNU's regular expression
extensions (
\w,\band the rest) is refused, and so is@{upstream}or@{push}in a repository with remotes in the files ofremotes/orbranches/, which git still reads; @{-<n>}reads onlyHEAD'scheckout: moving fromentries, and@{push}takes no account ofremote.<name>.mirror;zig-git cat-filefinds nothing by a range, as git does, rather than refusing it;zig-git rev-parse --disambiguatewith a single digit is refused: git then lists some of the objects the digit begins and not others;- a tag whose tagger's timestamp is negative is refused in an ambiguity hint, where git stops with "Timestamp too large for this system";
zig-git ls-files --debugand-fare refused whencore.fsmonitoris set, since git asks the monitor before it answers them, and long options cannot be abbreviated as git allows;- walking by generation number,
--author-date-orderis refused when a commit is queued before git has read its author date, which git then orders by a rule not matched (about one walk in two thousand); - given a commit-graph whose parent positions are corrupt in a commit
that is only an ancestor of the merge bases, git may find the bases
without reading it, where
zig-git merge-basereads it and stops with git's own complaint; - gitformat-commit-graph(5) gives the second Bloom filter seed as 0x7e646e2; the filters git writes use 0x7e646e2c, and so does the library.
- the
attrpathspec magic is refused, where git reads attributes from the working tree, and so is the internalprefixmagic; --followis refused across a merge the walk lists (or a merge among--boundary's commits), where git looks for the file through the merge's parents by a rule not matched, and with--reverse; since a merge is met only as the walk goes,log --followfirst walks with nothing written, so that the refusal comes before any commit is written, at the cost of walking twice;- a commit whose
encodingheader names a charset glibc 2.44 converts and zig-charset does not yet (Big5-HKSCS, EUC-TW, ISO-2022-JP-2, ISO-2022-JP-3, EUC-JISX0213 and the rest), or UTF-16, UTF-32, UCS-2 or UCS-4, which git reads only as far as the commit's first NUL and was seen to read past the end of, a name asking for//TRANSLITor//IGNORE, or a name that comes down to nothing, such as/, which glibc takes for the locale's charset, is refused wherever the commit's message or identities are shown or searched and need converting, as is an output encoding naming one; UTF-8 past U+10FFFF, in its old five- and six-byte forms, is refused when it would be converted between two names of UTF-8 that git does not take for one another (ISO-10646/UTF8/andUTF-8), where glibc converts what zig-charset cannot; a format of the user's is refused for a commit converted from EBCDIC with no blank line left in it, which git reads past the end of; and a commit holding anything past ASCII is refused where a built-in format or a search would convert it from EUC-CN into GBK or Big5, or from either of those into EUC-CN, which glibc converts by tables of its own rather than through Unicode (Big5's traditional characters for EUC-CN's simplified ones, among other differences); - colors that git turns on only for a terminal (
--color=auto,color.ui=auto) stay off, aszig-gittakes its output never to be one; - a few corners of padding are not matched:
%>>(<n>)taking back spaces written before a%w(...)that changes nothing, padding followed by a color and then%%,%>>(<n>)with the space magic on a placeholder too wide for it, and padding followed by a color and a%w(...); nor is a NUL written before a%w(...)region, which git's wrapping loses; - the display widths
%<(<n>)and%w(...)count are Unicode 17.0.0's, which match git 2.56 at every code point except U+FFFE and U+FFFF (git does not take those for UTF-8 and counts a column a byte), and may differ from a git built with another Unicode version for the characters added or changed since; - a malformed
--grepor--authorpattern is refused in glibc's words, where git names it before refusing an unknown option, and a back reference is refused by name; - git's indent heuristic is matched by a model inferred from git's
choices (
src/diff/indent.zig), not derived from a description of it: its structure was pinned by probes, and its weights are the one set of integers, at the smallest scale that has any, that agrees with every one of 1.2 million generated slides. It agreed with git on all of 200,000 generated comparisons (100,000 code-like and random, 100,000 weighted toward deep nesting, tabs, long runs of blank lines, edits near either end and very long lines) and on 289,000 further slides generated apart from the ones it was found from. Being inferred, it could still place a run differently from git on input unlike any of those, and would then still write a correct patch.--no-indent-heuristicanddiff.indentHeuristic=falseturn it off; - past 256 steps of a search for a middle snake, which only a comparison
of more than 65,532 lines can reach once the common head and tail and
the lines found in one text only are set aside, git splits the
comparison early, and zig-git does as git does: on a step where either
search found a run of at least 21 matching lines, at a run of at least
20 that step found, ending more than twice as many lines from where
that search began, in each text, as the steps taken (the forward
search's furthest out in the nearer text, else the backward search's).
The rule was found by black-box probes of git, condition by condition.
Where it was not seen to hold, or where the order of git's choices is
not known, the line diff is refused (
LineDiff.Error.LongSearchUnsupported): an early split on a step that found two such runs of 21 or more, or two runs to split at as far out as each other, a comparison where both searches found one far enough out in the 16 steps before step 257 (git was seen to split there at a run found before step 257, by a rule not found), an early split on the step where the search gives up, an early split due on a step where the other search then meets it elsewhere, and any search past 256 steps in a range--patienceor--histogramhands back to Myers' algorithm. The refusal applies wherever a command compares lines: the patch,--stat,--numstat,--shortstat,--compact-summary,--dirstat=lines,--check,-G,-B,-W, a merge's combined diff and its counts against the first parent, and--no-index, each withfatal: zig-git <command>: 'a line diff searching past 256 steps' is not supportedand exit status 128, what was written before it left in place. On 618 generated comparisons of 14,000 to 50,000 lines a side, most of them searching past 256 steps, run as 1,854diff --no-indexwith and without the indent heuristic and with-U0, zig-git matched git on 1,423 and refused 431, and differed on none; on 360 more of 5,000 to 100,000 lines with a range of options it refused 21 and differed from git only under--histogram(below). The Ghostty commits updating its vendored simdutf, which split early, match git byte for byte.--minimalnever splits early and is not refused; --histogramis matched by a model inferred from git's choices (src/diff/histogram.zig), whose rules were pinned by probes but which does not explain everything git does. Over 3,200 sampled commits of Ghostty and 400 of zig-git (show, its patch,--statand--numstat) and 600 Ghostty merges (show --cc,-cand--cc --stat) it disagreed with git on two Ghostty commits (a shell-script rewrite and a change to the tmux control parser, each in the patch,--statand--numstat) and on one merge's--cc --stat. On generated texts of a few to a few hundred lines drawn from a handful of distinct ones it disagreed on 946 of 80,000diff --no-indexcomparisons (1.2%), from 0.3% for code-like texts to 2.1% for texts of a few dozen lines drawn from three to a hundred distinct ones, and on 73 of 5,760 commands on generated repositories. Where it differs, git has chosen between runs of matching lines that are equally good by the model's rules (the same count and length) by a rule not found, or has preferred a run the model counts as worse (lower in count when the lines it was extended back over are left out, which holds often but not always), or has compared a range the way the model does only for the range before a run that took another's place at the end of both texts (step 5 of the model), or has left a run of changes where the model's sliding would move it. A wrong answer is still a correct patch, placed differently from git's;- long options cannot be abbreviated in
zig-git diff, as git allows, and short ones cannot be bundled; --find-copies-harderagainst the working tree or the index under-Ris refused;log,showandwhatchangedrefuse--exit-code, under which git was seen to exit with 1 even where it writes no diff, and cannot bundle the diff's short options (-pR), as git's second reading of the arguments does;- the combined patch of a merge of more than 62 parents is refused as
the merge is reached, after what comes before it is written, where git
was seen to mark and leave out lines by a rule not found (from 63
parents under
--cc, and from 64 under-ctoo); the raw format, the names and the counts are written for any number; - a combined diff (
-c,--cc) that would merge more than 2^26 pairs of lines the parents lost at one place (a table of a quarter of a gigabyte, where git was seen to use gigabytes), and so aregit diff-files -pwith unmerged paths (unless-1,-2or-3chooses a stage),--remerge-diffand--diff-merges=remerge; diff-treerefuses a merge's combined diff with--quiet,--exit-codeor--check, where git's answers were not established, as it comes to the merge, or under--stdin(but for--quiet, which writes nothing) before reading any commit, since a merge may come after others have been written;diff-tree,logandshowrefuse a merge's combined diff under-twith-Rwhere each parent's pairs are compared on their own (renames, copies,-B,--diff-filteror the pickaxe), where git pairs a path that is a file on one side and a tree on the other by a rule not found;logrefuses these before anything is written, andshowfor the merges it is given;diff-treerefuses such a combined diff with--stator the other counts where--skip-toor--rotate-tonames a path a later parent's diff lacks, where git stops after writing the counts against the first parent;--line-prefixwith aformat:string, where git puts the prefix before some separators and not others; and the options of git's revision walking it takes without saying what they do there (--notes,--show-signature,--parents,--left-rightand the like), each by name;diff,diff-index,diff-filesanddiff-treereadlog's options as git does: those that change nothing there are taken (--full-diffwithout paths,--first-parent,--reverse,--topo-order,--since,--author,--grep,-nand the like, a value given apart taken with them), a limit on the walk (--max-count,--since) gets git's usage where git writes it (comparing the index or the working tree, and indiff-filesa count above 3), as do listings naming more revisions than--cachedtakes, and git's complaints about a missing value, a word that is neither a revision nor a path, a revision after--and an option after a path are git's; refused by name, once git would have read every argument, are those with an effect not matched (--alland the other listings naming any ref,--not,--bisect,-m,-c,--cc,--default,--full-diffwith paths,--ignore-missing, a count of 0 to 3 indiff-files, which chooses a stage), at once those git stops at in words not matched (a count or date mode it cannot read,--merge,--followwithout exactly one path), and the pairs git refuses together (--graphwith--reverse,-gwith the options shaping its walk);- a function pattern with a back reference, which git takes, is refused,
and so is one whose first group lies inside a repetition that may
iterate more than once, where glibc's choice of iteration was matched
only 98 times in 100 over 3,440 random cases (against none missed in
13,660 with the group anywhere else); so is
-Wtogether with--ignore-blank-linesor-I, whose meeting has not been matched; drivers that run programs (diff.<driver>.command,textconv) anddiff.externalare refused too.--binary, colors, word diffs in a patch (--word-diff,--word-diff-regex,--color-words; a word diff changes nothing else, and is taken there),--stat-graph-widthbelow -1,--submodule=log|diffand--ignore-submodules(other thannone) are refused by name; - a pattern of
-Gor-S --pickaxe-regexusing what the regular expressions here do not support is refused before anything is written; - the pickaxe is refused with
--quiet, which stops at the first difference before the pickaxe has seen the rest; with-iand--find-objecttogether, where git aborts on an internal error; with--find-objectnaming a tree, where git puts trees in the diff as-tdoes, recursing even where it otherwise would not, whichlogandshowcannot; with unmerged paths, where git searches the working tree file of the unmerged entry and lists the pair against stage 2 apart from it.log --find-objectis refused with--follow, under which git was seen to follow renames by another rule, not found; --relativeis refused with paths, which git matches against the shortened paths, with the working tree, and with--summary, whose paths git leaves whole;--line-prefixis refused with-zwhere a diff is written, whose records git prefixes by a rule not matched;- a file in the working tree that a
filterdriver'scleanorprocesscommand would convert is refused, since that means running a program; so is one whoseworking-tree-encodingis a charset glibc converts and zig-charset does not yet (Big5-HKSCS, EUC-TW and the rest), or that is UCS-4 holding a value past U+10FFFF, which glibc converts and zig-charset does not; so are a checked-out submodule'sHEAD,core.fsmonitorand a sparse index; git diffrefreshes the index and writes it when it can;zig-git diffnever writes it, comparing contents where git would refresh, so that the output is the same; the device number in the stat data is not compared, nor nanoseconds, which git was seen not to compare either;zig-git diffoutside a repository without--no-index,--merge-base,A...B, blobs and more than two commits are refused;
The API documentation is generated from the doc comments and published at https://jeff.jcollie.page/zig-git/.
What it is for
grebe, a history browser for git, reads repositories by running
git log and git show. zig-git is being written so that it can stop:
the plan is a library in layers, each depending only on the ones before it.
- Core — the object database (loose objects, packs, the multi-pack
index, alternates), the ref store (loose refs,
packed-refs, reftable, reflogs), configuration with includes, discovering a repository the way git does, and the index file. - Revision — revision arguments in git's own syntax, and walking the history they choose: ranges, path limiting, the three orderings, mailmap, replace refs, grafts.
- Diff — between two texts first, then between trees, the index and the working tree, producing patches byte-identical to git's.
- Write and transport, later: ref transactions, writing objects,
signing, and git's protocol v2 over
file://,ssh://andhttps://.
Three choices run through all of it, and the decision records in
docs/adr/ give the reasons:
- Agreeing with git is the definition of correct. The tests build their
repositories with
gitand compare answers with it, and patches are to match git's byte for byte. - What it does not support, it says so. A revision argument outside the
supported set is an error naming it, and a repository using an extension
it does not implement is refused, so a caller can fall back to
gitrather than receive an answer that is nearly right. - It is written from git's documentation and behavior, never its source, so that it can be MIT licensed.
The words used for the things in a repository — object ID, object format,
object database, ref store, git directory — are defined in
GLOSSARY.md.
Building and testing
Everything is pinned in the Nix flake, Zig and the git the tests compare
against included:
nix develop
zig build test --summary all # every repository test runs with SHA-1 and SHA-256
zig build docs-serve # the API documentation on http://localhost:8000
CONTRIBUTING.md says more.
Where this lives
The canonical repository is on my Forgejo instance, and Tangled carries a mirror of it:
git clone https://git.jcollie.dev/jeff/zig-git.git
- Forgejo: https://git.jcollie.dev/jeff/zig-git
- Tangled: https://tangled.org/jcollie.dev/zig-git
Report issues and send pull requests to the Tangled mirror. CI and the published documentation come from the Forgejo repository.
License
MIT; see LICENSES/MIT.txt. The project follows REUSE.
References cited
- Deutsch, P. and J-L. Gailly. ZLIB Compressed Data Format Specification version 3.3. RFC 1950, 1996. https://www.rfc-editor.org/info/rfc1950 — the container loose objects and pack entries are stored in, and its Adler-32 checksum, computed a block at a time from its definition.
- Deutsch, P. DEFLATE Compressed Data Format Specification version 1.3. RFC 1951, 1996. https://www.rfc-editor.org/info/rfc1951 — the format the DEFLATE decoder for pack entries is written from: block types, the canonical Huffman codes and their construction, the fixed codes, the dynamic codes' code length alphabet, and the length and distance tables; the stored blocks the tests write corrupt loose objects with; and the longest match and shortest codes that bound how far a stream can inflate.
- The Git Project. gitrepository-layout(5): Git Repository Layout.
https://git-scm.com/docs/gitrepository-layout — the objects directory,
objects/info/alternates,.gitfiles,commondir, a worktree'sgitdir, the repository format versions, andinfo/graftsandshallow. - The Git Project. git(1). https://git-scm.com/docs/git —
GIT_ALTERNATE_OBJECT_DIRECTORIESand its quoting,-c, theGIT_CONFIG_*environment variables,-C,--git-dir,--work-tree,GIT_INDEX_FILE,--no-replace-objectsandGIT_NO_REPLACE_OBJECTS, and the variables discovery reads:GIT_DIR,GIT_WORK_TREE,GIT_COMMON_DIR,GIT_OBJECT_DIRECTORY,GIT_CEILING_DIRECTORIESandGIT_DISCOVERY_ACROSS_FILESYSTEM; andGIT_LITERAL_PATHSPECS,GIT_GLOB_PATHSPECS,GIT_NOGLOB_PATHSPECSandGIT_ICASE_PATHSPECS;GIT_ATTR_NOSYSTEM,GIT_ATTR_SOURCEandGIT_EXTERNAL_DIFF. - The Git Project. hash-function-transition: Transitioning Git to SHA-256.
https://git-scm.com/docs/hash-function-transition — SHA-256 object
formats alongside SHA-1, and
extensions.compatObjectFormat. - The Git Project. git-rev-parse(1).
https://git-scm.com/docs/git-rev-parse — what
zig-git rev-parseanswers,--path-format,--verify,--quiet,--short,--disambiguate,--symbolic,--symbolic-full-name,--abbrev-ref,--default,--all,--branches,--tags,--remotes,--globand--exclude. - The Git Project. git-worktree(1). https://git-scm.com/docs/git-worktree
— linked worktrees, their git directories,
extensions.worktreeConfigand thecore.bareandcore.worktreeit moves, and which refs are per-worktree and howmain-worktree/andworktrees/reach them. - The Git Project. gitsubmodules(7).
https://git-scm.com/docs/gitsubmodules — a submodule's
.gitfile and its git directory under the superproject's. - The Git Project. Upcoming breaking changes.
https://git-scm.com/docs/BreakingChanges — why
safe.bareRepositoryexists, and its default to come. - The Linux man-pages project. statx(2). https://man7.org/linux/man-pages/man2/statx.2.html — a file's owner and device, for ownership and filesystem boundaries.
- The util-linux project. unshare(1). https://man7.org/linux/man-pages/man1/unshare.1.html — the user namespace the tests run git as root in, to see a repository someone else owns.
- The Git Project. reftable. https://git-scm.com/docs/reftable — the
reftable format: header, footer, blocks, records, varints, the
tables.liststack and its layout in a repository. - The Git Project. git-check-ref-format(1).
https://git-scm.com/docs/git-check-ref-format — the rules for ref
names, and what
zig-git check-ref-formatanswers. - The Git Project. git-show-ref(1). https://git-scm.com/docs/git-show-ref
— what
zig-git show-refanswers, and its patterns. - The Git Project. git-for-each-ref(1).
https://git-scm.com/docs/git-for-each-ref — what
zig-git for-each-refanswers: patterns, field names,%(refname:short), and--contains,--no-contains,--merged,--no-mergedand--points-at. - The Git Project. git-symbolic-ref(1).
https://git-scm.com/docs/git-symbolic-ref — what
zig-git symbolic-refanswers. - The Git Project. git-pack-refs(1). https://git-scm.com/docs/git-pack-refs
—
packed-refs, and the compaction the tests run. - The Git Project. git-update-ref(1). https://git-scm.com/docs/git-update-ref — the reflog line format.
- The Git Project. git-refs(1). https://git-scm.com/docs/git-refs —
git refs migrate, which the tests convert repositories with. - The Git Project. git-reflog(1). https://git-scm.com/docs/git-reflog — the oracle for reading reflogs.
- The Git Project. gitrevisions(7). https://git-scm.com/docs/gitrevisions
— the rules short ref names are tried by, which shortening reverses;
abbreviated object IDs, and the
^{commit}and^{tree}suffixes that tell an ambiguous one apart; every form of a single revision, the ranges and sets of commits refused for now, andgit describeoutput. - The Git Project. gitcli(7). https://git-scm.com/docs/gitcli — how
git tells a revision from a path, behind
rev-parse's andrev-list's complaints about an argument that is neither, or both, and--. - The Git Project. git-fetch(1). https://git-scm.com/docs/git-fetch — the refspec format, pattern and negative refspecs, and how a remote's fetch refspecs say where its branches are tracked.
- The Git Project. git-push(1). https://git-scm.com/docs/git-push —
push refspecs,
:and deleting with an empty source. - The Git Project. git-fast-import(1). https://git-scm.com/docs/git-fast-import — the stream the tests build long histories with merges and tags from.
- The Git Project. gitdatamodel(7). https://git-scm.com/docs/gitdatamodel
— references, symbolic references and
HEAD. - The Git Project. git-cat-file(1). https://git-scm.com/docs/git-cat-file
— what
zig-git cat-fileanswers. - The Git Project. git-hash-object(1).
https://git-scm.com/docs/git-hash-object — how an object ID is
computed, and
--literally, which the tests make malformed objects with. - The Git Project. gitformat-pack(5): Git Pack Format. https://git-scm.com/docs/gitformat-pack — packs, pack indexes, the delta instruction format and the multi-pack-index.
- The Git Project. gitformat-chunk(5): Chunk-based File Formats. https://git-scm.com/docs/gitformat-chunk — the table of contents the multi-pack-index begins with.
- The Git Project. Multi-Pack-Index (MIDX) Design Notes. https://git-scm.com/docs/multi-pack-index — incremental multi-pack-index chains and their layout.
- The Git Project. git-multi-pack-index(1). https://git-scm.com/docs/git-multi-pack-index — writing one, and the incremental chains the tests make.
- The Git Project. git-show-index(1).
https://git-scm.com/docs/git-show-index — what
zig-git show-indexanswers. - The Git Project. git-verify-pack(1).
https://git-scm.com/docs/git-verify-pack — what
zig-git verify-packanswers. - The Git Project. git-index-pack(1).
https://git-scm.com/docs/git-index-pack — version 1 pack indexes and
completing thin packs with
--fix-thin. - The Git Project. git-pack-objects(1). https://git-scm.com/docs/git-pack-objects — thin packs, and the deepest delta chain git writes.
- The Git Project. git-repack(1). https://git-scm.com/docs/git-repack — the packs the tests make.
- The Git Project. git-clone(1). https://git-scm.com/docs/git-clone —
--shared, which borrows objects through alternates, and--depth,--shallow-sinceand--shallow-exclude, with which the tests make shallow clones. - The Git Project. git-config(1). https://git-scm.com/docs/git-config
— the configuration file syntax, its value types, its sources and
scopes, includes and their conditions, what
zig-git configanswers, protected configuration,core.bare,core.worktree,safe.directory,safe.bareRepository, everyextensions.*git knows, and theindex.*,core.splitIndex,core.sparseCheckout,core.fsmonitorandcore.quotePathsettings the index is read by,core.abbrev,core.warnAmbiguousRefs,advice.objectNameWarning,branch.<name>.remote,.mergeand.pushRemote,format.pretty,pretty.<name>,log.date,log.abbrevCommit,log.mailmap,log.decorate,log.excludeDecoration,log.initialDecorationSet,color.decorate.<slot>,core.useReplaceRefs,color.ui,color.diff,color.diff.commit, the "color" value type,grep.patternType,grep.extendedRegexp,core.commentChar,core.commentString,mailmap.file,mailmap.blobandi18n.logOutputEncoding,diff.algorithm,diff.context,diff.interHunkContext,core.whitespace,diff.orderFile,diff.relative,diff.dirstat,diff.indentHeuristic,diff.noprefix,diff.mnemonicPrefix,diff.suppressBlankEmpty,diff.external,diff.srcPrefix,diff.dstPrefix,diff.statNameWidth,diff.statGraphWidth,diff.renames,diff.renameLimit,diff.<driver>.binary,diff.<driver>.xfuncname,diff.<driver>.funcnameand the driver settings zig-git refuses,core.attributesFile,attr.tree,core.bigFileThreshold,core.fileMode,core.trustctime,core.checkStat,core.symlinks,core.autocrlf,core.eol,core.safecrlf,core.checkRoundtripEncoding(which git was seen to check only when it writes an object),filter.<driver>.clean,.smudge,.processand.required,log.showRoot,remote.pushDefault,remote.<name>.url,.pushurl,.fetchand.push,push.default, andcommitGraph.readChangedPathsandcommitGraph.changedPathsVersion, theadvice.*settings (none of which was seen to silence the byte order mark hint),color.adviceandcolor.advice.hint, anddiff.algorithm: the algorithms' names, and histogram as extending patience "to support low-occurrence common elements". - The Git Project. gitignore(5): Specifies intentionally untracked files
to ignore. https://git-scm.com/docs/gitignore — the glob patterns
wildmatch implements,
**among them. - The Git Project. gitattributes(5): Defining attributes per path.
https://git-scm.com/docs/gitattributes — attribute patterns, through
which
git check-attrwas asked how globs match paths; the files, their precedence, the four states, macros andbinary; thediffattribute, diff drivers anddiff.<driver>.binary; the conversion attributestext,eol,crlf,ident,filterandworking-tree-encoding, the order they are applied in on check-in, and what "auto" means, from which the experiments behindconvertstarted; thewhitespaceandconflict-marker-sizeattributes--checkreads;diff.<driver>.algorithm, and that it applies to patches and--stat; and git's default rule for the function name after@@,diff.<driver>.xfuncnameand the list of built-in drivers. The rest of what git does with a hunk-header pattern (several to a value,!,funcname, the group shown) was found by experiment. - The Git Project. git-check-attr(1).
https://git-scm.com/docs/git-check-attr — the oracle for the
wildmatch tests, and what
zig-git check-attranswers. - The Git Project. git-tag(1). https://git-scm.com/docs/git-tag —
git tag -land--ignore-case, the oracle for patterns matched without the pathname rule, and whatzig-git taglists. - The Open Group. Regular Expressions. The Open Group Base
Specifications Issue 8, chapter 9, 2024.
https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap09.html
— their syntax, basic and extended, bracket expressions and character
classes, for
zig-git config, message searches,--grepand diff drivers' function patterns, and the leftmost-longest rule for where a match lies (from which glibc's groups were seen to depart). - The Open Group. strtol: convert a string to a long integer. The Open Group Base Specifications Issue 8, 2024. https://pubs.opengroup.org/onlinepubs/9799919799/functions/strtol.html — how git reads an integer value, base prefixes and all.
- Cox, Russ. Glob Matching Can Be Simple And Fast Too. 2017.
https://research.swtch.com/glob — matching globs by resuming from the
latest star, which wildmatch extends to
**to keep its work bounded. - Cox, Russ. Regular Expression Matching Can Be Simple And Fast. 2007.
https://swtch.com/~rsc/regexp/regexp1.html — running every state of
an automaton at once, as
zig-git config's regular expressions do. - The Git Project. gitglossary(7): A Git Glossary.
https://git-scm.com/docs/gitglossary — the vocabulary
GLOSSARY.mdfollows, root refs, pseudorefs and per-worktree refs, and pathspecs: their syntax, the long and short magic forms, and thetop,literal,icase,glob,attrandexcludemagic. - The Git Project. git-log(1). https://git-scm.com/docs/git-log —
the
--date=modes,auto:,format:andhuman; its "PRETTY FORMATS": the built-in formats and every placeholder; and whatzig-git loganswers:--pretty,--format,--oneline,--abbrev-commit,--expand-tabs,--use-mailmap,--grep,--author,--committer,--all-match,--invert-grep,-i,-Eand-F; and--decorate,--decorate-refs,--decorate-refs-exclude,--clear-decorations,--source, and the%d,%D,%(decorate),%Sand%(describe)placeholders; its diff options,--full-diffand--first-parent; and its "Diff Formatting" section (https://git-scm.com/docs/git-log#_diff_formatting):-m,-c,--cc,--dd,--no-diff-merges,--diff-mergesand its formats,--follow, andlog.diffMergesandlog.follow. - The Git Project. git-show(1). https://git-scm.com/docs/git-show —
what
zig-git showanswers, and how it shows tags, trees and blobs; its default patch and combined diff for merges. - The Git Project. git-interpret-trailers(1).
https://git-scm.com/docs/git-interpret-trailers — trailer blocks, their
keys, separators, folded values and the share of trailers a block needs,
and
trailer.separatorsandtrailer.<key-alias>.key. - The Git Project. gitmailmap(5). https://git-scm.com/docs/gitmailmap — the mailmap's line forms and matching.
- The Git Project. git-check-mailmap(1).
https://git-scm.com/docs/git-check-mailmap — what
zig-git check-mailmapanswers. - Murai, J., Crispin, M., and van der Poel, E. Japanese Character Encoding for Internet Messages. RFC 1468, 1993. https://www.rfc-editor.org/info/rfc1468 — ISO-2022-JP: its escape sequences, and the return to ASCII at the end of a line.
- Freed, N., and Borenstein, N. Multipurpose Internet Mail Extensions
(MIME) Part One: Format of Internet Message Bodies. RFC 2045, 1996.
https://www.rfc-editor.org/info/rfc2045 — the
MIME-Version,Content-TypeandContent-Transfer-Encodingheaders theemailformat adds. - Moore, K. MIME (Multipurpose Internet Mail Extensions) Part Three:
Message Header Extensions for Non-ASCII Text. RFC 2047, 1996.
https://www.rfc-editor.org/info/rfc2047 — the encoded words the
emailformat writes a header past ASCII in. - Resnick, P., Ed. Internet Message Format. RFC 5322, 2008.
https://www.rfc-editor.org/info/rfc5322 — the specials that make the
emailformat quote a name. - The Unicode Consortium. Unicode Standard Annex #11: East Asian Width. https://www.unicode.org/reports/tr11/ — which characters take two columns when padding and wrapping.
- The Unicode Consortium. Unicode Character Database, version 17.0.0.
https://www.unicode.org/Public/17.0.0/ucd/ —
DerivedEastAsianWidth.txtandDerivedGeneralCategory.txt, from whichtools/gen_width.ziggenerates the tables of characters taking no columns and two. - The Unicode Consortium. Unicode Standard Annex #44: Unicode Character
Database, revision 36 (Unicode 17.0.0).
https://www.unicode.org/reports/tr44/tr44-36.html — the format of the
UCD's data files, and the
@missinglines that give the default East Asian width of unassigned code points. - The Git Project. git-rev-list(1). https://git-scm.com/docs/git-rev-list
—
--sinceand--until, through which the approximate parser was checked; and whatzig-git rev-listanswers: commit limiting, the orderings,--boundary,--ancestry-path,--parents,--children,--left-rightand--count; and its "History Simplification": TREESAME,--simplify-by-decoration, the default mode,--full-historywith and without parent rewriting,--dense,--sparse,--simplify-merges,--show-pullsand--remove-empty, and its two example histories, which the tests build. - The Git Project. git-diff-tree(1). https://git-scm.com/docs/git-diff-tree
—
-rand its raw output, the oracle for comparing trees;-t,--root,-m,--always,--no-commit-id,--stdinwith the lines it reads (two trees, a commit, or a commit and the commits taken as its parents) and the raw output format, whatzig-git diff-treeanswers;--combined-all-paths;--cc, whose description of the uninteresting hunks it leaves out is the rule dense combined diffs were matched from, and the raw format for merges. - The Git Project. git-diff-index(1). https://git-scm.com/docs/git-diff-index
—
--cached,-m, and comparing a tree with the index or the working tree, whatzig-git diff-indexanswers. - The Git Project. git-diff-files(1). https://git-scm.com/docs/git-diff-files
— the stages of unmerged paths,
-q, whatzig-git diff-filesanswers. - The Git Project. git-mktree(1). https://git-scm.com/docs/git-mktree — trees with gitlinks and with a file and a directory of one name, made for the experiments.
- The Git Project. api-trace2: Trace2 API.
https://git-scm.com/docs/api-trace2 —
GIT_TRACE2_PERF, through whosebloomstatistics the tests see when git asks its changed-path filters. - The Git Project. gitformat-commit-graph(5): Git commit-graph format. https://git-scm.com/docs/gitformat-commit-graph — the commit-graph file, its chunks, generation numbers, the changed-path Bloom filters and the base graphs of a chain.
- The Git Project. commit-graph: Git Commit-Graph Design Notes. https://git-scm.com/docs/commit-graph — corrected commit dates and topological levels, split chains and their file layout, mixed generation chains, and chains across alternates.
- The Git Project. git-commit-graph(1).
https://git-scm.com/docs/git-commit-graph — writing commit-graphs and
split chains for the tests, and
commitGraph.generationVersionandcommitGraph.changedPathsVersion. - The Git Project. git-merge-base(1).
https://git-scm.com/docs/git-merge-base — what
zig-git merge-baseanswers: merge bases,--octopus,--independent,--is-ancestorand--fork-point. - The Git Project. git-replace(1). https://git-scm.com/docs/git-replace
— replace refs, what they replace and how they are turned off, and
--graft, with which the tests make them. - The Git Project. git-describe(1).
https://git-scm.com/docs/git-describe — what
zig-git describeanswers, and its "Search Strategy". - The Git Project. git-name-rev(1).
https://git-scm.com/docs/git-name-rev — the naming the experiments
could not match, for which
name-revis refused. - The Git Project. git-branch(1). https://git-scm.com/docs/git-branch
— what
zig-git branchlists,--show-currentand the reachability filters. - The Git Project. git-commit(1). https://git-scm.com/docs/git-commit
— its "Date formats" section, the forms
GIT_COMMITTER_DATEaccepts. - The Git Project. git-var(1). https://git-scm.com/docs/git-var —
GIT_COMMITTER_IDENT, through which the strict parser was checked. - The Open Group. strftime: convert date and time to a string. The Open
Group Base Specifications Issue 8, 2024.
https://pubs.opengroup.org/onlinepubs/9799919799/functions/strftime.html
— the conversions, and the
EandOmodifiers. - The Git Project. gitformat-index(5): Git index format. https://git-scm.com/docs/gitformat-index — the index file: its header, entries, versions, padding, checksum and every extension; the stat data compared with the working tree.
- The Git Project. bitmap-format: GIT bitmap v1 format. https://git-scm.com/docs/bitmap-format — its appendix on the serialization of an EWAH bitmap, as the split index, untracked cache and fsmonitor extensions hold them.
- The Git Project. sparse-index: Git Sparse-Index Design Document.
https://git-scm.com/docs/sparse-index — sparse directories, the
sdirextension, and expanding a sparse index to a full one. - The Git Project. git-ls-files(1). https://git-scm.com/docs/git-ls-files
— what
zig-git ls-filesanswers: its options, tags and field names. - The Git Project. git-update-index(1). https://git-scm.com/docs/git-update-index — index versions, the split index, the untracked cache, skip-worktree, assume-unchanged and the fsmonitor bits, through which the tests make their indexes; "Using index info" and racy git, which the working tree comparison follows.
- The Git Project. git-sparse-checkout(1). https://git-scm.com/docs/git-sparse-checkout — cone mode and the sparse index, and the settings that allow it.
- The Git Project. git-status(1). https://git-scm.com/docs/git-status — the oracle for what the untracked cache holds.
- Cohen, Bram. Patience Diff Advantages. 2010. https://bramcohen.livejournal.com/73318.html — patience diff: match the common head and tail, match the lines unique to both sides along a longest common subsequence, and repeat between the matched lines.
- Aldous, David, and Persi Diaconis. Longest increasing subsequences: from patience sorting to the Baik–Deift–Johansson theorem. Bulletin of the American Mathematical Society 36, 413–432, 1999. https://doi.org/10.1090/S0273-0979-99-00796-X — patience sorting and reading a longest increasing subsequence back from its piles.
- Myers, Eugene W. An O(ND) Difference Algorithm and Its Variations. Algorithmica 1, 251–266, 1986. https://doi.org/10.1007/BF01840446 — the greedy algorithm, the middle snake and the linear-space refinement the line diff follows.
- The Git Project. git-diff(1). https://git-scm.com/docs/git-diff —
--no-index, the patch format, the combined diff format and itsdiff --ccheader, the combined options,--minimal, the whitespace options,--ignore-blank-lines,-I,--inter-hunk-context,-W(--function-context), the prefixes,--outputand the exit status;--patience,--histogram,--anchored=<text>and--diff-algorithm. - The Git Project. diff-options, as included in git-diff(1),
git-diff-files(1), git-diff-index(1) and git-diff-tree(1) —
--indent-heuristic,--diff-algorithm,--full-index,--abbrevand--text; the output formats,--statand its widths,--diff-filter,-R,--exit-code, and the raw output format;-M,-C,--find-copies-harder,-l,--no-renamesand--rename-empty, and the rename and copy lines of the patch and--summary;-S,-G,--find-object,--pickaxe-all,--pickaxe-regex,-O,--skip-to,--rotate-to,--relative,--line-prefix,-D,--checkand--dirstatwith its parameters; and, with the summarygit diff --no-index -hprints, the list of every diff option and its spellings thatrev-listwas tried with. - The Git Project. git-whatchanged(1).
https://git-scm.com/docs/git-whatchanged —
whatchangedaslogwith the raw format and without merges. - The Git Project. gitdiffcore(7): Tweaking diff output.
https://git-scm.com/docs/gitdiffcore — the order of the diffcore
stages, rename and copy detection as "the amount of material kept",
the sources
-Cand--find-copies-harderadd, the preliminary step that pairs files of the same name, and-B's breaking of rewrites and putting them back together; the pickaxe (-S,-G,--pickaxe-all), the orderfile and the rotation, and where each comes in the chain. - The Git Project. Git 2.11 Release Notes.
https://github.com/git/git/blob/master/Documentation/RelNotes/2.11.0.adoc
— the indent heuristic's introduction, as
--indent-heuristicanddiff.indentHeuristic, chosen by the lines before and after a change. - The Open Group. diff: compare two files. The Open Group Base
Specifications Issue 8, 2024.
https://pubs.opengroup.org/onlinepubs/9799919799/utilities/diff.html
— the unified format:
---and+++,@@ranges and the line marks. - Ollie, Jeffrey C. zig-charset: character encodings for Zig. 2026.
https://git.jcollie.dev/jeff/zig-charset — glibc 2.44's charsets and
the names it knows them by, converted byte for byte as its
iconvconverts them. - Ollie, Jeffrey C. zig-datetime: dates, times and time zones for Zig.
2026. https://git.jcollie.dev/jeff/zig-datetime — the calendar, the
time zone database, glibc's lenient reading of
TZ, strftime with format strings read at run time, and git's two date parsers. - Ollie, Jeffrey C. grebe: a history browser for git. 2026. https://git.jcollie.dev/jeff/grebe — the first consumer, and the source of the test fixture helper.