committer handbook: Fix typos and reformat

Fix a few typos and reformat a few paragraphs to one line per sentence
style.  Try to use repository insteast of 'repo' or even 'source of
truth'. Clarify a few places and fix some grammar errors.

Submitted by: Pau Amma

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

@@ -1393,22 +1393,15 @@ How so do that is specific to the software being imported and is beyond the scop
 
 === FreeBSD Src Committer Transition Guide
 
-This section is designed to walk people through the conversion
+This section is designed to walk people through the conversion process from Subversion to Git, written from the source committer's point of view.
-process from Subversion to Git, written from the source committer's point
-of view.
 
 ==== Migrating from a Subversion tree
 
-This section will cover a couple of common scenarios for migrating
+This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source git repo.
-from using the FreeBSD Subversion repo to the FreeBSD source git repo. The
+The FreeBSD Git conversion is still in beta status, so some minor things may change between this and going into production.
-FreeBSD Git conversion is still in beta status, so some minor things
-may change between this and going into production.
-
-Before you git started, you'll need a copy of Git. Any Git will do,
-though the latest ones are always recommended. Either build it from
-ports, or install it using pkg (though some folks might use `su` or
-`doas` instead of `sudo`):
 
+The fist thing to do is install git. Any version of Git will do, though the latest one in ports / packages generally will be good.
+Either build it from ports, or install it using pkg (though some folks might use `su` or `doas` instead of `sudo`):
 
 [source,shell]
 ....
