git: 6b6cb62f7d - main - handbook: update mirrors to include git
Warner Losh
imp at FreeBSD.org
Sun Mar 14 23:48:05 UTC 2021
The branch main has been updated by imp:
URL: https://cgit.FreeBSD.org/doc/commit/?id=6b6cb62f7d918f84befd37e3c493de565a24cb65
commit 6b6cb62f7d918f84befd37e3c493de565a24cb65
Author: Warner Losh <imp at FreeBSD.org>
AuthorDate: 2021-03-14 23:47:37 +0000
Commit: Warner Losh <imp at FreeBSD.org>
CommitDate: 2021-03-14 23:47:37 +0000
handbook: update mirrors to include git
Pull most of URLs.md from my freebsd-git-docs github repo and reformat to
asciidoc. Copy some of the existing svn info and retarget it to Git.
Submissions on github from: lwshu@, 0mp@, Alexander Richardson, Ryan Libby,
Ceri Davies, Joseph Mingrone
Feedback from: Pau Amma, emaste@
Sponsored by: Netflix, Inc
Differential Revision: https://reviews.freebsd.org/D29252
---
.../content/en/books/handbook/mirrors/_index.adoc | 327 ++++++++++++++++++++-
1 file changed, 324 insertions(+), 3 deletions(-)
diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc
index f50f683c8f..54197edbca 100644
--- a/documentation/content/en/books/handbook/mirrors/_index.adoc
+++ b/documentation/content/en/books/handbook/mirrors/_index.adoc
@@ -386,17 +386,336 @@ In case of problems, please contact the hostmaster `<{mirrors-us-email}>` for th
* {mirrors-us-ftp14} (ftp / {mirrors-us-ftp14-http})
* {mirrors-us-ftp15} (ftp)
+[[git]]
+== Using Git
+
+[[git-intro]]
+=== Introduction
+
+As of December 2020, FreeBSD uses git as the primary version control system for storing all of FreeBSD's base source code and documentation.
+
+[NOTE]
+====
+Git is generally a developer tool.
+Users may prefer to use `freebsd-update` (crossref:cutting-edge[updating-upgrading-freebsdupdate,“FreeBSD Update”]) to update the FreeBSD base system, and `portsnap` (crossref:ports[ports-using,“Using the Ports Collection”]) to update the FreeBSD Ports Collection.
+In April 2021, the ports tree will migrate to git.
+====
+
+This section demonstrates how to install Git on a FreeBSD system and use it to create a local copy of a FreeBSD repository.
+Additional information on the use of Git is included.
+
+[[git-ssl-certificates]]
+=== Root SSL Certificates
+
+Older FreeBSD systems do not have proper root certificates.
+Installing package:security/ca_root_nss[] on these systems allows Git to verify the identity of HTTPS repository servers.
+The root SSL certificates can be installed from a port:
+
+[source,shell]
+....
+# cd /usr/ports/security/ca_root_nss
+# make install clean
+....
+
+or as a package:
+
+[source,shell]
+....
+# pkg install ca_root_nss
+....
+
+[[git-install]]
+=== Installation
+
+Git can be installed from the Ports Collection:
+
+[source,shell]
+....
+# cd /usr/ports/devel/git
+# make install clean
+....
+
+Git can also be installed as a package:
+
+[source,shell]
+....
+# pkg install git
+....
+
+[[git-usage]]
+=== Running Git
+
+To fetch a clean copy of the sources into a local directory, use `git`.
+This directory of files is called the _working tree_.
+
+[WARNING]
+====
+
+Move or delete an existing destination directory before using `git clone` for the first time.
+Cloning over an existing non-git directory will fail.
+====
+
+Git uses URLs to designate a repository, taking the form of _protocol://hostname/path_.
+The first component of the path is the FreeBSD repository to access.
+There are two different repositories, `src` for the FreeBSD systerm source code, and `doc` for documentation.
+In the future a third repository, 'ports' will be available for the FreeBSD ports code.
+For example, the URL `https://git.FreeBSD.org/src.git` specifies the main branch of the src repository, using the `https` protocol.
+
+.Handy URL Table
+[options="header,foooter"]
+|=======================================================
+|Item | Git URL
+| Web-based repository browser src | `https://cgit.freebsd.org/src`
+| Read-only src repo via HTTPS | `https://git.freebsd.org/src.git`
+| Read-only src repo via anon-ssh | `ssh://anongit@git.freebsd.org/src.git`
+| Read/write src repo for committers | `ssh://git@gitrepo.freebsd.org/src.git` (*)
+| Web-based repository browser doc | `https://cgit.freebsd.org/doc`
+| Read-only doc repo via HTTPS | `https://git.freebsd.org/doc.git`
+| Read-only doc repo via anon-ssh | `ssh://anongit@git.freebsd.org/doc.git`
+| Read/write doc repo for committers | `ssh://git@gitrepo.freebsd.org/doc.git` (*)
+|=======================================================
+ - (*) `git` is a special user on the repository server which will map your registered ssh key in FreeBSD.org to your identity, no need to change it.
+
+[WARNING]
+====
+
+Sometime after the switch to git is complete, `gitrepo.freebsd.org` will change to simply `repo.freebsd.org`.
+====
+
+
+To get started, clone a copy of the FreeBSD repository:
+
+[source,shell]
+....
+# git clone [ -b branch ] https://git.FreeBSD.org/repo.git wcdir
+....
+
+where:
+
+* _repo_ is one of the Project repositories: `src`, `ports`, or `doc`.
+* _branch_ depends on the repository used.
+`ports` and `doc` are mostly updated in the `main` branch, while `src` maintains the latest version of -CURRENT under `main` and the respective latest versions of the -STABLE branches under `stable/12` (12._x_) and `stable/13` (13._x_).
+* _wcdir_ is the target directory where the contents of the specified branch should be placed.
+This is usually [.filename]#/usr/ports# for `ports`, [.filename]#/usr/src# for `src`, and [.filename]#/usr/doc# for `doc`.
+
+This example checks out the `main` branch of the system sources from the FreeBSD repository using the HTTPS protocol, placing the local working copy in [.filename]#/usr/src#.
+If [.filename]#/usr/src# is already present but was not created by `git`, remember to rename or delete it before the checkout.
+Git will refuse to do anything otherwise.
+
+[source,shell]
+....
+# git clone https://git.FreeBSD.org/src.git /usr/src
+....
+
+Because the initial checkout must download the full branch of the remote repository, it can take a while.
+Please be patient.
+
+After the initial checkout, the local working copy can be updated by running:
+
+[source,shell]
+....
+# cd wcdir
+# git pull --rebase
+....
+
+To update [.filename]#/usr/src# created in the example above, use:
+
+[source,shell]
+....
+# cd /usr/src
+# git pull --rebase
+....
+
+The update is much quicker than a checkout, only transferring files that have changed.
+
+There are also external mirrors maintained by project members available, please refer to the "External mirrors" section.
+
+=== SSH related information
+
+ - `ssh://${user}@${url}/${repo}.git` can be written as `${user}@${url}:${repo}.git`, i.e., following two URLs are both valid for passing to git:
+ - `ssh://anongit@git.freebsd.org/${repo}.git`
+ - `anongit at git.freebsd.org:${repo}.git`
+
+ As well as the read-write repo:
+ - `ssh://git@(git)repo.freebsd.org/${repo}.git`
+ - `git@(git)repo.freebsd.org:${repo}.git`
+
+- gitrepo.FreeBSD.org host key fingerprints:
+
+ - ECDSA key fingerprint is `SHA256:seWO5D27ySURcx4bknTNKlC1mgai0whP443PAKEvvZA`
+ - ED25519 key fingerprint is `SHA256:lNR6i4BEOaaUhmDHBA1WJsO7H3KtvjE2r5q4sOxtIWo`
+ - RSA key fingerprint is `SHA256:f453CUEFXEJAXlKeEHV+ajJfeEfx9MdKQUD7lIscnQI`
+
+- git.FreeBSD.org host key fingerprints:
+
+ - ECDSA key fingerprint is `SHA256:/UlirUAsGiitupxmtsn7f9b7zCWd0vCs4Yo/tpVWP9w`
+ - ED25519 key fingerprint is `SHA256:y1ljKrKMD3lDObRUG3xJ9gXwEIuqnh306tSyFd1tuZE`
+ - RSA key fingerprint is `SHA256:jBe6FQGoH4HjvrIVM23dcnLZk9kmpdezR/CvQzm7rJM`
+
+These are also published as SSHFP records in DNS.
+
+=== Web-based repository browser
+
+The FreeBSD project currently uses cgit as the web-based repository browser: https://cgit.freebsd.org/
+The URL of the indivirual repository is at: https://cgit.freebsd.org/${repo}/
+
+=== For Users
+
+Using `git clone` and `git pull` from the official distributed mirrors is recommended.
+The GeoDNS should direct you to the nearest mirror to you.
+
+=== For Developers
+
+This section describes the read-write access for committers to push the commits from developers or contributors.
+For read-only access, please refer to the users section above.
+
+==== Daily use
+
+* Clone the repository:
+
+[source,shell]
+....
+% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git
+....
+ Then you should have the official mirrors as your remote:
+
+[source,shell]
+....
+% git remote -v
+freebsd https://git.freebsd.org/${repo}.git (fetch)
+freebsd https://git.freebsd.org/${repo}.git (push)
+....
+
+* Configure the FreeBSD committer data:
+
+ The commit hook in repo.freebsd.org checks the "Commit" field matches the
+ committer's information in FreeBSD.org. The easiest way to get the suggested
+ config is by executing `/usr/local/bin/gen-gitconfig.sh` script on freefall:
+
+[source,shell]
+....
+% gen-gitconfig.sh
+[...]
+% git config user.name (your name in gecos)
+% git config user.email (your login)@FreeBSD.org
+....
+
+* Set the push URL:
+
+[source,shell]
+....
+% git remote set-url --push freebsd git at gitrepo.freebsd.org:${repo}.git
+....
+ Then you should have separated fetch and push URLs as the most efficient setup:
+
+[source,shell]
+....
+% git remote -v
+freebsd https://git.freebsd.org/${repo}.git (fetch)
+freebsd git at gitrepo.freebsd.org:${repo}.git (push)
+....
+ Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future.
+
+* Install commit message template hook:
+
+[source,shell]
+....
+% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks
+% chmod 755 .git/hooks/prepare-commit-msg
+....
+
+==== "admin" branch
+
+The `access` and `mentors` files are stored in an orphan branch, `internal/admin`, in each repository.
+
+Following example is how to check out the `internal/admin` branch to a local branch named `admin`:
+
+[source,shell]
+....
+% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'
+% git fetch
+% git checkout -b admin internal/admin
+....
+Alternatively, you can add a worktree for the `admin` branch:
+
+[source,shell]
+....
+git worktree add -b admin ../${repo}-admin internal/admin
+....
+
+For browsing `internal/admin` branch on web:
+https://cgit.freebsd.org/${repo}/log/?h=internal/admin
+
+For pushing, either specify the full refspec:
+
+[source,shell]
+....
+git push freebsd HEAD:refs/internal/admin
+....
+
+Or set `push.default` to `upstream` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow:
+
+[source,shell]
+....
+git config push.default upstream
+....
+
+[WARNING]
+====
+These internal details may change often.
+====
+
+
+=== External mirrors
+
+Those mirrors are not hosted in FreeBSD.org but still maintained by the project members.
+Users and developers are welcome to pull or browse repositories on those mirrors.
+The project workflow with those mirrors are still under discussion.
+
+==== Codeberg
+ - doc: https://codeberg.org/FreeBSD/freebsd-doc
+ - src: https://codeberg.org/FreeBSD/freebsd-src
+
+==== GitHub
+ - doc: https://github.com/freebsd/freebsd-doc
+ - src: https://github.com/freebsd/freebsd-src
+
+==== GitLab
+ - doc: https://gitlab.com/FreeBSD/freebsd-doc
+ - src: https://gitlab.com/FreeBSD/freebsd-src
+
+=== Mailing lists
+
+General usage and questions about git in the FreeBSD project: [freebsd-git](https://lists.freebsd.org/mailman/listinfo/freebsd-git)
+
+Commit messages will be sent to the following mailing lists:
+
+- [dev-commits-doc-all](https://lists.freebsd.org/mailman/listinfo/dev-commits-doc-all): All changes to the doc repository
+- [dev-commits-ports-all](https://lists.freebsd.org/mailman/listinfo/dev-commits-ports-all): All changes to the ports repository
+- [dev-commits-ports-main](https://lists.freebsd.org/mailman/listinfo/dev-commits-ports-main): All changes to the "main" branch of the ports repository
+- [dev-commits-ports-branches](https://lists.freebsd.org/mailman/listinfo/dev-commits-ports-branches): All changes to the quarterly branches of the ports repository
+- [dev-commits-src-all](https://lists.freebsd.org/mailman/listinfo/dev-commits-src-all): All changes to the src repository
+- [dev-commits-src-main](https://lists.freebsd.org/mailman/listinfo/dev-commits-src-main): All changes to the "main" branch of the src repository (the FreeBSD-CURRENT branch)
+- [dev-commits-src-branches](https://lists.freebsd.org/mailman/listinfo/dev-commits-src-branches): All changes to all stable branches of the src repository
+
+For more information, please refer to the "Commit message lists" section of C.2. "Mailing Lists" in handbook: https://www.freebsd.org/doc/en/books/handbook/eresources-mail.html
+
[[svn]]
== Using Subversion
[[svn-intro]]
=== Introduction
-As of July 2012, FreeBSD uses Subversion as the only version control system for storing all of FreeBSD's source code, documentation, and the Ports Collection.
+As of July 2012, FreeBSD uses Subversion as the only version control system for storing all of FreeBSD's Ports Collection.
+As of December 2020, FreeBSD uses git as the primary version control system for storing all of FreeBSD's source code and documentation.
+Changes from the git repo on the `stable/11`, `stable/12` and related releng branches are exported to the subversion repository.
+This export will continue through the life of these branches.
[NOTE]
====
-Subversion is generally a developer tool. Users may prefer to use `freebsd-update` (crossref:cutting-edge[updating-upgrading-freebsdupdate,“FreeBSD Update”]) to update the FreeBSD base system, and `portsnap` (crossref:ports[ports-using,“Using the Ports Collection”]) to update the FreeBSD Ports Collection.
+Subversion is generally a developer tool.
+Users may prefer to use `freebsd-update` (crossref:cutting-edge[updating-upgrading-freebsdupdate,“FreeBSD Update”]) to update the FreeBSD base system, and `portsnap` (crossref:ports[ports-using,“Using the Ports Collection”]) to update the FreeBSD Ports Collection.
+After March 2021, subversion use is only for legacy branches (`stable/11` and `stable/12`).
====
This section demonstrates how to install Subversion on a FreeBSD system and use it to create a local copy of a FreeBSD repository. Additional information on the use of Subversion is included.
@@ -404,7 +723,9 @@ This section demonstrates how to install Subversion on a FreeBSD system and use
[[svn-ssl-certificates]]
=== Root SSL Certificates
-Installing package:security/ca_root_nss[] allows Subversion to verify the identity of HTTPS repository servers. The root SSL certificates can be installed from a port:
+FreeBSD systems older than 12._x_ do not have proper root certificates.
+Installing package:security/ca_root_nss[] on these systems allows Subversion to verify the identity of HTTPS repository servers.
+The root SSL certificates can be installed from a port:
[source,shell]
....
More information about the dev-commits-doc-all
mailing list