Git Good at Git Setup
This is a guide to learn how to get started with contributing to the code in as little time as possible. This guide uses the TortoiseGit client, which allows you to run Git commands without having to open a command line interface. Note that this means that this is a Windows only guide. If you are not using Windows, there are other Git clients that should work with your OS, with their own documentation.
First, we need to actually install Git itself.
- Go here: https://git-scm.com/downloads
- Download the Windows Git program.
- You should leave all the settings to default when installing, if you're not sure what something does.
Now we need an account on Github. Fortunately, we can make a free account fairly easily. If you already have an account, you can skip this step.
- Click Signup and Pricing
- Choose the free account option.
- Fill in your desired username/password and give it your email, verify it, etc. Done with step 2.
This part requires fiddling around with the console, however you only need to type a few lines in.
Open up Git Bash. If you did Step 1, you should have it installed. We want to tie your name to your commits, so type this in Git Bash. Replace "YOUR NAME" with your Github username. Make sure it is wrapped in quote tags.
git config --global user.name "YOUR NAME"
After that, we want to associate the email you gave Github to your commits as well, so type this. As previously, replace "YOUR EMAIL ADDRESS" with your email, wrapped in quotes.
git config --global user.email "YOUR EMAIL ADDRESS"
If you want your email address to be private, give this a read: https://help.github.com/articles/keeping-your-email-address-private/
Now for the part we've been waiting for. We'll be able to do most things without needing to open a command line interface once we get TortoiseGit.
- Go here: https://tortoisegit.org/
- Install the latest stable release. Make sure to install the right program for your system (32 bit vs 64 bit OS).
- While installing, make sure to select OpenSSH instead of TortoisePLink
Now, we need a copy of the code that you can play with, first we need a fork.
- If you haven't already, log into Github.
- Go to https://github.com/PolarisSS13/Polaris
- Click the 'Fork' button.
- The page you should be redirected to is now your Fork, which is a copy of the code, that you will be pushing updates to later on, and making Pull Requests from here to the main server branch.
- Copy the HTTPS URL of your fork, it should look something like https://github.com/NAME/Polaris , with NAME being your username.
We have a nice fork with a copy of the code, but we actually need the code on your system in order for you to make changes. We're now going to make a copy of the copy of the source code .
- Find a place on your system you don't mind your 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.
- Depending on your connection speed, this could take awhile to download all of the source code. You might want to go get a snack or drink while you wait.
After we're done downloading the source, we need to do some one-time setup for TortiseGit.
- Right click on the folder that was created (usually called Polaris), and go to TortoiseGit and then click on Settings.
- Click on Remote under Git.
- There should be one thing on the list origin. This is where your fork on Github is.
- 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/PolarisSS13/Polaris.git
- Click Add New/Save.
- Click Ok.
Your 'upstream' remote should look like this picture below.
Almost done!
This will reduce conflicts with .dmi and .dmm (icon and map) files. Technically optional, but highly recommended and quick to do.
- Open the .git folder in your source code.
- Open the file 'config' with a text editor (notepad might have issues, try notepad++ or your editor of choice).
- Add the following to the bottom and save it.
[merge "merge-dmi"]
name = iconfile merge driver
driver = ./tools/dmitool/dmimerge.sh %O %A %B
[merge "merge-dmm"]
name = mapmerge driver
driver = ./tools/mapmerge/mapmerge.sh %O %A %B
When you pull code, it should first try to resolve any conflicts by using these programs. Without it, .dmi is especially vulnerable to merge conflicts.
We're finally done with setup! However you probably don't know how to use TortiseGit. Don't worry, this guide will tell you how to do many operations with Git using TortoiseGit.
Before you start working on something, making sure you're up to date is always a good idea.
- Updating your source code with the master should be done before trying anything.
- Right-click the folder your source code 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.
Branches allow you to organize your changes. By default, when you cloned your copy of the code, the branch you start on is called master. You should never work directly on the master branch. You should only update the master branch, or make a new branch and work on that one. The reason for that is so you can fall back to the master branch if you make a mistake you're unable to fix on a separate branch, without needing to reinstall the source code.
Branching your source code is also 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 , if you want to work on it immediately.
- 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.
Note that TortoiseGit will complain if you have uncommitted changes. If have those, commit, stash, or revert them before switching.
A commit is confirmed change of the files in your source code repository, 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 changes to the code that you can commit, you should 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 → “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!
After you've made a change to the code, you probably want your change to make it to Polaris's server. Before that can happen, you need to push your commits (changes) to your origin remote, which should be the fork of the code that's sitting on Github.
Fortunately, if you cloned your source code, origin should already be set up.
- 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). If Remote is empty, copypaste your local branch name to it, and it'll get made as you push.
- 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/Polaris.git
Now that your changes are on your origin remote, you'll need to get them onto your upstream remote. To do this, you'll need to request that your changes are incorporated into the source code of the upstream repository.
- Navigate to your fork on Github.
- Click Pull Request at the top right.
- Make sure you don't see a red 'cannot merge' anywhere on the page.
- Fill out a summary and then create the pull request.
