Basic Guidelines for Using Version Control

Personal projects:

Just a note, these are more git based notes. You can only commit changes locally with git. That means you have to push things to the repository with other version control, which you don’t always, or can (say, if the internet is down) do. Even when my team uses a different version control system (like SVN), I still use git t control my local changes.

• Make lots of small commits. Commit even, or especially, after small changes that work so that when you go through and refractor everything you don’t end up losing that small change when you have to revert. There’ll be times when something just like this will happen to you and you’ll wonder why it doesn’t work anymore because you didn’t commit that one small change! Trust me: commit small, commit often
• Commit before a major change. Often times while coding you come across times when you know that
• ALWAYS MAKE A COMMENT WITH YOUR COMMIT AND YOUR PUSHES. Sure you know now the reason. You won’t 30 commits down the line and when it comes time that you need to look up this commit, your comment on the commit is going to save you a butt-load of time.
• MAKE THE COMMENT MEANINGFUL! Seriously, don’t make stupid comments unless they are coupled with a real reason. I don’t care if it’s “Iteration 15: tried -20 instead of -15”. COMMENT SMART! Seriously! Especially if it’s a working version before a big change, “Simple working version. Commit before adding more sophisitication.” You can even let yourself (and your team) know when a commit isn’t quite there, “Not a working version, but need to refractor and want to commit before the big change.” COMMENT, COMMENT, COMMENT SMART!!
• Branch often! This isn’t something someone using source control like perforce or SVN (do people still use SVN?) would tell you to do because the cost of branching in other version control systems is high. However in git it’s simple and this is where the power of git comes in. Keep separate branches for your master (the working, stable, version of your code), development, testing, and hot fixes. Branches for testing and hot fixes can be made and deleted as often as you need them and as soon as you are done with them. Branch away!
• Practice branching and merging on projects you don’t care about. As simple as git makes it to branch and merge, you can seriously mess some things up if you do it wrong. Purposely create merge conflicts (edit the same file in the same place on two different branches) and try resolving them. See if it turns out the way you really want. Do it lots of different times so that you’re sure if a merge conflict ever occurs in the future (which it will, especially when working with people who don’t understand how to manage large projects) you’ll be confident in your skillz to resole the issue.
• Push to the repository. You may not necessarily need to do this for your own personal projects, yet if you work on different computers it’s really nice to be able to pull down the latest from the repository which is quick, rather than having to transfer files between the computers which can take a significant amount of time especially for large projects. You can always sign up for a free account on assembla.com, github.com, or bitbucket, to start practicing. REMEMBER TO COMMENT!
• Commit small changes locally, but only push working versions to the repository. This is true especially when working with a team. Yet that doesn’t mean there won’t be bugs, it just means that you don’t push code you haven’t at least partially vetted to the repository.
• The exception: you have local work that isn’t vetted that you need to be able to access on a different computer and you gotta go. Create a branch on the repository to push those changes to. Merge them back into the working branch once you’ve fixed any issues
• The second exception: you need help resolving the problem. This one gets a bit into the next section (workng with a team), but again, create a branch on the repository and have your buddy check that branch out. Resolve the issue using that branch, then merge it back into the working branch.
• Practice reverting. There will come a time, lots of times, when you’ll need to revert changes you’ve made. That’s the beauty of version control at it’s heart: to get back to a working version when you need it! And now that you can branch and merge it’s the perfect time to learn how to revert. Make a bunch of branches (try making them from different commits you’ve already made), make and commit changes you don’t want, and practice reverting. This includes resetting from uncommited changes, and reverting to a lower down commit.

With a team

• ALWAYS MAKE A COMMENT WITH YOUR COMMITS AND PUSHES! Sure you know now the reason why, but how the heck would Suzy Day or George Film know? For that matter how the heck would you know why they’ve committed and pushed? ALWAYS MAKE A COMMENT WITH YOUR COMMITS AND PUSHES! It will save you and them a butt-load of time and work. JUST DO IT! Also, you probably won’t remember in a day or two anyway. Just do it. Okay.
• It’s best to avoid merge conflicts. When working with a team on a project the way you avoid conflicts is to not edit the same file at the same time. Communicate openly with your team on what files you’re editing and how you’re editing them. If you change a function’s parameters you better let your team know about asap. Pulled down a teammates file to edit it? Better let her know what you’re doing to it and why! You won’t know all the reasons why they did what they did. You’re working as a team because there’s too much to do alone. Ask before you change their code.
• Be willing to compromise so you can avoid merge conflicts. You may  change how you’re handling things. If someone is unwilling to change you can either help them see how the change you want will make their code better and easier, or change your own.
• Be willing to wait! If a teammate is editing a file you need, it’s still worth the wait to make avoid a merge conflict. Can’t wait? Create a new branch and make changes there. Merge their changes into your branch once they’ve pushed, and resolve the merge conflict. Once you vetted your code, then merge it back into your working branch, test and vet again, then merge into the repository.
• Only push working code to the repository! That’s not to say that there may still be some bugs, but don’t screw over your team by not vetting out your code as much as you can before pushing it.
• Bring your teammates that are unfamiliar with version control up to speed, and be nice about it! Show them how much easier their life will be when they do version control correctly and help them out when they have questions. It is a bunch to learn all at once. To get them started you can give them a link to this post and a copy of Pro git. Then go buy yourself a doughnut for being such a nice person. But really, in the end, it’ll benefit both of you, so buy them a doughnut too.

