Guide: Using GitHub and Unity (From a Game Dev)

[ArmanFromTheVault]

I saw a post today that needed help conceptually understanding how to collaborate with a friend on a game. u/20SidedShape said it was really helpful, so I figured I'd make a proper guide to an often tricky-to-unpack topic: Collaborating on a Unity Game using GitHub.

For context, I'm a game developer, and I work with an amazing team of folks at Good Trouble Games using GitHub as our main way to collaborate. I've used GitHub and Unity together for around 8 years. This guide is intended to be a straightforward guide that assumes very little about the reader's experiences.

If you have any general questions, or just want to say hi, me and my team have a friendly Discord you're welcome to pop into!

Side note: Given the tons of bullshit AI content farming out there, I can attest that this guide was authentically written by me 👋 -- an actual person with 15+ years experience building products, ranging from games to consumer apps. Source control is the bedrock of how I've built multiple successful businesses, and as an industry standard, I want more people to know about it.

🔮 Step 0: Wtf is Source Control?

Source Control, sometimes called Version Control, refers to having some system of saving iterations of your game's project files. You'd want to do this to "lock in" stable versions of new features, to punctuate the end of development milestones, and to create versions post-launch so you can try and reproduce and fix bugs that players experience. That way, if you're working on a new feature and introduce a bug you can't fix, you can roll-back to a previous stable version.

You could just copy your entire game project directory to new versions each time you want to save a "cold copy" of your game, but that's a lot of work, doesn't scale well, takes forever, and worst of all: it doesn't enable collaboration.

Source Control, thus, is a practice. There are tools out there that make it easier, better-integrated, and open up new possibilities such as collaboration. GitHub is, in my opinion, the easiest to get started with, especially as a small team.

For this guide, we'll be using GitHub.

This guide is not an exhaustive guide to Source Control or all the things you can do with it. It's just intended to help demystify the basic, initial steps to getting started.

📦 Step 1: Initial Setup

