git: a987bb623c - main - handbook: Shorten the Git section
Edward Tomasz Napierala <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
The branch main has been updated by trasz: URL: https://cgit.FreeBSD.org/doc/commit/?id=a987bb623cb88676d2af456b6cb729fc874a08c7 commit a987bb623cb88676d2af456b6cb729fc874a08c7 Author: Edward Tomasz Napierala <[email protected]> AuthorDate: 2022-01-31 15:58:25 +0000 Commit: Edward Tomasz Napierala <[email protected]> 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://[email protected]/src.git` -| Read/write src repo for committers | `ssh://[email protected]/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://[email protected]/doc.git` -| Read/write doc repo for committers | `ssh://[email protected]/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://[email protected]/ports.git` -| Read/write ports repo for committers | `ssh://[email protected]/ports.git` (*) +| Read-only src repo via HTTPS | `https://git.FreeBSD.org/src.git` +| Read-only src repo via anon-ssh | `ssh://[email protected]/src.git` +| Read-only doc repo via HTTPS | `https://git.FreeBSD.org/doc.git` +| Read-only doc repo via anon-ssh | `ssh://[email protected]/doc.git` +| Read-only ports repo via HTTPS | `https://git.FreeBSD.org/ports.git` +| Read-only ports repo via anon-ssh | `ssh://[email protected]/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 <<external-mirrors>> 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 <<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://[email protected]/${repo}.git` -** `[email protected]:${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 <<git-url-table>>. - -=== 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