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
@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] }
@type error() :: {:error, :invalid_since_ref | :diff_unavailable, map()}
@type line_range() :: {pos_integer(), pos_integer()}
@type sha() :: String.t()
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.
@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.