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).
@ -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.)
(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
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
push location so that you only push things into FreeBSD you intend to
by making it explicit.
by making it explicit.
[[git-faq]]
[[git-faq]]
=== 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
==== 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
**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
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,
**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
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
change in your tree, forcing a complicated merge rather than a simple
one.
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
==== 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
'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
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,
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
be simpler: just `git rebase -i`. Git will notice you've done
this and skip the common changes automatically (even if you had to
this and skip the common changes automatically (even if you had to
change the commit message or tweak the commit slightly). There's no
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
and there are no conflicts, you're done. If not, you'll need to
resolve the conflicts as you go.
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]
[source,shell]
....
....
% git checkout pre-split # Go back
% 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 checkout -B wilma # reset the wilma branch
% git branch -d pre-split # Pretend it didn't happen
% 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
**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
the end to create a branch, and now `fred` and `wilma` are all
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]
[source,shell]
....
....
% git checkout -B wilma 869cbd3
% git checkout -B wilma 869cbd3
% git branch -D fred
% 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]
[source,shell]
....
....
% git checkout 869cbd3
% 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
HEAD is now at 869cbd3 Encourage contributions
% git checkout -B wilma
% 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?
===== 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
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
===== Mixing and matching branches
@ -1891,12 +1885,11 @@ while maintaining the commits in both.
% git checkout -b feature # create a new branch
% git checkout -b feature # create a new branch
% git cherry-pick main..async # bring in the changes
% 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
**A:** This takes a little bit of prep work, but `git rebase` will do the heavy
lifting here.
lifting here.
@ -1974,7 +1967,7 @@ and use the `git rebase -i` to fold the related commits together).
==== Cloning and Mirroring
==== 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
**A:** If all you want to do is mirror, then
[source,shell]
[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
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.
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
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':
day work. There's a number of ways around this with 'git worktree':
Warner Losh
3 years ago