How jj git clone works

In short: jj turns the source into an absolute URL and picks a destination directory, which must be missing or empty. It creates a colocated workspace (a .git next to .jj) unless colocation is turned off. Then it adds the remote origin (one operation) and fetches the requested branches and tags (another), asking Git for the remote's default branch. It tracks that branch locally, writes trunk() and any fetch patterns to the repo config, and finally checks out a new empty commit on top of the working branch (a fourth operation).

The command is cmd_git_clone. Most of the fetching is the same library code as jj git fetch; this page covers what differs. The workspace and repo it creates are described on the working copy and operations pages.

1. Command-line surface

GitCloneArgs

Without a destination, the name is taken from the source: a trailing .git and then a trailing / are stripped, and whatever follows the last /, \ or : is used (clone_destination_for_source). So https://example.com/org/repo.git clones into repo.

2. Configuration

Settings are read for the new workspace's path, so conditional config scoped to the destination applies (source). After a successful clone jj may write a repo config file with revset-aliases."trunk()" and, if --branch or --tag were given, remotes.<name>.fetch-bookmarks/fetch-tags; the patterns are joined with |, and an empty list becomes ~* (matches nothing). If none of these apply, no repo config file is written (write_repo_presets, join_string_expressions).

3. End-to-end flow

1. Pre-checks. --at-op is refused because there is no repo yet. The source goes through absolute_git_url, which lets gix parse it as a URL, an scp-like address or a local path and canonicalizes it against the current directory; that is why a later jj git fetch works even if the source was a relative path. The destination must not exist or must be an empty directory (source).
2. Options. Colocation is !--no-colocate when git.colocate is true, otherwise --colocate. If either --branch or --tag is given, the other one defaults to "nothing" rather than "everything", so --branch main fetches no tags (source).
3. Workspace. init_workspace uses the settings for the new path and calls Workspace::init_colocated_git or init_internal_git (a bare Git repo in .jj/repo/store/git). Initialization commits the first operation, which checks out the root commit in workspace default (source). In a colocated workspace, .jj/.gitignore is written with /* so Git ignores .jj (maybe_add_gitignore).
4. Remote. git::add_remote writes the remote with fetch refspec +refs/heads/*:refs/remotes/<name>/* into the Git config (default_fetch_refspec) and registers the remote in the view. The workspace is then reloaded so the store's Git handle sees the new remote (source).
5. Fetch. Prints Fetching into new repo in "…", then runs the same GitFetch as jj git fetch, with --depth passed through and synthetic predecessors turned off because there may be many new commits. It asks Git for the remote's default branch with git remote show (get_default_branch, spawn_remote_show) (source).
6. Working branch and tracking. See §6. Then the import stats are printed and the transaction finishes (source).
7. Presets and checkout. trunk() is set to <default>@<remote> only when the working branch is the default branch. If the working branch's remote bookmark is a single commit, a last transaction checks it out (source).

4. Core architecture touchpoints

• Workspace and repo creation: Workspace::init_with_factories creates .jj, the repo directory and its stores, then the working copy. If it fails, it removes .jj itself.
• Git backend: the commit store is a Git repo, colocated or internal; see the commits page.
• View: the fetch imports <name>@<remote> remote bookmarks and tags, and track_remote_bookmark creates the local bookmark; see the view page and jj bookmark track.
• Working copy: check_out creates a new empty commit on the working branch and the working copy is updated to it, which is where Added N files comes from.
• Config: the repo-level config file is created only if there is something to write.

5. Transaction and operation

A successful clone writes four operations, in this order (test, where the newest entry, new empty commit, comes from a later jj new):

The last one is skipped when there is no working branch, for example when cloning an empty repo. In that case the fetch transaction has nothing to record and prints Nothing changed. (test). The repo config is written between the third and fourth operations and is not part of any operation, so jj undo doesn't remove it.

6. Algorithm and invariants

Choosing the working branch

Only exact names count: a glob like push-* limits what is fetched but never selects the working branch. When --branch names a branch other than the default, jj checks it out but neither tracks it automatically nor sets trunk() (source, source). Other fetched branches are tracked only if auto-track-bookmarks matches them, exactly as in jj git fetch.

Clean-up on failure

Everything from creating the workspace to the end of the fetch runs in one block. If it fails, jj removes .jj, .git too if colocated, and the destination directory if it didn't exist before. A failure to clean up is only a warning: Failed to clean up … (source). Errors in the later steps (writing the config, the checkout) leave the clone in place.

Invariants: clone never writes into a non-empty directory. A successful clone has exactly one remote and, if anything was fetched, a working-copy commit whose parent is the working branch's commit. trunk() is only pinned to the remote's default branch.

7. Errors and edge cases

Tags have no equivalent of the missing-branch warning: an upstream TODO notes it would need adding if tag patterns gain it (source).

8. Worked example

From upstream's test_git_clone_remote_default_bookmark. The source repo has main (its HEAD) and feature1, both at one commit. With remotes.origin.auto-track-bookmarks = '~*' (track nothing automatically), jj git clone source clone2 imports both remote bookmarks but tracks only the default branch main, sets trunk() to main@origin, and checks out a new commit on top:

Upstream's output (source):

Fetching into new repo in "$TEST_ENV/clone2"
bookmark: feature1@origin [new] untracked
bookmark: main@origin     [new] tracked
Setting the revset alias `trunk()` to `main@origin`.
Working copy  (@) now at: rzvqmyuk 27e56779 (empty) (no description set)
Parent commit (@-)      : qomsplrm ebeb70d8 feature1@origin main | message
Added 1 files, modified 0 files, removed 0 files

In the same test, moving the source's HEAD to feature1 makes the next clone track feature1 and set trunk() to feature1@origin. With git.track-default-bookmark-on-clone=false, both stay untracked, but trunk() is still set and the checkout still happens (source).