Minecraft Forge Publishing To GitHub Using SourceTree

Introduction and Background

Some people who practice Minecraft modding don't have formal education in programming, so this may be helpful for them.

In computer programming, once you try programming for a while you quickly run into three problems:

1. Sometimes you make changes you wish you could undo.  And not just last change, maybe undo back to a time when you knew it worked previously.  
2. You may want to start collaborating with others (working on other computers, possibly physically remote), so need a way to allow two people to edit the same overall project without causing confusion.
3. You may want to work on your same project from multiple computers.

While general file backup and cloud sharing have greatly improved in the past few years such that you could probably combine them to solve these issues, the best way to put these together is to use a "version control system" purposely made for collaborating on programming projects.

Tip: You should use a version control system to ensure you can roll back history of your program and collaborate (including with yourself on multiple computers).

There have been many such systems developed over the years, and one that has become quite popular lately is a modern, open-source implementation called "git".  Git is great, but it was created by those "open source geeks" who are perfectly comfortable rooting around file systems using the command lines.  Furthermore, it is quite powerful and integrated into your file system so you need to ensure you understand what you're doing before cloning and cleaning repositories.  So it can be a little daunting, even dangerous, for a casual user to infuse their family computer with it.

So, while "a real programmer" might be expected to use a command line there have also been a few GUIs created to help operate git.  The one that I use and recommend is free, is available for Windows and iOS, called SourceTree.

SourceTree will make it easy to use git, but you still have to associate your repositories with a cloud host.  I use the free cloud service called github.

This tutorial further explains how to set SourceTree up to sync your Forge modding projects with github from a Windows PC.

Note: There are many other combinations possible.  SourceTree can work on a Mac, and can work with a different revision system called Mercurial.  It can also access bitbucket and other cloud services.  All these combos are valid and probably similar to set up, I just don't have experience with them.

Getting Started

I'll assume that you're already a modder so already have a Forge workspace and one or more Eclipse/IntelliJ projects created.  If not, please look up tutorials on that!

Create a free github account at github.com.  

Note: Do NOT create any repository on github (we'll be doing that from within SourceTree for your existing projects later.)

Download the installer for the latest version of free SourceTree appropriate to your operating system from: www.sourcetreeapp.com

Note: Do NOT download git itself or install it -- we'll be using the embedded installation in SourceTree.  (You can use SourceTree with your own git installation, but that isn't the approach of my tutorial.)

Install SourceTree

Run the SourceTree installer with the following considerations:

