D29252.diff
No OneTemporary
Actions

Size

13 KB

Referenced Files

None

Subscribers

None

D29252.diff
View Options

	diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc
	--- a/documentation/content/en/books/handbook/mirrors/_index.adoc
	+++ b/documentation/content/en/books/handbook/mirrors/_index.adoc
	@@ -386,17 +386,336 @@
	* {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@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@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@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 @@
	[[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]
	....

File Metadata

Mime Type: text/plain
Expires: Tue, Feb 11, 5:31 AM (9 h, 42 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 16589371
Default Alt Text: D29252.diff (13 KB)

D29252.diffNo OneTemporaryActions

D29252.diffView Options

File Metadata

Event Timeline

D29252.diff
No OneTemporary
Actions

D29252.diff
View Options