1

I'm planning a sequence of lessons for how to build a web app using a demo app and building it from the ground up.

I would like to use git for 1) a repo of the demonstration app's code, and 2) have the git commit log help guide students.

Each lesson is a small step in building the web app. I'd like each lesson to correspond to a single git commit, where the student can see exactly what code changed in the lesson by viewing the lesson's commit on GitHub.

What I'm not sure of is how to do this and make it maintainable so the commit history is always in sequence of the lessons. Or is there an alternative technique commonly used to do this that I'm unaware of (such as using branches/tags/patches)? My main concerns are:

  • Making corrections and updates to lessons/commits and ensuring these changes appear throughout the subsequent commits
  • Updating dependencies such as 3rd-party JavaScript libraries in any of the commits
  • Keeping the commit history in order, so that each commit is equal to one lesson and it appears in sequence. If the first commit/lesson is updated much later after it was originally committed, then it should still be the first entry in the commit log.

Guidance, suggestions, feedback, and improvements are all welcome, thanks in advance!

Eliot Sykes
  • 9,616
  • 6
  • 50
  • 64
  • 1
    This is perfectly doable, but you'll have to be comfortable with amending and rebasing. – JB Nizet Feb 14 '15 at 13:56
  • 1
    Related questions: [Version control setup for a tutorial](http://stackoverflow.com/questions/5924302/version-control-setup-for-a-tutorial), [Tagging steps for a tutorial?](http://stackoverflow.com/questions/24928115/tagging-steps-for-a-tutorial) and [How to create a coding tutorial with snapshots in Git](http://stackoverflow.com/questions/14200886/how-to-create-a-coding-tutorial-with-snapshots-in-git) – xverges Mar 17 '15 at 20:16
  • I wrote a tool that allows you to check a Git repo into a Git repo, so you can create a history of your history. I made it for exactly this purpose. It's called "doublegit." https://github.com/depp/doublegit – Dietrich Epp Mar 17 '15 at 20:34

3 Answers3

2

Use branches - one branch for each lesson. So if you need to update the contents of a lesson afterwards, just make a commit in the lesson branch and, if needed, simply merge them to all following lesson branches.

Examples:

Two branches can be easily compared to show what's new in any given lesson. For example git diff lesson02..lesson03 shows what's new in lesson 3.

Rewriting git repo history (rebasing, amending etc.) is usually not OK. Please do not show your students otherwise. The git commit log will help guide students much better if it will include and not hide all bug fixes, upgrade changes etc.

Messa
  • 24,321
  • 6
  • 68
  • 92
  • I'm curious: was it a coincidence that we both answered this old question at about the same time, or my answer triggered some notification that prompted you to provide a better answer? – xverges Mar 18 '15 at 12:34
  • @Xv: I saw this question on the SO homepage, where are questions ordered by latest activity and also maybe filtered by preferred tags or some other magic. So it's not coincidence :) – Messa Mar 18 '15 at 13:15
1

git rebase in interactive mode should handle most of your use cases:

making corrections and updates to lessons/commits
View this post which describes how you would go about changing a file/commit from a previous lesson. You need to use git rebase -i to get into rebase interactive mode. Once you have selected the commit you want to change, you modify it with git commit --amend and then you continue the rebase.

updating dependencies
Here is a post which discusses how to add a new file in rebase interactive mode. This is the option to use if you need to add a new dependency to a lesson/commit. It's a bit more complicated than just modifying a file which already exists. As you might have guessed, you end up doing a git add inside the rebase.

When using rebase in both of these cases, you should keep in mind that you are rewriting the history of your lessons. As a result, if you git push -force the lessons branch to the repository, you run the risk of causing some confusion to your students.

Community
  • 1
  • 1
Tim Biegeleisen
  • 502,043
  • 27
  • 286
  • 360
0

If you remove the constrain of keeping the log in order so it can be read as the tutorial script, you can use tags. I'm under the impression that tags would make maintenance simpler and more natural.

The question How to create a coding tutorial with snapshots in Git describes the approach and points to an AngularJS tutorial that uses tags. The tutorial provides links with code comparisons: https://github.com/angular/angular-phonecat/compare/step-0...step-1

I'm planning to use this approach, so I'll need to get more familiar with git tagging and with updating the commit that is associated to a tag.

Community
  • 1
  • 1
xverges
  • 4,608
  • 1
  • 39
  • 60