Document how to convert a Git repo into a Jujutsu repo

[sbroglie]

Description

I was just in the situation to convert an existing Git repo into a Jujutsu repo. However, I struggled to find how I should do that.

$ cd path/to/git-repo
$ ls
.git/
foo.txt
...
$ jj ????

jj git --help, jj git init --help failed to give any suitable hints. I've found the --git-repo argument but its description looked more like what to use when the repo directory does not contain the .git/ folder, i.e. the .git/ folder is somewhere else on the filesystem. At one point I briefly considered jj git clone and clone the repo to convert it since this is found everywhere when looking for "using Jujutsu with Git".

Since in this case the Git repo in question was a disposable sandbox repo, where data loss was irrelevant, I decided to try my luck with jj git init.

$ jj git init
Done importing changes from the underlying Git repo.
Initialized repo in "."
Hint: Running `git clean -xdf` will remove `.jj/`!

I believe this worked, though I've only tested basic functionality. Is that the intended way of achieving this or should jj git init --git-repo=. be used?

Expected Behavior

I wish Jujutsu would be more clear how to convert an existing Git repo to a (colocated) Jujutsu repo.
A hint somewhere in jj git init --help, e.g. a sentence like

If the destination directory already contains a .git/ folder, then Jujutsu uses it as the backing git repo for the newly created jj repo, effectively converting the Git repo into a colocated Jujutsu repo.

or

If the destination directory already contains a .git/ folder, then use --git-repo=$DESTINATION to convert it into a colocated Jujutsu repo.

or

--git-repo
[....]
Pass $DESTINATION to convert an existing Git repo into a colocated Jujutsu repo.

whatever is the correct way of doing this. (Feel free to use these sentences as you wish.)

I've also looked through the documentation on https://www.jj-vcs.dev but couldn't find there anything either.
So additionally, it could be mentioned there, e.g. under FAQ and possibly also under the Tutorial

For the FAQ:

Q: How to convert an existing Git repo into a Jujutsu repo?
A1: Run jj git WHATEVER IS CORRECT /path/to/git/repo.
(could potentially elaborate that .git/ is not part of the path)

For the Tutorial:

(after jj git clone code block)

Alternatively, you can convert an existing Git repository into a Jujutsu repository by running

$ cd path/to/my-git-repo
$ jj git WHATEVER IS CORRECT

[josephlou5]

To answer the immediate question: Yes, jj git init is the proper command to initialize a jj repo in an existing Git repo. The simplest thing to do would be cd path/to/git-repo where path/to/git-repo/.git/ exists, then run jj git init without any arguments.

See this existing FAQ entry, which is under the "Git compatibility" page rather than FAQ (so perhaps a bit hard to find): https://docs.jj-vcs.dev/latest/git-compatibility/#creating-a-repo-backed-by-an-existing-git-repo:

Creating a repo backed by an existing Git repo

To create a Jujutsu repo backed by a Git repo you already have on disk, use jj git init --git-repo=<path to Git repo> <name>. The repo will work similar to a Git worktree, meaning that the working copies files and the record of the working-copy commit will be separate, but the commits will be accessible in both repos.

(I got to this page through the help for jj git init, which links to the "colocation docs".)

I think it couldn't hurt to make this more obvious as you suggested. I like your proposed addition to the tutorial.

---

jj git --help, jj git init --help failed to give any suitable hints. I've found the --git-repo argument but its description looked more like what to use when the repo directory does not contain the .git/ folder, i.e. the .git/ folder is somewhere else on the filesystem.

I think the explanation on --git-repo makes it clear that: (1) it should point to an existing Git repository, which will be used as the backing repo for the jj repo, and (2) the given directory path can contain a .git/ folder, meaning .jj/ will exist as a sibling to that, meaning "This is called a colocated workspace." So it seems to follow that if you had path/to/git-repo/.git/, passing --git-dir path/to/git-repo would create a jj repo that is colocated with the existing Git repo.

It's a little unclear though, from the command help, that not providing --git-dir will look for an existing .git/ folder at the destination path (which defaults to the current directory) and use that as needed. Perhaps that's where your confusion came from?

[sbroglie]

Thanks @josephlou5 for the reply and lifting the confusion.

---

