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
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
===== 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]
[source,shell]
....
....
% cd path-to-svn-checkout-tree
% cd path-to-svn-checkout-tree
% svn diff > /tmp/src.diff
% svn diff > /tmp/src.diff
% cd mumble/freebsd-src
% cd _mumble_/freebsd-src
% git checkout -b working
% 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]
[source,shell]
....
....
% git apply /tmp/src.diff
% 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]
[source,shell]
....
....
% git add _files_
% git commit
% 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
===== 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]
[source,shell]
....
....
% git config --global pull.ff only
% git config --global pull.ff only
....
....
You may need to omit the --global if you want this setting to only this repository.
[source,shell]
[source,shell]
....
....
@ -1506,9 +1491,8 @@ in the main directory.
% git pull (--ff-only|--rebase)
% 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.
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
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.
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]
[source,shell]
....
....
% git push freebsd working:main
% 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]
[source,shell]
....
....
% git checkout working
% git checkout working
@ -1593,13 +1574,12 @@ hash you can use to refer to this commit.
==== Migrating from GitHub fork
==== 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 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)
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