# Read-support refs-v1; explain fetches a git-refs checkpoint on clone

`b37743e`→[main](/content/gh/entireio/cli/commits/main/index.html)·Soph·2w ago·14 files·+59 added/-31 removed

- checkpointpolicy: refs-v1 is now read- AND write-supported (refsV1Format added to both readFormats and writeFormats) so explain/resume/attach accept git-refs checkpoints and the git-refs store may write them. Tests that used "refs-v1" as a stand-in *unsupported* version now use "refs-v2" (the next, genuinely unsupported refs major); format_test asserts refs-v1 is supported.
- explain: on a fresh clone the prefix→ID remote fallback only fetched the v1 metadata branch (empty under git-refs). When the primary is git-refs and the prefix is a full checkpoint ID (the Entire-Checkpoint trailer always is), fetch that one ref via FetchCheckpointRef and re-list.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## Sessions

291fe479c0a8View transcript

## Changes

14

- cmd/entire/cli

- Mcheckpoint_policy_read_test.go+2/-2
  - Mcheckpoint_policy_test.go+3/-3
  - Mcheckpoint_policy_test_helpers_test.go+1/-1
  - Mcheckpoint_policy_warning_test.go+2/-2
  - checkpointpolicy
    - Mformat.go+6/-1
    - Mformat_test.go+3/-2
    - Mpolicy_test.go+1/-1
    - Mremote_test.go+4/-4
    - Mstore_test.go+2/-2
    - Mupdate_test.go+6/-6
    - Mwarning_test.go+2/-2
  - Mexplain_export.go+22
  - Mexplain_export_test.go+3/-3
  - Mresume_test.go+2/-2

```go
_, err := readCheckpointInfoFromStore(context.Background(), checkpointInfoPolicyStub{
	summary: &checkpoint.CheckpointSummary{
		CheckpointID:      cpID,
		CheckpointVersion: "refs-v1",
		CheckpointVersion: "refs-v2",
	},
}, cpID)

require.EqualError(t, err, `checkpoint 111111111111 uses unsupported checkpoint_version "refs-v1": not read-supported by this Entire CLI`)
require.EqualError(t, err, `checkpoint 111111111111 uses unsupported checkpoint_version "refs-v2": not read-supported by this Entire CLI`)
}

```

func TestCheckpointPolicyCmd_RejectsDowngradeWithoutForce(t *testing.T) {
	dir, bareDir := setupCheckpointPolicyRepo(t)
	seedCheckpointPolicyForCommand(t, dir, checkpointpolicy.Policy{
		CheckpointVersion:    "refs-v1",
		CheckpointMinVersion: "refs-v1",
		CheckpointVersion:    "refs-v2",
		CheckpointMinVersion: "refs-v2",
	})
	pushCheckpointPolicyRefForCommandTest(t, dir, bareDir)
}

Mcmd/entire/cli/checkpoint_policy_read_test.go+2/-2

```

func writeUnsupportedCheckpointPolicyForCLITest(t *testing.T, repo *git.Repository) {
	t.Helper()
	_, err := checkpointpolicy.WriteLocal(t.Context(), repo, plumbing.ZeroHash, checkpointpolicy.Policy{
		CheckpointVersion:    "refs-v1",
		CheckpointVersion:    "refs-v2",
		CheckpointMinVersion: "branch-v1",
	})
	require.NoError(t, err)
}

Mcmd/entire/cli/checkpoint_policy_warning_test.go+2/-2

```

var branchV1Format = CheckpointFormat{Family: CheckpointFamilyBranch, Major: 1}
var (
	branchV1Format = CheckpointFormat{Family: CheckpointFamilyBranch, Major: 1}
	refsV1Format   = CheckpointFormat{Family: CheckpointFamilyRefs, Major: 1}
)
var (
	readFormats = map[CheckpointFormat]bool{
		branchV1Format: true,
		refsV1Format:   true,
	}

writeFormats = map[CheckpointFormat]bool{
		branchV1Format: true,
		refsV1Format:   true,
	}
)
```

```go
require.True(t, checkpointpolicy.CanWrite(branchV1))
require.Equal(t, checkpoint.CheckpointVersionBranchV1, branchV1.String())

require.False(t, checkpointpolicy.CanRead(refsV1))
require.False(t, checkpointpolicy.CanWrite(refsV1))
// refs-v1 is the git-refs store format: read- and write-supported.
require.True(t, checkpointpolicy.CanRead(refsV1))
require.True(t, checkpointpolicy.CanWrite(refsV1))
require.Negative(t, checkpointpolicy.Compare(branchV1, refsV1))

require.False(t, checkpointpolicy.CanRead(unknownV1))
```

func TestUpdateRejectsDowngradeFromRemoteWithoutForce(t *testing.T) {
	remoteDir, remoteRepo, bareDir := initPolicyRemoteFixture(t)
	_, err := checkpointpolicy.WriteLocal(t.Context(), remoteRepo, plumbing.ZeroHash, checkpointpolicy.Policy{
		CheckpointVersion:    "refs-v1",
		CheckpointMinVersion: "refs-v1",
		CheckpointVersion:    "refs-v2",
		CheckpointMinVersion: "refs-v2",
	})
	require.NoError(t, err)
	pushPolicyRefWithGit(t, remoteDir, bareDir)
}

```

```go
package checkpointpolicy

import "github.com/entireio/cli/cmd/entire/cli/checkpoint"
import "github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
import "github.com/entireio/cli/cmd/entire/cli/checkpointpolicy"
import "github.com/entireio/cli/cmd/entire/cli/settings"
import "github.com/entireio/cli/cmd/entire/cli/strategy"
import "github.com/entireio/cli/cmd/entire/cli/trailers"
```

```go
require.NoError(t, err)
var summary checkpoint.CheckpointSummary
require.NoError(t, json.Unmarshal([]byte(content), &summary))
summary.CheckpointVersion = "refs-v1"
summary.CheckpointVersion = "refs-v2"
metadataJSON, err := json.Marshal(summary)
require.NoError(t, err)
metadataHash, err := checkpoint.CreateBlobFromContent(repo, metadataJSON)
```

```go
_ = fresh.Close()
if cpCfg, _ := settings.LoadCheckpointsConfig(ctx); checkpoint.PrimaryIsRefs(cpCfg) {
	if cid, err := id.NewCheckpointID(prefix); err == nil {
		stop := startSpinner(errW, "Fetching checkpoint from remote")
		fetchErr := FetchCheckpointRef(ctx, checkpoint.RefName(cid))
		stop(false)
		if fetchErr == nil {
			if fresh, freshErr := newExplainCheckpointLookup(ctx); freshErr == nil {
				if m := matchCheckpointPrefix(fresh, prefix); len(m) > 0 {
					return m, fresh
				}
			}
		}
	}
}
return nil, lookup
```