Reviewing
otisk's review model is one commit per change. You amend it rather than stacking fix-ups on top, and each push of it is kept as a revision, so nothing you pushed is ever lost. Concepts explains why it is shaped that way and how it differs from a pull request; this page is how to use it.
A change
From inside a clone:
echo "a first idea" > idea.md
git add idea.md
otisk change commit -m "Write down an idea"
otisk change push # git push origin HEAD:refs/for/main
otisk: change 1 revision 1 -- Write down an idea
To ssh://git.otisk.dev/yuritomanek/notes.git
* [new reference] HEAD -> refs/changes/1/1
change commit is your own git commit — every argument goes to git, so your
signing, hooks, message template and editor apply — with a Change-Id added if
nothing else supplied one. It stages nothing: what you have staged is what gets
committed.
Revise it, and push again. change revise amends the newest commit, keeping
the Change-Id that makes it the same change, and says which revision pushing
it would make:
echo "a better idea" > idea.md
git add idea.md
otisk change revise # amends it, keeping its Change-Id
otisk change push # revision 2 of the same change
otisk change list # open changes
otisk change show 1 # its revisions, and what each touches
otisk change diff 1 # what changed between revisions 1 and 2
otisk change land 1 # fast-forward main to revision 2
Committing with plain git works too: otisk change hook installs a commit-msg
hook that adds the Change-Id, so git commit and git commit --amend behave
as they do above. The hook is not needed when you commit through the client —
change commit adds the trailer itself — but it costs nothing, and it is what
keeps a git commit made out of habit from being refused at the push.
What change revise adds over git commit --amend is the check git cannot
make: it knows what that Change-Id already means on the host. It refuses a
commit that is not a change yet, and one whose change has landed — the mistake
that otherwise splits your review into two changes, since git commit where
you meant --amend starts a second one and git has no basis to object. When
the host cannot be reached it amends anyway and says the check was skipped.
show says what each revision touches, which is usually the question:
change 1 (open) -> main
Change-Id: I3f2a9c7e1b4d8a60f5c2e9b17d4a8c30e6f1b2d9
r1 b71d4e05c3a9 2026-09-19 10:02 Write down an idea
+ +2 -0 idea.md
r2 8f1c0b2a9d44 2026-09-19 10:14 Write down an idea
M +1 -1 idea.md
The host works that out when a revision is pushed, so it answers from anywhere: you need neither a clone nor the revision fetched to see what a change contains.
The Change-Id trailer is what makes an amended commit the same change, so
keep it when you amend. Landing only ever fast-forwards: if main has moved
on, rebase onto it and push a new revision first.
Several at once
A push may carry several commits, and each one becomes its own change, stacked in order:
git commit -m "Add a lexer" # on top of the change above
otisk change push # both commits, a change each
otisk: change 1: no new changes
otisk: change 2 revision 1 -- Add a lexer
The commits are reported bottom-up: the one already pushed has nothing new, and the one on top became change 2.
Amend any of them and push again, and each change gains a revision; nothing
new means nothing recorded. Land them from the bottom up — a change whose
parent has not landed is refused. If any commit in the push is unusable, for
example because it has no Change-Id, the whole push is refused and nothing
is recorded, naming the commit at fault.
Comments
Comments go on a change, on a file of one of its revisions, or on a line of that file:
otisk change comment 1 --file idea.md --line 1 -m "is this the best idea?"
otisk change comment 1 --file idea.md -m "this whole file could go"
otisk change comment 1 -m "otherwise this looks fine" # about the change
otisk change reply 1 1 -m "probably not, but it is mine" # thread 1
otisk change comments 1
t1 open r2 idea.md:1
yuritomanek 2026-09-18 10:02
is this the best idea?
yuritomanek 2026-09-18 10:05
probably not, but it is mine
A comment names the revision, and the file and line, it was written about, and
stays there when you push a new revision, so it always points at what was
actually read. In the interface, c with a file selected comments on that
file.
Mark one dealt with, or bring it back:
otisk change resolve 1 1
otisk change comments 1 --all # resolved threads too
otisk change reopen 1 1
otisk change show 1 counts the threads still open, and otisk change list
marks changes that have any, so nothing is landed with a question outstanding
unless you mean it.
Comments live in the repository, as a commit per comment on
refs/changes/<number>/meta. They are stored, replicated, and restored exactly
as your code is, and you can read them with git alone:
git fetch origin refs/changes/1/meta:refs/otisk/meta && git log refs/otisk/meta
All of it in one place
Everything above is also a terminal interface:
otisk ui # in a clone; or otisk ui --repo yuritomanek/notes
┌─ 1 yuritomanek/notes — open changes ─────────┐┌─ 3 revisions ────────────────────────────────┐
│> 1 open r2 main (1) Write down an idea ││ change 1 (open) → main │
│ ││ Change-Id: I3f2a9c7e1b4d8a60f5c2e9b17d4a8c3…│
│ ││> r1 b71d4e05c3a9 Write down an idea │
│ ││ r2 8f1c0b2a9d44 Write down an idea │
│ ││ │
└──────────────────────────────────────────────┘└──────────────────────────────────────────────┘
┌─ 2 local work — origin/main..HEAD ───────────┐┌─ 4 comments ─────────────────────────────────┐
│> new change Say why it is worth writing down││> t1 open r2 idea.md:1 │
│ ││ yuritomanek say why, not what │
│ ││ │
│ ││ │
└──────────────────────────────────────────────┘└──────────────────────────────────────────────┘
Four panels: the repository's changes and the commits you have not pushed yet
on the left, the selected change's revisions and conversation on the right.
Moving in the change list changes what the right-hand panels show, so reading
a change never costs you sight of the others. tab moves to the next panel
and 1–4 straight to one — the number each panel wears. The line below
names the panel the keys are in and what it offers, and ? shows every
panel's keys. Each panel scrolls when it holds more than fits, and says on its
border how much is out of sight.
local work is what git log <remote>/<branch>..HEAD holds, which is what
the panel is titled — the branch being the one the selected change targets, or
the repository's default, and fetched first so that landing something
elsewhere takes it off the list. Each commit is labelled with what pushing it
would do: start a new change, add a revision to change N, or nothing, because
it is already the latest revision, has landed, or has no Change-Id. p
pushes them for review, as one series, and what the host answers is what you
then see.
In changes, a lists every change, l lands, x abandons, and c
comments. In revisions, d shows the selected revision's diff and D
compares the last two — both in your pager, through git, returning when you
quit it. In comments, R replies and s resolves or reopens. Colour says
what a change's status is, and which threads are still open.
It does nothing the commands cannot: each keystroke is one of them, over one reused ssh connection, so a refusal reads exactly as it does in the shell.