Skip to content

Version History & Restore

SkillMeat maintains a complete immutable record of every change to your artifacts. This guide explains how to view version history, compare versions, and safely restore to any previous version.

Overview

Every modification to an artifact creates a new immutable version entry:

  • Saved changes — When you update artifact content
  • Synced updates — When you pull changes from upstream
  • Imported versions — When you import from the marketplace or GitHub
  • Restored versions — When you restore a previous version (creates a new version, preserves original)

The version timeline preserves complete history with: - Exact timestamp of each change - Who made the change (collection source, sync, import, restore) - What changed (file additions, deletions, modifications) - Why it changed (change attribution: upstream, local, conflict)

This enables you to recover from corruption, rollback unwanted changes, or explore your artifact's evolution over time.

Viewing Version History

Opening the History Timeline

  1. Navigate to an artifact in the web UI
  2. Click the History tab at the top of the artifact details panel
  3. The timeline view displays all versions chronologically with:
  4. Version timestamps — When each version was created
  5. Change badges — Color-coded indicators of change origin
  6. Current marker — Shows which version is currently deployed
  7. Summary counts — Number of files added, removed, modified

Timeline Navigation

The timeline displays versions in reverse chronological order (newest first). Each version shows:

Date & Time - When the version was created (formatted as "Jan 15, 2025 10:30 AM")

Version Type Badge - Indicates what kind of change created this version: - Saved — Manual edit to artifact - Synced — Pulled from upstream or collection - Imported — Added from marketplace or GitHub - Restored — This is a restore operation result

Change Origin Badges - Files in each version show their origin: - Blue Badge — Upstream changes (from collection or marketplace source) - Amber Badge — Local modifications (your customizations) - Red Badge — Conflicting changes (both sides modified)

File Summary - Quick counts showing: - +N files added - -N files removed - M N files modified

Identifying the Current Version

The "Current" label appears on whichever version is currently deployed to your project. If you're viewing version history in the web UI, the current version helps you understand what's running right now.

Viewing Version Metadata

Click on any version in the timeline to see:

  • Exact timestamp of creation
  • Version type (saved, synced, imported, restored)
  • File list with change attribution badges for each file
  • Change summary showing total additions and deletions
  • Associated metadata (sync source, upstream version if applicable)

Comparing Versions

Side-by-Side Diff

To see exactly what changed between two versions:

  1. In the timeline, click the first version you want to compare
  2. Hold Shift and click a second version to compare against
  3. A diff panel opens showing side-by-side comparison:
  4. Left side — Content from the first version (older)
  5. Right side — Content from the second version (newer)
  6. Green highlights — Lines added in the newer version
  7. Red highlights — Lines removed in the newer version
  8. Blue highlights — Lines that changed

Understanding Diff Display

The diff viewer shows:

File structure - Full path of file being compared

Change legend: - Green (+) — Added in the newer version - Red (-) — Removed in the newer version - Blue (modified) — Changed content

Context lines - Several unchanged lines around each change for context

Binary files - Indicated as binary with a note (no detailed diff for binary files)

Comparing Against Current Version

To compare any version against what's currently deployed:

  1. Click the version you want to compare
  2. Look for the "Compare with Current" option
  3. The diff panel opens automatically showing changes needed to update to this version

Large Artifact Handling

For artifacts with many versions or large file sizes:

  • Lazy diff loading — Diffs only render when you scroll into view (faster loading)
  • Performance optimized — Even with 100+ versions, timeline remains responsive
  • Indexed queries — Efficient version lookups by creation date

Restoring a Previous Version

Two-Step Restore Process

Restore follows a safe two-step workflow: preview, then confirm.

Step 1: Select & Preview

  1. Open the History tab on your artifact
  2. Click the version you want to restore to
  3. Click "Restore to This Version" button
  4. The preview diff panel appears showing:
  5. What the artifact looks like now (current version)
  6. What it will look like after restore (target version)
  7. Exact line-by-line changes that will happen
  8. Whether any conflicts exist

Step 2: Confirm Restore

After reviewing the preview:

  1. Click "Confirm Restore" button
  2. A confirmation dialog appears with a final summary
  3. Click "Restore" to proceed
  4. The restore completes and a new version is created

Non-Destructive Restore Behavior

Critically, restore is always safe:

  • New version is created — Your artifact gains a new entry in the timeline
  • Original versions preserved — The version you restored from still exists unchanged
  • Complete audit trail — All versions remain visible in history
  • Multiple restores allowed — You can restore from the same version multiple times

Example: If you have versions v1 → v2 → v3 and restore to v1, the timeline becomes v1 → v2 → v3 → v1-restored. All four versions exist. You can restore from v1 again later.

Restore with Conflicts

If the version you're restoring has conflicting changes (marked with red badges):

  1. The diff preview shows conflict markers indicating which lines conflict
  2. You can proceed with restore knowing conflicts exist
  3. After restore, you may need to manually resolve conflict markers in the restored file

See "Handling Conflicts" section below for resolution guidance.

What Happens to Deployments

