My Practices:
- Create the repo first, then begin the project. It's just easier for me.
- Use a free online service provider, for offsite backups and to quickly move between machines.
- Use git-lfs. It's not really necessary with small GB Studio projects, but it's a good habit to get into.
- Make frequent, small commits. Typically this means, every time I change an asset and/or add/alter some code, I immediately stage and commit; this makes it much easier if I need to step backwards later to figure out when I broke something, and also means I don't have to remember what I just did for very long.
- Push occasionally, after a significant amount of work is done, usually about once every 30 to 60 minutes. This means it's easier to back out and remove commits in the rare case when I decide I shouldn't have done something in the first place.
- In general semantic versioning is sensible but it may be too fine-grained for most GB Studio projects. I tend not to assign version numbers at all until I'm sharing the game with testers, when I begin at 0.1-beta. When I release, that's 1.0 and every subsequent release gets a tag.
- Keep the following simple
.gitattributeand.gitignorefiles.
File contents
.gitattribute
⌗ GitHub Language Detection design/* linguist-documentation⌗ Normalize Line Endings to LineFeed
*.md text=auto
*.text text=auto
*.txt text=auto
LICENSE text=auto
⌗ LFS
*.mod filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.sav filter=lfs diff=lfs merge=lfs -text
*.uge filter=lfs diff=lfs merge=lfs -text
*.vgm filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
.gitignore
[Bb]uild
*.bak
~*I think that frequent, small commits are the most important of these. Here's an example of my commit history:
Confused? Read on for a brief intro & tutorial!
Feedback welcome!
What's the Idea?
First, why use version control as a GB Studio developer?
- You get backups of your files in case something is corrupted or deleted
- You get a history of your changes, which makes debugging much easier
- It's much easier to collaborate with others on a shared project
But then, why use git specifically?
Honestly, I don't love git and it wasn't designed with game development in mind. However, it's the de facto industry standard, which means nearly everyone is familiar with it already. So it's easier to get help when you need it!
What about it being not made for game dev?
The problem with git and other version control systems like it is that they are designed to work only with text. Games contain a lot of text, both prose and code, but they also contain a lot of images, sounds, and sometimes movies.
As a GB Studio developer, you're not actually likely to run into the pain points that developers at AAA studios are likely to hit. However, it's still worth setting up git plugins that will help alleviate these issues. I'll go over that below.
Requirements
If you've never used git before, you'll need to download and install it. It's free!
If you're comfortable with the command line, then you may want to work with git directly from there. This is how git is designed to work.
I find command line git especially viable if you're developing on Linux or Mac. On Windows, I find it easier to use a graphical user interface.
I also think there is a strong argument for using a git GUI for game dev on any operating system as a good GUI will visualize graphical files for you, but many people disagree with me on that.
Currently, I use Fork as my git GUI, which is paid trialware. Here are the most popular free options:
There are many others, paid and free.
Once you have installed Git (and a GUI if you want one) you'll probably want to set up an account with a free git service provider. These are some of the most common; they all have pros and cons:
There are many others.
I use GitHub for the same reason I use git: it's not necessarily the best, but it is the industry standard.
You can skip a remote service provider and run everything yourself; it's not too hard, but IMO it's trickier for a first-timer. Also, there are two other reasons to consider using a remote provider:
1, your files are backed up off-site
2, it's easier to share your projects with others, if you want to
Okay! With all that out of the way, let's talk about how to actually use git with GB Studio.
Creating the Repository
When I start a brand new project, I like to begin by creating the project's git repository ("repo" for short) on GitHub itself. This is backwards from what most git tutorials will tell you to do, but for me it's easier.
Here's how that looks on GitHub:
I usually pick a simple code name for my project to start with since it's easy to change later, once I have a better understanding of my game.
I also typically work with my repository set to private until I reach 1.0, when I make it public. You don't need to ever make your project public; alternatively, you can make it public from day 1.
If you know you are going to want to release your project publicly, it's worth thinking now about what license you want to release it under. GitHub has this tool to help with that, and Creative Commons offers this tool.
If you don't select a license, then legally people aren't allowed to do anything with the files. However, if the repo is public, they probably will anyway.
Downloading the Repository
Once the repo exists you can download it to your local machine. This is called cloning.
First, you will need to enter the folder where you plan to keep your repository. Each OS has a default area for this, but really you can do it just about anywhere.
From the command line, you would enter something like:
git clone https://YOUR-SERVICE-PROVIDER.com/YOUR-USERNAME/YOUR-REPOSITORY
For example:
git clone https://github.com/chrismaltby/gb-studio
From a GUI there will likely be a menu operation that does the same thing. This is what it looks like in Fork:
Setting Up the Repository
Remember how I said git wasn't designed to handle images and sound? Here is how we fix that.
First, you'll need to move from the folder that holds your repository into the repository itself. So, instead of hanging out in My Cool Files > Repos we move to My Cool Files > Repos > My New Project
Now, we start up Git Large File Storage.
From the command line we enter: git lfs install
A GUI will have an equivalent, like this:
After this, there are two small text files we need to add.
One of these is directly related to LFS. It's called .gitattributes and it tells LFS which files are not text and so, which files it should store for us.
*.mod filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.sav filter=lfs diff=lfs merge=lfs -text
*.uge filter=lfs diff=lfs merge=lfs -text
*.vgm filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
There is more you can add to the gitattributes file, but this is all you need.
The other file is called a .gitignore file, and it tells git what files not to track at all. For GB Studio projects, this file tends to be very simple:
[Bb]uild
*.bak
~*
This tells git to ignore everything in the build directory, where your game ROM and other files will be generated when you hit "Run" or "Export", and to ignore some common backup files.
Now it's time to create a new GB Studio project in this folder. You do this as usual through GB Studio.
Telling Git to Remember Your Work
Once you have created and saved a new project in this folder, it's time to let git know that it should remember these files.
From the command line you would type:
git commit -m "Create new project"
There are two steps here. git add tells git get ready to track any changes it finds; this is called "Staging". git commit tells it to actually track them; this is called committing.
Note the text that says "Create new project". This is a note to your future self. These notes are one of the most powerful and important parts of git. They tell you what you did at this moment in time, when you told git to track and store the current state of your project.
By convention, you write these notes in the present tense in an imperative fashion, and without punctuation. You can actually do it however you like; just make sure it's clear and easy to understand.
Some example notes from my most recent GB Studio project:
Implement grid-based selector movement
Implement drawing various card fronts when flipped
Fix tile ordering
You can do the same thing in a GUI, usually through a dedicated tab or pane and a set of Stage and Commit buttons.
Storing Your Work Online
Once you've staged and committed, it's time to tell git to copy all of this to the service provider you set up an account with. This is called "pushing".
In a GUI, there will be a button for this, usually with an arrow icon. On the command line you'd usually just type: git push
Here's what one of my project folders look like once all of these steps are done:
Good Habits
As you work on your project, you have to remember to stop from time-to-time to stage, commit, and push. Git stores a copy (more or less) of your project every time you commit, but it can't guess when you want it to do that. So you have to tell it.
I've found that the best results come when I do this very frequently, whenever I change an asset or code.
After finishing a new sprite graphics, for example, I'll immediately go to my git GUI, stage that new file, and commit with a message like "Add the vampire sprite"; this makes it much easier to figure out when and how something broke later on.
If I finished writing a new routine, like shuffling a deck of cards, I would likewise immediately stage and commit once I had done that, even if the feature that shuffling is part of was not complete and not tested.
After a while, perhaps each hour or perhaps once a day, I'll push. This should be much less frequent than committing, but often enough so that if you need to pick up where you left off on another computer, or restore a backup after a system failure, you can.
Finally, I like to tag certain commits to show when I released a build. This is easy to do; just type: git tag 0.1-beta or git tag 1.0-release
Lots of people, including myself, like to use semantic versioning for this, but you don't need to. In fact, you don't need to tag at all.
I tend to tag only when I release, for example when I send the game to testers or when I publish it on Itch.
Any questions? Feel free to ask!
