Using Moru
Changes
How change IDs work, how to propose your own work as a change, and how revisions and diffs work.
A change is a proposed piece of work on its way into a branch. Agents’ work arrives as changes, and so does yours when you propose a branch. Each change has a stable ID and a list of revisions, and it’s reviewed and merged as a whole.
The Changes tab#
A repository’s Changes tab lists its changes: Open, Merged or Closed, and by origin: All, For a request or Standalone (proposed without a request). Conflicts shows only the changes that no longer apply to their target. Search matches titles and change IDs.
An open change is in one of these states:
- Open: waiting for review.
- Approved: a person approved its latest revision.
- Conflicted: merging it failed because it conflicts with its target branch. A new revision makes it Open again.
- Proposed: sent to GitHub as a pull request, for a repository that follows GitHub.
Change IDs#
A change ID is 32 letters from k to z, such as kzvpqrstuwxyzkzvpqrstuwxyzkzvpqr. Lists
show its first eight letters, with the shortest part that’s unique in the repository
highlighted; hover for the whole ID. Where it comes from:
- From jj. jj (since version 0.30) writes each commit’s
change ID into a
change-idheader in the git commit. Moru reads it, so the change on Moru has the same ID as the change in yourjj log, and pushing a new version of it adds a revision to the same change. - Assigned by Moru. A commit made with plain git has no such header. Moru assigns an ID and records it in the change, without touching your commit.
The change page says which it was, under the list of revisions.
When Moru merges a change and has to rebase it onto the target branch, the rewritten commit
gets a change-id header with the change’s ID, so jj still sees the same change after the
merge.
Propose a branch#
The everyday way to get your own work reviewed: push a branch, then propose it.
git switch -c timezones
# ...commit your work...
git push -u origin timezones After the push, the repository’s Overview shows a banner with Propose this branch for
the branches you pushed most recently. Dismiss the ones you don’t mean to propose. The branch’s
own page on the Code tab has the same button, and the command menu (⌘K or Ctrl+K) has Propose a change.
On Propose a branch:
- Branch: the branch to propose.
- Title and Description start from the tip commit’s message. Edit them as you like.
- For a request links the change to one of the repository’s open requests, through an attempt assigned to you. Leave it on None for a standalone change.
- With a request, Pre-review can have a reviewer agent score each revision against the request’s acceptance criteria. It only advises, and it never pushes to your branch.
- Click Propose.
The change targets the branch its request merges into, or the repository’s default branch when it isn’t for a request. Its first revision is the branch’s tip, and its ID is the tip commit’s jj change ID if it has one, otherwise a new one.
The change tracks the branch: from now on, every push to the branch adds a revision. A force push is fine too: it’s just another revision, and earlier revisions stay available. A branch carries one open change at a time, so proposing it again goes to the same change.
Push to refs/for#
To propose a commit without making a branch, push it to refs/for/<branch>, where <branch> is the branch it should be merged into:
git push origin HEAD:refs/for/main The node turns the pushed commit, with everything under it down to main, into a change and
then deletes the ref, so nothing is left behind. The title and description come from the
commit message. Find the new change on the Changes tab.
To add a revision to that change later, push to refs/for/<branch>/<change-id>:
git commit --amend
git push origin HEAD:refs/for/main/kzvpqrstuwxyzkzvpqrstuwxyzkzvpqr The change page shows this command, with the right ID, under Update this change. With
jj you don’t need the ID: the commit carries it, so pushing to refs/for/main again revises
the same change.
People with write access to the repository may propose changes and push revisions. On a repository that follows GitHub, neither works: open a pull request on GitHub instead.
Revisions#
Every change has one or more revisions, r1, r2 and so on. The list on the left of the change page shows each one with its author, its commit, when it arrived, and a shield if its attestation verified.
Revisions come from:
- a push to the branch the change tracks, or to
refs/for/<branch>/<change-id>; - an agent submitting work, for an agent’s change;
- Revise with an agent, which has an agent address the open comments and submit the next revision (see Requests).
Each revision’s commit stays reachable under refs/moru/changes/<change-id>/r<N>, even after
a force push or after the branch is deleted.
Diffs#
The diff shows the selected revision against its base, the point on the target branch it
started from. To see only what changed between two revisions, choose an earlier one in compared with above the diff. Press [ and ] to step through the revisions.
Line numbers in the diff are links: click one, or shift-click for a range, and share the URL. To comment on lines, see Reviewing and merging.
When a change no longer applies#
While a change is open, other work keeps landing on its target branch. Moru checks every open change again whenever its target moves and whenever the change gets a new revision. The check asks one thing: would the latest revision still merge into the branch as it is now?
A change that’s behind the branch but still merges cleanly is fine. Nothing is shown and
nothing needs doing: merging rebases it. Only a change that no longer applies gets a Conflicts with main badge, on its page and in the change list. On the change page,
click the badge to see the files that conflict and the commit of main it was checked
against.
What happens next depends on where the change came from:
- An agent’s change with revise rounds left. The agent rebases it on its own, as one more round. See Revise rounds.
- A change made for a request. Fix with an agent starts Revise with an agent on it. The agent rebases onto the branch first, keeping what both sides meant, then works through the open threads as usual. Any agent asked to revise a conflicting change does this, however it was started.
- Any other change. Rebase it yourself and push a new revision. The badge goes away once a revision applies again.
If your change starts to conflict while it waits for review, you get a notification once no agent is fixing it (none was asked, or the one that was failed or was stopped): “Your change conflicts with its target”. If an agent’s revise rounds gave up on it, the notification that its attempt ended tells whoever started it; if that’s not you, you get the conflict notice. A change that already conflicts the first time Moru checks it, for example right after an upgrade, shows the badge without a notification.
The check combines all of a revision’s commits into one merge, while merging replays them one at a time. So now and then a change with no badge still conflicts when you merge it. It’s then marked Conflicted, as before.
A change marked Conflicted goes back to Open when it gets a new revision. Its approval doesn’t carry over: the rebase changed the code, so someone has to approve the new revision before it can be merged.
After merging#
A merged change says where it went: “Merged into main as” and the new commit. If it tracked
a branch, the change offers Delete branch, unless the branch is protected. Nothing is
deleted without you asking.
If you delete a tracked branch before merging, the change stays, marked branch deleted. Its revisions are still there, and it can still be merged.
The change’s history#
At the bottom of the change page, History lists every edit to the change: created, a
revision added, provenance recorded, a status set, merged. Each one is a signed commit in refs/moru/objects/change/<change-id>, so the history travels with the repository.