Like many in this hobby, I've started to pick up some coding here and there by learning to use Ren'py. However, programming is not my field, and whenever the discussion starts to get more technical then "How to use Word", I start to feel out of my depth and like a boomer. As I am part of a community of fellow FVNs creators, those that actually have programming training never tire to stress to the rest of us the importance of using "version control". Frustratingly, however, they never bother to stop and explain what it means to you, who don't even know what version control is. If you try to learn on your own, you will have to face such delightful and obscure language such as "commit", "branches", "detached heads" (yes, really)...

This finally changed for me when my fellow FVN creator Akiba took the time to teach me the basics. This little session, however, was not meant to benefit just me: our idea was that I would then pass on what I have learned, from the perspective of an absolute noob, for those out there who were in the same situation as me. This is what you are now reading: this is my guide on how to use GitHub.

If this is a familiar topic for you, please be ready to forgive the mistakes I will inevitably be making in the following guide. While I am doing my best, the whole premise of this exercise was to let a layman write this guide for better accessibility (otherwise, I'm sure Akiba could have done this by himself)!

So, without further ado, let's start with some basics. While there are other options for version control, I chose to learn GitHub because it seemed to be the easiest.

WHAT IS GITHUB FOR?

So, you are an aspiring or current game dev. Why should you give me 10 minutes of your time and learn how to use GitHub? What can it do for you?

The main benefits are as follow:

• GitHub allows you to work locally on your project and at the same time have an online backup of your project. You don't need to worry about something nefarius happening to your computer and you losing all your hard work! And, unlike other forms of cloud backup (like Google Drive), GitHub works by keeping track of your changes: this means you don't need to upload every time your whole project to the cloud, GitHub will only update the changes made to your last "save state". This is a nice little extra for people with a slow or limited Internet connection.
• When you "save" a new version of your project, this doesn't overwrite your old "saves". Instead, each version of your project you "saved" is kept as a "save state". This means, you can easily navigate between different versions of your project. You realize that you accidentally deleted a file? No problem, just go back to an older version and retrieve it. You screwed up your code and now no longer works? No problem, go back to the last version that worked.
• Finally, GitHub is great for sharing your code and working with a team. Because your project is on a cloud, it's easy for multiple people to work on the same project. GitHub also allows you to create "branches": instead of all people working on the same version of the project, you can assign to each developer a separate "branch". Because I'm lonely though, discussing branches is beyond the scope of this guide. Furthermore, if you are a believer in open source, you have a public version of your project for anyone to access.

SO, ABOUT THAT DEMONIC TERMINOLOGY

In the next session of the guide, I will go step-by-step about setting your project in GitHub. However, I think the most important thing when approaching GitHub for the first time is understanding the simple logic of how it operates and what perverse version of English it uses.

The easiest way to visualize how this all operates is to imagine that your project exists in three different places at the same time:

• Your local project folder. This is a normal folder on your computer, where you will be working on your project as normal. When you make changes to your folder, *nothing gets saved on GitHub yet*.
• Your local repository. This is where you will create a backup version of your project from time to time. The act of "saving" your current project state in your local repository is called *committing*. When you save your changes to your local repository, you can already start to benefit from the functions of GitHub we discussed above (for example, have a history of all your "save states"). However, your changes still only exist on your computer at this point, they haven't been uploaded to the cloud yet.
• Your repository on the cloud. This is the final step: you upload what you have committed to your local repository and create a copy in your repository in the cloud. This is called *pushing*. Once you have pushed your commit, those changes are on the Internet and you have a backup that will be available to be downloaded from any other computer.

If everything so far is clear, then don't worry: we're almost halfway there already!

STEP-BY-STEP GUIDE

Ok now, let's get started with the nitty gritty. First things first, you want to create your GitHub account. Go to https://github.com/ , click Sign up, and follow the steps.

Now that you are on your GitHub profile, go to your dashboard on the GitHub website and create a new repository. Like we said above, "repositories" are like folders where you will save the backups of your project. Create one repository per project.

When setting up your repository, the only things you will have to choose is the name and whether it's a public or private repository. Everything else you can ignore for now: we will come back to the .gitignore file, since there isn't a premade template for Ren'py. If you are not using Ren'py, but something else, you can check out the available templates.

You will now want to download the GitHub desktop app to be able to work on your repository locally, by going here: https://desktop.github.com/

Here I have two repositories for my two projects.

Now that you have created your repository, you want to create your project folder on your computer (the one that will be synchronized with your repository). To do so, you basically have to  download your repository to your computer (even if, at this point, your repository is still empty). Doing so is called *cloning* your repository (=download your backup).

Click your repository, go to File, and Clone it, choosing your file path. This will create a folder on your computer, which will be your project folder from now.

If you had already started working on your project before, no sweat. Just transfer all of your files to this new folder!

While you are on the GitHub desktop app, you can at any time click on "Show in Explorer" to go to your local project folder and "View on GitHub" to go to your repository on the cloud.

So, what happens now that you have your synchronized project folder? Every time you change something in this folder, on the GitHub app you will be able to see all changes from your last commit ("save state"). For example:

Here you can see a bunch of files with a green plus: this are all new files that I added to the project folder since my last "save". The last file (script.rpy) is instead marked with a yellow dot: this means that this is not a new file, but a file to which changes were made. By clicking on it, you can see all the changes from the previous version (see on the right all lines of code in red with a minus, which were removed, and all lines in green with a plus, which were added). If I had removed a file from the folder, this would have appeard up here with a red minus.

The GitHub will constantly track your changes to your project folder. However, *until you have committed your changes, nothing has been saved yet*. 

Before we do that though, let's now go back to that .gitignore file we skipped earlier. This is a file that basically tells GitHub what files to ignore when you are creating a backup.  This file needs to have a .gitignore extension and should be in your root folder of your game (as it will not apply to folders of a higher level. Here is what Akiba kindly provided as a good base .gitignore file if you are working on Ren'py. For example, this will tell GitHub to ignore all files with a .keystore extension (those are meant to be kept secret!) or .rpyc extension (you don't need these if you are already have the .rpy files). You can open .gitignore with any text editor.

Feel free to copy my .gitignore from my directory: https://github.com/LoudoEp/The-Flying-General/blob/main/.gitignore

In order to commit, you must first type a name for your commit in the "Summary" bar (you can also add a longer description, but that's optional). Then you will be able to click on "Commit to main". (Main being the main branch. As we discussed above, it is possible to create and commit changes to separate branches too.)

Look at all those sprites I added: better save all that hard work.

Now that you have committed your changes, you will see that the app will tell you there are no more changes to your project: this is now your last "save state", only new changes compared to this version will be tracked.

However, as we discussed above, these changes have only been saved *locally*. You now want to create a backup on your GitHub cloud. To do so, you have to *push* your commit.

Push ma'am! Push! I can almost see the head.

Congratulations, you have successfully created a backup of your project on GitHub!

But what about this fabled "version control" I keep hearing about? You said it's even possible to go *gulp* back? Yes, indeed!

You will have noticed that on your GitHub app, there is a second tab in your repository: History. By going there, you can see the list of all your commits, and all the changes to the project associated with every commit.

Oh, yeah, "Added sprites" did contain a lot of new sprites.

If you right click on one of your past commits, you have some options that will allow you to go back. In particular, I want to highlight the first option, "Checkout commit".

This will temporarily revert your project to that "save state": GitHub has a delightful name for this, a detached head of your project.

Don't worry, it's not as worrying as it sounds.

To go back from the detached head to your main branch, simply click on the branch button and select main.

This is all for now. I am exhausted and I realize this guide is really basic, but I hope it will be useful for those like me who had no idea about how to us