MutagenEx.GitDiff (mutagen_ex v0.2.0)

Copy Markdown View Source

Reads changed source lines against a Git merge-base and reads blobs from it.

Diff roots must be real directories within the resolved project directory. Scope compares normalized root spellings and folds case when Git config or the disk indicates case-insensitivity. Results keep Git's path spelling, including case and normalization. The caller should use those keys directly and name the reason and path for each skipped entry when marking a read incomplete.

Symlinks and gitlinks in the index at or below a root count as skipped even when unchanged. A changed entry can also carry its diff reason.

Git runs without a shell or pager. The environment drops inherited GIT_* variables, including GIT_EXTERNAL_DIFF, GIT_DIFF_OPTS, GIT_PAGER, GIT_TRACE*, GIT_CONFIG*, GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE, GIT_ATTR_SOURCE, and GIT_*_PATHSPECS. GIT_CONFIG_NOSYSTEM and GIT_ATTR_NOSYSTEM suppress system configuration and attributes. GIT_OPTIONAL_LOCKS, GIT_NO_REPLACE_OBJECTS, GIT_NO_LAZY_FETCH, and GIT_ALLOW_PROTOCOL disable optional writes, replacement objects, lazy fetches, and transports. LC_ALL is set to C.

Command-line config pins core.quotepath, core.attributesFile, core.bigFileThreshold, core.fsmonitor, core.hooksPath, core.pager, pager.diff, pager.show, color.ui, color.diff, log.showSignature, and protocol.allow. It pins diff.external, diff.noPrefix, diff.mnemonicPrefix, diff.srcPrefix, diff.dstPrefix, diff.relative, diff.context, diff.interHunkContext, diff.algorithm, diff.indentHeuristic, diff.suppressBlankEmpty, diff.suppress-blank-empty, diff.orderFile, diff.renames, diff.renameLimit, diff.ignoreSubmodules, diff.submodule, submodule.recurse, and diff.autoRefreshIndex. Explicit flags disable external diff, textconv, color, notes, signatures, and decorations. The reader keeps standard global configuration so Git can enforce ownership with the runner's safe.directory entries. It never adds an ownership exception.

Local driver names are open-ended. A bounded config read finds filter.<driver>.{clean,smudge,process,required} and diff.<driver>.{algorithm,binary,command,textconv,cacheTextconv}. GIT_CONFIG_PARAMETERS carries Git's command-line config encoding for these keys. It disables the configured programs and pins the binary and algorithm settings without putting variable flags in argv. Git 2.41 or newer is required. GIT_ATTR_SOURCE selects the empty tree and core.autocrlf, core.eol, and core.safecrlf are pinned for raw working bytes. Git's repository info/attributes must be empty. GIT_WORK_TREE is pinned to the discovered checkout and GIT_GRAFT_FILE disables grafts. core.precomposeUnicode is disabled to pass literal pathspec bytes to Git. advice.graftFileDeprecated suppresses the diagnostic for the empty graft file. Promisor repositories fail closed before a command can fetch. As with the index and worktree, keep the local config stable during the read.

Summary

Functions

Reads the raw blob at base_sha and relative_path, using the same options as changed_lines/2. Use the old path for a rename. Returns :absent when the commit exists and the path has no tree entry.

Returns the new-side line ranges under :roots (default ["lib"]).

Types

change_set()

@type change_set() :: %{
  optional(:deletion_anchors) => %{optional(binary()) => [non_neg_integer()]},
  base: sha(),
  head: sha() | nil,
  files: %{optional(binary()) => [line_range()]},
  renames: %{optional(binary()) => binary()},
  skipped: [%{path: binary(), reason: atom()}],
  warnings: [:empty_diff]
}

error()

@type error() :: {:error, :invalid_since_ref | :diff_unavailable, map()}

line_range()

@type line_range() :: {pos_integer(), pos_integer()}

sha()

@type sha() :: String.t()

Functions

base_file(base_sha, relative_path, opts)

@spec base_file(sha(), binary(), keyword()) :: {:ok, binary()} | :absent | error()

Reads the raw blob at base_sha and relative_path, using the same options as changed_lines/2. Use the old path for a rename. Returns :absent when the commit exists and the path has no tree entry.

changed_lines(ref, opts)

@spec changed_lines(
  binary(),
  keyword()
) :: {:ok, change_set()} | error()

Returns the new-side line ranges under :roots (default ["lib"]).

:cd selects the project directory. :timeout is the deadline in milliseconds for each Git command and defaults to 30 seconds. :cmd accepts a three-argument function with the same arguments and binary result as System.cmd/3. :kill_cmd can inject that same interface for timeout cleanup. :renames maps each selected destination to its old path, including pure renames. Git detects renames within the selected roots. Set :deletion_anchors to return a separate map of new-side line numbers from zero-line hunks. An anchor of 0 is before the first line. Set file_kind: :test to select changed *_test.exs files, including pure renames. The default kind is :source (.ex). With :allow_missing_roots, a missing root is part of the working-tree snapshot and an empty roots list selects no paths. Set :untracked to include unignored working files without requiring intent-to-add.