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.

Advertisement