All you ever wanted to know about Git in UE4 but didn't know you had to ask

Part 1 - Getting to know Git

After UE4 .7 there is a plugin integration by Sebastien Rombauts that lets you run source control for your project using Git. It's not immediately obvious what needs to be done to use this within UE4, but here's an overview. There's various setting up documents to plod through if you're a reluctant user of Git, like me (and Hitler).

Possibly you already have used GitHub in order to grab the source code of Unreal Engine. Well, that's fine, but it's not what we want for setting up version control. Instead (or as well), download GIT : http://git-scm.com/downloads

Set that up, and then in UE4 you can go File > Connect to Source Control and specify that binary of Git that you just installed to manage your version control.

The whole point of Git version control is to use an online repository (it's an incremental cloud back up essentially) so you'll need to choose between a public one hosted by GitHub or a private one. In all likelihood you'll want to keep your content (or possibly the tools you're using inside of UE4 like Marketplace content or your own secret sauce) hidden, so what you can do at this point is jump onto BitBucket.org where you can create a free private repository. This isn't explained when you log onto github and see their private-repositories-for-$7-per-month link.

After creating an account on the BitBucket.org website create an empty repository there with a catchy name. Then on your PC, locate the shortcut to run GitBash and fire that up. GitBash is a command line tool installed with Git. A hacker would probably feel comfortable using it to control satellites in orbit. For me, it's something I only want to use if I really have to. Now, on the BitBucket website you'll see a little snippet which tells you how to upload your existing local project (that you connected to Git from within UE4) to BitBucket. You just need these two lines:

First type into GitBash's prompt

$ git remote add origin https://youraccount@bitbucket.org/yourRepo/yourRepo.git

This connects you to your BitBucket account from your Git repo locally

$ git push -u origin --all

This sends all your project up to BitBucket, which may take a good while, but you get to watch the percentage/bitrate tick over (and write blogs like this one) in the meantime.

