Version control commands for the Unity CLI
Manage version control for Unity projects with Git, Git providers, and Unity Version Control (UVCS), including commands for asset integrity checks, scene and prefab merges, resolving conflicts, and change analysis.
阅读时间22 分钟最后更新于 7 天前
Use the commands to manage version control for Unity projects from the Unity CLI. Check repository health, track changes, compare scenes and prefabs, resolve merge conflicts, and analyze how changes affect assets, assemblies, and tests. The commands work with Unity Version Control (UVCS) and Git repositories, including GitHub, GitLab, and self-hosted Git with Git LFS. These commands are separate from Unity Collaboration.
unity vcsEach command understands something about Unity projects that a generic version control tool doesn't. For example, scenes and prefabs are YAML ordered by serialization, a missing file breaks every reference to its asset, and pulling with the Editor open can trigger a full reimport.
.metaCommand | Description |
|---|---|
| Sets up a project from no version control to its first commit on a remote. Asks only what it can't detect, and prints the equivalent flag command. |
| Reports which Git providers this machine can reach, as whom, and what each host allows. |
| Configures Unity scene and prefab merging (UnityYAMLMerge) for the repository. |
| Checks the repository settings, ignore rules, and LFS configuration a Unity project needs. |
| Installs or removes Git hooks that run Unity integrity checks on your commits. |
| Shows changes grouped by their meaning to Unity, including |
| Pulls safely: refuses while an Editor holds the project, fetches commits and LFS objects, then reports the reimport. |
| Switches branches safely and reports the impact before you switch. |
| Compares a scene or prefab by GameObject and component name rather than by |
| Shows who last changed each GameObject and component in a scene or prefab. |
| Shows which asset each GUID names, in your working tree or at a commit. |
| Summarizes branch changes so you can paste them into a pull request. |
| Reports which assets, assemblies, and tests a change affects. Reports a lower bound when applicable. |
| Lists unresolved merge conflicts, classified by whether they can merge automatically. |
| Explains in plain language what each side of a conflict changed. |
| Resolves a conflicted Unity asset using the Editor's own merge tool, or by taking one side. |
| Git-only commands: |
| Unity Version Control reads: |
Refer to for the complete list of options for each command.
unity vcs <command> --helpBefore you start
Choose the project
Commands that act on a project accept it in one of these ways, and use the current directory if you pass none:
- A argument: a project path or a registered project name.
[path] - The option.
--project-path <path> - The environment variable.
UNITY_PROJECT_PATH
Pass either the argument or the option, not both. Commands whose argument is a file, such as , , , and , don't take . Neither does , which reads the repository in the current directory and ignores .
vcs diffvcs blamevcs explainvcs resolve--project-pathvcs guidUNITY_PROJECT_PATHRevisions
The , , , and options take a Git revision: a branch, a tag, a commit, or an expression such as .
--from--to--at--sinceHEAD~3Use text serialization
vcs diffvcs blamevcs explainvcs resolvevcs doctorSERIALIZATION_NOT_FORCE_TEXTOutput for scripts
Every command supports the CLI's output formats. Use (or ) when a script reads the result. For details, refer to Output formats and automation.
vcs--json--format jsonSet up version control
Put a project into version control and push its first commit. The command detects what it can, such as an existing repository or remote and the providers you're signed in to, and asks only what it can't work out. It adopts a Git repository that already has a remote.
unity vcs setup [options] [path]
Setup options
Option | Usage | Description |
|---|---|---|
| | The provider: |
| | GitHub organization or GitLab group. Defaults to the signed-in user. |
| | Remote repository name. Defaults to the project folder name. |
| | |
| | Default branch of a new repository. Defaults to |
| | |
| | Description of a new repository. |
| | Reads a personal access token from standard input. Use this instead of |
| | Skips the automatic first commit and push. |
| | Initializes Git LFS before the first commit. New repositories only. |
| | UVCS region for the organization's subscription, the first time only. |
| | Shows what UVCS setup would create, then exits. Only with |
| | Unity Cloud organization for UVCS. You can also set |
| | Existing Unity Cloud project to use with UVCS. |
| | Fills every option you don't pass from a saved preset. |
| | Saves this run's choices as a preset and makes it the default. |
If you don't pass a token, the CLI looks for a Git credential in this order: the provider's environment variable, your Git credential helper or Git Credential Manager, then a provider CLI you're already signed in to (, , or ). The CLI never signs you in or prompts for a token. If none of these has a credential, the command stops and names the sign-in command to run, so sign in to the provider CLI or pass a token first. UVCS uses your Unity sign-in () and needs no token.
ghglabteaunity auth loginIf you pass and Git LFS isn't installed, the CLI prints the command that installs it with your platform's package manager. Run that command, then run again. To have the CLI install Git LFS for you and continue, set . On Linux, the installation asks for administrator rights.
--git-lfsvcs setupUNITY_INSTALL_MISSING_TOOLS=1Setup examples
# Run inside the project and answer the questionsunity vcs setup# Private GitHub repository in an organization, with Git LFS, without promptsunity vcs setup --vcs github --git-namespace my-studio --git-repo space-game --git-lfs --non-interactive# Self-hosted GitLab or Gitea, by host name, over SSHunity vcs setup --vcs git.example.com --git-namespace games --git-remote-protocol ssh# CI: read the token from a secret on standard inputprintf '%s' "$GITHUB_TOKEN" | unity vcs setup --vcs github --git-token-from-stdin --non-interactive# Unity Version Control: preview, then createunity vcs setup --vcs uvcs --cloud-org my-studio --dry-rununity vcs setup --vcs uvcs --cloud-org my-studio# Save the team's choices once and reuse them for every new projectunity vcs setup --vcs github --git-namespace my-studio --git-lfs --save-preset studiounity vcs setup --preset studio
To create a project and its repository in one step, use .
unity projects create --vcs <provider>Check provider access
Report the version control tools on this machine (, , , , , and the UVCS client), which providers the machine can reach and as whom, and what each host allows. This command makes network requests and never prompts for a credential.
gitgit-lfsghglabteacmunity vcs providers [--host <host>]...
Option | Usage | Description |
|---|---|---|
| | Also reports this self-hosted GitHub, GitLab, or Gitea host. You can repeat it. |
unity vcs providersunity vcs providers --host github.example.com --host gitlab.example.com
Configure scene and prefab merging
Configure Git to merge scenes and prefabs with , the merge tool every Editor installation includes. The command writes the entries and the merge driver configuration, then runs a test merge to prove the tool works.
UnityYAMLMerge.gitattributesunity vcs merge-setup [options] [path]
Option | Usage | Description |
|---|---|---|
| | Uses this Editor version's merge tool instead of the version the project requires. You can also set |
| | Uses the merge tool in this Editor installation. |
| | Reports what needs to be configured without changing anything. Exits with code |
| | Skips the test merge. |
Git stores merge driver configuration in , which isn't committed. Run once in each clone, and use in CI to catch a clone that hasn't.
.git/configvcs merge-setup--checkunity vcs merge-setupunity vcs merge-setup --check
Check repository health
Audit what a Unity project needs from its repository: Git settings, ignore rules, Git LFS patterns, and package pinning. The command exits with code when it finds a problem.
4unity vcs doctor [--fix] [--check <codes>] [path]
Option | Usage | Description |
|---|---|---|
| | Repairs every repairable finding. Running it again changes nothing. |
| | Runs only these checks, separated by commas. |
Doctor checks
Area | Checks |
|---|---|
| Ignore rules | |
| Meta files | |
| Attributes and settings | |
| Git LFS | |
| Packages | |
| Package submodules | |
unity vcs doctorunity vcs doctor --fixunity vcs doctor --format github # annotations in a GitHub Actions log
vcs doctorunity projects verifyInstall Git hooks
Install , , and hooks that run the Unity integrity checks automatically. also upgrades hooks from an earlier version. removes only the block the CLI added, so your own hook content stays.
pre-commitpost-checkoutpost-mergeinstalluninstallunity vcs hooks install [path]unity vcs hooks status [path]unity vcs hooks uninstall [path]
Show changes
Show what changed, grouped by what it means to Unity, with file problems called out. For example, an asset added without its file, or a file left behind by a move. This command works only in a Git repository. In a UVCS workspace, use for changes and for lock state.
.meta.meta.metaunity uvcs statusunity vcs uvcs locksunity vcs status [path]
Pull changes safely
Pull commits and Git LFS objects, then report the reimport the pull causes. The command refuses while an Editor has the project open, because pulling under a running Editor can trigger a large reimport or corrupt the folder.
Libraryunity vcs sync [options] [path]
Option | Usage | Description |
|---|---|---|
| | Replays your local commits on top of the incoming ones. |
| | Pulls over uncommitted changes to tracked files instead of refusing. |
| | Pulls even while an Editor has the project open. |
| | Checks the project afterwards without asking. |
unity vcs syncunity vcs sync --rebase --verify
Switch branches safely
Switch branches with the same Editor check as , then report the reimport the switch causes.
vcs syncunity vcs switch [options] <branch> [path]
Option | Usage | Description |
|---|---|---|
| | Runs every check and reports the reimport scope without switching. |
| | Carries uncommitted changes across the switch. |
| | Discards uncommitted changes to tracked files. |
| | Asks the Editor that has the project open to quit, then switches. |
| | Switches even while an Editor has the project open. |
| | Answers yes to every confirmation. |
unity vcs switch feature/lighting --dry-rununity vcs switch feature/lightingunity vcs switch main --close-editor
Compare a scene or prefab
Show what changed in a scene, prefab, or other text-serialized asset, by GameObject and component name instead of by . For example:
fileIDChanged Transform on Player at Player: position position: {x: 0, y: 0, z: 0} to {x: 5, y: 0, z: 0}
unity vcs diff [--from <revision>] [--to <revision>] [--full] <path>
Option | Usage | Description |
|---|---|---|
| | Revision to compare from. Defaults to |
| | Revision to compare to. Defaults to your working tree, including uncommitted changes. |
| | Shows every change and every value in full, with no output limit. |
Each changed object reports how confidently it was matched between the two revisions. Treat anything below as likely rather than certain. Prefab overrides are reported on the prefab instance in the referencing scene, not on the source prefab.
exactWhen a changed value refers to another asset, the output names that asset by its path, looked up at the commit on each side of the comparison. A label marks references that aren't an ordinary asset in the repository: , , , , , or . In JSON, each value has and . In objects larger than 4 MB, reference names appear only with . Without it, the output says the names were left out, and JSON sets .
(added in this range)(deleted in this range)(built in)(package)(in this file)(not in this repository)fromReferencestoReferences--fullreferencesTruncated: true# Your uncommitted changes to a sceneunity vcs diff Assets/Scenes/Level.unity# What a branch changed in a prefabunity vcs diff Assets/Prefabs/Player.prefab --from main --to feature/jump# The last commit onlyunity vcs diff Assets/Scenes/Level.unity --from HEAD~1 --to HEAD# The complete result as JSON, for a script or an AI agentunity vcs diff Assets/Scenes/Level.unity --full --json > level-diff.json
Find who changed an object
Show who last changed each GameObject and component in a scene or prefab. reports who last changed a line of YAML. reports who last changed an object, such as the on the .
git blamevcs blameRigidbodyPlayerunity vcs blame [options] <path>
Option | Usage | Description |
|---|---|---|
| | Blames as of this revision. Defaults to |
| | Only this object, by name or hierarchy path. Naming a GameObject also returns its components. |
| | Only the commit that last changed this serialized field. |
| | How many revisions to search. Defaults to |
If an object shows as , the search reached before finding the change. Increase the limit and run the command again.
unknown--max-revisionsunity vcs blame Assets/Scenes/Level.unity# The Player and every component on itunity vcs blame Assets/Scenes/Level.unity --object Level/Actors/Player# Who last changed the Player's massunity vcs blame Assets/Scenes/Level.unity --object Player --field m_Mass
Find the asset a GUID names
Show which asset each GUID names. Logs, errors, and raw diffs often print a GUID instead of a path, and this saves searching every file for it.
.metaunity vcs guid [--at <revision>] <guid...>
Option | Usage | Description |
|---|---|---|
| | Looks the GUIDs up in the |
The output has one row per GUID, in the order you pass them, with the GUID, its status, its path, and its name. The status is , , , or . A GUID that names nothing still gets a row and isn't an error. A value that isn't 32 hexadecimal digits is a usage error, with exit code .
presentbuilt-inpackagenot-in-repository2unity vcs guid 0123456789abcdef0123456789abcdef# As of a branchunity vcs guid 0123456789abcdef0123456789abcdef --at main# Several at once, as JSONunity vcs guid 0123456789abcdef0123456789abcdef fedcba9876543210fedcba9876543210 --json
Summarize a branch
Summarize what a branch changed, ready to paste into a pull request: counts by Unity asset category, plus the risks a reviewer needs to see. Risks include GUID changes that can break references, assets moved without their file, binary files that can't be reviewed as text, and package manifest changes.
.metaunity vcs summarize --since <revision> [--to <revision>] [--objects] [--full] [path]
Option | Usage | Description |
|---|---|---|
| | Required. Starts the summary at this revision's merge base with the end of the range. |
| | Ends the range at this commit instead of |
| | Adds what changed inside each changed scene, prefab, and asset, object by object, the way |
| | Removes the per-file output limits. Implies |
The can be any folder inside the repository, so the command also works from the root of a repository that contains several projects.
pathunity vcs summarize --since main# Summarize another branch without checking it outunity vcs summarize --since main --to origin/feature/login# Include what changed inside each scene and prefabunity vcs summarize --since main --objects# Write the summary to a file and use it as a pull request bodyunity vcs summarize --since main --format human --no-color > pr-summary.md
Find affected assets and tests
Report which assets, assemblies, and tests a change affects. The command follows two separate paths:
- Assets: from each changed asset, through GUID references, to the prefabs that reference it and then to the scenes that reference those.
- Assemblies: from each changed script, assembly definition, or assembly definition reference to its assembly, and then to the assemblies that reference it, including test assemblies.
The asset path doesn't feed the assembly path. A change to only scenes or prefabs lists affected assets, but no assemblies or test assemblies.
unity vcs affected [--since <revision>] [path]
Option | Usage | Description |
|---|---|---|
| | Compares against this revision's merge base with |
The result is a lower bound. Addressables groups, lookups, assets loaded by name in code, and binary assets are real dependencies that a static reader can't find. JSON output includes and a object that counts what the command couldn't read. Use the result to prioritize tests, not to skip them.
ResourceslowerBound: trueholesunity vcs affectedunity vcs affected --since main# The test assemblies a branch affects, one per lineunity vcs affected --since main --json | jq -r '.data.testAssemblies[]'
List merge conflicts
List every unresolved conflict, classified by Unity asset type, with whether each one can merge automatically.
unity vcs conflicts [path]
unity vcs conflicts# Only the conflicts that need a personunity vcs conflicts --json | jq -r '.data.conflicts[] | select(.mergeEligible | not) | .path'
Explain a conflict
Explain, in plain language and by object and component name, what each branch changed in one conflicted asset.
unity vcs explain <path>
Resolve a conflict
Resolve a conflicted asset by merging both sides with , or by taking one side. Run first.
UnityYAMLMergevcs merge-setupunity vcs resolve [--merge | --ours | --theirs] [options] <path>unity vcs resolve --all [options]
Option | Usage | Description |
|---|---|---|
| | Merges both sides with |
| | Keeps your side of the file and discards theirs. |
| | Keeps their side of the file and discards yours. |
| | Resolves every conflict that can merge automatically. Use it instead of a path. |
| | Uses this Editor version's |
| | Uses the |
unity vcs resolve Assets/Scenes/Level.unityunity vcs resolve Assets/Prefabs/Player.prefab --theirsunity vcs resolve --all
Git-only commands
unity vcs gitFind binaries for Git LFS
Find binary files already committed to history and print the command that moves them to Git LFS. The command never runs the migration itself, because migrating rewrites history.
git lfs migrate importunity vcs git migrate-lfs [--min-size <size>] [--after <date>] [path]
Option | Usage | Description |
|---|---|---|
| | Smallest file size to report, such as |
| | Scans only commits newer than this date, to save time on a large repository. Accepts a date or a relative time, such as |
The printed command includes only the asset types that Unity projects usually store in Git LFS, plus the types the repository already tracks there. Other large files are listed but not included, so source code doesn't end up in Git LFS. Agree on the migration with your team before you run it, because everyone has to clone again afterwards.
unity vcs git migrate-lfsunity vcs git migrate-lfs --min-size 5MB --after 2025-01-01
Work in a second checkout
Create a Git worktree that's ready to open in minutes instead of after a full import: it has the right Editor version, a folder copied from the current checkout, and an entry in the Unity Hub project list.
Libraryunity vcs git worktree add [options] <branch> [path]unity vcs git worktree remove [options] <path>
worktree addOption | Usage | Description |
|---|---|---|
| | Where to create the worktree. Defaults to a folder next to the repository, named after the branch. |
| | How much of the |
| | Installs the Editor version the branch needs instead of only reporting it. If the command can't ask for confirmation, it stops before creating anything, with exit code |
| | Leaves the worktree out of the Unity Hub project list. |
| | Reports the plan without changing anything. |
| | Answers yes to every confirmation. |
If the branch doesn't exist, the command creates it from .
HEADworktree removeOption | Usage | Description |
|---|---|---|
| | Removes the worktree even though it has uncommitted changes. |
| | Removes the worktree even while an Editor has it open. |
| | Reports the plan without changing anything. |
| | Answers yes to every confirmation. |
unity vcs git worktree add feature/lighting --into ../space-game-lightingunity open ../space-game-lightingunity vcs git worktree remove ../space-game-lighting --yes
Unity Version Control commands
unity vcs uvcscmunity plugin install uvcsTo run any other command, use , which passes the arguments to unchanged. For example, or .
cmunity uvcs <arguments>cmunity uvcs lock listunity uvcs shelveList locks
Show who holds each lock, and which locks cover files you changed.
unity vcs uvcs locks [path]
List changesets
List recent changesets.
unity vcs uvcs changesets [--limit <n>] [path]
Option | Usage | Description |
|---|---|---|
| | How many recent changesets to list. Defaults to |
Work with code reviews
Read, answer, and resolve UVCS code review comments. is an alias of .
vcs uvcs reviewsvcs uvcs reviewunity vcs uvcs review [--changeset <id>] [--branch <name>] [--status <status>] [--limit <n>] [path]unity vcs uvcs review comments (--review <id> | --changeset <id> | --branch <name>) [--all-activity] [--limit <n>] [path]unity vcs uvcs review reply --review <id> --comment <id> --body <text> [path]unity vcs uvcs review resolve --review <id> --comment <id> --changeset <id> [path]
Subcommand | Description |
|---|---|
| (none) | Lists code reviews, filtered by changeset, branch, or status. Lists up to 50 by default, and up to 500 with |
| Lists a review's comments with the file and line each one refers to. Select the review by ID, or by the changeset or branch it belongs to. |
| Replies to a comment. |
| Marks a comment as applied in a changeset. |
unity vcs uvcs reviews --branch /main/featureunity vcs uvcs review comments --review 42unity vcs uvcs review reply --review 42 --comment 7 --body "Fixed in the next changeset"unity vcs uvcs review resolve --review 42 --comment 7 --changeset 118
Common workflows
Put a new project under version control
unity vcs providersunity vcs setup --vcs github --git-namespace my-studio --git-lfsunity vcs merge-setupunity vcs hooks installunity vcs doctor
Set up a new clone
git clone https://github.com/my-studio/space-game.gitcd space-gameunity vcs doctor --fixunity vcs merge-setupunity vcs hooks install
Check a pull request in CI
Each command exits with a non-zero code when the repository needs attention, so the job fails.
set -euo pipefailunity vcs doctor --format githubunity vcs summarize --since "origin/$BASE_BRANCH" --format human --no-color > summary.mdunity vcs affected --since "origin/$BASE_BRANCH" --json > affected.json
The job doesn't run . The merge driver is stored in each clone's , which a fresh CI checkout never has, so the check would always fail there. Run once in each developer clone instead.
vcs merge-setup --check.git/configvcs merge-setupResolve a merge that changed scenes
git merge feature/lightingunity vcs conflictsunity vcs resolve --allunity vcs conflictsunity vcs explain Assets/Scenes/Level.unityunity vcs resolve Assets/Scenes/Level.unity --theirsgit commit
Review a scene change
unity vcs summarize --since main --to origin/feature/lightingunity vcs diff Assets/Scenes/Level.unity --from main --to origin/feature/lightingunity vcs blame Assets/Scenes/Level.unity --object Sun --field m_Intensity --at origin/feature/lighting