Module push_failure_notice 

The record of a failed backup push and the rule for when a wrapper command shows it. What: The record of a backup push that failed after its commit was saved, and the rule for when the wrapper shows it: the resident service writes one record per failed push under the Git directory of the worktree whose commit it was, a later wrapper command in that worktree shows each record once on standard error, and a later push of the same branch that succeeds removes the records of that branch. Why: The push runs in the service after the commit command returned, so nothing is attached to the command that could print its failure; without a record the person would never learn that their backup push was refused (doc/planning/cli-git-resident-service.md, “After-commit work”). Records are plain files in the worktree’s own Git directory so the check on every command is one directory read that finds nothing when nothing failed. A record holds the branch, the whole commit name and Git’s words with credentials already masked; the wrapper words the notice when it shows it, so the commit name is abbreviated the way Git abbreviates it in the repository as it is then. Records are shown on standard error only, and not at all to a command whose output a program reads (--porcelain, -z, plumbing), so that program neither sees the text in its output nor consumes the record before a person can read it.

In TS you’d write (pseudocode):

await recordPushFailure(gitDir, { branchRef, oid, reason }); stderr.write(await takePushFailures(gitDir));

Structs

Worktrees

Where the worktrees of a repository stand: the branch the asking worktree has checked out and every branch any worktree has checked out.

Constants

NOTICE_DIRECTORY

Directory under the worktree’s own Git directory that holds the records for the person.

ORPHAN_NOTICE_DIRECTORY

Directory under the repository’s common Git directory that holds the records of removed worktrees, which any worktree’s command shows because the worktree they were made for is gone.

Functions

branch_of_head

What: The branch reference a HEAD file names, or nothing for a detached head or an unreadable file. Why: Only the plain ref: refs/heads/<name> form names a branch.

checked_out_branches

What: The branches checked out in the repository’s worktrees: the main one and each linked one. Why: A linked worktree keeps its own HEAD under worktrees/<name>; the main worktree’s is the common directory’s.

clean_reason

What: Git’s words for the person: the user name and password of every URL masked, control characters dropped, and the length bounded. Why: The text came from a remote and from Git, and is printed on a terminal; a URL with a user name and password, or an escape sequence, must not reach the screen or a log of it. Only the credentials are masked, never the line around them, because the line often says why the push failed (the wrapper’s own Git LFS failure line names the endpoint setting and carries the exit status).

clear_push_failures

What: Removes the records of one branch, after a push of that branch succeeded. Why: A successful push of the branch carries every earlier commit of it, so an earlier failure is no longer true.

clear_push_failures_before

What: Removes the records of one branch that were written no later than cutoff, after a push of that branch succeeded. Why: A push carries the commits that existed when it began. A record written after that moment is about a newer commit, which another instance of the service may have pushed and failed to push while this push’s result was still being handled; the older push says nothing about it, so it stays.

fnv_hex

A 64-bit FNV-1a hash of the text, in hexadecimal.

is_machine_read

What: Whether a command’s output is read by a program, so that no record may be shown to it or taken from it. Why: A prompt, an editor or a script runs git status --porcelain or git rev-parse often and reads every byte; the record is meant for the person, and the first such call would otherwise take it.

notice_directory

The directory that holds the records of a repository.

push_failure_text

What: The text shown for a failed backup push, from Git’s raw words. Why: The commit is named as the caller gives it, so a caller that has the repository passes Git’s own abbreviation.

record_lost_push

What: Leaves the record of a push that was lost with its worktree, unless a record of that commit on that branch is already there. Why: An existing record holds Git’s own words about a failed push, which say more than this one does.

record_name

The file name of the record of one failed push.

record_push_failure

What: Leaves the record of one failed push, replacing an earlier record of the same commit on the same branch. Why: The name is derived from the branch and the commit, so a push that is tried again and fails again leaves one record. The reason is cleaned before it is written, so no credential reaches the disk.

record_push_skip

What: Leaves the record of one push the service did not make, replacing an earlier record of the same commit on the same branch. Why: The service settles such a push as done because nothing is left for it to retry, and the person would otherwise never learn that the backup does not exist. The name is the failure record’s, so a later successful push of the branch removes it with the failures.

take_orphaned_failures

What: Reads and removes the records of removed worktrees, which belong to no worktree and so are shown to the first command that asks. Why: The worktree a record was made for is gone, so nobody else could ever be shown it; one directory read when none exist.

take_push_failures

What: Reads and removes every record, with each commit named in full. Why: The service’s own controls and a repository with no worktree to ask need all of them.

take_push_failures_for

What: Reads and removes the records that are for the asking worktree (all of them when no worktree is given), oldest name first, worded with the commit named by abbreviate. Why: A record is shown once, to the worktree whose commit it is about; another worktree’s command leaves it where it is. When nothing failed the notice directory does not exist, and this is one directory read.