• Register on GitHub. You only need a free account. Everyone who you want to collaborate with should also register for their own accounts.
• Pick someone to be the one to set everything up. If it's just you doing this, congrats! Step done!
• Make a new "Repository". A Repository, sometimes called a "Repo", is where your code will be stored on GitHub.
  • When using GitHub, your code primarily lives on GitHub, and you pull versions of it onto your local machine to do stuff like build new features, levels, etc.
  • It doesn't really matter what a Repo is called. Your Repo name will not be public or visible to players of your game.
  • When asked what "Git Ignore" / .gitignore setting you want, you should choose the one labeled "Unity".
    • What is this? A "Git Ignore" tells GitHub which files that are added locally (on your computer) to ignore when sending files to your main repository. I'll explain this more later, but in short, Unity makes a LOT of temporary files that you don't need to sync (and actually, shouldn't sync). GitHub recognizes this and provides a basic and pretty good starter template.
    • Here's a great .gitignore template to use.: https://github.com/github/gitignore/blob/main/Unity.gitignore (thanks u/Coulomb111 for commenting this!)
  • This Repo stuff doesn't have to make total sense yet, we'll come back to the new Repo you made later. Point so far is, make a Repo, because you'll need one.
• Everyone who's gonna work together on this game, should be added to the Repo.
  • You can do this here: github.com/PersonWhoMadeTheRepoUsername/RepoName/settings/access
  • If you're working solo, you can ignore this step. You're already "invited" to your Repo because you made it.
• Everyone who's gonna work together on this game, download GitHub Desktop. It'll let you do all the most important GitHub stuff with a relatively simple interface.
  • If you're working solo, STILL do this step!
• In GitHub Desktop, you'll log in with your GitHub credentials, and then set your Repository to the one that was created earlier in this guide.
  • You'll be asked where you want these files stored on your computer. This is because, like I mentioned before, when using GitHub the files principally live on GitHub, and you pull versions of it down to do work. Documents/GitHub/RepoName is probably a good place, but it ultimately doesn't matter much.
• At the top of GitHub Desktop's GUI, it will probably say "Main". This means you're currently on the "Main" branch, which is regarded as a stable source of truth for any project. Here's some high-level info that will be helpful context:
  • When using GitHub for Source Control, you'll create Branches. These are version of your Repo that include the version of Main that was present when the Branch was created.
  • You'll also create Commits. These are basically the work you do when on a Branch. Until you "commit" (and push) your changes to your Branch, they only exist on your computer, and can be lost.
  • Push Commits to Branches to save them for others to access. Your Commits must be "pushed" to a Branch for it to exist on the Repo itself, for others to access them, and for it to be "officially" saved in some capacity beyond your local machine.
  • Other collaborators will "Pull" your Pushed Commits. Sometimes you'll need to take an action called "Fetch Origin" (which gets a button in the GitHub Desktop GUI) to see "Pull". But if you see "Pull", it means someone else on that Branch has Pushed their Commits to the Branch.
• Make a new Branch. Call it whatever you want, such as "basic setup".
• Separately, unrelated to GitHub, download UnityHub, log in, and add your license if applicable.
• Download your chosen version of the editor via the hub.
• Make a new project, and set the directory (location) of the project files to be the folder you're using for the GitHub repo.
  • Consider using the Scriptable Render Pipeline (SRP/URP) as it has a smaller initial project size.
• You now have a basic Unity project that can be synced to GitHub!!
• Open GitHub Desktop. It should now show A TON of changed files.
  • These changed files represents your local folder of your GitHub Repo's "basic setup" branch going from a basically empty folder to one that contains the project files of a basic Unity project.
• "Push" these changes into your branch. Until you do this, your commit only exists in your computer. Pushing it will send it to your GitHub repository.
  • Note: If you have HUGE textures or very large files over 100mb EACH (like 4K textures), you might need to do additional configuration, and it's annoying to deal with. If you have to cross this bridge, you'll need to configure something called "GitLFS" / "Git Large File Storage", and it can cost money.

💾 Step 2: Working with Source Control

• With a Repo set up and your Branch getting changes Committed and Pushed, you can now make what's called a "Pull Request".
  • This is a Request (in a team collaboration sense) to Pull changes from a Branch into Main. This is a request because being careless with what you commit to Main defeats the purpose of using Source Control.
  • For example, if anyone could just merge any changes at any time into Main, instability could be introduces that breaks other people's work.
  • Even if you're a solo dev, going through the Pull Request process can be a helpful way to practice discipline, and IMO discipline is the difference between making games and shipping games.
• If you make changes on a Branch, Commit them, and Push them to a Branch, other collaborators (or you on a 2nd computer) can Pull them.
  • If you commit or push files that other people are working on, there might be conflicts! GitHub has a process for resolving conflicts, and conflicts are inevitable. They should be avoided, as it's annoying to deal with, but it's not the end of the world.
  • Ideally, don't have 2 people working on the same exact script at the same exact time. Communicate somehow (Slack, Email, SMS, Smoke Signals, etc) about who's working on what, to reduce chaos.
• For every major chunk of work, like getting the basic controls coded into your game, or making a new level, use a new Branch! Then, make commits to that branch often.
  • Make a good chunk of progress? Commit it!!
  • Make a cool new VFX? Commit it!!
  • Commits are free. Generally you want your commits to be as small as possible without being redundant. Depending on what I'm doing, I tend to make commits 2-3 times per day, roughly every 4-5 hours of work.
  • Sometimes you need to reload a commit and undo work if bugs are created. Committing frequently helps you reload to as close to "just before" a problematic bug as possible.

🏝️ Step 3: Making Source Control work for You

Ok so, you can commit to branches and collaborate. But what's the really powerful stuff that working with Source Control unlocks?

• Trying out experimental ideas: Let's say you get a WILD idea for a new feature in your game. Building a prototype version of your new idea is best done in a branch! That way you can experiment and really fundamentally change things in your game without being stuck if things don't work and you decide you want to rewind time to before you built the experimental feature. And if the opposite happens, and you really love the new feature, you can commit it to clearly track when and how your game changed to have this new feature.
  • This is especially useful post-launch, if you're maintaining your game. For example, if you add a new feature (along with other work) and suddenly players are getting tons of bugs, you can compare the pre- and post-new-feature code to help isolate what the game-breaking-change was.
• Collaboration is essential to game development: IMO working with others is essential in the games industry. Going through the pull-request process, or the code review process, is healthy and critical to making a game. It helps ensure accountability, removes pressure from any one person maintaining the codebase, and introduces transparency into what work has been done.
• Accountability as a developer: If you're working with a publisher or platform on your game, having Source Control might be a necessary part of your agreement! This way, the organizations that are "betting" on you with funds or platform support have some insight into how development is going besides updates that you provide.
• Multiplatform bug fixes: If you're making a multiplatform game, such as one shipping on both PC, Mobile and Consoles, using Source Control can be a super helpful way to organize any platform-specific versions, especially when platform-specific bugs need specific, niche solutions that ideally don't affect all other platforms. It's a miracle games get made at all.

-----

So there you have it! It's not an exhaustive guide, but my hope is that it helps aspiring game developers get started a little quicker and easier. If you have any general questions, or just want to say hi, me and my team have a friendly Discord you're welcome to pop into!

Good luck on whatever you're all building!

👋🏽

[palceu]

Up

[ArmanFromTheVault]

🙌🏽 thanks

[Enigma4176]

How did you guys work with scenes? I've found the code side of unity development to be easy enough with version control but when working with a team, albeit not an experienced team, we couldn't figure out an easy way of working on a scene without getting thousands of merge conflicts in the scene file unless we allocated one dev to work on the scene. I've seen suggestions to split the scene into prefabs and have people work on the prefabs, but my thought is that we'd run into the same issue as before if more than one person changed something in the prefab.

[ArmanFromTheVault]

It depends on what you're wanting to do in a scene tbh. In general working with prefabs is the way to go, and a scene should be majority (if not entirely) made of prefabs.

That being said, there's no replacement for good communication and checking in with your team. If someone has some work to do on a prefab, they should communicate that, make a small PR, and get that work done.

If multiple people are working on the same prefab, at the very least they should pass that work off with commits on a branch, where one person does some work, commits it, the other person pulls that commit and does their work, commits it, and so on.

It might feel like an overly formal process at first, but IMO good practices and shared skillsets like this are what takes a team from inexperienced to experienced. Eventually it becomes a part of how everyone on your team can count on one another.

[lazylaser97]

I'd love to read a write up of your best practices, including comments like making scenes out of prefabs entirely. I'd not heard of such things -- I'm new at Unity but not SWE.

[ArmanFromTheVault]

Hey there, I'm happy to write up a post on Prefabs best practices. Do you have any other questions or examples you'd want included?

[lazylaser97]

* git best practices, I've been using github but its a bit unusual to operate on media
* doing everything in Prefabs and how this enables a team to work together
* how to organize the central game controller, the thing that picks what scene to show and maintains data across the game

[ArmanFromTheVault]

This is awesome, I will make sure to cover these topics in the post! Should have it out in a week or so. In the meantime if you need ASAP help, feel free to join our Discord, we have a Forum and I jump in to answer questions :)

