Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,31 @@ file and cannot be at different versions. The two entries therefore compete for
`bin/gitpic` — install one, not both — and the formula exists for Linux, Intel, CI, and
anyone who wants no app.

**Two cask stanzas the app's updater depends on. Do not drop either.**

`auto_updates true` declares that the artifact updates itself, which is what lets the in-app
installer replace a cask-managed bundle without brew fighting it — the Cask Cookbook defines the
stanza as exactly this case, an app menu with a *Check for Updates…* that really downloads and
installs. It is not "brew stops managing gitpic": current Homebrew reads the version out of
`/Applications/GitPic.app/Contents/Info.plist` and compares *that* against the tap
(`Cask#auto_updates_bundle_outdated?`; `HOMEBREW_UPGRADE_AUTO_UPDATES_CASKS` defaults on), so
`brew upgrade` still upgrades a bundle that is genuinely behind and correctly does nothing once
the app has updated itself. Without the stanza brew compares its own install receipt, which goes
stale the moment the app self-updates, and reinstalls a version already on disk.

`uninstall quit: "dev.gitpic.app"` makes brew quit the app before it swaps the bundle and reopen
it afterwards (`Cask::Upgrade` passes `quit: true` by default). Without it a
`brew upgrade --cask gitpic` typed into a terminal replaces a bundle that is still running. It
does not interfere with the app's own update: brew skips the quit when the app is not running, so
nothing gets opened twice.

The app-side half of this is `SelfUpdate.route` and `Updater`, whose headers carry the full
argument. **The two repositories have to move together** — the app has no Homebrew branch left,
so a cask without these stanzas means brew and the app both trying to own the bundle.

The tap's `update-gitpic.yml` rewrites only the `version`, `sha256` and `url` lines by targeted
`sub!`, so hand-written stanzas survive a release. It does not regenerate the cask.

**How the tap learns about a release.** Two paths, and the second one exists because the
first cannot be trusted alone:

Expand Down
32 changes: 18 additions & 14 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,20 +38,24 @@ appears — and can be turned off — in 系统设置 ▸ 通用 ▸ 登录项
separate settings.

**Update checks** run once a day by default, and can be run on demand from the 通用 pane or the
menu bar. A new version is shown with its release notes, and the button matches how GitPic was
installed: 立即更新 when Homebrew owns this copy, which runs `brew upgrade --cask gitpic`, and
下载并更新 when it does not, which fetches the release's disk image and replaces the bundle.
Either way GitPic quits first (nothing can replace a running bundle) and reopens when the
install finishes.

A downloaded image is verified against the SHA-256 GitHub publishes for that file before
anything is replaced, which is the same check Homebrew makes against a cask — **no checksum, no
install** — and the download, verification and copy all happen before GitPic quits, so a failure
changes nothing. Homebrew stays the installer whenever it owns the bundle: replacing a
cask-managed app behind brew's back would leave its manifest describing a version that is no
longer on disk. The in-app installer needs GitPic to be in `/Applications` or `~/Applications`;
a copy kept elsewhere is sent to the release page, and the sheet says which reason applied. The
terminal equivalent of the check is `gitpic update check`.
menu bar. A new version is shown with its release notes and one 下载并更新 button — whether this
copy came from Homebrew or was installed by hand, GitPic fetches the release's disk image and
replaces the bundle itself. It quits first (nothing can replace a running bundle) and reopens
when the install finishes.

The image is verified against the SHA-256 GitHub publishes for that file before anything is
replaced, which is the same check Homebrew makes against a cask — **no checksum, no install** —
and the download, verification and copy all happen before GitPic quits, so a failure changes
nothing. The installer needs GitPic to be in `/Applications` or `~/Applications`; a copy kept
elsewhere is sent to the release page, and the sheet says which reason applied. The terminal
equivalent of the check is `gitpic update check`.

A Homebrew install can still be upgraded with `brew upgrade --cask gitpic`, or a bare
`brew upgrade`. The cask declares `auto_updates true`, so Homebrew compares the version in
`/Applications/GitPic.app` against the tap rather than its own install receipt: it does nothing
once the app has already updated itself, and upgrades when the bundle is genuinely behind. It also
declares `uninstall quit:`, so a terminal upgrade quits the app before the swap and reopens it
afterwards.

