GDnD Wiki

GDnD Wiki

This site is for Ulster University students and staff. Enter the class access password to continue.

GitHub for Unity: Setup and Collaboration

14 min read

Summary

GitHub is the standard platform for hosting Git repositories, providing cloud backup for your project and enabling team collaboration. For Unity developers, GitHub means your project is safe from hard drive failure, your team can work in parallel on separate features, and every change is traceable to a person and a reason. This page covers everything needed to get a Unity project onto GitHub and to work collaboratively with a small team.

Setup

1. Create a GitHub account

Visit github.com and sign up for a free account. Use an email address you check regularly — GitHub sends notifications about activity on your repositories. Enable two-factor authentication under Security settings once your account is created.

2. First-time Git configuration

If you have not already set up Git on your machine:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global init.defaultBranch main

The email address here should match the one registered on GitHub so your commits are linked to your profile.

Creating a new repository on GitHub

  1. Click the + button in the top-right corner of GitHub and choose New repository
  2. Enter a repository name (e.g. my-unity-game) — short and descriptive
  3. Choose Public (anyone can see it) or Private (only you and collaborators)
  4. Do not initialise with a README if you have an existing Unity project locally — you will push from your machine instead
  5. Click Create repository

GitHub will show you the commands to use. For a new project:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/my-unity-game.git
git push -u origin main

The -u flag sets origin/main as the default upstream, so future pushes just need git push.

Unity .gitignore

Create this file first — before your initial commit. Save it as .gitignore in the root folder of your Unity project (the folder containing Assets/, ProjectSettings/, etc.):

# Unity auto-generated folders — never commit these
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Ll]ogs/
[Mm]emoryCaptures/

# Build output
[Bb]uild/
[Bb]uilds/
[Rr]eleases/

# IDE and editor files
.vs/
*.csproj
*.sln
*.userprefs
*.suo
UserSettings/

# OS-generated files
.DS_Store
.DS_Store?
Thumbs.db

# Asset Store tools
[Aa]ssetStoreTools*

What to track (do NOT add to .gitignore):

FolderWhy it must be tracked
Assets/All game content: scripts, scenes, prefabs, textures, audio
ProjectSettings/Input manager, quality settings, physics layers, tags
Packages/Unity Package Manager dependencies

Why the Library/ folder must be excluded: Unity’s Library folder is a compiled cache of all your assets — it can be hundreds of megabytes or several gigabytes for large projects. It is entirely regenerated by Unity from the Assets folder. Committing it wastes storage, slows every push and pull dramatically, and causes endless merge conflicts.

If you already committed Library/ by mistake

git rm -r --cached Library/
git commit -m "Remove Library folder from tracking"

The --cached flag removes it from Git tracking without deleting it from your hard drive.

Cloning an existing project

When joining a project that already exists on GitHub:

git clone https://github.com/username/project-name.git

This downloads the full repository and sets up origin automatically. Open the resulting folder in Unity Hub.

Daily workflow with GitHub

# Start of work session: get latest from teammates
git pull
 
# Make changes, then save them
git add .
git commit -m "Add collectible item with score counter"
 
# End of work session: upload to GitHub
git push origin main

Always pull before pushing when collaborating. This prevents your push from being rejected because teammates have added commits since you last synced.

Adding collaborators

To give teammates push access to your repository:

  1. Go to the repository on GitHub
  2. Click Settings → Collaborators
  3. Type their GitHub username and click Add collaborator
  4. They receive an email invitation and must accept it

Collaborators can clone, push, and pull directly. They do not need to fork. This is the right setup for a small class team (2–5 people) working on one project together.

Pull Requests

A Pull Request (PR) is a GitHub feature for proposing and discussing changes before merging them. The workflow:

  1. Create a feature branch locally: git checkout -b feature-health-system
  2. Make commits on that branch
  3. Push the branch to GitHub: git push origin feature-health-system
  4. On GitHub, you will see a prompt to Compare & pull request — click it
  5. Write a title and description explaining what the change does and why
  6. Submit the Pull Request

Your teammate can then review the code, leave comments on specific lines, and either approve or request changes. When everyone is satisfied, click Merge pull request on GitHub.

Which branch a pull request should target (main or a develop integration branch), and how to make GitHub require an approval and a passing Unity build before the merge button works, are covered in git-branching (team branching models, protected branches) and unity-ci-with-gameci.

Why use Pull Requests even in small teams:

  • Forces a second pair of eyes on every change
  • Creates a written record of why each feature was added the way it was
  • Gives practice with the industry-standard collaboration workflow

Basic PR workflow

# On your machine:
git checkout -b feature-sound-effects
git add Assets/Scripts/AudioManager.cs
git commit -m "Add positional audio for footsteps and impacts"
git push origin feature-sound-effects
 
# On GitHub:
# 1. Open Pull Request from feature-sound-effects to main
# 2. Teammate reviews and approves
# 3. Merge on GitHub
# 4. Back on your machine:
git checkout main
git pull              # get the merged changes
git branch -d feature-sound-effects    # clean up

