Who is this for?
I’ve specifically written this for anyone whose main role is not programming. If you interact with code and programmers a lot, but your primary focus is not programming and code, my goal is to get you started with the basics of Git without having to go too deep into the nitty gritty details. You can also read this if you are new to Github and/or are a programmer, but know that I’m not going to go way in-depth into Github internals (that can be its own separate doc).
What is Github?
Github is a platform for version control, which basically means you can save different versions of code – kind of like a Google docs version history!
Pretty much anyone who interacts with code uses some kind of version control, from a single individual (for example, I use my own personal Github to manage my personal projects) to massive teams at giant tech companies (the Google codebase is SO big that they use their own in-house version control system based off an old version of perforce – but the core concepts still remain the same). So Github is definitely a good tool to know if you’re going to interact with an environment that involves code!
Some Definitions
Where does code live?
To understand Github you need to understand where the code lives.
There is a remote repository, which is the place in the cloud (Github’s servers) that stores your code. It serves as your “main” or “master” repository, and we usually call that branch main. You might also see it named master in some places, which is outdated terminology, but they are effectively the same thing. You only merge your code into main when you feel that your changes are ready to be merged into the official version – so your code should be compiled and tested before you merge into main!
You make your actual code changes in your local repository, which lives somewhere on your computer. This is a clone or copy of the remote repository, so any changes you make to the local repository won’t affect the remote repository until you push and merge your changes. The local repository is your staging ground where you can make all of your code edits while you work on a new feature!
Important note for game dev about file sizes!
While version control works very well for text (it literally was built for code), it doesn’t work well with many other large file types such as images and sound files. This means that game dev often needs some special considerations when setting up version control.
Github lets you use something called Git LFS, which stands for Large File Storage. This allows Github to upload your large files into remote file storage, and the actual versions themselves are just text pointers that point to the remote file. This makes checking in changes waaaaayy faster and easier.
I highly recommend that the repo owner set this up if you use Github. It mostly involves installing Git LFS, and then creating a .gitattributes file to denote which file types get uploaded to the remote storage. However, do note that the cloud storage space may not be free and you might have to pay Github for that storage space.
Github vs git (vs Perforce)
Github is actually just a specific platform owned by Microsoft, which uses a version control scheme called git. Git is a style of distributed version control that involves being able to rapidly create many different branches of code. It is incredibly flexible – you can create branches of branches of branches, but also it can get pretty unmanageable pretty quickly. That’s why we tend to adhere to the standard where there’s one main branch that everyone merges their changes into, and that main branch serves as the “official” code version.
You may have heard of Perforce, which is another kind of version control system often used by larger companies. Perforce is a centralized version control system which strictly adheres to the “main branch” system in its core design. Every branch must branch out from main, and merge back into main, so there is less of a chance of an explosion of branches. Very large teams and companies tend to prefer this because it is better at avoiding crazy merge conflicts and make rollbacks slightly less cumbersome, which are a common occurance can get pretty gnarly in git. Don’t know what those are? Don’t worry, we’ll get to that later.
Getting Started with Github Desktop
Basic Workflow
A basic workflow for working with Github might look like this:
Make a copy (clone) of the remote repository onto your computer so that you can make local edits.
NOTE: This only needs to be done the first time you start working with a repository.
This is so that you can make changes in a separate place from main so that you don’t accidentally push your changes to main (it happens!)
Code code code: make your edits to your local files!
This lets you create a checkpoint of all of your edits as a new “version” on your local copy.
Push your commits to the remote repository once you’re happy with your changes.
Remember when we created the new branch? If you did that correctly before, this will push your changes to a different branch in the remote repository – it’s not in main quite yet!
This is not required if you’re the sole contributor to the repo, but it’s good practice. Many teams have some version of code review and use the PR system to handle that. Even if you’re not doing code reviews, it’s good to be able to see all of your change history formatted nicely on Github’s website!
Do steps 3-6 as often as you like.
If you’re working on the same branch and have already created a pull request, new commits/pushes will just go to the same PR and should reflect on the Github website when you push.
Merge your pull request into main when you / your team are happy with the changes!
Congratulations! You’ve made a code change!
For a deep dive into how to do each of these, hop down to the Workflow section.
Create a Github account
If you haven’t already, create an account on the github website.
Install Github Desktop
The first thing we need to do is install Github Desktop. You may have seen programmers open up a terminal to do all of their git handling, but I find that the Github Desktop is a much smoother introduction to using git.
Make sure you’re a repository collaborator
If you aren’t the person who created the Github repository, you likely need to be added as a collaborator. Ask your friendly neighborhood programmer to add you as a collaborator to the repository!
They can do that by going to the repository’s Settings > Collaborators tab and adding either your username or your email address that you used to set up your Github account.
Github Desktop UI Overview
Current repository: This section tells you which repository you’re working in. If you have cloned multiple repos, you can switch them here!
Current branch: This tells you which branch you’re on. Initially it should say “main” right after you clone the repository.
Fetch origin: This button syncs your local repository with the remote repository. The remote repository is often called the origin.
You want to sync often, and especially before you push your changes to the remote repository! Otherwise if your local repository isn’t up to date with the latest code, there may be merging issues later on.
Changes: This window will show all the files you’ve modified when you make changes.
Commit description: When you want to commit your changes to your local repository, you can do that here. Make sure to add a descriptive summary and description!
Information Window: If you have local changes, this will actually show the changes you made (called a diff). But since there’s no changes here, it shows these various options. After you push your changes, this window will also conveniently prompt you to create a pull request.
You can also click on the “History” tab to view the history of all commits that have been made to your branch! This is very convenient when troubleshooting git issues.
Workflow
Clone the Repository
First we will make a copy (clone) of a repository from the remote repo so that it lives locally on your machine! Github Desktop should know all of the repositories attached to your Github account, so in Github desktop, you can just go to File > Clone repository…
Select the repo you want to clone, and choose a folder on your computer for it to live. If you are already a repository collaborator, then you should be able to see your desired repo in this list. I like to create a directory named “Github” or “code” in my Documents folder where I put all my Github repos.
And that’s it! You should be able to open up the project and edit the files now!
You only need to do this once when you first set up your local repository. If you ever need or want to do this step again (for example, if your local repo got into a really bad state because you made some bad changes), you can just delete the local repo folder from your computer (in this example, I would delete C:\Users\cluu9\Documents\GitHub\CatTale-LD55) and redo this clone step to make a new clean copy of the remote repository.
Create a new branch
To make a new branch, first make sure that your current branch is main. You almost always want to branch from main, unless someone has told you otherwise (this often means they have some kind of release versioning scheme, or some other kind of branch management system that is specific to how they operate – ask them about it!).
Then, click on Fetch origin. You always want to make sure you are branching from the latest code.
Finally, to actually create the new branch, click the down arrow on the “Current branch” button and click Create new branch. Then give it a descriptive name. If you have made local edits already, it may ask you if you want to bring your changes to the new branch or leave them on main. Click Bring my changes to [NEW BRANCH].
I like to use the naming convention “MYNAME_FEATURE_NAME” so that I can differentiate my branch from other people’s branches. So if I’m adding level 1 sound effects in this change, I might name it something like “cris_level1_sfx”.
Commit local changes
Once you make some changes, Github desktop should automatically detect them. To commit your changes to the local repository, you can simply add a descriptive Summary and Description, and then click “commit to MY_BRANCH”
Push your commits to the remote repository
When you are ready to send your code to the remote repository on Github, you can click Publish Branch in Github Desktop. This will push your local commits to the remote repository, also known as origin.
Create a new Pull Request (PR)
Once you’ve published your branch, you’re ready to create your pull request! Click on the Preview Pull Request button to preview, and then hit Create pull request to create it! This will send you to the Github website to finish creating your Pull Request.
On Github’s website, you can add more to the description, and then click on Create pull request to finish making the PR. Once you do that, you should be able to preview your changes, send a link to the PR to your friends to review, etc.
Merge your changes into main
Once you are happy with all of your changes in your PR, you can finally merge your changes into main! On your PR there should be a button that says either Squash and merge or Merge pull request. Squash and merge is actually a setting that the Github repo owner can set. It basically takes all of the individual commits that you did for this PR and squashes them down into one so that the git history looks clean on main.
Congratulations! You’ve pushed a change! Once you’ve merged your changes, it should look something like this:
There should be a purple “Merged” indicator, and your remote branch will be deleted from Github’s history.
Note that only the remote branch is deleted, not your local one, so you should still see that local branch on your computer on github desktop. For clean code management though, I recommend deleting your local branch when you are done pushing a change into main, and creating a new branch every time you want to make new changes.
Troubleshooting
TODO
Comments