See this existing FAQ entry, which is under the "Git compatibility" page rather than FAQ (so perhaps a bit hard to find): https://docs.jj-vcs.dev/latest/git-compatibility/#creating-a-repo-backed-by-an-existing-git-repo:

Creating a repo backed by an existing Git repo

To create a Jujutsu repo backed by a Git repo you already have on disk, use jj git init --git-repo=<path to Git repo> <name>. The repo will work similar to a Git worktree, meaning that the working copies files and the record of the working-copy commit will be separate, but the commits will be accessible in both repos. [emphasis mine]

This description indicates to me that --git-repo should be used if .git/ is not in the repo directory, i.e. the equivalent of adding an additional workspace to a git repo. It does not indicate to me that I can use it to convert an existing Git repo into an colocated Jujutsu repo.

See this existing FAQ entry, which is under the "Git compatibility" page rather than FAQ (so perhaps a bit hard to find): https://docs.jj-vcs.dev/latest/git-compatibility/#creating-a-repo-backed-by-an-existing-git-repo: [...]
I think it couldn't hurt to make this more obvious as you suggested.

I admit that I've not found this. I skimmed/jumped through the page found "supported features", "disadvantages of colocation" , and "UTF-8 conflicts" and concluded that there was nothing there. Personally, I expect the 2nd (Creating an empty repo) to 4th subsection (Creating a repo by cloning a Git repo) to be part of the FAQ; of course with one answer expanded/added on how to convert an existing Git repo to a Jujutsu repo. ;-)

---

jj git --help, jj git init --help failed to give any suitable hints. I've found the --git-repo argument but its description looked more like what to use when the repo directory does not contain the .git/ folder, i.e. the .git/ folder is somewhere else on the filesystem.

I think the explanation on --git-repo makes it clear that: (1) it should point to an existing Git repository, which will be used as the backing repo for the jj repo, and (2) the given directory path can contain a .git/ folder, meaning .jj/ will exist as a sibling to that, meaning "This is called a colocated workspace." So it seems to follow that if you had path/to/git-repo/.git/, passing --git-dir path/to/git-repo would create a jj repo that is colocated with the existing Git repo.

I found this description confusing for many reasons:

• The phrasing uses "jj repo path" and not some derivation of "destination" as other parts of jj git init --help do.

• The quoted second paragraph states a definition for the term "colocated workspace" in terms of .git and .jj but does not state that this command will fulfill that prerequisite.

• This definition of colocation is only under the --git-repo option and not under the --colocate option, indicating to me that --colocate colocation is different to the --git-repo colocation.

• It uses the term colocated workspace while I was looking for a colocated repository. I admit that this one is probably on me for not getting the terms right, however, the phrasing of --colocate "Colocate the Jujutsu repo" is another hint that this might not be the colocate I'm looking for.

  In my (admittedly slightly Git primed) mind workspace has the connotation of a checkout/worktree outside of the repo.

• The third paragraph clearly states what will happen if the option is passed:

  This option [--git-repo] [...] turns colocation off.

  So using --git-dir does not fulfill the criteria of the definition given before and to me this was not what I was looking for.

---

It's a little unclear though, from the command help, that not providing --git-dir will look for an existing .git/ folder at the destination path (which defaults to the current directory) and use that as needed. Perhaps that's where your confusion came from?

It added to it because I couldn't find what would happen if there is already a .git directory in the destination path. It would be nice to document this behavior somewhere.

---

