Git intro for TFVC users

So, you’re using Team Foundation Version Control (TFVC). You know about Team Projects and Collections, have a “stable” and “dev” branch for most projects, know how to do basic merges, and know how to shelve and unshelve changes. But you only have superficial knowledge of Git.

Well, then you’ve come to the right place: my Git intro for TFVC users.

Disclaimers

Here’s a heads-up about this particular post:

  • It is not in-depth;
  • It will oversimplify things to the point where not every statement is technically true;
  • It does not teach you actual Git skills or commands;
  • It is somewhat subjective.

Oh, and in my humble opinion: Git has a crazy learning curve. So buckle up!

And, as a final disclaimer: I’m writing this because I want to be able to explain the basics of Git, and certainly not because I’m an expert. In fact, I know more about Mercurial than about Git, I have worked mostly with TFVC in the past year, and would have to look up nearly every Git command when using the command line (I prefer GUI tools most of the time). Just so you know.

Disclaimers done, let’s get started!

On “TFS” vs “TFVC”

First, let’s get the TF* terminology right. These terms are different but related things:

  • “TFVC” stands for Team Foundation Version Control, and is the actual system for keeping history of your codebase;
  • “TFS” stands for Team Foundation Server and is the “environment” (if you will) in which source control features come together.

Many people, myself included, often use the acronym “TFS” when we actually mean “TFS with TFVC”. This is probably because TFS is very often used with TFVC as the version control system; but note that you can also use Git with TFS.

This blog post focuses on TFVC (which almost always implies you’re using TFS too).

Why Learn about git?

The personal reasons for learning Git are quite simple: it’s the de facto standard for version control. Knowing about Git is:

  • crucial for your career (your new employer is likely to use Git);
  • crucial for talking to new hires (who will very likely know Git);
  • crucial for efficiently navigating open source.

The intrinsic reasons for learning Git all come down to the fact that it is insanely powerful (which also accounts for the steep learning curve). After having worked with TFVC in a 12 person team for over a year, I’d like to highlight the following main- and most direct advantages over TFVC:

  • Cheap branching;
  • Small repository size;
  • Local commits;
  • Better options for “shelving”;
  • Speed;
  • Better “offline” support.

Beyond these advantages, which you’ll get if you’re using a “central” Git repository, there are even more goodies if you tap into the distributed nature of Git, as well as the more powerful commands (e.g. to rewrite history).

Basic differences

Git is a lot like TFVC, in that it is also a Version Control System (VCS). It is also quite different. Here’s how they compare when managing the code base and doing changes:

TFVC Git
There is a central, server-hosted Team Project and you’ll have one or more local workspaces containing a copy of all the code. For now, let’s assume that there is a central repository hosted somewhere on a server. You’ll have one or more local “clone” repositories containing a copy of all the code and also all of its history.
check in is a command to send your pending local changes to the server where they will be committed to the version control history. You commit changes locally which creates a “change set” private to your “clone”. You can do this multiple times. You push one or more change sets at once to the central repository.
You can Get the Latest Version from the server which directly tries to merge with your current state. You fetch changes from the central repository and merge with your current state (or do both at once by doing a pull) possibly creating a new commit.

The fact that a TFVC “check in” is multiple separate commands in Git gives several advantages:

  • You can build history in small, individual steps (commits), which you can undo individually in several ways, and you can apply individual commits to other branches.
  • Your changes are “safe” in commits when you want to send your changes to the central repository and find out others have conflicting changes, by default they won’t get “lost” if merges go bad. With TFVC, you’re required to resolve conflicts as you try to check in, which can screw up “unsaved” changes.

Our next set of differences would be about branching, but before that it’s good to talk briefly about “shelving” changes.

Setting changes aside

With TFVC you can shelve changes you currently have to safeguard them, optionally reverting those changes in your local workspace. You don’t necessarily need to do this when switching work to another branch, because the branch is typically a sibling folder of the main branch. More on that later.

With Git, you can stash changes you currently have, reverting changes in your local clone. You have to do this before switching to another branch. In order to see how that works, let me move on to the next topic: branches.

