Lots of improvements.
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).
This commit is contained in:
Warner Losh
parent
78a21ab121
commit
9fc1c18c75
1 changed files with 53 additions and 63 deletions
|
|
@ -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
|
||||
|
|
@ -1794,33 +1793,30 @@ a6a5094 (fred) HEAD@{4}: rebase -i (pick): Encourage contributions
|
|||
%
|
||||
....
|
||||
|
||||
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':
|
||||
[source,shell]
|
||||
....
|
||||
% git clone --mirror https://cgit-beta.freebsd.org/ports.git ports.git
|
||||
% git clone --mirror https://cgit.freebsd.org/ports.git ports.git
|
||||
% cd ports.git
|
||||
% git worktree add ../ports main
|
||||
% git worktree add ../quarterly branches/2020Q4
|
||||
|
|
@ -2000,12 +1993,12 @@ But if you aren't using your mirror for further local clones, then it's a poor m
|
|||
The second disadvantage is that Git normally rewrites the refs (branch name, tags, etc)
|
||||
from upstream so that your local refs can evolve independently of
|
||||
upstream. This means that you'll lose changes if you are committing to
|
||||
this repo on anything other than private project branches.
|
||||
this repository on anything other than private project branches.
|
||||
|
||||
**Q:** So what can I do instead?
|
||||
|
||||
**A:** Well, you can stuff all of the upstream repo's refs into a private
|
||||
namespace in your local repo. Git clones everything via a 'refspec' and
|
||||
**A:** Well, you can stuff all of the upstream repository's refs into a private
|
||||
namespace in your local repository. Git clones everything via a 'refspec' and
|
||||
the default refspec is:
|
||||
[source,shell]
|
||||
....
|
||||
|
|
@ -2013,20 +2006,17 @@ the default refspec is:
|
|||
....
|
||||
which says just fetch the branch refs.
|
||||
|
||||
However, the FreeBSD repo has a number of other things in it. To see
|
||||
However, the FreeBSD repository has a number of other things in it. To see
|
||||
those, you can add explicit refspecs for each ref namespace, or you
|
||||
can fetch everything. To setup your repo to do that:
|
||||
can fetch everything. To setup your repository to do that:
|
||||
[source,shell]
|
||||
....
|
||||
git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'
|
||||
....
|
||||
which will put everything in the upstream repo into your local repo's
|
||||
'res/freebsd/' namespace. Please note, that this
|
||||
also grabs all the unconverted vendor branches and the number of refs
|
||||
associated with them is quite large.
|
||||
which will put everything in the upstream repository into your local repository's 'ref/freebsd/' namespace.
|
||||
Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large.
|
||||
|
||||
You'll need to refer to these 'refs' with their full name because they
|
||||
aren't in and of Git's regular namespaces.
|
||||
You'll need to refer to these 'refs' with their full name because they aren't in and of Git's regular namespaces.
|
||||
[source,shell]
|
||||
....
|
||||
git log refs/freebsd/vendor/zlib/1.2.10
|
||||
|
|
|
|||
Loading…
Reference in a new issue