Blender Git

Git-based version control directly inside Blender. Commit, branch, merge.

Blender 5.x Git LFS Ready Solo & Team Friendly GitHub · GitLab · Any Remote
On this page
Introduction

Overview

Blender Git brings Git-based version control directly inside Blender, with no terminal required for everyday tasks. It gives you a dedicated Git tab in the 3D Viewport sidebar, where you can commit your work, manage branches, view history, resolve merge conflicts, and connect to remote repositories. All without leaving Blender.

Because .blend files are binary, standard Git cannot tell you what changed inside them. Blender Git partially solves this by capturing a snapshot of your scene each time you stage a .blend file. When you look at a change in the panel, you see a plain-English list like "Object 'Cube' moved", "Material 'Base' shader nodes changed", "Render resolution changed" , rather than an unreadable binary diff.

Blender Git panel showing changes

The Git panel inside Blender's 3D Viewport sidebar

Snapshot limitations Snapshots provide friendly summaries of scene changes, not a complete low-level record of every internal .blend detail. Staging, unstaging, and discarding work at the file level. You cannot operate on individual scene changes inside a .blend. Conflict resolution also works at the file level: choose one complete version per file.

Who is this for?

Solo Artists

A save-point system with meaningful descriptions. Roll back to any earlier state of your project anytime.

Small Teams

Collaborate on a shared project via GitHub, GitLab, or any Git host without leaving Blender.

Anyone who wants history

Ever wished you could roll back a Blender project to an earlier state? Now you can.

Requirements

Prerequisites

Before installing the addon, make sure the following tools are in place:

Requirement Where to get it Notes
Blender 5.x or later blender.org Earlier versions are not tested
Git git-scm.com Must be installed and available system-wide
Git LFS git-lfs.com Required. Handles large .blend files efficiently
Why Git LFS? Standard Git stores the full history of every changed file. A 200 MB .blend with 50 commits would bloat the repository to gigabytes. Git LFS stores the actual binary files in a separate object store and keeps only small pointer files in the Git history , keeping the repository lean and fast. Git LFS is a separate install from Git itself. After installing, it registers globally and works transparently.
Setup

Installation

  1. Download the addon .zip file.
  2. In Blender, go to Edit > Preferences > Add-ons.
  3. Click Install and select the downloaded .zip.
  4. Enable the addon by ticking its checkbox.

The addon adds a Git tab to the 3D Viewport's N-panel. Press N to open the sidebar if it is not visible.

First-time Configuration

Open the addon preferences to review the Requirements section. It shows whether Blender can find Git and Git LFS, plus the official install locations if either is missing. Install them separately, then restart Blender.

Addon preferences: Requirements section

Addon preferences showing Git and Git LFS detection status

Before committing, set your Git author identity from Configuration > Set Identity. Enter your name and email, then save them for the current repository. Enable Save globally only if you want the same identity to become your user-wide Git default.

Set Identity dialog

Configuration → Set Identity dialog

No workflow settings need to be configured. Scene snapshots are always captured automatically when you stage a .blend file.
First Steps

Getting Started

Starting a New Project

  1. Save your .blend file to the folder where you want the project to live.
  2. Open the Git panel. It will prompt: "No Git repository found."
  3. Click Initialize Repository.

The addon creates a Git repository in the same folder as your .blend file, configures Git LFS, prepares .gitignore and .gitattributes, and makes the first commit. You are ready to work.

Initializing a new repository

Git panel after initialization

.gitignore configuration popup

Joining an Existing Project

If someone has already set up a project on a remote (GitHub, GitLab, etc.):

  1. Open Blender before opening any .blend file.
  2. Click Clone it here (visible when no repository is detected).
  3. Enter the repository URL and choose a destination folder.
  4. After cloning, open your .blend file from that folder via File > Open.

If you already have a local clone, simply open a .blend file from inside that folder and the panel will detect the existing repository automatically.

Cloning an existing project

Architecture

How It Works

Tracks Your Whole Project

When you initialize a repository, Git watches every file in that folder and its subfolders, including .blend files, textures, references, and any other assets. You decide which changes to record and when.

Git LFS for Large Files

.blend files are binary. Git LFS stores them in a dedicated object store and places a small text pointer in the Git history. From your perspective it is invisible. Just stage, commit, and switch branches as usual.

Scene Snapshots

Each time you stage a .blend, the addon captures a snapshot of the current scene state and stages it alongside the file as a small JSON stored under .blender_git/snapshots/.

Snapshots

Scene Snapshots

Snapshots are how Blender Git generates human-readable change descriptions for binary .blend files. Every snapshot captures the state of the open file at the moment of staging.

