docs: document the --init flag and first-use destination bootstrap#130
Merged
Conversation
The README said a kopia repo is created "on first use", which contradicts the shipped behaviour: first-use creation is gated behind `--init` (and the agent/scheduler never passes it). `--init` was documented only in the flag help, not the README. - Correct the kopia section: the repository is not auto-created; first sync needs `--init`. - Add a "First use and the .squirrel-volume marker" section explaining what `--init` bootstraps per destination type (local marker, kopia repo; remote rclone markers are a tracked follow-up) and why first-use creation is a deliberate human-driven step rather than automatic. - List `--init` in the CLI reference (sync usage + flag table). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KE9A1VTdw7k1GQq87fQyfx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Targets
main.The
--initflag was documented only in the CLI flag help, and the README's kopia section actively contradicted the shipped behaviour — it said the repository is created "on first use", when first-use creation is in fact gated behind--init(and the agent/scheduler never passes it). This fixes the docs.Changes (README only)
--init..squirrel-volumemarker" section — what--initbootstraps per destination type, kept accurate to the code:local— writes the.squirrel-volumemarker; later syncs require it (sync/sync.goensureDestinationMarker, gated ondest.Type == "local").kopia— permitskopia repository createwhen connect finds no repo.sftp/s3/b2/gcs) — marker not yet enforced, so--initisn't required for them (tracked as a follow-up, sync: require .squirrel-volume markers on destination and source to gate against misconfiguration #64).offloadlater delete the only local copy.--initon thesyncusage line and in the flag table.No code change. Verified the documented behaviour against
sync/sync.go(ensureDestinationMarker, thedest.Type == "local"gate) andcmd/squirrel/sync.go(the--initflag).🤖 Generated with Claude Code
https://claude.ai/code/session_01KE9A1VTdw7k1GQq87fQyfx
Generated by Claude Code