Skip to content

Conversation

alex-ball
Copy link
Contributor

These changes provide the explanation of branches that is promised but not delivered in the lesson.

In order to keep the cognitive load light, I've split the explanation into two parts:

  • In episode 2, following the use of git status, we explain branches as labelled sequences of commits. This is all we need for episodes 2-4.
  • In episode 5, following the first pull request challenge, we explain what just happened in terms of branching and merging.

Each of these is illustrated with a diagram. The first one is there primarily to make the second one seem more familiar.

  • In common with how the Git Book does it, the arrows between commits point backwards in time. I've used triangular arrow heads to evoke how UML shows class inheritance: each commit "inherits" the last one then changes it a bit. The callout in episode 2 says commits point back to their parents, to explain this.
  • I used a dashed arrow for the merged-parent relationship to emphasise that merging isn't a symmetrical operation.
  • I have used colours from the stylesheet so they tone with the rest of the site; these choices seem to work well in both light and dark mode, normally and when viewed in greyscale.
  • The alt texts describe the diagrams structurally rather than captioning them, in an attempt to improve accessibility.

Addresses #54.

Copy link

github-actions bot commented Aug 29, 2025

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

  • 🎯 correct output
  • 🖼️ correct figures
  • ❓ new warnings
  • ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/LibraryCarpentry/lc-git/compare/md-outputs..md-outputs-PR-190

The following changes were observed in the rendered markdown documents:

 02-getting-started.md      |  15 +++-
 05-github-pages.md         |  14 +++
 fig/git-branch.svg (new)   | 129 +++++++++++++++++++++++++++
 fig/git-branches.svg (new) | 214 +++++++++++++++++++++++++++++++++++++++++++++
 md5sum.txt                 |   4 +-
 5 files changed, 373 insertions(+), 3 deletions(-)
What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2025-08-29 12:05:05 +0000

github-actions bot pushed a commit that referenced this pull request Aug 29, 2025
@srerickson
Copy link
Contributor

srerickson commented Sep 2, 2025

This is really great. I was considering whether to expand the initial callout to explain the the idea of an active branch, but I think simpler is better, especially since we don't talk about "HEAD" in this lesson. The SVGs look great in both light/dark modes.

@srerickson srerickson assigned alex-ball and unassigned srerickson Sep 2, 2025
@alex-ball alex-ball merged commit 7ad567b into LibraryCarpentry:main Sep 3, 2025
3 checks passed
@alex-ball alex-ball deleted the patch-54 branch September 3, 2025 08:36
github-actions bot pushed a commit that referenced this pull request Sep 3, 2025
Auto-generated via `{sandpaper}`
Source  : 7ad567b
Branch  : main
Author  : Alex Ball <alex-ball@users.noreply.github.com>
Time    : 2025-09-03 08:36:28 +0000
Message : Merge pull request #190 from alex-ball/patch-54

Add callouts explaining branches
github-actions bot pushed a commit that referenced this pull request Sep 3, 2025
Auto-generated via `{sandpaper}`
Source  : 22d5032
Branch  : md-outputs
Author  : GitHub Actions <actions@github.com>
Time    : 2025-09-03 08:37:04 +0000
Message : markdown source builds

Auto-generated via `{sandpaper}`
Source  : 7ad567b
Branch  : main
Author  : Alex Ball <alex-ball@users.noreply.github.com>
Time    : 2025-09-03 08:36:28 +0000
Message : Merge pull request #190 from alex-ball/patch-54

Add callouts explaining branches
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants