ID:1327918
 
Foreword:

Hello, there. I understand that I don't really frequent the byond forums too much, but I do manage to get some programming done, even if not as much as I would like. When recently looking through the forums, I found no decent and comprehensive guides to contributing or managing a project on github. This, being a tool that I often use, did irk me a bit.

Therefore, this guide is here to explain what exactly git is, and how it can be used in conjunction to github in order to, efficiently, do a byond project.

Note before beginning that this guide can only effectively apply to development on the 'Windows' operating system.

====== What is Git(hub)? =====================

Git is a sort of version control that allows you to more simply collaborate with other developers or even simply work on your own code in an organized fashion.

Github is an online service where you can upload your files into a public (free) or private (paid) repository for other individuals to be able to view, 'fork', or manage on their own.

====== Setting Up a Project ==================

You'll need to ensure that you have git installed onto your computer. You'll need to get git in order to do any of this. In order to acquire it, you should go to the following link, which should start the download for you.

Git Download Page

As said by Github itself:


You'll need to make certain that you have set up a proper github account. You can sign up for one on the homepage of github, accessible via the following link.

Github

Once these are complete, you should likely create the repository on github. In order to do this, log into your account on the website and look towards the top right of the screen in order to see this. Click the link shown-- "Create a new rep"



You'll come onto a new screen. In this one, you need to type in the name of the repository where it asked for the repository name (simple enough), add the description, and make sure to initialize it with a readme. Over all, the screen should look something similar to this.



And, just like that, you now have the project created inside of github, ready to be prepared.




====== Setting Up a Project for BYOND ==================

Now comes the actual preparedness part. Navigate to where you would like your project to be, within its own folder. Then, right click and select, "Git Bash", which should be in the context menu.



A small terminal will come up. Here is where the majority of your git interactions will go. Since you should already be navigated to your folder, you can simple type in the following:

Note: Case is important, here!



Once you have done so, you can open up the folder. You'll see README.md-- Feel free to ignore it for now. Now what you need to do is open up dream maker and create a Dream Maker environment inside of the project's new 'git' folder. Once you have don so, you should look back on it and create a new text file named, ".gitignore", without the quotations. Do not forget the period.

Open up that file and then add the following lines-- I'll explain what it does after.

*.int
*.rsc
*.dmb
*.lk

This means that when making commits, those files and any changes to them will be ignored. The reasoning for this is because you don't want to be committing the compiled files onto github-- It's for the code itself, where other people can compile it on their own computer. You should add to this file anything that you don't want your changes to to be added onto the main repository.

Now that you have done this, it's a good idea to open up the dream maker IDE, move your cursor to the top left, and select the 'Build' drop-down menu. Select preferences. You should then do one of two things. Either...

Uncheck the 'Automatically set FILE_DIR for sub-directories'

OR

Hide the path from the object tree, ".git/", which should work.

Why? .git will be a hidden file within the folder that stores all of the git information. If you don't do this, the object tree may become confused by .git and issues might occur. I personally prefer the first action, so that I have to fully define the path to a resource, but that isn't everyone's preference.

Afterwards, you can go back and look at the readme. Feel free to edit it about in order to give an explanation of the project, or information such as that. If you want to license your game under a specific license (ALWAYS a good idea), I recommend this website for ease of licensing and easy explanation.

Choose a License!

[NOTE!]
You're also capable of using an existing project like this. If you would like, instead of creating a new environment there, just move the files into the folder that you cloned in, add the .gitignore and set-up the readme, then proceed to go hide .git/ or uncheck automatically set FILE_DIR, then continue on to the next section.

====== Committing and Pushing/Pulling ==================

And with that, your game has been prepped. Generally, now would be a good time to go ahead and create a 'commit'. In order to do this, go back to git bash. You can then type in the following command,



'git status' tells you the status of the current branch that you're on. You'll note the untracked files, such as .gitignore and defaults.dm-- You'll need to get these tracked. In order to do so, simply type in:



'git add -A', which will stage all of the files. You're now ready to commit them. Simply type in, 'git commit', which will result in a text file being opened up inside of the vim text editor.