Branches

A typical setup in TFVC starts like this (with a local workspace matching the Team Project 1-on-1 in this example):

Inside the project folder for the Team Project, there immediately is a sub folder called “main”. This is done so that it is easy to branch off the entire codebase for that project into this:

The folder “dev” is now a complete copy of “main”. This also means you could be working on two branches simultaneously, and you can check in files to both branches at ones if you so desire. You could even have “main” and “dev” at different points in your version control history.

Git is different.

With Git, the “main” folder as you’d have it in TFVC would be pointless. Instead, there is just:

You can “branch off” any state of “project-x” at any point in time. Your folder “project-x” will point at a certain state, de facto having the code for a specific branch.

If you would like to have both branches “ready for action” on your disk, you would typically have multiple “clones” of the repository. One would be at the most recent state of the “main” (typically called “master”) branch, and another might be at the most recent state of another branch.

As a summary, Git branches relative to TFVC branches:

  • Are light-weight and can be used to “switch context” for example to work on a feature;
  • Are a top-level thing, as opposed to the “path-based” branches in TFVC;
  • Allow for more precise merges and “cherry picking” of commits;

These differences allow for completely different workflows with Git. This is a topic for another post though, if you’re interested I’d recommend research things like “Git Flow”, “GitHub Flow”, and “GitLab Flow”.

Other differences

While there are many other differences, both small (e.g. specific commands) and big (e.g. the “distributed” nature of Git), this post will keep it at the above. Mentioned differences are in my opinion the most “direct” and eye-catching differences. If you want to learn about the other differences I recommend you first get started with some practical skills, e.g. by following a tutorial.

Conclusion

TFVC is a mature, decent version control system. But personally, having worked with both centralized and distributed version control, in TFVC I’m misssing:

  • Ability to do commits locally;
  • Cheap, more powerful branching;
  • Great “shelve” options;

Those three, in addition to its “distributed” nature enabling online platforms like GitHub to flourish, are likely the reasons Git is so popular nowadays. In my opinion those are great intrinsic reasons to learn Git when you’re currently using TFVC (even if you cannot switch on the short term), and if not for those reasons then because it’s crucial for your career.

So ready yourself for a bad-ass learning-curve climb, and start learning more about Git!


Resources & Further Reading

Here are some links to continue your journey:

Finishing Things – Intermezzo part 2 of 2

So, like I wrote, Google is “bidding farewell to Google Code“. So my recently “wrapped” up projects needed some post-wrapping-wrap-up (you still with me?!). I’m using this as a good excuse to partially move from Mercurial to Git, because I suspect Google Code’s export to GitHub is probably the migration path they’ve put most effort in.

So, here’s my first (active) day at GitHub:

GitHub Contributions

I’m a little afraid that -given GitHub’s popularity- many will see this and consider it to be my current status on code hosting services (disregarding commits to those repo’s being done over a larger time span, and disregarding activity on CodePlex). However -given GitHub’s popularity- I guess my GitHub activity will increase anyways over the coming years.

As a related side note: moving projects from Google Code to GitHub was extremely easy. The web-based tool required nothing besides a link to my Google Code project, and me authorizing Google Code in GitHub through OAuth. The only downsides I personally found during this automated conversion:

  1. My old commits in the migrated GitHub repo’s don’t get attributed to my GitHub account, because the user details were different. Also, apparently TortoiseHg “helped” me commit unwittingly as “jeroenheijmans <jeroenheijmans@localhost>”. I guess if I’d payed attention I (sh/w)ould’ve at least used a valid e-mail address. (Yes, given that probably no one has cloned my repo’s (yet) I could probably rewrite history to change this, but it’s not that big a deal I guess…)
  2. My repository includes some Mercurial-specific files, i.e. a .hgignore file. I might’ve stripped that if I had done the Hg-Git conversion manually.
  3. The project home page from Google Code was not automatically added as a README.md file in the GitHub repo. I think that would’ve been nice. Then again, this omission gave me a chance to check out Git(Hub).

