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,311 @@ * {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. +==== + +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 subversion +.... + +[[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/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,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: + ``` + 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 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: +``` +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] ==== @@ -404,7 +702,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: +Older FreeBSD systems 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] ....