> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-13-freebsd-system-updates/di-13.2-jie-shi-yong-yuan-dai-ma-geng-xin-freebsd.md).
# 13.2 Updating FreeBSD from Source
Building FreeBSD from source allows customization of kernel options and compilation parameters, suitable for architectures not supported by freebsd-update or scenarios requiring a trimmed system.
The basic approach is to obtain the FreeBSD source code, then compile and install it. You can use Git to pull the code directly, download txz compressed files from the FreeBSD download site, or download the zip archive of the current FreeBSD project from GitHub.
For the compilation process, refer to other chapters in this book.
## Obtaining Source Code from Git
### Installing Git
Install Git using pkg:
```sh
# pkg install git
```
Or install Git using Ports:
```sh
# cd /usr/ports/devel/git/
# make install clean
```
### Git Proxy Configuration
In restricted network environments, you may need to configure a proxy for Git to pull source code properly. Below are methods for setting and removing Git proxies.
* Set Git global proxy:
```sh
# git config --global http.proxy http://192.168.X.X:7890 # Set Git global HTTP proxy
# git config --global https.proxy http://192.168.X.X:7890 # Set Git global HTTPS proxy
```
* Remove Git global proxy:
```sh
# git config --global --unset http.proxy # Remove Git global HTTP proxy setting
# git config --global --unset https.proxy # Remove Git global HTTPS proxy setting
```
### Pulling Source Code with Git
#### Pulling CURRENT
Pull the source code from the official FreeBSD repository. Clone the FreeBSD source repository to **/usr/src** using a shallow clone to reduce download size:
```sh
$ git clone --depth 1 https://git.FreeBSD.org/src.git /usr/src
```
Explanation of the `--depth 1` parameter: Uses shallow clone mode, fetching only the latest commit without the complete commit history.
Pull the source code from GitHub (GitHub is a mirror of the src repository on FreeBSD.org, synchronized every 10 minutes).
```sh
$ git clone --depth 1 https://github.com/freebsd/freebsd-src /usr/src
```
#### Pulling a Specific RELEASE
Pull from the official FreeBSD repository. Clone the FreeBSD 15.0 release branch source code to **/usr/src**, using a shallow clone with only that branch:
```sh
$ git clone --branch releng/15.0 --single-branch --depth 1 https://git.freebsd.org/src.git /usr/src
```
Option explanation:
* `--branch releng/15.0`: Specifies the branch to pull (the version of the FreeBSD RELEASE)
* `--single-branch`: Clones only one branch, containing no other refs besides the single cloned branch.
Or pull from GitHub. Clone the FreeBSD 15.0 release branch source code to **/usr/src** from GitHub, using a shallow clone with only that branch:
```sh
$ git clone --branch releng/15.0 --single-branch --depth 1 https://github.com/freebsd/freebsd-src /usr/src
```
### References
* Warner Losh. Submitting GitHub Pull Requests to FreeBSD\[EB/OL]. \[2026-03-25]. . Detailed explanation of the workflow and considerations for submitting pull requests to FreeBSD via GitHub.
## Obtaining Source Code from Compressed Archives (Convenient but Not Latest)
This method is simple to operate.
Taking FreeBSD 15.0-RELEASE as an example:
```sh
# fetch https://download.freebsd.org/releases/amd64/amd64/15.0-RELEASE/src.txz # Download the FreeBSD 15.0-RELEASE source code archive
# tar xvf src.txz -C / # Extract the source code to the root directory
```
> **Why extract to `/`?**
>
> Because the archive contains paths, extracting to **/** will place the source code in **/usr/src**. If you change the path above to **/usr/src**, the source code will be extracted to **/usr/src/usr/src**.
> **Tip**
>
> If the download is slow, you can switch to
## Starting the Build
```sh
# cd /usr/src # Switch to the working directory
# make -j4 buildworld # Build world
# make -j4 kernel # Build and install the kernel (equivalent to buildkernel followed by installkernel)
# reboot # Reboot to use the new kernel
# cd /usr/src # Switch back to the working directory
# etcupdate -p # Merge configuration files that must be updated before installworld
# make installworld # Install world
# etcupdate -B # Reuse the previously built object tree to merge updates
# reboot # Reboot to complete the update process
```
### Appendix: Resolving Conflicts
* `Conflicts remain from previous update, aborting.`
Conflicts need to be resolved.
> **Tip**
>
> Unlike most modern Linux distributions, `vi` on [FreeBSD](https://github.com/freebsd/freebsd-src/tree/main/contrib/nvi) (and OpenBSD) is [*nvi*](https://sites.google.com/a/bostic.com/keithbostic/keith-bostic?authuser=0) (a reimplementation of the original **ex/vi**), not a symbolic link to *vim*. This editor is used infrequently, so it is recommended to switch to another text editor.
>
> ```sh
> export EDITOR=/usr/bin/ee # Switch the default editor to ee. If using csh/tcsh, use setenv EDITOR /usr/bin/ee instead
> export VISUAL=/usr/bin/ee # Switch the visual editor to ee. If using csh/tcsh, use setenv VISUAL /usr/bin/ee instead
> ```
Merge conflicts. Use `etcupdate` to merge configuration file updates:
```sh
# etcupdate -B
Conflicts remain from previous update, aborting.
```
`etcupdate` automatically triggers post-processing for several system files after merging:
| Changed File | Triggered Command |
| ----------------------------------------------------- | ----------------- |
| **/etc/master.passwd** | `pwd_mkdb` |
| **/etc/login.conf** | `cap_mkdb` |
| **/etc/mail/aliases** | `newaliases` |
| **/etc/services** | `services_mkdb` |
| **/etc/localtime** (when **/var/db/zoneinfo** exists) | `tzsetup` |
| **/etc/motd** | `/etc/rc.d/motd` |
Resolve conflicts:
```sh
# etcupdate resolve # Resolve conflicts
Resolving conflict in '/etc/group':
Select: (p) postpone, (df) diff-full, (e) edit,
(h) help for more options: e # Enter e to resolve the conflict
# etcupdate -B
```
## Troubleshooting and Outstanding Issues
### Git: `fatal: unable to update url base from redirection`
The FreeBSD source repository address was used without the `.git` suffix.
### Git: `fatal: unable to access 'https://git.FreeBSD.org/src.git/': SSL certificate problem: certificate is not yet valid`
This is caused by incorrect system time. Use `ntpd -q -g pool.ntp.org` to synchronize the system time. For detailed instructions, refer to other relevant chapters in this book.
## References
* FreeBSD Foundation. 2021 in Review: Software Development\[EB/OL]. \[2026-04-16].
* FreeBSD Project. etcupdate -- manage updates to system files not updated by installworld\[EB/OL]. \[2026-03-25]. . Official technical documentation for the system configuration file update tool.
## Exercises
1. Summarize the complete process of obtaining source code from the FreeBSD Git repository, listing the required commands and their parameter meanings.
2. Use etcupdate to manage configuration file updates in the **/etc** directory, and document a complete conflict resolution process.
3. Modify **/etc/src.conf** to exclude unnecessary components (such as certain debugging tools), and measure the change in `make buildworld` compilation time.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://book.bsdcn.org/ask/flat/chapter-13-freebsd-system-updates/di-13.2-jie-shi-yong-yuan-dai-ma-geng-xin-freebsd.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.