> For the complete documentation index, see [llms.txt](https://swu-forge.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://swu-forge.gitbook.io/docs/decks/managing-decks/deck-versioning.md).

# Deck Versioning

**Deck Versioning** lets you track the evolution of a deck over time. Unlike traditional version control where each version is an immutable snapshot frozen in time, SWU Forge's versioning **updates versions in place** — when you save your deck, the active version is overwritten with your current changes. This means versions represent meaningful milestones you explicitly create, not automatic save points.

> Deck Versioning is available to all logged-in users. The Versioning button appears in the workshop once you've signed in and loaded a deck.

## Key Concept: Versions Update in Place

This is the most important thing to understand about deck versioning:

* **Saving your deck updates the active version.** When you click Save in the workshop, your current deck state is written into the active version's snapshot. It does not create a new version — it overwrites the existing one.
* **Creating a new version is a deliberate action.** You must explicitly click the `+` button in the version tree to create a new version. This snapshots your current deck state as a new point in the timeline.
* **Switching to a version loads its snapshot.** When you activate a different version, your working copy is replaced with that version's saved state.

This design means you control exactly when a new version is created. You can iterate on a deck across many save cycles, and the active version absorbs all those changes. When you're ready to mark a milestone — say, before a tournament or after a major rebuild — you create a new version to preserve that state.

![Screenshot: Version tree with multiple versions on a branch](https://cdn.swuforge.com/how-tos/version-tree-overview.png)

## Getting Started

### Automatic Initialization

Every new deck starts with versioning already set up:

* A **main** branch is created automatically
* A first version (**v1**) is created, capturing the deck's initial state
* A baseline **History** entry is recorded for that initial state, so the deck's history starts at creation rather than at your first edit

You don't need to do anything to "enable" versioning — it's there from the moment you create a deck.

### Opening the Versioning Panel

In the workshop, click the **Versioning** button (clock icon with a down chevron) in the header area. This opens a drawer below the header showing the **version tree** — a visual graph of all your branches and versions.

![Screenshot: Versioning button in workshop header](https://cdn.swuforge.com/how-tos/versioning-button.png)

The chevron rotates when the panel is open. Click the button again to close the panel.

## The Version Tree

The version tree is a visual graph where:

* Each **row** (lane) represents a branch
* Each **circle** on a lane represents a version
* **Lines** between circles show the parent-child relationship
* The **active version** is highlighted with a bright green glow
* Branch names are displayed on the left side of each lane

![Screenshot: Version tree with branches and active version highlighted](https://cdn.swuforge.com/how-tos/version-tree-branches.png)

## Creating Versions

At the end of the active branch, you'll see a **dashed circle with a `+` symbol** — this is the "Add Version" button. It only appears on the active branch since new versions are always created there.

1. Click the `+` node
2. A dialog appears with an optional **label** field and two tabs: **Current Deck** and **Import**

### From Current Deck

The default mode. This snapshots your current working copy as a new version.

1. Optionally type a label (e.g., "Pre-tournament", "Added more removal")
2. Click **Create**
3. The new version appears in the tree, highlighted briefly in green

![Screenshot: Add version dialog with label input and mode tabs](https://cdn.swuforge.com/how-tos/add-version-dialog.png)

The new version captures your deck's current state. From this point, saving the deck will update this new version — the previous version remains frozen with the state it had when you created the new one.

### From Import

Instead of snapshotting your current deck, you can import a deck list as the new version. Click the **Import** tab to reveal the import panel, which supports:

* **File upload** — Drag & drop or browse for a `.json` (SWUDB / SWU Forge export) or `.txt` (Melee export) file
* **Paste deck list** — Copy and paste deck content directly (JSON or Melee text format)
* **URL import** — Paste a deck URL from SWU Forge (`swuforge.com/decks/...`), SWUDB (`swudb.com/deck/...`), or Melee (`melee.gg/Decklist/View/...`)

Once the import succeeds, a green confirmation shows the total card count. Click **Create** to save it as a new version. Your working copy is also updated to match the imported deck.

![Screenshot: Add version dialog with import tab active](https://cdn.swuforge.com/how-tos/add-version-import.png)

### When to Create a New Version

Since versions update in place, create a new version when you want to **preserve the current state** before making further changes. Common reasons:

* Before a tournament (so you can revert if post-tournament changes don't work out)
* After a significant rebuild
* Before experimenting with a different strategy
* When you want to compare two states of the deck side-by-side
* When importing a deck list from another source (SWUDB, Melee, or another SWU Forge deck)

## Viewing Version Details

Click any version node in the tree to open a **detail popover** showing:

* **Version number** (v1, v2, etc.) and optional label
* **Parent version** — which version this was created from
* **Timestamp** — when the version was created (shown as relative time, e.g., "3h ago")
* **Diff** — a summary of what changed compared to the parent version:
  * Cards added to the main deck
  * Cards removed from the main deck
  * Cards added to the sideboard
  * Cards removed from the sideboard
  * Whether the Leader changed
  * Whether the Base changed

![Screenshot: Version detail popover showing diff](https://cdn.swuforge.com/how-tos/version-diff-popover.png)

Click the version node again or click elsewhere to close the popover. You can also press **Escape** to dismiss it.

## Setting the Active Version

To load a previous version's state into your working copy:

1. Click the version node you want to activate
2. In the detail popover, click **Set Active**
3. The deck reloads with that version's saved state

The active version is always shown with a **green glow** in the tree. After activating, any saves you make will update this version.

> **Important:** Setting a different version active replaces your current working copy with that version's snapshot. If you have unsaved changes, a [dirty guard dialog](#unsaved-changes-dirty-guard) will appear first.

![Screenshot: Set Active button in version popover](https://cdn.swuforge.com/how-tos/set-active-version.png)

## Branching

Branches let you explore alternative directions for a deck without losing your main timeline.

### Creating a Branch

1. Click the version node you want to branch from
2. In the detail popover, click **Branch**
3. Enter a **branch name** (e.g., "aggro variant", "post-ban")
4. Optionally enter a **label** for the first version on the new branch
5. Choose the deck source using the tabs:
   * **From Source** (default) — the new branch inherits the source version's deck state
   * **Import** — import a deck list from a file, paste, or URL (same options as [creating a version from import](#from-import))
6. Click **Create**

The new branch appears as a new lane in the tree, with its first version (v1) containing either the source version's state or the imported deck. The new branch becomes active immediately, and your working copy loads accordingly.

![Screenshot: Create branch dialog with source and import tabs](https://cdn.swuforge.com/how-tos/create-branch-dialog.png)

### Switching Branches

Click a **branch name** on the left side of the version tree to switch to that branch. This loads the latest version on that branch into your working copy.

You can also switch by activating any version on the target branch via the **Set Active** button.

> Switching branches replaces your working copy. The [dirty guard](#unsaved-changes-dirty-guard) protects against accidental data loss.

### Limits

* Maximum **10 branches** per deck
* Maximum **50 versions** per branch

## Renaming

### Rename a Version

1. Click the version node
2. In the detail popover, click **Rename Version**
3. Type the new label and press **Enter**

Labels are optional — you can add, change, or clear them at any time.

### Rename a Branch

1. Hover over the branch name on the left side of the tree
2. Click the **pencil icon** that appears
3. Type the new name and press **Enter**

Branch names must be unique within a deck.

## Deleting Versions and Branches

### Delete a Version

1. Click the version node
2. In the detail popover, click **Delete Version**
3. Confirm in the dialog

You **cannot** delete the active version or the only version on a branch. If child versions exist, they are re-parented to the deleted version's parent — the chain is preserved without gaps.

### Trim After

To remove all versions after a certain point on a branch:

1. Click the version you want to keep as the last
2. Click **Trim After**
3. Confirm — all later versions on that branch are removed

This is useful for "rewinding" a branch to an earlier state. Branches that were forked from the deleted versions are re-parented to the surviving version.

### Delete a Branch

1. Click the only version on the branch (or use the branch menu)
2. Click **Delete Branch**
3. Confirm in the dialog

You **cannot** delete the active branch or the last remaining branch. All versions on the deleted branch are removed. Branches that were forked from deleted versions are re-parented up the chain to a surviving ancestor.

## Unsaved Changes (Dirty Guard)

When you have unsaved changes and try to switch versions, switch branches, or create a branch, a **dialog** appears with three options:

| Option              | What happens                                                                       |
| ------------------- | ---------------------------------------------------------------------------------- |
| **Cancel**          | Abort the action. Your unsaved changes remain in the working copy.                 |
| **Discard Changes** | Proceed with the action. Your unsaved edits are lost.                              |
| **Save as Version** | Create a new version from your current working copy, then proceed with the action. |

This ensures you never accidentally lose work when navigating the version tree.

![Screenshot: Dirty guard dialog with three options](https://cdn.swuforge.com/how-tos/dirty-guard-dialog.png)

## Reset Versioning

To completely clear all versioning data for a deck:

1. Scroll to the bottom of the version tree panel
2. Click **Reset Versioning**
3. Confirm in the dialog

This deletes **all branches and versions** but does **not** change your current deck content. Your deck continues to exist with its current cards — only the version history is removed. A fresh main branch and v1 will be created the next time you open the versioning panel.

## Summary: How Saving and Versioning Interact

| Action                   | Effect on active version                       | Effect on working copy       |
| ------------------------ | ---------------------------------------------- | ---------------------------- |
| **Save deck**            | Active version's snapshot is overwritten       | No change                    |
| **Create new version**   | New version captures current or imported state | Updated if imported          |
| **Set Active (version)** | New version becomes active                     | Replaced with snapshot       |
| **Switch branch**        | Latest version on new branch becomes active    | Replaced with snapshot       |
| **Create branch**        | New branch's v1 becomes active                 | Loaded from source or import |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://swu-forge.gitbook.io/docs/decks/managing-decks/deck-versioning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.