The state of an unfinished clone is one versioned record, written before the fetch #188

New Issue

2026-11-11T05:58:40Z

james.maes commented

2026-11-11 05:58:40 +00:00

From the release reviews of 1.1.1 (2026-11-10). Not part of 1.1.1; planned for 1.2.0 unless said otherwise.

Why

Whether a folder's working tree is finished, and which files in it are gclo's, is worked out on every sync from several traces: two configuration keys, the recovery file, whether .git/index exists, the content of files compared against commits. Each fix since 1.0 added one. The rules hold (four reviews of #174 found no way left to replace a user's file), but they are hard to change safely, and none of the traces carries a version.

Known gaps this would close

A process that ends after a clone's fetch has returned and before the folder is marked unfinished (a window of milliseconds) leaves commits and no files; the next sync reports the empty folder as up to date until the origin's next commit. This was so in 1.1.0 as well.
When two gclo processes clone the same folder at the same moment, the cleanup of the one that fails can remove a folder it did not create.
After a checkout that was cut off: a half-written last file can stay when the user ran git in the folder; files of a rewritten history stay untracked.

Direction

One journal file in .git with a schema version, written before the fetch: the phase (fetching, writing a commit, complete, managed by path recovery) and the list of files written. First checkouts made under a staging name that is renamed when complete. "Whose file is this" is then answered by the list. A smaller first step: treat "has commits, has no index, holds nothing but .git" as unfinished.

An ADR for the format belongs to this.

Re-verify against current main before working on it. A fix needs a regression test that fails without it.

From the release reviews of 1.1.1 (2026-11-10). Not part of 1.1.1; planned for 1.2.0 unless said otherwise. ## Why Whether a folder's working tree is finished, and which files in it are gclo's, is worked out on every sync from several traces: two configuration keys, the recovery file, whether `.git/index` exists, the content of files compared against commits. Each fix since 1.0 added one. The rules hold (four reviews of #174 found no way left to replace a user's file), but they are hard to change safely, and none of the traces carries a version. ## Known gaps this would close - A process that ends after a clone's fetch has returned and before the folder is marked unfinished (a window of milliseconds) leaves commits and no files; the next sync reports the empty folder as up to date until the origin's next commit. This was so in 1.1.0 as well. - When two gclo processes clone the same folder at the same moment, the cleanup of the one that fails can remove a folder it did not create. - After a checkout that was cut off: a half-written last file can stay when the user ran git in the folder; files of a rewritten history stay untracked. ## Direction One journal file in `.git` with a schema version, written before the fetch: the phase (fetching, writing a commit, complete, managed by path recovery) and the list of files written. First checkouts made under a staging name that is renamed when complete. "Whose file is this" is then answered by the list. A smaller first step: treat "has commits, has no index, holds nothing but `.git`" as unfinished. An ADR for the format belongs to this. Re-verify against current `main` before working on it. A fix needs a regression test that fails without it.

james.maes added the deferred refactor labels 2026-11-11 05:58:40 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/gclo#188