Workspaces

The Cost of Branch Switching

When working on Unreal Engine projects, you frequently encounter situations where you want to “just check another branch”:

• While developing a main feature, an urgent bug fix request comes in
• You want to review a colleague’s PR while continuing your own work
• You need to check the release branch to investigate a production issue

However, in large projects, the cost of branch switching becomes very high:

• Editor restart: When .uasset files change, you need to close the Editor
• Shader compilation and cache regeneration: Depending on branch differences, cache regeneration can take a long time
• Loss of work state: Open assets, window layouts, and debug settings are reset

Waiting 30 minutes “just to check something” isn’t practical. As a result, you start avoiding branch switches, and development flexibility is lost.

Solving with Workspaces

The workspace feature uses Git worktree to deploy multiple branches simultaneously.

• Parallel work: Deploy multiple branches in independent folders
• State preservation: Maintain DCC and shader/C++ compilation results for each workspace
• Instant switching: Switch between workspaces without file checkout

Prerequisites

To use the workspace feature, the repository must be in Textil Workspace configuration. Traditional Git repositories (with a .git folder) only support branch switching.

Repositories created with Textil are automatically in Workspace configuration. Existing repositories can be converted from Textil.

Directory Structure

Textil Workspace uses Git worktree with the following structure:

Each workspace is an independent directory, but they share Git objects in .bare/.

Comparison with Clones

You could also clone the repository multiple times to work on different branches. However, for large projects, disk usage becomes a problem.

Method	Git Objects	Working Files
Multiple clones	Per branch	Per branch
Workspaces	Shared	Per branch

Working files (checked out files) require the same amount either way, but Git objects and LFS file caches are shared across workspaces.

Note

In the future, we plan to add functionality to share Unreal Engine’s generated DCC and compilation results across workspaces for even faster switching.

Workspace List

The workspace panel shows all workspaces associated with the current repository.

Item	Description
Name	Workspace identifier
Branch	Checked out branch
Path	Workspace directory path
Status	Presence of changes (clean / has changes)

The currently active workspace is highlighted.

Usage

Create a Workspace

1. Click the + button in the workspace panel
2. Enter a workspace name
3. Select the branch to check out
4. Select the destination directory (or auto)
5. Click Create

Tip

We recommend creating workspace directories on the same drive as the main repository. Hard links won’t work on different drives, which may reduce efficiency.

Switch Workspaces

1. Click the target workspace in the workspace list
2. The selected workspace becomes active
3. File list and diff views switch

Switching completes instantly—no file checkout occurs.

Work in a Workspace

Each workspace functions as an independent working directory:

• Edit files: Edit just like a normal repository
• Commit: Commit independently in each workspace
• Push: Push changes to remote
• Pull: Fetch changes from remote

Delete a Workspace

1. Right-click the workspace you want to delete
2. Select Delete Workspace
3. Click Delete in the confirmation dialog

Caution

Deleting a workspace with uncommitted changes will lose those changes. Commit or stash changes before deletion.

Branches and Workspaces

Creating New Branches

When creating a workspace, you can select an existing branch or create a new one:

• Existing branch: Select from dropdown
• New branch: Enter a branch name to create

Branch Constraints

You cannot check out the same branch in multiple workspaces within one repository.

✅ workspace-a: main
✅ workspace-b: feature/login
✅ workspace-c: feature/settings
❌ workspace-d: main (main is already in use by workspace-a)

Use different workspaces for different branches.

Use Cases

Parallel Feature Development and Bug Fixes

When developing a main feature while handling an urgent bug fix:

1. Developing features on feature/new-ui branch
2. Urgent bug report comes in
3. Create a new workspace with hotfix/critical-bug
4. Fix the bug, commit, and push
5. Return to the original workspace and continue feature development

Switch work instantly without waiting for Editor restart or shader recompilation.

Separating Reviews and Development

When reviewing code while continuing your own development:

1. Your development on feature/my-work
2. Create a workspace for feature/teammate-pr to review
3. After review, return to your development workspace

Simultaneous Testing of Multiple Versions

When testing different versions simultaneously:

1. Workspace for release/v1.0
2. Workspace for release/v2.0
3. Check behavior in each Editor

Unreal Editor Integration

When opening a workspace in Unreal Editor, open each workspace’s .uproject file separately:

D:\Projects\MyGame\           <- main branch
D:\Projects\MyGame-feature\   <- feature branch

You can launch separate Editor instances for each workspace. This means:

• Shader cache is maintained per workspace
• Run multiple versions simultaneously