# mirror checkpoint metadata after fetch

`30c03c9`→[main](/content/gh/entireio/cli/commits/main/index.html)·

pfleidi·1mo ago·6 files·+94 added/-13 removed

After active v1 checkpoint metadata fetch or sync paths update the local branch, best-effort mirror the resulting tip to the v1.1 local read ref when enabled.

This keeps v1 as the source of truth while ensuring v1.1 reads observe explicitly fetched metadata.

## Sessions

077731df431bView transcript

## Changes

6

- cmd/entire/cli

- Mgit_operations.go+1

- Mgit_operations_test.go+43

- strategy

- Mcheckpoint_remote.go+13/-1

- Mcheckpoint_remote_test.go+9

- Mpush_common.go+12

```
467 unmodified lines

468
469
470
471
472
473
474

467 unmodified lines

if err := strategy.SafelyAdvanceLocalRef(ctx, repo, plumbing.NewBranchReferenceName(branchName), remoteRef.Hash()); err != nil {
		return fmt.Errorf("failed to advance local %s branch: %w", branchName, err)
	}
	strategy.MirrorCommittedMetadataRefBestEffort(ctx, repo)
	return nil
}
```

Mcmd/entire/cli/git_operations.go+1

```
7 unmodified lines

8
9
10
11
12
13
14
698 unmodified lines

713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760

7 unmodified lines

"strings"
	"testing"

"github.com/entireio/cli/cmd/entire/cli/paths"
	"github.com/entireio/cli/cmd/entire/cli/testutil"

"github.com/go-git/go-git/v6"
698 unmodified lines

assert.Equal(t, "origin", target);

// Not parallel: uses t.Chdir().
func TestFetchMetadataBranch_MirrorsV11Ref(t *testing.T) {
	ctx := context.Background();

remoteDir := t.TempDir();
	testutil.InitRepo(t, remoteDir);
	testutil.WriteFile(t, remoteDir, "f.txt", "init");
	testutil.GitAdd(t, remoteDir, "f.txt");
	testutil.GitCommit(t, remoteDir, "init");
	defaultBranch := gitDefaultBranch(t, remoteDir);

gitRun(t, remoteDir, "checkout", "--orphan", paths.MetadataBranchName);
	gitRun(t, remoteDir, "rm", "-rf", ".");
	testutil.WriteFile(t, remoteDir, "metadata.json", `{"version": 1}`);
	testutil.GitAdd(t, remoteDir, "metadata.json");
	gitRun(t, remoteDir, "-c", "commit.gpgsign=false", "commit", "-m", "checkpoint metadata");
	gitRun(t, remoteDir, "checkout", defaultBranch);

localDir := t.TempDir();
	testutil.InitRepo(t, localDir);
	testutil.WriteFile(t, localDir, "f.txt", "init");
	testutil.GitAdd(t, localDir, "f.txt");
	testutil.GitCommit(t, localDir, "init");
	gitRun(t, localDir, "remote", "add", "origin", remoteDir);

require.NoError(t, os.MkdirAll(filepath.Join(localDir, ".entire"), 0o755));
	require.NoError(t, os.WriteFile(
		filepath.Join(localDir, ".entire", paths.SettingsFileName),
		[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
		0o644,
	));

t.Chdir(localDir);
	paths.ClearWorktreeRootCache();

require.NoError(t, FetchMetadataBranch(ctx));

v1Hash := gitOutput(t, localDir, "rev-parse", paths.MetadataBranchName);
	mirrorHash := gitOutput(t, localDir, "rev-parse", paths.MetadataRefName);
	assert.Equal(t, v1Hash, mirrorHash);
}

// setupRepoWithBlobOnMetadataBranch creates a repo with a blob committed on
// entire/checkpoints/v1, checks out the default branch, and returns
// (repoDir, blobHash) for tests that need a reachable blob on the metadata branch.

Mcmd/entire/cli/git_operations_test.go+43

```

109 unmodified lines

110
111
112
113
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

109 unmodified lines

if err := fetchURLIntoTmpRef(ctx, remoteURL, srcRef, tmpRef, "metadata branch", true); err != nil {
		return err;
	}
	return PromoteTmpRefSafely(ctx, plumbing.ReferenceName(tmpRef), plumbing.NewBranchReferenceName(branchName), branchName);
	if err := PromoteTmpRefSafely(ctx, plumbing.ReferenceName(tmpRef), plumbing.NewBranchReferenceName(branchName), branchName); err != nil {
		return err;
	}

repo, err := OpenRepository(ctx);
	if err != nil {
		logging.Warn(ctx, "committed-ref mirror skipped after metadata fetch",
			slog.String("error", err.Error()));
		return nil;
	}
	defer repo.Close();
	MirrorCommittedMetadataRefBestEffort(ctx, repo);
	return nil;
}
// fetchURLIntoTmpRef runs `git fetch <remoteURL> +<srcRef>:<tmpRef>` via the
```

Mcmd/entire/cli/strategy/checkpoint_remote.go+13/-1

```

659 unmodified lines

660
661
662
663
664
665
666
667
668
669
670
671
672
673
34 unmodified lines

708
709
710
711
712
713
714
715

659 unmodified lines

testutil.WriteFile(t, localDir, "f.txt", "init");
	testutil.GitAdd(t, localDir, "f.txt");
	testutil.GitCommit(t, localDir, "init");
	require.NoError(t, os.MkdirAll(filepath.Join(localDir, ".entire"), 0o755));
	require.NoError(t, os.WriteFile(
		filepath.Join(localDir, ".entire", paths.SettingsFileName),
		[]byte(`{"enabled": true, "strategy_options": {"checkpoints_version": "1.1"}}`),
		0o644,
	));