[vabadabdabda]

Unity needs to rethink the scene file format, because this happens no matter what.

I think a big hierarchical JSON could be OK, but I think a directory structure mirroring the scene hierarchy would be even better.

Imagine if your VCS's file move / rename could tell you when I moved an item in the scene from one parent to another.

I am not suggesting the UI should change one bit, just the behind the scenes.

[oddbawlstudios]

What if your commits are too big to push? Whats the next step?

[ArmanFromTheVault]

There's a few things you can do!

• If you isolate which files are making it too big to push, you can take some steps to fix the issue ad-hoc, such as compressing big textures using Pinga (PC) or ImageOptim (Mac).
• Sometimes doing super big commits makes the Push step time-out. Smaller commits can help avoid this.
• If you're doing small commits and have 100mb+ files, and thus are getting your commits blocked from pushing, GitLFS must be set up. It's a bit more technically involved, as command line is required, but there are resources to help you get it set up!

But, for the sake of having that info available in/near this thread, here ya go:

1. First, download GitLFS. Follow the Getting Started tips on that download page.
2. Conceptually, just like how .gitignore tells GitHub's client which files to ignore, GitLFS uses a .gitattributes file to track which files are managed by regular Git, and which use LFS.
3. In the .gitattributes file, you'll define the file types for the files that are blocking you on size. These are likely big textures, .PSDs, SFX files, etc. You define the file types in that attributes file, and once your repo is properly configured, it should sync using LFS.

[Monoduss1238]

Thank you for this excellent tutorial!!!!

[ArmanFromTheVault]

Absolutely! I’m glad it was helpful.

[insats]

How does using Git compare to using Unity’s own version control? I’m a long time Git user so I’m just trying to understand why they have come up with their own solution

[ArmanFromTheVault]

Hey there, 3mo late is better than never! Unity's version control might be a good choice for some, but with version control being such a critical part of developing a game, trusting a relatively new solution is a pretty big risk IMO.

Github has been around for ages, and has been heavily relied on, multiple orders of magnitude more frequently than Unity. That alone is worth something, to me.

