One lecture on VCS: What needs to be covered?

Question

I've been asked to do a one-lecture (50 minute) presentation on Version Control. In the class we'll be using Git; there will be a hands-on opportunity to work with Git later in lab. (The Git GUI of choice of the professor is GitKraken).

I don't need to teach anyone to be Git Wizards. I'm not a git wizard myself. But I need to show the class what version control can do, and the basics of using Git to collaborate between multiple people.

@si618 provided a wonderful "Why use VCS" over on StackOverflow, which I am going to borrow (with credit, obviously, the CC license requires it). That covers the motivation portion.

Then I need to cover the actual model of sharing code via VCS. That's the hard part. LearnGitBranching is a wonderful resource I'll likely use to show commits and branches, but the main use of that site seems like (to me) experimenting with more complicated rebase-based operations. And a quick here's-what-vcs-is doesn't (shouldn't) need to rewrite history.

Explaining the model is the hard part; showing the application of the model is simple since I'll likely use the GUI. The command line interface isn't of import. But what really needs to be understood to understand a DVCS model?

• commit -- add snapshot to your local history
• push -- publish your local history to some location
• pull -- download history from some source
• branch -- split the line of history into two "timelines" for concurrent work
• merge -- collapse bring two parallel histories into one

Is there anything else that really should be covered? These five seem like the key components. Is it worth mentioning that every local master downloaded from the repository is a new copy, and is effectively a branch origin/master -> local/master? Is it worth mentioning that a headless git repository is no different than a local one, and that you can pull directly from a non-origin repo? Merge conflicts happen; should I mention how to go about resolving those?

Distilling an (admittedly shorter than my seniors') career of working with Git into a short "Here's why Git is awesome and you should use it" is difficult. I want to teach Git (and more generally, VCS) and not just "how to use GitHub". Thinking Git === GitHub is one of my pet peeves.

---

Context:

The structure of the course itself is rather open-ended: the second half of the course is opportunities for students to share something they've spent some time learning on their own (that's where I fit in). Since I potentially have the greatest cross-section of teaching ability and domain knowledge among the students, I was asked by the professor to do a section on Git before the lab where people get to try it out themselves. During that time as well, students will be working in groups to complete a large assignment, so I definitely want them to use some sort of VCS; it'll save everyone a bit of trouble.

The course is an upper level university CS elective.

---

On How to make git easy to learn:

I believe the two questions are meaningfully different. The other question addresses a (self) learning approach while this question seeks a teaching approach.

More importantly, answers on either question aren't generally applicable to the other. Trivial answers may be able to answer both, but any real meat on an answer makes it only really applicable to one question.

Answer 1

As requested, I'm expanding my comment into an answer. This is going to echo a lot of what I said in this answer, so you might also check that out for some background motivation.

Version control systems are tools that are designed to solve specific problems.

They're great for stuff like:

• Storing multiple revisions of a file.
• Allowing collaboration among multiple people.
• Handling cases where multiple people are editing the same file or even the same section of code.

If the students haven't encountered these problems, then they might not be ready to start using a version control system.

Another consideration is that students need to understand basic directory and file structure interaction before diving into version control. Do they know how to navigate a directory structure? How to edit and copy files? This is less "common sense" than you might expect, but it's definitely a prereq to talking about version control.

All of that being said, I think you should start by explaining the above problems. Discuss how they might "solve" those without version control. Ask them if they've found themselves trying to manually merge files where multiple people were contributing, or if they've found themselves with files named HomeworkAssignment_FinalDraft-3-ReallyFinalThisTime-6.txt. If students have seen these problems, they'll naturally see the benefit of version control.

Present version control as a solution to the problems that they're already experiencing.

In other words, don't make it theoretical. Make the lesson practical and pertinent to what the students actually do.

Go through some example scenarios. Explain how they might use Git to solve the above problems, and focus on real actionable things they can do:

• Here's how you'd set up a code repo so you and your team can edit files without breaking everything.
• Here is the command you'd run if you wanted to upload your edits.
• Here is the command you'd run to download changes from other people.
• Here is how you'd resolve merge conflicts.

Even better: have students run through these scenarios live. Have them typing commands and pushing buttons instead of just listening to you. This should be information that they can actually use, not just theory that they'll forget as soon as they leave the classroom.

Don't spend an hour talking about theory. If students have never seen version control before, then they don't need to know how Git stores changes. They need to know how to setup a repo.

On the other hand, don't spend an hour telling them about all the different things Git can do. If you throw a hundred different commands at them, they'll remember zero of them.

Instead, introduce specific problems (that the students have already seen in their own coding), and show the solution to those problems. Have students work through those solutions and practice the commands right away.

Is it worth mentioning that every local master downloaded from the repository is a new copy, and is effectively a branch origin/master -> local/master?

Students should understand branches (bonus points for using branches to do pull requests and code reviews), but do you really need to get into this level of detail? Imagine students writing this down as you lectured. Would they really need to know this later, or is it just clutter?

Is it worth mentioning that a headless git repository is no different than a local one, and that you can pull directly from a non-origin repo?

Meh. This seems like trivia to me. Do I need to know any of the above to solve the problems I'm having?

Merge conflicts happen; should I mention how to go about resolving those?

Yes, absolutely. Like Michael said, this is a very common problem that students will face, so they should definitely know how to handle this case.

Answer 2

I think the material you cover will vary depending on how much of Git you're trying to cover.

If you're just trying to cover basic use of git, I think teaching clone, add, commit, push, pull, status, and diff should be sufficient (if you're using the command line). Since you're using a GUI, I suppose you can prune some of these commands down (though I do think showing how to use Git from the command line is useful).

