Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
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
58 changes: 39 additions & 19 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
- `github.rs` — GitHub Contents API client (upload, dedup, health checks).
- `naming.rs`, `link.rs`, `imageproc.rs`, `output.rs`, `error.rs` — path/hash, URL/markdown, compression, human/JSON output, error types.
- `history.rs` — the upload log the app's 历史 pane reads.
- `release.rs` — the update check behind `gitpic update check`: version parsing and comparison, the `releases/latest` fetch, and the release's assets (name, size, download URL, GitHub's `digest`) that the app installs an update from. The feed is a compile-time constant on purpose, pinned by a test — its text is rendered inside GitPic's own window, so nothing configurable may choose its origin, and download URLs come from the API rather than a template for the same reason.
- `release.rs` — the update check behind `gitpic update check`, and the tap lookup behind `gitpic update cask`: version parsing and comparison, the `releases/latest` fetch, the release's assets (name, size, download URL, GitHub's `digest`) that the app installs an update from, and a Contents-API read of the tap's `Casks/gitpic.rb` answering what `brew upgrade --cask gitpic` would install. Both origins are compile-time constants on purpose, pinned by a test — their text is rendered inside GitPic's own window, so nothing configurable may choose them, and download URLs come from the API rather than a template for the same reason.
- `install_source.rs` — which of the five ways this binary was installed (cask app, hand-installed app, `gitpic_cli` formula, `cargo install`, or unknown), so `gitpic update` prints the one upgrade command that install actually wants instead of two to choose between. Canonicalises `current_exe()` first: the cask links `bin/gitpic` into the app bundle, and on Apple platforms the un-canonicalised path is the symlink, which classifies the commonest install of all as neither an app nor a formula. Distinct from `GitPicCore`'s `CaskOwnership`, which asks whether *the bundle* is cask-managed rather than where *this binary* came from.
- `testutil.rs` — `#[cfg(test)]` only: the loopback stub server, a canned response, and the request reader shared by `github`'s and `release`'s tests. One `sock.read` is not a whole request; the module says what that cost twice.
- `commands/` — one module per action (`upload`, `auth_cmd`, `repos`, `branches`, `doctor`, `list`, `config_cmd`, `completion`, `skill`, `update`).

Expand Down Expand Up @@ -50,27 +51,46 @@ 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.
**One cask stanza the app's updater depends on. Do not drop it.**