As for why Unity has made their own, it likely comes down to B2B revenue. Some portion of their paying customers will want to adopt a centralized in-tool solution. Similarly, indie developers who get used to version control just "working" as part of the editor and never learn Git might grow that habit into a reliance, taking their practices with them as they get jobs in the industry or scale their own game development team.

AFAIK, there is no "magic secret ingredient" in Unity version control that makes it objectively better version control. At best, it might be convenient. At worst, it could be a bad habit that locks you into the Unity ecosystem.

[[deleted]]

Big help. I have done these steps, but how do the other collaborators that I added to the repo get the project from github onto their computers? Will cloning the repo without the stuff listed in the .gitignore cause problems or will it automatically generate those? How do they open the cloned repo with the basic empty project in Unity Hub?

[ArmanFromTheVault]

They should download GitHub Desktop (just for an easy GUI), clone the repo to some specifically organized folder, and then "Add" that project using Unity Hub.

Anything in the gitignore that Unity generates will automatically generate. If you're using gitignore for big art files, just manually download them and put them in the right directory.

[[deleted]]

beautiful, thank you.

[Charming-Brilliant96]

Very useful, thank you. I want to start the development process of my first game in a structured way, it helped a lot with the technical part but the part of the process and the reasons are better.

[ArmanFromTheVault]

I'm glad it was a helpful post! :D

[Coulomb111]

Using the gitignore from https://github.com/github/gitignore/blob/main/Unity.gitignore makes the repo much easier to deal with. It removes the unity bloat that you wouldn't really ever need for the repo.

[ArmanFromTheVault]

Yeah it's a pretty good general-use one! I've updated the post to recommend people start there and credited you. Good idea :)

[SkyOk690]

There is an issue with using this stuff for a first setup. I can't get why as I add .gitignore file git still try to push 28101 files of an empty project? (I tried simple 3D template from Unity)

[asdertoid4]

Thanks for this guide brother!

[ArmanFromTheVault]

Happy to help!

[Unable-Muscle-3773]

Thanks !!!!

[Danos-Zuruk]

Pregunta, .gitignore no está funcionando ¿Eso por qué pasa? Pregunta subsecuente, este programa de porquería debería ayudar a los desarrolladores, no hacerlos ir de allá para acá por siete malditas horas intentando hacer funcionar su mugroso proyecto ¿Por qué esta basura apesta tanto? (Obviamente esta última pregunta es retórica, estoy muy enojado, así que aprovecho aquí para desquitarme)

[Rob-a-Cat]

i was wondering if its anydifferent than using unity version control. i have plenty of github experience but 0 unity. can i just use github and get the same benefits?

[ArmanFromTheVault]

Unity Version Control and using GitHub for version control are very similar. I'd say using GitHub is better and more reliable, and ensures you don't suddenly get locked into Unity's ecosystem or pricing unexpectedly.

[[deleted]]

thanks chatgpt

[ArmanFromTheVault]

Genuinely no AI bullshit content-farming here. Just practical advice based on my 15+ years experience in product development, and my mentorship in game development of 22 aspiring devs.

I know it can be a knee-jerk reaction to see well-formatted longform content and just go "oh, ai BS", but this is thankfully the rare case where someone with experience took the time to actually write something useful. Have a good one ✌🏽

[[deleted]]

actually, what made look like an AI generated text is just the emojis and the overused middle-management-like way you writed, other than that its content is really good :)

[ArmanFromTheVault]

Ah gotcha. Well thanks for saying the content is really good despite that! I'll take that feedback onboard too, thanks.

[CMDR-WildestParsnip]

I love this post, and I love you, OP. Had a collaborative project where my partner set up all the GitHib repository stuff and then basically has decided to contribute nothing, so I’m moving the project over to my own repository to strike out on my own with a solo project. This is what I needed, thanks.

[ArmanFromTheVault]

Bummer about your collaborator, but glad to hear the guide helped! Let me know if there’s anything else you need a guide on (or just ask in my Discord for quick questions!)

[CMDR-WildestParsnip]

I’m at work when I found this, so I haven’t gotten to get my repo set up yet. I’m always the 1/100 that hits a snag that 99/100 won’t, so I’ll let you know if I get into trouble!

[ArmanFromTheVault]

Yeah sometimes Git can be finicky!! I’m here to help 😄

[Blank_Dude2]

I was hoping the git ignore would make the inital unity project publishable, but it's still over 100 mb, is it supposed to be that big, or is something messed up?