Unity .meta files and merge conflicts

Every asset in a Unity project — scripts, textures, prefabs, scenes, folders — has a corresponding .meta file. Unity uses these to store internal GUIDs (unique identifiers) that link assets together. If a script is referenced by a prefab, that link is stored via the script’s GUID in its .meta file.

The rule: always commit .meta files. Never add *.meta to your .gitignore. If a .meta file is missing, Unity regenerates it with a new GUID, breaking every reference to that asset across the project.

Why .meta conflicts happen

.meta files are plain text and can be merged automatically in most cases. Each asset has its own .meta file, so two teammates adding different assets to the same folder does not cause a conflict. Conflicts arise in two main situations:

  • Both branches change the same asset’s import settings (for example, one person changes a texture’s compression and another changes its filter mode), so both edit the same lines of the same .meta file.
  • The same new asset or folder is created on two branches (for example, both people create Assets/Sprites/Enemies/), so Unity generates two .meta files for the same path with different GUIDs.

The fix is straightforward:

  1. Open the conflicting .meta file in a text editor
  2. For a GUID clash, keep one version’s GUID — usually the teammate who made the first commit wins, since other assets may already reference that GUID. For an import-settings clash, keep the settings the team actually wants
  3. Delete the conflict markers (<<<<<<<, =======, >>>>>>>)
  4. Stage the resolved file: git add Assets/Path/To/Asset.meta

Preventing .meta conflicts

The most effective prevention is coordination: agree who creates shared folders and who owns each asset’s import settings. If two people both create the same folder, or both re-import the same texture with different settings, a .meta conflict is likely. Use the branch strategy — each teammate works on a feature branch with its own set of new assets, then one person merges at a time.

Scene and prefab conflicts are harder. Scene (.unity) and prefab (.prefab) files are serialised in Unity’s YAML format — they are technically text, but the auto-merge output is usually broken. The safest policy:

  • Treat scene and prefab files as binary for the purposes of team coordination
  • Use Smart Merge (Unity’s UnityYAMLMerge tool, shipped with the Editor) for genuine scene conflicts
  • Register it once in your Git config. Naming the tool is not enough; Git also needs the command that runs the UnityYAMLMerge binary. The Unity manual’s documented form for .gitconfig is:
[merge]
    tool = unityyamlmerge
 
[mergetool "unityyamlmerge"]
    trustExitCode = false
    cmd = '<path to UnityYAMLMerge>' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

