## Introduction
I would like to share a shell script I developed with the assistance of Cla=
ude
(Anthropic's AI) to automate the most tedious part of FreeBSD upgrades:=
resolving merge conflicts in configuration files.
The script is called **freebsd-automerge.sh** and it handles the complete u=
pgrade workflow from start to finish, including conflict resolution, backup=
, and the install/reboot cycle.
---
## The problem it solves
Anyone who has upgraded FreeBSD using `freebsd-update upgrade` knows the pa=
in: When configuration files have been locally modified, freebsd-update sto=
ps and asks you to manually resolve conflicts one by one in an editor. On a=
system with many customized files, this can mean dozens of interruptions r=
equiring careful manual editing.
The standard approach (mergemaster, etcupdate) works well but still require=
s
significant manual intervention. I wanted something fully automated that co=
uld handle an upgrade =E2=80=94 including a major version jump =E2=80=94 wi=
th minimal human input.
---
## How it works
The core idea is a **3-way merge**:
```
base OLD (e.g. 14.3-RELEASE clean) =E2=86=92 your customized file =3D Y=
OUR changes
base OLD (e.g. 14.3-RELEASE clean) =E2=86=92 base NEW (14.4-RELEASE) =3D =
FreeBSD changes
```
By comparing both sets of changes independently against the original clean =
base,the script can automatically apply both your customizations and FreeBS=
D's updates without conflicts =E2=80=94 exactly the same mechanism git =
uses for merging branches.
The script operates in two distinct modes:
### EDITOR mode
The script registers itself as the `$EDITOR` for `freebsd-update`:
```sh
EDITOR=3D/root/freebsd-automerge.sh freebsd-update -r 14.4-RELEASE upgrade<=
br>
```
When freebsd-update encounters a file it cannot merge automatically, instea=
d of opening nano it calls our script with the conflicted file path. The sc=
ript then:
1. Extracts the clean OLD base version from `base.txz`
2. Extracts the clean NEW base version from `base.txz`
3. Uses `merge(1)` (from the base system) for the 3-way merge in-place
4. If residual conflicts remain, fall back to nano for manual resolution
5. Returns control to freebsd-update
### MAIN mode
The primary workflow:
1. Interactive menu querying the FreeBSD mirror in real time to show availa=
ble RELEASE, STABLE, RC, and BETA targets
2. Downloads `base.txz` for both OLD and NEW releases
3. Runs `freebsd-update upgrade` with itself as EDITOR
4. After upgrade, scans `/etc` and `/usr/share` for any remaining `<<=
<<<<<`
markers and resolves them with the same 3-way merge
5. Creates a centralized backup of all conflicted files with SHA256 manifes=
t
and generates a `restore.sh` script for rollback
6. Runs `freebsd-update install` and handles the reboot cycle automatically=
,
including the two-pass install required for major version upgrades
---
## Key features
- **Zero configuration** =E2=80=94 detects OLD and NEW versions automatical=
ly from
`uname -r` and `/var/db/freebsd-update/tag`
- **Live mirror query** =E2=80=94 the target selection menu fetches availab=
le versions directly from the FreeBSD mirror at runtime
- **Kernel/userland selection** =E2=80=94 asks whether to upgrade both or u=
serland only,useful for systems running custom kernels (e.g. ARM SBCs with =
custom DRM drivers)
- **Auto-confirm mode** =E2=80=94 `--auto-confirm` flag uses `expect(1)` to=
answer
freebsd-update's interactive prompts automatically
- **Major upgrade support** =E2=80=94 handles the two-install, two-reboot c=
ycle for
major version jumps (e.g. 14.x =E2=86=92 15.x) using a temporary `rc.d` s=
ervice
that survives the first reboot
- **Safe by design** =E2=80=94 full backup before touching anything, restor=
e script
generated automatically, SHA256 integrity verification
---
## Current limitations and known bugs
I want to be transparent about what still needs work:
1. **STABLE branch detection** =E2=80=94 the menu regex for `-STABLE` targe=
ts does not always match the mirror directory listing correctly
2. **State recovery after interruption** =E2=80=94 if the script is killed =
mid-upgrade,
resuming it does not correctly re-enter the freebsd-update merge phase;<=
br>
it tries to call `freebsd-update install` prematurely
3. **grep -c arithmetic** =E2=80=94 a subtle shell arithmetic bug produces<=
br>
`[: 0 0: bad number` in some cases when counting conflict markers
4. **STABLE/CURRENT upgrade type** =E2=80=94 `is_major_upgrade()` only comp=
ares
major version numbers; it does not distinguish STABLE or CURRENT targets=
which may need different handling
5. **Terminal compatibility** =E2=80=94 Unicode box-drawing characters in m=
enus do not render correctly in all FreeBSD terminal configurations; should=
fall back
to plain ASCII
---
## What I would love feedback on
This is where I genuinely need input from people who know FreeBSD internals=
better than I do:
**1. Is using `$EDITOR` the right hook into freebsd-update?**
Is there a cleaner, more supported way to intercept freebsd-update's me=
rge
phase? I am essentially abusing the EDITOR variable =E2=80=94 it works, but=
it feels
fragile. Is there an official API or hook mechanism I am missing?
**2. The 3-way merge approach =E2=80=94 is merge(1) the right tool?**
I am using `merge(1)` from the `rcs` package. Are there better alternatives=
in the FreeBSD base system? `diff3(1)` is available but requires more
orchestration. `patch(1)` could work but loses context. Thoughts?
**3. Handling STABLE and CURRENT upgrades**
Upgrading to a -STABLE or -CURRENT branch is fundamentally different from
a RELEASE upgrade =E2=80=94 freebsd-update behaves differently, and the bas=
e.txz
download path is different. Has anyone automated this reliably?
**4. The two-reboot major upgrade cycle**
I implemented this using a temporary `rc.d` service (`automerge_resume`)
that runs `freebsd-update install` after the first reboot and then removes<=
br>
itself. It works, but it feels like a hack. Is there a cleaner pattern?
**5. pkg alignment after major upgrades**
After a major upgrade (e.g. 14.x =E2=86=92 15.x), all installed packages ne=
ed to be
rebuilt or reinstalled. I currently just tell the user to run `pkg upgrade =
-f`
manually. Should this be integrated into the script? What is the safest
sequence?
---
## How to get it
The script is a single self-contained shell file with no external dependenc=
ies
beyond `merge(1)` (from `pkg install rcs`) and optionally `expect(1)` for
auto-confirm mode.
Usage:
```sh
# Show interactive target menu (queries mirror live)
sh freebsd-automerge.sh
# Filter menu to branch 14
sh freebsd-automerge.sh 14
# Direct upgrade, no menu
sh freebsd-automerge.sh 14.4-RELEASE
# Fully automated (requires: pkg install expect)
sh freebsd-automerge.sh --auto-confirm 14
```
---
## Credits
The script was conceived and directed by **ZioMario** (forums.freebsd.org user: ZioMario), developed with th=
e assistance of **Claude** (Anthropic AI).
The idea, architecture decisions, testing, and debugging were all driven by=
ZioMario =E2=80=94 Claude was used as an implementation tool.
All feedback, pull requests, and brutal criticism are welcome.