Changes panel showing readable scene diff

Readable scene diff generated from snapshots in the Changes panel

What Gets Recorded

  • Whether each object was added, removed, or modified
  • Transform: position, rotation, scale
  • Viewport and render visibility
  • Parent-child relationships & collection membership
  • Applied modifiers, material slot assignments, shape keys
  • Vertex groups, constraints, particle systems, rigid body physics

  • Meshes: vertex count, face count, UV map count
  • Armatures: bone count
  • Cameras: focal length, camera type (perspective / orthographic / panoramic)
  • Lights: energy, type (point / sun / spot / area), color
  • Text objects: character count

  • Keyframe count per object
  • Number of animated properties (F-Curves)
  • NLA tracks & drivers

  • Whether each material was added or removed
  • Shader node count & texture image node count
  • Transparency mode

  • Frame range (start / end), FPS
  • Render engine, resolution, samples (Cycles & EEVEE)
  • Active camera, world environment, render output format
  • Collections: objects inside each, sub-collection structure
  • Linked library file paths & externally referenced image names

Snapshot Rules

  • Staged automatically. When you stage a .blend file, its snapshot is captured and staged alongside it.
  • Must be committed. The snapshot is the "before" state the next time you make changes. If you stage but do not commit, the change view may be incomplete.
  • Orphan snapshots are visible. If a snapshot exists without its .blend, Blender Git shows it as an orphan row. Stage or discard it from the panel.
  • Do not edit snapshot files by hand. Treat them as managed project metadata. Use the panel's controls to resolve any issues.
  • Do not add .blender_git/ to .gitignore. Everything in it (especially snapshots/) must be tracked and committed.
  • Multi-file projects are supported. Each .blend file gets its own snapshot in a mirrored subfolder structure.
Interface

Panel Reference

The Git panel lives in the 3D Viewport's N-panel. Press N to toggle the sidebar. The panel is divided into several sections:

Toolbar
  • Home: Opens the repository root folder in your system's file explorer.
  • CMD: Opens a terminal window at the repository root for advanced Git commands.
  • Configuration: Access identity, remote settings, .gitignore editor, .gitattributes editor, and credentials info.
  • Refresh: Manually re-checks the repository status if something appears out of sync.
Branch & Remote Status

Below the toolbar, a box shows the current branch name, the remote name and URL (if configured), and whether you are ahead, behind, or up to date with the remote.

Save Required State If the current .blend file has unsaved edits, Blender Git pauses the normal workflow until you save. The panel shows a warning with a Save File button. Git actions use the on-disk version of the file . Saving first keeps the change list, snapshot, and commit content aligned.
Commit Section
  • Commit message field: A description of what you did. Required to commit.
  • Commit Staged: Records staged changes as a new commit.
  • Stash All: Saves all changes (staged and unstaged) into a temporary stash, leaving the working tree clean.
Staged Changes Panel
  • Each file row shows a status indicator and the filename.
  • For .blend files with a snapshot, a chevron button expands a scrollable list of changes in plain English.
  • Click the minus button to unstage a file or folder.
  • Unstage All moves everything back to the Changes panel.
Changes Panel
  • Files displayed in a folder tree. Click a folder name to expand or collapse it.
  • Plus button on a file or folder stages it (auto-captures the snapshot for .blend files).
  • Trash button discards all changes and reverts to the last committed state. This cannot be undone.
  • Blender icon on a .blend row opens that file in a new Blender window.
  • Stage All and Discard All apply to all visible changes at once.
Stashes Panel

Collapsed by default. Click the header to expand. Lists all saved stashes with their label and index.

  • Apply: Restores a stash's changes to the working tree and reopens the .blend file. Only available when the working tree is clean.
  • Drop: Permanently deletes a stash entry. A confirmation dialog appears first.

Using the Stashes panel

Branching

Branch Management

Access branch actions via the Branch Actions button next to the current branch name.

  • New Branch: Creates a new branch from the current state and switches to it immediately. Staged, unstaged, and untracked changes remain in place.
  • Change Branch: Switch to a different local or remote branch. Local changes are preserved; conflicts are surfaced via the conflict banner.
  • Merge Branch: Merges the selected branch into the current branch. If a conflict is detected, the conflict banner appears.
  • Fetch: Downloads new commits and branch references from the remote without modifying local files.
  • Pull: Downloads and applies remote commits to the current branch.
  • Push: Uploads your local commits to the remote tracking branch.
  • Delete Branch: Deletes a local branch. Protected names (main, master, develop, dev) cannot be deleted.
  • History: Opens the commit history view.

Creating a new branch and committing work