If typing that is too scary, you can try using SourceTree (from https://www.sourcetreeapp.com/), which is promoted by BitBucket as a nice way for 'artists and designers' to control their repository for free using a compelling 'tree-like' GUI tool set. It will pull your local project to BitBucket for you (fundamentally the same way as using GitBash though) after you install SourceTree and login with your BitBucket account details.

By now you have UE4, github, git, bitbucket, sourcetree installations (and visual studio) to worry about. I'd suggest adding a browser bookmark folder to hold shortcuts to refer back to each of those. It's a lot to absorb in one sitting, though I managed so it can't be too hard.

When you're done settings those up and log into SourceTree you can add an SSH key (https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Git). This is really well explained on the webpage above, and is a desirable step, essentially exchanging having to enter a login/password every time you use SourceTree for having a machine-locked identity that handshakes with the BitBucket website (in simple terms). If that is too deep, you can skip it. Just don't forget your login credentials. In short, you can generate an SSH key pair in SourceTree in the Tools > Launch SSH Agent section, and apply the public key info in BitBucket in its Settings > Security section.

Part 2 - What to do with all that?

My first impression is that Git is aimed at forward merging of content, especially by collaborators on a project, knitting together bunches of new content, whereas Perforce and Alienbrain are strong at backward merging, restoring, missing, deleted, and otherwise fudged up files to their earlier goodness. The trick is to reconcile both of those directions (and I'll update my first impression when the murk clears).

This tool is still in development. Make sure you are using UE4.8 if you want to try the latest features : See the forum posting by the plugin author : http://bit.ly/1ckPWMl

At present, the Git plugin for UE4 can commit changes (to files) in the local repository, can show you the history of changes, but cannot internally roll back (or revert) changes if you decide you've screwed things up and want to go back in time. Diff Against Depot, which is a method of comparing differences between files to see what was changed from one state to another, doesn't work, and Merging changes, which is a sneaky method of combining content best thought of as black magic, doesn't work (yet). Essentially you have a shortcut to adding and updating files in the git system building onto the commit history. This simplicity probably serves well enough most of the time, but maybe without the level of checking and double-checking that an advanced user might rely on. Just be sure to name your commit changes (which is required) clearly so the history remains readable after some time has passed, so you can recollect what was what with files when you're tempted to revert. It's hard to differentiate changelogs such as uh and um and agh.

Going back to the start, it's hard to know, at times, what tools to learn. When git first came out it seemed like a tool for people who were too smart for their own good, who wanted a designer look to their code (though that is fair enough compared to working with just a command prompt for company). Github was presented in the then strange looking hipster fashionista style of app where they clearly studied some style guides in their visual communications classes, with its cat silhouette icon and its minimalist fonts and quirky terminology. A while ago, Perforce was the main integration of source control software in UDK and UE4. Then Subversion was added. A lot of people use TortoisesSVN, AlienBrain Essentials or bazaar, all of which integrate into Windows explorer, and manage their project files outside of the game editor. Which is better? Well, that's a matter of experience mainly, and it's like debating whether Max or Maya or Modo are better for 3D. If you're a beginner, go with whatever one gets you working fastest. In my thinking, Git is nice in that you can easily put your live project files in the big ol' tank of cloud storage. Just remember that you trade 'access anywhere' for 'takes time to upload'. Should your PC blow up, you won't lose all that hard work. On a more day to day level, if you're working Blueprint gets all messed up and you're not sure what went wrong, you can always call back the working copy you committed. For now, I'm not sure how future UE4 releases, git updates, and changes to the UE4 git plugin will change and permutate in ways that may make keeping things up to date easy, but the fact that Epic Games promotes UE4 releases using git says something. What's nice is that all of that can be done for free.

You will want to learn to distinguish the 'git terms' in order to not feel bogged down.

What I've written here is possibly wrong and certainly badly expressed, but it'll alert you of terms used in git repository management.

Pull - takes altered or new content from there to here, or set your PC to match the online version
Push - takes altered or new content from here to there, or set the online version to match what's on your PC
Commit - locally submit files with a changelog name
Fork - a hip way of duplicating repository content between users (but online)
Clone - just copy the entire repository wholesale to your PC
Fetch - like pull, but gets the changes commited by others from their repos
Branch - keep some files in a state different to the master state of the project, like if you aren't sure of something and want to try it out in a safe way first
Merge - 1. in git, updates files in the working tree to match the version in the index or the specified tree.
Merge - 2, amalgamate the differences in a file worked on by two different people (ie, add your changes + their changes and address any conflicts ... basically it's black magic that works easier with text than with art assets)
Rebase - kind of like revert or, um, merge, but for stuff you've done yourself (https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
Tag - a way to rope together a bunch of files to handle apart from others, a bit like grouping
Checkout 1. - navigates between git branches (a sort of advanced way of flexibly running more than one state of the project but which needs to be reconciled at some point) as being in use by you currently (can be used to prevent others working on the same file you are working on)
Checkout 2. - a more local situation, where you make a file workable by you (more of a term for Perforce or Alienbrain)
IgnoreList - project files you know you won't need to keep updating such as autosaves or user settings, which might bog down file transfers
Stash - a method of extracting dirty files out of the current state of the repo in order to clean it, which can later be added back in again

So how do you actually get a file back to a former state where it was what you wanted, or closer to what you want. Say you have a white mushroom, then you made it green, and now you want the white version again (going backward rather than just making it white twice). To revert, you can try (in SourceTree) the Reset Branch to this commit command. But how does that update the content in UE4?

Questions to figure out

How to get out of binds that occur? This can be complex in any version control.
How to remove a branch we no longer want locally and remotely? [This is easy enough so long as there aren't currently files waiting to be commited, such as autosaves and user settings data].
How does just deleting a file locally effect its presence on the repository?
Can one view a history of changed files from within UE4 or must one jump to the repo browser, SourceTree or BitBucket? [You can view a history, but not do actions based on it].
Can one check that reversals don't delete files you still need?