I wouldn't even cover branching: it's not useful for basic usage.

When doing this, be sure to remember that you do need to do a little initial setup before you can use git: you need to set your default name and email, set up an ssh key (which, note, you can do on both Windows and Linux -- no need for something like putty). I'm not sure how you're asked to do this setup when using the GUI, but it's certainly something you need to do when first using Git on the command line.

You also should absolutely cover how to resolve merge conflicts here, and techniques for minimizing merge conflicts (e.g. commit before pulling). If you can, try and have students do an exercise where they deliberately cause merge conflicts and need to resolve them. Merge conflicts are inevitable, so you should prepare your students to deal with them.

I try and demystify merge conflicts as much as possible: for example, I like straight-up showing students what a conflicted file looks like in their text editor to emphasize you don't need any special tools to resolve one, just their editor.

---

If you're instead interested in giving students a solid foundation in Git, and preparing them for how Git is often used in industry, I think you should heavily emphasize the underlying model behind git (the DAG).

The hope is by doing this, you can train your students to NOT try and memorize every single Git command. (Trying to do that is an exercise in futility: there are many Git commands, and many of them are overloaded and poorly named). Instead, try and train your students to think in terms of DAG manipulations: if you can manipulate a DAG in a particular way, you can certainly make Git do the same (though you might need to google a little to find the exact command).

If you're going to do this, you should also probably cover rebasing. You can maybe introduce this as a sort of exercise (e.g. something like "we said Git was a DAG, so does that mean it's possible to arbitrarily rearrange nodes? Yes! Meet rebase -i..."). It also turns out many people in industry prefer rebasing over merging since it lets them maintain a cleaner git history, so it's useful to know how to do both.

The other advantage of focusing on the DAG (besides setting up a solid foundation) is that it lets you connect Git back to what your students already know: data structures and algorithms. That gives them a nice "hook" to hang their new knowledge on.

---

Is it worth mentioning that every local master downloaded from the repository is a new copy, and is effectively a branch origin/master -> local/master?

I would. Git is a distributed VCS, after all, so I do think it's worth noting that origin/master and master can fall out of sync (which helps motivates why we need push). If you take the "let's focus on the DAG" approach, doing this also helps reduce the number of new concepts you need to introduce: master and origin/master are just two distinct labels you can attach to a node, just like any other branch or tag.

Is it worth mentioning that a headless git repository is no different than a local one, and that you can pull directly from a non-origin repo?

These ones you can probably skip -- these sorts of situations don't really come up (unless you're doing something like push-to-deploy).

Merge conflicts happen; should I mention how to go about resolving those?

Absolutely. Merge conflicts are common in school settings, where students frequently need to work on the same, small, subset of files.