-
Notifications
You must be signed in to change notification settings - Fork 166
Getting Started: Git
If you're working on a hack using any variant of decomp (such as HackerSM64), you'd be stupid not to use Git. But a lot of confusion arises around the tool, so let's clear it up with a guide! Here you'll learn just what Git is, and work around many of its most common features.
Git, in a nutshell, is a tool to store the history of your work on a software project. You add changes in the form of "commits" to the "repository", and can go back to any version of your project at any time!
"...It's like Google Docs, but for coding"
Now you might be wondering, "Google Docs has collaboration between any number of people. Does that mean Git does too?"
And the answer to that is, yes! Git can be used to collaborate with people all over the world for your project.
GitHub is a website where you can host a git repository for others to download and make changes to. From there, they can make a "Pull Request" to your repository, and you (and potentially a team of reviewers) can choose whether you want that change merged in.
Collaboration on a small scale through a private GitHub repo is the gold standard around the community, but some users prefer other hosting services like GitLab and BitBucket, since they're able to be self-hosted.
You already did! When downloading HackerSM64 for the first time, you ran this command:
git clone https://github.com/HackerN64/HackerSM64.git
This downloads all of the code repository's files, as well as its history as a Git repo. Run:
git log
to see what has changed since you cloned. (and press q to quit that menu)
If you want to commit a change to your repository, you'll have to tell Git who you are, so it can append your name to the commits you write. This makes it easy to see who changed what in a repo.
git config --global user.name "your name"
git config --global user.email "your email"
The email/name you use doesn't have to be your real name/email address, if you're worried about that. It's just to mark who made changes and, in a public repository like the Linux kernel, who to email regarding the change.
First you might be asking, "What's a branch?" After this tutorial, you'll know all about how they're the best thing to happen to your workflow since sliced bread!
git checkout -b my_new_branch
the -b flag creates a brand new branch called my_new_branch, and git checkout switches you to that branch. If you look at the asciinema videos I have under each lesson, you'll see that I will also run git status. This is a super useful command that lets you see what branch you're on, as well as any files you've changed that are ready to commit.
Now that you're on a new branch, let's make some changes!
- Open up your text editor and make a change to some random file. Maybe you want to change some text, or do a debug print somewhere.
- After that change is made, commit it using
git commit -m "short description of what you changed"
(Note: I fumble around the file I decided to change a lot before finding the thing I wanted to change lol)
After your change is committed, run
git checkout master
git checkout -b my_new_branch_2
This will switch you to a new branch named my_new_branch_2. Here we'll be simulating one of two things. Either:
- You're working on two features at the same time, and don't want one to interfere with the other, or
- A collaborator on your hack is working on a feature and will make a pull request when it's done
Now pick a new file to edit. Maybe you want to tweak one of mario's actions. Or you want to put in a debug L to Levitate code. After it's done, commit it.
Note: I use
git add path/to/file
because I only change one file. If you change more than one file in one commit, you can grab them all in one go using
git add .
Now run
git checkout master
to go back to master. We will be merging in the new branches one at a time using
git merge my_new_branch
git merge my_new_branch_2
If a text editor pops up, press Ctrl-X to close out of it. Now check the git log. Both of your "features" should now be merged into your main branch!
Pro Tip: You're not limited to only two branches. Make as many branches as you want, and merge them one at a time whenever you're ready! With this method you'll also learn about Merge Conflicts, which will help you become better at maintaining your own code!
Git stores all your changes locally, so how are you supposed to sync your changes? Of course, by hosting a server that you and collaborators can access and sharing the password/SSH keys to it, making sure that server is always online so that you can commit to it whenever you want!
Just kidding! GitHub does all of that for you! Let's see how to do that:
- On GitHub, go to HackerSM64's page
- Hit the Fork button on the top right corner
- On your new forked repo, and under the green Code button, copy the SSH link and put it somewhere for later
- Follow This tutorial to get a new SSH key, and this tutorial to allow your GitHub account to use that key
- Run
git remote add my_remote_name (your GitHub SSH link from step 3)
git push my_remote_name master
- Go to your GitHub fork, and voila! Your changes are there!