From nobody Mon Jan 31 16:00:56 2022 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 1CC99199BA6C for ; Mon, 31 Jan 2022 16:00:57 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4JnXpx0Cw0z4rqN; Mon, 31 Jan 2022 16:00:57 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1643644857; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=atgFDZ+PFmtzKq7NKdRphcpa8343DmItgj/cqV86qf4=; b=fY0KIeA86wh7q98HjfiCuqSxcnKLQ8ryx5tgLBRFYNFFafcxnXXiIrbKFrYuFRdmaC7p6B kzB+bbfZN599lnW4xipUSI8lz+YQ0WIjGVCzj4ZVxoRsW/ebbsBoLH10ypPkyp/Ixlkfsy ZISOnLYnDppxdNHPhI3CrAB7+5PSmrGPpa5/BI5GjoXSVFxapRwoDxs5umjBz/Ym+iVa3i m+M0RT+Bo0JmnkXcIDe951hOk+M6eY4yPnCssExwsUg9FQPKnxW2uxSQ7wJY8eNhX8Mt3z 7FUzB6vNxl2IGD+X2EApcfoaytPRArbsGdFqrpivgs7JEj4RGJuYxxEH+p3/Dw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id DB7FE1F0B5; Mon, 31 Jan 2022 16:00:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 20VG0uhJ071102; Mon, 31 Jan 2022 16:00:56 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 20VG0uYf071101; Mon, 31 Jan 2022 16:00:56 GMT (envelope-from git) Date: Mon, 31 Jan 2022 16:00:56 GMT Message-Id: <202201311600.20VG0uYf071101@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Edward Tomasz Napierala Subject: git: a987bb623c - main - handbook: Shorten the Git section List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: trasz X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: a987bb623cb88676d2af456b6cb729fc874a08c7 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1643644857; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=atgFDZ+PFmtzKq7NKdRphcpa8343DmItgj/cqV86qf4=; b=GUWcfYdBSiOhrjcUmgpbXnh3JVuUC1FFYFK4fdaNqv1wk9bj9RqjTPiwLwC0WStAVfkIQo weGJ7csBD14pUooEeIPwb1SxhSZjuA66RsBDdENTBWT6inVWeRWhpLrUSsnysluNuCC6NZ 6anrucIcv4BZAodtmip5PYgox/BpAIw6Wes5HA7MeXpIW2tfwyFmJng46juSoeIwByXg0F PlkN8OhQipnGWMYDsE/hRMXdeU+whIIMPnjqxAL+H4XK5dGgQouBnKOdkqO16b8GsxKfp+ ttGfAOWG57VZhMDgEp5sM2XUi1X/y7GE5HQA30MKTPIJ3lKT2H3CLPXTkeGBnA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1643644857; a=rsa-sha256; cv=none; b=KIMlpUWLkuqfRv/ZeXskxmCVF4rjX/2gsGdu+kocddFX5n4+RfhKE0UuDFaJhsqjenpT7C WHXLylB2h6gFL6DOthY4KwikLBx/SaSQyts+wuAIh9C/J4QPrNy+ovGSGWdFC6vQD38GYO mnNNr418AKJQvSaasYYaIH+QVl5roVgAOF/oGw1siGPEhVjbEhCYWES81BcfZpD1lAJGun 5uc4l6w6PkKAo6wStTZ21lghjb5IKtht7UT7KTQf50GwT6fdsMuUT5b9u1PDIwvFJq3/bB B3snqXKxGfUJjWbiDVlXDLvFW6VFTR2SmnnwnlheqignaISMgX/OzsTQ0Ff6lQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by trasz: URL: https://cgit.FreeBSD.org/doc/commit/?id=a987bb623cb88676d2af456b6cb729fc874a08c7 commit a987bb623cb88676d2af456b6cb729fc874a08c7 Author: Edward Tomasz Napierala AuthorDate: 2022-01-31 15:58:25 +0000 Commit: Edward Tomasz Napierala CommitDate: 2022-01-31 15:58:41 +0000 handbook: Shorten the Git section Remove stuff that's developer-only - write Git access belongs to Committer's Handbook, normal users don't care. Also remove stuff that's redundant, like two examples for 'git pull', and confusing, like the ssh URL expansion/substutution explanation. Move SSH keys lower down; there are already SSHFP records for them. Tweak wording. Reviewed By: debdrup, Pau Amma Sponsored By: EPSRC Differential Revision: https://reviews.freebsd.org/D34061 --- .../content/en/books/handbook/mirrors/_index.adoc | 142 ++++++--------------- 1 file changed, 40 insertions(+), 102 deletions(-) diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc index 041bdd393c..3723d5f948 100644 --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -552,107 +552,64 @@ 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. +This section demonstrates how to install Git on a FreeBSD system and use it to create a local copy of a FreeBSD source code repository. [[git-install]] === Installation -Git can be installed as a package: +Git can be installed from the Ports Collection, or as a package: [source,shell] .... # pkg install git .... -Git can also be installed from the Ports Collection: - -[source,shell] -.... -# cd /usr/ports/devel/git -# make install clean -.... - [[git-usage]] === Running Git -To fetch a clean copy of the sources into a local directory, use `git`. +To fetch a clean copy of the sources into a local directory, use `git clone`. 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. +Git uses URLs to designate a repository. There are three different repositories, `src` for the FreeBSD system source code, `doc` for documentation, and `ports` for the FreeBSD Ports Collection. -For example, the URL `https://git.FreeBSD.org/src.git` specifies the main branch of the src repository, using the `https` protocol. +All three are reachable over two different protocols: HTTPS and SSH. +For example, the URL `https://git.FreeBSD.org/src.git` specifies the main branch of the `src` repository, using the `https` protocol. [[git-url-table]] .FreeBSD Git Repository URL Table [options="header,footer"] |======================================================= |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` (*) -| Web-based repository browser ports | `https://cgit.freebsd.org/ports` -| Read-only ports repo via HTTPS | `https://git.freebsd.org/ports.git` -| Read-only ports repo via anon-ssh | `ssh://anongit@git.freebsd.org/ports.git` -| Read/write ports repo for committers | `ssh://git@gitrepo.freebsd.org/ports.git` (*) +| 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-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-only ports repo via HTTPS | `https://git.FreeBSD.org/ports.git` +| Read-only ports repo via anon-ssh | `ssh://anongit@git.FreeBSD.org/ports.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`. -==== +External mirrors maintained by project members are also available; please refer to the <> section. -To get started, clone a copy of the FreeBSD repository: - -[source,shell] -.... -# git clone -o freebsd [ -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`. -* _freebsd_ is the name of the origin to use. -By convention in the FreeBSD documentation, the origin is assumed to be `freebsd`. - -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. +To clone a copy of the FreeBSD system source code repository: [source,shell] .... # git clone -o freebsd https://git.FreeBSD.org/src.git /usr/src .... +The `-o freebsd` option specifies the origin; by convention in the FreeBSD documentation, the origin is assumed to be `freebsd`. 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: - +Initially, the working tree contains source code for the `main` branch, which corresponds to CURRENT. +To switch to 13-STABLE instead: [source,shell] .... -# cd wcdir -# git pull --rebase +# cd /usr/src +# git checkout stable/13 .... +The working tree can be updated with `git pull`. To update [.filename]#/usr/src# created in the example above, use: [source,shell] @@ -663,65 +620,32 @@ To update [.filename]#/usr/src# created in the example above, use: 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 <> 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 URLs of individual repositories are listed in <>. - -=== 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. +The FreeBSD project uses cgit as the web-based repository browser: link:https://cgit.FreeBSD.org/[https://cgit.FreeBSD.org/]. === For Developers -Please see the extref:{committers-guide}[Committer's Guide, git-mini-primer]. +For information about write access to repositories see the extref:{committers-guide}[Committer's Guide, git-mini-primer]. [[external-mirrors]] === 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. +Pull requests for the `doc` GitHub repository are being accepted; otherwise, the project workflow with those mirrors is still under discussion. -==== Codeberg +Codeberg:: - doc: https://codeberg.org/FreeBSD/freebsd-doc - ports: https://codeberg.org/FreeBSD/freebsd-ports - src: https://codeberg.org/FreeBSD/freebsd-src -==== GitHub +GitHub:: - doc: https://github.com/freebsd/freebsd-doc - ports: https://github.com/freebsd/freebsd-ports - src: https://github.com/freebsd/freebsd-src -==== GitLab +GitLab:: - doc: https://gitlab.com/FreeBSD/freebsd-doc - ports: https://gitlab.com/FreeBSD/freebsd-ports - src: https://gitlab.com/FreeBSD/freebsd-src @@ -731,6 +655,20 @@ The project workflow with those mirrors are still under discussion. The main mailing list for general usage and questions about git in the FreeBSD project is https://lists.freebsd.org/subscription/freebsd-git[freebsd-git]. For more details, including commit messages lists, see the crossref:handbook/eresources[eresources-mail, Mailing Lists] chapter. +=== SSH host keys + +* 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. + [[svn]] == Using Subversion