Connect a Unity project to GitHub Desktop

In this tutorial, you’ll download a sample Unity project, explore its folder structure, and set it up with GitHub version control. By the end, you’ll have a properly configured local repository and an understanding of how to commit, push, and optionally collaborate with others.

Before setting up version control, you'll explore a sample Unity project. This step also familiarizes you with a well-structured project, which is important for efficient collaboration.

Instructions

1. Download and unzip the sample Unity project folder

• Download this sample Unity project folder.
• Unzip the folder in a convenient location on your computer.

2. Add the project to the Unity Hub

• Open the Unity Hub.
• Select Add > Add project from disk.
• Go to the folder you just extracted and select Open to add it to the Unity Hub.

Note: The project folder must be unzipped for Unity Hub to add it successfully. The actual Unity project folder is the one containing the Assets/, Packages/, and ProjectSettings/ folders.

3. Open and explore the project

• In the project list, select the project to open it in the Unity Editor.
• Open the Main Scene from the Assets > Scenes folder.
• Take a moment to explore the scene. You'll see two capsules: one named Player, and one named BossCharacter — but no functionality is implemented yet.
• Observe the folder structure in the Project window. A clean and logical structure, such as Art, Audio, Scripts, Prefabs, Scenes, UI, and ThirdParty, supports collaboration and reduces merge conflicts by making it easier to locate files, understand project organization, and minimize overlapping changes in the same areas.

4. Close the Unity Editor

• Close the Unity Editor before moving to the next step.

Git only tracks files that are inside its repository folder. To enable version control for your Unity project, you'll now move all its files and folders into the Git repository folder you created in the previous tutorial. This action will allow GitHub Desktop to detect and track all project asset changes.

Instructions

1. Locate your Git repository and Unity project folders

• In GitHub Desktop, select Repository > Show in Explorer (macOS: Repository > Show in Finder) to open your Git repository folder.
• Navigate to your Unity project folder. If you can’t remember where you created it, open the Unity Hub, select the More () menu next to the project name, then select Show in Explorer (Windows) (macOS: Show in Finder).

2. Move Unity project files into the repository folder

• Select and cut or copy all the files and folders inside the Unity project folder.
• Paste your Unity project files into the Git repository folder.

3. Return to GitHub Desktop

• You should now see a list of files under the Changes tab. Since you selected the Unity .gitignore template when creating the repository, the number of tracked changes is already manageable; you should see a reasonable count, such as 67 changed files. This is because Git is already ignoring unnecessary files specific to Unity (like Library/ and Temp/).

Note: The next section demonstrates exactly how the .gitignore file achieves this cleanup by showing the effect of removing it.

4. Delete the original Unity project folder

• Now that you have your Unity project files safely in the repo folder, you can safely delete the Unity project folder to avoid confusion.

Unity generates many files specific to your local computer (like cache files or temporary data). A .gitignore file tells Git to skip these files and keep your repository clean and lightweight, ensuring only essential project files are tracked. Because you selected the Unity template earlier, this file is already active, keeping your repository fast. This step demonstrates what happens when that file is missing.

Instructions

1. Temporarily remove the .gitignore file

• Using your file explorer (Finder/Explorer), navigate to the root of your local repository folder.
• Locate the hidden .gitignore file. On macOS, you may need to press Cmd + Shift + . (period) to toggle the visibility of hidden files.
• Drag the .gitignore file out of the repository root folder onto your Desktop (or another temporary location).

2. Observe the resulting file count change

• Return to GitHub Desktop.
• Git immediately begins tracking all the files that were previously ignored. You should now see the number of tracked changes skyrocket, potentially showing more than 32,000 files. This massive number of files is too much to upload and would make managing the project difficult and slow.

3. Restore the .gitignore file

• Move the .gitignore file back into the root folder of your repository.

4. Confirm cleanup in GitHub Desktop

• Return to GitHub Desktop. The list of tracked files should immediately reduce back down to the manageable number (e.g., 67 changed files or something similar).
• The .gitignore file makes files like the Library/, Temp/, and .vs/ invisible to Git, preventing them from being committed, pushed, or causing conflicts, keeping your repository clean and focused.

A commit records a snapshot of your project at a specific point in time. It’s essentially your first official save into Git, marking the initial state of your project under version control. This step saves all the files you’ve moved into your repository and configured with the .gitignore file.

Instructions

1. Go to the Changes tab in GitHub Desktop

• In GitHub Desktop, select the Changes tab.

2. Enter a commit summary

• In the Summary box, enter “Initial commit”. This message clearly indicates that this is the very first save of your project into version control.
• Add a short description for more context, for example, “Set up project files with .gitignore and basic Unity structure”.

3. Commit the changes

• Select Commit x files to main.

Note: The main branch is the primary, default branch in your Git repository. It’s typically where the stable and production-ready version of your project resides. Right now, these changes are recorded only in your local repository on the main branch.

4. Publish your repository

• Select Publish repository (or Publish branch) to upload your files to the online repository on GitHub.com.
• You can add a Description to your repository, and enable Keep this code private if you don’t want other users to see your repository. You can change these configurations later.
• Select Publish repository.

5. View your files online

• To see your files online, go to Repository > View on GitHub.
• Once on GitHub.com, explore your repository:
  • Browse the Code tab to see your Assets/ folder and other project files.
  • Select individual files or folders to view their contents.
  • Select the Commits tab to see your Initial commit listed, which represents the first snapshot of your project.

Your first commit is now created, and your project files are tracked by Git both locally and on GitHub.com.

Now that your project is under version control, you'll make a simple change to the project and observe how Git tracks these updates. This demonstrates the core process of saving and synchronizing your work as you develop.

Instructions

1. Create a new script in Unity

• Open the Unity Hub and add the tutorial-repo project.
• In the Unity Editor, go to the Project window.
• Right-click and select Create > Monobehaviour Script.
• Name the new script “MyScript”.

2. Observe changes in GitHub Desktop

• Open GitHub Desktop.
• The Changes tab will show that you have a new file added since your last commit.

3. Commit your changes

• In the Summary box, enter “Added new script”.
• Select Commit to main.

4. Push your changes to GitHub

• Select Push origin to upload your changes to GitHub.com.

Note: Commit saves changes to your local repository, which solely lives on your current machine. Push sends those changes to GitHub.com so that you or other team members can later access the project's history and files.

Commit often and push when you’ve completed a working task or feature. Commit after completing small, meaningful tasks (for example, implementing a new feature or fixing a bug). Push your commits as soon as they’re tested or reviewed. Avoid waiting until the end of a game jam or project, as this increases the risk of merge conflicts.

Once your project is pushed to GitHub, you can invite others to work on it. This step explains how to add collaborators to your repository, allowing them to contribute to the project. Even if you don’t plan on inviting someone now, you should follow these steps to understand the process for future collaborations.

Instructions

1. Navigate to collaborators settings

• From your repository on Github.com, select the Settings tab in the top menu.
• In the left menu, select Collaborators (or Manage access).

2. Invite a collaborator

• Select Add people.
• Enter your teammate’s GitHub username or email.
• Select their profile from the dropdown and select Add.

In this tutorial, you learned how to put a Unity project in a Github repository, configure a .gitignore file, and perform your first commits and pushes. You now have a foundational understanding of how to manage your Unity project with version control.

In the next tutorial, you’ll learn how to configure Git Large File Storage (Git LFS) to efficiently handle large assets often found in Unity projects, ensuring your repository remains lightweight and performant.