And so my move to Git(Hub) begins. I’ve already enjoyed reading through other people’s thoughts on (Git) commit messages, had my first dealings with Atlassian SourceTree, as well as a combination of the two. You’d almost wonder how I got the actual migration done at all.

I feel excited about getting to know more about SourceTree, Git, and GitHub. However, I’m also still very determined to finish Bieb, which will remain on CodePlex. We’ll see how that plays out in the coming weeks / months. Stay tuned.

Finishing Things – Intermezzo part 1 of 2

In the beginning of 2015 I declared I was wrapping up my open projects. I’ve since quickly wrapped up BattleTop, TimeLine, and DotaGrid. After that I’ve started to work on my somewhat bigger project: Bieb. I haven’t had as much time to put into that project as I wanted, but there has been a thin stream of commits.

However, all this has been brutally interjected by Google: they’re “bidding farewell to Google Code“.

Google Code was very barebones, but in a sense that was its charm. I like BitBucket and CodePlex too, but for small projects Google Code was just fine. Especially since I’ve shut down those projects. However, now I need to make a choice: do I put effort in moving my discontinued projects? And if so, do I move them to another Hg provider, or do I bite the bullet and convert them to Git?

Guess I’ll bite the bullet. Let me do so right now, and get back in a fresh post with the results…

Google Code Hg Hosting

A few months back I wrote a short comparison of Hg Hosting Providers, followed by a post about CodePlex Hg Hosting. In the mean time I’ve also tested creating a Bitbucket project, but I’ve neglected writing a post about the experience. I may get back on that some time, but first I would like to share my more recent experience with Google Code.

Note that I’m not ready (read: “proud enough”) to share the actual project I’m hosting, as it’s still in (and may never leave) prototype status. Once it’s worth viewing, I’ll probably be doing a short blog post about the project itself.

Without further ado, let’s jump in!

Sign Up and Project Creation

In this case I’m not writing much about sign up. You need a Google account, which most folks will probably already have. If, like me, you are already signed in to your account, nothing more is needed here.

On to project creation, which was surprisingly simple. The process is one step total:

Creating a Google Code Project
Creating a Google Code Project

Very similar to the CodePlex project creation. To note the differences:

  • It’s not entirely clear in Google Code how the project name would become part of the project URL.
  • Source control at Google Code (understandably) excludes TFS.
  • Google Code asks you to label (tag?) your project at creation time.
  • Most importantly: Google Code requires you to pick a license at project creation time.

That last one is really the only difference from CodePlex, but a big one at that! With CodePlex you get a one-month “Setup Mode“, which means your project is private and you can still work out the details (including picking an appropriate license). This is a big plus for CodePlex, especially if (like me at the time) you’re creating your first open source project.

Importing the Existing Repository

Where I had some cautionary steps importing my existing repository the previous time around, this time I had only one, making a total of four steps to get my existing repo pushed to Google Code:

  1. Create a temporary “copy-paste-backup” of my (existing) repo folder.
  2. Clone the Google Code (empty) repo locally.
  3. Copy the existing repo into the empty repo.
  4. Push the repo.

Step one turned out to be superfluous. So, this is in fact easy as pie.

Google Code Features Overview

