The main reasons to add version control to your workflow are:
- Having your project in a remote repository (like GitHub, GitLab, or Bitbucket) ensures you don’t lose your work if something happens to your computer.
- Git allows you to track changes in your project, revert to previous versions if something goes wrong, and understand what changes were made and when.
- If you work in a team, Git makes it easier for multiple people to work on the same project without conflicts, using branches and merges.
- You can use branches to experiment with new features or fixes without affecting the main version, keeping the project organized.
- Many CI/CD platforms and development tools integrate with Git, streamlining workflows like automated testing or deployments.
- Using Git is an industry standard, and mastering it prepares you for professional environments.
However, you shouldn’t upload all your files to a Git repository. For example, it makes no sense to upload compiled files because anyone can generate them from the source code. Uploading compiled files only unnecessarily increases the repository’s size, making it more expensive to maintain and slowing down synchronization for the rest of the development team.
For Unity projects, ensure you include an appropriate .gitignore file to avoid uploading unnecessary files. Git expects this file at the project’s root (at the same level as the Assets folder). Its content lists the file and folder names that Git should ignore to keep the repository clean. On the internet, you can find plenty of examples of .gitignore files suitable for Unity. If you use Rider, JetBrains has an official plugin (called .ignore) that provides a wizard to generate a .gitignore tailored to your project (including Unity). Another source is GitHub, which has an official repository with .gitignore files for the most popular development frameworks, including Unity.
What to Leave Out of the Repository
If you choose to create a .gitignore file from scratch, you should exclude the following:
- Unity-related folders: Exclude Library, Temp, Obj, Build, Logs, and UserSettings, as they are automatically generated by Unity and should not be versioned.
- Build files: Files like .csproj, .sln, and others generated by Visual Studio or Rider are not needed in the repository.
- Cache and assets: Exclude Addressables cache, StreamingAssets, and packages to reduce the repository size.
- Operating system files: Ignore .DS_Store (macOS) and Thumbs.db (Windows).
- Editors and tools: Exclude editor-specific configurations like VS Code or Rider, but allow shareable configurations (e.g., .vscode/settings.json).
- Large files: If you don’t use Git LFS, exclude .unitypackage, compressed or heavy files like .zip.
What to Include in the Repository Files
With the above excluded, your repository should only contain the following folders:
- Assets
- Packages
- ProjectSettings
The most critical folder is Assets, as it contains all the project’s code, as well as models, textures, music, sounds, and all the elements that make up your project.
The Eternal Question: What Do I Do with .meta Files?
When you browse the Assets folder using a file explorer, you’ll notice that each item has an associated .meta file, In the .meta, files. Since .metadata Unity automatically generates these .meta files, many people wonder whether they should be included in the repository.
Unity associates a .meta file with each asset included in the project. These .meta files store the import parameters for each asset. This is especially important for assets like textures or sounds, as failing to include .meta files in version control could lead to other developers importing the same assets with different settings, which can cause issues.
Since Unity generates them automatically if they’re missing, it’s critical to emphasize to the entire development team that when creating a new asset, they must include both the asset and its corresponding .meta file in the repository. If someone forgets to include the .meta file for a newly created asset, the next developer who clones the repository will have Unity automatically generate a .meta file for it (when Unity notices it’s missing), which can lead to merge conflicts, as different .meta files (one per developer) might exist for the same asset. This is an ugly situation that often sparks recurring questions on Reddit.
Moral of the story: Never forget to include .meta files in your version control repository
Conclusion
With the above, you now have the basics to check if your repository is missing anything critical. Operating a Git repository is another matter entirely and has plenty of nuance. Using Git is easy, but using it effectively without messing things up takes a lot more effort.
If you want to dive deeper into this topic, I dedicate Chapter 15 of my book, "Reconstruction of a Legendary Game with Unity", to it.