Thinking about it know, we could provide the definition for a colocated repository/workspace in the introductory text (I've mashed up wordings of --ccolocate, --git-repo and https://docs.jj-vcs.dev/latest/git-compatibility/#colocated-jujutsugit-repos):

jj git init

Create a new Git backed repo

A colocated Jujutsu workspace/repository is a Jujutsu workspace/repository that is also a Git workspace/repository, i.e. both .jj and .git directories are at the top-level of the workspace/repository.
This allows to use both jj and git commands in the same workspace/repository.

If the destination directory already contains a .git/ folder, then Jujutsu creates a new jj repo backed by the existing git repo, effectively converting the Git repo into a colocated Jujutsu repo.

[...]

--git-repo <GIT_REPO> — Specifies a path to an existing git repository to be used as the backing git repo for the newly created jj repo.
This option is mutually exclusive with --colocate.
If <GIT_REPO> is $destination, then this converts the existing repo into a colocated workspace/repository, otherwise it turns colocation off.

I'm sure the phrasing of the definition given by me needs some polishing.

[josephlou5]

Thanks for the detailed explanation! Please see #9851 to see if that makes more sense to you.

• The third paragraph clearly states what will happen if the option is passed:

  This option [--git-repo] [...] turns colocation off.

  So using --git-dir does not fulfill the criteria of the definition given before and to me this was not what I was looking for.

Indeed, you're right! That's pretty interesting. So it seems the intended behavior is that jj git init will colocate with an existing .git/ (since the git.colocate setting defaults to true), but --git-dir=. will make it non-colocated (it will move the .git/ to .jj/repo/store/git/?). That's a little unexpected to me; I would imagine --git-dir should respect the colocation setting (or a given flag).

• It uses the term colocated workspace while I was looking for a colocated repository. I admit that this one is probably on me for not getting the terms right, however, the phrasing of --colocate "Colocate the Jujutsu repo" is another hint that this might not be the colocate I'm looking for.
  In my (admittedly slightly Git primed) mind workspace has the connotation of a checkout/worktree outside of the repo.

I'm not the best person to explain this, but IIUC all "jj repos" are made up of "jj workspaces", where a default workspace is created whenever you initialize a jj repo (from jj git init or jj git clone) (run jj workspace list). I believe only the default workspace can contain the .jj/ folder (or at least, colocated non-default workspaces is currently not supported; #8052), so it does seem to be a little confusing to me that the wording "colocated workspace" is used. Maybe it's just outdated? Most of this seems to have been written in 2024. I could be wrong about all of this though (I don't use multiple workspaces so this is only what I've heard as a bystander).

[sbroglie]

Thanks for the detailed explanation! Please see #9851 to see if that makes more sense to you.

Thanks, I'll comment here.

• The third paragraph clearly states what will happen if the option is passed:

  This option [--git-repo] [...] turns colocation off.

  So using --git-dir does not fulfill the criteria of the definition given before and to me this was not what I was looking for.

Indeed, you're right! That's pretty interesting. So it seems the intended behavior is that jj git init will colocate with an existing .git/ (since the git.colocate setting defaults to true), but --git-dir=. will make it non-colocated (it will move the .git/ to .jj/repo/store/git/?). That's a little unexpected to me; I would imagine --git-dir should respect the colocation setting (or a given flag).

I don't know, I just read and repeated what it states.

But you made me curious enough, so I ran some tests. All commands are execute in path/to/git/repo without a Jujutsu repo:

Command	Result
jj git init --git-repo=.	Both .jj and .git in top-level dir
jj git init --git-repo=. --no-colocate	Both .jj and .git in top-level dir
jj --config git.colocate=false git init --git-repo=.	Both .jj and .git in top-level dir
jj --config git.colocate=false git init	Error: Did not create a jj repo because there is an existing Git repo in this directory.

I used the phrase with .jj and .git directories since I don't know whether "colocated" implies more than .jj and .git repo in the same dir, e.g. some internal repo property is set to true/false or the git repo is internally accessed in a different way.

The result of the second and third test are surprising to me in particular because the fourth test errors out. In these tests the user explicitly asks for a non-colocated repo but maybe got a colocated one anyway.

• It uses the term colocated workspace while I was looking for a colocated repository. I admit that this one is probably on me for not getting the terms right, however, the phrasing of --colocate "Colocate the Jujutsu repo" is another hint that this might not be the colocate I'm looking for.
  In my (admittedly slightly Git primed) mind workspace has the connotation of a checkout/worktree outside of the repo.

I'm not the best person to explain this, but IIUC all "jj repos" are made up of "jj workspaces", where a default workspace is created whenever you initialize a jj repo (from jj git init or jj git clone) (run jj workspace list). I believe only the default workspace can contain the .jj/ folder (or at least, colocated non-default workspaces is currently not supported; #8052), so it does seem to be a little confusing to me that the wording "colocated workspace" is used. Maybe it's just outdated? Most of this seems to have been written in 2024. I could be wrong about all of this though (I don't use multiple workspaces so this is only what I've heard as a bystander).

Thanks for explaining this. So workspaces are indeed very similar/the same as git workspaces and usually "external" to the jj repo. About the colocated workspace vs colocated repo, here I'm even more unknowing than you. Maybe someone knowledgeable in that area could chip in.

[josephlou5]

But you made me curious enough, so I ran some tests.

Thanks for the summary. I tried something similar and was also surprised lol.

My understanding, without reading code (which probably would have made this easier), is:

• If you provide --git-repo:
  • If it's the same as the destination (e.g., --git-repo=.), then the jj repo is always colocated. That is, jj will never move a .git/ folder.
  • If it's not the same as the destination (e.g., --git-repo=path/to/another/repo), then the jj repo will not be colocated (.jj/repo/store/git_target will reference the Git repo path). (I don't know if passing --colocate will cause an error.) Again, jj will never move a .git/ folder, so all it can do is create a jj repo that references the Git repo.
