git: d5ea2ebac2 - main - committer handbook: Fix typos and reformat
Warner Losh
imp at FreeBSD.org
Wed Mar 17 22:53:39 UTC 2021
The branch main has been updated by imp:
URL: https://cgit.FreeBSD.org/doc/commit/?id=d5ea2ebac2092499c91b262679d62778e7bfd147
commit d5ea2ebac2092499c91b262679d62778e7bfd147
Author: Warner Losh <imp at FreeBSD.org>
AuthorDate: 2021-03-17 22:51:12 +0000
Commit: Warner Losh <imp at FreeBSD.org>
CommitDate: 2021-03-17 22:53:22 +0000
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
---
.../en/articles/committers-guide/_index.adoc | 120 +++++++++------------
1 file changed, 50 insertions(+), 70 deletions(-)
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index b25a555367..d0b66e1a52 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/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
-process from Subversion to Git, written from the source committer's point
-of view.
+This section is designed to walk people through the conversion 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
-from using the FreeBSD Subversion repo to the FreeBSD source git repo. The
-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`):
+This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source git repo.
+The FreeBSD Git conversion is still in beta status, so some minor things may change between this and going into production.
+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
-this, you abandon the Subversion tree and clone the Git repo. It's
-likely best to retain your subversion tree, in case there's something
-you've forgotten about there. First, let's clone a repo:
+If you have no changes pending, the migration is straightforward.
+In this, you abandon the Subversion tree and clone the Git repoository.
+It's likely best to retain your subversion tree, in case there's something you've forgotten about there.
+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
-`freebsd-src` and include the 'notes' about the revisions.
-The current plan for GitHub mirroring is to mirror to
-https://github.com/freebsd/freebsd.git as well. When the transition
-starts, the github `master` branch will be frozen. We will be using the name `main` instead
-of `master` that was used in the beta version of the github.com mirror.
-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.
+will create a clone of the FreeBSD src repository into a subdirectory called `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.
+https://github.com/freebsd/freebsd-legacy.git has the old github mirror with the old hashes should you need that for your migration.
+The github `master` branch has been frozen.
+As the default in git has change, we've shifted from `master` to `main`, the new repository uses `main`.
+We also mirror the repository to gitlab at https://gitlab.com/FreeBSD/src.git .
-It's useful to have the old Subversion revisions available. This data is stored
-using Git notes, but Git doesn't fetch those by default. The --config
-and the argument above changed the default to fetch the notes. If
-you've cloned the repo without this, or wish to add notes to an
-previously clone repository, use the following commands:
+It's useful to have the old Subversion revisions available.
+This data is stored using Git notes, but Git doesn't fetch those by default.
+The --config and the argument above changed the default to fetch the notes.
+If you've cloned the repository without this, or wish to add notes to a 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
-do other things.
+At this point you have the src checked out into a Git tree, ready to 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
-committed to FreeBSD, you'll need to follow the steps from the
-previous section first, and then follow these.
+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.
[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
-creates a branch called `working` though you can call it whatever you
-want.
+This will create a diff of your current changes.
+The last command creates a branch called `working` though you can call it whatever you want.
[source,shell]
....
% git apply /tmp/src.diff
....
-this will apply all your pending changes to the working tree. This
-doesn't commit the change, so you'll need to make this permanent:
+this will apply all your pending changes to the working tree.
+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
-will prompt you for a commit message. Enter one as if you were
-committing to FreeBSD.
+The last command will commit these changes to the branch.
+The editor will prompt you for a commit message.
+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
-changes upstream. 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.
+So, time passes.
+It's time now to update the tree for the latest changes upstream.
+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`, I would 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 directory.
+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.
[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
-try to perform a merge, which would sometimes creates a merge commit
-sha that didn't exist before. This can be harder to recover from.
+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.
+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
-/usr/local/bin is in the PATH.
+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.
-It's important that you curate your changes to be just
-like you want them in the FreeBSD source repo before doing this.
+It's important that you curate your changes to be just 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
-before trying again:
+If your push is rejected due to losing a commit race, rebase your branch 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.
-We'll likely retain the `master` branch for a certain time, but in the future
-it will only be kept in the
+contains the instructions for migrating to the new `main` branch.
+We'll retain the `master` branch for a certain time, but in the future 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]
....
More information about the dev-commits-doc-all
mailing list