Home
Git is a source version control manager. It tracks the history of code, synchronizes your computer's copy with an online copy, allows collaborators to work independently and merge their changes together, and is generally a pain in the butt.
There are multiple ways to use Git. My method is to use a combination of the command line interface, downloadable here, and Sublime Merge for any heavy lifting / merging.
A folder tracked by Git is called a repository. The online repository hosted by GitHub is called remote, your computer's copy is called local. You can clone this repository to your computer with git clone https://github.com/jwapobie/artstation.git.
Branches store different editions of the code. They usually store WIP or untested code to be merged into the main branch later. You can switch between them with git checkout <branchname> as long as you don't have pending changes. You can make a new branch based off the active one with git branch <branchname>. This lets you do your work in peace without remote changes messing you up. When done, work from your branch can be copied back into the original.
- Master: A copy of tgstation/master. This contains no custom assets.
- artstation: The stable build of artstation. This branch contains all custom assets and should be working most of the time.
- art-latest: Whenever we want to upgrade to the latest version of tgstation/master, do it in here so that it doesn't break the artstation branch.
A commit is a discrete unit of work. Each commit marks a unique version of the code. Every time you make a change, it will show up as a pending item when you run git status. Use git add or a Git GUI tool like Sublime Merge to queue your changes for commit, then run git commit -m "<commit message>" to save your changes. Then, push your changes.
Pulling is the act of updating your local repository to match the remote. Do this constantly, especially before you make changes. The command for it is git pull.
Pushing is when you push your local changes up to the remote repository. This updates the repository on GitHub. The command for it is git push.
Do you want to become a GIT MASTER? Well, it'll take more than me lecturing you to make it happen. But here's what you need to get started:
When other people update a branch on the repo, it can conflict with your local changes. To avoid this, you should run git checkout -b <newbranch>. The checkout command changes your local files to a different branch; the -b flag tells it to create a new branch rather than switch to an existing one. For now, that branch only exists on your local machine. You must use the command git push -u origin <newbranch> to put it into the cloud as well.
If you want to update your branch with work done in other branches, you can use the command git pull origin <branchname>. It will create a merge commit which pulls in the new work.
If you want to update the main artstation branch with work done in your branch, please first make your branch up to date with artstation using the above procedure, then make a Pull Request with the GitHub website. If everything looks like it works, we will confirm the pull request and merge it.
If multiple people work on the same branch, you might encounter conflicts. You can resolve it through merging (described below), or you can do a quick fix with the following commands:
git stash - saves your local unstaged changes, leaves you with a clean directory
git pull - pull remote changes
git stash pop - re-applies the changes you made on top of the new code
This re-applies your work without regard for conflicts with new changes. If you're afraid that your changes have broken things, merge instead of doing this. If you've only changed config files, stashing can save you a lot of time.
When you merge branches with git pull origin <branchname>, you are likely to encounter a merge conflict. This is what happens when two different changes have altered the same lines of code. Git will insert flags within each file marking where the conflicts are, so all you need to do is open up those files, fix them up, and save the new version.
It can be troublesome to do this manually, so I recommend pulling Sublime Merge out for these. It will list all conflicts and provides an editor with comparisons between each version.
TGstation has some tools which allow you to automatically merge conflicting sprite sheets (.dmi files). You can read about it here. Since it takes some set-up, you can just ask Jwap to merge it for you.