Docs/Introduction
View on Fab

Introduction

SafeSave is a compact Unreal Engine 5 editor plugin that makes source control status and unsaved assets impossible to ignore. It lives in your Level Editor toolbar and continuously reports your branch/workspace, local changes, upstream state, unsaved work, and explicit status failures when the provider CLI cannot return a clean read. The goal is simple: fewer surprises, safer updates, and fewer lost edits.

Always-On Status

Continuously checks dirty assets and SCM status so you can act before it is too late.

File Locking Protection

Actively detects checkout status and strictly blocks saving of files locked by other users.

Clear Signals

Labels and color cues explain exactly what is happening in your repo, including degraded states like Status Error, Login Required, and unsaved work with no valid SCM connection.

Status Pipeline

SafeSave combines two signals: unsaved assets from the editor and source control status from the CLI. The toolbar fuses those into a single, readable state.

Dirty Scan SCM Status Toolbar

Quick Start

1. Install the Plugin

Place the SafeSave folder into your project Plugins directory and restart the editor.

YourProject/
└── Plugins/
    └── SafeSave/
        ├── SafeSave.uplugin
        └── Source/

2. Ensure Source Control Is Available

SafeSave supports Git and Plastic SCM (Unity Version Control). Make sure the CLI for your provider is installed and reachable.

  • Git: Ensure git.exe is on PATH and the project is inside a Git repo.
  • Plastic SCM: Install the cm CLI and sign in via UE Source Control.

Set the active provider in UE: Source Control → Connect to Git or Plastic SCM.

If UE Source Control is not connected, SafeSave falls back to provider probing: it checks Git first, then Plastic SCM, and still keeps unsaved asset counts visible in degraded states.

First Run Checklist

  1. Open your project in UE5.
  2. Look for the SafeSave widget in the Level Editor toolbar.
  3. Click it and verify the menu opens.
  4. Open Editor Preferences and tune the settings.
  5. Run SafeSave.StressTest from the UE console if you want a quick developer sanity check of toolbar transitions.
Tip: If you see SCM Missing, No SCM Repo, or Login Required, scroll down to Troubleshooting for exact fixes.

Toolbar Tour

The SafeSave widget is a single button with a dynamic label. The icon and color are meaningful and change with the repo state.

Label Anatomy

The label always uses the format branch | state. For Git, detached head shows as detached. For Plastic SCM, the workspace/branch name is shown. If source control is unavailable or unresolved, SafeSave still combines the state with unsaved asset counts, for example SCM Missing | Unsaved 3 or Login Required | Unsaved 2.

  • Branch: Current Git branch, or Plastic SCM workspace/branch.
  • State: One of the status states described below.
  • Composite States: Missing SCM, missing repo, or login-required states can be paired with Unsaved N so unsaved work is never hidden.
  • Lock Warnings: If files you are editing are checked out by another user, the state overrides to Locked (N) to immediately warn you of impending conflict.
  • Checkout Prompts: If files require server checkout, the state shows Checkout Req (N).
main | Clean Icon Branch State

Menu Actions

The menu header reflects the active provider (Git or Plastic SCM), and the action list adapts automatically.

Core Actions

  • Save All: Saves all dirty assets and maps.
  • Refresh Status: Re-scan dirty assets and source control status.
  • Show Status Details: A dialog with full repo details, including CLI diagnostics for Status Error.

Source Control Actions

  • Git: Fetch, Pull (Rebase), Push (clean tree required, resolved status required).
  • Plastic SCM: Update Workspace (clean workspace required, login required state blocks update, resolved status required).
  • Auto Fetch: Git-only toggle with visible interval.

Developer Utility

SafeSave registers the console command SafeSave.StressTest. Use it to exercise toolbar transitions and notification behavior during development or demos.

Status States

SafeSave reduces source control complexity into a small set of states. These are the exact labels you will see in the toolbar.

SCM Missing

No Git or Plastic SCM CLI found. Install the provider CLI and restart UE.

No SCM Repo

Project is not inside a Git repo or Plastic workspace.

Login Required

Plastic SCM is selected, but credentials are missing or expired. Unsaved asset counts remain visible in the label.

Status Error

The provider CLI was found and the repo/workspace was detected, but a status command failed. Open Show Status Details to inspect the exact error.

Conflicts

Merge conflicts detected (Git or Plastic). Resolve before updating.

