GitKit (VSCode Edition): Learn git and GitHub in Context

Reviews the main git / GitHub concepts and vocabulary from Topic 1. The terms upstream repository, origin repository, local repository, local, remote, fork, and clone should be reviewed so that they begin to be part of the student’s working vocabulary.

Reviews the simplified workflow introduced in the previous topic. It should be re-emphasized that this is a simplified view and that this topic is about "un-simplifying" this view by filling in the details. The figure on this slide, shows a situation where a contributor has made changes to their local repository that they want to upstream.

Introduces branches and commits. In the diagrams on these slides, and throughout the remainder of the GitKit, different colors are used as the unique identifier for each commit (e.g. we can talk about the "red" or the "yellow" commit). This slide introduces a conceptual simplification to think of a commit as a complete "snapshot" of all files in the project repository at that point in time, along with some meta data. Depending on the level of the course being taught, it may be worth a moment here to to explore the idea that storing a complete copy of the files for each commit would be very inefficient and discuss that it does not work that way in practice. Git commits do not actually contain full copies of every file in the repo. Instead, for each file that is changed by the commit, the "snapshot" contains a full (compressed) copy of the file. For each file that is not changed by the commit, the "snapshot" contains only a link (like a shortcut) to that file. This link points to the file in the most recent commit in which it was changed. Depending on the level of the course being taught, this can also provide an opportunity to distinguish git from other delta-based version control systems (cvs, svn) where commits record changes to files rather than complete copies of the changed files.

The rule that they should "only commit to feature branches" is introduced here. Rather than attempting to provide a full explanation of the technical reasons for not committing to the main branch, this rule is based on the following rationale. Any time new work is started it should begin from the definitive version of the project. This definitive version is contained in the upstream main branch. Now recall, from the first topic, that only the project maintainers have the permissions necessary to change the upstream main branch. Thus, keeping your copies of the main branch identical to the upstream (i.e. by not committing to it) allows you to start your work from the definitive version. This explanation often elicits the question of what happens when the maintainers change the upstream main branch? That question can be put off, as how to keep in synch with the upstream is the focus of the next topic.

The diagrams used by the GitKit to illustrate git and GitHub concepts are extended to include branches and commits. The convention of using colors as the unique identifier for each commit is also used in these diagrams. In doing so, it is important to emphasize the distinction between the final commit in the active branch and the local files. Before any changes are made, the local files can be thought of as a copy of the final commit in the active branch. This is illustrated by initially having the "dot" in the local files be green, the same color as the final commit in the main branch.

The diagrams here illustrate creating and switching to a feature branch. With multiple branches, the concept of the active branch as the target for future commits becomes important and is introduced here. Later slides will show the addition of new commits to the active feature branch.

This diagram illustrates the editing of the local files. The difference between this diagram and the previous one can be easy to miss. The color of the "dot" in the local files changes from green to blue indicating that the local files have been edited. The fact that the final commit has remained green can be used here to further emphasize the fact that the final commit and the local files are distinct.

The diagrams here illustrate the process of staging changes and then committing them to the active branch. The notion that a commit should contain a "nameable unit of work" is introduced here. Additional attention to the idea of "nameable" is provided by several exercises in the chapter that have students assess the quality of commit messages. If time is available when presenting this topic, spending some class time on similar exercises in class would help to clarify that idea.

The diagrams here complete a full cycle of the forking workflow by illustrating the feature branch being pushed to GitHub and a pull request being made to the upstream repository. A point of emphasis here should be that pushing the branch to GitHub is necessary to make the changes that it contains available to the maintainers of the upstream. This can be used as another point at which to draw distinction between version control (git) and repository hosting (GitHub). Specifically, pull requests are a repository hosting feature created to facilitate collaboration by allowing many contributors to work on changes and submit them to the upstream for consideration.

If a student is seeing commit dates, usernames and messages that differ from the correct answers then it is likely that they created their fork after PRs were merged at the start of Chapter 4. Other than difficulty answering these questions this will not cause an issue with continuing with this chapter. Issues will arise with the exercises in Chapter 4 and Section 5.4. Each of those chapters provide the students with instructions for resolving the issues at the point where they arise.

The git status command here should show one untracked file with modifications and that file should agree with the file that they identified in Exercise 3.4.1.

This question is a good checkpoint to ensure that they have done things correctly to this point. The most recent commit in the git log output should show that they committed changes to the correct file (i.e. the one from Exercise 3.4.1) and that they have used a meaningful commit message.