Module worktree_convert_journal 

The journal of a conversion and the retirement of the kernel lock file older releases left. What: The journal of one conversion of a worktree into a subvolume. Why: The journal is the only proof that the converting subvolume and the index lock are this command’s, and it names the identity of the old root and of the subvolume it created, which is what every later phase checks before it reuses, exchanges, destroys or deletes anything. The journal is written through exclusively created files and never replaces a file it did not make. One command at a time owns a conversion through a numbered claim file (single_owner_claim.rs) taken before the journal is read, so no kernel lock is held.

In TS you’d write (pseudocode):

const claim = await takeClaim({ directory: admin, prefix: CLAIM_PREFIX }); // busy when another command owns it
const journal = await Journal.load(admin);
await journal.save(admin); // exclusive temporary, then rename

Structs

Journal

What: The journal of one conversion, kept in the worktree’s administrative directory. Why: See the module description.

Enums

Phase

What: The phase a conversion has reached, in order. Why: A rerun reads it to skip the finished phases and to decide whether an abandon is still possible.

Constants

CLAIM_PREFIX

The prefix of the numbered claim files that give one command at a time the conversion of a worktree.

JOURNAL_NAME

The name of the journal inside the worktree’s administrative directory.

LOCK_NAME

The name of the kernel lock file that releases up to 0.5.20 left in the administrative directory; this release only probes for it and removes it when nothing holds it.

Functions

is_recorded_object

Whether found is the object the journal recorded as recorded: the same device and inode and, when a birth time was recorded, the same birth time.

legacy_lock_is_held

What: Whether a command of an older release still holds the conversion’s kernel lock on admin, retiring the lock file when none does. Why: Releases up to 0.5.20 serialized conversions with an advisory kernel lock on cli-git-convert.lock and left the file in place. This release serializes with a claim file instead and takes no kernel lock, but an older command may still be converting the worktree, and two commands must never convert one worktree at once. The probe asks without waiting and gives the lock straight back; a file nobody holds is removed, so the leftover disappears after the upgrade. A file that is absent costs nothing, and a file that is not a plain file is left where it is.

read_plain_file

What: The bytes of the plain file at path, opened without blocking and without following a link, refused when it is anything else or larger than limit. Why: Opening a named pipe for reading waits for a writer, and a command that waits while it owns the conversion blocks every other command that wants it; the type is read from the open handle, and the read is bounded.

read_plain_text

The text of the plain file at path, read like read_plain_file.