Lots of improvements.

Lots of wording improvements, grammar errors, punctuation error and wrong word
fixes.  Also, do some limited one sentence one line (1s1l) conversion.

Submitted by: Pau Amma (though not the 1s1l stuff).

documentation/content/en/articles/committers-guide/_index.adoc

@@ -1620,25 +1620,28 @@ You'll need to do the following once to update the push URL if you are a FreeBSD
 (note that gitrepo.freebsd.org will be change to repo.freebsd.org in the future.)
 
 You will also need to add `freebsd` as the location to push to. The
-author recommends that your upstream github repo remain the default
+author recommends that your upstream github repository remain the default
 push location so that you only push things into FreeBSD you intend to
 by making it explicit.
 
 [[git-faq]]
 === Git FAQ
 
-This section  provides a number of targeted answers to questions that are likely to come up often for users, developer and integrators.
+This section  provides a number of targeted answers to questions that are likely to come up often for users and developers.
 
-Note, we use the common convention of having the origin for the FreeBSD repo being 'freebsd' rather than the default 'origin' to allow
+[NOTE]
-people to use that for their own development and to minimize "whoopse" pushes to source of truth.
+====
+We use the common convention of having the origin for the FreeBSD repository being 'freebsd' rather than the default 'origin' to allow
+people to use that for their own development and to minimize "whoopse" pushes to the wrong repository.
+====
 
 ==== Users
 
-===== How do I track -current and -stable with only one copy of the repo?
+===== How do I track -current and -stable with only one copy of the repository?
 
 **Q:** Although disk space is not a huge issue, it's more efficient to use
 only one copy of the repository. With SVN mirroring, I could checkout
-multiple trees from the same repo. How do I do this with Git?
+multiple trees from the same repository. How do I do this with Git?
 
 **A:** You can use Git worktrees. There's a number of ways to do this,
 but the simplest way is to use a clone to track -current, and a
@@ -1677,7 +1680,7 @@ accidentally getting into a 'merge nightmare' where you have an extra
 change in your tree, forcing a complicated merge rather than a simple
 one.
 
-Here's https://adventurist.me/posts/00296 a good writeup that goes into more detail.
+Here's https://adventurist.me/posts/00296[a good writeup] that goes into more detail.
 
 ==== Developers
 
@@ -1732,7 +1735,7 @@ keep the rest in `wilma` for some reason?
 '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 repo. Once you've done that, cleanup couldn't
+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
@@ -1749,13 +1752,9 @@ correspond to the commits you copied to `fred`. If all goes well,
 and there are no conflicts, you're done. If not, you'll need to
 resolve the conflicts as you go.
 
-The other way to do this would be to checkout `wilma` and then create
+The other way to do this would be to checkout `wilma` and then create the branch `fred` to point to the same point in the tree.
-the branch `fred` to point to the same point in the tree. You can then
+You can then `git rebase -i` both these branches, selecting the changes you want in `fred` or `wilma` by retaining the pick likes, and deleting the rest from the editor.
-`git rebase -i` both these branches, selecting the changes you want in
+Some people would create a tag/branch called `pre-split` before starting in case something goes wrong in the split, you can undo it with the following sequence:
-`fred` or `wilma` by retaining the pick likes, and deleting the rest
-from the editor. Some people would create a tag/branch called
-`pre-split` before starting in case something goes wrong in the split,
-you can undo it with the following sequence:
 [source,shell]
 ....
 % git checkout pre-split	# Go back
@@ -1763,8 +1762,8 @@ you can undo it with the following sequence:
 % git checkout -B wilma		# reset the wilma branch
 % git branch -d pre-split	# Pretend it didn't happen
 ....
-the last step is optional. If you are going to try again to
+The last step is optional.
-split, you'd omit it.
+If you are going to try again to split, you'd omit it.
 
 **Q:** But I did things as I read along and didn't see your advice at
 the end to create a branch, and now `fred` and `wilma` are all
@@ -1794,33 +1793,30 @@ a6a5094 (fred) HEAD@{4}: rebase -i (pick): Encourage contributions
 %
 ....
 
-Here we see the changes I've made. You can use it to figure out where
+Here we see the changes I've made.
-things when wrong. I'll just point out a few things here. The first
+You can use it to figure out where things went wrong.
-one is that HEAD@{X} is a 'commitish' thing, so you can use that as an
+I'll just point out a few things here.
-argument to a command. Though if that command commits anything to the
+The first one is that HEAD@{X} is a 'commitish' thing, so you can use that as an argument to a command.
-repo, the X numbers change. You can also use the hash (first column)
+Though if that command commits anything to the repository, the X numbers change.
-as well.
+You can also use the hash (first column) as well.
 
-Next 'Encourage contributions' was the last commit I did to `wilma`
+Next 'Encourage contributions' was the last commit I did to `wilma` before I decided to split things up.
-before I decided to split things up. You can also see the same hash is
+You can also see the same hash is there when I created the `fred` branch to do that.
-there when I created the `fred` branch to do that. I started by
+I started by rebasing `fred` and you see the 'start', each step, and the 'finish' for that process.
-rebasing `fred` and you see the 'start', each step, and the 'finish'
+While we don't need it here, you can figure out exactly what happened.
-for that process. While we don't need it here, you can figure out
+Fortunately, to fix this, you can follow the prior answer's steps, but with the hash `869cbd3` instead of `pre-split`.
-exactly what happened.  Fortunately, to fix this, you can follow the
+While that seems a bit verbose, it's easy to remember since you're doing one thing at a time.
-prior answer's steps, but with the hash `869cbd3` instead of
+You can also stack:
-`pre-split`. While that set of a bit verbose, it's easy to remember
-since you're doing one thing at a time. You can also stack:
 [source,shell]
 ....
 % git checkout -B wilma 869cbd3
 % git branch -D fred
 ....
