This guide (Updated 8/13/2020) will set up your local version of the code, and your github fork using GIT/GITBASH.
INITIAL SETUP, OR BASICALLY ATTACHING THE CODE TO GITHUB.
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 git
This should cover everything you need to get started, but now lets talk about actually USING git for something practical.
Author's note
REGULAR USE
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 will tell 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 will 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 will basically 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 will send your local changes from your branch back to the website version of the code.
If you're trying to update your master branch of the code at any point and time, you can use the above 4 commands, in order to fully update your master branch!
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 argument. 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.
WARNING: SLIGHTLY OUT OF DATEYou can also follow this guide and use GitKraken instead: https://forums.yogstation.net/index.php?threads/release-the-gitkraken-how-to-make-your-first-pull-request.15099/
Yes, we know it is for yogstation but it works exactly the same when using the /tg/ github. Still, most of the help you can get from the discord and forums will be from gitbash, but GitKraken is a viable alternative if you prefer it.
CLICK EXPAND FOR A REALLY REALLY OLD VERSION OF SETTING THIS UP VIA TORTOISEGIT. IT'S JANK AND DOESN'T REALLY WORK EITHER, BUT, it's left here for archival purposes:
This guide uses TortoiseGIT. While there are other programs out there, this one is the most commonly used. This guide is for Windows only. TortoiseGIT is a simple enough program but other clients or the git command line are recommended once you are familiar with the basics.
It's recommended if you don't want to read this that you just watch this video:https://www.youtube.com/watch?v=ZDR433b0HJY
Some further videos that are recommended watching for any git user:
https://www.youtube.com/watch?v=MYP56QJpDr4 - Git from bits up
https://www.youtube.com/watch?v=4XpnKHJAok8 - Linus Torvalds (yes that linus) on git
If you are having trouble
Watch this video guide if you are having difficulty with any step below. [1] If you have further problems, contact someone on #coderbus
Step 1 - Install Git
- Go here: http://git-scm.com/downloads
- Download the Windows Git program.
- It should look something like 'Git-1.7.11-preview20120620.exe'
- Install it and leave everything on default (just keep clicking next).
- Wait till the installer has finished.
- Step 1 over!
Step 2 - Register on Github
- Head over here: https://github.com/
- Click Signup and Pricing in the top right-hand corner.
- Click the Create free account button'.
- Create an account with your username and email.
- Done!
Step 3 - Configure Git
OPTIONAL!
- Head here: https://help.github.com/articles/set-up-git/#setting-up-git
- Follow the guide above from steps 2 to 4, you can install Git for Windows if you want however it's not recommended
- Now you have Git all setup, but if you're command line illiterate like me, you'll wanna have some fancy graphics!
Step 4 - TortoiseGit
- Go here: https://tortoisegit.org/download/
- Download the right TortoiseGit for your system.
- When installing, click OpenSSH rather than TortoisePLink
- Finish installing.
Step 5 - Forking Code
- Head over to: https://github.com/tgstation/tgstation
- Click the Fork button in the top right corner.
- The page you'll be directed to is now your fork. You'll be pushing updates here, and making pull requests to have them merged the main (master) repository.
- Copy the HTTP URL. It's next to the HTTP GIT and Git Read-Only buttons. It'll look something like: https://github.com/NAME/tgstation
Step 6 - Downloading the Code
- Find a computer folder where you don't mind the code sitting.
- Right click and choose Git Clone...
- The URL field should be filled with the URL of your Fork. If not, paste it in.
- Click Next and watch flying tortoises bring you your code.
Step 7 - Setting up TortoiseGit
- Right click on the folder that was created (usually called tgstation13), and go to TortoiseGit and then click on Settings.
- Click on Remote under Git.
- There should be one thing on the list of remotes, with the name: origin.
- You're now adding the main repository as a source you can pull updates from.
- In the Remote box type in upstream.
- In the URL: box put: https://github.com/tgstation/tgstation.git
- Click Add New/Save.
- Click Ok.
- Almost done!
Step 8 - Updating your Repo
- Updating your repo with the master should be done before trying anything.
- Right-click the folder your repo is in and select TortoiseGit then Pull.
- Click the radial button next to Remote and make sure upstream (or whatever you called it) is selected next to it.
- The remote branch should be set to master.
- Then click Ok. This will pull the latest changes from the master repo.
Step 9 - Making a Branch
- Branching your repo is very important for organising your commits, you should have a different branch for each unrelated code change (e.g. if you wanted to make some new sprites for one item and change the properties of another these should be in seperate branches), as Pull requests work off branches rather than commits this will allow you to make a seperate Pull Request per change. Doing this streamlines the whole process and will save everyone a bunch of headaches.
- Right-click in your working folder. Then choose TortoiseGit, and Create Branch...
- Type in your new branch name
- (Optional) Tick Switch to new branch
- Press Okay and your new branch is created
To switch between Branches:
- Right-click in your working folder. Then choose TortoiseGit, and Switch/Checkout...
- Choose your Branch then press Okay
Step 10 - Making a Commit
- A commit is confirmed change of the files in your repo, it's how you make changes permanently to the files in your repo, so try not to commit without making sure it works (though subsequent commits can fix it).
- As said before, you should use different branches to separate your commits/changes. Don't commit to master. It should be clean, so you can fall back on it if needed.
- To make your commits, you need to edit the files using BYOND's inbuilt editing tools. Make sure to follow coding standards when making your changes! When you're finished, right click the folder you're working with and choose Git Commit -> "[Your Branch Name]" (Example: Git Commit -> "My_First_Branch")
- You can then select only the files you want to be committed by ticking or unticking them. You should also write a detailed commit summary, detailing what happened in that commit.
- Click Ok and the commit will be committed to your local repo!
Step 11 - Making a Pull Request
- Right-click in your working folder. Then choose TortoiseGit, and Push...
- Set Local and Remote to the name of the branch you committed before. (e.g. My_First_Branch)
- Under Destination, set Remote: to origin.
- Click Ok. This'll upload your changes to your remote repo (the one on GitHub).
- Head to your GitHub repo e.g https://github.com/NAME/tgstation13.git
- Click Pull Request at the top right.
- Give this a quick read.
- Fill out a summary and then create the pull request.
- You're done! In many cases there will be issues pointed out by other contributors, unfortunate merge conflicts, and other things that will require you to revisit your pull request.
- Optionally, view step 13 for a guide on cleaner commit logs, cleaner commits help maintainers review!
Step 12 - Checking Out Github PRs Locally (Optional)
- This is a must for maintainers who need to easily test other people's code!
- Locate the section for your Github remote in the .git/config file. Note that it is hidden by default. It looks like this:
- [remote "upstream"]
- fetch = +refs/heads/*:refs/remotes/upstream/*
- url = https://github.com/tgstation/tgstation.git
- Now add the following line:
- fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*
- Fetch from the upstream remote.
- To check out a particular pull request, use Switch/Checkout and select the branch from the drop-down list.
Git command line verison
No editing of the git config file needed, just do git fetch <remote> pull/<pr>/head:target_branch usually something like git fetch upstream pull/26271/head:pr-26271.
Then you can checkout the target_branch
Step 13 - Clean commits (Optional)
- This is a guide specifically for TortoiseGit, our recommended client
- Your commit logs are filthy, full of one or two line commits that fix an error that makes you look bad, and the commit is called "Whoops" or "oops"
- Navigate to your local version of the branch
- Ensure it is up to date with the remote
- Go to Show log
- Select all the commits associated with this change or PR
- Right click and choose Combine to one commit
- This will open up the standard commit interface for TortoiseGit, with the commit logs of the selected commits merged together
- Perform the normal routine for a commit
- Go to push your branch to the remote branch
- Ensure Force Overwrite Existing Branch (may discard changes) is selected to make sure the PR/Remote updates to contain just this squashed commit