`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.
`brew upgrade --cask gitpic` typed into a terminal replaces a bundle that is still running. This
is now **load-bearing rather than a courtesy**: the app's update sheet hands that exact command to
every Homebrew user instead of installing anything itself, and GitPic is `.accessory`, so brew's
reopen is the only thing that puts the menu-bar icon back.

**`auto_updates true` is on its way out, and the order matters.** It asserts that the artifact
updates itself, which stopped being true of a cask-managed copy when `SelfUpdate.route` began
deferring to brew for those bundles. Remove it *after* the app that defers is released, never
before: an `auto_updates`-free cask against an older app leaves brew's receipt comparison and the
app's installer both writing `/Applications/GitPic.app`.

Two things about that stanza are worth recording, because both were stated wrongly here before:

- **It never governed the command the app prints.** `brew upgrade --cask gitpic` names the cask
explicitly, and `Cask::Upgrade` takes the `cask.outdated?(greedy: true)` branch for a named
cask (`cask/upgrade.rb:70`), which skips the `auto_updates` comparison entirely and falls
through to plain receipt inequality (`cask/cask.rb:442`). The stanza only ever affected a bare
`brew upgrade` and `brew outdated`.
- `HOMEBREW_UPGRADE_AUTO_UPDATES_CASKS`, which the old text cited as "defaults on", is marked
`odeprecated` with `replacement: "the default behaviour"` (`env_config.rb:745-755`). It was a
knob to point at, and it is going away.

Removing it means brew compares its own receipt again, which is correct once the app no longer
touches a cask-managed bundle. **One transitional hazard, worth a CHANGELOG line rather than
code:** a 0.20.9 cask user who self-updated has a bundle ahead of that receipt, so a bare
`brew upgrade` can reinstall an older tap version over it. The common shape (bundle 0.20.10,
receipt 0.20.9, tap 0.20.10) is one redundant download that repairs the receipt, not a downgrade;
a real downgrade needs the bundle to be ahead of the *tap*, which takes skipping a version in-app
inside the tap's lag window. It closes after one `brew upgrade`. The app itself cannot cause it:
`route` compares the tap against the installed bundle, so it never prints a command that would
move backwards.

The app-side half of this is `SelfUpdate.route`, `CaskOwnership` and `Updater`, whose headers
carry the full argument. **The two repositories still have to move together**, just in the other
direction now: the app defers to brew for a cask-managed bundle, so a cask that drops
`uninstall quit:` means telling people to run a command that replaces a running app.

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.
Expand Down
83 changes: 83 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,89 @@ All notable changes to this project are documented here. The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### A Homebrew install is upgraded by Homebrew, and GitPic says so

- Installed with `brew`? The sheet hands you `brew upgrade --cask gitpic` and installs nothing itself
- When the cask has nothing newer it says so, rather than giving you a command that does nothing
- `gitpic update` prints the one upgrade command your install wants, not two to choose between

<!-- release-notes-end: everything above is shared by the GitHub Release and the in-app update sheet; everything below stays in this file. Keep each bullet above to one line — the sheet renders with .inlineOnlyPreservingWhitespace, so newlines survive and wrapping breaks at 480pt -->

### App

- 0.20.9 made the app install every update itself, a cask-managed bundle included. This reverses
that for Homebrew users — but not by restoring what 0.20.9 deleted. Both of that version's
measured defects came from *running* brew after the app had quit: the vanished menu-bar icon with
no progress and nothing to cancel, and `brew upgrade` exiting **0** with "the latest version is
already installed" while the script logged success and reopened the same build. Nothing is
spawned now and nothing quits. The app prints the command and stays where it is, so neither
failure has anywhere left to happen.
- The version it compares against is the **cask's**, not the release's, and that is the half that
makes it safe to hand a command over at all. Read out of Claude Code 2.1.251's own binary, which
does the same thing: it asks what the cask offers, then prints either "Update available: X → Y"
with the command or "Claude is up to date!" with none. A release exists the moment it is
published while the tap follows by dispatch with a six-hourly cron behind it, so those two facts
genuinely differ — and in that window GitPic now says 「已是 Homebrew 提供的最新版本」 rather than
offering a command that no-ops. The cost is stated rather than papered over: inside the tap's lag
a brew user waits, and the app does not install over a cask-managed bundle to fill the gap.
- Ownership is asked *before* the location rule, which fixes a case that was always broken:
`brew install --cask gitpic --appdir ~/Apps` produces a bundle the app called 「不是 /Applications
或 ~/Applications」 and refused, when `brew upgrade --cask gitpic` was exactly right for it.
- Detection asks about the **bundle**, not the machine. `brew list --cask gitpic` — what 0.20.9
deleted — is true whenever a cask is installed anywhere, so a copy in `~/Applications` beside a
cask in `/Applications` could be told to upgrade the other one. Reading the Caskroom's own
symlink answers about this bundle, works at any `--appdir`, and costs a directory scan instead of
up to 8 s of login shell plus 20 s per prefix.
- The tap lookup is off `GitpicRunner`'s spawn gate and bounded at 10 s. On the gate its worst case
— the CLI's 20 s request plus one anonymous retry — would have sat in front of every upload, on
the sheet-open path, which is the shape 0.20.9 was written to delete. The tap's local clone is
read first and settles the answer for free whenever it already names something newer, so the
common case costs no request at all.
- **Fixed, and it was live since before this change:** the update sheet appended 「或在终端运行
`brew upgrade --cask gitpic`」 to *every* refusal, so a copy running from `~/Downloads` on a
machine with no cask was told to run a command that answers `Error: Cask 'gitpic' is not
installed`. That sentence now appears only for a bundle a cask really owns.

### CLI

- `gitpic update` printed the cask's command and the formula's side by side and left the reader to
pick, which had no answer at all for a hand-installed `GitPic.app`, a `cargo install --git` build
or an unpacked tarball. It now detects the install and prints one command.
- The detection turns on canonicalising `current_exe()`, and the naive version gets the commonest
install wrong. The cask links `HOMEBREW_PREFIX/bin/gitpic` at the copy inside the app bundle, and
on Apple platforms `current_exe()` is `_NSGetExecutablePath` with no canonicalisation — measured:
`/opt/homebrew/bin/gitpic` has no `.app` ancestor while its realpath does. Both answers it would
otherwise fall to are wrong ones, and one of them prints `brew upgrade gitpic_cli`, the exact "no
available formula" failure the two-command note existed to avoid.
- `gitpic` is not on crates.io (verified against the API), so the cargo hint carries `--git`. The
bare spelling would have been a command that cannot work.
- New `gitpic update cask`, which reports what the tap's cask declares. The origin is a
compile-time constant, pinned by the same test as the release feed: what it returns is rendered
in GitPic's own window next to a command the user is being told to run.

### Homebrew

- **`auto_updates true` is being removed from the cask**, after this release ships — never before,
or brew's receipt comparison and an older app's installer both write `/Applications/GitPic.app`.
It asserts that the artifact updates itself, which stops being true of a cask-managed copy now
that the app defers.
- Two claims this file and AGENTS.md made about that stanza were wrong, and are corrected there:
it never governed `brew upgrade --cask gitpic`, because a named cask takes
`outdated?(greedy: true)` (`cask/upgrade.rb:70`) and skips the `auto_updates` comparison
entirely; and `HOMEBREW_UPGRADE_AUTO_UPDATES_CASKS`, cited here as "defaults on", is marked
`odeprecated`.
- **Transitional, one release wide:** a 0.20.9 cask user who self-updated has a bundle ahead of
brew's receipt, so once the stanza is gone a bare `brew upgrade` can reinstall an older tap
version over it. The common shape is one redundant download that repairs the receipt; a real
downgrade needs the bundle ahead of the *tap*, which takes skipping a version in-app inside the
tap's lag. It closes after one `brew upgrade`. The app cannot cause it — it compares the tap
against the installed bundle, so it never prints a command that moves backwards.
- `uninstall quit: "dev.gitpic.app"` stays and is now load-bearing rather than a courtesy: it is
what makes the command the app hands out safe, and for an `.accessory` app brew's reopen is the
only thing that puts the menu-bar icon back.

## [0.20.9] - 2026-08-28

### A Homebrew install updates in one click, without waiting on brew
Expand Down
Loading