Git and related corrections and improvements

df53ae0fdd98e9452095ac2fdaf95fcfac8c9c7f (2023-04-23):

* removed portsnap
* encourages use of Git.

This round of Git-oriented corrections and changes is, essentially,
timed to precede creation of the releng/14.0 branch. Not intended to be
comprehensive.

Attention to things such as:

* HEAD (not a branch) and main (branch)
* main (not a branch) and mainline
* repositories (there are three)
* ports latest, current (not CURRENT) and quarterly
* FREEBSD-CURRENT and FREEBSD-STABLE
* master
* things that were relevant only around the time of migration to Git
* markup
* grammar.

Under
https://docs.freebsd.org/en/articles/committers-guide/#_rebasing_your_change_against_latest_freebsd_source_tree
a list of items was misrepresented as a single paragraph with asterisk
characters in its midst.

Reviewed by:           carlavilla, imp
Approved by:           imp
Pull Request:          https://github.com/freebsd/freebsd-doc/pull/182
Differential revision: https://reviews.freebsd.org/D40026

4 files changed, 94 insertions, 123 deletions

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 8cdd145f75..47d7060859 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -434,13 +434,24 @@ There are two ways to download.
 Most people will want to do a deep clone of the repository.
 However, there are times when you may wish to do a shallow clone.
 
-===== Branch names
-The branch names in the new Git repository are similar to the old names.
-For the stable branches, they are stable/X where X is the major release (like 11 or 12).
-The main branch in the new repository is 'main'.
-The main branch in the old GitHub mirror was 'master', but is now 'main'.
-Both reflect the defaults of Git at the time they were created.
-The 'main' branch is the default branch if you omit the '-b branch' or '--branch branch' options below.
+===== Branch Names
+FreeBSD-CURRENT uses the  `main` branch.
+
+`main` is the default branch.
+
+For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`.
+
+For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` and `releng/13.2`.
+
+https://www.freebsd.org/releng/[] shows:
+
+* `main` and `stable/⋯` branches open
+* `releng/⋯` branches, each of which is frozen when a release is tagged.
+
+Examples:
+
+* tag https://cgit.freebsd.org/src/tag/?h=release/13.1.0[release/13.1.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.1[releng/13.1] branch
+* tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch.
 
 ===== Repositories
 Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD sources.
@@ -455,12 +466,12 @@ It is the easiest to do.
 It also allows you to use Git's worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository.
 [source,shell]
 ....
-% git clone -o freebsd $URL -b branch [dir]
+% git clone -o freebsd $URL -b branch [<directory>]
 ....
