GitHub User Guide and Tutorial

[Akiba]

GitHub User Guide and Tutorial

What is GitHub?
How does it work?
Sounds great! How do I start?
Git Reference

[a id]whatisit[/a id]

What is GitHub?

GitHub is an online version control service centered around fast, reliable, safe, and collaboration-centric development. It is used as the fundamental code versioning system for enormous and successful open source projects such as the Linux Kernel, Apache, and Mozilla. However, it is also home to over 2 million other projects, all created and developed by people who want to make the world a better place.

[a id]howdoesitwork[/a id]

How Does It Work?

GitHub takes your code, files, ROMs, or anything else, and manages a tree of changes, so that any changes can be tracked, reverted, merged, or refactored in an ever-growing variety of ways. GitHub will give you unlimited space for your development (as long as you use it in the intended way). The very nature of unlimited space means that your previous work will never be deleted. With GitHub, you will never lose your progress again! In fact, failure to back up and correctly track and manage project files is the number one reason that an electronic project is halted. Unfortunately, that applies to most hacks started on Pokecommunity.

[a id]howtostart[/a id]

Sounds Great! How do I start?

For this tutorial, I'll be using my GitHub details. Please use your own details when following the steps.
Username: pokecommunity
Email: [email protected]

First, let's make an account.

Once that's done, Let's try forking my fork of veekun's Python Pokedex by clicking the 'Fork' button on GitHub.
Now you have a working copy of a Python Pokedex, that belongs to you, and you alone!

At this point, you'll need to install Git Git is all you'll need to use GitHub, but if you're a Windows or Mac user, you can also download their respective GitHub clients to complement. That said, I'll also be including the command line equivalents of each step for you Linux and CLI users.

$ apt-get install git

# or

$ pacman -S git

# or

# Installation for other distributions found here

$ git config --global user.name "pokecommunity"
$ git config --global user.email "[email protected]"

Now, it's time to clone the repository on your computer, so that you can work on it. Click on the 'Clone in Desktop' button in GitHub.

$ git clone https://github.com/pokecommunity/pokedex.git

# /your_username/repository_name

$ git remote add upstream https://github.com/veekun/pokedex.git

# /parent_author_username/repository_name

Once you have modified the source to your heart's content, you can send your changes back to GitHub, with your GitHub client. Feel free to throw in a summary.

$ git push origin master

You've updated your code, and now it's on GitHub, along with your project's previous states! Everything will always stay there, and you will have a complete history of all of your actions and progresses. You can compare files with a text or binary diff comparison, track development status, and even keep your intended customers up to date. GitHub allows for an unlimited number of people to work on a project at once, as well.

If you would like to commit back to the master repository, GitHub allows for a 'Pull Request'. It's a bright green button that you can't miss. :)

Note: Binaries or anything that can be built from sources should not be versioned. For the special case of ROMs, it is recommended to version patches, which can be automated with a build system.

More coming soon.

[a id]reference[/a id]

Git Reference

# How to create a repository

# Create folder myrepo

$ mkdir myrepo

# Enter folder myrepo

$ cd myrepo

# Create folder master

$ mkdir master

# Enter folder master

$ cd master

# Initialize Git repository

$ git init

# How to add files

# Add all files

$ git add *

# Add individual files

$ git add myfile.ext

# How to commit changes

# Commit and stage all changes with a message

$ git commit -a -m "Updated looping function, refactored program stucture"

# How to branch and merge

# Copy current state into new branch mybranch

$ git branch mybranch

# Change current branch to mybranch

$ git checkout mybranch

# After changes confirmed and ready to move back to master

# Change current branch to master branch

$ git checkout master

# Merge mybranch into master

$ git merge mybranch

# How to push changes

# Push all changes to branch master on origin repository

$ git push origin master

Good? Now go make some amazing hacks and hacking tools!

 

[com3tiin]

Until now I realize how this works ...

I'll try and comment later.

 

[esperance]

Ah, this is very helpful!
You do a nice job of explaining this, which can be very confusing to new users.

 

[ThomasWinwood]

I can't find anything particularly authoritative, but everything I can find says Git is a poor choice if you're using it to version-control binary data like ROM hacks, because it's optimised for text which can be diffed and so on easily. You can't solve a merge conflict in a binary file.

Unless Git provides some specific functionality which you need, you should give serious consideration to just using a folder on Dropbox and saving copies (or perhaps sequential IPS patches) of your ROM hack with a revision number in the filename before rushing to use Github. When knizz produces a text file which you can feed into GNU as and get out a binary file identical to the original FireRed ROM, we can all start using that to make ROM hacks and put that on Github.

 

[Akiba]

I can't find anything particularly authoritative, but everything I can find says Git is a poor choice if you're using it to version-control binary data like ROM hacks, because it's optimised for text which can be diffed and so on easily. You can't solve a merge conflict in a binary file.

Unless Git provides some specific functionality which you need, you should give serious consideration to just using a folder on Dropbox and saving copies (or perhaps sequential IPS patches) of your ROM hack with a revision number in the filename before rushing to use Github. When knizz produces a text file which you can feed into GNU as and get out a binary file identical to the original FireRed ROM, we can all start using that to make ROM hacks and put that on Github.

Yes, it is true that it is nearly impossible to resolve a binary conflict, but at the very least, ROMs can still be versioned. A serious group of hackers would not be afraid to continuously make copies of 16 to 32 MB files, not on Github, but likely on a team server, possibly configured with Dropbox.

That said, you are right about creating a patch file before committing. I'll add that to the post.

This does in fact lead to knizz's completely source-based ROM. I can safely predict that hacking will evolve into either something like that, or a system where only the original ROM and most current builds are preserved, and whenever a ROM is to be compiled, a project directory with a Makefile or something similar can be built from scripts, resources, etc.

 

[ThomasWinwood]

I can safely predict that hacking will evolve into ... something like that

It already has - check out Sonic Retro's GitHub page. We call them split disassemblies, because they're disassemblies with the binary content - graphics, sound, etc., anything that isn't machine code - split out. It just hasn't happened in the Pokémon community yet, probably because few people in this community are anywhere near as dedicated as Nemesis. (It hasn't happened in the Mario hacking community either, because FuSoYa made an editor which can do anything they would ever want to do and discourages people from ever looking under the hood.)

 

[Akiba]

It already has - check out Sonic Retro's GitHub page. We call them split disassemblies, because they're disassemblies with the binary content - graphics, sound, etc., anything that isn't machine code - split out. It just hasn't happened in the Pokémon community yet, probably because few people in this community are anywhere near as dedicated as Nemesis. (It hasn't happened in the Mario hacking community either, because FuSoYa made an editor which can do anything they would ever want to do and discourages people from ever looking under the hood.)

Well, then hacking hasn't quite yet evolved, has it? :pink_wink:

 

[miksy91]

We have disassemblies for hacking Red and Crystal too, but not for the others.

It would be kinda hard to imagine one being made for any gen III pokemon game though; A-Map, XSE, assembler, debugger and a hex editor are all you really need as long as you know how to use them.