What you need to know here is that you can press, 'i', or, alternatively, the 'INS'(INSERT) key, in order to begin typing words. Go ahead and do that. At the top line, just give a brief and concise explanation of what the changes were, then press enter four times to make four empty lines, and then give a more in-depth explanation of the commit. Once you have done so, press the ESC key, and then type in ":wq", which will write to the file and then quit vim.

You've now performed a commit and prepped up your game. In order to get it back onto the remote repo on github, you'll need to type in the following command:



'git push origin master'

It'll ask for your username and password on github-- Go ahead and type both in. You'll note that you can't see your password typing, but it will type. What the command does is push every commit to the 'origin' remote repository (Where you cloned from!), and then the 'master' branch of that repository. All of your changes can now be seen, and pulled, directly from github. Go ahead and check it out on the website.
===== Forks and Updating Forks ==========

Alright! You can actually make your own project now, and work with it, but-- How do you contribute to one that someone else has? Or, even better, how can you ensure people can contribute to your own?

Well-- Github provides an excellent service to let people 'fork' a project. This basically sets them up to have their own repository that is linked, and based, on yours. In order to do this, you just navigate to the project page, and...



Press the button! Once that happens, it'll take you directly to the fork. The URL will be your new fork. Generally, it's a good idea to make a clone of your fork if you have a fork, rather than the regular repo, so that your remote, 'origin', will be set properly. Simply go and make a clone of your fork the same way that you would've made a clone of the regular repo...



