In this tutorial I’m going to try to introduce you to Git and GitHub and teach you how to make a change to a project and send a Pull Request.

I’m also going to explain you what Git jargon means, for example a Pull Request (PR for short) is a request for a project to merge your changes.

Anyway, first of all, something that should be clarified, the tool Git and the platform GitHub are different things.

Git is a tool used to version control projects, what does this mean? In simple words, it keeps a history of your project that makes it easy to roll back changes if you need and it also makes it possible for several people to work on the same project without destroying each other’s work.

GitHub, the platform is mostly used to host Git projects and there’s several other platforms like GitLab for example, GitHub is just the most popular one.

Git is a command line tool but because this is an introduction tutorial we will be using a GUI Client for Git. There’s several of these but I’ll be showing GitHub Desktop. I’ll also cover some commands but only the most common ones that are useful to know.

With this said you should start by downloading and installing GitHub Desktop. This will also install Git for you so that’s all you need for this tutorial. If you were to do things without GitHub Desktop you would need to install Git first.

You should also create a GitHub account if you don’t have one already.

So, for this tutorial we are going to use one of my projects, we will fork WaspLib.

Forking means making a copy of a project at a certain point in the project history. When a project is forked the forks can later be merged or drift off in different directions.

So first, head on to GitHub.com and login. Then go to the project page you want to fork and click the fork button:

It will then prompt you with this and just click ""Create fork"":

This will create a fork by making a repository of your own with a copy of the project.

""Generally, an information technology repository (or repo) is a centralized place where data is stored and maintained in an organized way, typically in computer storage."" We usually use it to refer to the project itself but that’s the definition of repository.

Now that you have your own fork in GitHub, you could actually edit it online and do everything through the page but that’s not really efficient.

Now… If you already had WaspLib installed from using my scripts you will want to delete it for this.

Go to your Simba Includes folder, probably C:/Simba/Includes and delete WaspLib.

Once that’s done, open GitHub Desktop, click on File > Clone repository… :

• From the menu choose the project you want and clone it:

Make sure you set the path to Simba includes to easily edit it with Simba later.

After doing this you will get this prompt:

You will want to choose the second option because you can’t write stuff to other people’s permission unless they let you. Instead you will make your changes in your own fork (the second option) and then send a pull request.

Now if you wanted to make this with the command line, you would first navidate to the directory and then use git clone project_url: Now for the command line, it’s very easy actually. you only need to know the Git project URL. In this case it’s https://github.com/torwent/wasplib.git.

So open the command line in the includes folder or navigate there with one and then use git clone URL:

cd C:/Simba/Includes/
git clone https://github.com/torwent/wasplib.git

Now that we have our project locally, let’s move on.

Personally, I’ve learned that when I want to keep the project in sync with the orginal, it’s better to make the changes in a new branch, that way you have an easy way of falling back to the original project without having to refork everything or something, so make a new branch, e.g. WaspLib-Additions. To make a new branch with GitHub Desktop you open the branches tab and click ""New branch"":

Give a name and click ""Create branch"":

Now open Simba, go to the ""File Browser"" panel (on the right by default), expand Includes, then WaspLib and open the file you want to modify, in this case I’ll do osr.simba:

Now, since this is not a Simba tutorial I’m just going to add a comment:

Save the file and go back to GitHub Desktop:

We now have changes waiting to be commited.

Commiting in Git is sort of saving the changes in a way that it gets registered to the project history. This way if you ever want to roll back a project to a certain commit, it’s super easy to do so.

When you change several stuff you have the option to select only some files to commit on the left panel or you can even select just certain lines on the right panel to commit. You will need to play around with GitHub Desktop and find out what it can do.

On the bottom left panel you have the commit controls. There’s a field for the commit header and another for commit description.

Descriptions are optional and personally I only use it if the header is not self explanatory.

One thing to note is that all my projects use what’s called conventional commits. If you want you can read more about it here, but the gist of it is that: Small changes should start with: ""fix: "" Features should start with: ""feat: "" Breaking changes should start with ""fix: "" or ""feat: "" and they must have at the end of their description: ""BREAKING CHANGES: "".

You can also use scopes like ""fix(TRSWalker): …"" and there’s more convention commit messages like ""perf"" for performance improvements, ""chore"" for chore work, etc but the ones above are the main ones.

Also, I have all Simba projects set up in a way that ""fix"", ""feat"", ""BREAKING CHANGES"" will bump the project’s version file like so: v(BREAKING CHANGES).(feat).(fix).

Anyway… with this explained, let’s do our commit:

And click commit.

Now our branch is not published, so let’s publish it:

If you make a commit and already have the branch published you will have the option to push the pending commits to GitHub:

Now let’s go back to GitHub.com and go to the main project page. Click on ""Pull Requests"":

And then on ""New pull request"":

A new page will open up, in this page first you need to enable ""compare across forks"" so you can see your fork:

Now select your fork:

And then your branch. If you can’t see it, search for it:

Now you can see what changes you made to the project, and ""Create a pull request"":

Clicking to create a pull request will give you the option to leave a message to the repository maintainers:

Click create and your pull request will stay on hold until it is accepted or closed. Keep in mind that not everything you think is a good change might be considered as such by everyone. Usually very personal things should be kept for youself only and only things that truly benefits everyone should be pull requeted and will be accepted.

When your pull request is accepted or declined, you can optionally delete the branch you made for it if you don’t need it anymore:

And you will be asked if you also want to delete it ""on the remote"" which means on GitHub.com:

Deleting a branch on the remote you used to make a PR will automatically close the PR. Keep that in mind.

And that’s about it, you should have enough knowledge to start playing around with Git. Git has a lot to it and sometimes things don’t really work as you expect but you need to be patient and read/ask about your issues and learn to solve them. It’s a really powerful tool but comes with a learning curve.

I hope you find this helpful, thank you for reading!