handbook: update mirrors to include git
Pull most of URLs.md from my freebsd-git-docs github repo and reformat to asciidoc. Copy some of the existing svn info and retarget it to Git. Submissions on github from: lwshu@, 0mp@, Alexander Richardson, Ryan Libby, Ceri Davies, Joseph Mingrone Feedback from: Pau Amma, emaste@ Sponsored by: Netflix, Inc Differential Revision: https://reviews.freebsd.org/D29252
This commit is contained in:
Warner Losh
parent
35b2d6e95d
commit
6b6cb62f7d
1 changed files with 324 additions and 3 deletions
|
|
@ -386,17 +386,336 @@ In case of problems, please contact the hostmaster `<{mirrors-us-email}>` for th
|
|||
* {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.
|
||||
In April 2021, the ports tree will migrate to git.
|
||||
====
|
||||
|
||||
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 git
|
||||
....
|
||||
|
||||
[[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/src.git /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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% 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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git remote -v
|
||||
freebsd https://git.freebsd.org/${repo}.git (fetch)
|
||||
freebsd https://git.freebsd.org/${repo}.git (push)
|
||||
....
|
||||
|
||||
* Configure 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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% gen-gitconfig.sh
|
||||
[...]
|
||||
% git config user.name (your name in gecos)
|
||||
% git config user.email (your login)@FreeBSD.org
|
||||
....
|
||||
|
||||
* Set the push URL:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% 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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% 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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% 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`:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% 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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
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:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
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]
|
||||
====
|
||||
Subversion 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.
|
||||
Subversion 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.
|
||||
After March 2021, subversion use is only for legacy branches (`stable/11` and `stable/12`).
|
||||
====
|
||||
|
||||
This section demonstrates how to install Subversion on a FreeBSD system and use it to create a local copy of a FreeBSD repository. Additional information on the use of Subversion is included.
|
||||
|
|
@ -404,7 +723,9 @@ This section demonstrates how to install Subversion on a FreeBSD system and use
|
|||
[[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:
|
||||
FreeBSD systems older than 12._x_ 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]
|
||||
....
|
||||
|
|
|
|||
Loading…
Reference in a new issue