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
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.
* _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.
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:
Warner Losh
3 years ago