A Practical Git Companion📋

Repository cleanliness is a useful first example because the requested answer is small while the native report can grow with the working tree. The supplied Generated-GitOverview.ps1↗ (ouvre dans une nouvelle fenêtre) computes branch state, changed tracked entries, untracked entries and a cleanliness Boolean. Its maintained source and the runtime live together in the FrenchExDev repository and complete downloadable module.

From an extracted module or source checkout, inspect a repository without modifying it:

$moduleRoot = 'C:/tools/QuietCli'
& (Join-Path $moduleRoot 'examples/Generated-GitOverview.ps1') `
    -Repository 'C:/code/my-project' -MaxOutputBytes 2048

The script imports the adjacent runtime, runs two documented Git commands and returns one QuietCli task envelope. The report from the series runner records fixture observations separately from the illustrative examples in the prose.

Two commands with different jobs📋

The first command is git branch --show-current. Its trimmed output supplies the branch name. An empty name identifies detached state in this companion. The result retains a Detached Boolean so that an empty string is not interpreted as a missing parser value.

The second command is git status --porcelain=v1 -z --untracked-files=normal. The porcelain format is intended for machine consumption. Its NUL termination avoids treating spaces or embedded newlines in paths as record boundaries. Under -z, rename entries include a second path record, which a parser must account for. These format rules come from the official Git status documentation↗ (ouvre dans une nouvelle fenêtre).

The companion only needs entry counts, so it does not build an unlimited list of filenames. For a tracked status entry it increments Changed; for ?? it increments Untracked. It recognizes rename and copy status codes and skips the associated source-path record. Without that state, a rename could be counted twice or its second path mistaken for a status entry.

The runtime supplies records to the callback. The callback supplies Git semantics. QuietCli itself does not know that a two-character status code precedes a path or that some records contain a second path. Those assumptions belong in the companion and its checks.

State the unit explicitly📋

Changed counts changed tracked status entries. It does not count changed lines, individual hunks, or independently sum the staged and unstaged columns. A tracked path with multiple status flags still contributes one entry to this particular answer.

Untracked uses --untracked-files=normal. That option can represent an untracked directory as one entry. The runner creates a directory containing two files and verifies an untracked count of one. Reporting that result as two missing files, or calling it a total untracked file count, would misrepresent the selected command.

The derived property is straightforward:

[pscustomobject]@{
    Clean = ($status.Data.Changed -eq 0 -and
             $status.Data.Untracked -eq 0)
}

It is computed only after the relevant steps succeed. A command failure does not establish that both counts are zero. A parser that returns no data cannot supply an answer merely because the desired final value is a Boolean.

Read the actual result boundary📋

For the modified repository fixture, the useful domain values include these properties. This block illustrates the domain projection, not every execution field:

{
  "Branch": "main",
  "Detached": false,
  "Changed": 1,
  "Untracked": 1,
  "Clean": false,
  "AnswerComplete": true
}

The full execution envelope also tells the reader whether the task succeeded and whether information was omitted. The fixture's committed baseline and subsequent changes are created in a temporary directory. Its results should not be generalized into a description of the user's repository.

Two observations are also not an atomic repository snapshot. Another process can change the branch or working tree between commands. The new composition example states that limitation in its Scope. If the decision requires stronger consistency, the contract and execution strategy need additional work. A useful overview does not by itself authorize or establish readiness for deployment.

Reuse and inspect targeted detail📋

The repository decision example↗ (ouvre dans une nouvelle fenêtre) reuses this companion, consumes its JSON locally, checks its envelope, and combines its properties with a separately obtained commit identifier. That is a second use of the same parsing capability. The model does not need to reinterpret the Git status records in the composition task.

When a subsequent request asks which files changed, this overview should not be stretched beyond its contract. Add a targeted companion or projection that retains the necessary paths, then inspect selected content using documented Git options. Counts remain helpful context, but they cannot replace the evidence needed for a code review.

Checks that protect the meaning📋

The supplied verification runner exercises a clean repository, one changed tracked entry, an untracked directory, a staged rename, and detached HEAD. Those cases check the interpretation rather than merely comparing the shape of two objects. Native failure and truncation are exercised in separate runtime scenarios.

The checks establish the documented behavior for those fixtures and the recorded tool environment. They do not establish that every possible Git status combination has been exhaustively tested. A companion extended to submodules, ignored entries or a different untracked mode should state its new scope and add the corresponding evidence.

Previous: The Result Contract · Series overview · Next: Streaming Long-Running Jobs