-and you are ready to try again. The 'checkout -B' with the hash combines
+and you are ready to try again.
-checking out and creating a branch for it. The -B instead of -b forces
+The 'checkout -B' with the hash combines checking out and creating a branch for it.
-the movement of a pre-existing branch. Either way works, which is what's
+The -B instead of -b forces the movement of a pre-existing branch.
-great (and awful) about Git. One reason I tend to use `git checkout -B xxxx hash`
+Either way works, which is what's great (and awful) about Git.
-instead of checking out the hash, and then creating / moving the branch
+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:
-is purely to avoid the slightly distressing message about detached heads:
 [source,shell]
 ....
 % git checkout 869cbd3
@@ -1839,8 +1835,7 @@ do so (now or later) by using -b with the checkout command again. Example:
 HEAD is now at 869cbd3 Encourage contributions
 % git checkout -B wilma
 ....
-this produces the same effect, but I have to read a lot more and severed heads
+this produces the same effect, but I have to read a lot more and severed heads aren't an image I like to contemplate.
-aren't an image I like to contemplate.
 
 ===== Ooops! I did a 'git pull' and it created a merge commit, what do I do?
 
@@ -1873,10 +1868,9 @@ namespace.  To fix your 'main' branch, just make it point to the remote's
 ....
 git branch -f main freebsd/main
 ....
-There's nothing magical about branches in git: they are just labels on a DAG
+There's nothing magical about branches in git: they are just labels on a graph that are automatically moved forward by making commits.
-that are automatically moved forward by making commits.  So the above works
+So the above works because you're just moving a label.
-because you're just moving a label. There's no metadata about the branch
+There's no metadata about the branch that needs to be preserved due to this.
-that needs to be preserved due to this.
 
 ===== Mixing and matching branches
 
@@ -1891,12 +1885,11 @@ while maintaining the commits in both.
 % git checkout -b feature	# create a new branch
 % git cherry-pick main..async	# bring in the changes
 ....
-You now have one branch called `feature`. This branch combines commits
+You now have a new branch called `feature`.
-from both branches. You can further curate it with `git rebase`.
+This branch combines commits from both branches.
+You can further curate it with `git rebase`.
 
-**Q:** OK Wise Guy. That was too easy. I have a branch called `driver` and I'd like
+**Q:** I have a branch called `driver` and I'd like to break it up into `kernel` and `userland` so I can evolve them separately and commit each branch as it becomes ready.
-to break it up into `kernel` and `userland` so I can evolve them separately and commit
-each branch as it becomes ready.
 
 **A:** This takes a little bit of prep work, but `git rebase` will do the heavy
 lifting here.
@@ -1974,7 +1967,7 @@ and use the `git rebase -i` to fold the related commits together).
 
 ==== Cloning and Mirroring
 
-**Q:** I'd like to mirror the entire git repo, how do I do that?
+**Q:** I'd like to mirror the entire git repository, how do I do that?
 
 **A:** If all you want to do is mirror, then
 [source,shell]
@@ -1984,12 +1977,12 @@ and use the `git rebase -i` to fold the related commits together).
 will do the trick. However, there are two disadvantages to this if you
 want to use it for anything other than a mirror you'll reclone.
 
-First, this is a 'bare repo' which has the repository database, but no
+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':
 [source,shell]
 ....
-% git clone --mirror https://cgit-beta.freebsd.org/ports.git ports.git
+% git clone --mirror https://cgit.freebsd.org/ports.git ports.git
 % cd ports.git
 % git worktree add ../ports main
 % git worktree add ../quarterly branches/2020Q4
@@ -2000,12 +1993,12 @@ But if you aren't using your mirror for further local clones, then it's a poor m
 The second disadvantage is that Git normally rewrites the refs (branch name, tags, etc)
 from upstream so that your local refs can evolve independently of
 upstream. This means that you'll lose changes if you are committing to
-this repo on anything other than private project branches.
+this repository on anything other than private project branches.
 
 **Q:** So what can I do instead?
 
-**A:** Well, you can stuff all of the upstream repo's refs into a private
+**A:** Well, you can stuff all of the upstream repository's refs into a private
-namespace in your local repo. Git clones everything via a 'refspec' and
+namespace in your local repository. Git clones everything via a 'refspec' and
 the default refspec is:
 [source,shell]
 ....
@@ -2013,20 +2006,17 @@ the default refspec is:
 ....
 which says just fetch the branch refs.
 
-However, the FreeBSD repo has a number of other things in it. To see
+However, the FreeBSD repository has a number of other things in it. To see
 those, you can add explicit refspecs for each ref namespace, or you
-can fetch everything. To setup your repo to do that:
+can fetch everything. To setup your repository to do that:
 [source,shell]
 ....
 git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'
 ....
-which will put everything in the upstream repo into your local repo's
+which will put everything in the upstream repository into your local repository's 'ref/freebsd/' namespace.
-'res/freebsd/' namespace. Please note, that this
+Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large.
-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
+You'll need to refer to these 'refs' with their full name because they aren't in and of Git's regular namespaces.
-aren't in and of Git's regular namespaces.
 [source,shell]
 ....
 git log refs/freebsd/vendor/zlib/1.2.10