Protected Branches The following branch names cannot be deleted from within the panel as a safeguard: mainmasterdevelopdev. They can still be deleted via a terminal if genuinely needed.
History

Commit History

Accessed via Branch Actions > History. The history panel lists commits in reverse chronological order, showing the short hash, message, author, and date.

Commit details use the same snapshot language as the Changes panels. Snapshot-only entries are visible, and orphan snapshots are labelled with (orphan).

Checkout to New Branch

From any commit entry, click Checkout to New Branch to prompt for a branch name, then create a branch starting at that commit and switch to it. Requires a clean working tree.

Browsing commit history

Conflicts

Merge Conflict Resolution

When a merge produces a conflict, the normal Changes and Commit panels are replaced by a conflict banner showing which branches are involved and how many files need resolution.

Do not reopen conflicted files normally While a .blend file is unresolved, opening it normally can disturb the binary conflict state. Use the conflict dialog's inspection buttons. Reopen the conflicted file normally only after the conflict has been resolved.

Resolution Steps

  1. Click Resolve Conflicts to open the conflict dialog.
  2. For each conflicted .blend file, use Open Ours in Blender and Open Theirs in Blender to inspect both versions.
  3. Click Keep Ours or Keep Theirs for each conflicted file. Its companion snapshot follows the same choice.
  4. Resolve any snapshot-only conflict rows, including orphan snapshot rows marked with (orphan).
  5. Once all conflicted files have a choice assigned, click Complete Merge to finalize and create the merge commit.

To abandon the merge entirely, click Restore to Latest Commit (Abort Merge) from the conflict banner. The repository returns to the state before the merge.

Because .blend files are binary, conflicts are resolved per file. You choose one complete version of each conflicted file. There is no partial merge.

Resolving a merge conflict

Configuration

Remote & Configuration

Identity

Open Configuration > Set Identity to set the author name and email used for commits. By default, values are saved only to the current repository. Turn on Save globally to write them to your user-wide Git config.

Remote

Open Configuration > Configure Remote to:

  • Add or change the remote URL (e.g. a GitHub or GitLab repository)
  • View the current tracking branch

After adding a remote, use Fetch to retrieve its branches, Pull to bring in the latest commits, and Push to upload your commits.

Configuring a remote repository

.gitignore Editor

Lists the current .gitignore entries. Add patterns for files or folders you do not want Git to track (e.g. temporary render output, cache folders). The addon pre-populates sensible defaults for Blender projects on initialization.

.gitattributes Editor

Controls how Git treats specific file types, including which formats are stored via Git LFS. The defaults cover .blend and common image and video formats. Edit only if you need to add custom file types.

Workflows

Typical Workflows

Daily Work: Solo
  1. Work on your scene.
  2. Save the .blend file (Ctrl+S).
  3. Switch to the Git panel and review the Changes list.
  4. Click the + button on your .blend to stage it (snapshot captured automatically).
  5. Type a commit message and click Commit Staged.
Saving Work-in-Progress
  1. Type a short description in the commit message field (it will become the stash label).
  2. Click Stash All.
  3. Your changes are saved and the working tree goes clean.
  4. When ready, open the Stashes panel and click Apply.
Experimenting on a Branch
  1. Make sure your current work is committed (or stashed).
  2. Branch Actions > New Branch, named e.g. experiment-retopo.
  3. Work and commit freely on this branch.
  4. If it works: Merge Branch back into your main branch.
  5. If not: switch back and delete the experiment branch.
Collaborating with a Team
  1. One person initializes the repo and pushes to a remote.
  2. Team members use Clone it here to get a local copy.
  3. Each person works on their own branch.
  4. Use Fetch / Pull to stay current; Push to share.
  5. Open a pull request on your hosting platform, then pull the merged result.

Team collaboration and merging via GitHub

Example

Example: Two-Person GitHub Collaboration

This example follows two users working on the same Blender project through GitHub. Both have Git, Git LFS, Blender Git installed, and access to the same GitHub repository.

1. User A: Initializes the Project

  1. Save the .blend file inside a clean project folder.
  2. Open the Git tab and click Initialize Repository.
  3. Blender Git creates the repository, configures Git LFS, prepares .gitignore and .gitattributes, and creates the first commit.

Initializing the repository

2. User A: Uploads to GitHub

  1. Create an empty GitHub repository.
  2. Open Configuration > Configure Remote and add the GitHub URL.
  3. Click Branch Actions > Push for the first upload.

Adding a remote and pushing

3. User B: Clones the Project

  1. Open Blender before opening any .blend file.
  2. Open the Git tab and click Clone it here.
  3. Enter the GitHub repository URL and choose a local folder.
  4. Open the cloned .blend from that folder.

Cloning the project