Good luck!

You’re not on your own though. You can always do an internet search for help with git or check out the version control guide here.

Quick Git Tag Reference Guide (Make, View, and Rename)

Here’s a quick reference to the basic git tag commands that I use frequently, but not frequent enough to always recall offhand. For a more detailed explanation of everything you need to know about the basics of git tags go here.

Basic Tag Commands

These will get you through most everything you need for tags.

Make a new tag
git tag -a -m “message about tag” //creates the tag

View tags
git tag //will show list of tags
git show <tag name> //lets you view information about the specified tag including the message

Share tags
git push origin <tag name> //will push specified tag(s) to repo

Advanced: Renaming Tags

After creating several tags on a game we were making, I realized we should have added version numbers to the tags so we could visually identify when each tag was made by its version number. This meant renaming tags, pushing changes to the repo, and then having my teammates clean their local repos.

I garnered this value information from this stack overflow.

1. Rename the tag

Simple tag (not annotated)
git tag new old
Annotated Tag
git tag -a new old^{}

2. Delete the old tag and push changes to the repo

Both kinds of tags:
git tag -d old
git push origin new :old

3. Have team members update their local repos

Have team members run this:
git pull –prune –tags

Git Pro

To be a git pro just start practicing with git. Here are resource links I recommend to get started with git. For convenience, this is the book I recommend: Git Pro, which I explain on the resource links page as well. (#ThanksForYourSupport #CommissionsEarned)

A Reference for Setting Up Git for the First Time: A Very Brief Overview of Installation and Set-Up

This is a very brief overview of installation and set up of git for reference purposes. This isn’t for teaching you git. I’ve found that as I’ve taught people git these are the things I constantly had to look up or have them look up just for getting started. So I thought I’d make a brief overview of the steps to make everyone’s lives easier.

For information about git resources, including a book that can teach you all you want to know about git, I have a post about that here.

Important note: some of these steps are specific to the gitlab git server repository. If you are using a different repository check their documentation.

Git Installation Overview:

Basically all you need to do, for Windows, is download git from git-scm.com. Install git bash (which will be your command line interface). A git gui is not necessary, but can be helpful if you’re not a command line pro. (The pros use command line! Just saying! 😉Become a pro!)

Git Set Up:

Set your user name and email. These “tag” your commits. In git bash:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

At this point you can start using git locally. If you don’t have a git repository there is nothing further you need to do for set up. The rest of the article is for connecting to (in this case a gitlab repository) git repository to push (like SVN commit) and pull (like SVN update), and lots more for easy collaboration among your fellows.

Connecting to a Remote Repository

Create your SSH Keys (You can add multiple):

(Should match your email from above)

ssh-keygen -t rsa -C "your_email@example.com"

• The default place to save is correct (unless you’ve changed your settings) so just hit enter.
• If you want a passphrase enter it followed by an enter twice. Otherwise hit enter twice.

The ssh key will now be saved in your user folder under “.ssh”. By default in Windows this will be in your user’s directory. Open the idrsa.pub file and copy the whole thing.

Save the key in your repository.

In Gitlab go to:
My profile -> Add public key
paste the entire key in the “key” box. Title will auto fill.
Select “Add key”

You should now have ssh access to the git repository and will be able to push, pull, clone, etc.

Make/Update your server repository

If you have a blank project: Clone/create a new repository:

Navigate/create the directory where you want the cloned project to go. (For SVNers, this is like checking out a project.)

In general, to clone from a repository via ssh the command is:

git clone git@:/.git

For example project it’s this:

git clone git@git.eaemgs.utah.edu:john.doe/BestProjectEvah.git

Once that is done, you need to create a local repository and then tell local git where your origin is. Git won’t make an empty repository unless you tell it to. So make a dummy file and add it to the repository and push to origin and tell git to track the upline:

cd project_folder
touch README.md
git add README.md
git commit -m "add README"
git push -u origin master

If you have an existing project (but not a git repo)

cd existing_project_folder
git init
git remote add origin git@git.eaemgs.utah.edu:john.doe/BestProjectEvah.git
git add .
git commit -m "Initial commit"
git push -u origin master

If you have an existing Git repository

cd existing_repo
git remote add origin git@git.eaemgs.utah.edu:john.doe/BestProjectEvah.git
git push -u origin --all
git push -u origin --tags

The “-u” in the “git push” tells git to track the branch on the remote branch. In future pushes then you don’t have to tell git which branch on the origin to push to. Just do a “git push origin $branch_name”.

Update your remote url

Sometimes your remote url will change. (curse the techs right?! 😉 )

To check your remote url run

$ git remote -v

This will list any short name remotes along with their urls.

To update run:

$git remote set-url  

If you need more details the

$ git remote set-url --help

is in fact very helpful.

Good luck! 🙂

Let me know if you find anything that is incorrect or other important startup commands to get going. I’m happy to refine. 🙂

Getting Started with Git: Resource Links

I’ve been sending out this information quite a bit (all in different emails). I figured this would make a perfect follow up to Learning Version Control, and I might as well just make a blog post with this information and then send people the link instead of searching aimlessly in my email for all this.

Learn Git

The book on git is Pro Git, by Scott Chacon. The most important chapters are 1-4, and 9 (if you want to really understand what is going on in the plumbing of git). If you’re using this for personal use, you can get a free copy here. Alternatively, you can support the author by buying Pro Git from Amazon. (#ThanksForYourSupport #CommissionsEarned)

Git Interfaces on Windows

There are several different ways you can run git on windows. Here are the ones I recommend.

GUI

Unless you are a command line pro, using GUIs are much easier to get started with.

• GitExtensions: one of the better GUIs for git I’ve used
• Git gui from git-scm (also has the command line). I always install the “git gui” from git-scm along with the command line “git bash.” At one point they also had a “git cheetah” option which is also a gui if you want to try that.

Command Line

• Git bash from git-scm (command line) — this is the most powerful. A lot of times things are easier via the command line. (Important note: When you install this version, make sure to install the git bash to get the command line interface.) With this download you also have the option to install a gui.

You can install multiple guis and the command line, so you have a visual and command line interface. Sometimes it

Why Learn Version Control (aka Source Control)?

Learning version control now will not only make your current life better, it will make your time in MSEAE and as a professional game developer much easier.

The University of Utah supports SVN, but if I can get my way we’ll hopefully be moving to git. Since I got one of the tech guys for the MEAE program to set up gitlab (which is the best git server repository application I’ve used. So if you’re going to set one up for yourself that seems to be the best way to go), it may now be a possibility! Git is the better choice anyway. 😉

The tech guys for our game design lab are awesome and are super willing to help out with so much! (Word to the wise: Always be nice to the tech guys! They can make or break you!)

You’re going to be working on some seriously complex programs and while SVN (which I learned on day one of the C++ class) has it’s upsides, when compared to git it is seriously lacking. Branching and merging (which you’ll be doing a lot of) are seriously simple with git. Even if you run into a merge conflict — which will happen, I even did it to myself the other day — it’s easier to resolve in git.

Just Learn Git

Best book on the topic, which you can also get for FREE, is Pro Git. I’ve had people who are experts on git tell me this book is the best, so it really is. If you want to support the author you can buy Pro Git. He did a great job, so seriously consider it. Just saying.

Pro git will walk you through how to install git — for fellow windowers: I always get the command line and git gui over the git cheetah. I prefer the command line, but it’s also nice to be able to visualize all the changes and gitk comes with git gui. There are lots of things that are actually easier to handle through the command line — what version control is in general and how to use it, branching, merging, etc. The important chapters are one-four, and nine. You can almost read nine first, but be prepared: it’s highly technical and you’re not doing much other than reading. I read the first half of chapter nine and then read chapters one-four. It gave me a better understanding of what was going on when I used certain commands so I wasn’t wondering why I was doing them.

Advantages to Version Control!

I know what you’re thinking: I have to learn another thing! I already have a list of languages and programs to learn. Listen to me oh ye of little faith: Dude, real version control is going to make your life so much easier! Quit making copies of your entire project and renaming it. You can never remember the exact difference between the copies, it’s hard to merge, and it takes up a lot space. That stuff is for kindergartners, enter the world of professionals and gain the benefits:

• Your can see (especially with gitk and other git commands), changes made between commits.
• It’s a lot faster and easier, and you can do it more often, to backup your program.
• It takes up less space to backup your program this way. (See Pro git for more on how git handles saving the differences, branches, etc. which saves so much space.)
• It’s a TON easier if you need to revert changes.
• It’s incredibly stupid easy to merge changes.
• All the professional programmers are doing it! 😉
• A lot of game companies use git.
• Your life as a programmer will be much improved. Once you get the hang of it you’ll wonder how you ever got along without it.

Get started

Here’s the link to resources you’ll need to get started.