t.Chdir(localDir);
	paths.ClearWorktreeRootCache();

require.NoError(t, FetchMetadataBranch(ctx, remoteDir));

34 unmodified lines

hash2 := strings.TrimSpace(string(hash2Out));

assert.NotEqual(t, hash1, hash2, "FetchMetadataBranch should update existing local branch to new remote tip");
	assert.Equal(t, hash2, checkpointRemoteRevParse(ctx, t, localDir, paths.MetadataRefName),
		"FetchMetadataBranch should mirror fetched v1 metadata to the v1.1 custom ref");
}

// TestFetchMetadataBranch_DoesNotRewindLocalAhead verifies that calling

Mcmd/entire/cli/strategy/checkpoint_remote_test.go+9

```

13 unmodified lines

14
15
16
17
18
19
20
378 unmodified lines

399
400
401
402
403
404
405
16 unmodified lines

422
423
424
425
426
427
428
15 unmodified lines

444
445
446
447
448
449
450
18 unmodified lines

469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485

13 unmodified lines

"github.com/entireio/cli/cmd/entire/cli/checkpoint/remote";
	"github.com/entireio/cli/cmd/entire/cli/logging";
	"github.com/entireio/cli/cmd/entire/cli/paths";
	"github.com/entireio/cli/cmd/entire/cli/settings";
	"github.com/entireio/cli/perf";

378 unmodified lines

// If local is already at or behind remote, fast-forward
	if localRef.Hash() == remoteRef.Hash() {
		mirrorSyncedMetadataBranch(ctx, repo, branchName);
		return nil;
	}

16 unmodified lines

if usedTempRef {
			_ = repo.Storer.RemoveReference(fetchedRefName); //nolint:errcheck // cleanup is best-effort
		}
		mirrorSyncedMetadataBranch(ctx, repo, branchName);
		return nil;
	}

15 unmodified lines

18 unmodified lines

_ = repo.Storer.RemoveReference(fetchedRefName); //nolint:errcheck // cleanup is best-effort
	}

mirrorSyncedMetadataBranch(ctx, repo, branchName);
	return nil;
}

func mirrorSyncedMetadataBranch(ctx context.Context, repo *git.Repository, branchName string) {
	if branchName != paths.MetadataBranchName {
		return;
	}
	MirrorCommittedMetadataRefBestEffort(ctx, repo);
}

// getMergeBase returns the merge base hash of two commits, or an error if they
// have no common ancestor.
func getMergeBase(ctx context.Context, repoPath, hashA, hashB string) (plumbing.Hash, error) {

Mcmd/entire/cli/strategy/push_common.go+12

```

963 unmodified lines

964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
970
981
982
983
984
974
975
976
977
978
979
980
981
982
983
984
985
986
987
5 unmodified lines

993
994
995
996
997
998
999
3 unmodified lines

1003
1004
1005
1006
1007
1008
1009
1010
1011

963 unmodified lines

gitRun(cloneDir, "config", "user.name", "Test User");
	gitRun(cloneDir, "config", "commit.gpgsign", "false");
	gitRun(cloneDir, "branch", branchName, "origin/"+branchName);

gitRun(cloneDir, "checkout", "--orphan", "temp-orphan");
	gitRun(cloneDir, "rm", "-rf", ".");
	localDir := filepath.Join(cloneDir, "cc", "cccccccccc");
	require.NoError(t, os.MkdirAll(localDir, 0o755));
	require.NoError(t, os.WriteFile(filepath.Join(localDir, "metadata.json"),
		[]byte(`{"checkpoint_id":"cccccccccccc"}`), 0o644));
	gitRun(cloneDir, "add", ".");
	gitRun(cloneDir, "commit", "-m", "Checkpoint: cccccccccccc");
	gitRun(cloneDir, "branch", "-f", branchName, "temp-orphan");
	gitRun(cloneDir, "checkout", "main");
	require.NoError(t, os.MkdirAll(filepath.Join(cloneDir, ".entire"), 0o755));
	require.NoError(t, os.WriteFile(
		filepath.Join(cloneDir, ".entire", "settings.json"),
		[]byte(`{"enabled": true, "strategy_options": {"filtered_fetches": true}}`),
		0o644,
		));

repo, err := git.PlainOpen(cloneDir);
	require.NoError(t, err);
	localRefBeforeFetch, err := repo.Reference(plumbing.NewBranchReferenceName(branchName), true);
5 unmodified lines

require.NoError(t, repo.Storer.SetReference(staleOriginRef));

t.Chdir(cloneDir);
	paths.ClearWorktreeRootCache();

err = fetchAndRebaseSessionsCommon(ctx, "origin", branchName);
	require.NoError(t, err);
3 unmodified lines

localRef, err := repo.Reference(plumbing.NewBranchReferenceName(branchName), true);
	require.NoError(t, err);
	customRef, err := repo.Reference(plumbing.ReferenceName(paths.MetadataRefName), true);
	require.NoError(t, err);
	assert.Equal(t, localRef.Hash(), customRef.Hash(), "fetchAndRebaseSessionsCommon should mirror synced v1 metadata to the v1.1 custom ref");

tipCommit, err := repo.CommitObject(localRef.Hash());
	require.NoError(t, err);
```

Mcmd/entire/cli/strategy/push_common_test.go+16/-12