git: a987bb623c - main - handbook: Shorten the Git section
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Mon, 31 Jan 2022 16:00:56 UTC
The branch main has been updated by trasz:
URL: https://cgit.FreeBSD.org/doc/commit/?id=a987bb623cb88676d2af456b6cb729fc874a08c7
commit a987bb623cb88676d2af456b6cb729fc874a08c7
Author: Edward Tomasz Napierala <trasz@FreeBSD.org>
AuthorDate: 2022-01-31 15:58:25 +0000
Commit: Edward Tomasz Napierala <trasz@FreeBSD.org>
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 <<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://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 <<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