Working with Github on a Torque3D project

#1 Prety much fork -> clone -> work in a branch -> merge

I'll copy/paste my observations from a blog of mine:

I manage my own fork such that the master and development branches only contain updates from the remote GarageGames repo, keeping them in a mirrored status. So whenever code gets pushed to the GarageGames repo, I look to the remote upstream to fetch and merge into my fork's master and development branches.

# Get all the commits applied to the GarageGames repo, but do nothing with them
git fetch upstream

# Get on the master branch
git checkout master

# Merge in changes from upstream
git merge upstream/master

# Do the same for development branch
git checkout development
git merge upstream/development

There are other methods of handling this (pull for example), and even some additional options (--ff-only), but I think this is about the simplest way of demonstrating how to update your fork from the GarageGames Github repository

I've seen that some people have wondered why their submitted pull request also contained cumalative changes outside of the request's purpose. "So how do I share changes that I make without forcing a merge of the other changes in my codebase&amp", you ask? The answer lies in how branches can be a useful organizational tool when using Git.

For example, the branch where I do all of my work is myworkingbranch which for this description is based upon the development branch. I then update this branch with merges from my repository's development branch, the origin -- which has already been updated from the GarageGames development branch, the remote.

Once someone makes commit X into the GarageGames development branch, I pull commit X into my local development branch, which is then merged into myworkingbranch creating commit Y. commit Y now contains the contents of all commits since I last merged development into myworkingbranch.

When I want to make some changes myself, I always always branch from the current dev head. I make lots of little changes against development as individual topic branches, and merge them all into myworkingbranch. The process looks something like this:

# Currently on branch myworkingbranch

# Checkout development
git checkout development

# Create topic branch
git checkout -b new-feature

# make changes to files

# Push changes to Github
git push origin new-feature

# Go back to myworkingbranch
git checkout myworkingbranch

# Merge in changes
git merge new-feature

# Push to Github
git push

This results in a commit history that looks something like this, assuming that myworkingbranch was up-to-date with development when I branched:

Where B, C, and D are my commits in the new-feature branch, and E is just the merge commit. This might seem cumbersome, but what it means, aside from having lots of neat little topic branches, is that I can pull-request from new-feature to the GarageGames development branch very cleanly.

I hope that wasn't too confusing! I also hope I'm not getting the Git process completely wrong, but the above works for me, and is a summary of a discussion that occurred between Daniel Buckmaster and myself.

Recap:

• Keep your master and development branches free of your own commits and up-to-date with GarageGames.
• To implement a change, create a topic branch from development.
• Maintain a branch for you (for example, ceport) and merge all your topic branches into it, as well as changes to development from upstream. Don't commit directly to this branch! (Unless you aren't going to pull-request stuff.)

#2 Still too complicated. At the moment I use the "Github for Windows" graphical client for Github windows.github.com/
, it helped me a lot, because it is very easy so far, but I could not find a single tutorial for it. It is kept very simple, just a button for add, clone, sync and commit. He automatically checks for changes. But no advanced instructions how to work with it.

But I think I got it now, before commiting create/change the branch and the commits will go to this branch and not to the main branch.

So I have the master branch that gets its updates from Garagegames and when I do changes to this I change the branch to "mydevelopment" and commit to this, so he keeps them seperated and I don't merge them, so the master stays the same and can be updated from Garagegames?!
Have no idea about that, because this never happened so far to me.

#3 I detest that Github for Windows app... and various other gui based clients; using the command line is the best option.

The reason for developer or "topic" branches is to allow clean pull requests with less of a chance for merge conflicts. If you have no intention of contributing pull requests then it's not something to worry about. In that case Github for Windows doesn't need "advanced" instructions since it only performs the most basic of tasks.

#4 I want to know if it is possible to work with such a gui-client, for advanced commands you can still launch the command line.

#5 The scenario I have is this: I have the forked Torqu3D folder from garagegames, in that I may want to make changes at some time, but at the moment I only work in the Torque3D/My Projects/Uebergame folder, which is supposed to be a seperate repository for my game, because 99% of the time the work takes place only in there.
So I want to keep two repositories, but the second one is inside the first and in both changes take place, from me and from other contributors, the question is now, how I manage that.
Someone suggested to add the Project folder as a submodule to the Torque3D folder, so they can be kept seperated.

Also need to know which files need to be ignored and how, because lots of files get generated that may not really be necessary for others, there is a lot in the "buildFiles" directory after you compiled and in the game folder there is for example the "shaders" thing, which is a lot of files.

#6 You can find the line in .gitignore that filters out the My Projects directory and remove it. Then the next time you commit/push your project will show up within your Torque3D fork under the My Projects directory.

Or: just create a new repository from your Uebergame project. Once you have it pushed to Github then others can fork/clone the project itself.

Look at .gitignore for setting up exclusions.

#7 I would encourage you to use submodules, though I have heard people who I respect say they're terrible. I've really not seen the issue, they seem to work very well for me when I manage projects-within-projects. For example, I'm doing it in a T2D project, keeping each module in its own repo so that others can use them more easily.

I'd keep the script project in its own repo, like I did with Moment.

Also, the purpose of having a 'mydevelopment' branch is so that you always have GG's master and development branches fresh with none of your changes in them. This will make it easier to get official changes. Then, if you like the changes, you can merge them into your own branch.

#8 Now I recreated my repo as an own, without submodule inside the Torque3D from garagegames, seems to work, it was just the graphical client, that refused me to do that, with console it worked, now I understand why people tend to hate the graphical client.

#9 The main problem I have is, that I mostly try to manage big amounts of artwork files that results in a huge size of the repo and that git/github and Torque3D seems not to be suited for that.
There seems to be an inofficial repository limit on github that is 1gb and the initial Torque3D folger with the project is already far over that, even with splitting the Torque3D engine/template folder from the project and adding some unneeded buildfiles to the ignore the initial size is still around 600mb and will likely grow in future.
I have another directory where the working files are kept, so I have Torque3D engine, Project directory and Workfilesdirectory.
And as things seem to be now, I am the project leader and have to manage all this.
So receive updates and push update to all repositorys, Torque3D engine gets compiled into project directory and files from workingfilesdirectory get moved or removed to project directory as needed.
This version control and hosting makes things pretty complicated...

#10 @Michael
This was, if you contribute to an existing project, but any experiences the other way around, for example if you create project yourself and others will contribute?

#11 Heh, complicated indeed. Unfortunately Git (and VCSs in general) don't do well with art files. It's more intended for versioning text. What I've done several times is linked my game directory to dropbox (using a directory junction) and only version controlled the scripts. So you don't get full version control on the assets, but at least they're in the cloud somewhere.

Adding binary files and asset files is what's bloated the main T3D repository (not to mention duplicating the template content... four times...). It's unfortunate, but we can avoid that in our own projects at least.

#12 Version control on artwork is not that bad, since my project is mostly artwork so far and I have a lot of files and they get updated a lot.

It just causes confusion sometimes, because model files for example are text and then git will load them and will check for changes in the code, but you cannot do much with it, since it is just a lot of numbers.
I try to keep all in one repository, since I would have to do version control manually on the artwork and maintain two repositories in total.