feat(update): source installs default to the stable release channel

`hermes update` and the Desktop update button on an official source
checkout now move between published vX.Y.Z releases instead of tracking
main commit by commit, and `hermes update --set-channel stable` works.

- stable resolves through R2 when a record exists; until one is published
  it falls back to the latest published GitHub release (non-draft,
  non-prerelease, strict vX.Y.Z, origin tag verified). It used to fail
  with "Channel object not found: releases/channels/stable.json".
- default_channel(): an official-origin source checkout defaults to
  stable; forks, mirrors and checkout-less trees keep main. Package
  installs (MSIX, Store, bundled, electron-updater) are untouched.
- An install that never chose a channel only moves forward: a checkout
  already newer than the latest release (every install that tracked main)
  stays put until a newer release ships. --set-channel stable is the
  explicit consent to land exactly on the release commit.
- Same rule in --check, the apply path and the passive source_check the
  Desktop and banner use.
This commit is contained in:
Teknium
2026-10-09 15:10:22 -07:00
Unverified
parent 097fcaa1de
commit 6a92a2aa49
12 changed files with 267 additions and 73 deletions
+8 -5
View File
@@ -267,14 +267,15 @@ def _write_cache(cache_file: Path, identity: dict, now: float, result: dict) ->
logger.debug("Could not cache source check: %s", exc)
def _resolve_channel(result: dict, channel: str, co: _Checkout):
def _resolve_channel(result: dict, channel: str, co: _Checkout, *, forward_only: bool = False):
"""Resolve a release channel's target into ``result``; the SourceTarget, or None on error.
A target with a pinned commit is final; one without names a branch to follow instead.
"""
try:
source_target = resolve_source_target(channel, [co.git] if not co.embedded else None, co.root,
repository=co.repository or OFFICIAL_REPOSITORY)
repository=co.repository or OFFICIAL_REPOSITORY,
forward_only=forward_only)
except (OSError, ValueError, subprocess.SubprocessError) as exc:
result.update(error="release-unavailable", message=f"Could not resolve the {channel} source channel: {exc}")
return None
@@ -382,7 +383,7 @@ def check_for_updates(*, install_root: Path | None = None, home: Path | None = N
"""
from hermes_cli.config import get_project_root, require_readable_config_before_write
from hermes_cli.steward import read_install_stamp
from hermes_cli.update_channel import install_id, resolve_update_channel
from hermes_cli.update_channel import channel_record, install_id, resolve_update_channel, rides_default_channel
from hermes_cli.release_channels import validate_name
embedded = (os.environ.get("HERMES_REVISION") or None) if install_root is None else None
@@ -397,6 +398,7 @@ def check_for_updates(*, install_root: Path | None = None, home: Path | None = N
if passive and (config.get("updates") or {}).get("check") is False:
return {**result, "reason": "disabled"}
channel = resolve_update_channel(config, root) if channel is None else validate_name(channel)
forward_only = rides_default_channel(channel_record(config, root), channel, root)
co = _read_checkout(root, git, embedded)
desktop_config = _read_json(branch_config_path) if branch_config_path else None
configured_branch = _configured_branch(desktop_config)
@@ -407,7 +409,8 @@ def check_for_updates(*, install_root: Path | None = None, home: Path | None = N
else:
result["branch"] = selected_branch
identity = {"root": str(root), "home": str(home), "head": co.head, "origin": co.origin, "branch": selected_branch,
"channel": channel, "embedded": embedded, "branchOverride": branch is not None, "channelProtocol": 1}
"channel": channel, "embedded": embedded, "branchOverride": branch is not None, "channelProtocol": 1,
"forwardOnly": forward_only}
cache_file = Path(cache_path) if cache_path is not None else home / "source-checks" / f"{install_id(root)}.json"
now = time.time()
cached = None if force else _cached_status(cache_file, identity, now)
@@ -418,7 +421,7 @@ def check_for_updates(*, install_root: Path | None = None, home: Path | None = N
if not _is_full_sha(co.head):
result.update(error="head-unavailable", message="Could not read the installed revision.")
elif branch is None:
source_target = _resolve_channel(result, channel, co)
source_target = _resolve_channel(result, channel, co, forward_only=forward_only)
if source_target is not None and not source_target.commit:
# The record supplies a default, not permission to leave the user's branch.
selected_branch = configured_branch or _checked_out_branch(co.current_branch, source_target.branch)
+54 -4
View File
@@ -54,8 +54,13 @@ class SourceTarget:
def retired(self) -> bool:
return self.requested_channel != self.channel
ahead: bool = False
@property
def label(self) -> str:
if self.ahead:
return (f"{self.channel} v{self.version}; this checkout is newer and waits for the next release"
" (`hermes update --set-channel main` follows every commit)")
return f"{self.channel} v{self.version} ({self.commit[:12]})" if self.commit else self.channel
@@ -72,8 +77,44 @@ def _resolve_channel(name: str, repository: str):
return ChannelReader(_PUBLIC_BASE, repository=repository).resolve(name)
def resolve_source_target(channel: str, git_cmd=None, cwd=None, *, repository=None) -> SourceTarget:
"""Resolve every subscription, including default labels, through R2."""
def resolve_source_target(channel: str, git_cmd=None, cwd=None, *, repository=None,
forward_only: bool = False) -> SourceTarget:
"""Resolve every subscription, including default labels, through R2.
``forward_only`` (an unchosen default subscription) pins a checkout that already
contains the release to its own HEAD, so the update is a no-op instead of a downgrade.
"""
target = _resolve_source_target(channel, git_cmd, cwd, repository=repository)
if forward_only and target.commit and git_cmd is not None and cwd is not None:
head = _head_containing(git_cmd, cwd, target.commit, target.repository)
if head is not None and head != target.commit:
from dataclasses import replace
return replace(target, commit=head, ahead=True)
return target
def _head_containing(git_cmd, cwd, commit: str, repository: str) -> str | None:
"""HEAD's sha when it equals or descends from ``commit``, else None."""
from hermes_cli.source_check import _github_compare, source_git_env
def run(*args):
return subprocess.run(
[*git_cmd, *args], cwd=cwd, capture_output=True, text=True, encoding="utf-8",
errors="replace", timeout=10, stdin=subprocess.DEVNULL, env=source_git_env())
head = run("rev-parse", "HEAD").stdout.strip()
if not _SHA.fullmatch(head):
return None
ancestry = run("merge-base", "--is-ancestor", commit, head).returncode
if ancestry in (0, 1):
return head if ancestry == 0 else None
# A shallow checkout may lack the release commit; GitHub knows the relation.
status = (_github_compare(commit, head, repository) or {}).get("status")
return head if status in ("ahead", "identical") else None
def _resolve_source_target(channel: str, git_cmd=None, cwd=None, *, repository=None) -> SourceTarget:
from hermes_cli.release_channels import ChannelNotFound, validate_name
validate_name(channel)
@@ -81,6 +122,14 @@ def resolve_source_target(channel: str, git_cmd=None, cwd=None, *, repository=No
try:
resolved = _resolve_channel(channel, repository)
except ChannelNotFound:
if channel == "stable":
# Until R2 publishes a stable record, stable is the latest published
# GitHub release (non-draft, non-prerelease, strict vX.Y.Z, origin
# tag verified). Never a branch tip or an arbitrary tag.
tag, commit = resolve_source_release("stable", git_cmd, cwd, repository=repository)
if commit is None:
raise ValueError("No published stable release could be verified") from None
return SourceTarget(channel, channel, repository, commit=commit, version=str(tag).removeprefix("v"))
if channel != "main":
raise
# main IS the source branch; its record can only add a retirement.
@@ -241,9 +290,10 @@ def _release_pointer(channel: str) -> tuple[str | None, str | None]:
def resolve_source_release(channel: str, git_cmd=None, cwd=None, *, repository=None) -> tuple[str | None, str | None]:
"""Read historical stable/canary release metadata (not channel discovery).
"""Read published stable/canary release metadata (not channel discovery).
Runtime check/apply use ``resolve_source_target`` and never fall back here.
Runtime check/apply go through ``resolve_source_target``; only an unpublished
R2 ``stable`` record falls back here.
Channel pointers outrank GitHub's release listing. A malformed pointer,
draft, or tag/commit mismatch is not permission to select a different build.
``git_cmd`` resolves the selected tag on origin; ZIP callers omit it and
+4 -3
View File
@@ -81,9 +81,10 @@ def build_update_parser(subparsers, *, cmd_update: Callable) -> None:
help=(
"Persist the update channel for THIS install (recorded per "
"install in config.yaml under update.installs). Names are resolved "
"from the release archive, not a built-in list. Source installs "
"check out the published build's exact commit; main follows the "
"source branch. Package channels are baked into their identities."
"from the release archive, not a built-in list. Official source "
"checkouts default to 'stable' (the latest published vX.Y.Z "
"release, exact commit); 'main' follows the source branch. "
"Package channels are baked into their identities."
),
)
update_parser.add_argument(
+40 -2
View File
@@ -22,6 +22,7 @@ same path, and the channel opt-in must survive that.
(it knows its own id — the user never types a sha).
* Shown by ``hermes update --install-id`` and the desktop About page.
* Source installs select an R2 channel name, or use an explicit branch override.
Unconfigured official checkouts track ``stable``; forks and mirrors keep ``main``.
Bundles derive their channel from their baked identity, never these records.
``external`` installs have no configurable channel; the steward owns updates.
@@ -139,7 +140,8 @@ def _package_channel(stamp: dict) -> bool:
def default_channel(project_root: Optional[Path] = None) -> str:
"""The channel an unconfigured install tracks.
``self`` source installs follow main (historical behavior).
A source checkout of the official repository follows the latest published
stable release. Forks, mirrors and checkout-less trees keep following main.
``electron-updater`` and ``app-installer`` bundles report their artifact
channel: a canary artifact tracks canary, every other bundle
tracks stable. The stamp's ``tag`` is the authority, the same fact
@@ -153,7 +155,7 @@ def default_channel(project_root: Optional[Path] = None) -> str:
root = Path(project_root) if project_root is not None else install_root()
stamp = _read_stamp(root)
if not _package_channel(stamp):
return CHANNEL_MAIN
return CHANNEL_STABLE if _tracks_official_origin(root) else CHANNEL_MAIN
if stamp.get("source") == "channel-build":
request = stamp.get("channelBuild")
if not isinstance(request, dict):
@@ -162,6 +164,42 @@ def default_channel(project_root: Optional[Path] = None) -> str:
return CHANNEL_CANARY if is_canary_tag(stamp.get("tag")) else CHANNEL_STABLE
def _tracks_official_origin(root: Path) -> bool:
"""True when ``root`` is a git checkout whose ``remote.origin.url`` is the official repo.
Read from the git config file (no git process: the banner and boot paths call this).
Forks, mirrors and local-path origins publish no official releases.
"""
from hermes_cli.source_releases import _GITHUB_ORIGIN, OFFICIAL_REPOSITORY
from hermes_cli.update_lock import _git_common_dir
common = _git_common_dir(root)
try:
lines = (common / "config").read_text(encoding="utf-8-sig").splitlines() if common else []
except OSError:
return False
in_origin = False
for line in lines:
text = line.strip()
if text.startswith("["):
in_origin = text == '[remote "origin"]'
elif in_origin and text.partition("=")[0].strip() == "url":
match = _GITHUB_ORIGIN.fullmatch(text.partition("=")[2].strip())
return bool(match) and match[1].lower() == OFFICIAL_REPOSITORY.lower()
return False
def rides_default_channel(record: dict, channel: str, project_root: Optional[Path] = None) -> bool:
"""True when no channel was ever persisted (``record``) and ``channel`` is the default.
Such an install never consented to a release switch, so it only moves forward: a
checkout already newer than the latest release waits for the next one. A transient
``--channel`` naming the default (the Desktop passes the channel its check reported)
is still the default; only ``--set-channel`` consents to a downgrade.
"""
return record.get("channel") is None and channel == default_channel(project_root)
def resolve_update_channel(
config: Optional[dict] = None,
project_root: Optional[Path] = None,
+14 -45
View File
@@ -1854,47 +1854,10 @@ def _cmd_update_impl(args, gateway_mode: bool):
had_desktop_app_before_update, gateway_mode)
branch = _m()._resolve_update_branch(args)
completion_request["branch"] = branch
target_ref = f"origin/{branch}"
release_sha = None
target_repository = None
selected_channel = _update_run_channel(args)
if not getattr(args, "branch", None):
from hermes_cli.release_channels import retrying_reads
from hermes_cli.source_releases import resolve_source_target
from copy import deepcopy
from hermes_cli.config import require_readable_config_before_write
from hermes_cli.update_channel import channel_record
original_record = deepcopy(channel_record(require_readable_config_before_write(
Path(completion_request["home"]) / "config.yaml"), _m().PROJECT_ROOT))
print(f"→ Update channel: {selected_channel}")
try:
with retrying_reads():
target = resolve_source_target(
selected_channel, None if use_zip_update else git_cmd, _m().PROJECT_ROOT)
except (OSError, ValueError, subprocess.SubprocessError) as exc:
print(f"✗ Could not resolve the {selected_channel} source channel: {exc}. No update was applied.")
_m()._resume_windows_gateways_after_update(_windows_gateway_resume)
_record_stop("channel_unresolved")
sys.exit(1)
if target.retired:
print(f"→ {selected_channel} retired; source destination: {target.channel}")
if (not getattr(args, "channel", None)
and original_record.get("channel", "main") == selected_channel):
completion_request["channel_retirement"] = {
"original": original_record, "destination": target.channel}
target_repository = target.repository
release_sha = target.commit
if release_sha:
print(f"→ Latest release: {target.label}")
target_ref = release_sha
completion_request["expected_sha"] = release_sha
else:
assert target.branch is not None # a SourceTarget without a commit names its branch
branch = target.branch
completion_request["branch"] = branch
target_ref = f"origin/{branch}"
target_ref, release_sha, target_is_head, target_repository = _check.select_apply_target(
args, branch, completion_request, git_cmd=None if use_zip_update else git_cmd,
stop=lambda: _m()._resume_windows_gateways_after_update(_windows_gateway_resume))
branch = completion_request["branch"]
if use_zip_update:
try:
@@ -1929,15 +1892,21 @@ def _cmd_update_impl(args, gateway_mode: bool):
# (#123346, #124645). Unshallow it (commits only) first.
_heal_stale_shallow_checkout(_m().PROJECT_ROOT, branch)
print("→ Fetching updates...")
if release_sha:
if release_sha and target_is_head:
# Forward-only default: the checkout already contains the release; nothing to fetch.
fetch_args = None
elif release_sha:
fetch_args = ["fetch", "--no-tags", "origin", target_ref]
else:
fetch_args = ["fetch", "origin", _check.tracking_refspec("origin", branch)]
from hermes_cli.gitlock import fetch_with_partial_clone_recovery, is_partial_clone_pack_objects_crash
# Marking the unmarked packs clears the git 2.53+ partial-clone pack-objects crash (#124272).
fetch_result = fetch_with_partial_clone_recovery(
lambda gc, a: _git_run(gc, a, network=True), git_cmd, fetch_args, _m().PROJECT_ROOT)
if fetch_args is None:
fetch_result = subprocess.CompletedProcess([], 0)
else:
print("→ Fetching updates...")
fetch_result = fetch_with_partial_clone_recovery(
lambda gc, a: _git_run(gc, a, network=True), git_cmd, fetch_args, _m().PROJECT_ROOT)
if fetch_result.returncode != 0:
if is_partial_clone_pack_objects_crash(fetch_result.stderr or ""):
print("✗ git still crashed after marking this checkout's packs. See 'Fetch fails with"
+53 -3
View File
@@ -66,13 +66,17 @@ def channel_compare_branch(selected_channel: str, git_cmd: list[str], root: Path
"""Report a release-pinned channel's verdict, or return the branch to compare against.
``None`` means the verdict is printed (the channel pins a commit); exits 1 when the channel
cannot be resolved.
cannot be resolved. An install riding its default channel only ever moves forward.
"""
from hermes_cli.config import get_config_path, require_readable_config_before_write
from hermes_cli.source_releases import resolve_source_target
from hermes_cli.update_channel import channel_record, rides_default_channel
print(f"→ Update channel: {selected_channel}")
record = channel_record(require_readable_config_before_write(get_config_path()), root)
forward_only = rides_default_channel(record, selected_channel, root)
try:
target = resolve_source_target(selected_channel, git_cmd, root)
target = resolve_source_target(selected_channel, git_cmd, root, forward_only=forward_only)
except (OSError, ValueError, subprocess.SubprocessError) as exc:
print(f"✗ Could not resolve the {selected_channel} source channel: {exc}")
sys.exit(1)
@@ -80,7 +84,9 @@ def channel_compare_branch(selected_channel: str, git_cmd: list[str], root: Path
return target.branch
if target.retired:
print(f"→ {selected_channel} retired; source destination: {target.channel}")
if _uc()._capture_head_sha(git_cmd, root) == target.commit:
if target.ahead:
print(f"✓ No newer release: {target.label}.")
elif _uc()._capture_head_sha(git_cmd, root) == target.commit:
print(f"✓ Up to date with the latest release ({target.label}).")
else:
print(f"→ Selected release available: {target.label}")
@@ -189,3 +195,47 @@ def report_rev_list_verdict(git_cmd: list[str], root: Path, compare_branch: str)
from hermes_cli.config import recommended_update_command
print(f" Run '{recommended_update_command()}' to install.")
def select_apply_target(args, branch: str, request: dict, *, git_cmd, stop) -> tuple:
"""Resolve the update's target before any tree write: ``(target_ref, release_sha,
target_is_head, repository)``; records branch/expected_sha/retirement on ``request``.
``target_is_head`` means an unchosen default subscription is already past the release,
so HEAD itself is the target. Exits 1 (after ``stop()``) when the channel is unresolvable.
"""
from copy import deepcopy
from hermes_cli.config import require_readable_config_before_write
from hermes_cli.release_channels import retrying_reads
from hermes_cli.source_releases import resolve_source_target
from hermes_cli.update_channel import channel_record, rides_default_channel
from hermes_cli.update_cmd_common import _record_stop
if getattr(args, "branch", None):
return f"origin/{branch}", None, False, None
root = _uc()._m().PROJECT_ROOT
selected = _uc()._update_run_channel(args)
original = deepcopy(channel_record(require_readable_config_before_write(
Path(request["home"]) / "config.yaml"), root))
print(f"→ Update channel: {selected}")
try:
with retrying_reads():
target = resolve_source_target(selected, git_cmd, root,
forward_only=rides_default_channel(original, selected, root))
except (OSError, ValueError, subprocess.SubprocessError) as exc:
print(f"✗ Could not resolve the {selected} source channel: {exc}. No update was applied.")
stop()
_record_stop("channel_unresolved")
sys.exit(1)
if target.retired:
print(f"→ {selected} retired; source destination: {target.channel}")
if not getattr(args, "channel", None) and original.get("channel", "main") == selected:
request["channel_retirement"] = {"original": original, "destination": target.channel}
if target.commit:
print(f"→ {'Release' if target.ahead else 'Latest release'}: {target.label}")
request["expected_sha"] = target.commit
return target.commit, target.commit, target.ahead, target.repository
assert target.branch is not None # a SourceTarget without a commit names its branch
request["branch"] = target.branch
return f"origin/{target.branch}", None, False, target.repository
@@ -37,7 +37,7 @@ def test_release_channel_never_compares_main_or_reuses_main_cache(tmp_path, monk
monkeypatch.setattr(source_check, "_branch_tip", main)
status = source_check.check_for_updates(passive=True)
assert status["behind"] == source_check.UPDATE_AVAILABLE_NO_COUNT
resolve.assert_called_once_with(channel, ["git"], root, repository="example/fork")
resolve.assert_called_once_with(channel, ["git"], root, repository="example/fork", forward_only=False)
main.assert_not_called()
assert status["channel"] == channel
assert status["targetSha"] == target
@@ -167,7 +167,7 @@ def test_unpublished_main_record_keeps_following_the_git_branch(source, monkeypa
assert "error" not in status, status
assert status["targetSha"] == source.commits[2]
with pytest.raises(ChannelNotFound):
source_releases.resolve_source_target("stable", ["git"], source.root)
source_releases.resolve_source_target("canary", ["git"], source.root)
def test_passive_check_reports_retirement_without_adopting_it(source, monkeypatch):
+4 -1
View File
@@ -246,7 +246,7 @@ def test_dynamic_source_channel_preserves_branch_precedence(installation, select
# branch, so the check keeps following a branch via git, with the usual branch
# precedence (test_unpublished_main_record_follows_the_branch below).
@pytest.mark.parametrize("name,failure", [
("stable", "missing"), ("canary", "missing"),
("canary", "missing"),
(None, "missing"), (None, "malformed"), (None, "foreign"), (None, "unpublished"),
])
def test_channel_failure_never_probes_or_heals_a_branch(installation, name, failure):
@@ -490,9 +490,12 @@ def test_malformed_optional_changelog_and_cache_do_not_hide_the_update(installat
@pytest.mark.parametrize("repository,heals", [("NousResearch/hermes-agent", True), ("fixture/fork", False)])
def test_official_ssh_healing_uses_public_https_without_retargeting_forks(installation, monkeypatch, repository, heals):
from hermes_cli.source_check import check_for_updates
from hermes_cli.update_channel import set_install_channel
root, linked, home, _base, head, responses, _requests, git = installation
git("remote", "set-url", "origin", f"git@github.com:{repository}.git")
git("config", f"url.{root.as_uri()}.insteadOf", "https://github.com/NousResearch/hermes-agent.git")
# The branch heal is a main-channel concern; an official checkout's default is stable.
set_install_channel("main", linked)
monkeypatch.setenv("GIT_SSH_COMMAND", "false")
branch_file = home / "desktop-update.json"
branch_file.write_text(json.dumps({"branch": "deleted"}))
@@ -245,3 +245,57 @@ def test_missing_pointers_fall_back_only_to_published_releases(releases, channel
)
assert not any("/tags?" in path for path in releases.requests)
assert f"/repos/NousResearch/hermes-agent/releases/tags/{releases.tags[channel]}" not in releases.requests
def _track_official_origin(releases):
official = "https://github.com/NousResearch/hermes-agent.git"
git(releases.root, "remote", "set-url", "origin", official)
git(releases.root, "config", f"url.{releases.origin.as_uri()}.insteadOf", official)
def test_unpublished_stable_record_resolves_the_published_github_release(releases):
"""Until R2 carries a stable record, stable is the latest published GitHub release."""
from hermes_cli import source_releases
from hermes_cli.release_channels import ChannelNotFound
_track_official_origin(releases)
releases.responses["/repos/NousResearch/hermes-agent/releases/latest"] = {
"tag_name": releases.tags["stable"], "draft": False, "prerelease": False}
def unpublished(name, repository):
raise ChannelNotFound(f"Channel object not found: releases/channels/{name}.json")
source_releases._resolve_channel = unpublished
target = source_releases.resolve_source_target("stable", ["git"], releases.root)
assert (target.commit, target.version) == (releases.commits[1], "1.2.3")
with pytest.raises(ChannelNotFound):
source_releases.resolve_source_target("canary", ["git"], releases.root)
@pytest.mark.parametrize("start,expected", [(0, 1), (3, 3)], ids=["behind-release", "newer-than-release"])
def test_default_stable_only_moves_forward_until_the_channel_is_chosen(releases, monkeypatch, capsys,
start, expected):
from hermes_cli.update_channel import default_channel
_track_official_origin(releases)
git(releases.root, "checkout", "--detach", releases.commits[start])
assert default_channel(releases.root) == "stable"
opts = update_cmd._UpdateOptions(
pre_update_version=None, gw_input_fn=None,
assume_yes=True, keep_stash=False, switch_branch=False, discard_local_changes=False,
)
monkeypatch.setattr(update_cmd, "_resolve_update_options", lambda *_: opts)
monkeypatch.setattr(update_cmd, "_begin_update_receipt_and_plan", lambda *_: None)
monkeypatch.setattr(main, "_run_pre_update_backup", lambda *_: None)
monkeypatch.setattr(main, "_pause_windows_gateways_for_update", lambda: None)
monkeypatch.setattr(update_cmd, "_prepare_git_command", lambda **_: (False, ["git"], False))
monkeypatch.setattr(update_cmd, "_complete_source_update", lambda request: None)
# The Desktop passes the channel its check reported; naming the default is not a choice.
update_cmd._cmd_update_impl(SimpleNamespace(branch=None, channel="stable", force_venv=True), False)
assert git(releases.root, "rev-parse", "HEAD") == releases.commits[expected]
update_cmd._cmd_update_check()
assert ("No newer release" if start > 1 else "Up to date with") in capsys.readouterr().out
# Persisting the channel is consent to land exactly on the release.
set_install_channel("stable", releases.root)
update_cmd._cmd_update_impl(SimpleNamespace(branch=None, channel=None, force_venv=True), False)
assert git(releases.root, "rev-parse", "HEAD") == releases.commits[1]
+24 -5
View File
@@ -30,8 +30,26 @@ For a managed source installation:
hermes update
```
Source installs track `main`, the only valid source channel. The update
prepares dependencies through PM and reports configuration changes and process-restart results.
A source checkout of the official repository tracks the **stable** channel: the
latest published `vX.Y.Z` GitHub release (never a draft, prerelease or canary tag),
checked out at its exact commit. `hermes update` and the Desktop update button move
only from one release to the next, never commit by commit. Forks and mirrors keep
tracking their `main` branch. The update prepares dependencies through PM and
reports configuration changes and process-restart results.
```bash
hermes update --set-channel main # follow every commit on main instead
hermes update --set-channel stable # back to releases only
hermes update --channel main # one run against main; nothing is saved
```
The choice is stored per install under `update.installs` in `config.yaml`. An
install that never chose a channel only moves forward: a checkout already newer
than the latest release (for example one that tracked `main` before this default)
stays where it is until a newer release ships. Running `--set-channel stable`
pins the checkout to the exact release commit, even when that is older.
Windows Store, MSIX and bundled desktop installs are unaffected; their channel
is baked into the package (see below).
### Bundled desktop updates
@@ -230,8 +248,8 @@ git -C "$repo" -c gc.writeCommitGraph=false gc --auto
### Updating against a non-default branch: `--branch`
Source installs track `origin/main`. Use
`--branch NAME` for a one-run branch override:
`--branch NAME` is a one-run override that updates against a branch tip
instead of the selected channel:
```bash
hermes update --branch release-candidate
@@ -287,7 +305,8 @@ You can pass `--keep-stash` to a terminal `hermes update` too if you want the sa
### Preview-only: `hermes update --check`
`hermes update --check` compares the checkout with `origin/main`
`hermes update --check` compares the checkout with the selected channel's
target (the latest stable release by default, `origin/main` on the main channel)
without applying code, installing dependencies, or restarting gateways. The
comparison can fetch Git metadata; it is not a promise of zero filesystem writes.
Package-owned installs report their external update method.
@@ -14,7 +14,14 @@ description: "如何将 Hermes Agent 更新至最新版本或将其卸载"
hermes update
```
此命令会从 `main` 拉取最新代码、更新依赖项,并提示你配置自上次更新以来新增的选项。
官方仓库的源码安装默认跟踪 **stable** 渠道:最新正式发布的 `vX.Y.Z` GitHub 版本(不含草稿、预发布或 canary 标签),并检出其确切提交。`hermes update` 和桌面应用的更新按钮只会在正式版本之间升级,不再逐个提交跟进。Fork 和镜像仍跟踪各自的 `main` 分支。此命令还会更新依赖项,并提示你配置自上次更新以来新增的选项。
```bash
hermes update --set-channel main # 改为跟踪 main 上的每个提交
hermes update --set-channel stable # 恢复为仅正式版本
```
从未选择渠道的安装只会向前更新:已经比最新正式版本更新的检出(例如此前跟踪 `main` 的安装)会保持不动,直到发布更新的版本。显式运行 `--set-channel stable` 会把检出固定到该版本的确切提交,即使它更旧。Windows 应用商店、MSIX 和捆绑桌面安装不受影响。
:::tip
`hermes update` 会自动检测新的配置选项并提示你添加。如果跳过了该提示,可手动运行 `hermes config check` 查看缺失的选项,再运行 `hermes config migrate` 以交互方式添加。
@@ -25,14 +32,14 @@ hermes update
运行 `hermes update` 时,将依次执行以下步骤:
1. **更新前快照** — Hermes 在每个 profile 的 `state-snapshots/` 目录中保存指定的状态文件,包括配对数据、cron 任务、`config.yaml`、`.env` 和 `auth.json`。自动快速快照会跳过单个大于 1 GiB 的文件。`updates.pre_update_backup` 可选择 `quick`、`full` 或 `off`。完整归档遵循[备份排除规则](../reference/faq.md#hermes-backup-vs-hermes-profile-export)。恢复方法见[快照与回滚](../user-guide/checkpoints-and-rollback.md)。快速快照恢复的是状态文件,不是应用程序代码。
2. **Git pull** — 从 `main` 分支拉取最新代码并更新子模块
2. **代码更新** — 检出所选渠道的目标(默认最新 stable 版本)并更新子模块
3. **依赖安装** — 运行 `python -m pm.cli install` 以获取新增或变更的依赖项
4. **配置迁移** — 检测自当前版本以来新增的配置选项并提示设置
5. **Gateway 自动重启** — 更新完成后刷新正在运行的 gateway,使新代码立即生效。由服务管理的 gateway(Linux 上的 systemd、macOS 上的 launchd)通过服务管理器重启;手动启动的 gateway 在 Hermes 能将运行中的 PID 映射回某个 profile 时会自动重新启动。
### 仅预览:`hermes update --check`
想在拉取前确认是否有更新?运行 `hermes update --check` — 它会获取并与 `origin/main` 比较提交。不修改任何文件,不重启 gateway。适合在以"是否有更新"为条件的脚本和 cron 任务中使用。
想在拉取前确认是否有更新?运行 `hermes update --check` — 它会与所选渠道的目标(默认最新 stable 版本,main 渠道为 `origin/main`)比较。不修改任何文件,不重启 gateway。适合在以"是否有更新"为条件的脚本和 cron 任务中使用。
### 完整更新前备份:`--backup`