@@ -1417,87 +1410,79 @@ ports, or install it using pkg (though some folks might use `su` or
 
 ===== No staged changes migration
 
-If you have no changes pending, the migration is straight forward. In
+If you have no changes pending, the migration is straightforward.
-this, you abandon the Subversion tree and clone the Git repo. It's
+In this, you abandon the Subversion tree and clone the Git repoository.
-likely best to retain your subversion tree, in case there's something
+It's likely best to retain your subversion tree, in case there's something you've forgotten about there.
-you've forgotten about there.  First, let's clone a repo:
+First, let's clone the repository:
 [source,shell]
 ....
 % git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/src.git freebsd-src
 ....
-will create a clone of the FreeBSD src repo into a subdirectory called
+will create a clone of the FreeBSD src repository into a subdirectory called `freebsd-src` and include the 'notes' about the revisions.
-`freebsd-src` and include the 'notes' about the revisions.
+We are currently mirroring the source repository to https://github.com/freebsd/freebsd-src.git as well.
-The current plan for GitHub mirroring is to mirror to
+https://github.com/freebsd/freebsd-legacy.git has the old github mirror with the old hashes should you need that for your migration.
-https://github.com/freebsd/freebsd.git as well. When the transition
+The github `master` branch has been frozen.
-starts, the github `master` branch will be frozen. We will be using the name `main` instead
+As the default in git has change, we've shifted from `master` to `main`, the new repository uses `main`.
-of `master` that was used in the beta version of the github.com mirror.
+We also mirror the repository to gitlab at https://gitlab.com/FreeBSD/src.git .
-The exact logistics of this are still being finalized, as there are over 2k forks and 5k stars.
-We will also mirror the repo to gitlab at https://gitlab.com/FreeBSD/src.git .
-Its transition plan is also being finalized. 
 
-It's useful to have the old Subversion revisions available. This data is stored
+It's useful to have the old Subversion revisions available.
-using Git notes, but Git doesn't fetch those by default. The --config
+This data is stored using Git notes, but Git doesn't fetch those by default.
-and the argument above changed the default to fetch the notes. If
+The --config and the argument above changed the default to fetch the notes.
-you've cloned the repo without this, or wish to add notes to an
+If you've cloned the repository without this, or wish to add notes to a previously clone repository, use the following commands:
-previously clone repository, use the following commands:
 [source,shell]
 ....
 % git config --add remote.freebsd.fetch "+refs/notes/*:refs/notes/*"
 % git fetch
 ....
-At this point you have the src checked out into a Git tree, ready to
+At this point you have the src checked out into a Git tree, ready to do other things.
-do other things.
 
 ===== But I have changes that I've not committed
 
-If you are migrating from a tree that has changes you've not yet
+If you are migrating from a tree that has changes you've not yet committed to FreeBSD, you'll need to follow the steps from the previous section first, and then follow these.
-committed to FreeBSD, you'll need to follow the steps from the
-previous section first, and then follow these.
 [source,shell]
 ....
 % cd path-to-svn-checkout-tree
 % svn diff > /tmp/src.diff
-% cd mumble/freebsd-src
+% cd _mumble_/freebsd-src
 % git checkout -b working
 ....
-This will create a diff of your current changes. The last command
+This will create a diff of your current changes.
-creates a branch called `working` though you can call it whatever you
+The last command creates a branch called `working` though you can call it whatever you want.
-want.
 
 [source,shell]
 ....
 % git apply /tmp/src.diff
 ....
-this will apply all your pending changes to the working tree. This
+this will apply all your pending changes to the working tree.
-doesn't commit the change, so you'll need to make this permanent:
+This doesn't commit the change, so you'll need to make this permanent:
 
 [source,shell]
 ....
+% git add _files_
 % git commit
 ....
 
-The last command will commit these changes to the branch. The editor
+The last command will commit these changes to the branch.
-will prompt you for a commit message. Enter one as if you were
+The editor will prompt you for a commit message.
-committing to FreeBSD.
+Enter one as if you were committing to FreeBSD.
 
-At this point, your work is preserved, and in the Git repo.
+At this point, your work is preserved, and in the Git repository.
 
 ===== Keeping current
 
-So, time passes. It's time now to update the tree for the latest
+So, time passes.
-changes upstream. When you checkout `main` make sure that you have no
+It's time now to update the tree for the latest changes upstream.
-diffs. It's a lot easier to commit those to a branch (or use `git
+When you checkout `main` make sure that you have no diffs.
-stash`) before doing the following.
+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`, I would strongly recommend using the
+If you are used to `git pull`, we strongly recommend using the `--ff-only` option, and further setting it as the default option.
-`--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 directory.
 
 [source,shell]
 ....
 % git config --global pull.ff only
 ....
+You may need to omit the --global if you want this setting to only this repository.
 
 [source,shell]
 ....
@@ -1506,9 +1491,8 @@ in the main directory.
 % git pull (--ff-only|--rebase)
 ....
 
-There is a common trap, that the combination command `git pull` will
+There is a common trap, that the combination command `git pull` will try to perform a merge, which would sometimes creates a merge commit sha that didn't exist before.
-try to perform a merge, which would sometimes creates a merge commit
+This can be harder to recover from.
-sha that didn't exist before. This can be harder to recover from.
 
 The longer form is also recommended.
 
@@ -1551,19 +1535,16 @@ that they exactly match the passwd entry in FreeBSD cluster.  Use
 ....
 freefall% gen-gitconfig.sh
 ....
-on freefall.freebsd.org to get recipe that you can use directly, assuming
+on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH.
-/usr/local/bin is in the PATH.
 
 The below command merges the 'working' branch into the upstream main line.
-It's important that you curate your changes to be just
+It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this.
-like you want them in the FreeBSD source repo before doing this.
 [source,shell]
 ....
 % git push freebsd working:main
 ....
 
-If your push is rejected due to losing a commit race, rebase your branch
+If your push is rejected due to losing a commit race, rebase your branch before trying again:
-before trying again:
 [source,shell]
 ....
 % git checkout working
@@ -1593,13 +1574,12 @@ hash you can use to refer to this commit.
 
 ==== Migrating from GitHub fork
 
-Note: as of this writing, the https://github.com/freebsd/freebsd-src
+Note: as of this writing, https://github.com/freebsd/freebsd-src
 is mirroring all official branches, along with a `master` branch which
-is the leagcy svn2git result.  The `master` branch will not be updated anymore,
+is the legacy svn2git result.  The `master` branch will not be updated anymore,
 and the [last commit](https://github.com/freebsd/freebsd-src/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf)
-contains the instructions of migrating to new `main` branch.
+contains the instructions for migrating to the new `main` branch.
-We'll likely retain the `master` branch for a certain time, but in the future
+We'll retain the `master` branch for a certain time, but in the future it will only be kept in the
-it will only be kept in the
 [freebsd-legacy](https://github.com/freebsd/freebsd-legacy) repository.
 
 When migrating branches from a github fork from the old github mirror
@@ -1616,15 +1596,15 @@ This also assumes a clean tree before starting...
 ....
 
 ===== Rebase all your WIP branches.
-For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` reference with the above checkout:
+For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` branch with the above checkout:
 [source,shell]
 ....
 % git rebase -i freebsd/master FOO --onto main
 ....
-And you'll now be tracking the official source of truth.
+And you'll now be tracking the official repository.
 You can then follow the `Keeping Current` section above to stay up to date.
 
-If you need to then commit work to FreeBSD, you can do so following the  `Time to push changes upstream` instructions.
+If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions.
 You'll need to do the following once to update the push URL if you are a FreeBSD committer:
 [source,shell]
 ....