Locked (N)

You have dirty assets that are actively locked by another user. These files are strictly blocked from being saved.

Checkout Req (N)

You have dirty assets that require server checkout. SafeSave will automatically request checkout on save.

Unsaved N

Editor has unsaved assets. Save before pull, push, or update.

Diverged

Ahead and behind at once. Common in Git; resolve before syncing.

Behind N

Updates available. Git shows commits; Plastic shows newer changesets.

Changes

Local pending changes. Git tracks staged/unstaged; Plastic tracks pending files.

Ahead N

Local commits ahead (Git) or newer changeset state (Plastic).

Clean

Working tree/workspace is clean and aligned with upstream.

Composite labels are intentional. If you have unsaved work while SCM is missing, no repo is detected, or Plastic login is required, SafeSave shows states like SCM Missing | Unsaved 3, No SCM Repo | Unsaved 3, and Login Required | Unsaved 2.

Source Control Actions

SafeSave exposes a conservative set of provider‑specific actions inside the editor.

Safety Gates

Pull and Push are intentionally conservative. These commands are only enabled when both your files and your editor state are clean, and when the provider status is fully resolved.

Gate 1
Clean working tree (no staged, unstaged, or untracked files).
Gate 2
Upstream must be configured for the branch.
Gate 3
No unsaved assets in the editor.
Gate 4
Status must be resolved. Git Status Error disables Git actions. Plastic update also requires a valid login.

Command Details

Git

  • Fetch: Runs git fetch --prune to update remote refs.
  • Pull (Rebase): Runs git pull --rebase when behind, clean, upstream is set, and the branch is not already ahead of upstream.
  • Push: Runs git push when ahead, clean, upstream is set, and the branch is not behind upstream.
  • Diverged: When ahead and behind at the same time, SafeSave shows Diverged and disables both Pull and Push.

Plastic SCM

  • Update Workspace: Runs cm update when clean, logged in, and the workspace status is resolved.
  • Login Required: Actions disable until credentials are valid.
  • Status Error: If Plastic CLI status commands fail after workspace detection, update is disabled until the error is resolved.
SafeSave never stages, commits, rebases manually, or resolves conflicts for you. It only exposes safe commands when the workspace state supports them.

Settings

Open Editor Preferences > Plugins > SafeSave to tune refresh rates and notifications.

Setting Default Effect
DirtyCheckIntervalSeconds 1.0 How often SafeSave checks for unsaved assets.
Status Poll Interval (GitCheckIntervalSeconds) 5.0 How often SafeSave polls the active provider (Git or Plastic).
Auto Fetch (bAutoFetch, Git only) false Automatically run fetch on a timer when Git is the provider.
Auto Fetch Interval (AutoFetchIntervalSeconds) 120 Interval for auto-fetch (minimum 10 seconds, Git only).
bToastOnStatusChange true Show a toast when the toolbar label changes.
StatusToastMinIntervalSeconds 4.0 Throttle toast frequency to avoid spam.

Auto Fetch

Auto fetch keeps your remote refs fresh without touching your local files. This feature applies to Git only.

How It Works

  • Only runs when Git is the active provider and the repo is valid.
  • Uses git fetch --prune.
  • Pauses automatically if a status update is already in flight or the repo is currently in Status Error.
  • Interval is visible in the SafeSave menu.
Fetch Fetch Fetch Fetch

Notifications

SafeSave can display toasts when the toolbar state changes. This is useful when you want visible feedback while working in full-screen viewports.

Status Change Toasts

Enabled by default. When the label changes (e.g., Behind 4 to Clean), SafeSave shows a brief toast. Healthy states use success styling; degraded states like Diverged, Conflicts, Login Required, or Status Error use warning or failure styling.

SafeSave: main | Clean

Error Feedback

If a Git or Plastic action fails, SafeSave shows an error toast with the first line of stderr. For provider status failures, open Show Status Details to view the full Status Error diagnostic.

Fetch failed. Check authentication or remote access.

Git Checkout & Locking

Unreal Engine's source control model was designed around Perforce, where files must be explicitly "checked out" (locked) before editing. Git does not have this concept natively. This section explains how SafeSave handles checkout across different setups.

The Checkout Problem on Git