4. User B: Creates a Branch & Commits

  1. Open Branch Actions > New Branch and give it a name.
  2. Edit the file, save it, then stage the .blend in the Changes panel.
  3. Expand the staged file to review the readable scene diff.
  4. Click Commit Staged, then Branch Actions > Push.

Creating a branch, committing, and pushing

5. User B: Stashes Temporary Work

  1. Start an experiment that is not ready to commit.
  2. Type a short stash label in the commit message field.
  3. Click Stash All.
  4. Later, open Stashes and click Apply to restore it.

Stashing and restoring work

6. User B: Checks History

  1. Open Branch Actions > History.
  2. Review commits by message, author, date, and hash.
  3. Use Checkout to New Branch to continue from an old version.

Viewing commit history

7. User B: Merges into Master

  1. Checkout to master via Branch Actions > Change Branch.
  2. Click Merge Branch, enable "Show remote", and select the work branch.
  3. Merge is complete. Master now contains changes from the working branch.

Merging changes via pull request

8. Merge with Conflict

If both users changed the same .blend file on different branches:

  1. During merge, Blender Git shows the conflict banner.
  2. Click Resolve Conflicts and use Open Ours / Open Theirs to inspect both versions.
  3. Choose Keep Ours or Keep Theirs for each conflicted file.
  4. Resolve any snapshot-only or orphan conflict rows.
  5. Click Complete Merge.

Resolving a merge conflict

Known Limitations

Limitations

Conflict resolution is all-or-nothing per file Because .blend files are binary, you cannot combine parts of two versions. You choose one complete version of each conflicted file.
Conflicted files should not be reopened before resolution While a .blend file is unresolved, opening it normally can disturb the binary conflict state. Use the conflict dialog's inspection buttons, resolve the conflict, then open the result normally.
Staging and discarding apply to entire files Because .blend files are binary, there is no way to include or exclude individual changes within a file. Every staging, unstaging, or discard operation affects the whole file at once.
Git & Git LFS are required Git LFS is not bundled with Git and must be installed separately from git-lfs.com before initializing a repository. The addon will refuse to initialize without it.
Blender 5.x only The addon is built for Blender 5.x and may not function correctly on earlier versions. Earlier versions are not currently tested.
Help

Q&A

No. Everything you need for daily version control: staging, committing, branching, fetching, pulling, pushing, and viewing history is available as buttons in the panel.

Git LFS (Large File Storage) stores large binary files like .blend and textures in a separate system so your repository history stays small and fast. Without it, every commit that touches a large .blend would duplicate its full size in history. Git LFS is required by this addon . Install it from git-lfs.com. It is a free, one-time install.

Yes. Any standard Git remote is compatible. You can clone, fetch, pull, and push from within the panel.

Make sure the addon is enabled in Edit > Preferences > Add-ons. The Git tab lives in the 3D Viewport's N-panel. Press N to toggle it. If you are in a workspace without a 3D Viewport (such as Video Editing), switch to a layout that includes one.

The addon detects the repository based on the location of the currently open .blend file. If no .blend is open, or if the .blend is not inside the repository folder, the panel cannot find it. Open a .blend from within the repository and the panel will connect automatically.

If a snapshot is missing, the matching .blend may show no snapshot until a new staged commit re-establishes the baseline. If a snapshot exists without its .blend, Blender Git shows it as an orphan snapshot row so you can stage or discard it instead of being left with a hidden dirty file.

Not simultaneously on the same file, which is a fundamental limitation of binary files. Teams should divide work so each person is primarily responsible for different .blend files or branches, and merge at natural milestones.

The file was first committed before the addon was installed, so no baseline snapshot exists in the history. Stage the file and commit once; the panel will capture a snapshot and from that point on the change details will appear normally.

Yes, as long as you save before switching. If the current .blend has unsaved edits, Blender Git disables branch switching and shows a Save File button first. After saving, switching branches reopens the .blend from the selected branch. If it does not exist on the target branch, Blender opens a new unsaved General file.

Yes. The Push button appears in the branch info box and in the Branch Actions menu whenever the current branch has a remote tracking branch. For advanced push options (force push, specific remote, etc.) use the CMD button to open a terminal.

The addon automatically moves the companion snapshot to match the new filename whenever a rename is detected via Save As in Blender. If files are renamed outside Blender, orphaned snapshots may appear . Discard them in the next staging pass.

Yes. The repository tracks the entire folder tree. Each .blend file gets its own snapshot in a mirrored subfolder structure under .blender_git/snapshots/. The change view works for all of them.
Support

Contact

Questions or issues? Reach out through:

Legal

License

GPL-3.0-or-later. See the LICENSE file for details.