Replace <path to UnityYAMLMerge> with the binary in your Editor install’s Data/Tools folder — for example C:\Program Files\Unity\Editor\Data\Tools\UnityYAMLMerge.exe on Windows or /Applications/Unity/Unity.app/Contents/Tools/UnityYAMLMerge on macOS (Unity Hub installs live in a versioned folder under the Hub’s Editor directory). Then run git mergetool when a scene or prefab conflict occurs (Unity Documentation, Smart merge, https://docs.unity3d.com/6000.2/Documentation/Manual/SmartMerge.html).

Large binary assets and Git LFS

Unity projects often include large files: audio clips, high-resolution textures, video clips, .fbx models, and packaged builds. Standard Git stores a full copy of every version of every file — a 50 MB texture committed ten times consumes 500 MB of repository history. This makes cloning slow and storage costs grow quickly.

Git LFS (Large File Storage) solves this by replacing large files in the repository with small text pointers. The actual file data is stored on a separate LFS server (GitHub provides this automatically). When you clone or pull, Git downloads only the LFS files you need.

Setting up Git LFS

# Install Git LFS (once per machine)
git lfs install
 
# Track specific file types — run this in your repo root
git lfs track "*.psd"
git lfs track "*.png"
git lfs track "*.tga"
git lfs track "*.fbx"
git lfs track "*.wav"
git lfs track "*.mp3"
git lfs track "*.ogg"
git lfs track "*.mp4"
 
# Commit the .gitattributes file that LFS creates
git add .gitattributes
git commit -m "Set up Git LFS for binary assets"

After setup, tracked files are handled automatically — git add, git commit, and git push work exactly as before, but the binary data goes to LFS storage.

What to track with LFS

Track files that are:

  • Large (over 1–2 MB per file)
  • Binary (not human-readable text)
  • Changed frequently, creating many historical versions

Do not track .meta files with LFS — they are plain text and must be mergeable.

Locking binary files so two people cannot edit them at once

LFS keeps large files out of Git’s history, but it does not make them mergeable. If two teammates both edit Boss.psd (or the same .fbx, or a scene that neither can merge cleanly) on different branches, Git can only ask which whole file to keep: one person’s work is lost. Git LFS file locking prevents this by letting one person claim a file before editing it (Git LFS, File Locking; GitHub, Git LFS 2.0.0 released).

1. Mark file types as lockable. Add --lockable when tracking:

git lfs track --lockable "*.psd"
git lfs track --lockable "*.fbx"
git add .gitattributes
git commit -m "Make PSD and FBX files lockable"

This writes lines such as *.psd filter=lfs diff=lfs merge=lfs -text lockable to .gitattributes. The lockable attribute can also be added by hand to text files that are not stored in LFS, for example *.unity lockable for scenes kept as Force Text YAML (Git LFS, File Locking). Files already tracked can be made lockable by running the same command with --lockable.

2. Lockable files are read-only until you lock them. Git LFS makes lockable files read-only in your working copy unless you hold the lock, so you cannot start editing one by accident (Git LFS, git-lfs-track). This is controlled by the lfs.setlockablereadonly setting, which defaults to true (Git LFS, git-lfs-config). Most editors, Unity included, will warn or fail when saving a read-only file, which is the reminder to lock it first.

3. The daily workflow.

git pull                                     # get the latest version first
git lfs lock Assets/Art/Boss.psd             # claim it (file becomes writable)
# ...edit, save, commit...
git push
git lfs unlock Assets/Art/Boss.psd           # release it for the team
git lfs locks                                # who has locked what?
  • git lfs lock <path> records the lock on the LFS server under your name; the file must exist in your working copy (Git LFS, git-lfs-lock).
  • git lfs locks lists current locks and their owners; git lfs locks --verify marks the ones you own with O (Git LFS, git-lfs-locks).
  • git lfs unlock <path> releases the lock. The file must have a clean git status, so commit and push first. git lfs unlock --force <path> removes someone else’s lock, for instance when a teammate went home with a file locked; some servers restrict this to administrators (Git LFS, git-lfs-unlock; File Locking).

4. What a lock actually enforces. When you push, Git LFS checks that you are not changing files locked by someone else and halts the push if you are (Git LFS, git-lfs-config, lfs.<url>.locksverify). A lock does not stop anyone editing a local copy they have made writable, and it does not undo edits made before the lock was taken: always pull and lock before opening the file. Locks are held on the server per file path; the Git LFS locking API describes itself as supporting only “the simplest use case: single branch locking” (Git LFS, File Locking API). In practice (tentative), treat a lock as “nobody else touches this file on any branch until I unlock it”, and merge your work promptly so the next person locks the up-to-date version.

GitHub support. GitHub’s LFS server implements the locking API, so these commands work against GitHub repositories (checked with git lfs locks --verify against a GitHub repository in October 2026). The locking API specification expects servers to give lock rights only to users with push access, so add teammates as collaborators (Git LFS, File Locking API).

When to use locks. Lock files that cannot be merged and are expensive to redo:

  • Art and source files: .psd, .kra, .aseprite, .blend, .fbx, large textures, audio project files
  • Scenes (.unity) that several people touch: even as YAML text, scene merges are unreliable, so a lock (by hand-added lockable) is often simpler than Smart Merge
  • Prefabs only if they are shared hot spots; small prefabs edited by one owner do not need locking, and locking too much slows everyone down
  • Not scripts (.cs) or .meta files: these are text and merge normally

A team that does not want the read-only friction can still use git lfs lock as a visible “I’m on it” flag without marking files lockable, but then nothing stops an accidental edit. The older team habit of agreeing scene ownership (see Collaboration tips below) remains useful alongside locks.

GitHub LFS limits

As of 2026, GitHub Free personal accounts (and free organisations) include 10 GiB of Git LFS storage and 10 GiB of Git LFS bandwidth, with the free quota resetting each billing cycle; without a payment method, going over blocks new LFS pushes (storage) or disables LFS until the next month (bandwidth) (GitHub Docs, Git Large File Storage billing, https://docs.github.com/en/billing/concepts/product-billing/git-lfs). Check that page for current figures, as GitHub has changed them before. For a student project this is usually sufficient. If you approach the limit, compress audio and textures before committing, track only genuinely large binaries, and avoid committing repeated versions of huge source files. Note that Unity Addressables do not help here: they control how content is packaged into builds and loaded at runtime, but the source assets still live in the project and the repository.

Collaboration tips for Unity teams

Assign ownership of scenes and large assets. Decide at the start of a work session who is editing which scenes and which prefabs. Scene file conflicts are painful to resolve manually. Git LFS file locking (above) turns this agreement into something the server enforces.

Commit often with clear messages. Small frequent commits are easier to understand and easier to reverse than large infrequent ones. “WIP” is not a useful commit message.

Pull at the start of every work session. Letting multiple days pass without pulling means conflicts accumulate and become harder to resolve.

Use branches for features, not for people. The branch model works best when branches track features (feature-shop-ui, fix-falling-bug) rather than people (johns-work, sarahs-branch). This makes it clear when a feature is done and ready to merge.

Communicate before touching shared files. A quick message to teammates (“I’m editing the shop UI scene and ShopManager.cs today”) prevents most conflicts.

External references

Graph View

Backlinks