When UE's built-in Git plugin is active, the editor may show a "Check Out Assets" dialog when you try to save a modified Blueprint or other asset. In this dialog, the "Check Out Selected" button is greyed out and only "Make Writable" is available. This happens because:

  1. Unreal asks the source control provider: "Can this file be checked out?"
  2. The standard UE Git plugin answers No — Git has no built-in file locking.
  3. The dialog renders "Check Out Selected" as disabled since the provider reported checkout is unsupported.

How SafeSave Handles This

SafeSave detects when the source control provider does not support checkout and bypasses the dialog entirely. During Save All, the following logic runs:

  1. For each dirty package, SafeSave queries the provider state.
  2. If a file is not checked out, not newly added, and CanCheckout() returns false, SafeSave marks it as a non-checkoutable file.
  3. When non-checkoutable files are detected, SafeSave clears the read-only flag on disk for each affected file.
  4. The save is then executed with the checkout prompt suppressed, so the "Check Out Assets" dialog never appears.

This means Git users without LFS locking can save assets normally through SafeSave without encountering the greyed-out dialog.

Important

This bypass only activates when the provider genuinely does not support checkout. If you have Git LFS locking configured with a compatible plugin, CanCheckout() returns true and the normal checkout flow is preserved.

Behavior by Source Control Setup

SafeSave adapts its save and checkout behavior based on your source control configuration:

Setup Checkout Dialog Lock Detection Save Behavior
Git (no LFS locking) Bypassed — never shown Not available — no lock server Files made writable automatically, saved directly
Git + LFS Locking Normal — checkout via git lfs lock Full — Locked (N) status, open-time toasts Automatic checkout before save, locked files blocked
Plastic SCM Normal — native checkout Full — Locked (N) status, open-time toasts Automatic checkout before save, locked files blocked
No Source Control Not applicable Not applicable All dirty packages saved directly

Enabling Git LFS Locking (Optional)

If your team needs file-level locking on Git (recommended for teams collaborating on binary assets like Blueprints and Maps), you can enable Git LFS locking. This gives SafeSave full lock detection and teammate conflict warnings.

Requirements

  • Git LFS installed (git lfs install).
  • A Git hosting service that supports LFS locking (GitHub, GitLab, Gitea, etc.).
  • A UE Git plugin that implements CanCheckout() via git lfs lock. The built-in UE Git plugin does not support this. Use a third-party plugin such as the ProjectBorealis UE Git Plugin.

Configuration

Add the lockable attribute to your binary asset types in .gitattributes:

*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap filter=lfs diff=lfs merge=lfs -text lockable

Once configured, SafeSave will automatically detect lock status through Unreal's source control provider interface and enable:

  • Locked (N) toolbar state when dirty assets are locked by teammates.
  • Open-time toast warnings when you open an asset that is already locked.
  • Automatic checkout (locking) before saving assets that require it.
  • Save blocking for files locked by other users.
Without LFS locking, Git users can still use every other SafeSave feature: status monitoring, branch display, fetch/pull/push, unsaved asset tracking, and the Save All workflow. Only the lock detection and checkout features require LFS locking support.

Recommended Workflow

SafeSave is designed for a simple, low-risk daily loop.

  1. Before starting work, hit Fetch to update remote refs.
  2. If you are Behind, save assets and Pull (Rebase) for Git or Update Workspace for Plastic.
  3. If you are Diverged or see Status Error, stop and inspect the repo state before running update actions.
  4. Work normally. Keep an eye on Unsaved and Changes.
  5. When done, save all assets and commit in your Git client.
  6. If Ahead, use Push for Git. For Plastic, check in via your Plastic client.
Tip

SafeSave does not stage or commit files. Use your preferred Git or Plastic client for commits. SafeSave focuses on safety and visibility inside the editor.

Troubleshooting

SCM Missing

Install Git or Plastic SCM (Unity Version Control) and ensure the CLI is reachable. Restart the editor after changes.

No SCM Repo

Initialize a Git repo or open a project inside a Plastic workspace. SafeSave will still show unsaved asset counts even when no repo is found.

Login Required (Plastic SCM)

Sign in via UE Source Control. SafeSave will show Login Required until credentials are valid, and unsaved assets remain visible in the same label.

Plastic CLI Not Found

Install the cm CLI and set the full path in the Source Control login dialog. Do not wrap the path in quotes.

Status Error

If SafeSave shows Status Error, the provider CLI was found and the repo/workspace was detected, but one of the status commands failed. Use Show Status Details to inspect the exact command error, then fix credentials, remote access, or CLI configuration.