When you restore a version:

  • Projects using this artifact remain unchanged until you explicitly redeploy
  • Deployment tracking updates to record the restore event
  • You can re-sync the artifact to projects to get the restored version
  • The restored version becomes available for deployment immediately

Deployments & Topology

Understanding Deployment Status

The Topology panel (available in the History tab) shows where your artifact is currently deployed across all projects:

Status indicators: - Active — Artifact is deployed and matches collection version - Outdated — Artifact is deployed but newer version exists in collection - Pinned — Deployment is locked to a specific version (won't auto-sync)

Viewing the Topology Panel

  1. Open artifact History tab
  2. Scroll to Topology section — Shows all projects with this artifact
  3. Each project displays:
  4. Project name
  5. Current deployed version (hash)
  6. Deployment status (active/outdated)
  7. Pin status (locked or unlocked)
  8. Deployment timestamp

Outdated Badge

An "Outdated" badge appears when your collection has a newer version than what's deployed in a project. This helps you spot projects that need updating.

The topology panel includes: - Count of outdated deployments (e.g., "3 of 5 projects outdated") - Percentage outdated (helps prioritize when many projects are behind)

Push to Collection

What is Push?

Push lets you take modifications you've made to an artifact in your project and push them back to your main collection. This is useful when you've customized an artifact locally and want to share that improvement across all your projects.

How to Push

  1. Open artifact in web UI and make your modifications
  2. Click the "Push to Collection" action in the artifact detail view
  3. A conflict preview appears showing what will change in your collection
  4. Review the changes — green shows what you're adding, red shows what you're removing
  5. Click "Confirm Push" to apply changes
  6. The artifact in your collection is now updated and available for deployment

Handling Push Conflicts

If your local modifications conflict with upstream changes:

  1. A "Conflict Detected" dialog appears showing both versions
  2. Review which approach makes more sense (yours or the upstream version)
  3. Choose "Push My Version" to keep your customization or "Cancel" to keep collection as-is
  4. After push, other projects can sync to get your improvement

Sync All Outdated

One-Click Sync for Multiple Projects

The "Sync All Outdated" action updates all projects that have outdated deployments to the latest collection version.

How to Use Sync All

  1. Open artifact in web UI
  2. Look for "Sync All Outdated" button in the Deployments section
  3. Click the button — all outdated projects are updated at once
  4. A progress indicator shows how many projects are syncing
  5. Pinned projects are skipped (won't be synced until unpinned)

Results Summary

After sync completes, you'll see: - "Synced 3 projects" — How many were successfully updated - "2 pinned (skipped)" — How many pinned deployments were not touched - Any errors that occurred (e.g., if a project was deleted)

Pinned Projects

Projects with pinned deployments are intentionally excluded from "Sync All". To sync a pinned project:

  1. Unpin it in the project details
  2. Run "Sync All" again, or manually redeploy the artifact
  3. Repin if needed for future deployments

Automatic Version Seeding

What is Automatic Seeding?

When you upgrade to VCS v2 or enable version history, SkillMeat automatically seeds historical versions for all your existing artifacts. This means:

  • Existing artifacts gain version history instantly (no manual action needed)
  • No versions are lost — all previously known states are preserved
  • Seeding happens in the background during upgrade

Hydration Banner

During the seeding process, a "Hydration in Progress" banner appears at the top of the web UI:

  • Shows progress: "Processing artifacts (45 of 120)"
  • Updates every few seconds as seeding continues
  • Disappears automatically when seeding completes

What Gets Seeded?

Automatic seeding captures versions from: - Deployed artifacts — Snapshots of what's currently in each project - Collection history — Previous syncs and imports are preserved - Upstream sources — Known versions from GitHub or marketplace

This ensures you have continuity before and after upgrade.

Impact on Your Work

  • No interruption — Continue using SkillMeat while seeding happens in the background
  • History available immediately — Once seeding completes, you can restore to any previous version
  • Safe operation — Seeding only reads existing state; no changes are made to artifacts

Composite Artifacts

Version History for Composites

Composite artifacts (bundles, composites with multiple members) show version history at two levels:

Composite level — Versions of the entire composite as a unit

Member level — You can view history for individual members within the composite

Restoring Individual Members

When restoring a composite artifact, you can choose which members to restore:

  1. Open the History tab for the composite artifact
  2. Click "Restore to This Version" on your target version
  3. Member selection panel appears listing all members:
  4. Check ✓ members you want to restore
  5. Uncheck members you want to keep at current versions
  6. Only selected members will be updated

Example Scenario

Suppose you have a bundle with: - canvas-ui.py (current: v2.1.0) - canvas-core.py (current: v2.0.0) - canvas-config.yml (current: v1.5.0)

You restore to version from 2025-01-10 which had: - canvas-ui.py v2.0.0 - canvas-core.py v1.9.0 - canvas-config.yml v1.4.0

You can select to restore only canvas-core.py and canvas-config.yml, keeping canvas-ui.py at v2.1.0.

Atomic Restore

If you select multiple members to restore:

  • All members are restored together in a single atomic operation
  • If any member restore fails, the entire operation rolls back (nothing is modified)
  • Safety snapshot is taken before restore to enable rollback if needed

This ensures composites never end up in a partially-restored state.

Enterprise: Version Scoping

Note: Version scoping features are available in Enterprise edition. Local edition users see a single global version timeline.

What is Version Scoping?

In Enterprise deployments, version history can be scoped at three levels:

User Scope — Each user has their own version timeline - User modifications are isolated from other team members - User can view and restore only their own versions - User versions are visible to team and enterprise admins

Team Scope — Team members share a curated version baseline - Team admins can approve or reject member versions - Members can promote personal versions to team baseline - Team versions become the reference point for all team members

Enterprise Scope — Organization-wide approved versions - Enterprise admins maintain the canonical version - Teams can promote to enterprise scope (requires approval) - Strict audit trail of all scope changes

Promotion Workflow

Members can promote versions up the scope hierarchy:

  1. User → Team: User version gets promoted to team baseline after team lead approval
  2. Team → Enterprise: Team version promoted to org-wide baseline after enterprise approval
  3. Enterprise Promotion: Results in increased visibility but doesn't change the version itself

Viewing Scoped Versions

In the Enterprise history tab, you see:

  • Your versions — All versions created by you
  • Team versions — Versions approved by your team
  • Enterprise versions — Organization-wide approved versions
  • Promotion status — Shows whether versions are pending approval, rejected, or approved

Approving/Rejecting Promotions

Team and enterprise admins can:

  1. Review promotion requests in the Admin Console
  2. View the version diff to understand what's being promoted
  3. Approve to move version up a scope tier
  4. Reject with optional feedback to require changes

Preventing & Resolving Conflicts

Understanding Conflict Badges

When a version has conflicting changes (red badges), it means:

  • Both upstream and your local changes affected the same file
  • The system performed a three-way merge but couldn't automatically resolve
  • Manual review is required to decide which approach to use

Handling Conflicts During Restore

If you restore a version with conflicts:

  1. Conflict markers appear in the restored file in Git-style format: 

    <<<<<<< LOCAL
your current version
=======
restored version
>>>>>>> RESTORED

  2. Resolve manually by:

  3. Keeping LOCAL (your current code)
  4. Keeping RESTORED (the restored version)
  5. Intelligently merging both approaches

  6. Removing the conflict markers

  7. After resolving, the artifact works normally and has a new version

Conflict Resolution Decision Guide

Situation Recommendation
Upstream added logging, you added error handling Merge intelligently — Keep both features
Upstream refactored function, you customized behavior Understand both sides — May need to reapply customization on refactored version
Upstream deprecated something, you still use it Keep local — Keep your version until you can migrate
Both added different features Merge — Import/call both features if possible

Feature Availability

Version history features are available in all SkillMeat editions, with scope restrictions in Enterprise. See the Edition Feature Matrix for complete details.

Feature Local Edition Enterprise Edition
View version timeline ✓ ✓
Compare any two versions ✓ ✓
Restore to previous version ✓ ✓
Composite member selection ✓ ✓
User version scoping — ✓
Team version approval workflow — ✓
Enterprise version promotion — ✓
Admin version management — ✓

Recovery Workflows

Scenario 1: Accidental Modification

Problem: You accidentally modified a critical artifact and want to revert.

Solution: 

1. Open artifact History tab
2. Find the version before your accidental modification
3. Click "Restore to This Version"
4. Review the preview diff
5. Click "Confirm Restore"
6. Redeploy the artifact to projects

Time to recover: ~2 minutes

Scenario 2: Corrupt File Content

Problem: Your artifact file is corrupted or has invalid syntax.

Solution: 

1. Review recent versions for when corruption started
2. Find the last known-good version
3. Click "Restore to This Version"
4. Verify the restored content is correct in preview
5. Confirm the restore
6. Test in your project

Key insight: Version history acts as automatic backup with full audit trail.

Scenario 3: Conflicting Upstream Changes

Problem: Upstream made changes that conflict with your customizations.

Solution: 

1. View History tab and locate versions with red conflict badges
2. Compare upstream version vs your version in diff panel
3. Decide: keep upstream, keep local, or merge both
4. Restore to your preferred version or manually merge
5. Create a new version with resolved conflict

Troubleshooting

History Not Showing All Versions

If your history timeline seems incomplete:

  1. Refresh the page — timeline data may need reloading
  2. Check if artifact was recently imported — early versions may not be available
  3. Contact support if timeline stops before expected date

Restore Preview Shows No Changes

If comparing identical versions:

  1. Both versions may be the same — no changes to preview
  2. Try comparing against a different version
  3. Use diff panel to see file structure differences

Conflict Resolution Difficult

If conflicts are complex:

  1. Start by understanding what upstream changed (blue badge changes)
  2. Understand what you changed (amber badge changes)
  3. Contact your team lead or maintainer for guidance
  4. Consider keeping both versions separately (fork strategy) to preserve both approaches

See Also