And `voila. You now have a copy of your code. Why is it special, and why do you need a separate fork from the original posting? Well-- From it, you can put your local changes onto the remote repo for anyone to view as they want. This allows for easy and simple code review.

You can push to this fork by pushing to the origin just as you would a regular one. That said-- Your fork will not be kept up to date automatically with the base repo. You'll need to update it manually. In order to do this, you'll also need to set up another remote URL. Upstream!



Remember to not put your own url for that, but rather, the URL of the main repo. Then, in order to pull in any changes from it...



The branch name is usually going to be simply, 'master'. Feel free to view the branches on github if you want to see the different ones. That command will cause your specific local repo to be updated, via 'fetching' then 'merging' the 'upstream' branch (that you just set), to whatever the upstream's additions are. If you get a merge conflict, there'll be a section in the guide explaining how to handle those, but for now simply go to the bottom and ask on the IRC provided or ask in the forum post.

===== Branches, Rebasing, and Merging ==========

(( I /highly/ recommend this interactive guide instead for learning this! This little tutorial part can't hurt, though. http://pcottle.github.io/learnGitBranching/ ))

One of the most important detail about developing in git is branches. It is practically needed in order to ensure that you are using git to its full capacity-- Allowing you to always have a stable branch (master!) as well as ones where you are working on specific things!

Basically, a branch just saves the commits that have been performed on it, and can be access/viewed simply by using the git checkout command. Let's make and try one!



This'll checkout a new branch immediately using the name, "BRANCHNAME". You can, of course, put any name you would like there (though short, descriptive names are best!) You cannot have spaces in the branch name. Now that you're on this branch, you can make any edits and numbers of commits that you would like, and be able to view the original branch (WITHOUT your edits/commits) by typing...



Causing you to look at that branch instead! Again, any change you make here won't be shown/appear on other branches. You cannot switch branches without making a commit (and therefore, having no modified files that aren't committed), or stashing the commits. Stashing the commits is simply using the, "git stash" verb.

But-- What if you want to say, update master with your changes? It should be pretty simple! Just type in the following while checked into the branch you want to merge into another.



That said. It will give our commit history a less clean look to any observers. So! Usually, you'll want to rebase instead-- in order to do this, checkout master...(The one you want to rebase)



And then use the following command:



Which will rebase master into the update, causing the commits from it to be placed into master directly in its commit log-- A much cleaner history!

(( NOTE! Merge Conflicts are possible here-- I'll write a section over handling them, but for now it is better to simply go and ask on the IRC or elsewhere from someone who has more experience, or googling the isuse. ))

===== Pull Requests -- Contributions ============

Finally, in order to actually contribute and get your changes to the main repo, you're going to have to make a pull request. Simply push your changes to the origin like this once they have been committed, from the branch where the commits are...



You should replace BRANCHNAME with the name of your branch that you want pushed, and then replace TEST with what name you want the branch to have on github. You can now view it on github, like so:



Now that you have your proper branch with your changes, you'll need to create a pull request for the maintainers of the project to view. In order to do this, go on github and click on 'Pull Requests' on the side.



Then the aptly named... "New pull request" button:



If it isn't showing it from your fork, you should press the 'compare across forks button'



From here-- the head fork will be the one that you want merged into the base fork. This means that you'll need to press the buttons provided in order to 'compare' the two forks, and then press the provided button to create a pull request.







Now that it's made, you can just press the pull request button from earlier in order to view it!



Once it's made, other people can review all of the changes, and the maintainers can merge it into the main project by a simple button found once you click on it. Remember to look at the feedback you get, and address it as best you can!
RESERVED-- FURTHER GUIDES
Useful Links and Such:

Learn Git Branching - Excellent resource of learning how to manage branches and individual commits on git.

==== Notes ==========
Incomplete guide! For now, if you have any further questions, feel free to ask on the following irc:

irc.sorcery.net (port 6667, the default)

#codershuttle

Where we'll try to answer your questions as best as we can.

Have a nice day, and enjoy building your own net dream.
Very helpful!
I haven't found a good reason to stick to using the default Git bash over a GUI like Tortoise Git, which handles a lot of the monotony for you.

Albeit, this is still pretty insightful for someone familiar with Git already!
I agree about the usage of TortoiseGit. In the coming week, I intend on making an addition to this post to outline the basic usage of it if Decius doesn't already beat me to it. :P
I like knowing the command-line stuff so that I can do it via a terminal. Consider learning both.
TheLionsRoar: That would be highly appreciated if you would actual like to do so. I was planning to do it myself, but regardless, it always helps to serve for my laziness. :P

Anyway! I considered using TortoiseGit in the basic learning, but to be honest, I consider command line to be a bit more important. It may be a little bit of my personal preference leaking in, but I suppose that's unavoidable.

Otherwise-- I'll make sure to expand the guide to quite a few more things. I want to make it comprehensive and simple for someone who doesn't understand git. :P

Either way, I will make sure to go over gitGUI, since it is included in the git basic installation that I provided and it is incredibly helpful for new people who want an interface.

Any specific questions, feedback, criticism, or yelling of how horrible I am is perfectly allowed and appreciated. ~
The argument mostly for getting familiar with the git CLI is that, particularly in fluid collaborative environments like github, there will be plenty of non-basic things you want to do, that the git CLI will do very easily, but git UIs traditionally make a royal pain of, assuming they can even manage it.
I've added a section to the fourth post-- For useful links and the sort. Feel free to mention your own. I'll be updating the guide with the next section tomorrow and I'll make sure to maintain the guide as changes come.
To simplify this, if you're using Github, why not use their Windows client? It makes it painfully easy!
http://windows.github.com/
To be honest? I didn't personally like the windows client for it-- that said, I'll add the link to the list.
Updated it with another section! The next section should cover a lot of the better parts of github-- organizations, issues, milestones, ranks, tags, and the sort. After that I'll try to get a nice merging one up. If TLR makes a guide over the tortoisegit GUI, I'll link to it and I'll be writing a guide over the git GUI separately, and link to it as well. I'll also make sure to... fix up this guide in a few areas where it was hurried.
I prefer using TortoiseSVN and Assembla, personally. I like Assembla's free team/project management features. Not to mention TortoiseSVN makes things super easy to update/commit/merge, etc. with multiple team members or even if it's just myself.
The git/github thing is much more about open collaboration, where you don't have to give all/any team member direct access to push to the remote repository, you can review their code before it goes in etc.

It works particularly well for libraries, open source games or situations where you basically don't want everyone with full access to everything. Assembla's project management and planning tools are better than github's by a country mile, for closed team development, and they do have git support, also. If it were a private project, and I was willing to spend a bit a money, Assembla Scrum/Agile + Git would be my preferred choice I think. For say ... Chatters, Github + Git is a hands down obvious winner.