Summary
The daily Git workflow follows a short loop: edit files, check what has changed, stage the changes you want to keep, commit the snapshot with a message. Most Git work uses the same handful of commands. This page covers everything needed to work confidently with Git on a Unity project — from first-time setup through pushing work to GitHub.
For an understanding of why these commands work the way they do, see git-concepts first.
First-time setup
Before making any commits, tell Git who you are. This information is attached to every commit you make.
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global init.defaultBranch mainRun these once on each computer you use. The --global flag saves them to your user account rather than just the current project.
Starting a project
Create a new repository from scratch
# Navigate to your Unity project folder first
git initThis creates the .git/ directory. The project is now a Git repository but has no commits yet.
Clone an existing repository from GitHub
git clone https://github.com/username/project-nameThis downloads the entire repository including all history, creates a folder named project-name, and sets up origin as the remote pointing to GitHub. Use this when joining a project that already exists on GitHub.
The core loop
1. Check status
git statusShows which files are modified, which are staged, and which are untracked. Run this constantly — it is the safest way to know exactly what Git sees before staging or committing.
2. Stage changes
git add filename.cs # stage one file
git add Assets/Scripts/ # stage all files in a folder
git add . # stage all changes in the current directorygit add moves files from the working tree to the staging area. You are not committing yet — you are choosing what to include in the next commit. This lets you make many changes and commit them in logical groups.
3. Commit
git commit -m "Add player jump with variable height"Creates a snapshot of everything currently staged, with your message attached. The message should describe what the commit does and why, not just “update files”.
Good commit messages:
Fix player falling through thin platforms at high speedAdd enemy patrol AI with detection radiusRefactor GameManager to use singleton pattern
Combine add and commit for already-tracked files:
git commit -a -m "Tweak enemy detection radius"The -a flag stages all modified tracked files automatically. Note: it does not stage brand-new untracked files.
4. Check what has changed
git diff # changes in working tree not yet staged
git diff --staged # changes staged but not yet committedShows the exact line-by-line differences. Useful for reviewing your work before committing.
Viewing history
git log # full history with author, date, message
git log --oneline # compact one-line-per-commit view
git log --oneline --graph # visual branch history
git log -5 # last 5 commits onlyThe Unity .gitignore
Unity generates large folders of compiled and cached files that must never be committed. Create a .gitignore file in the root of your Unity project containing:
# Unity auto-generated folders (never commit these)
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Ll]ogs/
[Mm]emoryCaptures/
[Aa]ssetStoreTools*
# Build folders
[Bb]uild/
[Bb]uilds/
# IDE files
.vs/
*.csproj
*.sln
*.userprefs
*.suo
UserSettings/
# OS files
.DS_Store
Thumbs.db
What to track (do NOT add these to .gitignore):
Assets/— all your game content and scriptsProjectSettings/— project configurationPackages/— Unity Package Manager manifest
Create this file before your first commit. If you accidentally committed Library/ already, see “Fixing mistakes” below.
.gitignore syntax
# Comment
*.log # ignore all .log files
[Ll]ibrary/ # ignore Library/ or library/ (Unity sometimes varies case)
!important.log # exception: do track this specific file
/TODO # only ignore TODO in the root folder, not subfolders
Build/ # ignore any folder named Build
Renaming and deleting files
git rm OldScript.cs # remove file from disk and from tracking
git rm --cached OldScript.cs # stop tracking but keep file on disk
git mv OldName.cs NewName.cs # rename (stages the rename automatically)Use git mv for renames rather than just renaming in the file explorer — it keeps the history connected.
Undoing mistakes
Amend the last commit (before pushing)
git commit --amend -m "Corrected commit message"Replaces the last commit entirely. Only use this before pushing — never amend commits that have been shared with others.
Unstage a file (keep your changes)
git restore --staged PlayerMovement.csRemoves the file from staging but leaves your edits in the working tree.
Discard working tree changes (permanent)
git restore PlayerMovement.csDangerous — discards all unsaved changes to this file and restores it to the last committed state. There is no undo.
Working with remotes (GitHub)
git remote -v # list configured remotes
git remote add origin <url> # connect repo to GitHub for the first time
git push origin main # upload commits to GitHub
git pull # download and merge latest from GitHub
git fetch # download latest without merginggit fetch downloads changes from GitHub without touching your working files, letting you review what is new before merging. git pull is fetch + merge in one step.
Typical daily sync with a team
git pull # get teammates' latest work first
# ... edit files ...
git add .
git commit -m "Add powerup collection logic"
git push origin main # share your workCommon situations
| Situation | Command |
|---|---|
| ”What have I changed?” | git status |
| ”Show me exact line changes” | git diff |
| ”Save my current work” | git add . && git commit -m "message" |
| ”Upload to GitHub” | git push origin main |
| ”Get teammates’ latest” | git pull |
| ”See commit history” | git log --oneline |
| ”I staged the wrong file” | git restore --staged <file> |
| ”Throw away my edits” | git restore <file> |
Related
- git-concepts — how Git stores data; the three states model
- git-branching — working on features without breaking the main project
- git-github-unity — setting up and using GitHub with Unity
- source-progit