Confusing documentation for jj git init

[wmjdgla]

https://martinvonz.github.io/jj/v0.16.0/cli-reference/#jj-git-init
Description of the command:

Create a new Git backed repo
...
<DESTINATION> — The destination directory where the jj repo will be created.

Which seems to indicate that the created repo will be both a git repo and a jj repo, i.e. both git and jj commands will work on it.
But the doc goes on to state:

--colocate — Specifies that the jj repo should also be a valid git repo, allowing the use of both jj and git commands in the same directory

Which begs the question: if I don't specify the --colocate option, or that it's set to false, then the command won't create a valid git repo? What does it even mean to have the command "create a new Git backed repo" but that it's not a valid git repo?

[joyously]

It's a fair question, but the problem is the word "valid", which should probably be something else related to location of the folder.
Since Git expects the .git folder to be in a certain place, putting it under the .jj folder is not "valid" and you can't do Git commands on the repo.

[wmjdgla]

@joyously thanks for clarifying
Perhaps the description of the command can be something like this:

Create a new repo in the given directory. Repo will be backed by Git but will not support the use of git commands by default.

The first sentence mirrors that of jj init for consistency.

Then for the --colocate option:

Specifies that the jj repo should also support the use of git commands.

[joyously]

That sounds better, but does it cover all the cases?

1. existing Git repo, put .jj folder outside of Git repo (not sure about .git folder for this one)
2. existing Git repo, put .jj folder at top level of Git repo (this is colocate)
3. new jj/Git repo, put .git folder into .jj folder
4. new jj/Git repo, put .git folder at top level of repo (this is colocate)

For an existing repo, you should always be able to use Git commands, but are there two .git folders, so they aren't in sync?

[wmjdgla]

From what I've learnt so far, it seems that having two .git folders is impossible?
For existing Git repo, running jj git init produces the following output:

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.

It we then run jj git init --colocate, it would have the same result as jj git init --git-repo ., which is scenario 2. So it looks like all cases are covered?

[joyously]

I think your example was scenario 2 the entire time because the default is the current directory. Did you try scenario 1? Or 3 with .jj folder external?

[martinvonz]

I think part of the problem is that the generated HTML misses an important part of the description. Here's the help from the CLI:

$ jj git init --help
Create a new Git backed repo

Usage: jj git init [OPTIONS] [DESTINATION]

Arguments:
  [DESTINATION]
          The destination directory where the `jj` repo will be created. If the directory does not exist, it will be created. If no directory is given, the current
          directory is used.

          By default the `git` repo is under `$destination/.jj`

          [default: .]
[...]

The "By default the git repo is under $destination/.jj" is the important bit, I think. Does that clarify?

[martinvonz]

@ilyagr, it looks like the markdown version keeps only the first paragraph in general. Any idea how to fix?

[ilyagr]

There's no easy way that I know of. We'd have to write our own markdown generator or import and extend the one we currently use (https://github.com/ConnorGray/clap-markdown). I don't think that generator is being actively worked on at the moment.

OTOH, writing out own generator is not prohibitive. For example, we could start by iterating over each command (just like clap-markdown) and putting clap's textual output into a code block for each one. It could be made a bit prettier by using some regexes to allow the help preamble to be outside the code block.

Or, if somebody found it fun to use something like https://github.com/sunng87/handlebars-rust and make a nice template to render clap's data structures into markdown, that'd be even better.

[ilyagr]

You could ask a lawyer how to fork clap-markdown and make the fork a Google project. Then, it could conceivably be eventually added to a jj GitHub org once that exists. Conveniently, it's licensed as "your choice of MIT or Apache".

I can also fork it myself, but I'm not sure how much maintenance burden it would be. I'd also want to use other people's open PRs in clap-markdown repo. I'd still eventually want it to become a Google project somehow, so that a community is responsible for it rather than just me.

I'm guessing that, technically, making it print all the paragraphs for argument help would be easy. Of course, it's possible it's harder than I think.

One thing I do have is a name for a fork. If I have my way, it shall be clap-markdown-pear. pear is mostly meant as a nonsense word that's easy to remember, but of course we'll know that the pear is really a jujube.

My other thought was clap-md-phd, but I'm not sure that's a great joke that everyone will get.

[ilyagr]

Also, I should've linked to the relevant bug: ConnorGray/clap-markdown#20.