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.)
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
people to use that for their own development and to minimize "whoopse" pushes to source of truth.
[NOTE]
====
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 branch `fred` to point to the same point in the tree. 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. 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:
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.
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.
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
split, you'd omit it.
The last step is optional.
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
Here we see the changes I've made. You can use it to figure out where
things when wrong. I'll just point out a few things here. The first
one is that HEAD@{X} is a 'commitish' thing, so you can use that as an
argument to a command. Though if that command commits anything to the
repo, the X numbers change. You can also use the hash (first column)
as well.
Here we see the changes I've made.
You can use it to figure out where things went wrong.
I'll just point out a few things here.
The first one is that HEAD@{X} is a 'commitish' thing, so you can use that as an argument to a command.
Though if that command commits anything to the repository, the X numbers change.
You can also use the hash (first column) as well.
Next 'Encourage contributions' was the last commit I did to `wilma`
before I decided to split things up. You can also see the same hash is
there when I created the `fred` branch to do that. I started by
rebasing `fred` and you see the 'start', each step, and the 'finish'
for that process. While we don't need it here, you can figure out
exactly what happened. Fortunately, to fix this, you can follow the
prior answer's steps, but with the hash `869cbd3` instead of
`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:
Next 'Encourage contributions' was the last commit I did to `wilma` before I decided to split things up.
You can also see the same hash is there when I created the `fred` branch to do that.
I started by rebasing `fred` and you see the 'start', each step, and the 'finish' for that process.
While we don't need it here, you can figure out exactly what happened.
Fortunately, to fix this, you can follow the prior answer's steps, but with the hash `869cbd3` instead of `pre-split`.
While that seems 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
checking out and creating a branch for it. The -B instead of -b forces
the movement of a pre-existing branch. Either way works, which is what's
great (and awful) about Git. 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:
and you are ready to try again.
The 'checkout -B' with the hash combines checking out and creating a branch for it.
The -B instead of -b forces the movement of a pre-existing branch.
Either way works, which is what's great (and awful) about Git.
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:
[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
aren't an image I like to contemplate.
this produces the same effect, but I have to read a lot more and severed heads 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
that are automatically moved forward by making commits. So the above works
because you're just moving a label. There's no metadata about the branch
that needs to be preserved due to this.
There's nothing magical about branches in git: they are just labels on a graph that are automatically moved forward by making commits.
So the above works because you're just moving a label.
There's no metadata about the branch 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
from both branches. You can further curate it with `git rebase`.
You now have a new branch called `feature`.
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
to break it up into `kernel` and `userland` so I can evolve them separately and commit
each branch as it becomes ready.
**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.
**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':
Warner Losh
3 years ago