Create Snapshot

The snapshot create command creates a backup of the current project state.

Bash

zeysdk snapshot create [COMMENT]

Parameters

Parameter	Description	Required	Example
COMMENT	Description of the snapshot	No	"Initial setup"

Process

1. Comment Collection

   • Uses the provided COMMENT argument when present
   • Prompts for a comment when no argument is provided
   • Requires a non-empty comment
   • Press Escape at the comment prompt to cancel without creating an archive or metadata

2. Archive Creation

   • Creates the local snapshot directory when needed
   • Generates YYYYMMDD-HHMMSS.zip, adding a numeric suffix if that name already exists
   • Reserves the output filename exclusively instead of overwriting an existing snapshot
   • Creates a compressed .zip archive and waits for the output stream to close
   • Removes the partial ZIP if archive creation fails

3. Metadata Update

   • Updates metadata only after the ZIP has fully closed
   • Stores the unique snapshot ID
   • Stores the comment
   • Stores the creation timestamp

Examples

Bash

zeysdk snapshot create "Initial setup"
zeysdk snapshot create
zeysdk snapshot create "Release v2.1.0"
zeysdk snapshot create "Pre-update: Payment API"

Error Handling

Error	Description	Resolution
Missing comment	No comment entered at prompt	Enter a non-empty comment
Snapshot write error	Archive could not be created	Check write permissions
Archive error	File compression failed	Check file access and disk space
Metadata error	Snapshot metadata could not be updated	Check snapshot storage permissions

Notes

• Snapshot IDs are generated from local date and time; collision suffixes preserve both same-second snapshots
• The normal project glob includes dotfiles and excludes root .git, node_modules, and .zeysdk/**
• Both .git directories and worktree .git pointer files are excluded
• .zeysdk/assets.json and .zeysdk/package.json are added explicitly when present
• settings/defaultsettings.json is included once through the normal project glob
• Other hidden files and directories are included unless covered by the exclusions above
• Generated directories such as dist and build are included; root node_modules is excluded
• Restore preserves the destination's current root .git and node_modules by moving them into the restored tree without copying their contents. Git history, stashes, and worktree identity survive; dependencies may need updating for restored manifests
• Restore rejects archives containing reserved root .git or node_modules entries, including older archives containing a worktree pointer. These entries must not replace destination operational state
• Preservation and archive validation use existing dependencies only
• Snapshot archives are compressed as ZIP files

Best Practices

• Create a snapshot before large refactors to a current-format project
• Use comments that describe the reason for the snapshot
• Include release, task, or change names in comments when helpful
• Create a fresh snapshot after a stable milestone