From a91233e24b4a382b802fd0c27090b99da3eee010 Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Fri, 29 Aug 2025 12:16:58 +0100 Subject: [PATCH 1/2] Add callouts explaining branches Addresses #54. --- episodes/02-getting-started.md | 15 ++- episodes/05-github-pages.md | 14 +++ episodes/fig/git-branch.svg | 129 ++++++++++++++++++++ episodes/fig/git-branches.svg | 214 +++++++++++++++++++++++++++++++++ 4 files changed, 371 insertions(+), 1 deletion(-) create mode 100644 episodes/fig/git-branch.svg create mode 100644 episodes/fig/git-branches.svg diff --git a/episodes/02-getting-started.md b/episodes/02-getting-started.md index 87607b8b..14b13320 100644 --- a/episodes/02-getting-started.md +++ b/episodes/02-getting-started.md @@ -167,9 +167,22 @@ No commits yet nothing to commit (create/copy files and use "git add" to track) ``` -The output tells us that we are on the main branch (more on this later) and that we have nothing to commit (no +The output tells us that we are on the main branch and that we have nothing to commit (no unsaved changes). +::::::::::::::::::::::::::::::::::::::::: callout + +## Branches and commits + +Commits in Git are like snapshots of our project. +They are ordered into sequences, or "branches", with each commit pointing back to the one before it in the branch. +Git keeps track of the last commit in each branch with a special label; +in this lesson we mostly use one branch with the label "main". + +![](fig/git-branch.svg){alt='The label ‘main’ points to commit c2; c2 points to its parent c1, which points to c0.'} + +:::::::::::::::::::::::::::::::::::::::::::::::::: + ### Two steps: Adding and committing We will now create and save our first project file. This is a two-step process. First, we **add** any files for which diff --git a/episodes/05-github-pages.md b/episodes/05-github-pages.md index 7bddf9ae..cfb8af71 100644 --- a/episodes/05-github-pages.md +++ b/episodes/05-github-pages.md @@ -133,6 +133,20 @@ it's more practical to grant everyone access to commit directly instead. :::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::::::::::::::::::::::::::: callout + +## Branching and merging + +Branches get their name because you can create a new one (say, "patch") +that splits off from an existing one like "main", +allowing different sets of changes to be made in parallel. +Later on, Git can take the changes from "patch" and merge (copy) them into the "main" branch. +In the last challenge, GitHub did all this for us in the background. + +![](fig/git-branches.svg){alt='The label ‘main’ points to commit c5; c5 points to its parent c3, which points to c1, which points to c0. The label ‘patch’ points to commit c4, which points to c2, which points to c1. Commit c5 also points to c4 as a secondary parent, indicating ‘patch’ was merged into ‘main’.'} + +:::::::::::::::::::::::::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: challenge ## Optional challenge: Contributing to a page owned by someone else (slightly more complicated way) diff --git a/episodes/fig/git-branch.svg b/episodes/fig/git-branch.svg new file mode 100644 index 00000000..c18e72a1 --- /dev/null +++ b/episodes/fig/git-branch.svg @@ -0,0 +1,129 @@ + + + + + + + + + + + + c0 + + + c1 + + + c2 + + main + + + + diff --git a/episodes/fig/git-branches.svg b/episodes/fig/git-branches.svg new file mode 100644 index 00000000..6626cebf --- /dev/null +++ b/episodes/fig/git-branches.svg @@ -0,0 +1,214 @@ + + + + + + + + + + + + + + c0 + + + c1 + + + c2 + + + c3 + + + c4 + + + c5 + + patch + + main + + + + + + From 79a0e9f12a4bda32b8055d9fdf74b15ae31c7f3a Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Fri, 29 Aug 2025 12:52:58 +0100 Subject: [PATCH 2/2] Shorten alt text for branching diagram --- episodes/05-github-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/05-github-pages.md b/episodes/05-github-pages.md index cfb8af71..ef272747 100644 --- a/episodes/05-github-pages.md +++ b/episodes/05-github-pages.md @@ -143,7 +143,7 @@ allowing different sets of changes to be made in parallel. Later on, Git can take the changes from "patch" and merge (copy) them into the "main" branch. In the last challenge, GitHub did all this for us in the background. -![](fig/git-branches.svg){alt='The label ‘main’ points to commit c5; c5 points to its parent c3, which points to c1, which points to c0. The label ‘patch’ points to commit c4, which points to c2, which points to c1. Commit c5 also points to c4 as a secondary parent, indicating ‘patch’ was merged into ‘main’.'} +![](fig/git-branches.svg){alt='The label ‘main’ points to commit c5; arrows point from c5 to c3 to c1 to c0. The label ‘patch’ points to commit c4; arrows point from c4 to c2 to c1. A dotted arrow points from c5 to c4.'} ::::::::::::::::::::::::::::::::::::::::::::::::::