-is how you make a deep clone.
-'branch' should be one of the branches listed in the previous section.
-It is optional if it is the main branch.
-'dir' is an optional directory to place it in (the default will be the name of the repo you are cloning (src, doc, etc)).
+-- will create a deep clone.
+`branch` should be one of the branches listed in the previous section.
+If no `branch` is given: the default (`main`) will be used.
+If no `<directory>` is given: the name of the new directory will match the name of the repo ([.filename]#doc#, [.filename]#ports# or [.filename]#src#).
 
 You will want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch.
 It is the easiest to keep up to date as well.
@@ -481,7 +492,7 @@ However, see below for a significant limitation of this approach.
 
 This clones the repository, but only has the most recent version in the repository.
 The rest of the history is not downloaded.
-Should you change your mind later, you can do 'git fetch --unshallow' to get the old history.
+Should you change your mind later, you can do `git fetch --unshallow` to get the old history.
 
 [WARNING]
 ====
@@ -516,15 +527,15 @@ This pulls in all the revisions since your last update.
 ....
 will update the tree.
 In Git, a 'fast forward' merge is one that only needs to set a new branch pointer and doesn't need to re-create the commits.
-By always doing a 'fast forward' merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree.
+By always doing a fast forward merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree.
 This will be important if you want to maintain local patches.
 
 See below for how to manage local changes.
-The simplest is to use --autostash on the 'git pull' command, but more sophisticated options are available.
+The simplest is to use `--autostash` on the `git pull` command, but more sophisticated options are available.
 
 ==== Selecting a Specific Version
 
-In Git, the 'git checkout' checks out both branches and specific versions.
+In Git, `git checkout` checks out both branches and specific versions.
 Git's versions are the long hashes rather than a sequential number.
 
 When you checkout a specific version, just specify the hash you want on the command line (the git log command can help you decide which hash you might want):
@@ -558,28 +569,28 @@ Sometimes, things go wrong.
 The last version worked, but the one you just updated to does not.
 A developer may ask you to bisect the problem to track down which commit caused the regression.
 
-Git makes bisecting changes easy with a powerful 'git bisect' command.
+Git makes bisecting changes easy with a powerful `git bisect` command.
 Here's a brief outline of how to use it.
 For more information, you can view https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details.
 The man git-bisect page is good at describing what can go wrong, what to do when versions won't build, when you want to use terms other than 'good' and 'bad', etc, none of which will be covered here.
 
 `git bisect start --first-parent` will start the bisection process.
 Next, you need to tell a range to go through.
-'git bisect good XXXXXX' will tell it the working version and 'git bisect bad XXXXX' will tell it the bad version.
+`git bisect good XXXXXX` will tell it the working version and `git bisect bad XXXXX` will tell it the bad version.
 The bad version will almost always be HEAD (a special tag for what you have checked out).
 The good version will be the last one you checked out.
 The `--first-parent` argument is necessary so that subsequent `git bisect` commands do not try to check out a vendor branch which lacks the full FreeBSD source tree.
 
 [TIP]
 ====
-If you want to know the last version you checked out, you should use 'git reflog':
+If you want to know the last version you checked out, you should use `git reflog`:
 [source,shell]
 ....
 5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward
 a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main
 ...
 ....
-shows me moving the working tree to the main branch (a816...) and then updating from upstream (to 5ef0...).
+shows me moving the working tree to the `main` branch (a816...) and then updating from upstream (to 5ef0...).
 In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165.
 As you can see from the output, HEAD@{1} also often works, but isn't foolproof if you have done other things to your Git tree after updating, but before you discover the need to bisect.
 ====
@@ -596,11 +607,11 @@ Bisecting: 1722 revisions left to test after this (roughly 11 steps)
 ....
 
 You would then build/install that version.
-If it's good you'd type 'git bisect good' otherwise 'git bisect bad'.
-If the version doesn't compile, type 'git bisect skip'.
+If it's good you'd type `git bisect good` otherwise `git bisect bad`.
+If the version doesn't compile, type `git bisect skip`.
 You will get a similar message to the above after each step.
 When you are done, report the bad version to the developer (or fix the bug yourself and send a patch).
-'git bisect reset' will end the process and return you back to where you started (usually tip of main).
+`git bisect reset` will end the process and return you back to where you started (usually tip of `main`).
 Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.
 
 [[git-gpg-signing]]
@@ -661,8 +672,8 @@ The cgit repository web interface for use with web browsers is at https://cgit.F
 The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git).
 
 There is also a mirror on GitHub, see extref:{handbook}/mirrors[External mirrors, mirrors] for an overview.
-The 'current' branch is 'main' .
-The quarterly branches are named 'yyyyQn' for year 'yyyy' and quarter 'n'.
+The _latest_ branch is `main`.
+The _quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'.
 
 [[port-commit-message-formats]]
 ===== Commit message formats
@@ -703,16 +714,16 @@ However, if you have local changes, you can use the same tool to manage them as
 All changes that you have not pushed are local and can easily be modified (git rebase, discussed below does this).
 
 ===== Keeping local changes
-The simplest way to keep local changes (especially trivial ones) is to use 'git stash'.
-In its simplest form, you use 'git stash' to record the changes (which pushes them onto the stash stack).
+The simplest way to keep local changes (especially trivial ones) is to use `git stash`.
+In its simplest form, you use `git stash` to record the changes (which pushes them onto the stash stack).
 Most people use this to save changes before updating the tree as described above.
