docs(jj): clarify deploys are commit-based, not tag/bookmark

4c0bfe361d149739b2a0797b7612526a7b784095
humdrum <me@humdrum.me> · 2026-07-08 08:27

parent cb249bf9

docs(jj): clarify deploys are commit-based, not tag/bookmark

JUJUTSU.md covered releases (tag gap / bookmark mode) but never mentioned
deploys, leaving a jj user to wonder whether preview/promote also need a
source mode. They don't: custard preview/promote deploy the newest
non-empty pushed commit regardless of tags/bookmarks, and jj's empty
working-copy commit is skipped automatically. Add a short section saying
so and noting the only requirement is to push first.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed

docs/JUJUTSU.md +17 −0

@@ -118,6 +118,23 @@ brew install <name>
 brew upgrade <name>
 ```
 
+## Deploys don't use tags or bookmarks
+
+The tag/bookmark question above is a **release** (Homebrew) concern only. `custard preview` and
+`custard promote` don't care about tags or bookmarks — they deploy the **newest non-empty, pushed
+commit** (a clean `git archive` of it). So `brew.source` mode is irrelevant to deploying, and there's
+nothing extra to configure for jj.
+
+jj works transparently here: the empty working-copy commit sitting on top after a push is skipped
+automatically, so custard deploys the real commit under it (`@-`). The only requirement is the usual
+one — **push first**, because custard archives the pushed commit, not your working copy:
+
+```sh
+jj git push --bookmark main     # or whatever bookmark tracks your trunk
+custard preview                 # deploys the newest non-empty pushed commit → URL
+custard promote                 # promotes that preview → production
+```
+
 ## How each jj operation shows up in custard
 
 | jj operation | Effect in custard |