Here’s my first impression of the various features of a Google Code project:

  • Project home is what you see when you land on the URL of your project (which is in the format: http://code.google.com/p/project-name)
  • Downloads is where you can host releases you’ve built and packaged. Haven’t tried this feature yet, but it looks very straightforward.
  • Wiki feels a little odd, because you start at a table-based listing of all pages. Beyond that it’s just a basic wiki (with yet another syntax), that’ll do the job.
  • Issues are for tracking bugs and tasks. Haven’t tried this yet, but it looks both straightforward and barebones.
  • Source provides a way to browse the files, view a history of the changes, and check on any clones there may be. Not as fancy as -say- GitHub, but gets the job done.
  • Administer allows you to change just about everything you see in your project, and works quite okay.

The theme should be clear: everything in Google Code is no-nonsense. All important features for code hosting are there though.

Conclusions

This hosting provider is pushing the KISS principle to the max. Google Code gets the job done, but it is very barebones, at times even downright ugly. Great hosting, but it doesn’t leave me “WOWed”. With the same functionality but a more pleasant experience, I think I would prefer CodePlex.

CodePlex Hg Hosting

This is a follow-up to my previous post on Hg Hosting Providers. I found that on the surface all four of them were very similar. From the four providers I investigated, CodePlex overall felt most intriguing, so I decided to start by trying out that one.

Note: I participate in another project, which I will be uploading to Bitbucket (because that’s the only one that supports small private projects at no charge), so I may be doing a follow-up on that provider too.

Sign Up and Project Creation

The CodePlex home page lures you into creating a project with a big, purple, Metro-style button:

CodePlex Step 1 - Create Project Button
Step 1 – Create Project Button

When you hit the button you’ll be asked to either sign in or register:

CodePlex Step 2 - Sign in
Step 2 – Sign in

If you don’t have an account yet (like I did) you can register for one on the spot. I decided to create an account linked to my Windows Live ID:

CodePlex Step 3 - Register
Step 3 – Register

The hardest part is the Captcha: damn those things can be a challenge! After finally completing this mini-game, it turned out CodePlex had forgotton all about my intention to “Create a Project”, and instead presented me with my personal (and very empty) project home page:

CodePlex Step 4 - Account page
Step 4 – Account page

Luckily, there’s another (though less obvious) “Create a Project” link on the page. There’s only a small number of fields you have to complete:

CodePlex Step 5 - Create Project
Step 5 – Create Project

The whole point for me was to choose Mercurial hosting, but it’s noteworthy that both TFS (which also supports SVN clients) and Git are an option too. Hit “Create” and if all goes well you’ll be directed to the brand new project’s home page:

CodePlex Step 6 - New Project Overview
Step 6 – New Project Overview

The project has now entered the “Setup Period”. This gives you 30 days to set up the project, i.e. before you have to go live. This was in fact a welcome surprise to me, because since this was my first time coordinating a hosted project the setup period allows me to calmly check out all the features.

Importing the Existing Repository

Keeping in mind that eventually I would be hosting the code online, I had already started with a Hg repository, committing my changes locally. There are several advantages to using version control while still flying solo, amongst others having backups and traceability.

I already suspected it wouldn’t be too hard to merge an existing repository into a new hosted project, and I even got some response to my question on Twitter, indicating it should be possible. The only thing I was worried about is that the username for commits would be “wrong”, because my computer user name “Jeroen” is different from my new CodePlex user name “jeroenheijmans”. To get everything to work I took the following steps:

  1. A simple copy/paste back-up of the existing repository, just to be safe.
  2. With some effort I got this Hg convert trick to work, changing the user name in commits for the existing repository to my CodePlex username.
  3. Make a clone (a.k.a. check out) of the project repository from CodePlex to a new local folder.
  4. Copy the existing repository over the clone from CodePlex.
  5. Some of the hidden files in the .hg folder have to be overwritten. I double checked all files with Notepad++, and in all (my!) cases the clone’s file could be safely overwritten.
  6. Using TortoiseHg I now pushed all the changes. In the previous step the CodePlex URL was probably lost, but that was easily remedied by entering it once more.

To be honest, in hindsight I don’t know if step 4 and 5 are really necessary. I guess you could safely try just pushing your existing repo to CodePlex: if it doesn’t work surely you’ll get an explanatory error message?

Either way, after completing the above steps my CodePlex project contained a complete history of 40+ commits, only minutes after setting up the project!

CodePlex Features Overview

After importing the source code it was time to investigate the various CodePlex features. Given the 30 day setup period I was able to check out all the features without having to worry others may see my silly mistakes. Here’s my first impression of the available features:

  • Home is the first thing you see if you go to the project URL (which is a nice subdomain of CodePlex: http://yourproject.codeplex.com). It mainly contains some text to explain what the project is all about, and you’re invited to edit it (with Wiki-style markup). Worked nice and easy for my simplistic purposes.
  • Downloads is the section where you can offer releases, which can have various properties as well as attachments such as binaries or installers. So far I’ve only created two “Planned Releases”, which worked pretty straightforward.
  • Documentation is Wiki-based. So far I’m headed straight for the quintessential documentation pitfall: I’ll create it once the product’s finished.
  • Discussions looks like a forum-based commenting area. Given that the project is one we do together with friends we may not get to use this option much.
  • Issue Tracker is a very basic work-item system. It contains the bare essentials, but not much more. This was a bit disappointing to be honest, I would at least have liked to have some basic formatting, but apparently that’s still a work item on CodePlex itself.
  • Source Code is the section where… well… you can find the source code! It shows all commits in descending order, and even though I haven’t tried it yet it also shows forks and pull requests. If you click on a commit you get to see the diffs for changed files.
  • People shows all the coordinators, developers and editors on the project. It’s also the place to invite your team mates to the party!
  • License is where you can view and change the license for your project. CodePlex allows you to choose from ten different OSI licenses. I’m leaning towards picking the BSD license, but this license stuff feels like a snake pit (with it’s own acronym: IANAL).

So far this list of features seems pretty sufficient. At least: I haven’t “missed” a feature so far.

Conclusions

All together I’m pleasantly surprised by how easy it was to set all this up. I’m not sure (yet) how it actually compares to the other hosting providers I considered, but so far I’m happy I chose CodePlex.

I’m fairly certain our project will be published some time soon, and when it does you can find it at bieb.codeplex.com: join the party!

Comparing Hg Code Hosting Providers

Mercury ElementMost usually, I’m a very organized person. Even before I was programming (when I was making Hero Quest maps in Q&A and WordPerfect) I would still want periodic backups of my data. Given all that, I’ve remained remarkably oblivious of Version Control for quite a long time. Here’s an overview of my VCS history:

  • 1990 – 1992 Derp derp, playing Commander Keen and friends.
  • 1992 – 2003 Copy-paste-style backups, periodically.
  • 2003 – 2005 Visual Sourcesafe. The horror…
  • 2005 – current SVN and TortoiseSVN. Much better!
  • 2011 – current Mercurial (with TortoiseHg), and a dash of Git.

On a coding project with friends, one of them suggested we’d use one of the DCVS systems: either Hg or Git. After a short debate (and after reading endless flamewars between the two) we decided on trying Hg. My “re-education” started with reading the HgInit tutorial by Joel Spolsky. Here’s a quote that stuck with me:

It turns out that if you’ve been using Subversion, your brain is a little bit, um, how can I say this politely? You’re brain damaged. No, that’s not polite. You need a little re-education.

True as it is.

To be honest though: I still don’t mind using SVN. At work we have an existing repository from which we’ll probably not be switching, and it even has some advantages over Hg. However, for any new project I would choose a DCVS, either Git or Hg, depending on the circumstances.

So for my latest pet project I’ve started a Hg repository as well. So far I’ve just been committing locally, using it as a backup and history mechanism. However, with friends and family joining on the project I will probably be moving the repository to an Open Source Hosting Provider. There’s a few that came to mind, and I’m currently considering four of them. Even though there’s a decent Wikipedia comparison article, I still decided to make my own comparison table with features I find interesting:

Google Code Bitbucket CodePlex SourceForge
Source Control Hg, Git, SVN Hg, Git Hg, Git, SVN, TFS Hg, Git, SVN
Issue tracker Custom JIRA Custom Custom
Wiki MoinMoin-based markdown Creole-based markdown Yes Daring Fireball-based markdown
Forum No No Yes Yes
Private projects No Yes No No
Licenses Any, single-licensed ? 10 OS licenses available Any OS license
Authentication Google Account Bitbucket account Codeplex + optional Win. Live SourceForge account
Projects 250,000+ 93,000+ 28,000+ 350,000+

Currently I’m leaning somewhat towards CodePlex, for no particular reason or rationale. Or perhaps I’ll end up trying them all before deciding. Either way, I’ll sleep another night on it, for now.