-They then use 'git stash apply' to re-apply them to the tree.
-The stash is a stack of changes that can be examined with 'git stash list'.
+They then use `git stash apply` to re-apply them to the tree.
+The stash is a stack of changes that can be examined with `git stash list`.
 The git-stash man page (https://git-scm.com/docs/git-stash) has all the details.
 
 This method is suitable when you have tiny tweaks to the tree.
 When you have anything non trivial, you'll likely be better off keeping a local branch and rebasing.
-Stashing is also integrated with the 'git pull' command: just add '--autostash' to the command line.
+Stashing is also integrated with the `git pull` command: just add `--autostash` to the command line.
 
 ===== Keeping a local branch
 [[keeping_a_local_branch]]
@@ -723,7 +734,7 @@ Git also allows one to merge, along with the same problems.
 That's one way to manage the branch, but it's the least flexible.
 
 In addition to merging, Git supports the concept of 'rebasing' which avoids these issues.
-The 'git rebase' command replays all the commits of a branch at a newer location on the parent branch.
+The `git rebase` command replays all the commits of a branch at a newer location on the parent branch.
 We will cover the most common scenarios that arise using it.
 
 ====== Create a branch
@@ -760,7 +771,7 @@ The commit will pop you into an editor to describe what you've done.
 Once you enter that, you have your own **local** branch in the Git repo.
 Build and install it like you normally would, following the directions in the handbook.
 Git differs from other version control systems in that you have to tell it explicitly which files to commit.
-I have opted to do it on the commit command line, but you can also do it with 'git add' which many of the more in depth tutorials cover.
+I have opted to do it on the commit command line, but you can also do it with `git add` which many of the more in depth tutorials cover.
 
 ====== Time to update
 
@@ -837,7 +848,7 @@ If the commit message is still accurate, just exit the editor.
 If you get stuck during the rebase, do not panic.
 git rebase --abort will take you back to a clean slate.
 It is important, though, to start with an unmodified tree.
-An aside: The above mentioned 'git reflog' comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick.
+An aside: The above mentioned `git reflog` comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick.
 
 For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment.
 It is a good resource for issues that arise occasionally but are too obscure for this guide.
@@ -853,7 +864,7 @@ If you have a deep clone, the following will suffice:
 If you have a local branch, though, there are one or two caveats.
 First, rebase will rewrite history, so you will likely want to do something to save it.
 Second, jumping branches tends to cause more conflicts.
-If we pretend the example above was relative to stable/12, then to move to main, I'd suggest the following:
+If we pretend the example above was relative to stable/12, then to move to `main`, I'd suggest the following:
 [source,shell]
 ....
 % git checkout no-color-ls
@@ -863,50 +874,9 @@ If we pretend the example above was relative to stable/12, then to move to main,
 
 What the above does is checkout no-color-ls.
 Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it.
-Then you rebase onto the main branch.
+Then you rebase onto the `main` branch.
 This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will
-replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a place holder name).
-
-===== Migrating from an existing Git clone
-If you have work based on a previous Git conversion or a locally running git-svn conversion, migrating to new repository can encounter problems because Git has no knowledge about the connection between the two.
-
-When you have only a few local changes, the easiest way would be to cherry-pick those changes to the new base:
-[source,shell]
-....
-% git checkout main
-% git cherry-pick old_branch..your_branch
-....
-Or alternatively, do the same thing with rebase:
-[source,shell]
-....
-% git rebase --onto main master your_branch
-....
-
-If you do have a lot of changes, you would probably want to perform a merge instead.
-The idea is to create a merge point that consolidates the history of the old_branch, and the new FreeBSD repository (main).
-
-You can find out by looking up the same commit that are found on both parents:
-[source,shell]
-....
-% git show old_branch
-....
-You will see a commit message, now search for that in the new branch:
-[source,shell]
-....
-% git log --grep="commit message on old_branch" freebsd/main
-....
-You would help locate the commit hash on the new main branch, create a helper branch (in the example we call it 'stage') from that hash:
-[source,shell]
-....
-% git checkout -b stage _hash_found_from_git_log_
-....
-Then perform a merge of the old branch:
-[source,shell]
-....
-% git merge -s ours -m "Mark old branch as merged" old_branch
-....
-With that, it's possible to merge your work branch or the main branch in any order without problem.
-Eventually, when you are ready to commit your work back to main, you can perform a rebase to main, or do a squash commit by combining everything into one commit.
+replay them onto the `main` branch creating a new no-color-ls branch there (which is why I had you create a place holder name).
 
 [[mfc-with-git]]
 === MFC (Merge From Current) Procedures
@@ -989,9 +959,9 @@ Once the MFC is complete, you can delete the temporary branch:
 
 ==== MFC a vendor import
 
-Vendor imports are the only thing in the tree that creates a merge commit in the main line.
+Vendor imports are the only thing in the tree that creates a merge commit in the `main` branch.
 Cherry picking merge commits into stable/XX presents an additional difficulty because there are two parents for a merge commit.
-Generally, you'll want the first parent's diff since that's the diff to mainline (though there may be some exceptions).
+Generally, you'll want the first parent's diff since that's the diff to `main` (though there may be some exceptions).
 
 [source,shell]
 ....
