Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I'm looking for practical examples to use when teaching version control.

Breaking down the material to basic concepts and providing examples is an obvious way to teach version control, but this can be very boring, unless the examples are really practical or interesting.

One idea I have is customizing a WordPress theme. I use WordPress a lot, and often need to tweak the theme a little. So I typically put the original theme directory in version control and start editing knowing I can easily roll back.

The problem with this example is that some people might not be familiar with WordPress, or have shell access to a WordPress site to try out the commands. Preparing a mock site and giving access to everyone is also not an option. I need a "toy example" that can be interesting to a broad audience of software developers, and something they can try on their own computers easily. The tutorial will use a DVCS, but the practical example I'm looking for is only to teach the basic features of version control, ignoring the distributed features for the moment.

Is there a more suitable / appropriate topic?


Thank you all. I ended up using textual data: dinner party planning with plain text files for guests, menu, invoices, and venue directions with images for some binary data. For teaching more advanced VCS features I later moved on to a collection of "hello world" implementations in different languages. Thanks again!

share|improve this question

closed as primarily opinion-based by MichaelT, Dynamic, Kilian Foth, Robert Harvey, user61852 Jul 10 '13 at 14:12

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

So who is your target audience? what level of expertise/experience are you going to be working from? – Crollster Jul 16 '12 at 8:52
Beginning to intermediate software developers. Ideally it would be great to include web designers, technical writers or translators too, but obviously that would make it even more difficult to find a good toy example to cater to everyone. – janos Jul 16 '12 at 9:07
Use an example relevant to your audience. If you cannot think of any, ask a representative sample of your future audience. – user1249 Jul 16 '12 at 16:38

10 Answers 10

up vote 30 down vote accepted

Use textual data.

For example you could write a simple shopping list for a party, and let students add, remove or edit items to buy.

IMO it is always best to focus on one task at a time, and not to split concentration between two things, like CSS and version control. Especially if your audience has beginners, or is very heterogeneous.

share|improve this answer
+1. If you are teaching source control, don't confuse things by throwing a technology into the mix that some people in the audience won't be familiar with. – RationalGeek Jul 16 '12 at 13:07
This link provide a good text example to explain how mercurial works – JF Dion Jul 16 '12 at 14:07
I agree that it's better to concentrate on one thing. But I'm looking for an example that is "braggable": something the students will want to learn so they can brag about. It's like when you teach programming, nobody cares about a for loop that increments a variable, but if at the end of the chapter that leads to an animation, now that is cool. I'm looking for a "braggable toy example" in version control land, if such exists. But thanks for the shopping list tip, I might stick with that in the end, or something like the recipes in hginit. – janos Jul 16 '12 at 14:44
+1 You definitely want to focus on the version control part of things by collaborating on something familiar. I've always thought of playing a game (scrabble, chess, etc) using one or more text files, but I haven't really found a good example that's asynchronous and both independent and collaborative at times. – Yann Jul 16 '12 at 15:24

Take a look at Version Control by Example, by Eric Sink. The same simple example is used over and over with multiple version control applications: svn, git, mercurial and veracity.

share|improve this answer
Thanks, I know this one, and it's really great. He explains each basic concept one by one, and although he managed to make it interesting and very cool with the Mona Lisa illustrations, I want to take a different approach, using a general project, and explaining and applying each basic concept in the context of that project. For this the project has to be general and interesting enough so that a lot of developers can relate to it. – janos Jul 16 '12 at 8:34

Forget about creating a really interesting example. That's not the point.

If you're teaching version control, the focus should be on that and not on the content of the files except insomuch as the target audience needs to be able to recognize different versions of the files. If you ask the audience to think about what a program does, how it could be made better, etc., they'll be thinking about that instead of learning to use the version control system.

What you need is the code equivalent of lorem ipsum.

Depending on your audience, even FizzBuzz might be too complicated. You certainly don't want raising their hands and suggesting better FizzBuzz implementations! I'd suggest starting with something that everybody understands, like Hello World. Then you can start making changes, like adding the date, adding the user's name, adding unit tests, adding a daemon mode, etc. This will give you plenty of opportunity to create branches, merge code from other programmers, revert to previous versions, look at differences between versions, etc., and that's where the real focus should be.

If a Wordpress theme suits you better, that could be fine too. It really shouldn't matter if audience members know anything about PHP or Wordpress. Explain at the outset that they don't need to know anything about how the code works, they only need to be able to recognize changes to the code. Give them some help in this respect by including a comment with each change that makes the change obvious. Use a good visual diff tool frequently so that they can see two versions of the file side by side with changes highlighted.

share|improve this answer

If you just want to teach version control I would suggest not using code. Just use simple text files.

One that I saw work particularly well was a basic [any simple dish here] recipe that was expanded and branched.

(Related: Software developers always have interesting salsa recipes)

share|improve this answer

The text file thing is important because it can teach Merging which is fairly important here (I don't think anyone said WHY to use a text file).

I'd suggest actually breaking up into teams of 4 people and then giving them a couple already checked-in documents to work on.

Give each person in the team a different assignment to modify some of the files and give them x minutes in which to do the modifications.

The first time you do this, if you make the timing short enough, should be a complete cluster-muck, after that teach them to solve the problems they encountered and do it again.

That should be able to teach the basics in a session or two as well as the "Feel" of version control in a real-world situation, something they probably won't get much of for years.

share|improve this answer

I would start with a Hello World program. Then I'd imagine that multiple new requirements came in that required separate developers to modify it various ways. Then I'd highlight how things can go smoothly and how things can get messy, showing that version control sometimes barely feels necessary but becomes a huge must-have when very common scenarios arise like hot-fixing, for instance.

The best thing, in my opinion, to give to student learning version control isn't necessarily in-depth expertise, but a tendency to believe in its importance when they go into the real world.

share|improve this answer

GitHub has created a simple, in-browser tutorial for Git:

share|improve this answer
Or, – GalacticCowboy Nov 8 '12 at 21:24
would you mind explaining more on what it does and why do you recommend it as answering the question asked? "Link-only answers" are not quite welcome at Stack Exchange – gnat Sep 12 '13 at 7:51
Well, it's a tutorial for git, and I recommend it because it's A.) Simple, B.) In browser and C.) by GitHub. – SomeKittens Sep 12 '13 at 17:37

There are several good resources to get familiar with common features of version controls (TFS, SVN, Git, etc.)

As a reference, a book by Eric Sync is pretty good, and there are plenty of online resources that you may find helpful:

Edit: some of the suggested resource are added (thanks for comments):

share|improve this answer
Another one: HG Init: A Mercurial Tutorial is specific to one VCS, but it's also filled with excellent toy examples. – user16764 Jul 16 '12 at 14:22
Thanks, good suggestions are welcome ! – Yusubov Jul 16 '12 at 14:41

How about downloading a portion of some famous codebase, for example the code used by the Apollo and Gemini NASA space missions. Its sure to get the interest of most developers.

share|improve this answer
would you mind explaining more on what it does and why do you recommend it as answering the question asked? "Link-only answers" are not quite welcome at Stack Exchange – gnat Sep 12 '13 at 7:52

GitHub and CodeSchool just released an interactive tutorial for learning how to use git that you might find really useful. After that, I'd suggest having them construct just a simple HTML site with their resume/CV on it. They'll be able to learn version control and have something useful at the end of it as well.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.