**Nothing needs a terminal to get started.** Open the settings window → 图床 → 「使用
GitHub 登录」: the one-time code appears in the window and the browser opens on its own.
Expand Down
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,18 @@ brew install tarnish233/tap/gitpic # App + 终端命令
macOS 自己的登录项,所以「系统设置 ▸ 通用 ▸ 登录项与扩展」里也能看到、也能关掉,两边永远是同一个开关。

**检查更新**默认每天自动查一次,也可以在「通用」页或菜单栏里随时手动查。发现新版本时会显示这一版
的更新内容,按钮按安装方式给:用 Homebrew 装的是「立即更新」,走 `brew upgrade --cask gitpic`;
手动装的是「下载并更新」,由 GitPic 自己下载该版本的磁盘映像来替换。两种方式都会先退出再替换
(没有办法替换正在运行的 bundle),装完自动重开。

自己下载的映像在替换之前会先核对 GitHub 为该文件公布的 SHA-256 —— 和 Homebrew 校验 cask 是同一件
事,**拿不到校验和就不装**;而且下载、校验、复制全都发生在退出之前,失败什么都不会改动。Homebrew
管着这份 GitPic 时永远走 brew:绕过它替换会让 cask 的 manifest 描述一个已经不在磁盘上的版本。自己
安装要求 GitPic 位于 `/Applications` 或 `~/Applications`,放在别处的副本会被指向发布页,弹窗里会
说明是哪一种原因。终端里等价的查询命令是 `gitpic update check`。
的更新内容,一个「下载并更新」按钮 —— 不管这份 GitPic 是 Homebrew 装的还是手动装的,都由 GitPic
自己下载该版本的磁盘映像来替换。替换前会先退出(没有办法替换正在运行的 bundle),装完自动重开。

替换之前会先核对 GitHub 为该文件公布的 SHA-256 —— 和 Homebrew 校验 cask 是同一件事,**拿不到校验和
就不装**;而且下载、校验、复制全都发生在退出之前,失败什么都不会改动。安装要求 GitPic 位于
`/Applications` 或 `~/Applications`,放在别处的副本会被指向发布页,弹窗里会说明是哪一种原因。终端里
等价的查询命令是 `gitpic update check`。

用 Homebrew 装的照样可以用 `brew upgrade --cask gitpic`(或者不带参数的 `brew upgrade`)。cask 声明了
`auto_updates true`,所以 Homebrew 比对的是 `/Applications/GitPic.app` 里的真实版本而不是它自己的安装
记录:app 已经自己更新到位时它什么都不做,真的落后了才升。它还声明了 `uninstall quit:`,所以终端里
升级会先退出 app、装完再打开它。

