Go Back   The PokéCommunity Forums > ROM Hacking > Tools, Tutorials & Resources
Reload this Page [Tutorial] GitHub User Guide and Tutorial

Notices
For all updates, view the main page.

Tools, Tutorials & Resources Various tools to help you develop your hacks can be found here.
New threads in this forum are to be approved by a moderator before they are displayed.



Reply
 
Thread Tools
  #1    
Old February 18th, 2014 (05:21 PM). Edited April 16th, 2014 by Reisen.
Reisen's Avatar
Reisen Reisen is offline
Crystal Tier
 
Join Date: Mar 2011
Location: 30.46°N 128.92°E
Age: 15
Gender: Female
Nature: Quiet
Posts: 3,101
Send a message via Skype™ to Reisen
GitHub User Guide and Tutorial
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.
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.
Sounds Great! How do I start?


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.
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!
__________________
Reply With Quote
  #2    
Old April 11th, 2014 (03:08 PM).
com3tiin's Avatar
com3tiin com3tiin is offline
Soy chamber...
 
Join Date: Jan 2013
Gender: Male
Posts: 110
Until now I realize how this works ...

I'll try and comment later.
__________________
Reply With Quote
  #3    
Old April 13th, 2014 (06:36 AM).
Hopeless Masquerade's Avatar
Hopeless Masquerade Hopeless Masquerade is online now
カミツレ
Silver Tier
 
Join Date: Mar 2010
Location: Nimbasa City
Age: 18
Gender: Female
Nature: Lax
Posts: 1,117
Ah, this is very helpful!
You do a nice job of explaining this, which can be very confusing to new users.
Reply With Quote
  #4    
Old April 15th, 2014 (01:45 PM).
ThomasWinwood's Avatar
ThomasWinwood ThomasWinwood is offline
 
Join Date: Nov 2013
Gender: Male
Nature: Relaxed
Posts: 40
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.
__________________
The rival in Red and Blue is called Green. Gary is some character from a lame cartoon.
Reply With Quote
  #5    
Old April 16th, 2014 (08:20 AM).
Reisen's Avatar
Reisen Reisen is offline
Crystal Tier
 
Join Date: Mar 2011
Location: 30.46°N 128.92°E
Age: 15
Gender: Female
Nature: Quiet
Posts: 3,101
Send a message via Skype™ to Reisen
Quote originally posted by 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.
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.
__________________
Reply With Quote
  #6    
Old April 16th, 2014 (10:03 AM).
ThomasWinwood's Avatar
ThomasWinwood ThomasWinwood is offline
 
Join Date: Nov 2013
Gender: Male
Nature: Relaxed
Posts: 40
Quote originally posted by DeltaSalamence:
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.)
Reply With Quote
  #7    
Old April 16th, 2014 (10:54 AM).
Reisen's Avatar
Reisen Reisen is offline
Crystal Tier
 
Join Date: Mar 2011
Location: 30.46°N 128.92°E
Age: 15
Gender: Female
Nature: Quiet
Posts: 3,101
Send a message via Skype™ to Reisen
Quote originally posted by ThomasWinwood:
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?
__________________
Reply With Quote
  #8    
Old April 16th, 2014 (11:31 PM).
miksy91's Avatar
miksy91 miksy91 is offline
A GB/C Rom Hacker since 2010
 
Join Date: Oct 2008
Location: A small country in the North
Gender: Male
Nature: Relaxed
Posts: 1,299
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.
__________________
My Rom Hack




Learn how to hack GB/C games:

Check my GameBoy/Color hacking videos in Youtube
-The video set uses Pokemon Silver (U) rom for demonstrations
Reply With Quote
Reply
Quick Reply

Sponsored Links
Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump


All times are UTC -8. The time now is 06:15 PM.