Page MenuHomeFreeBSD
Files F146006466

D29252.id85705.diff
No OneTemporary
Actions

D29252.id85705.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,13 +386,298 @@
* {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 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.
+====
+
+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
+
+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:
+
+[source,bash]
+....
+# cd /usr/ports/security/ca_root_nss
+# make install clean
+....
+
+or as a package:
+
+[source,bash]
+....
+# pkg install ca_root_nss
+....
+
+[[git-install]]
+=== Installation
+
+Git can be installed from the Ports Collection:
+
+[source,bash]
+....
+# cd /usr/ports/devel/git
+# make install clean
+....
+
+Git can also be installed as a package:
+
+[source,bash]
+....
+# pkg install subversion
+....
+
+[[git-usage]]
+=== Running Git
+
+To fetch a clean copy of the sources into a local directory, use `git`. The files in this directory are called a _local working copy_.
+
+[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]
+====
+
+In the future, `gitrepo.freebsd.org` will change to simply `repo.freebsd.org`.
+====
+
+
+A checkout from a given repository is performed with a command like this:
+
+[source,bash]
+....
+# git clone -b branch https://git.FreeBSD.org/repo.git lwcdir
+....
+
+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 `head` branch, while `base` maintains the latest version of -CURRENT under `head` and the respective latest versions of the -STABLE branches under `stable/9` (9._x_) and `stable/10` (10._x_).
+* _lwcdir_ 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.
+
+[source,bash]
+....
+# git clone https://svn.FreeBSD.org/git.src /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,bash]
+....
+# cd lwcdir
+# git pull --rebase
+....
+
+To update [.filename]#/usr/src# created in the example above, use:
+
+[source,bash]
+....
+# 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 "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 mirros 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 develoeprs or contributors. For read-only access, please refer to the users section above.
+
+We only document the important URLs here, the full information of retrieving all data in the repository is available at:
+https://github.com/freebsd/git_conv#gimme-the-repo
+
+==== Daily use
+
+* Clone the repository:
+ ```
+ 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:
+ ```
+ $ git remote -v
+ freebsd https://git.freebsd.org/${repo}.git (fetch)
+ freebsd https://git.freebsd.org/${repo}.git (push)
+ ```
+
+* Config 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:
+
+ ```
+ $ gen-gitconfig.sh
+ [...]
+ git config user.name (your name in gecos)
+ git config user.email (your login)FreeBSD.org
+ ````
+
+* Set the push URL:
+ ```
+ $ 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:
+ ```
+ $ 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:
+ ```
+ 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`:
+
+```
+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:
+```
+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:
+```
+git push freebsd HEAD:refs/internal/admin
+```
+
+Or setting `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:
+```
+git config push.default upstream
+```
+
+=== External mirrors
+
+Those mirrors are not hosted in FreeBSD.org but still maintained by the project members.
+Users and developers are welcomed 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 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]
====

File Metadata

Mime Type
text/plain
Expires
Fri, Feb 27, 11:25 PM (7 h, 20 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29044504
Default Alt Text
D29252.id85705.diff (12 KB)

Event Timeline