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

9 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.

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. Conflicts arise when two teammates both add a new asset to the same folder at the same time — Git sees two different .meta files trying to claim the same space and cannot auto-resolve. The fix is straightforward:

  1. Open the conflicting .meta file in a text editor
  2. Keep one version’s GUID — usually the teammate who made the first commit wins, since other assets may already reference that GUID
  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: tell teammates before adding new assets to shared folders. If two people add assets to Assets/Sprites/ in the same session, conflicts are almost guaranteed. 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 built-in YAML merge tool) for genuine scene conflicts
  • Enable it once in your Git config: git config --global merge.tool unityyamlmerge

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.

GitHub LFS limits

Free GitHub accounts include 1 GB of LFS storage and 1 GB/month bandwidth. For a student project this is usually sufficient. If you hit the limit, consider compressing audio/textures before committing, or using Unity Addressables to keep large assets out of the repository entirely.

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.

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.

Graph View

Backlinks