• Choose the "embedded" version of git.
• Do not configure Mercurial (that is a different version control system that we're not using.)
• Enter information appropriate to your github user access.

Add Your Projects As Working Copy Repositories

When your finished the installation, run SourceTree.  Now you can take your mod project directories and add them as repositories.  You can do this by dragging the folder over the SourceTree GUI, or you can hit the Clone/New button.  I'll explain the latter,

• Create working copy (local) repository:
• Click on the New Repository tab.
• Choose git as the Repository Type
• For the Destination Path, hit the ... button and find your project folder.  Once you select that folder, it should populate the rest of the fields in the tab.
• Make sure the Bookmark This Repository is checked. (It should be automatically.)
• Hit the Create button.

It should work for a second and the project should appear as a "bookmark" in the leftmost pane of the SourceTree application.

Understanding A Bit About Revision Control

There are a lot of scenarios and workflows you can use with revision control, but I'll assume that you're doing a small-scale project with just yourself, or maybe a couple others, programming occasionally.

What you need to understand is that the revision control is going to let you work on a local version (i.e. stored on your computer) working copy until you've made changes that you think are worth saving.  At that point you will need to add those files to the staging, and then "commit" them as a change (with comments describing the the changes to aid other collaborators).  At that point (after committing the changes) you have achieved revision control (you can go back to earlier commits if you need to) but have not yet published to github.  To do that you need to "push" the repository back to the cloud. 

Key Point: You don't want to revision control all the files in your Minecraft Forge mod directory because it will pick up all sorts of files that aren't yours.  Only revision control your own source and asset files, plus anything special to re-create the build. (Otherwise it will waste space and upload time.).  To control this, you want to instruct git to ignore files; you specify this with a gitignore file.  (I'll explain this below).  It is critical to setup a good gitignore to make the revision control manageable and efficient.

First Commit and Push

All you've done so far is associate your Minecraft Forge project with a local repository -- this repository still needs to be staged, committed and pushed.  You can do that as follows:

• Bring repository into application focus:
• Double-click the bookmark for the repository you just created.  It should bring focus to a tab that show panes called "staged changes" and "working copy changes".  
• Now all the buttons and menus will for controlling this selected repository.
• Tip: When you have several repositories, it is important to ensure the tab for the repository of interest is in focus.

• Set up gitignore file: 
• Set up your gitignore file for the repository by selecting Repository menu, select the Repository Settings, then Advanced, then Edit for the gitignore file.  A text editor should come up (or Windows will ask you to choose one, WordPad is fine). and I suggest you enter something like the following into the file (this will include your custom source and asset files, your build.gradle and .project files):
• # eclipse
• bin
• *.launch
• .settings
• .metadata
• .classpath
• .project
• # idea
• out
• *.ipr
• *.iws
• *.iml
• .idea
• # gradle
• build
• .gradle
• # other
• eclipse
• run
• saves/
• config/
• options.txt
• usercache.json
• usernamecache.json
• logs/
• crash-reports/
• *.launch
• # Minecraft
• minecraft
• Save the gitignore and it should filter the files in the working copy changes pane.
• For more on gitignore rules, see: help.github.com/articles/ignoring-files

• Create remote "hosted" repository (on github): 
• From the View menu, select Show Hosted Repositories.
• Click the Create New Repository button.
• Make sure the Create Repository On Account shows github plus your username (on github).
• Put in a name for the repository -- I strongly suggest that you put same name as your mod folder (assuming you name those well).
• The description, web page and public settings are up to you. 
• Click the Create Repository button.
• Your repository should now show up in the hosted repository list.
• You can close the hosted repository window.
• Important: At this point you should go to the github web site and confirm that a repository with the name you just created appears there.

• Add remote repository to your local repository:
• From the Repository menu, select the Add Remote.
• Check the Default Remote checkbox.  "origin" should appear as the Remote Name.
• Go to github web site and navigate to the repository.  Since you haven't pushed any code to github yet, it should give you a URL.  Copy that URL
• Come back to SourceTree and paste the URL into the URL field.
• That should automatically fill in the rest of the fields.
• Click OK to close the window.
• "origin" should now appear in the list of remotes.
• Click OK to close the window.

• Set remote user credentials: 
• Also in the Advanced Repository Settings, uncheck the Use Global Settings.  (For some reason the global settings causes trouble for me and others).  
• You should have your username for github entered (if not enter it).

• Stage the changes:
• Since you haven't done any commits yet, all the files (filtered by gitignore) should show up in the working copy changes pane.  If you set up the gitignore properly, you should only see files you recognize (like your .java source files).
• Select all your working copy changes (i.e. click on one change and press CTRL-A to select all).  
• Hit the Add button at top of window.  All the working copy changes should move up to the staged changes.

• Make the commit with combined push:
• Hit the Commit button at top of window.   
• In the window that comes up, enter a commit description something like "First commit"
• Note you can combine the commit with the push by selecting the Push Commits Immediately checkbox.
• Click the Commit button.
• It should work for a moment uploading (pushing) files to github.

• Confirm it all worked:
• Go to github web site and navigate to your repository.
• Your repository should now have all your files!

• Adjust your github repository settings:
• You should check the settings for your repository to make sure it is how you want it.
• You can add collaborators here.

Subsequent Changes

The initial setup does have a fair number of steps.  Once setup though, git (i.e. running embedded in SourceTree) will continuously monitor for changes in the file in your working copy (local) repository.  So if you go to Eclipse or IntelliJ and start doing coding on your mod, if you come back to SourceTree and select that repository you should see the changes show up in the Working Copy Changes pane.

Tip: You can just have SourceTree running while you code, and then it is easy to frequently sync your changes.

Whenever you've done coding that you think is worth saving, which should be fairly often, you will want to stage them then commit with push.  Pretty much the same as the last steps we did before:

• Add remote repository to your local repository:
• From the Repository menu, select the Add Remote.
• Check the Default Remote checkbox.  "origin" should appear as the Remote Name.
• Go to github web site and navigate to the repository.  Since you haven't pushed any code to github yet, it should give you a URL.  Copy that URL
• Come back to SourceTree and paste the URL into the URL field.
• That should automatically fill in the rest of the fields.
• Click OK to close the window.
• "origin" should now appear in the list of remotes.
• Click OK to close the window.

• Stage the changes:
• Since you haven't done any commits yet, all the files (filtered by gitignore) should show up in the working copy changes pane.  If you set up the gitignore properly, you should only see files you recognize (like your .java source files).
• Select all your working copy changes (i.e. click on one change and press CTRL-A to select all).  
• Hit the Add button at top of window.  All the working copy changes should move up to the staged changes.

• Make the commit with combined push:
• Hit the Commit button at top of window.   
• In the window that comes up, enter a commit description that explains the changes in this commit, e.g. "added an event handler for player rendering"
• Note you can combine the commit with the push by selecting the Push Commits Immediately checkbox.
• Click the Commit button.
• It should work for a moment uploading (pushing) files to github.

• Confirm it all worked:
• Go to github and navigate to your repository.
• Your repository should now have all your files!

Cloning The Repository On Different Computer

If you properly hosted the gradle files within your github repository, then it should contain all the information to rebuild your project structure on different computers, as follows:

• Clone the remote repository to your computer:
• With SourceTree hit the Clone/New button
• Click the "Internet" icon  next to the Source Path / URL field.  
• It should allow you to browse to github and find your repositories.  Select the one you want.  Ensure that the Bookmark This Repository option is selected.
• Click the Clone button.
• It should work for a moment downloading (pulling) files to your local computer.
• Set up the Forge decompiled workspace:
• Navigate to the workspace and open a command console in the project folder.
• At command prompt, issue command gradlew setupDecompWorkspace.
• It should work for a couple minutes and hopefully complete sucessfully.
• Issue command gradlew eclipse (or Intellij depending on your IDE of choice)
• It should work for a couple minutes and hopefully complete successfully.
• Import the project into Eclipse (or IntelliJ):
• In project explorer, right-click and choose import.
• In the pop-up choose to Import | Existing Projects Into Workspace
• Browse to the root directory of your modding workspace, and it should find the project.
• Click Finish button
• Check that the project seems to match your original project.  
• It should generally look the same as on originating computer.
• It should give added annotation in the Eclipse project explorer view showing it's relationship to the repository.  
• It will also show a > symbol on any parts of the project that have changed and need to be synced back to remote host repository.
• Update the gitignore
• In SourceTree, update the gitignore just like described in setup for original repository above.
• Check that SourceTree thinks everything is synced.
• The repository initially should show that there are no differences between local and remote repository.

Further Thoughts

There is a lot more you can learn about using SourceTree, especially related to collaboration and related to branching and merging code.  But hopefully this gets you off to a good start, and for many modders this may be all you really need (syncing to github).