@@ -1000,9 +970,9 @@ Generally, you'll want the first parent's diff since that's the diff to mainline
 is typically what you want.
 This will tell cherry-pick to apply the correct diff.
 
-There are some, hopefully, rare cases where it's possible that the mainline was merged backwards by the conversion script.
-Should that be the case (and we've not found any yet), you'd change the above to '-m 2' to pickup the proper parent.
-Just do
+There are some, hopefully, rare cases where it's possible that the `main` branch was merged backwards by the conversion script.
+Should that be the case (and we've not found any yet), you'd change the above to `-m 2` to pickup the proper parent.
+Just do:
 [source,shell]
 ....
 % git cherry-pick --abort
@@ -1019,7 +989,7 @@ then the easiest way is to use `git reset --hard` like so:
 % git reset --hard freebsd/stable/12
 ....
 though if you have some revs you want to keep, and others you don't,
-using 'git rebase -i' is better.
+using `git rebase -i` is better.
 
 ==== Considerations when MFCing
 
@@ -1031,7 +1001,7 @@ When committing source commits to stable and releng branches, we have the follow
 
 With Subversion, we used the following practices to achieve these goals:
 
-* Using 'MFC' and 'MFS' tags to mark commits that merged changes from another branch.
+* Using `MFC` and `MFS` tags to mark commits that merged changes from another branch.
 * Squashing fixup commits into the main commit when merging a change.
 * Recording mergeinfo so that `svn mergeinfo --show-revs` worked.
 
@@ -1046,7 +1016,7 @@ Instead, when this document refers to "merge commits", it means a commit origina
 
 Git provides some built-in support for this via the `git cherry` and `git log --cherry` commands.
 These commands compare the raw diffs of commits (but not other metadata such as log messages) to determine if two commits are identical.
-This works well when each commit from head is landed as a single commit to a stable branch, but it falls over if multiple commits from main are squashed together as a single commit to a stable branch.
+This works well when each commit from `main` is landed as a single commit to a stable branch, but it falls over if multiple commits from `main` are squashed together as a single commit to a stable branch.
 The project makes extensive use of `git cherry-pick -x` with all lines preserved to work around these difficulties and is working on automated tooling to take advantage of this.
 
 ==== Commit message standards
@@ -1066,7 +1036,7 @@ Should it include the metadata from the original commit unchanged, or should it
 Historical practice has varied, though some of the variance is by field.
 For example, MFCs that are relevant to a PR generally include the PR field in the MFC so that MFC commits are included in the bug tracker's audit trail.
 Other fields are less clear.
-For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the `main` commit with the landed commits.
+For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the main commit with the landed commits.
 The list of reviewers is also not clear.
 If a reviewer has approved a change to `main`, does that mean they have approved the MFC commit?  Is that true if it's identical code only, or with merely trivial rework? It's clearly not true for more extensive reworks.
 Even for identical code what if the commit doesn't conflict but introduces an ABI change?  A reviewer may have ok'd a commit for `main` due to the ABI breakage but may not approve of merging the same commit as-is.
@@ -1179,16 +1149,17 @@ Regular `git rebase` or `git pull --rebase` doesn't know how to rebase a merge c
 so instead of that you would have to recreate the commit.
 
 The following steps should be taken to easily recreate the merge commit as if `git rebase --merge-commits` worked properly:
+
 * cd to the top of the repo
 * Create a side branch `XXX` with the **contents** of the merged tree.
 * Update this side branch `XXX` to be merged and up-to-date with FreeBSD's `main` branch.
 ** In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this  should be really rare.
 ** Resolve conflicts, and collapse multiple commits down to 1 if need be (without conflicts, there's no collapse needed)
-* checkout main
+* checkout `main`
 * create a branch `YYY` (allows for easier unwinding if things go wrong)
 * Re-do the subtree merge
 * Instead of resolving any conflicts from the subtree merge, checkout the contents of XXX on top of it.
-** The trailing '.' is important, as is being at the top level of the repo.
+** The trailing `.` is important, as is being at the top level of the repo.
 ** Rather than switching branches to XXX, it splats the contents of XXX on top of the repo
 * Commit the results with the prior commit message (the example assumes there's only one merge on the XXX branch).
 * Make sure the branches are the same.
@@ -1228,7 +1199,7 @@ After review, when you are sure it is a good change, you can push it to the Free
 
 [source,shell]
 ....
-% git push freebsd YYY:main	# put the commit on upstream's main branch
+% git push freebsd YYY:main	# put the commit on upstream's 'main' branch
 % git branch -D XXX		# Throw away the throw-a-way branches.
 % git branch -D YYY
 ....
@@ -1351,7 +1322,7 @@ Here 'good' means:
 
 . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.
 . No other changes are in the tree.
-. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD main line and any caveats.
+. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.
 . UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.
 
 [NOTE]
@@ -1368,7 +1339,7 @@ When you checkout `main` make sure that you have no diffs.
 It's a lot easier to commit those to a branch (or use `git stash`) before doing the following.
 
 If you are used to `git pull`, we strongly recommend using the `--ff-only` option, and further setting it as the default option.
-Alternatively, `git pull --rebase` is useful if you have changes staged in the main branch.
+Alternatively, `git pull --rebase` is useful if you have changes staged in the `main` branch.
 
 [source,shell]
 ....
@@ -1397,7 +1368,7 @@ The longer form is also recommended.
 % git merge --ff-only freebsd/main
 ....
 
-These commands reset your tree to the main branch, and then update it from where you pulled the tree from originally.
+These commands reset your tree to the `main` branch, and then update it from where you pulled the tree from originally.
 It's important to switch to `main` before doing this so it moves forward.
 Now, it's time to move the changes forward:
 
@@ -1434,9 +1405,9 @@ freefall% gen-gitconfig.sh
 
 on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH.
 
-The below command merges the `working` branch into the upstream main line.
+The below command merges the `working` branch into the upstream `main` branch.
 It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this.
-This syntax pushes the `working` branch to main, moving the `main` branch forward.
+This syntax pushes the `working` branch to `main`, moving the `main` branch forward.
 You will only be able to do this if this results in a linear change to `main` (e.g. no merges).
 
 [source,shell]
@@ -1555,9 +1526,9 @@ Here's https://adventurist.me/posts/00296[a good writeup] that goes into more de
 
 ==== Developers
 
-===== Ooops! I committed to `main` instead of a branch.
+===== Ooops! I committed to `main`, instead of another branch.
 
-**Q:** From time to time, I goof up and commit to main instead of to a branch. What do I do?
+**Q:** From time to time, I goof up and mistakenly commit to the `main` branch. What do I do?
 
 **A:** First, don't panic.
 
@@ -1598,7 +1569,7 @@ cherry-pick it over.
 **Q:** But what if I want to commit a few changes to `main`, but keep the rest in `wilma` for some reason?
 
 **A:** The same technique above also works if you are wanting to 'land' parts of the branch you are working on into `main` before the rest of the branch is ready (say you noticed an unrelated typo, or fixed an incidental bug).
-You can cherry pick those changes into main, then push to the parent repository.
+You can cherry pick those changes into `main`, then push to the parent repository.
 Once you've done that, cleanup couldn't be simpler: just `git rebase -i`.
 Git will notice you've done this and skip the common changes automatically (even if you had to change the commit message or tweak the commit slightly).
 There's no need to switch back to wilma to adjust it: just rebase!
@@ -1675,8 +1646,8 @@ You can also stack:
 ....
 
 and you are ready to try again.
-The 'checkout -B' with the hash combines checking out and creating a branch for it.
-The -B instead of -b forces the movement of a pre-existing branch.
+The `checkout -B` with the hash combines checking out and creating a branch for it.
+The `-B` instead of `-b` forces the movement of a pre-existing branch.
 Either way works, which is what's great (and awful) about Git.
 One reason I tend to use `git checkout -B xxxx hash` instead of checking out the hash, and then creating / moving the branch is purely to avoid the slightly distressing message about detached heads:
 
@@ -1703,7 +1674,7 @@ this produces the same effect, but I have to read a lot more and severed heads a
 
 ===== Ooops! I did a `git pull` and it created a merge commit, what do I do?
 
-**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on the mainline.
+**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on `main`.
 How do I recover?
 
 **A:** This can happen when you invoke the pull with your development branch checked out.
@@ -1853,7 +1824,7 @@ However, there are two disadvantages to this if you want to use it for anything
 
 First, this is a 'bare repository' which has the repository database, but no checked out worktree.
 This is great for mirroring, but terrible for day to day work.
-There's a number of ways around this with 'git worktree':
+There's a number of ways around this with `git worktree`:
 
 [source,shell]
 ....
@@ -1890,7 +1861,7 @@ To setup your repository to do that:
 git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'
 ....
 
-which will put everything in the upstream repository into your local repository's 'refs/freebsd/' namespace.
+which will put everything in the upstream repository into your local repository's `refs/freebsd/` namespace.
 Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large.
 
 You'll need to refer to these 'refs' with their full name because they aren't in and of Git's regular namespaces.
@@ -1907,7 +1878,7 @@ would look at the log for the vendor branch for zlib starting at 1.2.10.
 One of the keys to good software development on a project as large as FreeBSD is the ability to collaborate with others before you push your changes to the tree.
 The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, in order to share changes in a user-generated branch.
 
-The following instructions show how to set up a user-generated branch, based on the FreeBSD main branch, and push it to GitHub.
+The following instructions show how to set up a user-generated branch, based on the FreeBSD `main` branch, and push it to GitHub.
 
 Before you begin, make sure that your local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>>
 
@@ -2340,7 +2311,7 @@ Detailed information on how to access these branches can be found in <<admin-bra
 == Pre-Commit Review
 
 Code review is one way to increase the quality of software.
-The following guidelines apply to commits to the `head` (-CURRENT) branch of the `src` repository.
+The following guidelines apply to commits to the `main` (-CURRENT) branch of the `src` repository.
 Other branches and the `ports` and `docs` trees have their own review policies, but these guidelines generally apply to commits requiring review:
 
 * All non-trivial changes should be reviewed before they are committed to the repository.
@@ -2750,7 +2721,7 @@ If you have code in the tree with the advertising clause, please consider removi
 In fact, please consider using the above license for your code.
 
 The FreeBSD project discourages completely new licenses and variations on the standard licenses.
-New licenses require the approval of the {core-email} to reside in the main repository.
+New licenses require the approval of {core-email} to reside in the `src` repository.
 The more different licenses that are used in the tree, the more problems that this causes to those wishing to utilize this code, typically from unintended consequences from a poorly worded license.
 
 Project policy dictates that code under some non-BSD licenses must be placed only in specific sections of the repository, and in some cases, compilation must be conditional or even disabled by default.
@@ -3543,8 +3514,8 @@ Merging commits to the quarterly branch (a process we call MFH for a historical
 % git push
 ....
 
-where '$HASH' is the hash of the commit you want to copy over to the quarterly branch.
-The -x parameter ensures the hash '$HASH' of the main branch is included in the new commit message of the quarterly branch.
+where `$HASH` is the hash of the commit you want to copy over to the quarterly branch.
+The `-x` parameter ensures the hash `$HASH` of the `main` branch is included in the new commit message of the quarterly branch.
 
 [[ports-qa-new-category]]
 === Creating a New Category
diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
index 930347ffbc..b1b07c7f6a 100644
--- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc
+++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
@@ -810,7 +810,7 @@ STABLE branches occasionally have bugs or incompatibilities which might affect u
 
 |`_X_-CURRENT`
 |`main`
-|The latest unreleased development version of FreeBSD. The CURRENT branch can have major bugs or incompatibilities and is recommended only for advanced users.
+|The latest unreleased development version of FreeBSD. The `main` branch can have major bugs or incompatibilities and is recommended only for advanced users.
 |===
 
 Determine which version of FreeBSD is being used with man:uname[1]:
diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc
index 745929f36b..24669e2d4a 100644
--- a/documentation/content/en/books/handbook/glossary.adoc
+++ b/documentation/content/en/books/handbook/glossary.adoc
@@ -582,7 +582,7 @@ Massachusetts Institute of Technology::
 
 [[mfc-glossary]]
 Merge From Current::
-To merge functionality or a patch from the -CURRENT branch to another, most often -STABLE.
+To merge functionality or a patch from the `main` branch (-CURRENT) to another, most often -STABLE.
 
 [[mfh-glossary]]
 Merge From Head::
diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc
index 4690379e63..cd0afab183 100644
--- a/documentation/content/en/books/handbook/ports/_index.adoc
+++ b/documentation/content/en/books/handbook/ports/_index.adoc
@@ -163,7 +163,7 @@ Do you want to fetch and install it not? [y/N]
 
 man:pkg[7] will intercept the command, and if you confirm that is your intention, download the man:pkg[8] tarball, install man:pkg[8] from it, bootstrap the local package database and then proceed to run the command you originally requested.
 
-More recent versions of man:pkg[7] understand `pkg -N` as a test to see if man:pkg[8] is installed without triggering the installation, and conversely, pkg bootstrap[-f] to install man:pkg[8] (or force it to be reinstalled) without performing any other actions.
+More recent versions of man:pkg[7] understand `pkg -N` as a test to see if man:pkg[8] is installed without triggering the installation, and conversely, `pkg bootstrap[-f]` to install man:pkg[8] (or force it to be reinstalled) without performing any other actions.
 
 Usage information for pkg is available in the man:pkg[8] manual page or by running `pkg` without additional arguments.
 Additional pkg configuration options are described in man:pkg.conf[5].
@@ -184,15 +184,15 @@ Refer to a command's help or man page for details and more examples.
 [[quarterly-latest-branch]]
 === Quarterly and Latest Ports Branches
 
-The `Quarterly` branch provides users with a more predictable and stable experience for port and package installation and upgrades.
+Quarterly branches provides users with a more predictable and stable experience for port and package installation and upgrades.
 This is done essentially by only allowing non-feature updates.
 Quarterly branches aim to receive security fixes (that may be version updates, or backports of commits), bug fixes and ports compliance or framework changes.
-The Quarterly branch is cut from HEAD at the beginning of every (yearly) quarter in January, April, July, and October.
+A quarterly is branched from `main` at the beginning of every (yearly) quarter in January, April, July, and October.
 Branches are named according to the year (YYYY) and quarter (Q1-4) they are created in.
-For example, the quarterly branch created in January 2023, is named 2023Q1.
-And the `Latest` branch provides the latest versions of the packages to the users.
+For example, the quarterly branch created in January 2023, is named `2023Q1`.
+`latest` provides the latest versions of ports.
 
-To switch man:pkg[8] from Quarterly to Latest run the following commands:
+To switch man:pkg.conf[5] from quarterly to latest -- if you do not already have a [.filename]#FreeBSD.conf# at [.filename]#/usr/local/etc/pkg/repos# -- run the following commands:
 
 [source,shell]
 ....
@@ -200,11 +200,11 @@ To switch man:pkg[8] from Quarterly to Latest run the following commands:
 # echo 'FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest" }' > /usr/local/etc/pkg/repos/FreeBSD.conf
 ....
 
-Then run this command to update the local package repositories catalogues for the Latest branch:
+Then run this command to update the local package repositories catalogues:
 
 [source,shell]
 ....
-# pkg update -f
+# pkg update
 ....
 
 [[pkg-configuration]]
@@ -675,13 +675,13 @@ By default, the Ports Collection itself is stored as a subdirectory of `/usr/por
 [WARNING]
 ====
 Before installing and using the Ports Collection, please be aware that it is generally ill-advised to use the Ports Collection in conjunction with the binary packages provided via pkg to install software.
-pkg, by default, tracks quarterly branch-releases of the ports tree and not HEAD.
-Dependencies could be different for a port in HEAD compared to its counterpart in a quarterly branch release and this could result in conflicts between dependencies installed by pkg and those from the Ports Collection.
-If the Ports Collection and pkg must be used in conjunction, then be sure that your Ports Collection and pkg are on the same branch release of the ports tree.
+In RELEASE versions of FreeBSD: man:pkg.conf[5] defaults to quarterly, not latest.
+Dependencies could be different for a port in latest, compared to its counterpart (if any) in quarterly, and this could result in conflicts between dependencies installed by pkg and those from the Ports Collection.
+If the Ports Collection and pkg must be used in conjunction, then be sure that your Ports Collection and pkg are on the same branch of the ports tree.
 ====
 
 The Ports Collection contains directories for software categories.
-Inside each category are subdirectories for individual applications.
+Within each category are subdirectories for individual applications.
 Each application subdirectory contains a set of files that tells FreeBSD how to compile and install that program, called a _ports skeleton_.
 Each port skeleton includes these files and directories:
 
@@ -727,14 +727,14 @@ If the ports tree is not available, or pkg is being used to manage packages, Git
 # pkg install git
 ....
 +
-. Check out a copy of the HEAD branch of the ports tree:
+. Check out the `main` branch of the ports repo:
 +
 [source,shell]
 ....
 # git clone https://git.FreeBSD.org/ports.git /usr/ports
 ....
 +
-. Or, check out a copy of a quarterly branch:
+. Or, check out a quarterly branch:
 +
 [source,shell]
 ....