• If you don't provide --git-repo:
  • Then jj git init will respect --colocate/--no-colocate, and if not given, then it will respect the git.colocate setting.
  • But if you try to say "don't colocate" and there's an existing .git/, then there's an error. This is because, as always, jj will not move the existing .git/ folder (to .jj/repo/store/git/) to make the jj repo colocated.

I think that matches the behavior you saw. In the second and third cases, you provided --git-repo, so colocation flags and settings are ignored, since jj won't move the existing .git/ folder. But in the fourth case, you didn't provide --git-repo, so jj looked for an existing one, found one, saw that you asked for no colocation, and then returned an error.

Hopefully I got this right and it makes sense.

(Note that my new understanding here conflicts with my previous thoughts above, which seem to be incorrect. Apologies for any confusion.)

[sbroglie]

• If you provide --git-repo:
  • [...]
  • [...] If it's not the same as the destination (e.g., --git-repo=path/to/another/repo), then the jj repo will be colocated

I guess this should read "not colocated"

---

I'm still treading carefully here: To make things clear: "colocated" is defined as .jj/ and .git/ in the same directory. There are no other hidden/internal state/property involved, e.g. slightly different file contents in .jj/repo/store. In particular there is no repo property like core.bare of Git.

---

Thinking about, if --colocate and --git-repo are mutually exclusive, maybe --no-colocate and --git-repo should be, too? Or at least it should error out, if the result would be colocated.

[josephlou5]

• If you provide --git-repo:
  • [...]
  • [...] If it's not the same as the destination (e.g., --git-repo=path/to/another/repo), then the jj repo will be colocated

I guess this should read "not colocated"

Yes, thanks, updated.

I'm still tread carefully here: To make things clear: "colocated" is defined as .jj/ and .git/ in the same directory. There are no other hidden/internal state/property involved, e.g. slightly different file contents in .jj/repo/store. In particular there is no repo property like core.bare of Git.

AFAIK, that's mostly correct. There is the small thing that a non-colocated jj repo does not share its working copy with Git (git --git-dir="$(jj git root)" status returns an error), but I don't know more than that. (I only learned this by reading the coloration docs while reviewing that PR lol.)

[sbroglie]

I'm still tread carefully here: To make things clear: "colocated" is defined as .jj/ and .git/ in the same directory. There are no other hidden/internal state/property involved, e.g. slightly different file contents in .jj/repo/store. In particular there is no repo property like core.bare of Git.

AFAIK, that's mostly correct. There is the small thing that a non-colocated jj repo does not share its working copy with Git (git --git-dir="$(jj git root)" status returns an error), but I don't know more than that. (I only learned this by reading the coloration docs while reviewing that PR lol.)

So there is a difference between jj git init --colocate and jj git init --git-repo=. and jj git init --git-repo=. --no-colocate (all run in a path/to/git-repo)?

[josephlou5]

So there is a difference between jj git init --colocate and jj git init --git-repo=. and jj git init --git-repo=. --no-colocate (all run in a path/to/git-repo)?

No, there's no difference. When --git-repo is provided, the colocate flags are ignored (except for an error at flag parsing time that --git-repo cannot be given with --colocate). That means the second example is equivalent to the third command, and since there's an existing .git/ then they're both equivalent to the first command. Just tested this:

$ ls -a
./  ../  .git/
$ jj git init --git-repo=. --no-colocate
Initialized repo in "."
$ ls -a
./  ../  .git/  .jj/
$ rm -rf .jj/
$ jj git init --no-colocate
Error: Did not create a jj repo because there is an existing Git repo in this directory.
Hint: To create a repo backed by the existing Git repo, run `jj git init --colocate` instead.