@ -263,8 +263,8 @@ This primer is less ambitiously scoped than the old Subversion Primer, but shoul
==== Scope
If you want to download FreeBSD, compile it from sources and generally keep up to date that way, this primer is for you.
It covers getting the sources, updating the sources, how to bisect and touches briefly on how to cope with a few local changes.
If you want to download FreeBSD, compile it from sources, and generally keep up to date that way, this primer is for you.
It covers getting the sources, updating the sources, bisecting and touches briefly on how to cope with a few local changes.
It covers the basics, and tries to give good pointers to more in-depth treatment for when the readers finds the basics insufficient.
Other sections of this guide cover more advanced topics related to contributing to the project.
@ -272,24 +272,24 @@ The goal of this section is to highlight those bits of git needed to track sourc
They assume a basic understanding of git.
There are many primers for git on the web, but the https://git-scm.com/book/en/v2[Git Book] provides one of the better treatments.
==== Keeping Current With FreeBSD src tree
==== Keeping Current With The FreeBSD src Tree
First step: cloning a tree.
This downloads the entire tree.
There are two ways to download.
Most people will want to do a deep clone of the repo.
However, there are times that you may wish to do a shallow clone.
Most people will want to do a deep clone of the repository.
However, there are times when you may wish to do a shallow clone.
===== Branch names
The branch names in the new git repo are similar to the old names.
The branch names in the new git repository are similar to the old names.
For the stable branches, they are stable/X where X is the major release (like 11 or 12).
The main branch in the new repo is 'main'.
The main branch in the new repository is 'main'.
The main branch in the old GitHub mirror was 'master', but is now 'main'.
Both reflect the defaults of git at the time they were created.
The 'main' branch is the default branch if you omit the '-b branch' or '--branch branch' options below.
===== Repositories
Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD soruces.
$URL below can be obstained from that page.
Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD sources.
$URL below can be obtained from that page.
Note: The project doesn't use submodules as they are a poor fit for our workflows and development model.
How we track changes in third-party applications is discussed elsewhere and generally of little concern to the casual user.
@ -328,8 +328,11 @@ This clones the repository, but only has the most recent version in the reposito
The rest of the history is not downloaded.
Should you change your mind later, you can do 'git fetch --unshallow' to get the old history.
WARNING: When you make a shallow clone, you will lose the commit count in your uname output.
[WARNING]
====
When you make a shallow clone, you will lose the commit count in your uname output.
This can make it more difficult to determine if your system needs to be updated when a security advisory is issued.
====
===== Building
@ -358,7 +361,7 @@ This pulls in all the revisions since your last update.
....
will update the tree.
In git, a 'fast forward' merge is one that only needs to set a new branch pointer and doesn't need to re-create the commits.
By always doing a 'fast forward' merge/pull, you'll ensure that you have an identical copy of the FreeBSD tree.
By always doing a 'fast forward' merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree.
This will be important if you want to maintain local patches.
See below for how to manage local changes.
@ -380,7 +383,7 @@ You will be greeted with a message similar to the following:
....
Note: checking out '08b8197a742a96964d2924391bf9fdfeb788865d'.
You are in 'detached HEAD' state. You can look around, make experimental
You are in a 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
@ -398,13 +401,10 @@ Git itself is inconsistent about how many digits it displays.
==== Bisecting
Sometimes, things go wrong.
The last version worked, but the one you just updated to does not.
A developer may ask to bisect the problem to track down which commit caused the regression.
If you have read the last section, you may be thinking to yourself "How the heck do I bisect with crazy version numbers like that?" then this section is for you.
It is also for you if you did not think that, but also want to bisect.
A developer may ask you to bisect the problem to track down which commit caused the regression.
Fortunately, one uses the 'git bisect' command.
Here's a brief outline in how to use it.
Git makes bisecting changes easy with a powerful 'git bisect' command.
Here's a brief outline of how to use it.
For more information, you can view https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details.
The man git-bisect page is good at describing what can go wrong, what to do when versions won't build, when you want to use terms other than 'good' and 'bad', etc, none of which will be covered here.
@ -414,7 +414,9 @@ Next, you need to tell a range to go through.
The bad version will almost always be HEAD (a special tag for what you have checked out).
The good version will be the last one you checked out.
A quick aside: if you want to know the last version you checked out, you should use 'git reflog':
[TIP]
====
If you want to know the last version you checked out, you should use 'git reflog':
shows me moving the working tree to the master branch (a816...) and then updating from upstream (to 5ef0...).
In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165.
As you can see from the output, HEAD@{1} also often works, but isn't foolproof if you have done other things to your git tree after updating, but before you discover the need to bisect.
====
Back to git bisect.
Set the 'good' version first, then set the bad (though the order doesn't matter).
When you set the bad version, it will give you some statistics on the process:
[source,shell]
@ -446,14 +448,15 @@ When you are done, report the bad version to the developer (or fix the bug yours
Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.
==== Ports Considerations
The ports migration is in progress, and some of this section may change before that is complete.
The ports tree operates the same way.
The branch names are different and the repos are in different locations.
The branch names are different and the repositories are in different locations.
The legacy GitHub mirror is at https://github.com/freebsd/freebsd-ports.git .
The canonical cgit mirror is https://cgit-beta.freebsd.org/ports.git .
The production git repo will be https://git.freebsd.org/ports.git and ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git) when the time comes.
As with ports, the 'current' branches are 'master' (legacy) and 'main' (new) respectively.
The 'current' branches are 'master' (legacy) and 'main' (new) respectively.
The quarterly branches are named the same as in FreeBSD's svn repo.
[NOTE]
@ -462,7 +465,7 @@ The cgit repo for ports is considered beta.
The git hashes may change as problems are found in the conversion prior to the cutover.
====
==== Coping with Local Changes
==== Managing Local Changes
This section addresses tracking local changes.
If you have no local changes, you can stop reading now (it is the last section and OK to skip).
@ -498,7 +501,7 @@ We will cover the most common scenarios that arise using it.
====== Create a branch
Let's say you want to make a hack to FreeBSD's ls command to never, ever do color.
Let's say you want to make a change to FreeBSD's ls command to never, ever do color.
There are many reasons to do this, but this example will use that as a baseline.
The FreeBSD ls command changes from time to time, and you'll need to cope with those changes.
Fortunately, with git rebase it usually is automatic.
@ -529,7 +532,7 @@ index 7378268867ef..cfc3f4342531 100644
The commit will pop you into an editor to describe what you've done.
Once you enter that, you have your own **local** branch in the git repo.
Build and install it like you normally would, following the directions in the handbook.
git differs from other version control systems in that you have to tell it explicitly which files to use.
git differs from other version control systems in that you have to tell it explicitly which files to commit.
I have opted to do it on the commit command line, but you can also do it with 'git add' which many of the more in depth tutorials cover.
====== Time to update
@ -554,8 +557,8 @@ Once you are done with the above, you have to move the commits to ls.c forward f
Sometimes there are merge conflicts.
That is OK.
Do not panic.
You wouldhandle them the same as you would any other merge conflicts.
To keep it simple, I will just describe a common issue you might see.
Instead, handle them the same as any other merge conflicts.
To keep it simple, I will just describe a common issue that may arise.
A pointer to a more complete treatment can be found at the end of this section.
Let's say the includes changes upstream in a radical shift to terminfo as well as a name change for the option.
@ -622,7 +625,7 @@ If you have a deep clone, the following will suffice:
....
If you have a local branch, though, there are one or two caveats.
First, rebase will rewrite history, so you will likely want to do something to save it.
Second, jumping branches tends to encounter more conflicts.
Second, jumping branches tends to cause more conflicts.
If we pretend the example above was relative to stable/12, then to move to main, I'd suggest the following:
[source,shell]
....
@ -640,20 +643,20 @@ replay them onto the main branch creating a new no-color-ls branch there (which
===== Migrating from an existing git clone
If you have work based on a previous git conversion or a locally running git-svn conversion, migrating to new repository can encounter problems because git has no knowledge about the connection between the two.
If do not have a lot of local changes, the easiest way would be to cherry-pick your changes to the new base:
When you have only a few local changes, the easiest way would be to cherry-pick those changes to the new base:
[source,shell]
....
% git checkout main
% git cherry-pick old_branch..your_branch
....
Or alternatively, you can do the same thing with rebase:
Or alternatively, do the same thing with rebase:
[source,shell]
....
% git rebase --onto main master your_branch
....
If you do have a lot of changes, you would probably want to perform a merge instead.
The idea is to create a merge point that consolidates the history of the old_branch, and the new source of truth (main).
The idea is to create a merge point that consolidates the history of the old_branch, and the new FreeBSD repository (main).
You can find out by looking up the same commit that are found on both parents:
[source,shell]
@ -665,10 +668,10 @@ You will see a commit message, now search for that in the new branch:
....
% git log --grep="commit message on old_branch" freebsd/main
....
You would get a SHA1 on the new main branch, create a helper branch (in the example we call it 'stage') from that SHA1:
You would help locat the commit hash on the new main branch, create a helper branch (in the example we call it 'stage') from that hash:
[source,shell]
....
% git checkout -b stage SHA1_found_from_git_log
% git checkout -b stage _hash_found_from_git_log_
....
Then perform a merge of the old branch:
[source,shell]
@ -1491,7 +1494,7 @@ You may need to omit the --global if you want this setting to only this reposito
% 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.
There is a common trap, that the combination command `git pull` will try to perform a merge, which would sometimes creates a merge commit that didn't exist before.
Warner Losh
3 years ago