# `MutagenEx.GitDiff`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/git_diff.ex#L1)

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.

# `change_set`

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

# `error`

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

# `line_range`

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

# `sha`

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

# `base_file`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