"Check Out Selected" Greyed Out (Git)

If you see the "Check Out Assets" dialog with the "Check Out Selected" button disabled, this means you are saving through Unreal's built-in save path rather than SafeSave's Save All. SafeSave's Save All bypasses this dialog entirely for Git users without LFS locking. Use the SafeSave toolbar menu or ensure you are saving through SafeSave. If you need full checkout support, see the Git Checkout & Locking section for how to enable Git LFS locking.

Pull, Push, or Update Disabled

SafeSave requires a clean workspace, no unsaved assets, a configured upstream (Git only), and a resolved status. Pull is also disabled when the branch is ahead of upstream, and Push is disabled when the branch is behind or diverged.

Upstream Not Set (Git)

Set an upstream using your Git client or CLI: git branch --set-upstream-to=origin/main.

Status Seems Stale

Use Refresh Status or reduce the status poll interval in settings.

FAQ

Does SafeSave modify my files automatically?

No. The only automatic action is optional Git fetch. Pull, push, and update require manual action.

How does SafeSave handle file locking?

File locking is handled through two distinct safety workflows designed to prevent un-mergeable binary conflicts:

  • Preemptive Open Alerts: The moment you double-click an asset (like a Blueprint or Map) in the Content Browser, SafeSave queries the server. If a teammate already has that file checked out, a large red toast notification instantly drops from the top of your screen warning you ("LOCKED by Teammate: Name"). This allows you to back out before making doomed edits.
  • Active Save Blocking: When you click Save All, SafeSave intercepts the dirty file list. If any file is locked by another user, SafeSave explicitly blocks the local save operation for those specific files, throwing a dialog popup with the list of blocked assets. For remaining files that just need standard checkout, it automatically issues the checkout command before letting the save complete.

Does SafeSave require Git LFS locking?

No. SafeSave works fully without Git LFS locking. Status monitoring, branch display, fetch/pull/push, unsaved asset tracking, and Save All all work with standard Git. LFS locking is only needed if your team wants file-level lock detection and teammate conflict warnings. See Git Checkout & Locking for details.

Why did I see a "Check Out Assets" dialog with a greyed-out button?

This is Unreal's built-in checkout dialog, which appears when saving through the editor's native save path (e.g., Ctrl+S in a Blueprint editor). The button is greyed out because the standard UE Git plugin does not support file checkout. SafeSave's Save All action bypasses this dialog entirely by detecting that checkout is unsupported, making files writable, and saving directly. Always use SafeSave's Save All to avoid this issue.

Does SafeSave support Plastic SCM?

Yes. When UE’s Source Control provider is set to Plastic SCM, SafeSave uses the cm CLI for status and update.

Can I use SafeSave without Git?

Yes. SafeSave supports Git or Plastic. If neither is available, it will show SCM Missing or No SCM Repo, and still shows unsaved assets.

Why does it say Status Error?

SafeSave could find the provider CLI and repo/workspace, but a status command failed after detection. Open Show Status Details to inspect the exact command error.

Why does it say Login Required?

Plastic SCM is selected but credentials are missing or expired. Sign in through Source Control to continue.

Why is it not showing branch names?

If Git is in a detached state, SafeSave displays detached. For Plastic, the workspace/branch name is shown when available.

How does provider detection work?

SafeSave uses the active UE Source Control provider when one is connected. If Source Control is disconnected, it probes Git first, then Plastic SCM, and uses the first valid repo/workspace it finds.

Is there a built-in test command?

Yes. SafeSave registers SafeSave.StressTest as a console command for development and demo sanity checks.

About

SafeSave is a Git and Plastic SCM Unreal Engine editor plugin built to reduce mistakes, surface risk, and protect your work from accidental overwrites.

If you want deeper integration (commit view, diffs, or changelist tooling), SafeSave pairs well with your existing Git client rather than replacing it.

Recent Validation Coverage

SafeSave was recently validated in UE 5.7 editor automation with successful coverage for integration, toolbar states, command gating, live disposable Git flows, live diverged Git behavior, and the live Plastic probe path.

7 / 7 Passed
Editor automation suite completed without SafeSave test failures.
Live Git Coverage
Clean, Changes, Ahead, Behind, and Diverged states were validated against disposable repos.
Live Plastic Probe
The real cm.exe path was validated for the current machine state.