**第一次用不需要开终端。** 打开设置窗口 → 图床页 → 「使用 GitHub 登录」,一次性码会显示在窗口里、
浏览器自动打开;授权完成后下面的下拉框会列出你可以上传的仓库,选一个,按右上角「保存」写进配置文件。
Expand Down
17 changes: 7 additions & 10 deletions apps/GitPic/Sources/GitPicApp/AppModel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -1120,7 +1120,6 @@ final class AppModel {
func resolveUpgradePath() async {
if upgradePathGeneration == updateGeneration {
if case .unavailable(_, retryable: false) = upgradePath { return }
if case .homebrew = upgradePath { return }
if case .selfInstall = upgradePath { return }
}
// The old guard also did not hold across the `await`, so two sheet appearances could
Expand Down Expand Up @@ -1155,17 +1154,15 @@ final class AppModel {
}
}

/// Do whichever upgrade was resolved, and quit.
/// Do the upgrade that was resolved, and quit.
///
/// One arm, where there were two. The other handed the install to `brew upgrade --cask gitpic`
/// and could fail *before* the app quit — hence the `catch` that used to be here, setting
/// 「启动升级失败」 while this process was still alive to show it. `performSelfInstall` reports
/// its own failures through `updateFailure` from inside its `Task`, so there is nothing to
/// catch at this level any more.
func performUpgrade() {
switch upgradePath {
case .homebrew(let brew):
do {
try Updater.upgradeAndRelaunch(brew: brew)
} catch {
// The handoff itself failed, so this process is still alive to say so.
updateFailure = "启动升级失败:\(error.localizedDescription)"
Diagnostics.log("update: handoff failed: \(String(describing: error))")
}
case .selfInstall(let asset, let sha, let version):
performSelfInstall(asset: asset, sha256: sha, version: version)
case .unavailable, .none:
Expand Down
35 changes: 15 additions & 20 deletions apps/GitPic/Sources/GitPicApp/UpdateSheet.swift
Original file line number Diff line number Diff line change
@@ -1,17 +1,20 @@
import SwiftUI
import GitPicCore

/// What a new release says, and the two ways to act on it.
/// What a new release says, and what to do about it.
///
/// A sheet rather than a pane, because it is about one moment: a version was found, here is
/// what is in it, do you want it. Raised by a *manual* check, and by 「查看更新内容」 for one
/// the daily check found — never by the daily check itself, which reports through
/// Notification Center instead of interrupting whatever the window was being used for.
///
/// It used to offer two actions, chosen by who installed the app: 「立即更新」 handed a
/// Homebrew-managed copy to `brew upgrade --cask gitpic`, and 「下载并更新」 was for everyone else.
/// There is one action now — see `Updater`'s header for why the split went away.
struct UpdateSheet: View {
@Bindable var model: AppModel
let report: UpdateReport

@State private var confirmingUpgrade = false
@State private var confirmingInstall = false

/// The release notes, parsed once per report rather than once per redraw.
Expand Down Expand Up @@ -114,18 +117,15 @@ struct UpdateSheet: View {
} else {
HStack(spacing: 8) {
switch model.upgradePath {
case .homebrew:
Button("立即更新") { confirmingUpgrade = true }
.buttonStyle(.borderedProminent)
case .selfInstall(let asset, _, _):
Button("下载并更新") { confirmingInstall = true }
.buttonStyle(.borderedProminent)
Text(Self.size(asset.size))
.font(.caption).foregroundStyle(.secondary)
case .unavailable, .none:
// No button at all rather than a disabled one: neither path can work
// No button at all rather than a disabled one: the install cannot work
// here, and a greyed-out control with a tooltip is a worse answer than
// the one route that does.
// the reason printed below it.
EmptyView()
}
Button("打开发布页") {
Expand Down Expand Up @@ -156,26 +156,21 @@ struct UpdateSheet: View {
}
}
.padding(16)
.alert("升级前需要退出 GitPic", isPresented: $confirmingUpgrade) {
Button("退出并升级") { model.performUpgrade() }
Button("取消", role: .cancel) {}
} message: {
// Says exactly what is about to happen, because all of it is visible and some
// of it is alarming: the window closes, the menu-bar icon disappears for the
// length of a download, and the app comes back on its own.
Text("Homebrew 不能替换正在运行的 App,所以 GitPic 会先退出,"
+ "升级完成后自动重新打开。这期间菜单栏图标会消失。\n\n"
+ "升级过程记录在 GitPic-update.log 里;万一失败,原来的版本仍然可用。")
}
.alert("下载并安装 GitPic \(report.latest)", isPresented: $confirmingInstall) {
Button("下载并安装") { model.performUpgrade() }
Button("取消", role: .cancel) {}
} message: {
// The order matters and is stated, because it is what makes this safe: everything
// that can go wrong happens while the window is still here.
Text("这份 GitPic 不是 Homebrew 装的,所以由 GitPic 自己安装更新。\n\n"
+ "会先下载并校验,全部通过之后才退出并替换,完成后自动重新打开——"
//
// It no longer opens by saying 「这份 GitPic 不是 Homebrew 装的,所以由 GitPic 自己
// 安装更新」. That sentence explained a fork that existed — brew-installed copies were
// sent to `brew upgrade` instead — and became false for those users the moment this
// became the only path. Nothing here needs to explain where the app came from; what
// the reader wants to know is what is about to happen to it.
Text("会先下载并校验,全部通过之后才退出并替换,完成后自动重新打开——"
+ "下载或校验失败的话什么都不会改动。\n\n"
+ "替换那一步记录在 GitPic-update.log 里;万一失败,原来的版本仍然可用。\n\n"
+ "校验用的是 GitHub 为这个文件公布的 SHA-256,和 Homebrew 验证 cask 的方式相同。")
}
}
Expand Down
Loading