Setting up git
This guide (Updated 8/13/2020) will set up your local version of the code, and your github fork using GIT/GITBASH.
Git Bash
Initial Setup
Step 1: The first step you need to perform is to install and download Git, located HERE. Git, or Gitbash, is a commandline style setup for making a working github repo off of a base sourcecode, but has some distinct advantages over many of the alternatives (Github desktop, Tortoise Git, Gitkraken, etc). In particular, it lacks many of the frills that a GUI based git client would give you, but it also gives you more exact control over what you're trying to do, and because of that if you make a mistake you can work backwards to fix something that might have gone wrong.
Step 2: Next, you need to create a fork of the base code. Go to the tgstation repository on github, and on most any page of the repo you'll want to hit the fork button at the top right. This may take a moment, but what this effectively does is it creates a copy of the code that belongs to you, but is linked directly to the main repository. This means that when a new Pull Request (PR for short) is merged into the main codebase, and is added to the game on live servers, you have a link through the website to easily make the new changes on your local version of the code.
Step 3: Get your Fork URL from github. It should be something like https://github.com/<yourgithubusername>/tgstation.git. You can also find this by hitting the large green Clone button on your fork. This URL is what effectively will link your github fork on the website to the code that you're about to download, so keep it on a tab or somewhere where you can pull it up in a moment.
Step 4: Navagate in your window explorer or file browser where you want your github repo to exist on your computer. Then, right clicking from within that file, open your command line. You may also do this with "Git Bash Here" on your right click menu, if you enabled that when installing Git.
Step 5: From your command line prompt, enter git clone <yourforkurlfromstep3.>. This tells git to take the code from that public github fork, and paste it into your designated folder.
Step 6: Next, also in command line, enter: cd tgstation Then, finally, enter: git remote add upstream https://github.com/tgstation/tgstation.git
This should cover everything you need to get started, but now lets talk about actually USING git for something practical.
|
Author's note
Now that your git is set up, you may want to also download Visual Studio Code, as there are plugins and add-ons that make working with byond code and the rest of the codebase significantly easier, but you can avoid that for now if you just want to get familiar with gitbash and the codebase (But #coderbus will ask you to download it at some point anyway). |
Command Reference
| GITBASH COMMAND | When you want to do something with gitbash, there are several commands you should memorise, or at least have save someplace to make your life easier. |
|---|---|
| git status | Tells you where you are, or what issues are potentially occuring with pushing or pulling your files. Use this if you forget what branch you're currently on, or why you can't updated/push your code, as it usually always has some clues. |
| git checkout master | Attempt to jump to your master branch, which comes standard with any fork. This will run into issues if you have uncommitted changes that haven't been pushed, or there's otherwise lingering code that might run into issues if you leave your current fork. Side note, Don't make changes on your master branch! Version control is the benefit to using all of this, so that you can make PR-able code changes on your branches, but you can update against your own master to have a clean version of the code for testing/changes. |
| git fetch upstream | Will go to the live version of the code, on github, and attempt to update your local master with the new changes that have been merged. |
| git reset upstream/master --hard | Force reset your current branch to the state of the live master version of the code. Take note of that --hard tag at the end. This means that it will do this forcefully, and obliterate any potential changes that have been made to your master branch. Remember, keep changes on a fork! |
| git push -f | Send your locally completed commits from your branch back to the Github website. |
Making a code change
If you know how to code in byond, here's how you would take your code changes and push them to the github repo to PR.
Starting from master (git checkout master), you want to run the command from gitbash git checkout -b <BRANCHNAME> , which will create a new branch on your repo with the BRANCHNAME name you selected (Note, branch names are public once you publish them later).
Once your branch is created, you are now on that branch, and any code changes you make will be located on that branch. It's here that you would code the changes you are attempting to make. For example, lets say we change a single line of code on a byond file called code/modules/freshmemes.dm. Once the file is saved, gitbash will see that you have created unstaged changes to the freshmemes.dm file. If you ever need to know what's commited or not, git status is your ally here.
Next, you'll need to run the gitbash command git add <filepath>, with filepath being code/modules/freshmemes.dm again.
Now that your changes are staged, you need to commit them. Run git commit -m "<words>". Every commit that's pushed to a PR is labeled in order to work with that excellent version control mentioned earlier, so if you needed to revert your code back to a old commit, it's possible to do so, and well indexed. This would create a commit with the changes to freshmemes.dm, labeled <words>, but please god give your commits a slightly descriptive name, at least.
Now we're nearly done, all you need to do now is run git push origin. If it's your first time pushing this code to github on that branch, you'll be asked to instead run git push origin --set-upstream <branch>, where <branch> is your current active branch. This is normal and expected. Once that's done, on your fork on the github website, as well as on your local code, your same branch will be hosted. This will enable you to PR your code to the main repo without needing to devolve into a disgusting web-editor.
Other Guides
Git Bash is preferred when you need help from someone who knows more about Git, because the commands are more powerful and easier to communicate. However, if you want to use a Git GUI to make things easier as a beginner, there are other guides: