From 9487d7ebdf29e795f96bb6113214517774c74901 Mon Sep 17 00:00:00 2001 From: Thomas Hebb Date: Tue, 16 Apr 2024 22:02:56 -0400 Subject: [PATCH 1/5] Update outline to match Lecture 2 contents --- lecture-notes/2-vcs.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/lecture-notes/2-vcs.md b/lecture-notes/2-vcs.md index 46f620f..b1d5385 100644 --- a/lecture-notes/2-vcs.md +++ b/lecture-notes/2-vcs.md @@ -2167,12 +2167,10 @@ subdirectories (which are sometimes inferred for ease of use). TODO: `HEAD` as a special ref pointing to your current checkout. -TODO: Talk about how either hashes or ref names can be used to refer to a -commit. Hashes are immutable, while refs may change. Say that either method -can be used in nearly every place you see us using one of them. +TODO: Refs define what's "in" a repository, more or less. Mention `git gc`, +dangers of committing while in detached HEAD. -TODO: There are operators that let you "move around" from a ref. For example, -`^` gets a ref's parent commit. Namedrop `man gitrevisions`. +TODO: Hashes are immutable, while refs may change. ### Exploring multiple branches From 86e9738e22a36efd7b4091043998d4dafb5c3ca3 Mon Sep 17 00:00:00 2001 From: Thomas Hebb Date: Tue, 16 Apr 2024 22:35:23 -0400 Subject: [PATCH 2/5] Incomplete overview of branches --- lecture-notes/2-vcs.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/lecture-notes/2-vcs.md b/lecture-notes/2-vcs.md index b1d5385..d8e450d 100644 --- a/lecture-notes/2-vcs.md +++ b/lecture-notes/2-vcs.md @@ -2138,12 +2138,31 @@ CONTENTS: More complex workflows ### Branches +Although we've mentioned them several times, we've yet to explain what +*branches* actually are. Conceptually, a branch is one specific line of +development---in other words, a specific commit history---within a Git +repository. Newly-created repositories have just a single branch, conventionally +named either `main` or `master`, and it's to this branch that our examples so +far have added commits. + +By creating other branches, you can keep track of more than just one history. +One branch, for example, might be an old version of the project, lacking new +commits from `main`. Another might contain everything from `main` plus +additional commits pertaining to an in-development feature. And yet another +might have no commits in common with `main` and hold a completely separate +codebase (although this is not common---typically branches within a single +repository share at least some commits). + TODO: "What is a branch?" paragraph. A convenient name you can use to reference a specific variant of your code or set of changes you're working on. TODO: Examples of what branches might be used for. Classify into long-lived branches and development/feature branches. +It's worth noting that there's nothing technically special about `main` as a +branch. Git treats it exactly like any other branch, save for its automatic +creation. By convention, however, many projects use `main` as TODO. + TODO: The concept of main/trunk/master as the main place where you commit new code and the one long-lived branch you can rely on virtually every project to have. Discussion of other long-lived branches you might encounter, like release From 0fc86b90ed18793735c3ef256906cb7233a67872 Mon Sep 17 00:00:00 2001 From: Thomas Hebb Date: Tue, 16 Apr 2024 23:03:18 -0400 Subject: [PATCH 3/5] Address Max comments --- lecture-notes/2-vcs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lecture-notes/2-vcs.md b/lecture-notes/2-vcs.md index d8e450d..af0d6e1 100644 --- a/lecture-notes/2-vcs.md +++ b/lecture-notes/2-vcs.md @@ -2139,11 +2139,11 @@ CONTENTS: More complex workflows ### Branches Although we've mentioned them several times, we've yet to explain what -*branches* actually are. Conceptually, a branch is one specific line of +*branches* actually are. Conceptually, a branch is one specific thread of development---in other words, a specific commit history---within a Git repository. Newly-created repositories have just a single branch, conventionally -named either `main` or `master`, and it's to this branch that our examples so -far have added commits. +named either `main` or `master`, and so far we have only added commits to this +branch. By creating other branches, you can keep track of more than just one history. One branch, for example, might be an old version of the project, lacking new From fe9e9da2e64982e2558dedf49f51616b23b4dfd8 Mon Sep 17 00:00:00 2001 From: Thomas Hebb Date: Mon, 29 Apr 2024 19:43:20 -0400 Subject: [PATCH 4/5] Some more about branches --- lecture-notes/2-vcs.md | 45 +++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/lecture-notes/2-vcs.md b/lecture-notes/2-vcs.md index af0d6e1..af0319a 100644 --- a/lecture-notes/2-vcs.md +++ b/lecture-notes/2-vcs.md @@ -2142,7 +2142,8 @@ Although we've mentioned them several times, we've yet to explain what *branches* actually are. Conceptually, a branch is one specific thread of development---in other words, a specific commit history---within a Git repository. Newly-created repositories have just a single branch, conventionally -named either `main` or `master`, and so far we have only added commits to this +named either `main` or `master` (which, save for being automatically created, is +identical to any other branch). So far we have only added commits to this branch. By creating other branches, you can keep track of more than just one history. @@ -2153,16 +2154,46 @@ might have no commits in common with `main` and hold a completely separate codebase (although this is not common---typically branches within a single repository share at least some commits). -TODO: "What is a branch?" paragraph. A convenient name you can use to reference -a specific variant of your code or set of changes you're working on. +Every branch has a name, which is by convention lowercase with hyphens (`-`) +between words. Depending on where you use it, a branch's name may refer either +to the branch itself or to the latest commit made to that branch---for example, +if you pass a branch name to a command that expects a revision parameter, like +`git show`: + +```console?prompt=$ +$ git show -s main +commit 0fb52357b6d1c76bda2d33890e1c8d2cd36ec792 (HEAD -> main) +Author: Thomas Hebb +Date: Wed Feb 28 22:35:12 2024 -0500 + + Revert "Support the modulo operator" + + This reverts commit 2d6603026105b168c126d2ee22c6f4dba8d48437. +$ +``` + +Note the annotation, `(HEAD -> main)`, that Git added to this commit. It tells +us two things: firstly, that this commit is the most recent commit in the `main` +branch; and secondly, that the working tree is currently based on `main`, +because that's where `HEAD` points. + +There is a difference between `HEAD` pointing to a branch and `HEAD` pointing +directly to the latest commit of that branch. In the former case (typically the +preferable one), we say that the branch itself is "checked out". When a branch +is checked out, `git commit` will automatically point that branch to the commit +it creates: in other words, it will add the commit to the branch. + +But when no branch is checked out and `HEAD` points directly to a commit (even +if there exists some branch that also points to that commit), `git commit` +doesn't point anything to newly-created commits. This state is called *detached +`HEAD`*, and it's very dangerous: if you ever navigate away from a commit you +make in detached `HEAD`, you may never be able to find it again! Even if you do +write down its hash somewhere, commits that aren't referenced by a branch or tag +can get deleted when a repository is cloned or "garbage collected" (`git gc`). TODO: Examples of what branches might be used for. Classify into long-lived branches and development/feature branches. -It's worth noting that there's nothing technically special about `main` as a -branch. Git treats it exactly like any other branch, save for its automatic -creation. By convention, however, many projects use `main` as TODO. - TODO: The concept of main/trunk/master as the main place where you commit new code and the one long-lived branch you can rely on virtually every project to have. Discussion of other long-lived branches you might encounter, like release From e4c5e20958bc997f4005cb3bbc7cc3599df12823 Mon Sep 17 00:00:00 2001 From: Thomas Hebb Date: Mon, 29 Apr 2024 19:47:26 -0400 Subject: [PATCH 5/5] Fix gc nit --- lecture-notes/2-vcs.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lecture-notes/2-vcs.md b/lecture-notes/2-vcs.md index af0319a..a1a1641 100644 --- a/lecture-notes/2-vcs.md +++ b/lecture-notes/2-vcs.md @@ -2189,7 +2189,8 @@ doesn't point anything to newly-created commits. This state is called *detached `HEAD`*, and it's very dangerous: if you ever navigate away from a commit you make in detached `HEAD`, you may never be able to find it again! Even if you do write down its hash somewhere, commits that aren't referenced by a branch or tag -can get deleted when a repository is cloned or "garbage collected" (`git gc`). +can get deleted when a repository is cloned or "garbage collected" during normal +Git operation. TODO: Examples of what branches might be used for. Classify into long-lived branches and development/feature branches.