Using Jujutsu Version Control in Xcode Projects
Last update: January 2026
Jujutsu, also known as jj, is a version control system that is growing in popularity with developers. One reason for its popularity is that it works with git repositories and services like GitHub.
In this article I share what I learned about using Jujutsu in Xcode projects and putting Jujutsu repos on GitHub. The article has two main sections: one on adding Jujutsu to an Xcode project with an existing git repo and one on adding Jujutsu to a project with no git repo.
Disclaimer: I am learning Jujutsu. I am not an expert on it.
I refer to Jujutsu in this article using both Jujutsu and jj.
Adding Jujutsu to an Xcode Project with a Git Repo
To add Jujutsu support to an Xcode project, you must create a jj repository for the project from the Terminal app. In the Terminal navigate to the directory above your Xcode project’s folder. If you are inexperienced with the Terminal, go to the directory above your project folder in the Finder, right-click, and choose Services > New Terminal at Folder. A Terminal window will open with the current directory being the directory above the project folder.
Run the following command to create a jj repo:
jj git init --colocate RepoName
Where RepoName is the name you give to the repo.
Now your Xcode project has two version control repos: a git repo and a jj repo. You can see this for yourself in the Finder by pressing Cmd-Shift-Dot. There will be a .git folder and a .jj folder inside your project folder.
Using the --colocate option tells Jujutsu that the git and jj repos share the same working copy. Xcode will continue to track the changes in your project. If you commit changes using Xcode or another git app like SourceTree, the commits appear in both the git and jj repos.
Putting the Jujutsu Repo on GitHub
If you want your Jujutsu repo on GitHub and have not created a remote GitHub branch for the Xcode project, do so from the Source Control navigator, which you can access by pressing Cmd-2. The following article has detailed instructions on putting an Xcode project on GitHub:
Putting Your Xcode Project on GitHub, Bitbucket, or GitLab
You must push the jj repo to GitHub. You have to do this from the Terminal. Go to your project folder in the Terminal.
Run the following commands to push the local jj repo to GitHub:
jj describe -m "Initial push to GitHub"
jj bookmark set trunk --allow-backwards -r @-
jj git push --allow-new -b trunk
The first command creates a description for a commit. I got an error when I pushed to GitHub without creating a description.
The second command creates a trunk branch for you to push to GitHub. The --allow-backwards option lets you move the bookmark backwards or sideways, which you need the first time you set a bookmark.
The -r option specifies the change (commit) where the bookmark should point. In most cases you should point the bookmark to the most recent change you made. Run the jj status command to check if the working copy is empty.
If the working copy is not empty, point the bookmark to the working copy by passing @ as the change ID. If the working copy is empty, point the bookmark to the working copy’s parent commit by passing @- as the change ID.
The final command pushes the local jj repo to the trunk branch on GitHub. Supply the --allow-new and -b options along with the name of the bookmark. The --allow-new option allows creating new bookmarks, which you need to do the first time you push.
If you don’t supply the -b argument, Jujutsu issues a warning about the working copy commit becoming immutable.
The GitHub repo should have a main branch that contains the project’s git repo and a trunk branch that contains the jj repo.
Adding Jujutsu to an Xcode Project with no Git Repo
To add Jujutsu support to your Xcode project, you must create a jj repo for the project. Go to your project folder in the Terminal and run the following command:
jj git init
Running the command creates a .jj folder in your project folder. You can see this for yourself in the Finder by pressing Cmd-Shift-Dot.
Xcode will not show the changes in your code because the project has a jj repo and no git repo. If you want Xcode to show the changes in your code, you must create a git repo. In Xcode choose Integrate > New Git Repository to add a git repo to your project.
Putting the Jujutsu Repo on GitHub
You must create a repository in GitHub and push your local jj repo to that repo. When you create the repo in GitHub, GitHub provides instructions on how to push an existing repo. The commands in those instructions provide a guide on what you need to run to push your local jj repo to GitHub.
Run the following commands to put your local jj repo on GitHub:
jj git remote add origin https://github.com/GitHubAccount/RepoName.git
jj describe -m "Initial push to GitHub"
jj bookmark set trunk --allow-backwards -r @-
jj git push --allow-new -b trunk
The first command adds a remote branch to your local repo. The branch contains the repo you created on GitHub. Replace GitHubAccount with your GitHub username, and replace RepoName with your repo name.
The second command creates a description for a commit. I got an error when I pushed to GitHub without creating a description.
The third command creates a trunk branch for you to push to GitHub. The --allow-backwards option lets you move the bookmark backwards or sideways, which you need the first time you set a bookmark.
The -r option specifies the change (commit) where the bookmark should point. In most cases you should point the bookmark to the most recent change you made. Run the jj status command to check if the working copy is empty.
If the working copy is not empty, point the bookmark to the working copy by passing @ as the change ID. If the working copy is empty, point the bookmark to the working copy’s parent commit by passing @- as the change ID.
The final command pushes the local jj repo to the trunk branch on GitHub. Supply the --allow-new and -b options along with the name of the bookmark. The --allow-new option allows creating new bookmarks, which you need to do the first time you push.
If you don’t supply the -b argument, Jujutsu issues a warning about the working copy commit becoming immutable.
Further Reading
Looking for a Jujutsu GUI Client?
If so, I’m developing Jjewel, a native Mac app that provides a GUI for Jujutsu. Use Jjewel to perform the most common version control tasks and spend less time entering Terminal commands.
Go to the Jjewel site to learn more about the app and download it.