How jj git push works

In short: jj picks the remotes. For each one, it collects ref updates from the flags, or by default from the revsets.git-push revset (remote_bookmarks(remote=…)..@). --change and --named first create local bookmarks. Each candidate ref is classified against its tracked remote ref: no change, conflicted, untracked, or an update. Every commit between the remote's known heads and the new targets is validated: it needs a description, an author and committer, no conflicts, and it can't be private. If git.sign-on-push is set, your unsigned mutable commits are signed and recorded as their own operation first. jj prints Changes to push to <remote>:, runs git push --porcelain --no-verify --force-with-lease=…, updates the pushed remote refs, and records push … to git remote ….

The command is cmd_git_push. The decision for each ref is classify_ref_push_action in jj-lib. The push itself is push_refs. Remote bookmarks and their tracking state live in the view (view page). The inverse command is jj git fetch.

1. Command-line surface

Two clap groups shape the flags. --bookmark, --tag, -r, --change and --named form the "specific" group, and --all and --tracked form a "what" group that conflicts with it (source). The global --no-integrate-operation is rejected with a hint to use --dry-run (source).

GitPushArgs

2. Configuration

3. End-to-end flow

4. Core architecture touchpoints

5. Transaction and operation

• Transaction: one, started right after the remotes are chosen (source). Created bookmarks and updated remote refs go into it.
• Signing: if git.sign-on-push signed anything, the bookmarks --change/--named created are taken out, the transaction is committed as sign commits before push, and a new transaction is started with those bookmarks put back (source). A failed push keeps the signatures but still drops the created bookmarks; if nothing needed signing, there is no extra operation (docs).
• When it is committed: only if every push succeeded or at least one ref was pushed (source). --dry-run and "Nothing changed." return without committing, so bookmarks created by --change are dropped. The source notes that on partial success those bookmarks are kept.
• Operation description: push all bookmarks/tags to …, push all tracked bookmarks/tags to …, push all deleted bookmarks/tags to …, or push bookmark X / push bookmarks X, Y / push tag T followed by to git remote R (or to git remotes R1, R2) (make_updates_term, source).
• Working copy: untouched, unless signing rebased @.
• jj undo restores the old remote-tracking state locally. It doesn't unpush anything from the remote, and it doesn't undo the signatures, which are a separate operation.

6. Algorithm and invariants

Classifying a ref

classify_ref_push_action compares the local target with the remote ref's tracked target, which is absent when the remote ref is untracked:

1. Equal: nothing to push.
2. Local conflicted, or remote conflicted: rejected.
3. Remote present but not tracked: rejected (Non-tracking remote bookmark … exists).
4. Otherwise, Update(before = remote, after = local), where either side may be absent.

The command then gates updates (classify_bookmark_update). Creating an untracked remote ref needs allow_new, and a deletion needs allow_delete. The default and -r paths set neither, so they only update refs already tracked on that remote. That includes a tracked name the remote doesn't have yet, which is created. --bookmark allows creation only for names tracked nowhere (source).

Force-with-lease

Every update is a forced refspec, guarded by a lease on the expected remote value, the before side. An empty lease means "must not exist yet" (push_updates, RefToPush::to_git_lease). Git ignores leases on +-prefixed refspecs, so the refspecs are passed unforced (spawn_push). --no-verify skips Git hooks. If the remote ref moved since the last fetch, Git rejects it and jj reports it under The following references unexpectedly moved on the remote (source). This is how jj avoids overwriting someone else's push without a separate fetch.

Commit validation

validate_commits walks (known remote heads | immutable_heads())..new_heads, where the known heads are the targets of the remote's bookmarks and tags, so a commit already on the remote as a tag isn't re-checked (source). It rejects the first commit that has an empty description, a missing author or committer name or email, a conflict, or that is private. Validated heads are added to the known heads, so later refs don't re-check shared ancestry. Refs named explicitly fail the whole command. Refs picked up by the default revset or -r are skipped with Won't push bookmark … (source).

Invariants: the remote is only changed where its current value equals jj's last recorded one. Untracked remote refs are never overwritten. Conflicted bookmarks are never pushed. The default selection never deletes a remote ref, and never creates one for a name that isn't tracked.

7. Errors and edge cases

8. Worked example

From upstream's test_git_push_current_bookmark. bookmark2@origin is on 38a20473. Locally, bookmark2 and a new my-bookmark are on its child 88ca14a7, which is @. bookmark1 was rewritten to e5ce6d9a on a side branch. Then jj git push uses the default revset remote_bookmarks(remote=origin)..@:

Upstream's snapshot:

$ jj git push
Changes to push to origin:
  bookmark: bookmark2 [move forward from 38a204733702 to 88ca14a7d46f]
  bookmark: my-bookmark [add to 88ca14a7d46f]

my-bookmark is new on the remote, but the setup configures auto-track-bookmarks = '*', so it was already tracked and counts as an update. Later in the same test, after bookmark2 is moved back to its parent, plain jj git push finds nothing (No bookmarks/tags found in revsets.git-push), and jj git push -b bookmark2 pushes [move backward from 88ca14a7d46f to 38a204733702] (source). If someone else had moved the bookmark on the remote, the lease would fail instead, as in test_git_push_forward_unexpectedly_moved.